@jgengine/core 0.14.0 → 0.15.0

package/dist/input/rebindSession.d.ts

@@ -0,0 +1,141 @@
+import { type ActionCodes, type ActionCodesMap } from "./actionBindings.js";
+import { type BindingOverrides } from "./bindingOverrides.js";
+/**
+ * One rebindable action as declared to {@link createRebindSession}. The `id` and
+ * `label` are FREE strings the session never interprets — the game owns their
+ * meaning and display text. `defaultCodes` is the authored binding the session
+ * resets back to.
+ */
+export interface RebindActionConfig {
+    /** Stable action id (also the {@link BindingOverrides} key). Free string. */
+    id: string;
+    /** Human label shown in the controls list ("Move Forward"). Free string. */
+    label: string;
+    /** The game's authored binding for this action; `reset` returns here. */
+    defaultCodes: ActionCodes;
+}
+/** Config for {@link createRebindSession}: an explicit action list, or an {@link ActionCodesMap} + labels. */
+export type RebindSessionConfig = RebindSessionActionsConfig | RebindSessionMapConfig;
+interface RebindSessionCommon {
+    /** Player rebinds to start from (e.g. from {@link loadBindingOverrides}). */
+    overrides?: BindingOverrides;
+    /** Injected clock (ms) used to timestamp each rebind. Default `Date.now`. */
+    now?: () => number;
+}
+/** Declare actions explicitly, in list order. */
+export interface RebindSessionActionsConfig extends RebindSessionCommon {
+    actions: readonly RebindActionConfig[];
+}
+/** Declare actions from an authored {@link ActionCodesMap}, labelled by `labels` (falling back to the id). */
+export interface RebindSessionMapConfig extends RebindSessionCommon {
+    input: ActionCodesMap;
+    labels?: Record<string, string>;
+}
+/** One controls-list row: an action, its effective binding, and any conflicts. */
+export interface RebindRow {
+    /** The action's free-string id. */
+    actionId: string;
+    /** The action's free-string label. */
+    label: string;
+    /** Effective binding (default merged with the current override) — hold/toggle/repeat shape preserved. */
+    codes: ActionCodes;
+    /** Normalized primary code driving this action (`"KeyW"`, `"Space"`), or `null` when unbound. */
+    code: string | null;
+    /** Short display glyph for {@link RebindRow.code} (via `bindingLabel`), or `""` when unbound. */
+    bindingLabel: string;
+    /** True when no override is set — the effective binding is the authored default. */
+    isDefault: boolean;
+    /** Other action ids that share a normalized code with this row (the conflict set). */
+    conflictWith: string[];
+    /** Clock time (ms) this action was last rebound, or `null` if never rebound this session. */
+    changedAt: number | null;
+}
+/** A group of actions bound to the same normalized code — the conflict this session detects. */
+export interface RebindConflict {
+    /** The shared normalized code. */
+    code: string;
+    /** Every action id bound to {@link RebindConflict.code} (always length ≥ 2). */
+    actionIds: string[];
+}
+/** Serializable session state for save/restore. */
+export interface RebindSessionSnapshot {
+    /** The current player rebinds. */
+    overrides: BindingOverrides;
+    /** When each action was last rebound (ms), by action id. */
+    changedAt: Record<string, number>;
+    /** The action currently armed for capture, or `null`. */
+    capturingActionId: string | null;
+}
+/** A live, observable, conflict-aware key-remap editor over the action-binding model. */
+export interface RebindSession {
+    /** The declared actions, in list order. */
+    actions(): readonly RebindActionConfig[];
+    /** One {@link RebindRow} per action, in list order, with effective binding + conflicts. */
+    rows(): RebindRow[];
+    /** The row for a single action, or `null` if the id is unknown. */
+    row(actionId: string): RebindRow | null;
+    /**
+     * Arm capture for an action: the next {@link RebindSession.capture} assigns to
+     * it. A React host shows "Press a key…" for the armed action. No-op for an
+     * unknown id.
+     */
+    beginCapture(actionId: string): void;
+    /** The action currently armed for capture, or `null`. */
+    capturingActionId(): string | null;
+    /** Whether capture is armed (for `actionId` specifically, if given). */
+    isCapturing(actionId?: string): boolean;
+    /**
+     * Feed a raw key/button code (e.g. a `KeyboardEvent.code`) to the armed action:
+     * it is normalized (`normalizeKeyCode`) and recorded as that action's primary
+     * override, preserving the action's hold/toggle/repeat shape, then capture
+     * disarms. Returns whether an assignment happened (false when nothing is armed).
+     */
+    capture(code: string): boolean;
+    /** Disarm capture without changing any binding. */
+    cancelCapture(): void;
+    /** Every conflict group — actions that share a normalized code. Empty when clean. */
+    conflicts(): RebindConflict[];
+    /** Whether any two actions share a normalized code. */
+    hasConflicts(): boolean;
+    /** Reset one action back to its `defaultCodes` (drops its override). */
+    reset(actionId: string): void;
+    /** Reset every action back to defaults (drops all overrides). */
+    resetAll(): void;
+    /** Whether an action has no override (its effective binding is the authored default). */
+    isDefault(actionId: string): boolean;
+    /** The current {@link BindingOverrides} to persist (the caller saves via `saveBindingOverride`). */
+    overrides(): BindingOverrides;
+    /**
+     * Hand the current overrides to a persist callback (e.g. one that calls
+     * `saveBindingOverride` per entry) and return them. With no callback it just
+     * returns the overrides — a convenient "commit" seam.
+     */
+    apply(persistFn?: (overrides: BindingOverrides) => void): BindingOverrides;
+    /** Observe changes (capture, reset, restore, arm/disarm). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): RebindSessionSnapshot;
+    /** Restore from a {@link RebindSessionSnapshot}. */
+    restore(snapshot: RebindSessionSnapshot): void;
+}
+/**
+ * A conflict-aware key-remap session over the action-binding model — the missing
+ * editor behind a controls-settings menu. It takes the game's authored actions
+ * ({@link RebindActionConfig}s, or an {@link ActionCodesMap} + labels) plus the
+ * player's saved {@link BindingOverrides}, and tracks the *effective* binding per
+ * action (default merged with the override via `applyBindingOverrides`). `rows()`
+ * exposes each action's label, current key glyph (via `bindingLabel`), whether it
+ * is still the default, and which other actions it collides with; `conflicts()`
+ * groups every action pair sharing a normalized code (the value-add a raw
+ * override map can't give you). `beginCapture`/`capture`/`cancelCapture` drive a
+ * "press a key" rebind (codes normalized via `normalizeKeyCode`), `reset`/
+ * `resetAll` return to defaults, and `overrides()`/`apply()` hand the caller the
+ * `BindingOverrides` to persist. Nothing here is genre-specific: action ids and
+ * labels are free strings the session never interprets, and hold/toggle/repeat
+ * binding shapes survive a rebind. `snapshot`/`restore` round-trips the editor
+ * (including the in-flight capture) through a save.
+ *
+ * @capability key-rebinding conflict-aware key-remap session over the action-binding model — capture/reassign, conflict detection, reset-to-defaults, persist overrides, snapshot/restore
+ */
+export declare function createRebindSession(config: RebindSessionConfig): RebindSession;
+export {};

package/dist/input/rebindSession.js

@@ -0,0 +1,235 @@
+import { bindingLabel, normalizeKeyCode, } from "./actionBindings.js";
+import { applyBindingOverrides } from "./bindingOverrides.js";
+/** All codes an {@link ActionCodes} entry binds (hold + toggle, or the plain array). */
+function allCodes(codes) {
+    if (Array.isArray(codes))
+        return [...codes];
+    const modes = codes;
+    return [...(modes.hold ?? []), ...(modes.toggle ?? [])];
+}
+/** The first (primary) code of an {@link ActionCodes} entry, or `null` when unbound. */
+function primaryCode(codes) {
+    return allCodes(codes)[0] ?? null;
+}
+/** Replace the primary code of `codes` with `code`, keeping the hold/toggle/repeat shape. */
+function withPrimaryCode(codes, code) {
+    if (Array.isArray(codes)) {
+        return [code, ...codes.slice(1)];
+    }
+    const modes = codes;
+    if (modes.hold !== undefined && modes.hold.length > 0) {
+        return { ...modes, hold: [code, ...modes.hold.slice(1)] };
+    }
+    if (modes.toggle !== undefined && modes.toggle.length > 0) {
+        return { ...modes, toggle: [code, ...modes.toggle.slice(1)] };
+    }
+    return { ...modes, hold: [code] };
+}
+function normalizeConfig(config) {
+    if ("actions" in config)
+        return config.actions.map((a) => ({ ...a }));
+    const labels = config.labels ?? {};
+    return Object.keys(config.input).map((id) => ({
+        id,
+        label: labels[id] ?? id,
+        defaultCodes: config.input[id],
+    }));
+}
+/**
+ * A conflict-aware key-remap session over the action-binding model — the missing
+ * editor behind a controls-settings menu. It takes the game's authored actions
+ * ({@link RebindActionConfig}s, or an {@link ActionCodesMap} + labels) plus the
+ * player's saved {@link BindingOverrides}, and tracks the *effective* binding per
+ * action (default merged with the override via `applyBindingOverrides`). `rows()`
+ * exposes each action's label, current key glyph (via `bindingLabel`), whether it
+ * is still the default, and which other actions it collides with; `conflicts()`
+ * groups every action pair sharing a normalized code (the value-add a raw
+ * override map can't give you). `beginCapture`/`capture`/`cancelCapture` drive a
+ * "press a key" rebind (codes normalized via `normalizeKeyCode`), `reset`/
+ * `resetAll` return to defaults, and `overrides()`/`apply()` hand the caller the
+ * `BindingOverrides` to persist. Nothing here is genre-specific: action ids and
+ * labels are free strings the session never interprets, and hold/toggle/repeat
+ * binding shapes survive a rebind. `snapshot`/`restore` round-trips the editor
+ * (including the in-flight capture) through a save.
+ *
+ * @capability key-rebinding conflict-aware key-remap session over the action-binding model — capture/reassign, conflict detection, reset-to-defaults, persist overrides, snapshot/restore
+ */
+export function createRebindSession(config) {
+    const now = config.now ?? Date.now;
+    const actionList = normalizeConfig(config);
+    const defaultMap = {};
+    for (const action of actionList)
+        defaultMap[action.id] = action.defaultCodes;
+    const knownIds = new Set(actionList.map((a) => a.id));
+    const overrides = {};
+    const changedAt = new Map();
+    let capturingActionId = null;
+    const listeners = new Set();
+    function ingestOverrides(source) {
+        for (const id of Object.keys(source)) {
+            if (knownIds.has(id))
+                overrides[id] = source[id];
+        }
+    }
+    if (config.overrides !== undefined)
+        ingestOverrides(config.overrides);
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    /** Effective codes for an action: override merged over the authored default. */
+    function effectiveMap() {
+        return applyBindingOverrides(defaultMap, overrides);
+    }
+    /** Map of normalized code → action ids currently bound to it. */
+    function codeIndex() {
+        const effective = effectiveMap();
+        const index = new Map();
+        for (const action of actionList) {
+            for (const raw of allCodes(effective[action.id])) {
+                const norm = normalizeKeyCode(raw);
+                const bucket = index.get(norm);
+                if (bucket === undefined)
+                    index.set(norm, [action.id]);
+                else
+                    bucket.push(action.id);
+            }
+        }
+        return index;
+    }
+    function rows() {
+        const effective = effectiveMap();
+        const index = codeIndex();
+        return actionList.map((action) => {
+            const codes = effective[action.id];
+            const primaryRaw = primaryCode(codes);
+            const primary = primaryRaw === null ? null : normalizeKeyCode(primaryRaw);
+            const conflictWith = new Set();
+            for (const raw of allCodes(codes)) {
+                const bound = index.get(normalizeKeyCode(raw));
+                if (bound === undefined)
+                    continue;
+                for (const other of bound)
+                    if (other !== action.id)
+                        conflictWith.add(other);
+            }
+            return {
+                actionId: action.id,
+                label: action.label,
+                codes,
+                code: primary,
+                bindingLabel: primary === null ? "" : bindingLabel(primary),
+                isDefault: overrides[action.id] === undefined,
+                conflictWith: [...conflictWith],
+                changedAt: changedAt.get(action.id) ?? null,
+            };
+        });
+    }
+    return {
+        actions() {
+            return actionList;
+        },
+        rows,
+        row(actionId) {
+            return rows().find((r) => r.actionId === actionId) ?? null;
+        },
+        beginCapture(actionId) {
+            if (!knownIds.has(actionId) || capturingActionId === actionId)
+                return;
+            capturingActionId = actionId;
+            notify();
+        },
+        capturingActionId() {
+            return capturingActionId;
+        },
+        isCapturing(actionId) {
+            if (actionId === undefined)
+                return capturingActionId !== null;
+            return capturingActionId === actionId;
+        },
+        capture(code) {
+            const target = capturingActionId;
+            if (target === null)
+                return false;
+            const normalized = normalizeKeyCode(code);
+            const base = effectiveMap()[target];
+            overrides[target] = withPrimaryCode(base, normalized);
+            changedAt.set(target, now());
+            capturingActionId = null;
+            notify();
+            return true;
+        },
+        cancelCapture() {
+            if (capturingActionId === null)
+                return;
+            capturingActionId = null;
+            notify();
+        },
+        conflicts() {
+            const groups = [];
+            for (const [code, actionIds] of codeIndex()) {
+                if (actionIds.length >= 2)
+                    groups.push({ code, actionIds: [...actionIds] });
+            }
+            return groups;
+        },
+        hasConflicts() {
+            for (const actionIds of codeIndex().values())
+                if (actionIds.length >= 2)
+                    return true;
+            return false;
+        },
+        reset(actionId) {
+            if (overrides[actionId] === undefined)
+                return;
+            delete overrides[actionId];
+            changedAt.delete(actionId);
+            notify();
+        },
+        resetAll() {
+            if (Object.keys(overrides).length === 0 && changedAt.size === 0)
+                return;
+            for (const key of Object.keys(overrides))
+                delete overrides[key];
+            changedAt.clear();
+            notify();
+        },
+        isDefault(actionId) {
+            return overrides[actionId] === undefined;
+        },
+        overrides() {
+            return { ...overrides };
+        },
+        apply(persistFn) {
+            const snapshot = { ...overrides };
+            persistFn?.(snapshot);
+            return snapshot;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return {
+                overrides: { ...overrides },
+                changedAt: Object.fromEntries(changedAt),
+                capturingActionId,
+            };
+        },
+        restore(snapshot) {
+            for (const key of Object.keys(overrides))
+                delete overrides[key];
+            changedAt.clear();
+            ingestOverrides(snapshot.overrides);
+            for (const [id, at] of Object.entries(snapshot.changedAt)) {
+                if (knownIds.has(id))
+                    changedAt.set(id, at);
+            }
+            capturingActionId =
+                snapshot.capturingActionId !== null && knownIds.has(snapshot.capturingActionId)
+                    ? snapshot.capturingActionId
+                    : null;
+            notify();
+        },
+    };
+}

package/dist/input/touchControlsMode.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Runtime switch for the active touch control context (see `TouchControlsConfig.modes`): gameplay
+ * calls `setTouchControlsMode(ctx, "car")` when the player boards a vehicle and `null` on exit, and
+ * the shell re-derives the touch scheme so only that context's controls are on screen. Backed by the
+ * ctx keyed store, so writes notify `ctx.subscribe` (the shell re-renders) and the value rides along
+ * with whole-world saves exactly like the gameplay state that implies it.
+ */
+import type { GameContext } from "../runtime/gameContext.js";
+/**
+ * Activate a named touch control mode, or `null` to return to the base config.
+ *
+ * @capability touch-controls switch the on-screen touch control set when gameplay context changes (enter/exit vehicle, mount, build mode)
+ */
+export declare function setTouchControlsMode(ctx: GameContext, mode: string | null): void;
+/** The active touch control mode, `null` when the base config applies. */
+export declare function activeTouchControlsMode(ctx: GameContext): string | null;

package/dist/input/touchControlsMode.js

@@ -0,0 +1,23 @@
+/**
+ * Runtime switch for the active touch control context (see `TouchControlsConfig.modes`): gameplay
+ * calls `setTouchControlsMode(ctx, "car")` when the player boards a vehicle and `null` on exit, and
+ * the shell re-derives the touch scheme so only that context's controls are on screen. Backed by the
+ * ctx keyed store, so writes notify `ctx.subscribe` (the shell re-renders) and the value rides along
+ * with whole-world saves exactly like the gameplay state that implies it.
+ */
+import { defineStore } from "../store/defineStore.js";
+const touchModeStore = defineStore("engine.touch.mode", null);
+/**
+ * Activate a named touch control mode, or `null` to return to the base config.
+ *
+ * @capability touch-controls switch the on-screen touch control set when gameplay context changes (enter/exit vehicle, mount, build mode)
+ */
+export function setTouchControlsMode(ctx, mode) {
+    if (touchModeStore.read(ctx) === mode)
+        return;
+    touchModeStore.write(ctx, mode);
+}
+/** The active touch control mode, `null` when the base config applies. */
+export function activeTouchControlsMode(ctx) {
+    return touchModeStore.read(ctx);
+}

package/dist/input/touchScheme.d.ts

@@ -62,6 +62,22 @@ export declare const TOUCH_STYLE_OPTIONS: readonly {
 }[];
 /** Skin used when neither the game nor the player picks one. */
 export declare const DEFAULT_TOUCH_STYLE: TouchStyle;
+/**
+ * How the movement joystick behaves — the two shipped variants, player-selectable in
+ * Settings → Controls. `fixed` is the classic always-visible stick in its dock corner;
+ * `floating` keeps the corner as an empty capture zone and spawns the stick centered under
+ * wherever the thumb lands, so the hand never has to find a fixed target mid-play.
+ */
+export type TouchJoystickVariant = "fixed" | "floating";
+/** Every joystick variant id, in menu order. */
+export declare const TOUCH_JOYSTICK_VARIANTS: readonly TouchJoystickVariant[];
+/** Joystick variants as `{ value, label }` rows for the Settings → Controls selector. */
+export declare const TOUCH_JOYSTICK_VARIANT_OPTIONS: readonly {
+    value: TouchJoystickVariant;
+    label: string;
+}[];
+/** Variant used when the player has not picked one. */
+export declare const DEFAULT_TOUCH_JOYSTICK_VARIANT: TouchJoystickVariant;
 /** Where each touch cluster docks; unset falls back to the classic bottom layout. */
 export interface TouchLayoutConfig {
     /** Virtual joystick / movement zone. Default `bottom-left`. */
@@ -95,6 +111,9 @@ export interface TouchButtonSpec {
 export interface TouchMovementConfig {
     axis?: "both" | "horizontal" | "vertical";
 }
+/** One named control context's touch config — the same shape as the base config, minus nested modes. */
+export type TouchControlsModeConfig = Omit<TouchControlsConfig, "modes">;
+/** Game-authored refinement of the derived touch scheme on `defineGame({ touch })` — gestures, curated buttons, hidden actions, cluster layout, skin, and per-context `modes`. */
 export interface TouchControlsConfig {
     /** `false` removes the virtual joystick even when movement actions are bound; an object restricts it to one axis. */
     movement?: false | TouchMovementConfig;
@@ -112,6 +131,14 @@ export interface TouchControlsConfig {
     layout?: TouchLayoutConfig;
     /** Suggested default skin; the player's Settings choice overrides it. Default `glass`. */
     style?: TouchStyle;
+    /**
+     * Per-context control sets for games whose verbs change at runtime — on foot vs driving vs
+     * flying. Each key is a mode name whose fields *replace* the matching base fields while that
+     * mode is active (base config = the default mode). Gameplay switches with
+     * `setTouchControlsMode(ctx, "car")` and back with `null`; only the actions a context actually
+     * uses should be visible in it, so a runner on foot never sees flight or vehicle chrome.
+     */
+    modes?: Record<string, TouchControlsModeConfig>;
 }
 export interface TouchJoystick {
     up: string | null;
@@ -157,9 +184,11 @@ export interface DeriveTouchSchemeOptions {
     reserved: ReadonlySet<string>;
     firstPerson: boolean;
     config?: TouchControlsConfig | false;
+    /** Active control context (see {@link TouchControlsConfig.modes}); null/unknown falls back to the base config. */
+    mode?: string | null;
 }
 /**
  * Null means "render no touch controls" — either the game opted out or there
  * is nothing to synthesize.
  */
-export declare function deriveTouchScheme(input: ActionCodesMap | undefined, { reserved, firstPerson, config }: DeriveTouchSchemeOptions): TouchScheme | null;
+export declare function deriveTouchScheme(input: ActionCodesMap | undefined, { reserved, firstPerson, config: rawConfig, mode }: DeriveTouchSchemeOptions): TouchScheme | null;

package/dist/input/touchScheme.js

@@ -44,6 +44,15 @@ export const TOUCH_STYLE_OPTIONS = [
 ];
 /** Skin used when neither the game nor the player picks one. */
 export const DEFAULT_TOUCH_STYLE = "glass";
+/** Every joystick variant id, in menu order. */
+export const TOUCH_JOYSTICK_VARIANTS = ["fixed", "floating"];
+/** Joystick variants as `{ value, label }` rows for the Settings → Controls selector. */
+export const TOUCH_JOYSTICK_VARIANT_OPTIONS = [
+    { value: "floating", label: "Floating (under your thumb)" },
+    { value: "fixed", label: "Fixed" },
+];
+/** Variant used when the player has not picked one. */
+export const DEFAULT_TOUCH_JOYSTICK_VARIANT = "floating";
 const DEFAULT_LOOK_SENSITIVITY = 0.005;
 const DEFAULT_TOUCH_LAYOUT = {
     movement: "bottom-left",
@@ -175,11 +184,27 @@ function gestureActions(gestures) {
     }
     return used;
 }
+/** Resolve the effective config for a mode: mode fields replace base fields; the base is the default mode. */
+function resolveModeConfig(config, mode) {
+    if (config === false || config === undefined || mode === null || mode === undefined)
+        return config;
+    const active = config.modes?.[mode];
+    if (active === undefined)
+        return config;
+    const { modes: _modes, ...base } = config;
+    return { ...base, ...active };
+}
+/**
+ * Auto-derived button count past which the dock stops being playable — two full thumb arcs. A
+ * curated `touch.buttons` list may exceed it deliberately; blind derivation may not.
+ */
+const DERIVED_BUTTON_BUDGET = 8;
 /**
  * Null means "render no touch controls" — either the game opted out or there
  * is nothing to synthesize.
  */
-export function deriveTouchScheme(input, { reserved, firstPerson, config }) {
+export function deriveTouchScheme(input, { reserved, firstPerson, config: rawConfig, mode }) {
+    const config = resolveModeConfig(rawConfig, mode);
     if (config === false)
         return null;
     const actions = Object.keys(input ?? {});
@@ -246,6 +271,11 @@ export function deriveTouchScheme(input, { reserved, firstPerson, config }) {
             anchor: null,
             image: null,
         }));
+        if (buttons.length > DERIVED_BUTTON_BUDGET) {
+            console.warn(`[jgengine:touch] derived ${buttons.length} on-screen buttons (${buttons
+                .map((button) => button.action)
+                .join(", ")}) — more than a thumb can reach. Curate touch.buttons, hide actions with touch.hidden, or split contexts with touch.modes.`);
+        }
     }
     const look = config?.look ?? firstPerson;
     if (joystick === null && buttons.length === 0 && gestures === null && !look)

package/dist/interaction/promptRegistry.d.ts

@@ -0,0 +1,78 @@
+import { type PositionedPrompt, type PromptPoint } from "./proximityPrompt.js";
+/**
+ * A partial edit applied to an already-registered {@link PositionedPrompt} by
+ * {@link PromptRegistry.update}. Any subset of the mutable fields — everything
+ * but the stable `id` — may be supplied; omitted fields keep their prior value.
+ */
+export type PositionedPromptPatch = Partial<Omit<PositionedPrompt, "id">>;
+/**
+ * The serializable shape {@link PromptRegistry.snapshot} returns and
+ * {@link PromptRegistry.restore} consumes: the full set of positioned prompts
+ * (in registration order) plus the id of the prompt that was active when the
+ * snapshot was taken. Prompt display/command payloads are free strings and ids —
+ * keep them serializable and this round-trips through a save cleanly.
+ */
+export interface PromptRegistrySnapshot {
+    /** Every registered prompt, in registration order (tie-break order for resolve). */
+    prompts: readonly PositionedPrompt[];
+    /** Id of the active prompt at snapshot time, or `null` if none was active. */
+    activeId: string | null;
+}
+/**
+ * A live, observable set of interaction prompts that OWNS the registered
+ * {@link PositionedPrompt}s and tracks which one is active for a player. It is a
+ * thin stateful layer over {@link resolveActivePrompt}: registration/order lives
+ * here, the nearest-within-radius / higher-priority selection stays in the pure
+ * resolver. {@link resolve} is the per-frame hot path — call it as the player
+ * moves; subscribers fire only when the active prompt actually CHANGES.
+ */
+export interface PromptRegistry {
+    /**
+     * Add (or replace, by id) a positioned prompt. Replacing an existing id keeps
+     * its registration slot so tie-break order is stable. Does not re-resolve on
+     * its own — the next {@link resolve} picks up the change.
+     */
+    register(prompt: PositionedPrompt): void;
+    /**
+     * Patch a registered prompt in place. No-op if `id` is unknown. Only the fields
+     * present in `patch` change; the rest are preserved.
+     */
+    update(id: string, patch: PositionedPromptPatch): void;
+    /** Remove the prompt with this id, if present. Returns whether one was removed. */
+    unregister(id: string): boolean;
+    /** Remove every prompt and clear the active selection. */
+    clear(): void;
+    /** All registered prompts in registration order (do not mutate the returned array). */
+    all(): readonly PositionedPrompt[];
+    /**
+     * Resolve the active prompt for a player at `playerPosition` by delegating to
+     * {@link resolveActivePrompt}, cache its id, and notify subscribers only when
+     * the active prompt changed since the last call — so a HUD bound to this
+     * registry re-renders on transitions, not every frame. Returns the active
+     * prompt or `null`.
+     */
+    resolve(playerPosition: PromptPoint): PositionedPrompt | null;
+    /** The prompt selected by the most recent {@link resolve}, or `null`. */
+    active(): PositionedPrompt | null;
+    /** Observe active-prompt changes (resolve transitions, clear, restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): PromptRegistrySnapshot;
+    /** Restore prompts + active id from a {@link PromptRegistrySnapshot}. */
+    restore(snapshot: PromptRegistrySnapshot): void;
+}
+/**
+ * Create a live, observable interaction-prompt registry over the pure
+ * {@link resolveActivePrompt} resolver. Register positioned "press E" prompts,
+ * `resolve(playerPosition)` each frame as the hero moves, and read `active()` —
+ * the nearest strictly-in-range prompt (higher `priority` beats closer). The set
+ * is owned here (register/update/unregister/clear/all); selection stays pure.
+ * Subscribers are notified only when the active prompt *changes*, so a HUD does
+ * not thrash per frame, and `snapshot`/`restore` round-trip the prompts plus the
+ * active id through a save (display payloads are free strings/ids the game owns —
+ * the registry never branches on their meaning). Allocation-aware: `all()` and
+ * `resolve()` reuse a cached array instead of rebuilding per call.
+ *
+ * @capability interaction-prompt observable nearest-interactable prompt registry over the proximity-prompt resolver — register/resolve/active with priority+range and change-notified snapshot/restore
+ */
+export declare function createPromptRegistry(): PromptRegistry;