@simpludify/web 0.1.2 → 0.1.4

package/README.md

@@ -1,11 +1,11 @@
 # @simpludify/web
 
-Experimental v0.1.2 browser SDK for Simpludify, a code-first TypeScript 2D engine. APIs may change between 0.x releases. Includes Game, PixiJS rendering, browser input and Canvas/DOM UI adapters; re-exports the host-independent Core API. Core and PixiJS are installed as runtime dependencies, not bundled into this package.
+Experimental v0.1.4 browser SDK for Simpludify, a code-first TypeScript 2D engine. APIs may change between 0.x releases. Includes Game, PixiJS rendering, browser input and Canvas/DOM UI adapters; re-exports the host-independent Core API. Core and PixiJS are installed as runtime dependencies, not bundled into this package.
 
-Registry installation (check availability with `npm view @simpludify/web@0.1.2 version`):
+Registry installation (check availability with `npm view @simpludify/web@0.1.4 version`):
 
 ```sh
-npm install @simpludify/web@0.1.2
+npm install @simpludify/web@0.1.4
 npm install --save-dev vite typescript
 ```
 
@@ -20,3 +20,5 @@ await game.run();
 Use a browser bundler such as Vite, with an HTML module entry and a parent with an explicit height. The entry automatically imports scoped CSS. It can also be imported explicitly with `import "@simpludify/web/style.css"`. Do not configure CSS as side-effect-free. No repository CLI, example assets or global stylesheet reset is included.
 
 ESM only, ES2022. Tooling requires Node >=22.12; Chromium/WebGL is the automated rendering target. This browser package is not a Node/SSR entry; use `@simpludify/core` for headless execution. Source maps embed original sources. [Complete Vite setup](https://github.oz-coden.com/Simpludify/guides/npm.html) · [Repository/API](https://github.com/oz-coden/Simpludify). MIT.
+
+Registry availability is recorded in the repository release report; a source version alone does not establish publication.

package/dist/canvas-visual.d.ts

@@ -18,6 +18,7 @@ export declare class CanvasVisual implements CanvasPresentation {
     private dirty;
     private dead;
     private active;
+    private cacheResolution;
     private mirroredFocus;
     private readonly subscriptions;
     private syncs;
@@ -25,14 +26,17 @@ export declare class CanvasVisual implements CanvasPresentation {
         graphics(graphics: Graphics, context: number | undefined): void;
         text(text: Text, key: string | undefined): void;
         changedText(key: string): void;
+        cacheResolution(): number | undefined;
     });
     get diagnostics(): {
         nodes: number;
+        visibleNodes: number;
         buttons: number;
         syncs: number;
         textMetrics: number;
     };
     private measure;
+    private clearCache;
     beforeResolutionChange(): void;
     focus(node: CanvasNode): void;
     private native;

package/dist/game.d.ts

@@ -1,5 +1,6 @@
 import type { CanvasNode } from "@simpludify/core";
 import { type ActionBindings, ActionController, type ActionSet, type Actor, Aspect, Camera, CanvasUI, type CanvasUIOptions, Engine, type FixedStepOptions, type FrameDriver, type JsonValue, type LogicalResolution, type RendererPort, type ReplayControllers, ReplayPlayer, Scene, ScenePointer, type ScreenPoint, type TweenScheduler, type Viewport, type ViewTransform, type WorldPoint } from "@simpludify/core";
+import { GamepadInput } from "./gamepads.js";
 import { Theme, type ThemeTokens, type UINode } from "./ui.js";
 export interface SceneContext {
     readonly scene: Scene;
@@ -37,6 +38,7 @@ export declare class Game<SceneId extends string = string> {
     readonly engine: Engine;
     readonly element: HTMLDivElement;
     readonly camera: Camera;
+    readonly gamepads: GamepadInput;
     private readonly renderer;
     private readonly keyboard;
     private readonly pointers;

package/dist/gamepad-bindings.d.ts

@@ -0,0 +1,100 @@
+import { type ActionKind, type ActionSet, type ActionToken } from "@simpludify/core";
+/** 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/gamepad-layout.d.ts

@@ -0,0 +1,18 @@
+export type GamepadLayout = "generic" | "xbox" | "playstation" | "nintendo";
+export interface GamepadInfo {
+    /** Unmodified browser string; never a persistent individual-device identifier. */
+    readonly id: string;
+    readonly index: number;
+    readonly connected: boolean;
+    readonly mapping: string;
+    readonly standardMapping: boolean;
+    readonly buttonCount: number;
+    readonly axisCount: number;
+    /** Heuristic ID hint, not a browser fact or guaranteed product detection. */
+    readonly inferredLayout: GamepadLayout;
+}
+export declare function gamepadButtonLabel(button: number, options?: {
+    readonly layout?: GamepadLayout;
+    readonly overrides?: Readonly<Record<number, string>>;
+}): string;
+export declare function inferredGamepadLayout(id: string): GamepadLayout;

package/dist/gamepads.d.ts

@@ -0,0 +1,79 @@
+import { type ActionController, type ActionSet, type InputAdapter, type InputSystem, type LifetimeOwner } from "@simpludify/core";
+import { type GamepadBindings } from "./gamepad-bindings.js";
+import { type GamepadInfo } from "./gamepad-layout.js";
+/** Structural polling boundary also usable by deterministic tests/custom Web hosts. */
+export interface GamepadState {
+    readonly id: string;
+    readonly index: number;
+    readonly connected: boolean;
+    readonly mapping: string;
+    readonly axes: readonly number[];
+    readonly buttons: readonly {
+        readonly value: number;
+        readonly pressed: boolean;
+    }[];
+}
+export type GamepadPoll = () => readonly (GamepadState | null)[];
+export interface GamepadOptions<A extends ActionSet> {
+    readonly index: number;
+    readonly bindings: GamepadBindings<A>;
+    readonly deadZone?: number;
+    /** Positional constants require standard mapping; raw is an explicit opt-in. */
+    readonly mapping?: "standard" | "raw";
+}
+/** A controller-owned device contribution. Reassignment does not replace its readers/Actors. */
+export declare class GamepadSource<A extends ActionSet> {
+    private readonly input;
+    private readonly controller;
+    private readonly life;
+    private readonly source;
+    private bindings;
+    private assigned;
+    private armed;
+    private signature;
+    private readonly zone;
+    private readonly mapping;
+    constructor(input: GamepadInput, controller: ActionController<A>, options: GamepadOptions<A>);
+    get disposed(): boolean;
+    get enabled(): boolean;
+    set enabled(value: boolean);
+    get index(): number;
+    get info(): GamepadInfo | undefined;
+    get connected(): boolean;
+    get usable(): boolean;
+    assign(index: number): void;
+    rebind(bindings: GamepadBindings<A>): void;
+    clear(): void;
+    private alive;
+    /** @internal */ sample(pad: GamepadState | undefined, allowed: boolean): void;
+    /** @internal */ onDispose(callback: () => void): () => void;
+    dispose(): void;
+}
+/** One Web host adapter; multiple sources share a single snapshot per Engine input boundary. */
+export declare class GamepadInput implements InputAdapter {
+    private readonly input;
+    private readonly life;
+    private readonly changes;
+    private readonly sources;
+    private readonly disconnected;
+    private listed;
+    private readable;
+    private readonly poll;
+    private readonly active;
+    constructor(input: InputSystem, options?: {
+        readonly poll?: GamepadPoll;
+        readonly active?: () => boolean;
+        readonly events?: EventTarget;
+    });
+    get disposed(): boolean;
+    /** Whether the most recent polling attempt completed; an empty list may still need a user gesture. */
+    get available(): boolean;
+    get devices(): readonly GamepadInfo[];
+    onChange(handler: () => void, owner?: LifetimeOwner): () => void;
+    private publish;
+    /** @internal */ assertController(controller: object): void;
+    bind<A extends ActionSet>(controller: ActionController<A>, options: GamepadOptions<A>): GamepadSource<A>;
+    sample(): void;
+    reset(): void;
+    dispose(): void;
+}

package/dist/index.d.ts

@@ -3,6 +3,12 @@ export * from "@simpludify/core";
 export { browserAbortSignal, CanvasButton } from "./canvas-node.js";
 export type { CanvasPresentation } from "./canvas-visual.js";
 export * from "./game.js";
+export type { GamepadAxisBinding, GamepadBinding, GamepadButtonBinding, GamepadVector3Binding, GamepadVectorBinding, } from "./gamepad-bindings.js";
+export { GamepadAxis, GamepadBindings, GamepadButton, } from "./gamepad-bindings.js";
+export type { GamepadInfo, GamepadLayout } from "./gamepad-layout.js";
+export { gamepadButtonLabel } from "./gamepad-layout.js";
+export type { GamepadOptions, GamepadPoll, GamepadState } from "./gamepads.js";
+export { GamepadInput, GamepadSource } from "./gamepads.js";
 export { BrowserInput } from "./input.js";
 export { PixiRenderer } from "./renderer.js";
 export * from "./ui.js";