@wildride/pad-kit

The gamepad kernel, extracted from game-kube.

Everything a browser app needs to turn navigator.getGamepads() into a mapping it can trust: the stored profile schema, the capture engine that builds one, the decode that applies it, the resolution gates that refuse to apply a wrong one, the glyph sets that label a button the way the pad in the user's hands does, and the diagram geometry that draws it.

The kernel is dependency-free — no framework, no HTTP client, no DOM. A synthetic { id, mapping, buttons: [{pressed, value}], axes: [] } object literal is a valid "Gamepad" to every function in it. Three optional Vue 3 components ship alongside for the presentation layer; vue is an optional peer dependency, so a pure node consumer (a server-side profile validator, the geometry checker) never resolves it.

Install

npm install @wildride/pad-kit

import { archetypeSteps, SCHEMA_VERSION } from '@wildride/pad-kit/schema';
import { applyProfile, profileToRemap }   from '@wildride/pad-kit/apply';
import { restSnapshot, detectInput }      from '@wildride/pad-kit/capture';
import { createResolver }                 from '@wildride/pad-kit/resolver';
import { resolveGlyph }                   from '@wildride/pad-kit/glyphs';
import { CONSOLE_SHAPES }                 from '@wildride/pad-kit/padShapes';
import { hitTest, moveControl }           from '@wildride/pad-kit/padGeometry';
import { pickCandidate }                  from '@wildride/pad-kit/lrud';

import { PadDiagram, PadButtonGlyph, GlyphChip, providePadGlyphContext }
  from '@wildride/pad-kit/components';
import '@wildride/pad-kit/tokens.css';

The root entry (import * as padKit from '@wildride/pad-kit') hands back one namespace per module rather than a flat barrel, because capture.js and resolver.js deliberately each carry their own parseVendorProduct / isXInputWrapper and a flat re-export would make those ambiguous.

What's in it

| Subpath | What | |---|---| | ./schema | SCHEMA_VERSION, the semantic BUTTONS/STICK_AXES/TRIGGERS vocabulary, CONTROLLER_TYPE, the ARCHETYPES step lists, platformBucket(), profileId() | | ./apply | applyProfile() (live pad → semantic names), profileToRemap() (semantic → wire flags), hatDirections, triggerValue, stickValue, BUTTON_FLAGS | | ./capture | restSnapshot, detectInput, selectForStep, resolveCapture, buildProfile, verifyProfile, parseVendorProduct, isXInputWrapper — the registration wizard's engine, DOM-free | | ./resolver | createResolver({ fetchProfile, saveProfile }) plus the stateless gates (gateProfile, REJECT, mergeResolvedLayers, resolveProfileFrom, buildRemapTable) | | ./glyphs | GLYPH_SETS, resolveGlyph(), diagramLabels(), sniffGlyphSet(), NAV_TO_SEMANTIC, PS_CLASS, ARROW_POINTS | | ./padShapes | PHYSICAL_SHAPES (per archetype), CONSOLE_SHAPES (per console family), PAD_SCALE, physicalShape(), consoleShape(), normalizePadLayout() | | ./padGeometry | Pure editor math over a shape: hitTest, moveControl, setControlField, snap, coverageDiff | | ./lrud | pickCandidate() / isDegenerate() — geometric spatial navigation (BBC lrud-spatial / W3C spatial-navigation model). DOM-free: callers pass DOMRect-likes | | ./components | PadDiagram, GlyphChip, PadButtonGlyph, providePadGlyphContext | | ./tokens.css | Default values for the CSS custom properties those components read | | ./tools/pad-geometry-check.mjs | The mechanical geometry checker, as a CLI and as importable pure rules | | ./testkit/* | padModel.mjs / padShim.mjs — a fake gamepad and the Playwright init-script builder that installs it in a page |

What's deliberately NOT in it

| Stayed in game-kube | Why | |---|---| | consoleFit.js + consoleFit.json | The libretro/RetroPad fit model: which console family a core presents, how a physical pad trades onto it, which control is unreachable. That is emulator-frontend domain knowledge, not gamepad knowledge — a non-emulator consumer of this kit would carry a 30KB table it can never use. It reads padShapes and glyphs from here; the dependency points the right way. | | consoleRemap.js | Same reason — it is the remap layer over the fit model. | | internal/gamepaddb (Go) | Server-side profile storage. The kit is the browser half. | | The wizard/panel app surfaces (GamepadCaptureStep.vue, ConsoleFitPanel.vue, PadLayoutPanel.vue, …) | Product UI: routing, stores, notifications, the app's own layout. They compose the kit; they are not part of it. |

PadDiagram / GlyphChip / PadButtonGlyph came across because they are pure presentation over kit data — they read no store, fetch nothing, and route nowhere.

The resolver's injection API

resolver.js is the one module that used to reach for the host app. In game-kube it imported apiRequest/getAuthToken from the app's api client and the URL from the app's endpoint table — two touchpoints, both about where the profile table comes from. The kit takes them as injected functions, so the gates ship with no transport opinion:

import { createResolver } from '@wildride/pad-kit/resolver';

export const resolver = createResolver({
  // () => Promise<body|null>. Resolve the raw GET /gamepads/resolved body:
  //   { schemaVersion, profiles: [...], library: [...] }
  // …or NULL for "there is no table for this caller".
  fetchProfile: () => {
    if (!getAuthToken()) return null;        // guest / logged out — see below
    return apiRequest('/gamepads/resolved', { method: 'GET' });
  },
  // Optional. Never called on the resolve path.
  saveProfile: (profile) => apiRequest('/gamepads', { method: 'POST', body: profile }),
});

null is a real answer, not an error. A caller with no credential gets "no table", and the pad still works through the browser's own standard mapping. This is load-bearing: an api client that treats a 401 as "your session ended" will clear the token and navigate away, and the pad database must never be able to take down the page that asked for it. A null answer is not cached — it is a statement about the caller's credential, not about the table.

createResolver returns the full surface: resolveProfile, remapTable, loadProfiles, loadRemapTable, setProfiles, clearProfiles, getProfiles, profilesLoaded, saveProfile, plus the stateless REJECT, gateProfile, parseVendorProduct, liveMappingState, isXInputWrapper, mergeResolvedLayers. Create one instance per app, at module scope — the profile cache is shared state on purpose (the wizard seeds it with setProfiles straight after a save; the stream path and the nav path both read it back).

The gates are the point

A stored profile is a set of raw hardware indices. Applied to the wrong pad state or the wrong report shape it does not degrade gracefully — it silently means something else, and the user cannot tell it is wrong. So gateProfile refuses rather than adapts, and a refusal drops the pad to the next tier:

user override > global verified > global unverified > your seed > browser standard

| REJECT | Refused because | |---|---| | SCHEMA | The profile's schemaVersion is newer than this build's | | IDENTITY | No vendor/product in the pad id, or it doesn't match | | MAPPING_STATE | The browser normalized this pad on one platform and not the other. Never adapt across that line | | REPORT_SHAPE | Button/axis counts differ. Equality, not tolerance — one extra button is not the pad that was captured |

The token layer

The Vue components style themselves entirely from CSS custom properties. Import the kit's defaults before your own token sheet so the cascade lets yours win:

import '@wildride/pad-kit/tokens.css';   // neutral-dark defaults
import './styles/tokens.css';            // yours — same :root specificity, later wins

Values are space-separated R G B integers, not rgb(...) strings, because the components read them as rgb(var(--token) / 0.3). A hex value breaks every rule that uses an alpha modifier.

The list is measured from the components' style blocks, not aspirational:

• PadDiagram — --surface-sunken --surface-overlay --edge --edge-strong --ink-secondary --ink-muted --color-brand --color-danger --color-warn --color-action
• GlyphChip / PadButtonGlyph — --surface-overlay --edge-strong --ink --color-brand --color-live --color-danger --color-warn --radius-lg

A host that already defines these names does not need to import tokens.css at all.

Glyph context

PadButtonGlyph learns which pad is in the user's hands through provide/inject, not through a store:

providePadGlyphContext({
  glyphSet: computed(() => ui.state.glyphSet),           // 'xbox' | 'playstation' | …
  glyphOverrides: computed(() => ui.state.glyphOverrides), // the profile's display.labels
});

Both fields take a ref/computed or a plain value. Nothing is required: with no provider at all every chip resolves through the generic set. A chip must degrade, never throw.

Versioning

SCHEMA_VERSION is the contract. Stored profiles are indices into real hardware; a consumer that reads a profile written by a newer schema than it understands is the exact failure the gates exist to prevent.

• A SCHEMA_VERSION bump is a MAJOR release. No exceptions, however additive the change looks.
• Adding a glyph set, a pad shape, an archetype, or a component prop: MINOR.
• Changing a PAD_SCALE radius, a shape's geometry, or a BUTTON_FLAGS value: MAJOR (the wire flags are pinned in lockstep with a stream core; the radii are pinned by the geometry checker).
• Consumers pin exactly. game-kube's web-ui/package.json carries an exact version, not a range.

Consumers

1. game-kube (web-ui/) — the origin. Registration wizard, console-fit / remap panels, in-stream pad mapping, FR-41 controller navigation.
2. (second consumer — this repo exists because the kernel outgrew one app.)

Development

npm install
npm test                 # vitest — the ported specs plus the kit's component spec
npm run check:geometry   # node tools/pad-geometry-check.mjs — every built-in shape

tools/pad-geometry-check.mjs is both a CLI and a set of importable pure rules. test/padGeometryCheck.spec.js hands it the same tables the bundler resolves, so npm test runs the geometry rules over the real built-ins — the checker cannot rot by nobody remembering to type the command.

node tools/pad-geometry-check.mjs                       # every built-in
node tools/pad-geometry-check.mjs layout.json           # a spec.padLayout document
node tools/pad-geometry-check.mjs layout.json --family ps2

Authoring or re-measuring a shape is .claude/skills/pad-geometry (/pad-geometry): it grids a reference photograph, reads control centres off it mechanically, rasterizes the result the way PadDiagram.vue draws it, and runs the checker before showing anyone a shape. The photographs live in a gitignored gamepad_refrence_images/ and are a reference, never a source — no outline is traced, no image or crop is embedded, and what lands in a diff is integers. Note that a CONSOLE.* control-id set is a cross-repo contract: consoleFit.js stayed in game-kube, so that is where the coverage-both-ways pin lives, and a renamed or added id passes here and fails there.

Phase 0 note

During the extraction, the specs under test/ also still live in game-kube (web-ui/src/gamepad/__tests__/, web-ui/src/composables/__tests__/lrud.spec.js), running against re-export shims. That duplication is deliberate and temporary: it is the equivalence proof that the extraction changed nothing. Two of them differ on purpose — game-kube's apply.spec.js and resolver.spec.js additionally pin against its vendored stream core (StreamControllerButton, the core's own parseVendorProduct), which the kit has no copy of; the kit pins the same values as literals and cross-checks resolver's parser against capture's.