web-input-system 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 林贤庆 (Xianqing Lin)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# web-input-system
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[中文文档](./README.zh-CN.md)
+
+A lightweight, Unity-style input system for browser games: describe all input in one
+**declarative asset** (action maps + actions + bindings), then consume typed action
+objects via callbacks or polling. Zero dependencies, engine-agnostic (works with
+Three.js, Phaser, Babylon, Canvas2D, or plain DOM).
+
+## Features
+
+- **Declarative input asset** — one `defineInputAsset` table holds every map/action/binding; action names and value types are fully inferred.
+- **Three-phase callbacks** — `started` / `performed` / `canceled`, Unity-style; subscriptions return an unsubscribe function.
+- **Polling channel** — `readValue()` (`boolean` / `number` / `{x,y}`) and `isPressed()`; inactive maps report default values.
+- **Composite bindings** — `axis1D` (A/D → axis), `vector2D` (WASD → vector, diagonals normalized).
+- **Interactions** — `hold` / `tap` / `doubleTap` decide *when* a button action fires.
+- **Processors** — `scale` / `invert` / `invertX` / `invertY` / `deadzone` / `clamp` / `normalize` transform values after evaluation (polling and callbacks see the same result).
+- **Action maps** — explicit `enable()/disable()` plus declarative `active(ctx)` predicates; deactivating a map fires `canceled` on its actuated actions (no stuck state).
+- **Mouse controls** — built-in paths `<Mouse>/delta`, `<Mouse>/wheelY`, `<Mouse>/leftButton`, etc., with optional pointer-lock gating.
+- **Browser robustness built in** — blur/tab-switch clears held keys and fires `canceled`, OS auto-repeat (`e.repeat`) filtered, form-field typing ignored, `preventDefault` only for bound keys.
+
+## Quick start
+
+```ts
+import { createInput, defineInputAsset, vector2D, scale, MOUSE_DELTA } from 'web-input-system';
+
+interface Ctx { isPaused: boolean }
+
+// 1. The input asset: single source of truth for maps/actions/bindings.
+//    (Annotate predicate parameters — the context type is inferred from them.)
+const asset = defineInputAsset({
+  maps: {
+    gameplay: {
+      active: (ctx: Ctx) => !ctx.isPaused,
+      actions: {
+        move: { type: 'value', value: 'vector2', bindings: [
+          vector2D({ up: 'KeyW', down: 'KeyS', left: 'KeyA', right: 'KeyD' }),
+        ]},
+        jump: { type: 'button', bindings: ['Space'] },
+        look: { type: 'value', value: 'vector2', bindings: [MOUSE_DELTA], processors: [scale(0.002)] },
+      },
+    },
+    ui: {
+      actions: {
+        pause: { type: 'button', bindings: ['Escape'] },
+      },
+    },
+  },
+});
+
+// 2. Create the manager (context sampled live; setContext also available).
+const input = createInput(asset, { context: () => ({ isPaused: store.paused }) });
+
+// 3. Subscribe (returns an unsubscribe function).
+input.action('ui', 'pause').performed(() => togglePause());
+input.action('gameplay', 'jump').canceled(() => console.log('jump released'));
+
+// 4. Frame loop: poll continuous values, reset deltas at end of frame.
+function frame(dt: number) {
+  const dir = input.action('gameplay', 'move').readValue(); // { x, y }, normalized
+  player.move(dir.x, dir.y);
+  input.update(dt);
+}
+```
+
+## Semantics worth knowing
+
+- **Delta controls** (`<Mouse>/delta`, `<Mouse>/wheelY`): callback `ctx.value` is the
+  *per-event* delta; `readValue()` is the *per-frame accumulation*, reset by
+  `input.update(dt)`. They dispatch `performed` only — no `started`/`canceled`.
+- **Discrete controls** (keyboard / mouse buttons): `started`+`performed` on press,
+  `canceled` on release, blur, or map deactivation.
+- **Interactions** (button actions): `hold` performs only after being held long enough
+  (early release only cancels); `tap` performs on a quick press+release; `doubleTap`
+  needs two quick taps within the interval. Timers advance in `input.update(dt)`.
+  One interaction per action.
+- **Processors** (value actions): applied in order after evaluation; each processor
+  declares the value types it handles and passes others through untouched.
+- **Context**: prefer the live `context: () => Ctx` sampler (never stale);
+  `input.setContext(ctx)` is the push-style alternative.
+- **SSR-safe**: no `window` access at module scope; without a DOM the manager is
+  constructed detached.
+
+## Runtime rebinding
+
+```ts
+// Capture flow: the next key/mouse-button press becomes the new binding
+// (Escape cancels by default; blur cancels; the returned function cancels manually).
+input.startRebind('gameplay', 'jump', {
+  onComplete: (path) => console.log('jump is now on', path),
+  onCancel: () => console.log('rebind cancelled'),
+});
+
+// Persistence is the host's job — overrides are plain JSON.
+localStorage.setItem('bindings', JSON.stringify(input.exportOverrides()));
+input.applyOverrides(JSON.parse(localStorage.getItem('bindings') ?? '{}'));
+
+// Conflict detection before accepting a binding.
+input.findActionsByControl('Space'); // → [{ map: 'gameplay', action: 'jump' }]
+
+// Composite parts (e.g. "move up"): read, edit, write back.
+const [wasd] = input.getBindings('movement', 'move');
+input.setBindings('movement', 'move', [vector2D({ ...wasd, up: 'ArrowUp' })]);
+
+input.resetBindings(); // restore asset defaults
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,108 @@
+# web-input-system
+
+[English](./README.md)
+
+Unity Input System 的浏览器轻量版：用一份**声明式输入资产**（动作地图 + 动作 + 绑定）
+描述全部输入，运行时得到类型安全的动作对象——回调订阅与轮询双通道，零依赖、
+引擎无关（不绑定 Three.js / Phaser / React）。
+
+## 特性
+
+- **声明式输入资产**：`defineInputAsset` 一张表声明地图/动作/绑定，动作名与值类型全推导；
+- **三阶段回调**：`started` / `performed` / `canceled`（Unity 同款生命周期），订阅返回退订函数；
+- **轮询双通道**：`readValue()`（boolean / number / Vector2）与 `isPressed()`，地图未激活时返回默认值；
+- **复合绑定**：`axis1D`（A/D 合成轴）、`vector2D`（WASD 合成向量，对角线自动归一化）；
+- **Interactions**：`hold`（长按）/ `tap`（点按）/ `doubleTap`（双击）决定 button 动作何时触发；
+- **Processors**：`scale` / `invert` / `invertX` / `invertY` / `deadzone` / `clamp` / `normalize`
+  链式加工 value 动作的值（轮询与回调拿到同一加工结果）；
+- **动作地图**：`enable()/disable()` 显式开关 + `active` 谓词声明式门控，二者并存；
+  地图失活自动给激活中的动作补发 `canceled`（状态不卡死）；
+- **鼠标控件**：`<Mouse>/delta`、`<Mouse>/wheelY`、`<Mouse>/leftButton` 等内置路径，
+  可选指针锁定门控（`gateMouseByPointerLock`）；
+- **健壮性**：窗口失焦/切后台清空按键并补发 `canceled`、过滤 OS 按住连发（`e.repeat`）、
+  输入框/文本域打字豁免、`preventDefault` 仅针对绑定键。
+
+## 快速上手
+
+```ts
+import { createInput, defineInputAsset, vector2D, MOUSE_DELTA } from 'web-input-system';
+
+interface Ctx { isPaused: boolean }
+
+// 1. 输入资产：地图/动作/绑定的唯一出处（谓词参数标注类型，Ctx 由此推导）
+const asset = defineInputAsset({
+  maps: {
+    gameplay: {
+      active: (ctx: Ctx) => !ctx.isPaused,
+      actions: {
+        move: { type: 'value', value: 'vector2', bindings: [
+          vector2D({ up: 'KeyW', down: 'KeyS', left: 'KeyA', right: 'KeyD' }),
+        ]},
+        jump: { type: 'button', bindings: ['Space'] },
+        look: { type: 'value', value: 'vector2', bindings: [MOUSE_DELTA] },
+      },
+    },
+    ui: {
+      actions: {
+        pause: { type: 'button', bindings: ['Escape'] },
+      },
+    },
+  },
+});
+
+// 2. 创建管理器（上下文实时采样；也可 setContext 推送）
+const input = createInput(asset, { context: () => ({ isPaused: store.paused }) });
+
+// 3. 回调订阅（返回退订函数）
+input.action('ui', 'pause').performed(() => togglePause());
+input.action('gameplay', 'jump').canceled(() => console.log('jump released'));
+
+// 4. 帧循环：轮询持续值，帧末清零增量
+function frame(dt: number) {
+  const dir = input.action('gameplay', 'move').readValue(); // { x, y }，已归一化
+  player.move(dir.x, dir.y);
+  input.update(dt);
+}
+```
+
+## 设计约定
+
+- **Interactions（button 动作）**：`interactions: [hold(0.5)]` 决定何时触发。
+  默认（即 `press()`）按下即 `started`+`performed`、松开 `canceled`；`hold` 按住满时长才
+  `performed`、提前松开只 `canceled`；`tap` 快速点按才 `performed`；`doubleTap` 间隔内两次
+  点按才 `performed`。计时依赖每帧调用 `input.update(dt)`；每个动作最多一个 interaction。
+- **Processors（value 动作）**：`processors: [scale(0.1), invertY()]` 在求值后按序加工，
+  轮询与回调拿到同一结果。每个 processor 声明自己处理的值类型（axis 走 `number`，
+  vector2 走 `vector2`），不匹配的类型原样透传。
+
+- **增量控件**（`<Mouse>/delta`、`MOUSE_WHEEL_Y`）：回调里 `ctx.value` 是**本次事件**的增量；
+  `readValue()` 轮询是**本帧累计**，`input.update(dt)` 清零。只派发 `performed`，
+  不维护 `started`/`canceled`。
+- **离散控件**（键盘/鼠标按键）：`started`+`performed` 在按下时派发，`canceled` 在松开、
+  失焦或所属地图失活时派发。
+- **上下文**：构造选项 `context: () => Ctx` 实时采样（推荐，无陈旧状态），
+  或 `input.setContext(ctx)` 推送；二者采样器优先。
+- **SSR 安全**：模块顶层不触碰 `window`；无 DOM 环境可构造但处于未接线状态。
+
+## 运行时重绑定
+
+```ts
+// 捕获流程：下一次按键/鼠标点击成为新绑定（默认 Escape 取消；失焦取消；返回函数手动取消）
+input.startRebind('gameplay', 'jump', {
+  onComplete: (path) => console.log('jump 现在绑定到', path),
+  onCancel: () => console.log('已取消'),
+});
+
+// 覆盖表是纯 JSON，持久化由宿主负责
+localStorage.setItem('bindings', JSON.stringify(input.exportOverrides()));
+input.applyOverrides(JSON.parse(localStorage.getItem('bindings') ?? '{}'));
+
+// 接受绑定前的冲突检测
+input.findActionsByControl('Space'); // → [{ map: 'gameplay', action: 'jump' }]
+
+// 复合绑定部件（如"向前移动"）：读出、改一个部件、写回
+const [wasd] = input.getBindings('movement', 'move');
+input.setBindings('movement', 'move', [vector2D({ ...wasd, up: 'ArrowUp' })]);
+
+input.resetBindings(); // 恢复资产默认
+```

package/dist/action.d.ts

@@ -0,0 +1,43 @@
+/**
+ * InputAction: a single action, created by InputManager from the asset.
+ *
+ * Two ways to consume:
+ * - subscribe: performed / started / canceled (each returns an unsubscribe fn)
+ * - poll: readValue() (current value), isPressed() (currently actuated)
+ *
+ * Lifecycle for discrete controls:
+ *   press → started → performed (re-fires on value change) → release → canceled
+ * Delta controls (mouse motion, wheel) only dispatch performed.
+ */
+import type { ActionCallback, ActionPhase } from './types';
+/** Runtime hooks injected by InputManager (avoids a reverse type dependency). */
+export interface ActionRuntime<T> {
+    readValue: () => T;
+    isPressed: () => boolean;
+}
+export declare class InputAction<T = boolean> {
+    /** Action name in 'map.action' form, for logging and debugging. */
+    readonly name: string;
+    /** Current phase ('waiting' = never triggered or fully reset). */
+    get phase(): ActionPhase;
+    private _phase;
+    private readonly runtime;
+    private readonly listeners;
+    constructor(name: string, runtime: ActionRuntime<T>);
+    /** Subscribe to performed (value produced/changed). Returns an unsubscribe fn. */
+    performed(cb: ActionCallback<T>): () => void;
+    /** Subscribe to started (first frame leaving the default value). Returns an unsubscribe fn. */
+    started(cb: ActionCallback<T>): () => void;
+    /** Subscribe to canceled (release / back to default / map deactivated). Returns an unsubscribe fn. */
+    canceled(cb: ActionCallback<T>): () => void;
+    private subscribe;
+    /** Poll the current value (type default — false / 0 / {0,0} — while the map is inactive). */
+    readValue(): T;
+    /** Whether the action is currently actuated (button: held; value: non-default). */
+    isPressed(): boolean;
+    /** [internal] Called by the manager during dispatch. */
+    _emit(phase: 'started' | 'performed' | 'canceled', value: T): void;
+    /** [internal] Reset phase without dispatching (used by dispose). */
+    _reset(): void;
+}
+//# sourceMappingURL=action.d.ts.map

package/dist/action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAyB,WAAW,EAAE,MAAM,SAAS,CAAC;AAElF,iFAAiF;AACjF,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC,CAAC;IACnB,SAAS,EAAE,MAAM,OAAO,CAAC;CAC1B;AAED,qBAAa,WAAW,CAAC,CAAC,GAAG,OAAO;IAClC,mEAAmE;IACnE,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,IAAW,KAAK,IAAI,WAAW,CAE9B;IAED,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAIxB;gBAEU,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC;IAKnD,kFAAkF;IAC3E,SAAS,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAInD,+FAA+F;IACxF,OAAO,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAIjD,sGAAsG;IAC/F,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAIlD,OAAO,CAAC,SAAS;IAMjB,6FAA6F;IACtF,SAAS,IAAI,CAAC;IAIrB,mFAAmF;IAC5E,SAAS,IAAI,OAAO;IAI3B,wDAAwD;IACjD,KAAK,CAAC,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAWzE,oEAAoE;IAC7D,MAAM,IAAI,IAAI;CAGtB"}

package/dist/actionMap.d.ts

@@ -0,0 +1,21 @@
+/**
+ * InputActionMap: a named group of actions with a shared activation condition.
+ *
+ * A map is effectively active when: enabled && (active?.(ctx) ?? true).
+ * - enable()/disable(): explicit runtime switch
+ * - the asset's `active` predicate: declarative context gating
+ *
+ * When a map deactivates, its actuated actions receive `canceled` (no stuck
+ * state); when it reactivates, still-held controls re-fire started+performed.
+ */
+export declare class InputActionMap {
+    readonly name: string;
+    /** [internal] Notifies the manager to re-evaluate dispatch on toggle. */
+    private readonly onToggle;
+    private _enabled;
+    constructor(name: string, onToggle: () => void);
+    get enabled(): boolean;
+    enable(): void;
+    disable(): void;
+}
+//# sourceMappingURL=actionMap.d.ts.map

package/dist/actionMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionMap.d.ts","sourceRoot":"","sources":["../src/actionMap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,qBAAa,cAAc;IACzB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAa;IACtC,OAAO,CAAC,QAAQ,CAAQ;gBAEZ,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI;IAK9C,IAAW,OAAO,IAAI,OAAO,CAE5B;IAEM,MAAM,IAAI,IAAI;IAMd,OAAO,IAAI,IAAI;CAKvB"}

package/dist/asset.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Input asset definition: the single source of truth for maps, actions, bindings.
+ *
+ * An asset is plain data (processors hold functions, everything else is
+ * JSON-serializable); defineInputAsset only carries types. Map names, action
+ * names and per-action value types are all inferred from the object literal,
+ * so input.action('movement', 'move') returns a precise type.
+ */
+import type { CompositeBinding } from './composites';
+import type { InteractionDef } from './interactions';
+import type { Processor } from './processors';
+import type { ActionValueType, ControlPath, ValueOfType } from './types';
+/** A single control path, or a composite combining several controls into one value. */
+export type Binding = ControlPath | CompositeBinding;
+export interface ButtonActionDef {
+    /** button: press/release semantics; started+performed on press, canceled on release. */
+    readonly type: 'button';
+    readonly bindings?: readonly Binding[];
+    /**
+     * Trigger conditions (hold / tap / doubleTap). Default (= press()) fires on
+     * press. At most one interaction per action.
+     */
+    readonly interactions?: readonly InteractionDef[];
+}
+export interface ValueActionDef {
+    /** value: continuous semantics; poll via readValue(), performed fires on value change. */
+    readonly type: 'value';
+    readonly value: ActionValueType;
+    readonly bindings?: readonly Binding[];
+    /** Value transforms, applied in order after evaluation (both polling and callbacks). */
+    readonly processors?: readonly Processor[];
+}
+export type ActionDef = ButtonActionDef | ValueActionDef;
+export interface ActionMapDef<Ctx = unknown> {
+    /**
+     * Activation predicate: false takes the whole map out of dispatch (default: always
+     * active). Coexists with the enabled flag: effective = enabled && active(ctx).
+     */
+    readonly active?: (ctx: Ctx) => boolean;
+    readonly actions: Record<string, ActionDef>;
+}
+export interface InputAssetDef<Ctx = unknown> {
+    readonly maps: Record<string, ActionMapDef<Ctx>>;
+}
+/** Opaque handle returned by defineInputAsset, carrying the def and context types. */
+export interface InputAsset<Ctx, Def extends InputAssetDef<Ctx>> {
+    readonly def: Def;
+}
+/** Context type inferred from the `active` predicate parameter annotations. */
+type CtxOf<Def> = Def extends InputAssetDef<infer C> ? C : unknown;
+/**
+ * Define an input asset (returns the def as-is; only carries types).
+ *
+ * Annotate predicate parameters with your context type so Ctx can be inferred:
+ *   defineInputAsset({ maps: { move: { active: (ctx: MyCtx) => ctx.playing, actions: {...} } } })
+ */
+export declare function defineInputAsset<const Def extends InputAssetDef<any>>(def: Def): InputAsset<CtxOf<Def>, Def>;
+/** JS value type of an action definition. */
+export type ActionValueOf<D> = D extends {
+    readonly type: 'button';
+} ? boolean : D extends {
+    readonly type: 'value';
+    readonly value: infer V extends ActionValueType;
+} ? ValueOfType<V> : never;
+/** Asset definition → per-action value types (drives InputManager.action's return type). */
+export type AssetActionValues<Def extends InputAssetDef<any>> = {
+    [M in keyof Def['maps']]: {
+        [A in keyof Def['maps'][M]['actions']]: ActionValueOf<Def['maps'][M]['actions'][A]>;
+    };
+};
+export {};
+//# sourceMappingURL=asset.d.ts.map

package/dist/asset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset.d.ts","sourceRoot":"","sources":["../src/asset.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEzE,uFAAuF;AACvF,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,gBAAgB,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,cAAc;IAC7B,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACvC,wFAAwF;IACxF,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;CAC5C;AAED,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,cAAc,CAAC;AAEzD,MAAM,WAAW,YAAY,CAAC,GAAG,GAAG,OAAO;IACzC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa,CAAC,GAAG,GAAG,OAAO;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;CAClD;AAED,sFAAsF;AACtF,MAAM,WAAW,UAAU,CAAC,GAAG,EAAE,GAAG,SAAS,aAAa,CAAC,GAAG,CAAC;IAC7D,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;CACnB;AAED,+EAA+E;AAC/E,KAAK,KAAK,CAAC,GAAG,IAAI,GAAG,SAAS,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;AAEnE;;;;;GAKG;AAEH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,GAAG,SAAS,aAAa,CAAC,GAAG,CAAC,EACnE,GAAG,EAAE,GAAG,GACP,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAE7B;AAED,6CAA6C;AAC7C,MAAM,MAAM,aAAa,CAAC,CAAC,IACzB,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,OAAO,GAC3C,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,SAAS,eAAe,CAAA;CAAE,GAAG,WAAW,CAAC,CAAC,CAAC,GACpG,KAAK,CAAC;AAEd,4FAA4F;AAE5F,MAAM,MAAM,iBAAiB,CAAC,GAAG,SAAS,aAAa,CAAC,GAAG,CAAC,IAAI;KAC7D,CAAC,IAAI,MAAM,GAAG,CAAC,MAAM,CAAC,GAAG;SACvB,CAAC,IAAI,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;KACpF;CACF,CAAC"}

package/dist/composites.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Composite bindings: combine several controls into a single value.
+ *
+ * - axis1D: negative/positive pair → [-1, 1] (e.g. A/D)
+ * - vector2D: four directions → 2D vector (e.g. WASD), normalized by default
+ */
+import type { ControlPath } from './types';
+export interface Axis1DBinding {
+    readonly kind: 'axis1d';
+    readonly negative: ControlPath;
+    readonly positive: ControlPath;
+}
+export interface Vector2DBinding {
+    readonly kind: 'vector2d';
+    readonly up: ControlPath;
+    readonly down: ControlPath;
+    readonly left: ControlPath;
+    readonly right: ControlPath;
+    /** Normalize diagonals (default true; false allows length up to √2). */
+    readonly normalize: boolean;
+}
+export type CompositeBinding = Axis1DBinding | Vector2DBinding;
+export declare function axis1D(opts: {
+    negative: ControlPath;
+    positive: ControlPath;
+}): Axis1DBinding;
+export declare function vector2D(opts: {
+    up: ControlPath;
+    down: ControlPath;
+    left: ControlPath;
+    right: ControlPath;
+    normalize?: boolean;
+}): Vector2DBinding;
+export declare function isComposite(binding: unknown): binding is CompositeBinding;
+//# sourceMappingURL=composites.d.ts.map

package/dist/composites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composites.d.ts","sourceRoot":"","sources":["../src/composites.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,eAAe,CAAC;AAE/D,wBAAgB,MAAM,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,GAAG,aAAa,CAE5F;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAC7B,EAAE,EAAE,WAAW,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GAAG,eAAe,CAElB;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,gBAAgB,CAMzE"}