@jgengine/core 0.10.0 → 0.11.0

package/dist/gameplay.js

@@ -0,0 +1,91 @@
+export { Behaviour, BehaviourModule, createBehaviourWorld } from "./behaviour/behaviour.js";
+export {} from "./board/laneBoard.js";
+export { createCardPile, createCardPileState, draw, moveCards, peek, pileRng, shuffleWithRng, } from "./cards/cardPile.js";
+export { runPipeline } from "./cards/modifierPipeline.js";
+export {} from "./crafting/crop.js";
+export { advanceTransport, createProductionState, drainOutput, feedProduction, productionBuilding, resolvePowerGrid, tickProduction, } from "./crafting/production.js";
+export { canCraft, craft, craftSeconds, createRecipeGraph, stationSatisfied, } from "./crafting/recipe.js";
+export { createListingBook } from "./economy/listingBook.js";
+export { addScheduledRule, advanceLedger, annotate, balanceOf, cancelRule, capAmount, createResourceLedger, curveScale, pauseRule, redirect, rejectWhen, resumeRule, taxFraction, thresholdScale, } from "./economy/resourceLedger.js";
+export {} from "./economy/techTree.js";
+export { balance, charge, chargeAll, createEmptyWallet, grant, isOverdrawn } from "./economy/wallet.js";
+export { DEFAULT_CHAT_BODY_LENGTH, DEFAULT_CHAT_HISTORY_LIMIT, DEFAULT_CHAT_RATE_LIMIT, createChatRateLimiter, } from "./game/chat.js";
+export { playControlsActive } from "./game/controlGate.js";
+export { createCosmetics } from "./game/cosmetics.js";
+export { defineGame, } from "./game/defineGame.js";
+export { defineSystem } from "./game/defineSystem.js";
+export { createGameDialogue, dialogueSlot } from "./game/dialogue.js";
+export { createGameEvents, } from "./game/events.js";
+export { appendFeed, createGameFeed, pruneFeed, } from "./game/feed.js";
+export { gamePhase, setGamePhase } from "./game/gamePhase.js";
+export { createKeyValueStore } from "./game/keyValueStore.js";
+export { createLeaderboard } from "./game/leaderboard.js";
+export { createLevelSequence } from "./game/levelSequence.js";
+export { createLoadouts } from "./game/loadout.js";
+export { evaluateLootFilter, lootFilter } from "./game/lootFilter.js";
+export { createLootPipeline, defineLootPipeline, } from "./game/lootPipeline.js";
+export { createLootRegistry, lootTable } from "./game/lootTable.js";
+export { resolveOneShotClip } from "./game/modelAnimation.js";
+export { evaluateObjective } from "./game/objectives.js";
+export { createLayerRegistry, diffParams, orderLayers, resolveParams, resolveSelection, validateLayers, } from "./game/paramLayers.js";
+export { DEFAULT_PING_CATEGORIES, PING_FEED_ACTION, createPingSystem, } from "./game/ping.js";
+export { CAMERA_FRUSTUM_DEFAULTS, worldHealthBarAllowsRole, } from "./game/playableGame.js";
+export { curve, evalCurve, leveling, } from "./game/progression.js";
+export { createQuestJournal } from "./game/quest.js";
+export { RaceState, createLapTimer, createRaceState, finishRaceSession, firstPastPost, idleRaceSession, lapDurations, parDelta, placementOf, raceOutcomeOf, racePlacements, raceTrack, splitSegments, startRaceCountdown, tickRaceSession, } from "./game/race.js";
+export { createRecordBook } from "./game/recordBook.js";
+export { createRuleRegistry, rerollRules, selectRules, } from "./game/ruleSelection.js";
+export { createRunDraft } from "./game/runDraft.js";
+export { createSaveStore, localSaveBackend, memorySaveBackend, remoteSaveBackend, } from "./game/saveStore.js";
+export { createSocial, } from "./game/social.js";
+export { createSpawnPoints } from "./game/spawnPoints.js";
+export { composeGameLoop } from "./game/systemRuntime.js";
+export { DEFAULT_FIXED_STAGES, DEFAULT_FRAME_STAGES, compileSystemSchedule, } from "./game/systemSchedule.js";
+export { createTalentTree } from "./game/talents.js";
+export { appendToast, createToastQueue, pruneToasts } from "./game/toasts.js";
+export { createUnlockCatalog, createUnlocks } from "./game/unlocks.js";
+export { createVfxInstanceStore, } from "./game/vfxInstance.js";
+export { DEFAULT_PICKUP_RADIUS, WORLD_ITEM_ENTITY_NAME, } from "./game/worldItem.js";
+export {} from "./input/actionBindings.js";
+export { NEUTRAL_AXIS } from "./input/axisInput.js";
+export { applyBindingOverrides, clearBindingOverride, loadBindingOverrides, saveBindingOverride, } from "./input/bindingOverrides.js";
+export { createGestureSurfaceTracker } from "./input/gestureSurface.js";
+export { aimToPoint } from "./input/pointer.js";
+export { normalizePointerToAxis } from "./input/pointerAxis.js";
+export { createTouchGestureTracker } from "./input/touchGestures.js";
+export { DEFAULT_TOUCH_STYLE, TOUCH_STYLES, TOUCH_STYLE_OPTIONS, deriveTouchScheme, touchButtonShape, touchCode, withTouchCodes, } from "./input/touchScheme.js";
+export {} from "./inventory/inventoryModel.js";
+export {} from "./inventory/shapedGrid.js";
+export {} from "./inventory/slotModel.js";
+export { createDeliveryQueue, insureLost, partitionOnDeath, resolveConsolation, } from "./inventory/storageTier.js";
+export { createAffixRoller, seededRng } from "./item/affix.js";
+export { applyWear, createDurability, createDurabilityTracker, durabilityFraction, isDisabled, repairQuote, wear, } from "./item/durability.js";
+export { activeSetBonuses, applySetBonuses, candidateViolatesForbid, captureProvenance, countSetMembers, identityOf, isIdentityValid, matchesQuery, validateIdentity, } from "./item/itemIdentity.js";
+export { createItemInstanceRegistry, proceduralLootEntry } from "./item/itemInstanceRegistry.js";
+export { generate, } from "./item/itemgen.js";
+export { computeEffectiveStats, createModularItem, install, isComplete, missingRequiredSlots, partInSlot, slotAccepts, uninstall, } from "./item/modularItem.js";
+export { createItemUse } from "./item/use.js";
+export { createUseBehaviorRegistry, } from "./item/useBehavior.js";
+export { createWeaponStats } from "./item/weapon.js";
+export { createStatGraph, statModifierContributions, } from "./progression/statGraph.js";
+export {} from "./puzzle/cellGrid.js";
+export {} from "./puzzle/fallingPiece.js";
+export { createNameGenerator } from "./random/nameGen.js";
+export { pickUniform, pickWeighted } from "./random/pick.js";
+export { seededStreams } from "./random/rng.js";
+export { addValue, clampValue, createPairKeyCodec, driftValue, getValue, setValue, towardValue, } from "./relation/keyedValues.js";
+export { crossThresholds, tierAt, } from "./relation/thresholds.js";
+export { evaluatePredicate, readPath, } from "./rules/predicate.js";
+export { getRuleEffect, listRuleEffects, registerRuleEffect } from "./rules/ruleEffects.js";
+export { createTriggeredRuleEngine, } from "./rules/triggeredRules.js";
+export { createRing, ringSampleAt } from "./session/ring.js";
+export {} from "./session/roles.js";
+export {} from "./session/roundState.js";
+export { createDecayMeterSet, decayMeterMoodles, decayMeterSnapshot, decayMeterState, decayMeters, initDecayMeters, refillMeter, } from "./survival/decayMeter.js";
+export { createMoodleStack, stackMoodles } from "./survival/moodle.js";
+export { createMultiRegionHealth } from "./survival/regionHealth.js";
+export { createCommitController } from "./turn/commit.js";
+export { createIntentBoard } from "./turn/intent.js";
+export { createTurnLoop } from "./turn/turnLoop.js";
+export { activeJobs, cancelJob, createWorkQueue, enqueue, fifoOrdering, jobById, jobProgress, pauseJob, priorityOrdering, queueSize, queuedJobs, resumeJob, tick, } from "./work/jobQueue.js";
+export { unitTrainingConfig, } from "./work/unitTraining.js";

package/dist/index.d.ts

@@ -1,14 +1,5 @@
-export * from "./runtime/save.js";
-export * from "./runtime/snapshot.js";
-export * from "./runtime/worldSnapshot.js";
-export * from "./runtime/worldReplication.js";
-export * from "./game/connectedPlayers.js";
-export * from "./runtime/hostedGameRunner.js";
-export * from "./runtime/hostedWorldSession.js";
-export * from "./runtime/worldMirror.js";
-export * from "./runtime/worldChannel.js";
-export * from "./runtime/commandRunner.js";
-export * from "./runtime/gameRuntime.js";
-export * from "./runtime/adapter.js";
-export * from "./runtime/transport.js";
-export * from "./runtime/visibility.js";
+/**
+ * Package root — deep-path imports only for engine APIs (`@jgengine/core/<domain>/<file>`).
+ * Re-exports {@link VERSION} / {@link CHANGELOG} so `import { VERSION } from "@jgengine/core"` works.
+ */
+export { VERSION, CHANGELOG, type ChangelogEntry } from "./meta/changelog.js";

package/dist/index.js

@@ -1,14 +1,5 @@
-export * from "./runtime/save.js";
-export * from "./runtime/snapshot.js";
-export * from "./runtime/worldSnapshot.js";
-export * from "./runtime/worldReplication.js";
-export * from "./game/connectedPlayers.js";
-export * from "./runtime/hostedGameRunner.js";
-export * from "./runtime/hostedWorldSession.js";
-export * from "./runtime/worldMirror.js";
-export * from "./runtime/worldChannel.js";
-export * from "./runtime/commandRunner.js";
-export * from "./runtime/gameRuntime.js";
-export * from "./runtime/adapter.js";
-export * from "./runtime/transport.js";
-export * from "./runtime/visibility.js";
+/**
+ * Package root — deep-path imports only for engine APIs (`@jgengine/core/<domain>/<file>`).
+ * Re-exports {@link VERSION} / {@link CHANGELOG} so `import { VERSION } from "@jgengine/core"` works.
+ */
+export { VERSION, CHANGELOG } from "./meta/changelog.js";

package/dist/input/actionBindings.d.ts

@@ -10,13 +10,17 @@ export interface ActionBinding<TCode extends string = string> {
     secondary: TCode | null;
 }
 export type ActionBindingMap<TAction extends string, TCode extends string = string> = Record<TAction, ActionBinding<TCode>>;
+/** @internal */
 export declare function bindingMatches<TCode extends string>(code: TCode, binding: ActionBinding<TCode>): boolean;
-/** First action (in the map's key order) bound to the given control code, or null. */
+/** First action (in the map's key order) bound to the given control code, or null.
+ * @internal
+ */
 export declare function resolveBoundAction<TAction extends string, TCode extends string>(code: TCode, bindings: ActionBindingMap<TAction, TCode>): TAction | null;
 /**
  * Collapse left/right modifier variants of a KeyboardEvent.code so bindings
  * store one logical key.
- */
+  * @internal
+  */
 export declare function normalizeKeyCode(code: string): string;
 export interface ActionBindingModes<TCode extends string = string> {
     hold?: ActionBinding<TCode>[];
@@ -31,6 +35,7 @@ export type ActionCodes<TCode extends string = string> = readonly TCode[] | {
 };
 /** Maps each game action name to the input codes (hold/toggle keys, repeat rate) that trigger it. */
 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;
 export interface ShouldDispatchActionInput {
     pressed: boolean;
@@ -39,24 +44,35 @@ export interface ShouldDispatchActionInput {
     lastFiredAt: number | null;
     now: number;
 }
+/** @internal */
 export declare function shouldDispatchAction({ pressed, down, repeatMs, lastFiredAt, now }: ShouldDispatchActionInput): boolean;
+/** @internal */
 export declare function toActionStateBindingMap<TAction extends string, TCode extends string>(map: ActionCodesMap<TAction, TCode>): ActionStateBindingMap<TAction, TCode>;
+/** @internal */
 export declare function hotbarSlotBindings(count: number, options?: {
     action?: (slot: number) => string;
 }): ActionCodesMap;
-/** 0-based slot index for a hotbar-slot action name (`slot1`, `hotbarSlot1`), or null. */
+/** 0-based slot index for a hotbar-slot action name (`slot1`, `hotbarSlot1`), or null.
+ * @internal
+ */
 export declare function hotbarSlotActionIndex(action: string): number | null;
+/** @internal */
 export declare function isHotbarSlotAction(action: string): boolean;
 /**
  * Convention mapping a bound input action to the command it fires: the action's
  * own name when a command by that name exists, otherwise a `ui.<action>`
  * fallback. Reserved actions (consumed natively by the shell) and hotbar slots
  * yield null so the shell can handle them itself.
- */
+  * @internal
+  */
 export declare function resolveActionCommand(action: string, has: (command: string) => boolean, reserved: ReadonlySet<string>): string | null;
-/** Short display label for a raw key/button code (e.g. `"KeyW"` → `"W"`). */
+/** Short display label for a raw key/button code (e.g. `"KeyW"` → `"W"`).
+ * @internal
+ */
 export declare function bindingLabel(code: string): string;
-/** Short display label for an action's first bound code, or null when unbound. */
+/** Short display label for an action's first bound code, or null when unbound.
+ * @internal
+ */
 export declare function actionLabel(map: ActionCodesMap, action: string): string | null;
 export interface ActionStateTracker<TAction extends string> {
     handleDown(code: string): TAction | null;
@@ -66,4 +82,5 @@ export interface ActionStateTracker<TAction extends string> {
     endFrame(): void;
     reset(): void;
 }
+/** @internal */
 export declare function createActionStateTracker<TAction extends string, TCode extends string = string>(map: ActionStateBindingMap<TAction, TCode>): ActionStateTracker<TAction>;

package/dist/input/actionBindings.js

@@ -5,10 +5,13 @@
  * the same model serves keyboard codes, mouse buttons, touch controls, or
  * gamepad inputs.
  */
+/** @internal */
 export function bindingMatches(code, binding) {
     return code === binding.primary || code === binding.secondary;
 }
-/** First action (in the map's key order) bound to the given control code, or null. */
+/** First action (in the map's key order) bound to the given control code, or null.
+ * @internal
+ */
 export function resolveBoundAction(code, bindings) {
     for (const action of Object.keys(bindings)) {
         if (bindingMatches(code, bindings[action]))
@@ -19,7 +22,8 @@ export function resolveBoundAction(code, bindings) {
 /**
  * Collapse left/right modifier variants of a KeyboardEvent.code so bindings
  * store one logical key.
- */
+  * @internal
+  */
 export function normalizeKeyCode(code) {
     if (code === "ShiftLeft" || code === "ShiftRight")
         return "Shift";
@@ -27,11 +31,13 @@ export function normalizeKeyCode(code) {
         return "Control";
     return code;
 }
+/** @internal */
 export function actionRepeatMs(codes) {
     if (codes === undefined || Array.isArray(codes))
         return undefined;
     return codes.repeatMs;
 }
+/** @internal */
 export function shouldDispatchAction({ pressed, down, repeatMs, lastFiredAt, now }) {
     if (pressed)
         return true;
@@ -44,6 +50,7 @@ export function shouldDispatchAction({ pressed, down, repeatMs, lastFiredAt, now
 function toBindings(codes) {
     return codes.map((code) => ({ primary: code, secondary: null }));
 }
+/** @internal */
 export function toActionStateBindingMap(map) {
     const result = {};
     for (const action of Object.keys(map)) {
@@ -70,6 +77,7 @@ const HOTBAR_DIGIT_CODES = [
     "Digit9",
     "Digit0",
 ];
+/** @internal */
 export function hotbarSlotBindings(count, options) {
     if (!Number.isInteger(count) || count < 1 || count > HOTBAR_DIGIT_CODES.length) {
         throw new Error(`hotbarSlotBindings: count must be an integer in [1, ${HOTBAR_DIGIT_CODES.length}]`);
@@ -82,11 +90,14 @@ export function hotbarSlotBindings(count, options) {
     return map;
 }
 const HOTBAR_SLOT_ACTION = /^(?:hotbar)?slot(\d+)$/i;
-/** 0-based slot index for a hotbar-slot action name (`slot1`, `hotbarSlot1`), or null. */
+/** 0-based slot index for a hotbar-slot action name (`slot1`, `hotbarSlot1`), or null.
+ * @internal
+ */
 export function hotbarSlotActionIndex(action) {
     const match = HOTBAR_SLOT_ACTION.exec(action);
     return match === null ? null : Number(match[1]) - 1;
 }
+/** @internal */
 export function isHotbarSlotAction(action) {
     return HOTBAR_SLOT_ACTION.test(action);
 }
@@ -95,7 +106,8 @@ export function isHotbarSlotAction(action) {
  * own name when a command by that name exists, otherwise a `ui.<action>`
  * fallback. Reserved actions (consumed natively by the shell) and hotbar slots
  * yield null so the shell can handle them itself.
- */
+  * @internal
+  */
 export function resolveActionCommand(action, has, reserved) {
     if (reserved.has(action) || isHotbarSlotAction(action))
         return null;
@@ -127,7 +139,9 @@ const CODE_LABELS = {
     ArrowLeft: "←",
     ArrowRight: "→",
 };
-/** Short display label for a raw key/button code (e.g. `"KeyW"` → `"W"`). */
+/** Short display label for a raw key/button code (e.g. `"KeyW"` → `"W"`).
+ * @internal
+ */
 export function bindingLabel(code) {
     const direct = CODE_LABELS[code];
     if (direct !== undefined)
@@ -138,7 +152,9 @@ export function bindingLabel(code) {
         return code.slice(5);
     return code.length === 1 ? code.toUpperCase() : code;
 }
-/** Short display label for an action's first bound code, or null when unbound. */
+/** Short display label for an action's first bound code, or null when unbound.
+ * @internal
+ */
 export function actionLabel(map, action) {
     const codes = map[action];
     if (codes === undefined)
@@ -159,6 +175,7 @@ function resolveActionBindingModes(config) {
         return { hold: config, toggle: [] };
     return { hold: config.hold ?? [], toggle: config.toggle ?? [] };
 }
+/** @internal */
 export function createActionStateTracker(map) {
     const actions = Object.keys(map);
     const modesByAction = new Map(actions.map((action) => [action, resolveActionBindingModes(map[action])]));

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 {