feat(input): drain gamepad hotplug queue + enriched event payloads (#610)

[apotema]

Closes #610.

What

Replaces the engine's fixed-slot gamepad availability scan with a queue drain over the core#18 GamepadEvent contract, and enriches the engine event payloads.

src/game.zig

• scanInputEvents now drains into a fixed [16]GamepadEvent stack buffer and emits one engine event per drained event (switch on ev.kind).
• Removed max_tracked_gamepads, the 4-slot cap, and the prev_gamepad_connected[4] edge tracker. Edge detection now belongs to the source.
• Comptime source selection via @hasDecl(InputImpl, "pollGamepadEvents") — probes the raw backend, not the InputInterface wrapper (whose method always exists and falls back to 0):
  • backend declares it → Self.Input.pollGamepadEvents(&buf)
  • backend does not → core.gamepad_source.pollEvents(&buf) + its init()/deinit() at Game init/deinit
  • never both — no double-source / duplicate events.
• Source init/deinit gated on uses_os_gamepad_source (!backend_polls_gamepads and gamepad_events_wanted), so they fold away for native-polling backends and event-less games.
• The whole drain block stays behind the existing comptime gamepad_events_wanted gate → zero-cost when no flow listens (and on the fallback path the OS source is then never polled).

src/root.zig

• Events.gamepad_connected now carries { id, name, name_len, guid, source_class, type_hint } with a nameSlice() helper. id is kept (first) for backward-compat — flows/hooks reading only .id still compile.
• name is stored inline ([63:0]u8 + name_len), not as a borrowed []const u8: engine events are copied into event_buffer and dispatched on a later frame, so a slice into the transient drain buffer would dangle.
• gamepad_disconnected unchanged ({ id }).

test/input_events_test.zig

• TestInput now declares pollGamepadEvents and injects GamepadEvents instead of toggling availability.
• Kept connect-once / disconnect / per-slot assertions; added: a multi-event single-drain test (uses slot 7 to prove the 4-slot cap is gone), an enriched-fields propagation test (name/guid/source_class/type_hint), and a fallback test using StubInput (no pollGamepadEvents) that exercises the gamepad_source branch + lifecycle.

Stacking

STACKED on labelle-core#19 (branch feat/gamepad-event-contract, core#18). This PR consumes core.gamepad.GamepadEvent, core.gamepad_source.{init,deinit,pollEvents}, core.GamepadSourceClass, and core.GamepadTypeHint.

build.zig.zon (and scene/build.zig.zon) pin labelle_core to the core#19 git ref — https://github.com/labelle-toolkit/labelle-core/archive/8fcf67641a1d6e021bc305ee62092944456f8f69.tar.gz (commit 8fcf676). This is required because CI clones core's main as a sibling, which does not yet contain the gamepad-event contract, so a ../labelle-core path pin fails to compile on CI. The pin bumps to a release tag once core#19 merges to main — see the TODO in both .zon files. Merge this PR after core#19 lands.

Verification

• zig build test (Zig 0.16.0, darwin) — green, 28/28 spec tests pass and every per-file test binary runs. Verified the new gamepad tests actually execute (temporarily flipped an assertion → observed the expected failure, then reverted).
• Both source paths type-check: the backend path via TestInput (declares pollGamepadEvents), the fallback path via StubInput (routes to core.gamepad_source, which is the unsupported stub on darwin → 0 events).

[cursor]

PR Summary

Medium Risk
Behavior change for all games using gamepad connect/disconnect flows (event timing and payload shape); depends on labelle-core#18 types and a pinned core ref until main merges.

Overview
Replaces the engine’s 4-slot gamepad availability diff with a per-tick drain of up to 16 core.GamepadEvents from a single source chosen at comptime: the raw input backend’s pollGamepadEvents when declared, otherwise core.gamepad_source (with init/deinit only when that fallback is needed and flows listen for gamepad events). prev_gamepad_connected is removed; connect/disconnect edges come from the queue, not engine-side polling.

engine__gamepad_connected now carries inline name, optional GUID, source_class, and type_hint (plus nameSlice()); id stays first for callers that only read the slot. gamepad_disconnected is unchanged.

Tests switch from toggling isGamepadAvailable to queuing drained events, add multi-slot and enriched-field coverage, and assert the StubInput → gamepad_source fallback compiles and runs lifecycle hooks.

^{Reviewed by Cursor Bugbot for commit c49c6e5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[gemini-code-assist]

Code Review

This pull request refactors the gamepad hotplug system to use an event-driven model instead of polling and diffing slot availability. It introduces compile-time selection between the active input backend's native event polling and a per-OS fallback source, and enriches the gamepad_connected event payload with metadata like name, GUID, source class, and type hint. The feedback recommends defensively capping the name slice length in nameSlice to prevent out-of-bounds panics, adding an assertion in the test helper queue to avoid out-of-bounds writes, and robustly handling partial drains in the test stub's pollGamepadEvents by shifting remaining events instead of clearing them unconditionally.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

To prevent potential out-of-bounds panics if name_len is corrupted or incorrectly reported by a backend, we should defensively cap the slice length to core.gamepad.NAME_CAPACITY.

        pub fn nameSlice(self: *const gamepad_connected) []const u8 {
            const len = @min(self.name_len, core.gamepad.NAME_CAPACITY);
            return self.name[0..len];
        }

[apotema]

Applied in 70c940c — nameSlice() now caps the length with @min(self.name_len, core.gamepad.NAME_CAPACITY). Valid defensive bound since name_len is backend-reported.

[gemini-code-assist]

To prevent out-of-bounds writes and provide a clear failure message if too many events are queued in tests, we should assert that pending_len is less than pending_events.len.

    fn queue(ev: core.GamepadEvent) void {
        std.debug.assert(pending_len < pending_events.len);
        pending_events[pending_len] = ev;
        pending_len += 1;
    }

[apotema]

Applied in 70c940c — added std.debug.assert(pending_len < pending_events.len) to queue().

[gemini-code-assist]

If out.len is smaller than pending_len, the remaining events are currently discarded because pending_len is unconditionally reset to 0. To make the test stub robust against different drain capacities, we should shift any remaining events and decrement pending_len accordingly.

    pub fn pollGamepadEvents(out: []core.GamepadEvent) usize {
        const n = @min(out.len, pending_len);
        for (0..n) |i| out[i] = pending_events[i];
        if (n < pending_len) {
            std.mem.copyForwards(core.GamepadEvent, pending_events[0..(pending_len - n)], pending_events[n..pending_len]);
            pending_len -= n;
        } else {
            pending_len = 0;
        }
        return n;
    }

[apotema]

Applied in 70c940c — pollGamepadEvents() now shifts the undrained tail with copyForwards and decrements pending_len when out.len < pending_len, so it behaves like a real FIFO backend instead of dropping events.