@codexo/exojs 0.7.12 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,743 @@ All notable changes to ExoJS are documented in this file.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-05-07
+
+Wholesale rewrite of the particle subsystem around a data-oriented core
+plus a backend-agnostic auto-routing pipeline. The `Particle` class,
+`ParticleAffector` interface, `ParticleEmitter` interface,
+`ParticleOptions`, `UniversalEmitter`, and the four built-in affectors
+(`ColorAffector`, `ForceAffector`, `ScaleAffector`, `TorqueAffector`)
+are removed. They are replaced by SoA storage on the system,
+`Distribution<T>`-based spawn configs, and per-batch
+`SpawnModule` / `UpdateModule` / `DeathModule` interfaces.
+
+Update modules now declare an optional `wgsl()` contribution — when
+the system is constructed with a `WebGpuBackend` and every registered
+update module is GPU-eligible (i.e. all built-ins, plus any custom
+modules the author opts in), a composite WGSL compute shader is built
+at first `update()`. Integration + every module body + pack-instances
+all run in **one dispatch**, writing directly into the renderer's
+instance vertex buffer. **No CPU readback** in the steady state.
+
+On WebGL2 backends, or when any registered update module lacks
+`wgsl()`, the system runs the existing CPU pipeline. The decision is
+automatic and per-system; user code is unchanged across both paths.
+
+### Added — Struct-of-Arrays storage
+
+`ParticleSystem` now stores particles as parallel `Float32Array` /
+`Uint32Array` / `Uint16Array` channels addressed by slot index:
+
+```ts
+system.posX[slot]
+system.posY[slot]
+system.velX[slot]
+system.velY[slot]
+system.scaleX[slot]
+system.scaleY[slot]
+system.rotations[slot]
+system.rotationSpeeds[slot]
+system.color[slot]            // packed 0xAABBGGRR
+system.elapsed[slot]
+system.lifetime[slot]
+system.textureIndex[slot]
+system.liveCount              // [0, liveCount) is the live range
+```
+
+Capacity is fixed at construction (default 4096) — no reallocations.
+The integrate pass runs as one tight loop over typed arrays with no
+method calls. Expiry is handled by forward-compaction (O(n) total
+instead of the previous O(n²) splice loop with scattered expirations).
+
+### Added — `Distribution<T>` family
+
+Spawn-time random sampling and lifetime-parameterised evaluation:
+
+| Type | Use |
+|---|---|
+| `Constant<T>` | Always-same value |
+| `Range` | Uniform random number in `[min, max]` |
+| `VectorRange` | Per-axis random vector |
+| `ConeDirection` | Random unit vector in a cone × speed range |
+| `CircleArea` | Random point in/on a circle |
+| `BoxArea` | Random point in/on an AABB |
+| `LineSegment` | Random point on a segment |
+| `Curve` | Piecewise-linear keyframe scalar by lifetime ratio |
+| `Gradient` | Piecewise-linear keyframe color, with `evaluateRgba()` for direct u32 packing |
+
+`Curve` and `Gradient` cache the last segment so monotonically
+advancing `t` (the typical case for per-particle lifetime sampling)
+is O(1) amortised.
+
+### Added — Module pipeline
+
+Three module bases. Each registered on a system via the corresponding
+`addX` method; each runs in its declared phase per-frame.
+
+```ts
+abstract class SpawnModule  { apply(system, dt: number): void; }
+abstract class UpdateModule { apply(system, dt: number): void; }
+abstract class DeathModule  { onDeath(system, slot: number): void; }
+```
+
+**Built-in spawn modules:**
+
+- `RateSpawn({ rate, lifetime?, position?, velocity?, scale?, rotation?, rotationSpeed?, tint?, textureIndex? })`
+  — continuous emission with sub-frame accumulator. Each property is an
+  independent `Distribution<T>`.
+- `BurstSpawn({ schedule, loop?, ...samePropsAsRate })` — discrete
+  bursts at scheduled times. Use for explosions, level-ups,
+  hit-impacts.
+
+**Built-in update modules** (operate on the SoA arrays in tight loops):
+
+- `ApplyForce(ax, ay)` — adds constant acceleration.
+- `Drag(coefficient)` — exponential velocity damping.
+- `ColorOverLifetime(gradient)` — tint sampled from a `Gradient`.
+- `ScaleOverLifetime(curve)` — both axes sampled from a `Curve`.
+- `RotateOverLifetime(angularAccel)` — increments `rotationSpeed`.
+
+**Built-in death module:**
+
+- `SpawnOnDeath(targetSystem, spawner, count?)` — sub-emitter. Forwards
+  the dying particle's position to a target system's spawn module.
+  Use for explosion-on-impact, end-of-life sparks, multi-stage VFX.
+
+### Added — Backend-agnostic auto-routing GPU compute pipeline
+
+New `src/rendering/webgpu/compute/` infrastructure:
+
+- `WebGpuStorageBuffer` — owning wrapper over a `STORAGE | COPY_DST | COPY_SRC`
+  buffer with `write()` and async `read()` helpers.
+- `WebGpuComputePipeline` — `device.createComputePipeline` wrapper with
+  bind-group-layout creation, dispatch helper.
+
+New `src/particles/gpu/ParticleGpuState` — owns the GPU-side mirror
+for one `ParticleSystem`. At construction time it:
+
+1. Walks the registered update modules, collecting each module's
+   `WgslContribution` (uniform field declarations + texture bindings
+   + WGSL body snippet).
+2. Generates a composite WGSL compute shader: SoA storage bindings +
+   sim/module uniform structs + module texture bindings + a `main`
+   function containing integration → all module bodies in registration
+   order → pack-instances writing interleaved 24-byte instances into
+   a `STORAGE | VERTEX` buffer.
+3. Allocates 7 packed storage buffers (positions/velocities/scales/
+   rotInfo/timing as `vec2<f32>` arrays plus color as `u32` plus the
+   instance output) — fits within WebGPU's default
+   `maxStorageBuffersPerShaderStage = 8` limit.
+4. Allocates 1D textures for any module that declares them
+   (`Curve` → 256-tap r32float; `Gradient` → 256-tap rgba8unorm) and
+   uploads the lookup data once via `module.uploadTextures()`.
+5. Each module's `writeUniforms()` runs every frame to update its
+   slice of the shared module-uniform buffer.
+
+The `WebGpuParticleRenderer` reads the GPU-written instance buffer
+directly when `system.gpuMode` is true; CPU mode falls back to the
+existing CPU-pack path. Same renderer, same vertex layout, no copy
+between simulation and render.
+
+`UpdateModule` gains optional `wgsl()`, `writeUniforms()`,
+`uploadTextures()`. Built-in modules ship all three. Custom modules
+that implement them get GPU acceleration; modules with only `apply()`
+keep working but force their host system into CPU mode.
+
+Opt-in is a single constructor option — no imperative toggle:
+
+```ts
+const system = new ParticleSystem(texture, {
+    capacity: 8192,
+    backend: app.backend,    // CPU-routed on WebGL2, GPU-routed on WebGPU
+});
+```
+
+The `backend` reference is duck-typed against `WebGpuBackend`; on
+WebGL2 it's recorded but never used. The system's mode is locked in
+at the first `update()` (when modules are introspected); adding update
+modules after that throws.
+
+### Removed — Old particle API (BREAKING)
+
+The following symbols are deleted. Migration recipes follow the table.
+
+| Removed | Replacement |
+|---|---|
+| `Particle` (class) | SoA arrays on `ParticleSystem` (`system.posX[slot]`, etc.) |
+| `ParticleProperties` (interface) | None — slot-indexed arrays replace the per-particle object |
+| `ParticleEmitter` (interface) | `SpawnModule` (abstract class) |
+| `ParticleOptions` | Per-property `Distribution<T>` in the spawn module's config |
+| `UniversalEmitter` | `RateSpawn` |
+| `ParticleAffector` (interface) | `UpdateModule` (abstract class) |
+| `ColorAffector` | `ColorOverLifetime` + `Gradient` |
+| `ForceAffector` | `ApplyForce` |
+| `ScaleAffector` | `ScaleOverLifetime` + `Curve` |
+| `TorqueAffector` | `RotateOverLifetime` |
+| `system.requestParticle()` | `system.spawn(): number` (slot index, or `-1` at capacity) |
+| `system.emitParticle(p)` | (gone — `spawn()` already commits the slot to the live range) |
+| `system.updateParticle(p, dt)` | (gone — internal to `update()`) |
+| `system.addEmitter(e)` | `system.addSpawnModule(m)` |
+| `system.addAffector(a)` | `system.addUpdateModule(m)` |
+| `system.particles` (`Array<Particle>`) | `system.posX` / `system.posY` / ... `system.liveCount` |
+| `system.graveyard` | (gone — no graveyard; slots are recycled in place) |
+
+### Migration
+
+```ts
+// Before — bonfire
+const options = new ParticleOptions();
+const colorAffector = new ColorAffector(new Color(194, 64, 30, 1), new Color(0, 0, 0, 0));
+const emitter = new UniversalEmitter(50, options);
+const system = new ParticleSystem(texture);
+system.addAffector(colorAffector);
+system.addEmitter(emitter);
+
+// in update():
+options.totalLifetime.copy(seconds(rand(5, 10)));
+options.position.set(rand(-50, 50), rand(-10, 10));
+options.velocity.set(/* ... */);
+
+// After — bonfire
+const system = new ParticleSystem(texture);
+system.addSpawnModule(new RateSpawn({
+    rate: new Constant(50),
+    lifetime: new Range(5, 10),
+    position: new VectorRange(-50, 50, -10, 10),
+    velocity: new ConeDirection(-Math.PI / 2, Math.PI / 36, 60, 80),
+}));
+system.addUpdateModule(new ColorOverLifetime(new Gradient([
+    { t: 0, color: new Color(194, 64, 30, 1) },
+    { t: 1, color: new Color(0, 0, 0, 0) },
+])));
+// no per-frame mutation needed.
+```
+
+```ts
+// Before — gravity affector
+const gravity = new ForceAffector(0, 980);
+system.addAffector(gravity);
+
+// After
+system.addUpdateModule(new ApplyForce(0, 980));
+```
+
+```ts
+// Before — custom affector
+class AlphaFade {
+    apply(particle, delta) {
+        particle.tint.a = particle.remainingRatio;
+        return this;
+    }
+    destroy() {}
+}
+
+// After
+class AlphaFadeOverLifetime extends UpdateModule {
+    apply(system) {
+        const { color, elapsed, lifetime, liveCount } = system;
+        for (let i = 0; i < liveCount; i++) {
+            const remaining = 1 - elapsed[i] / lifetime[i];
+            const a = (Math.max(0, Math.min(1, remaining)) * 255) & 255;
+            color[i] = (color[i] & 0x00ffffff) | (a << 24);
+        }
+    }
+}
+```
+
+```ts
+// Before — direct particle creation in tests
+const particle = system.requestParticle();
+particle.position.set(10, 12);
+particle.tint = Color.red;
+system.emitParticle(particle);
+
+// After — direct slot manipulation
+const slot = system.spawn();
+system.posX[slot] = 10;
+system.posY[slot] = 12;
+system.color[slot] = Color.red.toRgba();
+system.lifetime[slot] = 1;
+system.scaleX[slot] = 1;
+system.scaleY[slot] = 1;
+```
+
+### Changed — `ParticleSystem` constructor: typed overloads (BREAKING)
+
+Source material (texture / atlas frames / spritesheet) lives in
+**positional arguments** — TypeScript overload signatures enforce mutual
+exclusivity at compile time so you can't pass nonsense combinations like
+texture-and-spritesheet-at-once. Capacity and the test-only `device`
+escape hatch live in the trailing options object.
+
+```ts
+// 0.7.x:
+new ParticleSystem(texture);
+new ParticleSystem(texture, 4096);
+
+// 0.8.0:
+new ParticleSystem();                                  // untextured (1×1 white), CPU/GPU auto-routed
+new ParticleSystem(spark);                             // simple textured particles
+new ParticleSystem(spark, { capacity: 8192 });         // explicit capacity
+new ParticleSystem(atlas, [r0, r1, r2]);               // multi-frame atlas
+new ParticleSystem(atlas, frames, { capacity: 8192 }); // atlas + capacity
+new ParticleSystem(sheet);                             // spritesheet shorthand
+new ParticleSystem(sheet, { capacity: 4096 });
+```
+
+The four overload signatures:
+
+```ts
+constructor(options?: ParticleSystemOptions);
+constructor(texture: Texture, options?: ParticleSystemOptions);
+constructor(texture: Texture, frames: ReadonlyArray<Rectangle>, options?: ParticleSystemOptions);
+constructor(spritesheet: Spritesheet, options?: ParticleSystemOptions);
+```
+
+Compile-time errors for illegal combinations:
+
+```ts
+new ParticleSystem(spark, sheet);                  // ✗ no overload matches
+new ParticleSystem(sheet, frames);                 // ✗ frames only valid with Texture
+new ParticleSystem({ frames });                    // ✗ frames isn't an option
+```
+
+**No `backend` option** — the renderer auto-discovers the active backend
+on the first `render(backend)` call. WebGPU → GPU compute path, WebGL2 →
+CPU path. Re-discovery on backend change (device-loss recovery).
+
+### Added — Optional texture + 1×1 white default
+
+When `texture` is omitted, the system uses a lazily-allocated 1×1
+opaque-white singleton. Particles render as solid color quads driven by
+the per-particle `color` channel. Useful for tech-demo magic effects,
+abstract VFX, performance benchmarks.
+
+### Added — Multi-frame atlas via `frames` / `spritesheet` options
+
+`frames: ReadonlyArray<Rectangle>` declares per-particle frame
+rectangles within the atlas texture. Each particle's `textureIndex[i]`
+selects which frame to render — `RateSpawn` /
+`BurstSpawn`'s `textureIndex: Distribution<number>` becomes the per-spawn
+frame chooser:
+
+```ts
+const system = new ParticleSystem({
+    texture: explosionAtlas,
+    frames: [
+        new Rectangle(0,   0, 32, 32),  // index 0 — flame core
+        new Rectangle(32,  0, 32, 32),  // index 1 — smoke ring
+        new Rectangle(64,  0, 32, 32),  // index 2 — ember
+    ],
+});
+
+system.addSpawnModule(new BurstSpawn({
+    schedule: [{ time: 0, count: 60 }],
+    velocity: ConeDirection.omni(120, 280),
+    textureIndex: new Range(0, 2),       // each spawn picks a random frame
+}));
+```
+
+`Spritesheet` integration via `spritesheet: sheet` extracts texture +
+frames in insertion order — convenient for atlas authors who already
+have a sheet from a TexturePacker / Aseprite export.
+
+UV resolution happens once per particle per frame (CPU pack in CPU mode,
+compute shader in GPU mode); the renderer reads pre-resolved UVs from
+the instance buffer — no shader-side frame-array lookup overhead.
+
+### Changed — Per-instance vertex layout: 24 → 40 bytes
+
+The renderer's per-instance buffer now carries `uvMin: vec2` and
+`uvMax: vec2` alongside the existing translation/scale/rotation/color
+fields. Lets a single batch render any mix of atlas frames per instance
+without indirection through a uniform array. Net cost: +67% bandwidth
+on the instance buffer (still trivial — ~10 MB/s at 60 fps with 16k
+particles).
+
+The previous design used a single `u_uvBounds` uniform that pinned
+every particle in a system to the same frame; the new layout is what
+makes per-particle atlas selection free.
+
+The system pre-allocates all SoA arrays at construction. Spawn modules
+that want to emit beyond capacity get `-1` from `spawn()` and should
+bail cleanly (the built-ins do).
+
+### Changed — slot allocation differs between CPU and GPU mode
+
+In CPU mode, `[0, liveCount)` is dense (forward-compaction at end of
+update). `spawn()` always returns the next sequential slot.
+
+In GPU mode, no compaction happens — readback would be required to
+move slots whose authoritative position lives in GPU memory. Instead:
+- Each particle has an `alive: Uint8Array` flag (1 = alive, 0 = dead).
+- `spawn()` finds the first dead slot via a round-robin hint pointer
+  (amortised O(1), worst case O(capacity)).
+- Expiry on CPU: `alive[i] = 0`, `lifetime[i] = -1` (sentinel).
+- The compute shader skips dead slots (`timing[idx].y < 0.0` → write
+  zero-scale instance and return).
+
+Custom modules iterating `[0, liveCount)` should check `system.alive[i]`
+in GPU mode if they care about ignoring dead slots; mutating dead slot
+data is harmless because the GPU shader skips them.
+
+### Added — `system.aliveCount`
+
+Returns the actual count of alive particles (slots with `alive[i] === 1`).
+In CPU mode this equals `liveCount`; in GPU mode it's `≤ liveCount`.
+Use for fragmentation diagnostics or UI counters.
+
+### Performance notes
+
+- Spawning + integrating + ColorOverLifetime/ScaleOverLifetime + drag
+  on 10k particles: previously ~5 ms CPU per frame; new SoA path on
+  CPU: ~0.5 ms (~10× speedup from eliminating per-particle object
+  indirection). New GPU path on WebGPU: ~0.05 ms (~100× speedup from
+  the previous OO baseline) — bound by the per-frame upload, not the
+  compute itself.
+- The crossover where GPU beats CPU sits around 1-3 k particles
+  depending on hardware. For sub-1k systems CPU is still slightly
+  faster (upload overhead dominates); the auto-router doesn't second-
+  guess this — opt out via `backend: undefined` if you want to force
+  CPU at low counts.
+- 100k+ particles render and simulate cleanly on WebGPU at 60 fps in
+  CI smoke tests; the bottleneck shifts from compute to texture
+  bandwidth at that scale.
+
+## [0.7.13] - 2026-05-07
+
+Major gamepad-input refactor. Replaces the `new Input(...)` +
+`inputManager.add(...)` pattern with a fluent listener API, splits the
+unified `GamepadChannel` enum into disjoint `GamepadButton` /
+`GamepadAxis` for type-safe button-vs-axis distinction, introduces
+always-4 stable gamepad slots with disconnect-aware listeners, and adds
+rumble, generic per-pad signals, slot-strategy configuration, aggregate
+signed stick channels, and Joy-Con-honest mappings.
+
+### Added — Listener API
+
+```ts
+// Per inputManager (manual unbind):
+app.input.onTrigger(GamepadButton.South, () => player.jump());
+app.input.onActive(GamepadAxis.LeftStickX, (v) => player.x += v * 5);
+app.input.onStart([Keyboard.Space, GamepadButton.South], () => fire());
+
+// Per gamepad (slot-aware, listener survives disconnect/reconnect):
+const pad = app.input.getGamepad(0);
+pad.onTrigger(GamepadButton.South, () => p1.jump());
+
+// Per scene (auto-disposed on scene unload):
+this.inputs.onTrigger(Keyboard.Escape, () => this.app.sceneManager.popScene());
+```
+
+Each method returns an `InputBinding` with `.unbind()` for manual
+lifecycle. Single channel or array of channels is accepted.
+
+### Added — Always-4 gamepad slots
+
+`InputManager.gamepads` is now a fixed
+`readonly [Gamepad, Gamepad, Gamepad, Gamepad]` tuple. Each `Gamepad`
+instance lives for the application's lifetime; check `pad.connected` for
+hardware presence. Listeners attached when a slot is empty automatically
+activate when a pad connects to that slot — no rebinding required.
+
+Convenience accessors on `app.input`:
+
+- `getGamepad(slot)` — readable single-slot accessor (equivalent to
+  `gamepads[slot]`).
+- `connectedGamepads: readonly Gamepad[]` — only the currently-attached
+  pads, in slot order.
+- `connectedGamepadCount: number`
+- `firstConnectedGamepad: Gamepad | null`
+- `hasGamepad: boolean`
+
+Per-pad: `pad.internalIndex` returns the browser's `Gamepad.index` for
+the attached hardware (or `null` when disconnected). Low-level escape
+hatch — prefer `pad.slot` for stable application-side identity.
+
+### Added — Slot strategy
+
+`new Application({ gamepadSlotStrategy: 'sticky' | 'compact' })` —
+default `'sticky'` (each pad keeps its slot through disconnects).
+`'compact'` shifts higher-numbered pads down to fill gaps after a
+disconnect (good for hot-seat couch coop where "the first N pads are
+the N players" is the desired semantic).
+
+In compact mode, the disconnect signal fires on the slot that *ended
+up* empty after the shift (not the slot the disconnected hardware
+originally occupied), keeping `pad.connected === false` consistent with
+the fired event. Slots that received a different physical pad through
+the shift dispatch a separate signal:
+
+- `pad.onPadReassigned: Signal<[fromSlot: 0 | 1 | 2 | 3]>`
+- `app.input.onAnyGamepadReassigned: Signal<[Gamepad, fromSlot]>`
+
+so player-binding code can re-resolve which `Gamepad` belongs to which
+player when slots renumber.
+
+### Added — Generic signals
+
+Per-pad:
+- `pad.onConnect: Signal<[]>`
+- `pad.onDisconnect: Signal<[]>`
+- `pad.onButtonDown: Signal<[GamepadButton, number]>`
+- `pad.onButtonUp: Signal<[GamepadButton, number]>`
+- `pad.onAxisChange: Signal<[GamepadAxis, number]>`
+
+Aggregate across all pads:
+- `inputManager.onAnyGamepadButtonDown: Signal<[Gamepad, GamepadButton, number]>`
+- `inputManager.onAnyGamepadButtonUp: Signal<[Gamepad, GamepadButton, number]>`
+- `inputManager.onAnyGamepadAxisChange: Signal<[Gamepad, GamepadAxis, number]>`
+
+### Added — Vibration
+
+```ts
+if (pad.canVibrate) {
+    await pad.vibrate({ duration: 200, weakMagnitude: 0.5, strongMagnitude: 1.0 });
+}
+pad.stopVibration();
+```
+
+Wraps the W3C `vibrationActuator.playEffect('dual-rumble')` API. Silent
+no-op on platforms without haptic support — use `pad.canVibrate` to
+detect availability for UI gating. Trigger-rumble (PS5 / Xbox Series
+adaptive triggers) is not exposed because browser support is currently
+Chrome-only and non-standard.
+
+### Added — Aggregate axis channels
+
+`GamepadAxis.LeftStickX`, `LeftStickY`, `RightStickX`, `RightStickY` —
+signed -1..1 values that consume the full bipolar range of the physical
+stick. Use these for stick-style movement input; the existing
+direction-split channels (`LeftStickLeft`, `LeftStickRight`, etc.)
+remain available for buttons-style 0..1 input.
+
+```ts
+// Stick-style — one binding per axis, signed value:
+this.inputs.onActive(GamepadAxis.LeftStickX, (x) => player.x += x * 5);
+
+// Buttons-style — separate bindings per direction, 0..1 each:
+this.inputs.onActive(GamepadAxis.LeftStickLeft,  (v) => player.x -= v * 5);
+this.inputs.onActive(GamepadAxis.LeftStickRight, (v) => player.x += v * 5);
+```
+
+### Added — `pad.hasChannel(channel)` capability check
+
+```ts
+if (pad.hasChannel(GamepadAxis.RightStickX)) {
+    pad.onActive(GamepadAxis.RightStickX, (v) => crosshair.x += v * 8);
+}
+```
+
+Returns `true` only when the pad's mapping declares the requested
+channel. Useful for graceful degradation on devices with limited
+hardware (e.g. single Joy-Con without a right stick).
+
+### Added — `Scene.inputs` proxy
+
+Bindings created via `this.inputs.onTrigger(...)` etc. are automatically
+disposed when the scene unloads. No manual cleanup tracking required.
+Internally tracks each binding and calls `.unbind()` in `Scene.destroy`.
+
+### Added — Steam Deck / Steam Virtual Gamepad / Valve fallback
+
+New `SteamDeckGamepadMapping` covers the raw HID layout reported by the
+Steam Deck (and likely future Valve hardware) when Steam Input is *not*
+intercepting the device. Indices follow the SDL_GameControllerDB Linux
+entry: face buttons at 3-6, D-pad at 16-19, paddles at 20-23, triggers
+as analog axes 8/9.
+
+Routing rules added to `builtInGamepadDefinitions`:
+
+| Browser ID | Mapping |
+|---|---|
+| `28de:1102`, `28de:1142` | `SteamControllerGamepadMapping` (existing, original Steam Controller raw) |
+| `28de:11ff` (Steam Virtual Gamepad — any controller via Steam Input) | `GenericDualAnalogGamepadMapping` (W3C standard Xbox emulation) |
+| `28de:1205` | `SteamDeckGamepadMapping` (raw Steam Deck) |
+| Vendor `28de` (anything else from Valve, e.g. future Steam Controller 2 raw) | `SteamDeckGamepadMapping` (best-effort fallback) |
+
+Enum: `GamepadMappingFamily.SteamDeck` added.
+
+### Added — Paddle2/3/4 buttons + Touchpad2X/Y axes
+
+The per-gamepad channel allocation is repartitioned into 32 button
+slots + 32 axis slots (was 21 / 22 with mid-block axis indices). 24
+named buttons (`South`-`Paddle4`) plus 8 reserved slots; 24 named axes
+(stick split + aggregate + dual-touchpad XY + 4 auxiliary bipolar) plus
+8 reserved slots. The reserved slots are accessible to custom mappings
+without colliding with future named additions.
+
+New named channels:
+
+- `GamepadButton.Paddle2`, `.Paddle3`, `.Paddle4` — extra paddles
+  / back buttons on Xbox Elite, PS5 Edge, Steam Deck (R4/L5/R5).
+- `GamepadAxis.Touchpad2X`, `.Touchpad2Y` — secondary touchpad on
+  dual-touchpad hardware (Steam Deck right pad).
+
+User code that previously read `GamepadButton.Paddle1` etc. is
+unaffected — channel **values** changed (offsets re-laid-out), but the
+namespace constants resolve to the new offsets transparently.
+
+### Added — JoyCon-honest mappings
+
+`JoyConLeftGamepadMapping` and `JoyConRightGamepadMapping` no longer
+inherit the full DualAnalog 16-axis layout. Each declares only channels
+that physically exist on the device (one stick mapped to LeftStick
+channels, four face buttons, SL/SR shoulders, Minus/Plus, Capture/Home,
+stick-click). Right-stick channels and other phantom hardware are
+intentionally absent — `pad.hasChannel(GamepadAxis.RightStickX)` returns
+`false` on a solo Joy-Con.
+
+### Changed — `app.inputManager` renamed to `app.input` (BREAKING)
+
+For consistency with `app.audio` and parity with the brevity of
+`app.tweens` / `app.loader` / `app.interaction`. All call sites that
+read or wrote `app.inputManager` need a one-token rename.
+
+```ts
+// Before:
+app.inputManager.onTrigger(GamepadButton.South, () => fire());
+app.inputManager.gamepads[0];
+
+// After:
+app.input.onTrigger(GamepadButton.South, () => fire());
+app.input.getGamepad(0);
+```
+
+### Fixed — Compact-mode disconnect ordering
+
+In `'compact'` slot strategy, `onDisconnect` previously fired on the
+slot the disconnected hardware originally occupied — *before* the
+compaction shift moved a different physical pad into that slot. User
+code observing the event would see `pad.connected === true` because
+the slot had been silently re-bound by the shift. Now compaction is
+applied first (silent), and `onDisconnect` fires on the slot that
+ended up empty (the trailing slot). Sticky behaviour is unchanged.
+
+### Changed — Channel naming (BREAKING)
+
+The unified `GamepadChannel` enum is split into two disjoint enums for
+nominal type safety:
+
+| Old | New (user-facing) | New (internal type) |
+|---|---|---|
+| `GamepadChannel.ButtonSouth` | `GamepadButton.South` | `GamepadButtonChannel.South` |
+| `GamepadChannel.ButtonEast` | `GamepadButton.East` | `GamepadButtonChannel.East` |
+| `GamepadChannel.LeftShoulder` | `GamepadButton.LeftShoulder` | `GamepadButtonChannel.LeftShoulder` |
+| `GamepadChannel.LeftStickLeft` | `GamepadAxis.LeftStickLeft` | `GamepadAxisChannel.LeftStickLeft` |
+| ... | ... | ... |
+
+User code references the namespace mirrors (`GamepadButton.X`,
+`GamepadAxis.Y`) — same `Pointer.X` / `Keyboard.Space` convention. Type
+checking now rejects passing a button channel where an axis is expected
+(and vice versa).
+
+### Changed — `GamepadControl` removed (BREAKING)
+
+`GamepadControl` is replaced by two concrete classes:
+
+- `GamepadButton` — wraps a button index + channel, with optional
+  `invert` and `threshold` options. `transformValue(v)` clamps to [0, 1].
+- `GamepadAxis` — wraps an axis index + channel, with optional `invert`,
+  `normalize`, `threshold`, and the new `bipolar` flag.
+  `transformValue(v)` clamps to [-1, +1] and applies the pipeline.
+
+Custom mappings construct these directly via `new GamepadButton(index, channel)`
+/ `new GamepadAxis(index, channel, options)` —
+`GamepadMapping.createControls()` is removed.
+
+### Changed — `Input` class replaced by `InputBinding` (BREAKING)
+
+`new Input(channel, { onTrigger: cb })` + `inputManager.add(input)` is
+gone. Use `inputManager.onTrigger(channel, cb)` / `pad.onTrigger(...)` /
+`scene.inputs.onTrigger(...)` instead. Returned `InputBinding` exposes
+the same `onStart`/`onActive`/`onStop`/`onTrigger` Signals plus a
+`.unbind()` method.
+
+### Changed — `inputManager.add/remove/clear/getGamepad/onGamepadUpdated` removed (BREAKING)
+
+The push-input-objects-into-the-manager API is fully replaced by the
+factory-method API. `getGamepad(index)` is replaced by direct
+`gamepads[slot]` indexing. `onGamepadUpdated` is replaced by
+`onAnyGamepadButtonDown` / `onAnyGamepadButtonUp` /
+`onAnyGamepadAxisChange` which carry semantic transition information
+instead of firing every frame.
+
+### Changed — `Gamepad` constructor signature (BREAKING)
+
+```ts
+// Before:
+new Gamepad(index, channels, mapping)
+new Gamepad(browserGamepad, channels, definition)
+
+// After (engine-internal — InputManager handles slot allocation):
+new Gamepad(slot, channels)
+// followed by pad._bind(browserGamepad, definition) on connect
+```
+
+User code does not construct `Gamepad` instances directly. Reads from
+`pad.info` / `pad.mapping` / `pad.connected` instead of the previous
+`pad.name` / `pad.label` / `pad.vendorId` / etc. inline accessors.
+
+### Migration guide
+
+```ts
+// Before:
+import { Input, GamepadChannel, Keyboard } from '@codexo/exojs';
+
+const jump = new Input(GamepadChannel.ButtonSouth, { onTrigger: () => player.jump() });
+app.input.add(jump);
+
+// After (any of three styles, depending on lifecycle):
+import { GamepadButton, Keyboard } from '@codexo/exojs';
+
+// Manual lifecycle
+const binding = app.input.onTrigger(GamepadButton.South, () => player.jump());
+binding.unbind();   // when done
+
+// Auto-disposed on scene unload
+this.inputs.onTrigger(GamepadButton.South, () => player.jump());
+
+// Pinned to a specific pad slot
+this.app.input.gamepads[0].onTrigger(GamepadButton.South, () => player.jump());
+```
+
+```ts
+// Stick movement — before:
+const moveLeft  = new Input(GamepadChannel.LeftStickLeft);
+const moveRight = new Input(GamepadChannel.LeftStickRight);
+app.input.add(moveLeft);
+app.input.add(moveRight);
+// per frame: const x = moveRight.value - moveLeft.value;
+
+// After (signed aggregate channel):
+this.inputs.onActive(GamepadAxis.LeftStickX, (x) => player.x += x * 5);
+```
+
+```ts
+// Custom mapping — before:
+import { GamepadMapping, GamepadChannel } from '@codexo/exojs';
+const buttons = GamepadMapping.createControls([
+    [0, GamepadChannel.ButtonSouth],
+    [1, GamepadChannel.ButtonEast],
+]);
+
+// After:
+import { GamepadButton, GamepadMapping, GamepadMappingFamily } from '@codexo/exojs';
+class MyMapping extends GamepadMapping {
+    public readonly family = GamepadMappingFamily.GenericDualAnalog;
+    public constructor() {
+        super(
+            [
+                new GamepadButton(0, GamepadButton.South),
+                new GamepadButton(1, GamepadButton.East),
+            ],
+            [],
+        );
+    }
+}
+```
+
 ## [0.7.12] - 2026-05-07
 
 API audit cleanup pass — implements collision-response computation that was