@realnation/builder-shared-sdk 2.5.1 → 2.6.0

package/dist/gamepad/controls.js

@@ -0,0 +1,109 @@
+/**
+ * The platform's vocabulary of wheel controls.
+ *
+ * These names describe a *role* on a racing wheel, never the glyph printed on
+ * one particular device. A second wheel model maps its own axes and buttons
+ * onto the same names, so the Builder's Key Event Code dropdown never has to
+ * change when hardware does.
+ *
+ * Each control owns a code in the 1001+ range, deliberately outside the
+ * keyboard keyCode space. The runner synthesises keyboard events carrying
+ * these codes so that every element which already binds a Key Event Code works
+ * with a wheel without any module change. The stored value is the number: the
+ * English label is display only and can be reworded later.
+ */
+/** Continuous controls. The wheel reports a direction as two opposite controls. */
+export const AXIS_CONTROLS = ['wheel-left', 'wheel-right', 'throttle', 'brake', 'clutch'];
+/**
+ * Button roles. Named after the standard gamepad layout so a second model can
+ * be mapped by position rather than by the glyph it happens to print.
+ * `aux-1..4` absorbs whatever a device has that does not fit the roles above.
+ */
+export const BUTTON_CONTROLS = [
+    'start',
+    'select',
+    'home',
+    'paddle-left',
+    'paddle-right',
+    'dpad-up',
+    'dpad-down',
+    'dpad-left',
+    'dpad-right',
+    'action-1',
+    'action-2',
+    'action-3',
+    'action-4',
+    'shoulder-left',
+    'shoulder-right',
+    'aux-1',
+    'aux-2',
+    'aux-3',
+    'aux-4',
+];
+export const CONTROL_NAMES = [...AXIS_CONTROLS, ...BUTTON_CONTROLS];
+/**
+ * Axis controls take 1001-1010, buttons 1011 onwards, with gaps left so a later
+ * addition in one group never renumbers the other. Codes are persisted in
+ * campaign data: once shipped, a code may never be reassigned to a different
+ * control.
+ */
+const AXIS_BASE = 1001;
+const BUTTON_BASE = 1011;
+const LABELS = {
+    'wheel-left': 'Wheel Left',
+    'wheel-right': 'Wheel Right',
+    throttle: 'Throttle',
+    brake: 'Brake',
+    clutch: 'Clutch',
+    start: 'Wheel Start',
+    select: 'Wheel Select',
+    home: 'Wheel Home',
+    'paddle-left': 'Paddle Left',
+    'paddle-right': 'Paddle Right',
+    'dpad-up': 'D-pad Up',
+    'dpad-down': 'D-pad Down',
+    'dpad-left': 'D-pad Left',
+    'dpad-right': 'D-pad Right',
+    'action-1': 'Action 1',
+    'action-2': 'Action 2',
+    'action-3': 'Action 3',
+    'action-4': 'Action 4',
+    'shoulder-left': 'Shoulder Left',
+    'shoulder-right': 'Shoulder Right',
+    'aux-1': 'Aux 1',
+    'aux-2': 'Aux 2',
+    'aux-3': 'Aux 3',
+    'aux-4': 'Aux 4',
+};
+export const CONTROLS = [
+    ...AXIS_CONTROLS.map((name, index) => ({ name, code: AXIS_BASE + index, label: LABELS[name] })),
+    ...BUTTON_CONTROLS.map((name, index) => ({
+        name,
+        code: BUTTON_BASE + index,
+        label: LABELS[name],
+    })),
+];
+const BY_NAME = new Map(CONTROLS.map((c) => [c.name, c]));
+const BY_CODE = new Map(CONTROLS.map((c) => [c.code, c]));
+export function controlByName(name) {
+    const found = BY_NAME.get(name);
+    if (!found)
+        throw new Error(`Unknown control: ${name}`);
+    return found;
+}
+export function controlByCode(code) {
+    return BY_CODE.get(code) ?? null;
+}
+export function controlCode(name) {
+    return controlByName(name).code;
+}
+/**
+ * True for codes this module owns. The runner uses it to keep synthetic wheel
+ * events apart from real keyboard ones.
+ */
+export function isControlCode(code) {
+    return BY_CODE.has(code);
+}
+export function isAxisControl(name) {
+    return AXIS_CONTROLS.includes(name);
+}

package/dist/gamepad/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * QikSense Gamepad SDK — racing wheels and pedals for web experiences.
+ *
+ * A module subscribes to named controls (`wheel-left`, `throttle`, `start`)
+ * and never touches `navigator.getGamepads()`. Device layout, normalisation
+ * and the press/release decision all live below this line, so a second wheel
+ * model is a profile entry rather than a change in every game.
+ *
+ * Framework-free by construction, like `/runtime`: no Vue import anywhere in
+ * this directory, so a Canvas game or a node test pulls in no reactivity.
+ *
+ * The host creates the session; modules receive it. See README.md.
+ */
+export { createGamepad, GamepadSession, explainGamepadMiss } from './session.js';
+export type { AxesUpdate, CreateGamepadOptions, GamepadMissReason, GamepadState, GamepadStatus, Unsubscribe, } from './session.js';
+export { AXIS_CONTROLS, BUTTON_CONTROLS, CONTROLS, CONTROL_NAMES, controlByCode, controlByName, controlCode, isAxisControl, isControlCode, } from './controls.js';
+export type { AxisControl, ButtonControl, ControlDefinition, ControlName } from './controls.js';
+export { DEFAULT_THRESHOLDS, releaseAll, resolveThresholds, stepSignals } from './signals.js';
+export type { ControlEvent, ControlReading, SignalState, Thresholds } from './signals.js';
+export { PROFILES, matchProfile, selectDevice } from './profiles.js';
+export type { GamepadProfile, ProfileLookup, ProfileMatch } from './profiles.js';
+export { decodeHat, deviceKey, normalizeBinding, parseDeviceIdentity, readBinding } from './normalize.js';
+export type { AxisBinding, Binding, ButtonBinding, DeviceIdentity, GamepadLike, HatBinding, } from './normalize.js';
+export { LiveGamepadSource, MockGamepadSource, mockPad } from './source.js';
+export type { GamepadSource, MockGamepadOptions } from './source.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/gamepad/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gamepad/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACjF,YAAY,EACV,UAAU,EACV,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,WAAW,GACZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,aAAa,EACb,eAAe,EACf,QAAQ,EACR,aAAa,EACb,aAAa,EACb,aAAa,EACb,WAAW,EACX,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEhG,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9F,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACrE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEjF,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1G,YAAY,EACV,WAAW,EACX,OAAO,EACP,aAAa,EACb,cAAc,EACd,WAAW,EACX,UAAU,GACX,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC5E,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/dist/gamepad/index.js

@@ -0,0 +1,19 @@
+/**
+ * QikSense Gamepad SDK — racing wheels and pedals for web experiences.
+ *
+ * A module subscribes to named controls (`wheel-left`, `throttle`, `start`)
+ * and never touches `navigator.getGamepads()`. Device layout, normalisation
+ * and the press/release decision all live below this line, so a second wheel
+ * model is a profile entry rather than a change in every game.
+ *
+ * Framework-free by construction, like `/runtime`: no Vue import anywhere in
+ * this directory, so a Canvas game or a node test pulls in no reactivity.
+ *
+ * The host creates the session; modules receive it. See README.md.
+ */
+export { createGamepad, GamepadSession, explainGamepadMiss } from './session.js';
+export { AXIS_CONTROLS, BUTTON_CONTROLS, CONTROLS, CONTROL_NAMES, controlByCode, controlByName, controlCode, isAxisControl, isControlCode, } from './controls.js';
+export { DEFAULT_THRESHOLDS, releaseAll, resolveThresholds, stepSignals } from './signals.js';
+export { PROFILES, matchProfile, selectDevice } from './profiles.js';
+export { decodeHat, deviceKey, normalizeBinding, parseDeviceIdentity, readBinding } from './normalize.js';
+export { LiveGamepadSource, MockGamepadSource, mockPad } from './source.js';

package/dist/gamepad/normalize.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Turning what a device reports into numbers a game can use.
+ *
+ * Ported from the racing-game prototype's `src/input/gamepad.ts`, which had
+ * already been proven against a real wheel and carried its own unit tests. The
+ * substance is unchanged; what changed is where the binding comes from. The
+ * prototype asked every player to calibrate on the spot, so its bindings were
+ * discovered at runtime. Here they come from a device profile shipped with the
+ * SDK, because a kiosk operator should never have to calibrate anything.
+ *
+ * Pure functions over plain data: no browser API, no state, no framework.
+ */
+/** Where one control's reading comes from on the device. */
+export type BindingSource = 'axis' | 'button';
+export interface AxisBinding {
+    source: 'axis';
+    /** Index into `Gamepad.axes`. */
+    index: number;
+    /** The reading when nothing is touched. Not always 0: pedals often rest at -1. */
+    rest: number;
+    /** The reading at full deflection in the direction this binding measures. */
+    active: number;
+    /**
+     * Present only for a two-sided axis such as steering, where one axis carries
+     * both directions. Lets an asymmetric wheel normalise correctly on each side.
+     */
+    minimum?: number;
+    maximum?: number;
+    /** Readings within this much of `rest` count as untouched. */
+    deadzone: number;
+}
+export interface ButtonBinding {
+    source: 'button';
+    /** Index into `Gamepad.buttons`. */
+    index: number;
+    rest: number;
+    active: number;
+    deadzone: number;
+}
+export type Binding = AxisBinding | ButtonBinding;
+/**
+ * A D-pad reported as one axis instead of four buttons.
+ *
+ * Browsers hand a HID hat switch to the page as a single axis carrying eight
+ * directions plus a released state, so it cannot be expressed as a button
+ * index. Confirmed on the PS3/PC Wheel on 2026-09-21: axis 9 sits at 3.2857
+ * untouched and sweeps down to -1.
+ */
+export interface HatBinding {
+    source: 'hat';
+    /** Index into `Gamepad.axes`. */
+    index: number;
+    /**
+     * The reading when no direction is held. Usually out of the -1..1 range
+     * (3.2857 is the common one). Left unset, any out-of-range value counts as
+     * released, which covers every device seen so far.
+     */
+    released?: number;
+}
+/**
+ * Decodes a hat axis into the four directions.
+ *
+ * Diagonals set both neighbours, which is what a game wants: holding up-right
+ * on a menu should move up and right, not neither. The released state is the
+ * value falling outside -1..1, so a profile only needs to name it when a
+ * device is unusual.
+ */
+export declare function decodeHat(value: number, released?: number): {
+    up: boolean;
+    right: boolean;
+    down: boolean;
+    left: boolean;
+};
+/** The subset of `Gamepad` this module reads. Keeps tests free of DOM types. */
+export interface GamepadLike {
+    id: string;
+    index: number;
+    connected: boolean;
+    mapping?: string;
+    axes: readonly number[];
+    buttons: readonly {
+        pressed: boolean;
+        value: number;
+    }[];
+}
+/**
+ * Maps a raw reading onto 0..1, or -1..1 for a two-sided axis.
+ *
+ * A two-sided axis is normalised against each side's own travel, so a wheel
+ * whose centre does not sit exactly halfway still reaches 1 and -1 at full
+ * lock. Every other binding is one-sided and returns 0..1.
+ */
+export declare function normalizeBinding(binding: Binding, raw: number): number;
+/** Reads one binding off a device snapshot. Absent indices read as untouched. */
+export declare function readBinding(binding: Binding, pad: GamepadLike): number;
+/**
+ * A device fingerprint: the id plus its shape.
+ *
+ * The counts matter because vendor and product ids are not unique in practice.
+ * Generic controller boards get resold under many names, so two different
+ * wheels can report the same pair of numbers while exposing different axes.
+ */
+export declare function deviceKey(pad: GamepadLike): string;
+export interface DeviceIdentity {
+    /** Vendor id as lowercase hex, e.g. `2563`. Null when the id carries none. */
+    vendor: string | null;
+    product: string | null;
+    /** The id with the vendor/product part stripped, for display. */
+    name: string;
+}
+/**
+ * Pulls vendor and product out of a gamepad id string.
+ *
+ * Browsers disagree on the format. Chrome writes
+ * `PS3/PC Wheel (Vendor: 2563 Product: 0906)`, Firefox writes
+ * `2563-0906-PS3/PC Wheel`. Both are recognised so one profile covers both,
+ * and an unparseable id degrades to a name with no numbers rather than
+ * throwing: matching then simply fails and the operator sees the raw id.
+ */
+export declare function parseDeviceIdentity(id: string): DeviceIdentity;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/gamepad/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/gamepad/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE9C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,QAAQ,CAAC;IACjB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,aAAa,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,KAAK,CAAC;IACd,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAKD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,GAChB;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAc/D;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,SAAS;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACzD;AAOD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAiBtE;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CAMtE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAElD;AAED,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,CAoB9D"}

package/dist/gamepad/normalize.js

@@ -0,0 +1,110 @@
+/**
+ * Turning what a device reports into numbers a game can use.
+ *
+ * Ported from the racing-game prototype's `src/input/gamepad.ts`, which had
+ * already been proven against a real wheel and carried its own unit tests. The
+ * substance is unchanged; what changed is where the binding comes from. The
+ * prototype asked every player to calibrate on the spot, so its bindings were
+ * discovered at runtime. Here they come from a device profile shipped with the
+ * SDK, because a kiosk operator should never have to calibrate anything.
+ *
+ * Pure functions over plain data: no browser API, no state, no framework.
+ */
+/** The eight directions are -1 plus this step, so one step is an eighth turn. */
+const HAT_STEP = 2 / 7;
+/**
+ * Decodes a hat axis into the four directions.
+ *
+ * Diagonals set both neighbours, which is what a game wants: holding up-right
+ * on a menu should move up and right, not neither. The released state is the
+ * value falling outside -1..1, so a profile only needs to name it when a
+ * device is unusual.
+ */
+export function decodeHat(value, released) {
+    const none = { up: false, right: false, down: false, left: false };
+    if (!Number.isFinite(value))
+        return none;
+    if (released !== undefined && Math.abs(value - released) < 0.05)
+        return none;
+    if (Math.abs(value) > 1.05)
+        return none;
+    const step = Math.round((value + 1) / HAT_STEP);
+    if (step < 0 || step > 7)
+        return none;
+    return {
+        up: step === 7 || step === 0 || step === 1,
+        right: step >= 1 && step <= 3,
+        down: step >= 3 && step <= 5,
+        left: step >= 5 && step <= 7,
+    };
+}
+const clamp01 = (value) => Math.max(0, Math.min(1, value));
+/** Guards the divisions below: a zero span would otherwise produce Infinity. */
+const nonZero = (value) => (Math.abs(value) < 0.0001 ? 1 : value);
+/**
+ * Maps a raw reading onto 0..1, or -1..1 for a two-sided axis.
+ *
+ * A two-sided axis is normalised against each side's own travel, so a wheel
+ * whose centre does not sit exactly halfway still reaches 1 and -1 at full
+ * lock. Every other binding is one-sided and returns 0..1.
+ */
+export function normalizeBinding(binding, raw) {
+    if (binding.source === 'button') {
+        return clamp01((raw - binding.rest) / nonZero(binding.active - binding.rest));
+    }
+    if (binding.minimum !== undefined && binding.maximum !== undefined) {
+        const delta = raw - binding.rest;
+        if (Math.abs(delta) <= binding.deadzone)
+            return 0;
+        return delta < 0
+            ? -clamp01(Math.abs(delta) / Math.max(binding.deadzone, Math.abs(binding.minimum - binding.rest)))
+            : clamp01(delta / Math.max(binding.deadzone, binding.maximum - binding.rest));
+    }
+    const amount = (raw - binding.rest) / nonZero(binding.active - binding.rest);
+    return clamp01(Math.abs(raw - binding.rest) <= binding.deadzone ? 0 : amount);
+}
+/** Reads one binding off a device snapshot. Absent indices read as untouched. */
+export function readBinding(binding, pad) {
+    const raw = binding.source === 'axis'
+        ? (pad.axes[binding.index] ?? binding.rest)
+        : (pad.buttons[binding.index]?.value ?? binding.rest);
+    return normalizeBinding(binding, raw);
+}
+/**
+ * A device fingerprint: the id plus its shape.
+ *
+ * The counts matter because vendor and product ids are not unique in practice.
+ * Generic controller boards get resold under many names, so two different
+ * wheels can report the same pair of numbers while exposing different axes.
+ */
+export function deviceKey(pad) {
+    return `${pad.id}|a${pad.axes.length}|b${pad.buttons.length}`;
+}
+/**
+ * Pulls vendor and product out of a gamepad id string.
+ *
+ * Browsers disagree on the format. Chrome writes
+ * `PS3/PC Wheel (Vendor: 2563 Product: 0906)`, Firefox writes
+ * `2563-0906-PS3/PC Wheel`. Both are recognised so one profile covers both,
+ * and an unparseable id degrades to a name with no numbers rather than
+ * throwing: matching then simply fails and the operator sees the raw id.
+ */
+export function parseDeviceIdentity(id) {
+    const chrome = id.match(/vendor:\s*([0-9a-f]{4})\s+product:\s*([0-9a-f]{4})/i);
+    if (chrome) {
+        return {
+            vendor: chrome[1].toLowerCase(),
+            product: chrome[2].toLowerCase(),
+            name: id.replace(/\s*\((?:vendor|Vendor).*?\)\s*/, '').trim() || id,
+        };
+    }
+    const firefox = id.match(/^([0-9a-f]{4})-([0-9a-f]{4})-(.*)$/i);
+    if (firefox) {
+        return {
+            vendor: firefox[1].toLowerCase(),
+            product: firefox[2].toLowerCase(),
+            name: firefox[3].trim(),
+        };
+    }
+    return { vendor: null, product: null, name: id };
+}

package/dist/gamepad/profiles.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Device profiles: what each wheel model's axes and buttons mean.
+ *
+ * A profile replaces on-site calibration. The operator plugs a wheel in and
+ * plays; nobody walks through a wizard, and nothing is stored in the browser
+ * that a cleared cache could lose. The cost is that a new model needs a
+ * profile added here and the SDK republished, which is the trade the team
+ * accepted: wheel models change rarely, kiosks are set up often.
+ *
+ * Recording a new model: open `examples/gamepad/reader.html`, run through the
+ * steps with the device, and paste the JSON it produces into a new entry.
+ */
+import type { AxisBinding, Binding, ButtonBinding, GamepadLike, HatBinding } from './normalize.js';
+import type { AxisControl, ButtonControl } from './controls.js';
+import type { Thresholds } from './signals.js';
+export interface ProfileMatch {
+    vendor: string;
+    product: string;
+    /**
+     * Required shape. Vendor and product ids are not reliably unique, so a
+     * profile only claims a device whose axis and button counts also line up.
+     * A mismatch is reported as an unknown device rather than silently driving
+     * the wrong axes.
+     */
+    axes: number;
+    buttons: number;
+}
+export interface GamepadProfile {
+    /** Stable identifier used in logs and support conversations. */
+    id: string;
+    /** Human readable model name. */
+    name: string;
+    match: ProfileMatch;
+    /** Steering is one two-sided axis: negative is left, positive is right. */
+    steering: AxisBinding;
+    throttle?: Binding;
+    brake?: Binding;
+    clutch?: Binding;
+    /** Button role to device button index. Roles a device lacks are left out. */
+    buttons: Partial<Record<ButtonControl, number>>;
+    /** Set when the D-pad arrives as a hat axis rather than as four buttons. */
+    dpad?: HatBinding;
+    /** Per-model overrides for the press/release lines. Merged over defaults. */
+    thresholds?: Partial<Thresholds>;
+    /** Set when the model is known to expose a working vibration actuator. */
+    vibration?: boolean;
+}
+/**
+ * Registry of known wheels.
+ *
+ * Entries land here only after a real device has been recorded with
+ * `examples/gamepad/reader.html`. A guessed profile is worse than none: an
+ * unknown device tells the operator plainly that the model is unsupported,
+ * whereas a wrong profile drives the wrong axes and looks like a broken game.
+ */
+export declare const PROFILES: readonly GamepadProfile[];
+export interface ProfileLookup {
+    profile: GamepadProfile | null;
+    /** The device id as reported, so an unmatched device can be named in the UI. */
+    deviceId: string;
+    vendor: string | null;
+    product: string | null;
+}
+/** Finds the profile for one device snapshot. */
+export declare function matchProfile(pad: GamepadLike, profiles?: readonly GamepadProfile[]): ProfileLookup;
+/**
+ * Picks the device to drive from everything currently connected.
+ *
+ * A kiosk has one wheel, so the first device with a profile wins. When none
+ * matches, the first connected device is still returned so the operator can be
+ * told which model was seen and rejected.
+ */
+export declare function selectDevice(pads: readonly (GamepadLike | null)[], profiles?: readonly GamepadProfile[]): {
+    pad: GamepadLike;
+    lookup: ProfileLookup;
+} | null;
+/** The binding for one axis control, or null when the model lacks that pedal. */
+export declare function axisBinding(profile: GamepadProfile, control: AxisControl): Binding | null;
+/** Synthesises a binding for a mapped button so it reads like any other control. */
+export declare function buttonBinding(profile: GamepadProfile, control: ButtonControl): ButtonBinding | null;
+//# sourceMappingURL=profiles.d.ts.map

package/dist/gamepad/profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/gamepad/profiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEnG,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,YAAY,CAAC;IACpB,2EAA2E;IAC3E,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,4EAA4E;IAC5E,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IACjC,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AA0CD;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,cAAc,EAAmB,CAAC;AAElE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,iDAAiD;AACjD,wBAAgB,YAAY,CAC1B,GAAG,EAAE,WAAW,EAChB,QAAQ,GAAE,SAAS,cAAc,EAAa,GAC7C,aAAa,CAYf;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAAE,EACrC,QAAQ,GAAE,SAAS,cAAc,EAAa,GAC7C;IAAE,GAAG,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GAAG,IAAI,CASpD;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,GAAG,IAAI,CAczF;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa,GAAG,aAAa,GAAG,IAAI,CAInG"}

package/dist/gamepad/profiles.js

@@ -0,0 +1,99 @@
+import { parseDeviceIdentity } from './normalize.js';
+/**
+ * The first wheel the platform supports, recorded 2026-09-21 and 09-22.
+ *
+ * Two things about it are worth knowing because they are not obvious and both
+ * cost a round of debugging:
+ *
+ * ① **The two pedals share one axis.** Accelerator pushes axis 1 negative,
+ *    brake pushes it positive, and untouched it rests near zero. That means
+ *    pressing both at once cancels out; the hardware cannot report them
+ *    separately and no amount of code can recover it.
+ * ② **The D-pad is a hat axis**, not four buttons (see `HatBinding`).
+ *
+ * Buttons 10 and 11 are declared by the device but have no physical control
+ * behind them, so they are deliberately unmapped.
+ */
+const PS3_PC_WHEEL = {
+    id: 'ps3-pc-wheel-2563-0906',
+    name: 'PS3/PC Racing Wheel',
+    match: { vendor: '2563', product: '0906', axes: 10, buttons: 12 },
+    // 静止 0.004 而不是 0：转向轴的中位本来就偏一点，死区要盖得住
+    steering: { source: 'axis', index: 0, rest: 0.004, active: 1, minimum: -1, maximum: 1, deadzone: 0.06 },
+    throttle: { source: 'axis', index: 1, rest: 0.004, active: -1, deadzone: 0.06 },
+    brake: { source: 'axis', index: 1, rest: 0.004, active: 1, deadzone: 0.06 },
+    dpad: { source: 'hat', index: 9, released: 3.2857 },
+    buttons: {
+        // 四个符号键按位置对应，不按符号本身：换一只贴 ABXY 的方向盘也映射到同一套名字
+        'action-1': 2, // X，下
+        'action-2': 1, // 圆圈，右
+        'action-3': 3, // 方形，左
+        'action-4': 0, // 三角，上
+        'shoulder-left': 4, // L1
+        'shoulder-right': 5, // R1
+        // 换挡拨片与 L2 / R2 是同一对物理键（实测两次都落在同一个下标）
+        'paddle-left': 6, // L2 = Gear Down
+        'paddle-right': 7, // R2 = Gear Up
+        select: 8,
+        start: 9,
+    },
+};
+/**
+ * Registry of known wheels.
+ *
+ * Entries land here only after a real device has been recorded with
+ * `examples/gamepad/reader.html`. A guessed profile is worse than none: an
+ * unknown device tells the operator plainly that the model is unsupported,
+ * whereas a wrong profile drives the wrong axes and looks like a broken game.
+ */
+export const PROFILES = [PS3_PC_WHEEL];
+/** Finds the profile for one device snapshot. */
+export function matchProfile(pad, profiles = PROFILES) {
+    const identity = parseDeviceIdentity(pad.id);
+    const profile = profiles.find((candidate) => candidate.match.vendor.toLowerCase() === identity.vendor &&
+        candidate.match.product.toLowerCase() === identity.product &&
+        candidate.match.axes === pad.axes.length &&
+        candidate.match.buttons === pad.buttons.length) ?? null;
+    return { profile, deviceId: pad.id, vendor: identity.vendor, product: identity.product };
+}
+/**
+ * Picks the device to drive from everything currently connected.
+ *
+ * A kiosk has one wheel, so the first device with a profile wins. When none
+ * matches, the first connected device is still returned so the operator can be
+ * told which model was seen and rejected.
+ */
+export function selectDevice(pads, profiles = PROFILES) {
+    const connected = pads.filter((pad) => Boolean(pad?.connected));
+    if (!connected.length)
+        return null;
+    for (const pad of connected) {
+        const lookup = matchProfile(pad, profiles);
+        if (lookup.profile)
+            return { pad, lookup };
+    }
+    return { pad: connected[0], lookup: matchProfile(connected[0], profiles) };
+}
+/** The binding for one axis control, or null when the model lacks that pedal. */
+export function axisBinding(profile, control) {
+    switch (control) {
+        case 'wheel-left':
+        case 'wheel-right':
+            return profile.steering;
+        case 'throttle':
+            return profile.throttle ?? null;
+        case 'brake':
+            return profile.brake ?? null;
+        case 'clutch':
+            return profile.clutch ?? null;
+        default:
+            return null;
+    }
+}
+/** Synthesises a binding for a mapped button so it reads like any other control. */
+export function buttonBinding(profile, control) {
+    const index = profile.buttons[control];
+    if (index === undefined)
+        return null;
+    return { source: 'button', index, rest: 0, active: 1, deadzone: 0.04 };
+}