@simpludify/core 0.1.4 → 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,25 +30,41 @@ 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;
+    /** @internal Device hosts may reject live gestures during Replay playback. */
+    get liveInput(): boolean;
     get sourceCount(): number;
     /** @internal */ registerActions(actions: ActionInputPort): () => void;
     /** 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;
@@ -54,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

@@ -4,6 +4,7 @@ import type { ScreenPoint, WorldPoint } from "../graphics/coordinates.js";
 import type { Scene } from "../scene/scene.js";
 import type { CanvasNode } from "../ui/canvas-node.js";
 import type { CanvasUI } from "../ui/canvas-ui.js";
+import type { PointerTarget, PointerTargetProvider } from "./pointer-target.js";
 /** Snapshot coordinates at DOM delivery. Screen is host CSS units; world includes the current Camera. */
 export interface PointerInfo {
     readonly pointerId: number;
@@ -30,6 +31,10 @@ export declare class ScenePointer implements LifetimeOwner {
     private readonly lifetime;
     readonly events: EventBus;
     private readonly removeScene;
+    private targets;
+    /** @internal Exactly one Scene virtual-input provider shares the existing router. */
+    attachTargets(provider: PointerTargetProvider): () => void;
+    /** @internal */ pickTarget(data: PointerInfo): PointerTarget | undefined;
     constructor(scene: Scene);
     get disposed(): boolean;
     onDispose(callback: () => void): () => void;
@@ -38,6 +43,7 @@ export declare class ScenePointer implements LifetimeOwner {
 /** @internal Device-independent routing state; DOM is only an adapter. */
 export declare class PointerRouting {
     private readonly released;
+    private readonly targetOwners;
     private readonly controlOwners;
     private readonly scrollOwners;
     private readonly suppressed;
@@ -60,6 +66,7 @@ export declare class PointerRouting {
         deliveries: number;
         scrollDrags: number;
         controlDrags: number;
+        virtualDrags: number;
     };
     setScene(channel: ScenePointer, ui?: CanvasUI): void;
     private hold;
@@ -72,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;
@@ -86,6 +95,8 @@ export declare class PointerRouting {
     releaseKeys(node: CanvasNode): void;
     private prune;
     release(): void;
+    /** @internal Host focus changes interrupt virtual devices without changing Canvas editing rules. */
+    releaseVirtual(): void;
     dispose(): void;
     reset(): void;
 }

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

@@ -0,0 +1,14 @@
+import type { LifetimeOwner } from "../foundation/lifetime.js";
+import type { PointerInfo } from "./pointer-routing.js";
+/** @internal Scene-scoped recipients behind Canvas UI; the existing router owns all IDs. */
+export interface PointerTarget extends LifetimeOwner {
+    readonly available: boolean;
+    readonly revision: number;
+    subscribe(callback: () => void): () => void;
+    contains(data: PointerInfo): boolean;
+    deliver(type: "down" | "move" | "up" | "cancel", data: PointerInfo): void;
+}
+/** @internal */
+export interface PointerTargetProvider extends LifetimeOwner {
+    pick(data: PointerInfo): PointerTarget | undefined;
+}

package/dist/interaction/virtual-control.d.ts

@@ -0,0 +1,140 @@
+import { type LifetimeOwner } from "../foundation/lifetime.js";
+import type { Point, ScreenPoint } from "../graphics/coordinates.js";
+import type { PointerInfo } from "./pointer-routing.js";
+import type { PointerTarget } from "./pointer-target.js";
+import { type VirtualPosition, type VirtualRegion } from "./virtual-regions.js";
+export declare const VirtualStickMode: {
+    readonly Fixed: "fixed";
+    readonly Floating: "floating";
+    readonly Follow: "follow";
+};
+export type VirtualStickMode = (typeof VirtualStickMode)[keyof typeof VirtualStickMode];
+export interface VirtualControlOptions {
+    readonly region: VirtualRegion;
+    readonly position?: VirtualPosition;
+    /** Host CSS pixels, independent of Camera, DPR and Canvas UI scale. */
+    readonly radius?: number;
+    /** Radial fraction, 0 <= deadZone < 1; the remaining magnitude is rescaled. */
+    readonly deadZone?: number;
+    readonly enabled?: boolean;
+    readonly visible?: boolean;
+    /** Presentation seconds to the one-shot onHold notification. Default 0.5. */
+    readonly holdDelay?: number;
+    readonly color?: number;
+}
+export interface VirtualStickOptions extends VirtualControlOptions {
+    readonly mode?: VirtualStickMode;
+}
+export interface VirtualButtonOptions extends VirtualControlOptions {
+    /** Direction is optional; false by default. The Action remains an ordinary Button. */
+    readonly direction?: boolean;
+}
+export interface VirtualGesture {
+    readonly control: VirtualControl;
+    readonly pointerId: number;
+    readonly pointerType: string;
+    readonly origin: ScreenPoint;
+    readonly position: ScreenPoint;
+    readonly center: ScreenPoint;
+    /** Final direction is retained in end/cancel payloads after the live Action is cleared. */
+    readonly direction: Point;
+    readonly inside: boolean;
+    readonly elapsed: number;
+}
+/** @internal */
+export interface VirtualControlHost {
+    available(): boolean;
+    center(control: VirtualControl): Point;
+    contains(control: VirtualControl, data: PointerInfo): boolean;
+    region(control: VirtualControl, value: VirtualRegion): void;
+    remove(control: VirtualControl): void;
+}
+/** @internal */
+export interface VirtualBinding extends LifetimeOwner {
+    write(direction: Point, pressed: boolean): void;
+    clear(): void;
+    dispose(): void;
+    active(): boolean;
+}
+/** @internal Validate before allocating ActionSources or registering a target. */
+export declare function checkVirtualOptions(options: VirtualStickOptions & VirtualButtonOptions): void;
+/** Portable gesture state. Routing, Action composition and rendering retain their existing owners. */
+export declare abstract class VirtualControl implements PointerTarget {
+    readonly kind: "stick" | "button";
+    private readonly host;
+    private readonly binding;
+    private readonly life;
+    private readonly events;
+    private readonly observers;
+    private activation;
+    private activeFlag;
+    private shown;
+    private size;
+    private deadZoneValue;
+    private version;
+    private gesture;
+    private vector;
+    private dragMode;
+    readonly position: VirtualPosition | undefined;
+    readonly holdDelay: number;
+    readonly color: number;
+    readonly directional: boolean;
+    protected constructor(kind: "stick" | "button", options: VirtualStickOptions & VirtualButtonOptions, host: VirtualControlHost, binding: VirtualBinding);
+    get disposed(): boolean;
+    get available(): boolean;
+    get revision(): number;
+    get enabled(): boolean;
+    set enabled(value: boolean);
+    get visible(): boolean;
+    set visible(value: boolean);
+    get radius(): number;
+    set radius(value: number);
+    get deadZone(): number;
+    set deadZone(value: number);
+    get region(): VirtualRegion;
+    set region(value: VirtualRegion);
+    protected get stickMode(): VirtualStickMode;
+    protected set stickMode(value: VirtualStickMode);
+    get pointerId(): number | undefined;
+    get pressed(): boolean;
+    get elapsed(): number;
+    get direction(): Point;
+    get center(): ScreenPoint;
+    get knob(): ScreenPoint;
+    onDispose(callback: () => void): () => void;
+    /** @internal Geometry/availability invalidation, not a per-frame observer. */
+    subscribe(callback: () => void): () => void;
+    onStart(callback: (event: VirtualGesture) => void, owner?: LifetimeOwner): () => void;
+    onChange(callback: (event: VirtualGesture) => void, owner?: LifetimeOwner): () => void;
+    onEnd(callback: (event: VirtualGesture) => void, owner?: LifetimeOwner): () => void;
+    onCancel(callback: (event: VirtualGesture) => void, owner?: LifetimeOwner): () => void;
+    onHold(callback: (event: VirtualGesture) => void, owner?: LifetimeOwner): () => void;
+    /** Release/cancel only; the captured physical ID stays suppressed until its release. */
+    cancel(): void;
+    /** @internal */
+    invalidate(): void;
+    private alive;
+    private interrupt;
+    contains(data: PointerInfo): boolean;
+    private snapshot;
+    private update;
+    deliver(type: "down" | "move" | "up" | "cancel", data: PointerInfo): void;
+    /** @internal Explicit presentation clock; no browser/OS timer in Core. */
+    advance(seconds: number): void;
+    private finish;
+    dispose(): void;
+}
+export declare class VirtualStick extends VirtualControl {
+    /** @internal Use VirtualInput.stick. */
+    constructor(options: VirtualStickOptions, host: VirtualControlHost, binding: VirtualBinding);
+    get value(): Point;
+    get mode(): VirtualStickMode;
+    set mode(value: VirtualStickMode);
+}
+export declare class VirtualButton extends VirtualControl {
+    /** @internal Use VirtualInput.button. */
+    constructor(options: VirtualButtonOptions, host: VirtualControlHost, binding: VirtualBinding);
+    get value(): boolean;
+    /** Confirmation on normal release, including a drag outside the activation region; never on cancel. */
+    onCommit(callback: (event: VirtualGesture) => void, owner?: LifetimeOwner): () => void;
+}

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

@@ -0,0 +1,49 @@
+import type { Viewport } from "../graphics/coordinates.js";
+import type { ActionController, ActionSet } from "./actions.js";
+import type { InputAdapter, InputSystem } from "./input.js";
+import type { PointerInfo, ScenePointer } from "./pointer-routing.js";
+import type { PointerTargetProvider } from "./pointer-target.js";
+import { VirtualButton, type VirtualButtonOptions, type VirtualControl, VirtualStick, type VirtualStickOptions } from "./virtual-control.js";
+/** Scene-scoped virtual devices; all gameplay values flow through existing ActionSources. */
+export declare class VirtualInput implements InputAdapter, PointerTargetProvider {
+    readonly pointer: ScenePointer;
+    private readonly input;
+    private readonly life;
+    private list;
+    private regions;
+    private anchors;
+    private view;
+    private active;
+    private shown;
+    private dirty;
+    private readonly host;
+    constructor(pointer: ScenePointer, input: InputSystem);
+    get disposed(): boolean;
+    get controls(): readonly VirtualControl[];
+    get viewport(): Viewport;
+    get enabled(): boolean;
+    set enabled(value: boolean);
+    get visible(): boolean;
+    set visible(value: boolean);
+    onDispose(callback: () => void): () => void;
+    private flag;
+    private alive;
+    private validate;
+    private binding;
+    stick<A extends ActionSet>(controller: ActionController<A>, action: Extract<A[keyof A], {
+        kind: "axis2d";
+    }>, options: VirtualStickOptions): VirtualStick;
+    button<A extends ActionSet>(controller: ActionController<A>, action: Extract<A[keyof A], {
+        kind: "button";
+    }>, options: VirtualButtonOptions): VirtualButton;
+    private add;
+    private resolve;
+    private centers;
+    /** Resolve after Canvas layout and before routing/rendering. Layout changes cancel active gestures. */
+    refresh(viewport?: Viewport): void;
+    pick(data: PointerInfo): VirtualControl | undefined;
+    sample(): void;
+    advance(seconds: number): void;
+    reset(): void;
+    dispose(): void;
+}