@simpludify/core 0.1.3 → 0.1.5

package/dist/interaction/actions.d.ts

@@ -42,15 +42,20 @@ export declare class ActionController<A extends ActionSet> implements LifetimeOw
     private readonly entries;
     private readonly sources;
     private readonly bus;
+    private keyboardAllowed;
+    private readonly blockedKeys;
     private pending;
     private transitions;
     constructor(actions: A, options: {
         scene: Scene;
         input: InputSystem;
         bindings?: ActionBindings<A>;
+        keyboard?: boolean;
     });
     get disposed(): boolean;
     get active(): boolean;
+    get keyboardEnabled(): boolean;
+    set keyboardEnabled(value: boolean);
     get sourceCount(): number;
     onDispose(callback: () => void): () => void;
     private entry;

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

@@ -2,8 +2,11 @@ import { type LifetimeOwner } from "../foundation/lifetime.js";
 /** @internal Shared lifetime for logical and device contributions. */
 export declare abstract class OwnedInputSource {
     private dead;
+    private accepting;
     private removeOwner;
     get disposed(): boolean;
+    get enabled(): boolean;
+    set enabled(value: boolean);
     /** @internal */ own(owner: LifetimeOwner): void;
     protected writable(neutral: boolean): boolean;
     protected abstract release(remove: boolean): void;

package/dist/interaction/input.d.ts

@@ -2,6 +2,12 @@ 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";
+/** Host device adapter. Sampled before all Action frames; reset flushes held device state. */
+export interface InputAdapter {
+    sample(): void;
+    reset(): void;
+    dispose(): void;
+}
 /** @internal Engine boundary participant, implemented by ActionController. */
 export interface ActionInputPort {
     readonly active: boolean;
@@ -24,12 +30,17 @@ export declare class KeyboardSource extends OwnedInputSource {
 /** 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 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;
     private notify;
     /** @internal Device state is resolved only through Action bindings. */

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;
@@ -86,6 +93,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;
+}

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

@@ -0,0 +1,68 @@
+import type { Point, ScreenPoint, Viewport } from "../graphics/coordinates.js";
+export type VirtualSpace = "viewport" | "screen";
+export interface VirtualPosition extends Point {
+    /** viewport uses fractions of the current Viewport; screen uses host CSS pixels. */
+    readonly space?: VirtualSpace;
+}
+export interface VirtualRectRegion extends VirtualPosition {
+    readonly kind: "rect";
+    readonly width: number;
+    readonly height: number;
+}
+export interface VirtualCircleRegion extends VirtualPosition {
+    readonly kind: "circle";
+    /** In viewport space the radius is a fraction of its smaller dimension. */
+    readonly radius: number;
+}
+export interface VirtualCustomRegion {
+    readonly kind: "custom";
+    /** Conservative host CSS-pixel bounds, including every point accepted by contains. */
+    readonly bounds: (viewport: Viewport) => Viewport;
+    readonly contains: (point: ScreenPoint, viewport: Viewport) => boolean;
+}
+export type VirtualRegion = VirtualRectRegion | VirtualCircleRegion | VirtualCustomRegion;
+export declare const VirtualRegions: Readonly<{
+    /** A shared edge is not an overlap. Use separate rectangles to leave a center gap. */
+    Left: Readonly<{
+        readonly kind: "rect";
+        readonly x: 0;
+        readonly y: 0;
+        readonly width: 0.5;
+        readonly height: 1;
+    }>;
+    Right: Readonly<{
+        readonly kind: "rect";
+        readonly x: 0.5;
+        readonly y: 0;
+        readonly width: 0.5;
+        readonly height: 1;
+    }>;
+}>;
+/** @internal */
+export type ResolvedVirtualRegion = {
+    readonly kind: "rect";
+    readonly bounds: Viewport;
+} | {
+    readonly kind: "circle";
+    readonly bounds: Viewport;
+    readonly center: Point;
+    readonly radius: number;
+} | {
+    readonly kind: "custom";
+    readonly bounds: Viewport;
+    readonly test: VirtualCustomRegion["contains"];
+};
+/** @internal */
+export declare function virtualFinite(value: number, field: string): number;
+/** @internal */
+export declare function virtualBounds(value: Viewport): Viewport;
+/** @internal */
+export declare function virtualPosition(value: VirtualPosition, viewport: Viewport): Point;
+/** @internal Copy configuration before retaining it. Predicate functions are deliberately live. */
+export declare function checkedVirtualRegion(region: VirtualRegion): VirtualRegion;
+/** @internal */
+export declare function resolveVirtualRegion(region: VirtualRegion, viewport: Viewport): ResolvedVirtualRegion;
+/** @internal Rectangles are half-open; circles exclude their circumference. */
+export declare function virtualContains(region: ResolvedVirtualRegion, point: ScreenPoint, viewport: Viewport): boolean;
+/** @internal Exact built-in intersection; custom bounds are conservatively ambiguous. */
+export declare function virtualOverlap(a: ResolvedVirtualRegion, b: ResolvedVirtualRegion): boolean;

package/package.json

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