@simpludify/core 0.1.5 → 0.1.6

package/dist/interaction/action-bindings.d.ts

@@ -1,11 +1,16 @@
 import type { ActionKind, ActionSet, ActionToken } from "./action-types.js";
+import { type GamepadBinding } from "./gamepad-bindings.js";
 import { KeyCode } from "./key-code.js";
+import { type MouseButton } from "./physical-input.js";
 export interface ButtonBinding {
     readonly keys?: readonly KeyCode[];
+    readonly mouse?: readonly MouseButton[];
 }
 export interface Axis1DBinding {
     readonly negative?: readonly KeyCode[];
     readonly positive?: readonly KeyCode[];
+    readonly mouseNegative?: readonly MouseButton[];
+    readonly mousePositive?: readonly MouseButton[];
 }
 export interface Axis2DBinding {
     readonly x?: Axis1DBinding;
@@ -14,16 +19,27 @@ export interface Axis2DBinding {
 export interface Axis3DBinding extends Axis2DBinding {
     readonly z?: Axis1DBinding;
 }
-export type ActionBinding<K extends ActionKind> = K extends "button" ? ButtonBinding : K extends "axis1d" ? Axis1DBinding : K extends "axis2d" ? Axis2DBinding : Axis3DBinding;
+export type ActionBinding<K extends ActionKind> = (K extends "button" ? ButtonBinding : K extends "axis1d" ? Axis1DBinding : K extends "axis2d" ? Axis2DBinding : Axis3DBinding) & {
+    readonly gamepad?: GamepadBinding<K>;
+};
 export type ActionBindings<A extends ActionSet> = {
     readonly [N in keyof A]?: ActionBinding<A[N]["kind"]>;
 };
-type Binding = ButtonBinding | Axis1DBinding | Axis2DBinding | Axis3DBinding;
+type Binding = ActionBinding<ActionKind>;
 export declare function checkedBinding(action: ActionToken, value: unknown): Binding;
 export declare function keyLists(binding: Binding, path?: string): Array<{
     path: string;
     keys: readonly KeyCode[];
 }>;
+export declare function mouseLists(binding: Binding, path?: string): Array<{
+    path: string;
+    buttons: readonly MouseButton[];
+}>;
+export declare function gamepadControls(binding: GamepadBinding<ActionKind>, path?: string): Array<{
+    kind: "button" | "axis";
+    index: number;
+    path: string;
+}>;
 export declare function editBinding(current: Binding, patch: Binding, remove: boolean): Binding;
 /** Physical keyboard presets for any user-defined Axis2D Action. */
 export declare const KeyboardBindings: Readonly<{

package/dist/interaction/actions.d.ts

@@ -10,11 +10,34 @@ import { type Scene } from "../scene/scene.js";
 import type { ActionInputPort, InputSystem } from "./input.js";
 import { OwnedInputSource } from "./input-source.js";
 import type { KeyCode } from "./key-code.js";
+import type { MouseButton } from "./physical-input.js";
 type Token<A extends ActionSet> = A[keyof A];
 type ButtonToken<A extends ActionSet> = Extract<Token<A>, {
     kind: "button";
 }>;
 type Value = boolean | number | Axis2DValue | Axis3DValue;
+type BindingUse<A extends ActionSet> = {
+    readonly action: Token<A>;
+    readonly path: string;
+};
+export interface KeyboardBindingConflict<A extends ActionSet> {
+    readonly key: KeyCode;
+    readonly bindings: readonly BindingUse<A>[];
+}
+export interface MouseBindingConflict<A extends ActionSet> {
+    readonly device: "mouse";
+    readonly button: MouseButton;
+    readonly bindings: readonly BindingUse<A>[];
+}
+export interface GamepadBindingConflict<A extends ActionSet> {
+    readonly device: "gamepad";
+    readonly kind: "button" | "axis";
+    readonly index: number;
+    readonly bindings: readonly BindingUse<A>[];
+}
+export type BindingConflict<A extends ActionSet> = (KeyboardBindingConflict<A> & {
+    readonly device: "keyboard";
+}) | MouseBindingConflict<A> | GamepadBindingConflict<A>;
 export interface ButtonState {
     readonly held: boolean;
     readonly pressed: boolean;
@@ -44,6 +67,9 @@ export declare class ActionController<A extends ActionSet> implements LifetimeOw
     private readonly bus;
     private keyboardAllowed;
     private readonly blockedKeys;
+    private mouseAllowed;
+    private readonly blockedMouse;
+    private bindingGeneration;
     private pending;
     private transitions;
     constructor(actions: A, options: {
@@ -51,12 +77,17 @@ export declare class ActionController<A extends ActionSet> implements LifetimeOw
         input: InputSystem;
         bindings?: ActionBindings<A>;
         keyboard?: boolean;
+        mouse?: boolean;
     });
     get disposed(): boolean;
     get active(): boolean;
     get keyboardEnabled(): boolean;
     set keyboardEnabled(value: boolean);
     get sourceCount(): number;
+    get mouseEnabled(): boolean;
+    set mouseEnabled(value: boolean);
+    /** @internal Used by existing host adapters to follow common binding settings. */
+    get bindingRevision(): number;
     onDispose(callback: () => void): () => void;
     private entry;
     value<T extends Token<A>>(action: T): ActionValue<T["kind"]>;
@@ -70,28 +101,29 @@ export declare class ActionController<A extends ActionSet> implements LifetimeOw
     snapshot(): ActionSnapshot<A>;
     onPressed(action: ButtonToken<A>, handler: () => void): () => void;
     createSource(owner?: LifetimeOwner): ActionSource<A>;
-    /** @internal */ write(source: ActionSource<A>, action: ActionToken, value: Value): void;
+    /** @internal */ write(source: ActionSource<A>, action: ActionToken, value: Value, edges?: boolean): void;
     /** @internal */ clearSource(source: ActionSource<A>, remove: boolean): void;
     private keyboard;
     private recompute;
     /** @internal */ keyChanged(): void;
     /** @internal */ accepts(code: KeyCode): boolean;
+    /** @internal */ acceptsMouse(button: MouseButton): boolean;
     /** @internal */ capture(override?: ActionFrame): void;
     /** @internal */ dispatch(): void;
     /** Clears held contributions and unconsumed edges; no synthetic button release. */
     reset(): void;
+    /** @internal Flush device transitions without destroying explicit program values. */
+    resetPhysical(): void;
     getBinding<T extends Token<A>>(action: T): ActionBinding<T["kind"]>;
     rebind<T extends Token<A>>(action: T, binding: NoInfer<ActionBinding<T["kind"]>>): void;
     addBindings<T extends Token<A>>(action: T, binding: NoInfer<ActionBinding<T["kind"]>>): void;
     removeBindings<T extends Token<A>>(action: T, binding: NoInfer<ActionBinding<T["kind"]>>): void;
     resetBindings(action?: Token<A>): void;
-    conflicts(): ReadonlyArray<{
-        readonly key: KeyCode;
-        readonly bindings: ReadonlyArray<{
-            readonly action: Token<A>;
-            readonly path: string;
-        }>;
-    }>;
+    conflicts(): readonly KeyboardBindingConflict<A>[];
+    conflicts(device: "keyboard"): readonly KeyboardBindingConflict<A>[];
+    conflicts(device: "mouse"): readonly MouseBindingConflict<A>[];
+    conflicts(device: "gamepad"): readonly GamepadBindingConflict<A>[];
+    conflicts(device: "all"): readonly BindingConflict<A>[];
     exportBindings(): {
         version: 1;
         bindings: ActionBindings<A>;
@@ -110,5 +142,7 @@ export declare class ActionSource<A extends ActionSet> extends OwnedInputSource
     private readonly controller;
     /** @internal */ constructor(controller: ActionController<A>);
     set<T extends Token<A>>(action: T, value: NoInfer<ActionInputValue<T["kind"]>>): void;
+    /** @internal Reset one device binding without synthesizing logical edges. */
+    resetBinding(action: Token<A>): void;
     protected release(remove: boolean): void;
 }

package/dist/interaction/gamepad-bindings.d.ts

@@ -0,0 +1,100 @@
+import type { ActionKind, ActionSet, ActionToken } from "./action-types.js";
+/** Standard mapping physical positions, not product-specific printed labels. */
+export declare const GamepadButton: Readonly<{
+    South: 0;
+    East: 1;
+    West: 2;
+    North: 3;
+    LeftShoulder: 4;
+    RightShoulder: 5;
+    LeftTrigger: 6;
+    RightTrigger: 7;
+    Select: 8;
+    Start: 9;
+    LeftStick: 10;
+    RightStick: 11;
+    DPadUp: 12;
+    DPadDown: 13;
+    DPadLeft: 14;
+    DPadRight: 15;
+    Home: 16;
+}>;
+export type GamepadButton = (typeof GamepadButton)[keyof typeof GamepadButton];
+export declare const GamepadAxis: Readonly<{
+    LeftX: 0;
+    LeftY: 1;
+    RightX: 2;
+    RightY: 3;
+}>;
+export type GamepadAxis = (typeof GamepadAxis)[keyof typeof GamepadAxis];
+export interface GamepadButtonBinding {
+    readonly buttons?: readonly (number | {
+        readonly button: number;
+        readonly threshold?: number;
+    })[];
+}
+export interface GamepadAxisBinding {
+    readonly axis?: number;
+    readonly invert?: boolean;
+    readonly negative?: readonly number[];
+    readonly positive?: readonly number[];
+    readonly deadZone?: number;
+}
+export interface GamepadVectorBinding {
+    readonly x?: GamepadAxisBinding;
+    readonly y?: GamepadAxisBinding;
+}
+export interface GamepadVector3Binding extends GamepadVectorBinding {
+    readonly z?: GamepadAxisBinding;
+}
+export type GamepadBinding<K extends ActionKind> = K extends "button" ? GamepadButtonBinding : K extends "axis1d" ? GamepadAxisBinding : K extends "axis2d" ? GamepadVectorBinding : GamepadVector3Binding;
+export type GamepadBindings<A extends ActionSet> = {
+    readonly [N in keyof A]?: GamepadBinding<A[N]["kind"]>;
+};
+/** Ready-to-use data; game Actions retain application-defined names. */
+export declare const GamepadBindings: Readonly<{
+    LeftStick: Readonly<{
+        x: Readonly<{
+            axis: number;
+        }>;
+        y: Readonly<{
+            axis: number;
+        }>;
+    }>;
+    RightStick: Readonly<{
+        x: Readonly<{
+            axis: number;
+        }>;
+        y: Readonly<{
+            axis: number;
+        }>;
+    }>;
+    DPad: Readonly<{
+        x: Readonly<{
+            negative: readonly number[];
+            positive: readonly number[];
+        }>;
+        y: Readonly<{
+            negative: readonly number[];
+            positive: readonly number[];
+        }>;
+    }>;
+    Move: Readonly<{
+        x: Readonly<{
+            axis: 0;
+            negative: readonly number[];
+            positive: readonly number[];
+        }>;
+        y: Readonly<{
+            axis: 1;
+            negative: readonly number[];
+            positive: readonly number[];
+        }>;
+    }>;
+}>;
+type Binding = GamepadButtonBinding | GamepadAxisBinding | GamepadVector3Binding;
+export type CheckedGamepadBinding = readonly [ActionToken, Binding];
+export declare function gamepadIndex(value: unknown): number;
+export declare function gamepadDeadZone(value: unknown): number;
+export declare function checkedGamepadBindings(actions: ActionSet, value: unknown): readonly CheckedGamepadBinding[];
+export {};

package/dist/interaction/input-capture.d.ts

@@ -0,0 +1,38 @@
+import { type LifetimeOwner } from "../foundation/lifetime.js";
+import type { ActionBinding } from "./action-bindings.js";
+import { InputDevice, type PhysicalInput } from "./physical-input.js";
+export declare const InputCaptureState: Readonly<{
+    readonly Arming: "arming";
+    readonly Listening: "listening";
+    readonly Completed: "completed";
+    readonly Cancelled: "cancelled";
+}>;
+export type InputCaptureState = (typeof InputCaptureState)[keyof typeof InputCaptureState];
+export interface InputCaptureOptions {
+    readonly devices?: readonly InputDevice[];
+    readonly gamepadIndex?: number;
+    readonly owner?: LifetimeOwner;
+}
+export type CapturedInput = PhysicalInput & {
+    readonly binding: ActionBinding<"button">;
+};
+/** A portable single-input session. Hosts supply neutral arming and physical events. */
+export declare class InputCapture implements LifetimeOwner {
+    private readonly life;
+    private status;
+    readonly devices: readonly InputDevice[];
+    readonly gamepadIndex: number | undefined;
+    readonly result: Promise<CapturedInput | undefined>;
+    private settle;
+    constructor(options?: InputCaptureOptions);
+    get state(): InputCaptureState;
+    get disposed(): boolean;
+    onDispose(callback: () => void): () => void;
+    /** @internal Hosts call only after all eligible preheld buttons/keys are neutral. */
+    arm(): void;
+    /** @internal Offer one fresh physical down, never a repeat or opening gesture. */
+    accept(input: PhysicalInput): boolean;
+    private finish;
+    cancel(): void;
+    dispose(): void;
+}

package/dist/interaction/input.d.ts

@@ -2,6 +2,7 @@ import { type LifetimeOwner } from "../foundation/lifetime.js";
 import type { ActionFrame } from "./action-frame.js";
 import { OwnedInputSource } from "./input-source.js";
 import { type KeyCode } from "./key-code.js";
+import { type MouseButton } from "./physical-input.js";
 /** Host device adapter. Sampled before all Action frames; reset flushes held device state. */
 export interface InputAdapter {
     sample(): void;
@@ -13,10 +14,12 @@ export interface ActionInputPort {
     readonly active: boolean;
     readonly sourceCount: number;
     accepts(code: KeyCode): boolean;
+    acceptsMouse(button: MouseButton): boolean;
     keyChanged(): void;
     capture(frame?: ActionFrame): void;
     dispatch(): void;
     reset(): void;
+    resetPhysical(): void;
     dispose(): void;
 }
 /** A keyboard device contribution, not a game-facing state reader.
@@ -27,11 +30,20 @@ export declare class KeyboardSource extends OwnedInputSource {
     set(code: KeyCode, pressed: boolean): void;
     protected release(remove: boolean): void;
 }
+/** Physical mouse contribution; game state is read through ActionController. */
+export declare class MouseSource extends OwnedInputSource {
+    private readonly input;
+    /** @internal */ constructor(input: InputSystem);
+    set(button: MouseButton, pressed: boolean): void;
+    protected release(remove: boolean): void;
+}
 /** Engine-owned routing and update boundary. No raw game-state/alternate movement API. */
 export declare class InputSystem {
     private readonly actions;
     private readonly adapters;
     private readonly keyboards;
+    private readonly mice;
+    private captureCancel;
     private dead;
     private playback;
     private frames;
@@ -42,12 +54,17 @@ export declare class InputSystem {
     /** Host integration boundary; ordinary game input uses ActionSource instead. */
     addAdapter(adapter: InputAdapter): () => void;
     acceptsKey(code: KeyCode): boolean;
+    acceptsMouse(button: MouseButton): boolean;
+    /** @internal */ mouseDown(button: MouseButton): boolean;
     private notify;
     /** @internal Device state is resolved only through Action bindings. */
     keyDown(code: KeyCode): boolean;
     /** @internal Freeze every controller before invoking any callbacks. */
     beginStep(captured?: () => void): void;
     createKeyboardSource(owner?: LifetimeOwner): KeyboardSource;
+    createMouseSource(owner?: LifetimeOwner): MouseSource;
+    /** @internal */ writeMouse(source: MouseSource, button: MouseButton, pressed: boolean): void;
+    /** @internal */ releaseMouse(source: MouseSource, remove: boolean): void;
     /** @internal */ writeKey(source: KeyboardSource, code: KeyCode, pressed: boolean): void;
     /** @internal */ releaseKeyboard(source: KeyboardSource, remove: boolean): void;
     /** @internal */ hasController(controller: object): boolean;
@@ -56,6 +73,9 @@ export declare class InputSystem {
     /** @internal */ lockPlayback(): void;
     /** @internal */ playbackFrames(frames: ReadonlyMap<object, ActionFrame>): void;
     /** @internal */ unlockPlayback(): void;
+    /** @internal Host capture gate. Program ActionSource values remain explicit. */
+    suspendLiveInput(cancel: () => void): () => void;
+    private resetPhysical;
     clear(): void;
     /** Device diagnostics only; game state is ActionController.snapshot(). */
     snapshot(): readonly KeyCode[];

package/dist/interaction/physical-input.d.ts

@@ -0,0 +1,32 @@
+import type { KeyCode } from "./key-code.js";
+export declare const InputDevice: Readonly<{
+    readonly Keyboard: "keyboard";
+    readonly Mouse: "mouse";
+    readonly Gamepad: "gamepad";
+}>;
+export type InputDevice = (typeof InputDevice)[keyof typeof InputDevice];
+/** Standard PointerEvent.button indices; these are not the buttons bit mask. */
+export declare const MouseButton: Readonly<{
+    readonly Left: 0;
+    readonly Middle: 1;
+    readonly Right: 2;
+    readonly Back: 3;
+    readonly Forward: 4;
+}>;
+export type MouseButton = (typeof MouseButton)[keyof typeof MouseButton];
+export declare function isMouseButton(value: unknown): value is MouseButton;
+export declare function parseMouseButton(value: unknown): MouseButton;
+/** One physical digital input, independent of an Action's gameplay meaning. */
+export type PhysicalInput = {
+    readonly device: "keyboard";
+    readonly code: KeyCode;
+} | {
+    readonly device: "mouse";
+    readonly button: MouseButton;
+} | {
+    readonly device: "gamepad";
+    readonly index: number;
+    readonly id: string;
+    readonly mapping: string;
+    readonly button: number;
+};

package/dist/interaction/pointer-routing.d.ts

@@ -79,6 +79,8 @@ export declare class PointerRouting {
     hasHover(id: number): boolean;
     has(id: number): boolean;
     owns(id: number): boolean;
+    /** @internal Mouse bindings observe world ownership without claiming a second gesture. */
+    worldOwns(id: number): boolean;
     move(data: PointerInfo): void;
     private sampleVelocity;
     private claimScroll;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpludify/core",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "module",
   "exports": {
     ".": {