Bind Manager is a browser-first key binding system for games and interactive applications.
It provides:
- A modal for rebinding keyboard, mouse and gamepad inputs (grouped by action category)
- A bottom-screen hint bar for action prompts
- Persistent bindings via localStorage
- Runtime action events (pressed, held, released, analog)
- Built-in tools to test a controller and to capture a new controller profile
- A framework-agnostic API that works in ThreeJS and non-ThreeJS apps
Input support: keyboard, mouse buttons, mouse wheel and the browser Gamepad API, including modifier key combos (e.g. ShiftLeft+KeyW, ControlLeft+MouseButton0) and modifier-only chords (e.g. ControlLeft+ShiftLeft) with capture-on-release semantics. Gamepads are labelled per controller family (eight families, detected by vendor/product id), with exact generated profiles for controllers whose raw layout needs remapping.
Coming from the last public build? Read Upgrading from 0.1.0 first.
A demo page is available that exercises all features and serves as a testbed during development. It is a copy of dist/standalone-demo.html, which now has a Fake controller panel so the gamepad features can be tried without a pad; the online copy shows it once it is republished.
- Action registration with labels, descriptions, groups, slots, and defaults (keyboard/mouse and gamepad)
- Multiple bindings per action (for example primary + secondary)
- Per-slot clear (delete) support from the modal
- Reset action to defaults and reset all actions
- Conflict warnings when the same key is bound to multiple actions (allowed, not blocked)
- Change subscriptions so host apps can react to rebinds
- Optional debug modal toggle key (default: F5)
- Bottom hint overlay with per-action and bulk visibility controls
- Gamepad binding capture and runtime action events, logical buttons
GP_B0..GP_B23 - Eight controller label families detected by vendor/product id, an Xbox Elite paddle variant, exact generated device profiles
- Manual gamepad profile override and family/generic fallback behavior
- Built-in tools (opt-in): Controller Test (live controller view, Debug panel, Profile editor) and Input Remap (guided capture into a controller profile)
- UI sized on a viewport scale unit (
--bm-u), so it looks the same between 1280x720 and 3840x2160 at the same aspect ratio - Mouse button and wheel bindings (buttons 0–4, wheel up/down, one notch = one press, Ctrl/Shift/Alt + wheel chords)
- Opt-in browser shortcut guard: cancels reload/find/save/zoom/scroll/context-menu/… while the game owns input, Keyboard Lock in fullscreen, optional "leave site?" prompt
- Modifier key combos for keyboard and mouse (e.g.
ShiftLeft+KeyW,ControlLeft+MouseButton0) - Modifier-only chords such as Ctrl + Shift (
ControlLeft+ShiftLeft), recorded in the rebind dialog and fired like any key; see Modifier-only chords - Capture-on-release: binding commits when the primary key/button is released, allowing modifier selection
- Cancel button fires on pointer-down to prevent accidental bind commits
activegetter andonActiveChangesubscription for host cursor management- Visible storage failures (
getStorageStatus())
Use these internal docs when you want implementation details rather than package-level usage guidance.
- src/core/README.md
- Core architecture, state model, manager lifecycle, import/export, persistence, and invariants.
- src/input/README.md
- Input runtime architecture, code formats, keyboard/mouse/gamepad event flow, and profile-dependent labeling.
- src/input/controller_definitions/README.md
- Generated controller profiles, the capture workflow, the processing pipeline, and when a profile applies.
- scripts/README.md
- The build and the controller-profile generator.
- dist/README.md
- The browser bundles and the standalone demo page.
The package is not published on npm. Get the code from the public repository:
git clone https://github.com/materia79/bind-manager.git
cd bind-manager
npm install # Node ^20.19.0 or >=22.12.0 (package.json "engines"); needed for the build and the tests
npm run demo # serves the repository root on port 3001Then open http://localhost:3001/demo/.
To use it in a game, either:
- copy
src/into your project and import from your copy ofsrc/index.js(plain ES modules: load your script with<script type="module">from a page served over http, not opened as afile://URL), or - run
npm run buildand loaddist/bind-manager.min.jswith a<script>tag; it exposes everything aswindow.BindManager(see dist/README.md).
The demo page registers fourteen actions with keyboard, mouse and gamepad defaults. Its event log shows pressed for every action, released for Move Forward, Block, Open Map, Open Inventory and Sprint, and held for Move Forward, plus binding changes, resets and the guard's pointer-lock and fullscreen state. Its HUD has the buttons Key Bindings, Controller Test, Input Remap, Toggle Hints, Reset All, Fullscreen + Keyboard Lock and Arm/Disarm Leave Guard, and a guard status line. Its Fake controller panel (off by default, labelled as simulated) installs a pretend gamepad of a chosen family (Xbox, Xbox Elite, Xbox 360, DualShock 4, DualSense, Switch Pro, Steam Deck, Stadia, unknown) with on-screen buttons, for trying the gamepad features without a pad.
A runnable minimal page is in examples/standalone/index.html (http://localhost:3001/examples/standalone/).
Generate browser-ready single-file bundles:
npm run buildBuild output:
dist/bind-manager.jsreadable bundle (globalwindow.BindManager)dist/bind-manager.min.jsminified bundle for hosting (205,235 bytes at this version)
Watch mode for local build iteration:
npm run build:watchThis repository automatically publishes the latest minified bundle as a rolling GitHub Release asset.
Behavior:
- Trigger: every push to
main - CI gates:
npm testandnpm run build - Release tag:
main-latest - Published asset:
dist/bind-manager.min.js
Workflow file:
Notes:
- The
main-latestrelease is updated in place on each push tomain. standalone-demo.htmlis not auto-deployed; publish it manually to your pages repository when needed.
Script-tag usage:
<script src="/path/to/dist/bind-manager.min.js"></script>
<script>
const binds = window.BindManager.createBindManager({
namespace: 'my-game',
builtInTools: {
inputRemap: true,
controllerTest: true,
},
});
</script>Load this as a module (<script type="module">) from a page served over http; ./src/index.js is your copy of the library's src/index.js (see Install and Run). The GP_* strings are gamepad codes, listed under Gamepads.
import { createBindManager } from './src/index.js';
const binds = createBindManager({
namespace: 'my-game',
debug: true, // F5 toggles the modal and no longer reloads the page
debugKey: 'F5',
builtInTools: true, // Input Remap and Controller Test in the modal's footer
});
const moveForward = binds.registerAction({
id: 'move-forward',
label: 'Move Forward',
description: 'Move character forward',
group: 'Movement',
slots: 2,
defaultBindings: ['KeyW', 'ArrowUp'],
gamepadSlots: 1,
defaultGamepadBindings: ['GP_A1N'], // left stick up
});
const jump = binds.registerAction({
id: 'jump',
label: 'Jump',
group: 'Movement',
slots: 2,
defaultBindings: ['Space', null],
defaultGamepadBindings: ['GP_B0'], // A / Cross / B (Switch), see Gamepads
});
moveForward.showHint();
jump.showHint();
moveForward.onPressed(() => {
// game logic
});
binds.subscribe((event) => {
if (event.type === 'binding-changed') {
console.log('Binding updated', event.actionId, event.device, event.slot, event.newCode);
}
});
// Your own settings button: open the bindings modal without the debug key.
document.querySelector('#settings').addEventListener('click', () => binds.open());With debug: true, the debug key (F5) toggles the modal and its default (page reload) is cancelled; leave debug off in production and call binds.open() from your own menu. Browsers expose a gamepad only after one of its buttons is pressed while the page is open, so a pad appears in the modal and the hints after the first press.
Options:
namespace?: stringstorage namespace, defaultdefaultdebug?: booleanenable debug toggle key listenerdebugKey?: stringKeyboardEvent.codeused for modal toggle, defaultF5. A key that types a character (a letter, a digit, Space, punctuation) or edits text (Backspace, Delete, the arrows, Home, End) does not toggle while the modal's search field has the focus, nor does any keystroke of an IME composition; it types there instead (see Searching the bindings)container?: HTMLElement | nullmount target for modal, hints and tools, defaultdocument.bodystorage?: { load, save, clear?, loadGamepadProfileOverrides?, saveGamepadProfileOverrides?, loadCollapsedGroups?, saveCollapsedGroups? } | nullcustom persistence adapter (see Persistence)builtInTools?: true | { inputRemap?: boolean, controllerTest?: boolean } | nullenable the bundled Input Remap and Controller Test tools (trueenables both; see Built-in tools)footerActions?: { id, label, className?, onClick }[]extra buttons in the bindings modal's footer, before the built-in toolsbrowserGuard?: boolean | BrowserGuardOptionscancel browser shortcuts while the game owns input, defaultfalse(see Browser shortcut guard)wheelPixelThreshold?: numberpixel delta that counts as one wheel notch, default30(see Mouse wheel bindings)reservedKeyWarnings?: booleannote in the rebind dialog when the player binds a key the browser or the operating system keeps, defaulttrue(see Reserved keys)bindSearch?: booleansearch field above the bindings list that filters it while the player types, defaulttrue(see Searching the bindings)groupFolding?: booleangroup headers of the bindings list fold and unfold their rows, defaulttrue(see Folding groups)collapsedGroups?: string[]groups that start folded, default[](all open); the player's remembered choice winsdeadband?: numbergamepad axis values at or below this are treated as rest, default0.12analogThreshold?: numberan axis direction counts as pressed past this value, default0.5
Returns a manager object with methods below.
registerAction(def)registerActions(defs)
Action definition fields:
id: stringrequired stable action idlabel?: stringhuman-friendly namedescription?: stringaction descriptiongroup?: stringmodal section grouping, defaultGeneralslots?: numberkeyboard/mouse bindings count, default2defaultBindings?: (string|null)[]KeyboardEvent.code, mouse, combo or chord codes per slotgamepadSlots?: numbergamepad bindings count, default1defaultGamepadBindings?: (string|null)[]GP_*codes per gamepad slotanalog?: booleanreceive continuousanalogevents from axes, defaultfalseplayerIndex?: numberonly this gamepad index triggers the action; omitted = any pad
registerAction returns an action handle:
showHint()hideHint()setHintVisible(boolean)onPressed(callback)onReleased(callback)onHeld(callback)onAnalog(callback)(actions withanalog: true)
open()close()toggle()isOpen()setGroupCollapsed(group, collapsed)— fold or unfold a group of the bindings list and remember it, like the player's click (no-op withgroupFolding: false)isGroupCollapsed(group)— the remembered fold state of a group: the player's choice, elsecollapsedGroupsopenInputRemap()— opens the Input Remap tool whenbuiltInToolsenables it (no-op otherwise)openControllerTest()— opens the Controller Test tool whenbuiltInToolsenables it (no-op otherwise)
The built-in tools are always part of the library (and of the bundle); builtInTools decides whether they are mounted and shown as footer buttons in the bindings modal.
active(getter) —truewhen the binding modal or capture session is open. Use this to show/hide your game cursor.keepCursorAfterClose(getter/setter) — a flag kept for host use: the library stores it but never reads it. bind-manager never changes the cursor or pointer lock itself; useactive/onActiveChangeto do that in your game.onActiveChange(callback)— subscribe to active-state transitions. Callback receives(active: boolean). Returns an unsubscribe function.
browserGuard(getter) — always present; inert until enabled. Methods:enabled,setEnabled(boolean),setTarget(element | null)isEngaged()—truewhile shortcuts are being cancelledsetGameOwnsInput(boolean)— tell the guard the game has the cursor (for games without pointer lock)block(patterns),allow(patterns),getShortcutPolicy()— opt shortcuts in / out at runtimekeyboardLockSupported,isKeyboardLocked()enterFullscreen(element?)→Promise<{ fullscreen, keyboardLocked, error? }>,exitFullscreen()armLeaveGuard(),disarmLeaveGuard(),isLeaveGuardArmed()
See Browser Shortcut Guard for the guide.
getBinding(actionId, device = 'keyboard')—deviceis'keyboard'(keyboard and mouse codes) or'gamepad'getBindings()exportBindings(options?)importBindings(payload, options?)setBinding(actionId, slot, code, device = 'keyboard')clearBinding(actionId, slot, device = 'keyboard')resetAction(actionId)resetAll()clearStorage()— delete the persisted bindings (including the saved entries of actions not registered yet) and gamepad profile overrides for this namespace (live bindings are kept; callresetAll()first to also restore defaults). Returnsfalseif a custom storage adapter has noclear().getStorageStatus()—{ ok, failedSaves, lastError, lastFailure }, see Persistence
getConnectedGamepads()—{ index, id, profile, resolvedProfile }[]getActiveGamepadProfile(gamepadIndex = 0)— the resolved family keygetResolvedGamepadProfile(gamepadIndex = 0)— the full resolved profile (see Gamepads)getGamepadLabel(code, gamepadIndex = null)— label of aGP_*code on that pad;null= the first connected pad (generic labels when none is connected)getGamepadThresholds()—{ deadband, analogThreshold, buttonThreshold }the runtime dispatches withgetGamepadLogicalState(gamepadIndex = 0)—{ buttons: boolean[24], axes: number[4] }exactly as the runtime reads the pad for dispatch, ornullwhen that pad is not connectedgetAvailableGamepadProfileOptions(gamepadIndex = 0)—{ exactProfiles, families, autoResolved }for a profile pickersetGamepadProfileOverride(gamepadIndex, override)/clearGamepadProfileOverride(gamepadIndex)— persisted manual override{ type: 'family', family }or{ type: 'profile', key }setGamepadProfileMappingEntry(gamepadIndex, code, entry, options?),removeGamepadProfileMappingEntry(gamepadIndex, code),resetGamepadProfileMapping(gamepadIndex),getGamepadProfileDefinition(gamepadIndex)— in-memory mapping edits, see In-memory mapping edits
Some keys never reach a web page, some only while it is fullscreen, and some only in some browsers. The rebind dialog adds a note when the player binds one of them; binding is still allowed. When the key is also bound to another action, the conflict note comes first, and the note's full text is in its title. The note stays 8 seconds when it includes a reserved-key note, 5 seconds for a conflict alone.
The levels:
| Level | Meaning | Examples |
|---|---|---|
blocked |
never reaches the page | the Windows key and every Windows-key combo when the platform is known and not a Mac; Ctrl+Alt+Del, Ctrl+Shift+Esc, Ctrl+Esc, Alt+Esc, Ctrl+Shift+Q; Cmd+Q, Cmd+Tab, Cmd+Space, Cmd+H; Alt+Tab and Alt+F4. Under the guard's Keyboard Lock exactly four of them change, each only with exactly the modifiers shown and only on its platform: Cmd+Tab on a Mac, and Alt+Tab, Alt+F4 and the bare Windows key on a platform known not to be a Mac (below) |
fullscreen-only |
reaches the page only while it is fullscreen in a Chromium browser | Ctrl+W, Ctrl+T, Ctrl+N, Ctrl+Q, Ctrl+Tab, Ctrl+PageUp, Ctrl+PageDown, Ctrl+F4 (also with Shift; Ctrl+Shift+Q excepted; never with Alt, since Ctrl+Alt is AltGr on many layouts); Cmd+W, Cmd+T, Cmd+N on a Mac; Alt+Tab (exactly Alt, on a platform known not to be a Mac) while the browser guard is enabled with Keyboard Lock on and Tab among its lock keys |
unreliable |
works in some browsers or situations only | Escape (with any modifiers), F11 and F12 (with any modifiers), Ctrl+Shift+I/J/C, Ctrl+1..9, Ctrl+Shift+P, Shift + right click, Alt+Space; the bare Command key on a Mac; Windows-key combos when the platform is unknown (except those that hold a blocked combo, which stay blocked; see Platform below); while the guard's Keyboard Lock locks their key, the bare Windows key and Alt+F4 (exactly Alt) on a platform known not to be a Mac, and Cmd+Tab (exactly Cmd) on a Mac; a browser command nothing cancels (below); a fullscreen-only shortcut the browser guard lets through |
In Firefox and Safari the tab and window shortcuts are generally not cancellable at all (see the table in What a page cannot block, and Keyboard Lock); fullscreen-only describes Chromium.
The browser shortcut guard is the single source of truth, and its real decision counts:
-
fullscreen-onlyis the guard'sFULLSCREEN_ONLY_SHORTCUTS, matched with the guard's own pattern logic (Modis Ctrl or the Windows / Command key; a pattern matches with at least its modifiers). -
Guard disabled (the default): nothing cancels the browser's action. Tab and window shortcuts stay
fullscreen-only, and the note says that in fullscreen the game has to cancel the browser's action itself, with the browser guard as the way to do it. Alt+Tab isblocked. -
Browser commands nothing cancels: the guard's default patterns with a Ctrl /
Modmodifier or on a function key (Ctrl+S, Ctrl+R, Ctrl+L, Ctrl+D, F5, F1, Ctrl+wheel, zoom, …; on a Mac the same with Cmd, and any other Cmd combo) areunreliablewhen nothing cancels them: the guard is disabled, or it lets the key through. One rule decides this for every platform. When the guard cancels them there is no note. For F1, F3, F6 and F7 the note says that whether they can be cancelled at all is up to each browser (see Browser shortcut guard). Scrolling keys, the mouse buttons (the mouse runtime cancels bound ones itself) and AltGr combos get no note. -
Guard enabled: a key it cancels is fine: through its lists (
shortcuts,block), or because it is bound andblockBoundis on (the default). A shortcut it really lets through (allow, orblockBound: falseand not in its lists) gets "The browser guard lets X through, so the browser also acts on it." (levelunreliable). -
Keyboard Lock: a level changes only where What a page cannot block, and Keyboard Lock plainly says Keyboard Lock delivers the combo, only with exactly the modifiers it names, and only on its platform. While the guard is enabled,
keyboardLockis on and the key is among its effective lock keys (keyboardLockKeys: nulllocks every key), exactly these change: on a Mac, Cmd+Tab with only Cmd held (Tab locked) becomesunreliable; on a platform known not to be a Mac, Alt+Tab with only Alt held (Tab locked) becomesfullscreen-only, Alt+F4 with only Alt held (F4 locked) becomesunreliable, and the bare Windows key (no other modifier held; MetaLeft / MetaRight locked) becomesunreliable. When the platform is unknown the lock changes no level. Everything else keeps the level it has without the lock, so these stayblockedwhatever is locked: Alt+Tab, Alt+F4 and Cmd+Tab with another modifier held (such as Alt+Shift+Tab, Ctrl+Alt+Tab, Ctrl+Alt+F4 or Cmd+Shift+Tab), Alt+Tab and Alt+F4 on a Mac, Win + any key (such as Win+Alt+Tab and Win+Alt+F4), Ctrl+Shift+Q and Cmd+Q (the browser keeps quit even in fullscreen), Ctrl+Esc, Alt+Esc, Ctrl+Shift+Esc, Cmd+Space, Cmd+H, and Ctrl+Alt+Del. -
Platform: the Windows / Command key is read from what a page can see (
navigator.userAgentData.platform, thennavigator.platform, then the user agent; anything unreadable counts as unknown). On a Mac it is Cmd, handled through the guard'sModlogic, and the bare Command key isunreliable; elsewhere the Windows key and every Windows-key combo areblocked. When the platform is unknown, the bare key and its combos areunreliable, except a combo that holds one of theblockedcombos above (its key with at least its modifiers): Win/Cmd + Q, Tab, Space or H, which macOS and Windows both keep, or any otherblockedcombo with the Windows / Command key added, such as Win+Alt+F4, Ctrl+Win+Esc or Ctrl+Alt+Win+Del. Those stayblocked, also with more modifiers held. -
getReservedInfo(code, { guard, platform, bound })returns{ level, reason }(plusguardLetsThrough: truein the case above) ornull. All options are optional:guardis a guard's effective state{ enabled, shortcuts, block, allow, blockBound, keyboardLock, keyboardLockKeys }. Values are read the way the guard reads them (a missingblockBoundorkeyboardLockmeanstrue, otherwise truthiness). Withoutguard, or with a falsyenabled, nothing is cancelled. Note thatbrowserGuard.getShortcutPolicy()alone has noenabledfield, so passing it counts as a disabled guard;manager.getReservedBindings()builds the full state for you.platformis'mac','other'or'unknown'(default: detected).bounddefaults totrue.
-
isReservedCode(code, options)istruefor any level. -
manager.getReservedBindings()lists current keyboard and mouse bindings that are affected,{ actionId, slot, code, level, reason, guardLetsThrough? }[], for example to check your defaults. It and the rebind dialog use the manager's guard and the detected platform. -
reservedKeyWarnings: falseturns the note in the rebind dialog off.
The macOS entries are not verified on a real Mac.
showHint(actionId)hideHint(actionId)showAllHints()hideAllHints()
onAnyAction(callback)— every action event of every device:pressed,held,released, and the gamepad'sanalogevents too (withcodenaming the half for an action bound to one half of an axis). Skiptype === 'analog'in a handler that tracks up/down state; read analog values with the action handle'sonAnalog().isActionPressed(actionId)—truewhile a bound key, mouse button or gamepad input is held. Gamepad bindings only count on the action'splayerIndexcontroller when one is set. Mouse wheel bindings always readfalsehere: the wheel has no held state and fires a pressed+released pulse, so listen withonPressedinstead. Inside a keyboard or mousereleasedlistener it already readsfalsefor that input, whether a keyup, a window blur, the modal opening ordestroy()released it.- A keyup the page never saw. Browsers lose keyups now and then while the window keeps its focus: a key let go while another frame, a native menu or a host's own listener had it, or a key let go while Cmd is held on macOS. The keyboard runtime repairs what it can, each time as if the keyup had arrived (
releasedfirst, with that event asoriginalEvent). Both repairs act only on key events the browser generated (isTrusted) and only on keys such events pressed. A key that a synthetic keydown pressed (a script, a host's on-screen key, a test), or pressed again while it was down, is never itself released by a repair, and a synthetic event never repairs; so synthetic key events behave as in 0.2.3 as long as no keyup of a real key is lost. A modifier-only chord that a synthetic modifier completes with a real modifier does end when that real modifier is repaired (itsreleasedcomes then, and the later synthetic keyup sends nothing for it); a combo whose key a synthetic keydown pressed stays until that key's keyup, as in 0.2.3.- A trusted keydown (not a repeat) of a key that is down releases the first press before the new one, so every
pressedgets itsreleased. 0.2.3 sent a secondpressedthere. If a browser sent such a keydown while the key is really still held (possible in principle, for example when a modifier changes during auto-repeat; not observed), the action would getreleased+pressedthere. - A trusted key event whose modifier flags (
ctrlKey,shiftKey,altKey,metaKey) show a held modifier up releases that modifier and every chord with it first, so a chord no longer fires on a single modifier press and a combo such as Ctrl + A is not sent once Ctrl is up. One flag covers both sides, so a flag that is off releases Left and Right; a lost keyup of one side is not seen while the other side is down. While AltGr is down (getModifierState('AltGraph')) the Ctrl and Alt flags are not read, because layouts and browsers report AltGr as Ctrl + Alt or clear both flags. An event's own key is never released by its flags. - The repair trusts these flags. Where trusted flags say a modifier is up although no keyup was lost, that modifier is released early: its
releasedcomes at that event, its auto-repeats send noheldand its keyup sends nothing. Known cases: automation that sets the flags per key name and not per side (Playwright: hold both Shift keys and let one go, and the other is released too); key events sent through a debugger (the Chrome DevTools protocol, some extensions) with empty flags; and, not verified in a real browser, Windows with NumLock on when Shift is held and a numpad key is pressed, and a platform that reports a held Meta key withmetaKeyfalse. - The browser shortcut guard (
browserGuard) reads the held modifiers before the repair runs, so the first key event after a lost keyup is still guarded as if the modifier were down. - Not repaired: a key that is not a modifier stays pressed until it is pressed again or the window loses focus (macOS: a key let go while Cmd is held).
- A trusted keydown (not a repeat) of a key that is down releases the first press before the new one, so every
subscribe(callback)for binding-change events (binding-changedwithdevice,actionId,slot,oldCode,newCode,conflicts;reset)
destroy()remove listeners and UI from the page
Everything below is exported from src/index.js (and is a property of window.BindManager in the bundles):
| Area | Exports |
|---|---|
| Manager | createBindManager |
| Keyboard and mouse | getKeyLabel, isKnownCode, KEY_DISPLAY_NAMES, MODIFIER_ORDER, MODIFIER_CODES, buildComboCode, buildChordCode, isModifierChord, normalizeChordCode, WheelNotchCounter, DEFAULT_WHEEL_PIXEL_THRESHOLD, getReservedInfo, isReservedCode |
| Browser guard | DEFAULT_BLOCKED_SHORTCUTS, DEFAULT_KEYBOARD_LOCK_KEYS, FULLSCREEN_ONLY_SHORTCUTS, parseShortcutPattern, matchesShortcutPattern |
| Gamepad codes | GP_CODES, GP_B0..GP_B23, GP_A0N..GP_A3P, GP_BUTTON_COUNT (24), GP_AXIS_COUNT (4), isGamepadCode, getGamepadCodeType |
| Families and labels | GAMEPAD_PROFILES, GAMEPAD_FAMILIES, GAMEPAD_FAMILY_NAMES, GAMEPAD_DEVICE_FAMILIES, GAMEPAD_LABEL_VARIANTS, GAMEPAD_UNVERIFIED_LABELS, detectGamepadProfile, getGamepadLabel, getGamepadFamilyName, getGamepadLabelVariant, isGamepadLabelUnverified, parseGamepadId |
| Profile resolution | getControllerFamily, getResolvedGamepadLabel, isControllerProfileApplicable, resolveGamepadProfile |
| Mapping helpers | decodeHatValue, isHatEntryActive, isHatGridLayout, readMappingEntryMagnitude |
New since 0.1.0: GP_B17..GP_B23, GP_BUTTON_COUNT, GP_AXIS_COUNT, GAMEPAD_FAMILIES, GAMEPAD_FAMILY_NAMES, GAMEPAD_DEVICE_FAMILIES, GAMEPAD_LABEL_VARIANTS, GAMEPAD_UNVERIFIED_LABELS, getGamepadFamilyName, getGamepadLabelVariant, isGamepadLabelUnverified, parseGamepadId, isControllerProfileApplicable, decodeHatValue, isHatEntryActive, isHatGridLayout, readMappingEntryMagnitude. Nothing was removed.
Games collide with browser shortcuts: Ctrl+S saves the page, Space scrolls it, Ctrl+wheel zooms, F5 reloads. The guard calls preventDefault() on those while the game owns input. It is opt-in:
const binds = createBindManager({
namespace: 'my-game',
browserGuard: {
target: canvas, // game element (scopes pointer-lock / fullscreen / focus detection)
allow: ['Mod+KeyF'], // opt out: let the browser keep Ctrl/Cmd+F
block: ['Tab'], // opt in: also cancel Tab
leaveGuard: true, // "leave site?" prompt once the game was played
},
});
canvas.addEventListener('click', () => canvas.requestPointerLock());
playButton.addEventListener('click', () => binds.browserGuard.enterFullscreen());browserGuard: true enables it with all defaults. Options (BrowserGuardOptions):
| Option | Default | Meaning |
|---|---|---|
enabled |
true (object form) |
start enabled; toggle later with setEnabled() |
target |
null |
game element; null = any pointer-lock / fullscreen element counts |
when |
'auto' |
when the game owns input: 'auto', 'always' or () => boolean |
shortcuts |
DEFAULT_BLOCKED_SHORTCUTS |
replaces the default list |
block / allow |
[] |
extra patterns to cancel / never cancel (allow wins) |
blockBound |
true |
also cancel anything that resolves to a bound action (bare or combo, with any modifiers) |
contextMenu |
true |
cancel the context menu |
keyboardLock |
true |
request Keyboard Lock in JS fullscreen |
keyboardLockKeys |
DEFAULT_KEYBOARD_LOCK_KEYS |
keys to lock; null = every key |
leaveGuard |
false |
arm a beforeunload prompt when the guard first engages |
When it is engaged. Only while all of these hold: the guard is enabled; the bindings modal, a capture session and the built-in tools are closed; focus is not in a text field (input, textarea, select, contenteditable — those keep every browser default); and the game owns input. With when: 'auto' that means pointer lock on the target, fullscreen containing the target, focus inside the target, or setGameOwnsInput(true). when: 'always' treats the whole page as the game, so Space on a focused page button is cancelled too. Events aimed at bind-manager UI are never touched. Listeners run on window in the capture phase, so a game's stopPropagation() cannot bypass them, and gameplay dispatch is unchanged.
Patterns use bind-manager codes with generic modifiers: Ctrl, Shift, Alt, Meta/Cmd, and Mod (Ctrl or Meta, so one entry covers Windows/Linux and macOS). A pattern matches when its key is pressed with at least its modifiers: F5 also covers Ctrl+F5, Mod+KeyR covers Ctrl+Shift+R. Alt alone means either Alt key and MouseWheel means either wheel direction. Side-specific codes from bindings (ControlLeft+KeyS) work too.
Default list (DEFAULT_BLOCKED_SHORTCUTS, exported):
| Group | Patterns |
|---|---|
| Reload | F5, Mod+KeyR |
| Save, print, find, find next, bookmark, history, downloads, view source, open file, address bar | Mod+KeyS, Mod+KeyP, Mod+KeyF, Mod+KeyG, Mod+KeyD, Mod+KeyH, Mod+KeyJ, Mod+KeyU, Mod+KeyO, Mod+KeyL |
| Function keys | F1, F3, F6, F7, F10, F12 |
| Menu bar focus | Alt (keydown and keyup) |
| Firefox quick find | Slash, Quote |
| Page zoom | Mod+Equal, Mod+Minus, Mod+Digit0, Mod+NumpadAdd, Mod+NumpadSubtract, Mod+Numpad0 |
| Back navigation and page scroll | Backspace, Space, arrows, PageUp, PageDown, Home, End |
| Tab / window management (effective in fullscreen only, see below) | Mod+KeyW, Mod+KeyT, Mod+KeyN, Mod+KeyQ, Ctrl+Tab, Ctrl+PageUp, Ctrl+PageDown, Ctrl+F4 |
| Wheel: page scroll, Ctrl+wheel zoom, Shift+wheel horizontal scroll | MouseWheel, Mod+MouseWheel, Shift+MouseWheel |
| Mouse: middle-click autoscroll/paste, back/forward thumb buttons | MouseButton1, MouseButton3, MouseButton4 |
| Context menu | contextMenu: true |
Entries are kept separate so you can filter single ones out, e.g. keep plain wheel scrolling but still block Ctrl+wheel zoom:
import { DEFAULT_BLOCKED_SHORTCUTS } from './src/index.js'; // your copy of src/index.js, or window.BindManager
createBindManager({ browserGuard: { shortcuts: DEFAULT_BLOCKED_SHORTCUTS.filter(p => p !== 'MouseWheel') } });The primary mouse button is never cancelled (focus and requestPointerLock() need it). Escape and F11 are not in the default list, so they keep their browser behaviour unless you bind them to an action (with blockBound) or add them with block; then they are cancelled too. DevTools combos other than F12 (Ctrl+Shift+I/J/C) are not in the default list; add them with block if you want. Whether F1/F3/F6/F7/F12 can be cancelled is up to each browser.
Outside fullscreen, Chromium handles a set of reserved shortcuts before the page sees them, so preventDefault() has no effect: close tab (Ctrl+W, Ctrl+F4), close window (Ctrl+Shift+W, Alt+F4), new tab (Ctrl+T), new window (Ctrl+N), new incognito window (Ctrl+Shift+N), reopen closed tab (Ctrl+Shift+T), next/previous tab (Ctrl+Tab, Ctrl+Shift+Tab, Ctrl+PageDown, Ctrl+PageUp) and quit. These are kReservedCommandIds in chrome/browser/ui/accelerator_table.cc. Per BrowserCommandController::IsReservedCommandOrKey, while the window is fullscreen, every command except exit and fullscreen toggling goes to the page first. That is why the guard's default list includes the tab and window shortcuts: they take effect in fullscreen.
Operating-system shortcuts (Alt+Tab, the Windows key, Cmd+Tab, Esc leaving fullscreen) never reach a page. The Keyboard Lock API (navigator.keyboard.lock(), MDN, Chrome docs) changes that:
- It only takes effect while JavaScript-initiated fullscreen is active. User-initiated F11 fullscreen does not count.
lock(keyCodes)captures the listedKeyboardEvent.codekeys with every modifier combination ("registeringKeyWensures that W, Shift+W, Control+W, Control+Shift+W … are sent to the app").lock()with no arguments captures every key.- It captures only keys the OS lets go of. Secure attention sequences such as Ctrl+Alt+Del can never be captured.
- If Escape is locked, the user exits fullscreen by holding Esc for 2 seconds.
- It has to be called from the active top-level document (it rejects with
InvalidStateErrorin iframes) and needs a secure context (HTTPS or localhost). - Browser support: Chrome 68+, Edge 79+, Opera 55+ and other Chromium browsers. No support in Firefox or Safari (caniuse). There the guard skips the lock (
keyboardLockSupported === false).
How the guard uses it: it locks DEFAULT_KEYBOARD_LOCK_KEYS (KeyW, KeyT, KeyN, KeyQ, Tab, PageUp, PageDown, F4) when fullscreen containing the target starts, and unlocks when fullscreen ends. enterFullscreen(element?) requests the lock and then fullscreen in the same user gesture and returns { fullscreen, keyboardLocked }. exitFullscreen() releases both. Escape is not locked by default, so one press still leaves fullscreen. Locking Tab also captures Alt+Tab on Windows while in fullscreen. Pass keyboardLockKeys: null to lock every key (Esc then has to be held), or your own list.
What remains unblockable:
| Situation | Not blockable |
|---|---|
| Chromium, not fullscreen | the reserved tab/window shortcuts above, all OS shortcuts |
| Chromium, JS fullscreen + Keyboard Lock | OS secure sequences (Ctrl+Alt+Del), anything the OS keeps; Esc exit when Esc is locked needs a 2 s hold |
| Chromium, F11 fullscreen | OS shortcuts (no Keyboard Lock); reserved shortcuts do reach the page |
| Firefox, Safari | no Keyboard Lock. Ctrl/Cmd+W, T, N, Q, Ctrl+Tab and OS shortcuts are generally not cancellable; this differs by version and platform, so verify on the target browser |
With leaveGuard: true, the guard arms a beforeunload "Leave site?" prompt as soon as it first engages: pointer lock on the target, focus moving into the target, fullscreen containing the target, setGameOwnsInput(true), or the first input event it handles while engaged. It stays armed after the cursor is released, so clicking the tab's close button still asks. Call disarmLeaveGuard() right before your app's own navigation (it re-arms on the next engagement), or arm and disarm it by hand with armLeaveGuard() and disarmLeaveGuard(). Browsers only show the prompt after the user has interacted with the page, and they use their own fixed text.
Wheel directions can be bound like keys: MouseWheelUp and MouseWheelDown, plus chords such as ControlLeft+MouseWheelUp or ShiftLeft+MouseWheelDown. In the bindings modal, click a slot and scroll. Labels read "Wheel Up" / "Left Ctrl + Wheel Up", and wheel bindings persist and import/export like any other code.
Each notch dispatches one pressed followed by one released (wheels have no held). Raw WheelEvents are normalised by WheelNotchCounter (exported):
- pixel mode (
deltaMode0, Chromium/Safari): an event of at leastwheelPixelThreshold(30) px is one notch - line mode (
deltaMode1, Firefox): an event of one or more whole lines is one notch. Firefox usually reports 3 lines per detent, which still counts as one notch - page mode (
deltaMode2): every event is one notch - smaller deltas from trackpads and high-resolution or free-spinning wheels add up per direction, and each 30 px (or 1 line) of travel emits a notch. The running total resets on a direction change or after 200 ms without wheel input
- one event never produces more than one notch
- Shift+wheel: Chromium and Safari report it on
deltaX, which is used whendeltaYis 0 and Shift is held, so Shift+wheel chords work everywhere. Pure horizontal scrolling (tilt wheel, sideways trackpad) is ignored
The window wheel listener is passive by default. It becomes non-passive only while a capture runs (so capture can stop the modal from scrolling) or while a wheel code is bound and gameplay is not suppressed (so a host handler can cancel through originalEvent). During gameplay, page scrolling is only cancelled by the browser guard.
A binding can consist of modifier keys only: two or more of Left/Right Ctrl, Shift, Alt and Meta, such as ControlLeft+ShiftLeft (label "Left Ctrl + Left Shift"). The player records one in the rebind dialog by holding the modifiers and letting go of one of them; a host gives one as a default like any other code:
binds.registerAction({ id: 'show-names', label: 'Show Names', slots: 2, defaultBindings: ['ControlLeft+ShiftLeft', 'ControlRight+ShiftRight'] });How a chord behaves:
- Fires on the keydown that completes it, when the modifiers held are then exactly the chord, in any order: Shift then Ctrl is the same chord as Ctrl then Shift. Keys other than modifiers that are held do not count. Left and right keys are different keys, as for single modifiers and combos:
ControlLeft+ShiftLeftdoes not fire for Right Ctrl + Left Shift; bind each variant you want in its own slot. heldfollows on the auto-repeat of the key that completed it;releasedcomes when the first of its keys goes up, so a "hold to show" action ends as soon as the player lets go of either key. Blur, opening the modal anddestroy()release it like any key, andisActionPressed()follows it.heldcomes from the operating system's auto-repeat of the completing key, so where the system does not repeat modifier keys (macOS) a chord gets noheld, onlypressedandreleased.- The chord wins over a single modifier for the keydown that completes it, like a combo wins over its key alone: with Ctrl bound to Crouch, Shift to Sprint and Ctrl + Shift to Show Names, pressing Ctrl then Shift sends Crouch, then Show Names (not Sprint); Crouch stays held until Ctrl goes up. Pressing Shift then Ctrl sends Sprint, then Show Names (not Crouch).
- On the way to a bigger combo the chord fires too. With Ctrl + Shift and Ctrl + Shift + A both bound, Ctrl, Shift, A sends Show Names at Shift and the Ctrl + Shift + A action at A; Show Names stays held until Ctrl or Shift goes up. A modifier pressed after the chord is complete leaves it active; a chord of more modifiers fires when its own last key goes down. Bind actions that can share a moment like this, or avoid binding both.
- Recording: the dialog commits when the first modifier goes up while no other key was pressed, as the chord of every modifier held at that moment. A single modifier pressed and released records itself as before, and combos still commit when their key goes up, so recording Ctrl + A is as before. A modifier already held when the recording starts is not counted (Ctrl held, start recording, tap Shift records Shift alone); the player presses it again inside the recording. The event's flags would show that Ctrl is down, but not whether it is Left or Right Ctrl, and the two are different bindings.
- Without a chord bound, nothing changes: every other binding sends exactly the events it sent in 0.2.2 (since 0.2.4, except where the browser's own events show a lost keyup or flags that disagree with the keys held; see A keyup the page never saw).
- The conflict note, the reserved-key notes (a chord with the Windows key never reaches the page off a Mac) and the browser guard treat a chord like a combo. With
blockBound, the guard cancels the keydown that completes a bound chord, its auto-repeats, and keyups while the whole chord is still held; the keydown of the chord's first key and the keyup of its last key pass through. The search matches its label ("ctrl shift"). - A chord written in another order (
'ShiftLeft+ControlLeft') is stored in canonical order (MODIFIER_ORDER: Ctrl, Shift, Alt, Meta, left before right); a stored chord in another order is read in that order and written back in it on the next save.buildChordCode(modifiers)builds that code,isModifierChord(code)recognises one, andnormalizeChordCode(code)puts a chord written in any order into that order (anything else, combos included, comes back unchanged), so two stored chords compare equal withnormalizeChordCode(a) === normalizeChordCode(b).
Storage: a chord is stored like a combo, as its code string in a keyboard slot of the bindings key ({ "version": 1, "bindings": { "show-names": { "keyboard": ["ControlLeft+ShiftLeft", null], "gamepad": [null] } } }). Version 0.2.2 reads such a store without error and keeps every binding: it shows the chord in the modal ("Left Ctrl + Left Shift"), lets the player clear or replace it and saves it back unchanged, but never fires it and cannot record one. Stores written by 0.2.2 load unchanged, with one exception: a modifier-only code a 0.2.2 host stored in another modifier order (ShiftLeft+ControlLeft, which 0.2.2 showed but never fired) is rewritten in the fixed order on the first save.
Gamepad bindings use logical codes:
GP_B0..GP_B16: the 17 buttons of the browser's standard layout (face buttons 0–3, bumpers 4–5, triggers 6–7, the two centre buttons 8–9, stick clicks 10–11, D-pad 12–15, home 16).GP_B17..GP_B23: extra buttons a pad reports after the standard 17 (Share, touchpad click, paddles, back grips).GP_BUTTON_COUNTis 24.GP_A0N/GP_A0P..GP_A3N/GP_A3P: the four stick axes, split into a negative and a positive direction (GP_A1Nis left stick up).
A button counts as pressed when the browser reports pressed: true or its value is above 0.5; an axis direction counts as pressed past analogThreshold (default 0.5). Axis values within deadband (default 0.12) are rest. Actions with analog: true also get continuous analog events, and exactly one analog event with value 0 when the axis returns into the deadband. Read the values in use with getGamepadThresholds().
Labels come from the family the pad is detected as. getGamepadLabel(code, family, variant?) (module function) and manager.getGamepadLabel(code, gamepadIndex?) return them; a family without a label for a code returns the code itself, which is how the UI knows a pad lacks that button.
Family (GAMEPAD_FAMILY_NAMES) |
GP_B0..GP_B3 |
GP_B8 / GP_B9 |
GP_B10 / GP_B11 |
GP_B16 |
GP_B17.. |
|---|---|---|---|---|---|
xbox (Xbox) |
A, B, X, Y | View / Menu | LS / RS | Xbox | Share |
xbox360 (Xbox 360) |
A, B, X, Y | Back / Start | LS / RS | Guide | — |
dualshock4 (DualShock 4) |
Cross, Circle, Square, Triangle | Share / Options | L3 / R3 | PS | Touchpad |
dualsense (DualSense) |
Cross, Circle, Square, Triangle | Create / Options | L3 / R3 | PS | Touchpad |
switch-pro (Switch Pro) |
B, A, Y, X (positional) | Minus / Plus | LS / RS | Home | Capture |
steam (Steam) |
A, B, X, Y | View / Menu | L3 / R3 | Steam | Quick Access, Left Pad, Right Pad, L4, L5, R4, R5 |
stadia (Stadia) |
A, B, X, Y | Options / Menu | L3 / R3 | Stadia | Assistant, Capture |
generic (Generic) |
Btn 0..Btn 3 | Btn 8 / Btn 9 | Btn 10 / Btn 11 | Btn 16 | Btn 17..Btn 23 |
Bumpers and triggers are LB/RB/LT/RT (Xbox families), L1/R1/L2/R2 (PlayStation, Steam, Stadia) and L/R/ZL/ZR (Switch Pro). Every named family labels the D-pad D-Up/D-Down/D-Left/D-Right and the sticks LS-Up, RS-Left and so on; generic labels axes Axis 0-, Axis 0+, ….
Xbox Elite variant. GAMEPAD_LABEL_VARIANTS['xbox-elite'] relabels GP_B17..GP_B20 as Paddle 1..4 for the Elite controllers (045e-02e3, 045e-0b00, 045e-0b05, 045e-0b22); the rest of the pad keeps the Xbox labels. Per research, only Chrome on Windows reports the paddles. The resolved profile names the variant in labelVariant.
Labels not verified on hardware. GAMEPAD_UNVERIFIED_LABELS lists entries no device was available for: Xbox GP_B17 (Share is confirmed only for Chrome on Windows), Steam GP_B17..GP_B23 (back-button order, the 2026 Steam Controller layout), Stadia GP_B17/GP_B18 (Assistant and Capture may be swapped). isGamepadLabelUnverified(code, family) checks one.
parseGamepadId(id) reads { vendorId, productId, key, name } from both browser id forms: Firefox 054c-0ce6-DualSense Wireless Controller (also with leading zeros dropped) and Chrome DualSense Wireless Controller (STANDARD GAMEPAD Vendor: 054c Product: 0ce6). detectGamepadProfile(id) then decides:
- With a vendor/product pair, only the device table
GAMEPAD_DEVICE_FAMILIESdecides; a pair not in the table isgeneric. - Without one, name patterns apply: any
XInputid isxbox; "Xbox 360" isxbox360; "Xbox Wireless/One/Series/Elite/Adaptive" isxbox; "DualSense", "DualShock", a bare "Wireless Controller" (DualShock 4 on older setups), "Pro Controller"/"Joy-Con", "Steam Deck/Controller", "Stadia" pick their family; anything else isgeneric.
getResolvedGamepadProfile(index) (and the module function resolveGamepadProfile(gamepad, { override })) resolves a pad in this order: a manual exact-profile override that fits the pad, a manual family override, an exact generated profile that fits the pad, the detected family, generic. In-memory mapping edits replace the result (source memory-edit). The result has source (manual, exact, family, generic, memory-edit), family, profileHint, profileKey, definition, override, ignoredOverride, gamepadId, displayName, vendorId, productId and labelVariant.
An exact profile (generated from a capture, see src/input/controller_definitions/README.md) remaps raw buttons and axes and brings its own labels. It applies only when isControllerProfileApplicable(profile, gamepad) holds: the browser did not remap the pad (gamepad.mapping !== 'standard') and the pad's raw button and axis counts equal the profile's sourceButtons and sourceAxes. With a bare id string it never applies. A manual exact override that does not fit is stored anyway (the pad may report a raw layout later) but not applied: the resolved profile reports it in ignoredOverride, the manager warns once in the console, and the bindings modal and the tools show "saved profile does not fit this controller's layout" next to the profile select ("saved profile is not available for this controller" when no profile with that key exists at all).
The one shipped exact profile is 054c-0ce6 (DualSense), captured from the raw layout Firefox reports (14 buttons, 12 axes, no remap). Chrome reports a DualSense with mapping: 'standard', so there the dualsense family labels apply instead.
Hat D-pads. A raw D-pad reported as one hat axis is decoded on the 2/7 grid (up -1, right -3/7, down 1/7, left 5/7): when a profile's four hat entries sit on the four cardinal grid positions (isHatGridLayout), a cardinal entry is also active on its two neighbouring diagonals, so up-right presses both GP_B12 and GP_B15, and a value off the grid (the resting value) is neutral. Other hat entries match their own value ± tolerance (default 0.2). decodeHatValue(raw) returns { up, right, down, left }.
setGamepadProfileMappingEntry(index, code, entry) maps one logical code to a raw { kind: 'button', index }, { kind: 'axis', index, direction } or { kind: 'hat', index, value, tolerance } input on that controller model. On a pad without an exact profile, editing one code keeps the rest of the pad on its standard layout. removeGamepadProfileMappingEntry(index, code) gives the code its base entry back (the exact profile's, or the standard layout's); resetGamepadProfileMapping(index) discards every edit of that pad and returns true when there were any. Edits apply to every pad of the same model, survive a reconnect, and are not persisted: they are gone on reload. getGamepadProfileDefinition(index) returns the edited (or exact) definition, or null for a pad on family or generic labels without edits. The Controller Test's Profile editor is a UI for these calls.
Every length in the UI is a multiple of --bm-u and every text size one of four font tokens, so between 1280x720 and 3840x2160 the UI looks the same at any resolution with the same aspect ratio. Below that range it keeps its 1280x720 size (and is capped at the viewport); above it, its 3840x2160 size. Small text also has px floors (9px and 10px), so near the floor the smallest text does not shrink with the rest.
:root {
--bm-u-min: 0.6667px;
--bm-u-max: 2px;
--bm-u: clamp(var(--bm-u-min), min(100vw / 1920, 100vh / 1080), var(--bm-u-max));
}--bm-u is 1px at 1920x1080. It reaches its floor (0.6667px) at 1280 wide or 720 tall and its ceiling (2px) at 3840x2160.
The library injects its stylesheet into <head> when the manager mounts (inside createBindManager()), after your own styles. Its :root rule therefore wins a tie with a host :root rule, so write root-level overrides as html:root { … }:
| Variable | Where a host may set it | Default |
|---|---|---|
--bm-u |
html:root or any ancestor of the UI (e.g. body { --bm-u: 1px } for fixed sizes) |
the clamp above |
--bm-u-min, --bm-u-max |
html:root only (read only by the :root declaration of --bm-u) |
0.6667px, 2px |
--bm-font-xs, --bm-font-s, --bm-font-m, --bm-font-l |
html:root or any ancestor |
max(9px, 14u), max(10px, 15u), 17u, 21u |
--bm-modal-width |
html:root or any ancestor |
calc(1080 * var(--bm-u)) |
--bm-modal-max-h |
html:root or any ancestor |
calc(880 * var(--bm-u)) |
--bm-modal-radius |
html:root or any ancestor |
calc(12 * var(--bm-u)) |
The bindings modal is capped at the viewport whatever these say: at most 100vw - min(32u, 4vw) wide and 100dvh - min(32u, 4dvh) tall. The three size variables are no longer declared on :root (their defaults are fallbacks where they are used), so getComputedStyle(document.documentElement) returns nothing for them. Set the font tokens through --bm-font-*; a host value for the internal --bm-fs-* tokens is replaced on the library's roots.
The built-in tools (Input Remap, Controller Test) follow the same rules: an ancestor's --bm-u and the --bm-font-* variables size their text as they size the modal's.
At 1280x720 and below, the smallest text is 9.33px (--bm-fs-xs), the others 10px, 11.33px and 14px.
| Variable | Default |
|---|---|
--bm-z-modal, --bm-z-capture, --bm-z-hints |
9000, 9010, 8000 |
--bm-overlay-bg |
rgba(0, 0, 0, 0.75) |
--bm-modal-bg, --bm-modal-border |
#1e1e2e, #3a3a5c |
--bm-text-primary, --bm-text-secondary, --bm-text-desc |
#e0e0f0, #b0b0d0, #9898c0 |
--bm-group-bg, --bm-group-border, --bm-row-hover |
#16162a, #2a2a44, #252540 |
--bm-accent, --bm-accent-hover, --bm-accent-active |
#5c7cfa, #748cfb, #4a6ae8 |
--bm-btn-bg, --bm-btn-hover, --bm-btn-border |
#2a2a44, #343460, #3a3a60 |
--bm-capture-bg, --bm-capture-border, --bm-capture-text |
#3a2a00, #c89000, #ffd060 |
--bm-reset-color, --bm-reset-hover |
#e06060, #f07070 |
--bm-warn-bg, --bm-warn-border, --bm-warn-text |
#2e1e00, #a06000, #ffa040 |
--bm-hints-bg, --bm-hints-border |
rgba(10, 10, 25, 0.85), rgba(255, 255, 255, 0.08) |
--bm-hint-key-bg, --bm-hint-key-border |
rgba(255, 255, 255, 0.12), rgba(255, 255, 255, 0.22) |
Changed defaults since 0.1.0: --bm-text-secondary (#9090b0 → #b0b0d0) and --bm-text-desc (#6a6a90 → #9898c0), so both reach 4.5:1 contrast on every default background.
Borders are box-shadows. Hairlines are drawn as box-shadow rings (outer for the modal, the capture modal and the hint pill; inset for buttons, the profile panel, the select, the warning), so they never shift the layout. Library buttons and selects have border: 0. A host border-color override therefore has no visible effect any more; recolour the hairlines through the variables above (--bm-modal-border, --bm-btn-border, --bm-capture-border, --bm-group-border, --bm-warn-border, --bm-hints-border, --bm-hint-key-border, --bm-accent on hover) or override box-shadow. In the built-in tools, the hairline colours are --bm-tool-line and --bm-btn-line, declared on the tool panels and on .bm-tool-btn themselves (set them on those elements; an ancestor value is overridden). Tool overlays use fixed z-indexes (10020, 10030, 10040).
The modal picks one of three row layouts from the body's measured width (in u) and the widest slot counts of all registered actions (kb keyboard slots, gp gamepad slots), and re-checks on resize:
bm-layout-inline(body at least388 + 154 × (kb + gp)u): one line per action, label, keyboard slots, a divider, gamepad slots, reset.bm-layout-stacked(body at least334 + 154 × max(kb, gp)u): label, then the keyboard row above the gamepad row, reset.bm-layout-narrow(otherwise): the label on its own line above the stacked rows.
Slot columns line up across all rows in every layout. At the default width (body about 1070u), the inline layout holds up to four slots in total. The layout class sits on .bm-modal.
On phones and tablets (a coarse primary pointer, pointer: coarse) the narrow layout sizes each action's device rows to its own slots rather than the widest action's: an action with one or two slots keeps its reset button on its line, and an action with more slots than fit wraps its own slots without widening the other rows. Slots still start at the same place and have the same width.
--bm-u stays at its floor, so the UI keeps its 1280x720 size. The bindings modal is capped at the viewport, its body scrolls, and its rows fall back to stacked or narrow; nothing overflows sideways. The capture modal (480u) is capped the same way. The two built-in tools (Controller Test 1400u x 800u and Input Remap 1200u x 760u at normal sizes) fill the viewport minus 16px below 1280 wide or 720 tall and become one scrolling column; below 800px wide their header takes two rows. Their capture window (640u x 420u) does not fill the viewport; it is capped at the viewport minus 16px. The Controller Test's controller view keeps a minimum width of 780u (520px) and scrolls sideways when narrower, starting at its centre.
The hint bar is a centred pill near the bottom edge (min(16u, 2vh) above it), at most the viewport width minus a margin, and at most three rows tall; further rows are clipped. Each hint label is at most 240u wide with an ellipsis; the full text is in its title.
Styles written for 0.1.0 against these no longer match:
- Bindings modal:
bm-with-gamepad(CSS only),bm-profile-summary,bm-profile-meta,bm-profile-subtitle(nowbm-profile-namewith the raw id in itstitle, andbm-profile-chipwithbm-profile-chip--exact|family|generic|manual|memory-edit),bm-profile-controls, and the Auto buttonbm-profile-auto-btn(use the select's "Auto detect" option). New:bm-profile-note,bm-empty,bm-device-row--keyboard/--gamepad,bm-layout-*. - Built-in tools: the card classes
bm-debug-card/bm-tester-card(nowbm-tool-section),bm-debug-small/bm-tester-help(nowbm-tool-note),bm-debug-actions/bm-tester-actions, the profile status lines and Auto buttons (nowbm-tool-device,bm-tool-chip,bm-tool-select), the DOM controller view (bm-tester-controller,bm-tester-nodewith itsbm-widemodifier,bm-tester-stick,bm-tester-stick-dotwithbm-tester-left-stick-dot/bm-tester-right-stick-dot,bm-tester-trigger-meter,bm-tester-trigger-fill,bm-tester-l2-fill,bm-tester-r2-fill,bm-tester-edit-mode; now one SVGbm-tester-padwithbm-pad-*classes;bm-tester-trigger-editstill exists), the raw-input toggle and its section (bm-tester-raw-section,bm-tester-raw-toggle-btn,bm-tester-raw-pre; now the Debug panel'sbm-tester-raw),bm-tester-last-signal,bm-tester-detail.
Enable them with builtInTools: true (or { inputRemap: true, controllerTest: true }). They appear as Input Remap and Controller Test buttons in the bindings modal's footer and open from code with openInputRemap() / openControllerTest(). One tool is open at a time: opening one closes the other. While a tool is open, Escape and Tab are handled at window capture for the topmost tool dialog wherever focus is (Escape closes it, Tab stays inside) and never reach the page or the bindings modal underneath; the browser shortcut guard is disengaged. Closing a tool returns focus to what opened it.
Opened by the footer button Controller Test (its dialog title reads the same). A fixed-size panel with a header (title, the device's own name with the raw id in its tooltip, a profile chip such as "Family · DualSense", "Exact · DualSense", "Manual · Stadia", "Generic" or "Edited", the profile select with "Auto detect", Debug, Profile editor, Close), a live SVG view of the controller in the family's layout, and one status line.
- The view lights a control exactly when the game gets
pressedfor it (it readsgetGamepadLogicalState()and the runtime's thresholds); movement below the threshold shows as a faint partial fill. Sticks show a dot, triggers a 0.00–1.00 bar; extra buttons (GP_B17..) show only when the pad has them, Elite paddles in a row of small keys. - Debug opens the last strongest signal (kind, index, direction, delta, raw, code, and the logical code it resolves to with its label), the active codes (
Active: GP_B0=Cross, …) and a raw table of every button and axis. - Profile editor opens Calibrate baseline (1.5 s; keep the controls released), Edit mode (click a control in the view, then hold the physical input you want for it: it is assigned after about two 100 ms samples; Trigger targets L2/R2/L2A/R2A pick the trigger codes; L2A/R2A are
GP_B6A/GP_B7A, the analog trigger readings, which exist only in this editor and in captures: they cannot be bound to actions), Capture update (a 5 s capture window for the selected control), Download JSON (the current exact or edited profile definition as<key>.json), Reset edits (discard this controller's in-memory edits), and the selected control's current binding with Remove. Edits are the in-memory mapping edits above: not saved.
A guided capture of a controller into the capture JSON that npm run process_controller_defs turns into an exact profile. Pick the preset (only "DualSense / PlayStation Layout" exists: 27 steps for GP_B0..GP_B16, the analog triggers GP_B6A/GP_B7A (capture-only codes; they cannot be bound) and the eight stick directions, then an optional "Touchpad click" step for GP_B17 that a pad without one skips with Next), press Start Debug and release everything for the 2 s baseline, then walk the steps with Back, Redo, Capture (each capture window is 5 s; the strongest stable input wins) and Next. The panel shows the live strongest signal, a validation line and the JSON (schemaVersion, runMeta.targetController { index, id, mapping, buttons, axes }, runMeta.baseline, sequence, captures, byExpected, controllerDefinition), with Copy JSON and Download JSON (file name <vendor>-<product>_dualsense.json). mapping is the layout the browser reports ('standard' or ''). For a pad the browser already reports in the standard layout, a note under the profile line says so when the tool opens, and the validation line is an error instead of "ready to export": no exact profile is needed there, the family labels apply (Copy and Download still work, for debugging).
The full workflow, and what it needs from the pad, is in src/input/controller_definitions/README.md.
- Only one key-capture session can be active at a time.
- While capturing, conflicting UI actions are disabled.
- Canceling capture (Escape) restores the button without applying changes.
- Per-slot clear buttons remove a binding without resetting the entire action.
- Duplicate bindings are allowed and shown as warnings.
- Tab stays inside the bindings modal and the capture dialog; closing returns focus to the opener. Reset, Reset All and profile changes update the modal in place and keep its scroll position and focus.
- Only the list scrolls. The modal box is
overflow: clip, so a host'sscrollIntoView()on a row, orfocus()on a button far down, scrolls the list and leaves the header, the search field and the footer in place. In a browser withoutoverflow: clip(Safari before 16) the box falls back tooverflow: hidden, and the modal puts it back when something scrolls it. - A tap or click on Cancel (or Close) never reaches the control underneath, also with touch and pen and on a double tap.
- The Escape that closes the modal ends there: it does not reach window listeners, so an action bound to Escape does not fire as the modal closes.
A search field sits between the modal's header and the list, so it stays in view while the list scrolls. What the player types filters the list at once:
- The text is split at spaces; a row is shown when every word occurs in its label, its description, its group name, or the label of one of its current bindings as its button shows it ("Space", "Ctrl", "Wheel Up", and gamepad buttons under the active profile, such as "Cross" on a DualSense). Internal codes (
KeyW,GP_B0) are not matched. Case and accents do not count ("saute" finds "Sauté"). - Rows that do not match are hidden in place (the
hiddenattribute; no re-render), and so is a group with no row left. Hidden rows are out of the Tab order and the focus trap. When nothing matches, one line says so and names the text; a polite live region tells screen readers the number of matches. - The filter follows binding changes and gamepad profile changes, since binding labels are matched. A row or group header that holds the focus stays shown until the text changes, so rebinding a key in a filtered list never removes the control in use. Should a focused control end up hidden all the same, the focus moves to the search field (from a hidden × clear-slot button: to its bind button), never out of the modal.
- While a filter is active the list starts at its top; clearing the text returns to the scroll position from before the search.
- Escape with text in the field, or on the clear button, clears the text, keeps the modal open and puts the focus in the field; the next Escape closes the modal. Elsewhere in the modal (a row, a group header) Escape closes it as before. Enter does nothing. Tab moves on to the clear button and the list. The clear button (×) appears when there is text.
- During an IME composition (
isComposing, orkeyCode229), every keystroke belongs to the input method: the Escape that cancels a composition neither clears the text nor closes the modal, and the debug toggle key does not toggle. - Typing in the field never fires an action or starts a capture, and the browser guard leaves it alone (actions are suppressed while the modal is open). The debug toggle key is ignored while it would type into the field (a letter, digit or other character, Backspace, Delete, the arrows, Home, End), so it may be a letter key; F5 and other non-typing keys still toggle.
- The text survives a re-render of the list, as
registerAction()while the modal is open does (value, focus and caret) and is cleared when the modal closes. Opening the modal puts the focus on the modal, not in the field. During a capture the field is disabled like the other controls. - On touch screens (
any-pointer: coarse) the field's text is at least 16px whatever--bm-uis, so iOS Safari does not zoom the page when it takes focus. The list body keeps a minimum height (min(120u, 40vh)), so a short viewport, such as one with an on-screen keyboard, cuts the footer before the list. bindSearch: falseremoves the field. The modal's markup is as in 0.2.1 only withgroupFolding: falseas well (folding is on by default), byte for byte, which a test checks against 0.2.1's output.
Classes: bm-search (the row), bm-search-input, bm-search-clear, bm-search-status (the live region, visually hidden with bm-visually-hidden) and bm-search-empty (the no-match line, also a bm-empty).
Each group title of the bindings list is a button that folds and unfolds the group's rows (click, tap, Enter or Space). It shows a marker, the group name and a count of bound actions out of all, for example "3 / 64" (read as "3 of 64 bound"); an action counts as bound when any keyboard, mouse or gamepad slot is set. The count follows binding changes in place.
- Defaults. All groups start open.
collapsedGroups: ['Spells']starts the named groups folded;manager.setGroupCollapsed(group, collapsed)folds or unfolds one from code. - Remembered. The player's choice, open or folded, is kept per namespace and wins over
collapsedGroups.LocalStorageAdapterkeeps it in its own key,bind-manager:<namespace>:collapsed-groups, as{ "version": 2, "groups": [["<group name>", true | false], ...] }, oldest choice first (truefolded,falseopened by the player); the bindings keybind-manager:<namespace>is not touched. At most 256 groups are kept: the newest choices, also for a stored list longer than that; a name listed twice counts with its last entry. The object form{ "version": 1, "groups": { "<name>": true | false } }is still read, in its stored order. A custom storage adapter may addloadCollapsedGroups()(returns the[name, folded]pairs, oldest first; an object{ name: folded }is accepted too) andsaveCollapsedGroups(groups)(gets the pairs); without them the state lives in memory for the page's lifetime. Reading and saving never throw. - Reset and clear. Reset All leaves the fold state alone.
clearStorage()deletes the stored fold state with the rest (the adapter'sclear()); the groups folded on screen stay as they are until the next reload. - With the search. While the search field holds text, every group with a match is shown open, so matches inside folded groups appear. A header click during a search folds or unfolds that group for the current search only; clearing the search brings back the fold state from before, unchanged.
- Focus. Rows of a folded group are out of the Tab order and the focus trap. When a group folds with the focus inside it, the focus goes to its header. Headers are disabled during a capture. A re-render of the list (
registerAction()while the modal is open) keeps fold state, focus (also on a header) and scroll. - Warnings. Rows carry no lasting conflict or reserved-key marker (those notes are the temporary line in the footer), so a folded header shows none.
groupFolding: falserenders plain group titles; withbindSearch: falseas well, the modal's markup is as in 0.2.1.
Classes: bm-group-toggle (the header button, also a bm-group-title), bm-group-marker, bm-group-name, bm-group-count (with bm-group-count-short and the screen-reader bm-group-count-long), bm-group-rows (the rows, hidden when folded) and bm-group-folded on a folded bm-group.
With 400 actions in 16 groups (desktop Chromium, to the second painted frame), open() takes about as long as in 0.2.1 while all groups are open (about 100 ms; about 600 ms with 4x CPU throttling) and is much faster with groups folded (about 34 ms with every group folded; about 120 ms throttled): rows of folded groups are built but not laid out. A keystroke that narrows the filter takes about two frames (33 ms; 70 ms throttled); one that widens it lays out the rows that come back (deleting one character to bring back 247 rows (from 40 to 287): about 50 ms; about 350 ms throttled).
Bindings are persisted under the localStorage key bind-manager:<namespace>, manual gamepad profile overrides under bind-manager:<namespace>:gamepad-profile-overrides, the folded groups of the bindings list under bind-manager:<namespace>:collapsed-groups (see Folding groups). The payloads are versioned internally.
- Saved bindings of actions that are not registered (yet) are kept on every save, so an action registered later still gets its saved bindings.
clearStorage()drops them too. - Saving happens once per committed change (
resetAll()is one commit). A failed save (quota exceeded, storage unavailable) never stops later saves: every later change tries again, the manager warns once in the console, andgetStorageStatus()returns{ ok, failedSaves, lastError, lastFailure }.okandlastErrordescribe the latest save (lastErrorisnullagain after a successful save);failedSavescounts failures andlastFailure({ error, at }) keeps the most recent one. - A custom
storageadapter needsload()andsave(bindings);clear(),loadGamepadProfileOverrides(),saveGamepadProfileOverrides(overrides),loadCollapsedGroups()andsaveCollapsedGroups(groups)are optional. Asave()that throws or returnsfalsecounts as a failed save (the built-inLocalStorageAdapterreturnstrue/falseand keepslastSaveError); asave()that returns nothing counts as a success. - In-memory gamepad mapping edits are never saved.
Export:
const payload = binds.exportBindings();
// { version: 2, namespace, bindings: { jump: { keyboard: ['Space', null], gamepad: ['GP_B0'] } }, metadata: { exportedAt } }Only registered actions are exported. Pass { includeMetadata: false } to leave out metadata.
Import (merge mode, default):
const report = binds.importBindings(payload);
// {
// mode: 'merge',
// appliedActions,
// appliedSlots,
// skippedUnknownActions, // ids ignored (merge mode: every unregistered id)
// storedUnregisteredActions, // replace mode: ids stored for later registration
// droppedUnregisteredActions, // replace mode: ids not stored because of a cap
// invalidEntries, // messages: unknown codes, wrong types, cuts
// conflictCount
// }Import (replace mode):
binds.importBindings(payload, { mode: 'replace' });In replace mode:
- A registered action missing from the payload has its keyboard slots cleared and, for a version 2 payload, its gamepad slots too. In a version 2 entry, a missing
keyboardorgamepadfield clears that device. Version 1 payloads (and legacy array entries) cannot express gamepad bindings and leave gamepad slots untouched. - The saved entries of all unregistered actions are made to match the payload: valid entries are stored (and apply when the action registers), saved ids missing from the payload are dropped, and an unrecognisable entry keeps the saved one. Stored data is capped: ids up to 128 characters, at most 512 unregistered ids per import, at most 16 slots per device; what is cut or dropped is reported.
An unknown code keeps the slot's current value and is reported in invalidEntries; a wrong value type clears the slot and is reported. An invalid mode throws.
The baseline is the last public build: the main-latest bundle of the public main branch as of 2026-08-10, package version 0.1.0. This release is 0.2.0 (see CHANGELOG.md). Below, "0.1.0" means that build.
Everything a host will notice, in one list. Nothing was removed from the public API.
Events
- Opening the bindings modal (gameplay suppressed) and disconnecting a pad now fire
releasedfor every gamepad code that firedpressed, and one finalanalogevent with value 0 to every analog action whose value (its half of the axis, or the whole axis) was non-zero. 0.1.0 left them pressed. - An input still held when gameplay resumes (modal closed) or after a capture is latched: it stays silent until it is released and pressed anew, so no
heldarrives without apressed. Analog events are not latched. A code released while the modal was open is unlatched at once. - An analog action whose value returns to 0 (the axis back in the deadband, or the stick on its other half) gets exactly one
analogevent with value 0; 0.1.0 left the last non-zero value standing. analogevents of an action bound to one half of an axis now carrycode(GP_A0N/GP_A0P, the same string as that half'spressed/held/released; for an action bound to both halvescodeis present butundefined), and within one poll they come before thepressed/heldof the same axis. A manager-wideonAnyActionhandler that treats every type other thanpressed/heldas "up" and keys its state bye.code(ore.code ?? e.actionId) therefore sees that half go up and down again on every frame the stick is past the threshold — also for a non-analog action bound to the same code. Skiptype === 'analog'in such a handler and read analog values withonAnalog(). A handler keyed byactionIdalready saw this for analog actions in 0.1.0.- Hat D-pad diagonals now press both directions (up-right =
GP_B12andGP_B15); a hat value between grid positions (the resting value) is neutral. - A button in an exact or edited mapping counts as pressed by the same rule as an unmapped one (
pressedor value above 0.5); 0.1.0 used the analog threshold for mapped buttons and ignoredpressed. destroy()firesreleased(withoriginalEvent: null) for every keyboard and mouse binding still held; 0.1.0's teardown released nothing. Gamepad bindings still get noreleasedfromdestroy().
Gamepad families and labels
- Five new families (
xbox360,dualshock4,switch-pro,steam,stadia) and detection by vendor/product id in both Chrome and Firefox id forms. 0.1.0 knewxbox,dualsenseandgenericand matched ids by substring. - DualShock 4 pads (
054c-05c4,054c-09cc,054c-0ba0, and a bare "Wireless Controller" id) are no longer labelled as DualSense: they get thedualshock4family (GP_B8is Share, not Create). - Xbox 360-era ids (
045e-028e,028f,0291,02a1,02a9,0719, Logitech F310/F510/F710 in X mode, the Steam virtual pad28de-11ff, Amazon Luna1949-041a) get thexbox360family (Back, Start, Guide). XInput ids without vendor/product stayxbox. - An unknown Microsoft or Sony vendor/product pair is now
generic(Btn 0, …); 0.1.0 labelled every Microsoft id Xbox and every Sony id DualSense. - Xbox labels changed:
GP_B8Back → View,GP_B9Start → Menu,GP_B10L3 → LS,GP_B11R3 → RS;GP_B17is Share. Elite controllers labelGP_B17..GP_B20Paddle 1..4. DualSense and DualShock 4 labelGP_B17Touchpad; generic labels go up toBtn 23. GP_B17..GP_B23exist: the runtime reads, captures and dispatches 24 buttons.GP_CODESlists 32 codes (0.1.0: 25) andisGamepadCode('GP_B17')istrue;GAMEPAD_PROFILEShas 8 families (0.1.0: 3). Code that iterates them sees the new entries.manager.getGamepadLabel(code)without an index uses the first connected pad; 0.1.0 used pad 0, so with pad 0 unplugged every label fell back to generic.- New:
getGamepadThresholds()andgetGamepadLogicalState(index)(what the runtime dispatches with and reads).
Exact profiles and overrides
- An exact profile applies only to a pad it fits (
mapping !== 'standard'and equal raw button/axis counts). 0.1.0 also handed the DualSense raw profile to any Sony pad (vendor-only fallback) and applied it to remapped pads. A manual exact override saved by 0.1.0 that does not fit is now ignored (reported inignoredOverride, no warning on load) and the pad uses its family. getAvailableGamepadProfileOptions()lists only exact profiles that fit the pad, and every named family with its display name.- The resolved profile (
getResolvedGamepadProfile(),resolveGamepadProfile()) has new fields:displayName,vendorId,productId,labelVariantandignoredOverride. removeGamepadProfileMappingEntry()restores the code's base entry; 0.1.0 left the code mapped to nothing. An edit on a pad without an exact profile no longer unmaps the rest of the pad. Edits survive a reconnect. New:resetGamepadProfileMapping().- Profile overrides are stored per controller model under a
vendor-productkey now, also for Chrome-form ids (0.1.0 usedid:<lowercased id>for those). Overrides saved by 0.1.0 are still read and are rewritten under the new key on their next change. Downgrade: overrides set or changed by this version for Chrome-form ids do not apply in 0.1.0 (the localStorage key is the same, the key inside it is not), overrides naming a new family show generic labels there, and savedGP_B17+ bindings never fire there.
Import and storage
- Replace-mode import clears the gamepad slots of missing actions (version 2 payloads) and the device fields missing from an entry, and makes the saved entries of unregistered actions match the payload (stored, dropped, capped at ids of 128 characters, 512 ids per import, 16 slots per device). The report has two new fields,
storedUnregisteredActionsanddroppedUnregisteredActions, and in replace mode an unregistered id is listed in one of them instead ofskippedUnknownActions(0.1.0 listed every unregistered id there; merge mode still does). See JSON Export and Import. - Merge-mode import no longer clears a device whose field is missing from an entry (an entry with only
keyboardleaves the gamepad slots alone), nor the gamepad slots of a version 1 array entry; 0.1.0 read a missing field as an empty list and cleared that device. - Saved bindings of unregistered actions are kept; 0.1.0 wiped them on the first save before the action registered.
- Failed saves are visible: one console warning and
getStorageStatus().LocalStorageAdapter.save()returnstrue/false; a custom adapter whosesave()throws or returnsfalseis counted as failing.
Mouse
- Window blur and the page going hidden release every held mouse button (
releasedevents) and reset the wheel notch counter. - During gameplay, the context menu is cancelled for right clicks while
MouseButton2(bare or as a combo with the held modifiers) is bound, except in text fields and the bind-manager UI; keyboard-opened menus are left alone. Without the browser guard, 0.1.0 never cancelled it, so the menu could open on the press and swallow the release. - A right press inside a text field or the bind-manager UI dispatches nothing.
- 0.1.0 registered the window wheel listener without options (passive in Chromium for window targets), so
originalEvent.preventDefault()in a wheel action had no effect there; now the listener is non-passive while a wheel code is bound during gameplay. It is also non-passive while a capture runs and passive otherwise; the browser guard's non-passive wheel listener exists only while the guard is enabled.
Packaging
package.jsondeclaresfiles(src/without the raw controller captures),sideEffects: falseandengines(node^20.19.0 || >=22.12.0); 0.1.0 declared none of them.
Built-in tools
- Rebuilt: fixed-size panels on the scale unit, an SVG controller view, the Debug and Profile editor panels, Reset edits. The Auto buttons are gone (use "Auto detect" in the select). The Input Remap dialog is titled "Input Remap" (was "Input Debugger").
- While a tool is open, Escape and Tab are stopped at window capture and handled by the topmost tool dialog, wherever focus is. One tool is open at a time.
Bindings modal behaviour
open()while the modal is open does nothing (no re-render, focus and scroll stay). Tab is trapped inside the modal and the capture dialog; closing returns focus to the element that opened it.- After a pointer cancel of the capture dialog (Cancel pressed by mouse, touch or pen), the click that follows is swallowed, so it never reaches the bind button underneath; for 350 ms a tap on that spot starts no new capture.
Look and layout
- Every size is on
--bm-u. The bindings modal is 1080u wide (1080px at 1920x1080; 0.1.0: 660px) and picks one of three row layouts; the hint bar is a centred pill capped at three rows (0.1.0: a full-width bar at the bottom edge). See Sizing and Theming. --bm-modal-width,--bm-modal-max-hand--bm-modal-radiusare no longer declared on:rootand have new defaults: 1080u (was 660px), 880u (was 80vh) and 12u (was 10px);--bm-text-secondaryand--bm-text-deschave new defaults; borders are box-shadows, soborder-coloroverrides no longer apply; several classes were removed (listed under Removed classes and markup), among them the tools classesbm-wide,bm-tester-raw-section,bm-tester-left-stick-dotandbm-tester-right-stick-dot. Focused controls in the bindings modal and the capture dialog get a 2u accent outline.bind-manager.min.jsgrew from 134,734 bytes in 0.1.0 to 205,235 bytes (withgzip -9: 34,471 bytes → about 56.8 kB), mostly the rebuilt tools, the families, the stylesheet and the browser guard.
Also new since 0.1.0 (made before the UI round)
- The opt-in browser shortcut guard:
browserGuardoption,manager.browserGuard, and the exportsDEFAULT_BLOCKED_SHORTCUTS,DEFAULT_KEYBOARD_LOCK_KEYS,parseShortcutPattern,matchesShortcutPattern. Nothing changes unless you enable it. - Wheel bindings fire one
pressed+releasedper notch (WheelNotchCounter,DEFAULT_WHEEL_PIXEL_THRESHOLD, thewheelPixelThresholdoption); 0.1.0 fired one per rawWheelEvent, so trackpads produced dozens. Shift+wheel chords work in Chromium and Safari; pure horizontal scrolling no longer counts as Wheel Down. registerAction()throws whenslotsorgamepadSlotsis not a positive integer (undefined/nullstill mean the default); default bindings beyond the slot count are dropped with a console warning.importBindings()accepts only payload versions 1 and 2 and validates the device arrays and codes: an unknown code keeps the slot and is reported ininvalidEntries.isActionPressed()honours the action'splayerIndex.- New:
clearStorage().resetAll()writes storage once. - Half-axis analog actions: an analog action bound to one half of an axis (
GP_A0NorGP_A0P) gets only that half, the signed value clamped to[-1, 0]or[0, 1](codenames the half); an action bound to both halves gets the full value; onevalue: 0event fires when the value returns to 0. 0.1.0 sent the full signed value to every action on either half. When an action gains slots after its bindings were saved, the new slots take their defaults (unless that code is already saved in another slot); 0.1.0 left them empty. These came from the public branchtwo-half-axis-analog(commit 4efef61), which was not inmain. destroy()closes the modal first, soactiveendsfalseandonActiveChangelisteners getfalse.- A key or mouse button pressed while the modal was open or during a capture no longer produces a lone
releasedwhen it is let go; Escape cancelling a keyboard capture clears the held keys. - Holding the debug key no longer toggles the modal on every key repeat.
- Gamepad capture ignores inputs already held when it starts, and the captured input stays silent until released.
- Stored profile overrides are normalised on load; invalid ones are dropped.
- Action ids such as
__proto__orconstructorwork.
- The shipped DualSense exact profile (
054c-0ce6) has no touchpad mapping: its capture predates the optional "Touchpad click" step, so the touchpad click is not mapped on a raw (Firefox) DualSense until someone re-captures the real pad in a browser that reports the raw layout. A binding onGP_B17still shows the family label "Touchpad" there, although it cannot fire. With Chrome's standard mappingGP_B17works and is labelled Touchpad. - Labels in
GAMEPAD_UNVERIFIED_LABELS(Xbox Share, the Steam back buttons, Stadia Assistant/Capture, and the Xbox Elite paddles Paddle 1..4 under thexbox-elitevariant) are not verified on hardware;isGamepadLabelUnverified(code, family, variant)checks a code against them. - The Controller Test's controller view keeps a minimum width of 780u (520px); on phone-sized viewports it scrolls sideways.
- The smallest text is about 9.3 CSS px at 1280x720 and below.
- The guided capture has one preset (DualSense layout) and tags every capture with the
dualsensefamily.
- ThreeJS integration guide: examples/threejs/README.md
- Standalone web app guide: examples/standalone/README.md, runnable page examples/standalone/index.html
- Full runnable demo used during development: demo/index.html
- The published single-file demo: dist/standalone-demo.html
Exact profile generation and runtime matching are described in src/input/controller_definitions/README.md, the generator in scripts/README.md. An exact profile is only for a browser that reports the controller's raw layout (gamepad.mapping is not 'standard'); where the browser already reports the standard layout (most pads in Chrome), no profile is needed, the family labels apply, and Input Remap says so when it opens. In short: in a browser that reports the raw layout, capture the controller with the built-in Input Remap tool, put the downloaded JSON into src/input/controller_definitions/captures/, run
npm run process_controller_defsand the generator writes a profile module under src/input/controller_definitions/profiles and refreshes the registry in src/input/controller_definitions/index.js.
Bind Manager keeps the browser Gamepad API as the primary runtime path.
Why this is primary:
- Works across Chromium, Firefox, and Safari with no additional permission prompt.
- Covers core binding needs (buttons, triggers, sticks, D-pad/hat mapping, profile labels).
- Keeps the normal binding flow simple and stable for most users.
WebHID is not part of the primary Bind Manager runtime input path.
Out of scope for the core runtime:
- Full migration from Gamepad API to WebHID.
- Requiring WebHID permissions for standard rebinding.
- Shipping adaptive trigger effect output as a default feature.
Run unit tests:
npm testRun E2E tests (install Chromium for Playwright once with npx playwright install chromium):
npm run test:e2eThe e2e server port defaults to 3001; set BM_E2E_PORT to run the e2e server on another port. tests/e2e/demo.spec.js checks the demo page, the standalone demo (run npm run build first) and the runnable example.
Manual checks for the browser guard and wheel bindings (desktop browsers; npm run demo, open /demo/, click the game area to capture the cursor):
- Before clicking the game area, Ctrl+S / Ctrl+F / Space behave normally.
- With the cursor captured (status shows "engaged · pointer lock"): Ctrl+S, Ctrl+P, Ctrl+F, Ctrl+G, Ctrl+D, Ctrl+H, Ctrl+J, Ctrl+U, Ctrl+O, Ctrl+L, Ctrl+R, Ctrl+Shift+R, F1, F3, F6, F7, F12 open nothing; Space, arrows and wheel do not scroll; Ctrl+wheel and Ctrl+± do not zoom.
- Firefox (Windows/Linux): tapping Alt does not show the menu bar;
/and'do not open quick find. - Right-click (after Esc released pointer lock, game area still focused) shows no context menu; middle-click does not start autoscroll; mouse back/forward buttons do not navigate.
- Opening the bindings modal (F5 debug key) disengages the guard: Ctrl+F opens find, the modal list scrolls.
- Bind "Previous Item" slot 2 by scrolling; label shows "Wheel Down"/"Wheel Up"; reload, binding persists; hint label updates.
- One mouse-wheel notch logs exactly one "next item" in Chrome and in Firefox; a slow trackpad swipe logs a few, not dozens per frame.
- Ctrl+wheel logs "zoom camera in/out" without zooming the page.
- Chrome/Edge: "⛶ Fullscreen + Keyboard Lock" → status "keyboard lock on"; Ctrl+W, Ctrl+T, Ctrl+N, Ctrl+Tab do nothing; a single Esc leaves fullscreen and the lock is released.
- Chrome/Edge outside fullscreen: Ctrl+W still closes the tab (documented limitation).
- Firefox/Safari: fullscreen works, status shows "keyboard lock n/a", nothing throws.
- "🚪 Arm Leave Guard", then close the tab: the browser asks "Leave site?"; after "Disarm" it closes without asking.
This project is licensed under the MIT License.
See LICENSE.md.
bind-manager works with two remotes:
origin: the public repository,https://github.com/materia79/bind-manager. It receives only finished work: themainbranch and tags. Every push tomainpublishesdist/bind-manager.min.jsas themain-latestrelease.private: your private work repository (git remote add private <its url>). Work branches, experiments and plans live there.
Once per clone, and again after every update of the guard scripts, run:
npm run setup:gitIt installs a copy of the guard into this clone's shared git directory (.git/hygiene-hooks/) and points core.hooksPath there, so the hook runs for every worktree of the clone whatever commit is checked out, and no checkout can replace it. It leaves another core.hooksPath (husky and the like) alone unless you add -- --force. Re-run it after every update of the guard scripts; until then the hook warns that the installed copy differs from the checkout and keeps scanning with the installed one. The installed copy is verified by hash before every push; npm run setup:git -- --check tells whether it is in place and intact, and npm test / npm run hygiene warn when it is not. It also sets remote.pushDefault to private when that remote exists (a bare git push then never goes public), adds your user.email and GitHub noreply addresses to hygiene.allowedEmail (the e-mails new public commits may carry; add others with git config --add hygiene.allowedEmail <address>), checks that origin is the public repository, and creates the untracked .hygiene-denylist from .hygiene-denylist.example. It is safe to run again.
What the pre-push guard checks, for pushes to the public remote only:
- only
mainand tags may be pushed; other branches, deletingmainand rewritingmain(a push that is not a fast-forward) are refused (a release isgit push origin <branch>:main); - tag and branch names are scanned too;
- the author and committer e-mail of every new commit must be in
hygiene.allowedEmail; - what is already public is asked from the remote at push time (
git ls-remote), not taken from local tracking refs; so a public push needs the network, and without an answer from the remote it is refused (also when aurl.*.insteadOfrule would send that question to another repository than the push goes to); - an installed guard (version 5 or later) older than the checkout's refuses public pushes; before the first public push of a release, re-run
npm run setup:gitin every clone;npm run setup:git -- --checkmust report the guard as current; - every commit that would become public is scanned: its message, every added line, every file path (merges and annotated tag messages included; binary,
-diffand UTF-16 content too), for secrets (private-key blocks; GitHub, Anthropic, OpenAI, AWS, Google, Stripe, Slack and npm keys; JWTs; bearer and basic auth; credentials in URLs; password, secret, token and api-key assignments, quoted or in env/YAML files), home, worktree and UNC paths, private IPv4 addresses, and private names.
Some checks run everywhere, some only on your machine:
- everywhere (pre-push hook,
npm run hygiene, and CI before themain-latestupload): secrets, private-key blocks, home, drive and UNC paths, private IPv4 addresses; - local only (pre-push hook and
npm run hygieneon your machine): this machine's host name, user name and home directory, the GitHub accountghis signed in to, the names in this repository's non-public remotes (owner/repo, the repository name, a private host), your gituser.emailand its domain (unless it is a webmail provider), the commit e-mail allowlist, and the entries of.hygiene-denylist.
.hygiene-denylist holds private names that no machine property reveals (other projects, codenames, ticket prefixes), one per line, plain strings or /regex/flags. It is untracked and never published; the format is explained in .hygiene-denylist.example.
On a hit the push is refused and the guard prints the commit, file:line (paths masked where they match) and the pattern name, never the matched text. Remove the text from the commit that added it (amend or rebuild the branch; a later deleting commit is not enough). For a deliberate false positive, add hygiene-allow: <pattern-name> on that line. Never use git push --no-verify for the public remote.
Examples of hits that are defensible in documentation, and the marker that keeps each one (the marker covers exactly that pattern on exactly that line):
postgres://user:pass@localhost/db # hygiene-allow: url-credentials
password: hunter22 # hygiene-allow: env-secret-assignment
192.168.1.10 # hygiene-allow: private-ipv4
A binary file (an image, a font) that trips a pattern by chance cannot carry a marker: after review, list it in .hygiene-allow-binaries as <sha256> <path> (sha256sum <path> prints the first part). The entry holds for exactly that content at exactly that path, and every push that includes the file prints allowed binary: <path>. It exempts the identity, path and denylist patterns only: private-key blocks and the provider token shapes (GitHub, Anthropic, OpenAI, AWS access key id, Slack, npm, Google, Stripe, JWT) are still matched inside a listed binary, so a real secret in it is refused anyway.
Every public step (push to origin, tag, main-latest release, npm publish, the GitHub Pages copy of the demo) goes through the release gate described in docs/RELEASING.md.