From 02b2195461b3abeafd6282b12fee5d9eefa217e2 Mon Sep 17 00:00:00 2001
From: Thor Whalen <1906276+thorwhalen@users.noreply.github.com>
Date: Mon, 6 Jul 2026 09:13:01 +0200
Subject: [PATCH] feat(hotkeys): end-user keymap customization (user remapping)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The second v1.14-deferred accelerator. Lets a USER (not just the developer)
remap shortcuts and have the choice persist (research-10) — pure composition
over the record defaults, NO change to the closed CommandRecord. The
reproducible zero-dependency equivalent already shipped as
docs/hand-written-keymap-override.md (v1.14); this is the tested package layer.

- bindHotkeys(registry, { keymap }) — an optional UserKeymap (sparse
  commandId → { replace | add | remove }) layered over each record's default
  keybinding at bind time. Default empty → existing callers unaffected.
  useHotkeys (React) forwards it and re-binds on keymap identity change (live
  remap UI).
- Pure keymap.ts: resolveKeys (override resolution); collectBindings gained a
  keymap param and orders user-touched bindings first on a shared key; and
  detectConflicts (definite/possible same-key clashes).
- Capture/display primitives: tokenFromEvent (press-to-record), isReservedCombo
  / RESERVED_COMBOS, formatKeybinding, layoutLabel (getLayoutMap w/ fallback).
- keymap.ts is tinykeys-free; bind.ts composes it (two-layer discipline).
- +14 tests (23 in the package; the 9 pre-existing bind tests still pass →
  backward-compatible). minor changeset (1.0.1 → 1.1.0).

Left to the app (primitives cover it): the full remap-UI React component,
preset packs, cloud sync, the WCAG "disable character-key shortcuts" toggle.

Claude-Session: https://claude.ai/code/session_016teVFousRsWNhiiPNpG1p9
---
 .changeset/hotkeys-keymap.md           |  26 +++
 .claude/skills/acture-hotkeys/SKILL.md |   2 +-
 docs/hand-written-keymap-override.md   |  17 +-
 docs/roadmap.md                        |  15 +-
 packages/hotkeys/README.md             |  30 ++++
 packages/hotkeys/src/bind.ts           |  44 +++--
 packages/hotkeys/src/index.ts          |  26 ++-
 packages/hotkeys/src/keymap.test.ts    | 135 ++++++++++++++++
 packages/hotkeys/src/keymap.ts         | 215 +++++++++++++++++++++++++
 packages/hotkeys/src/react.ts          |   8 +-
 10 files changed, 491 insertions(+), 27 deletions(-)
 create mode 100644 .changeset/hotkeys-keymap.md
 create mode 100644 packages/hotkeys/src/keymap.test.ts
 create mode 100644 packages/hotkeys/src/keymap.ts

diff --git a/.changeset/hotkeys-keymap.md b/.changeset/hotkeys-keymap.md
new file mode 100644
index 0000000..eab8db2
--- /dev/null
+++ b/.changeset/hotkeys-keymap.md
@@ -0,0 +1,26 @@
+---
+"acture-hotkeys": minor
+---
+
+Add **end-user keymap customization** — let a *user* (not just the developer)
+remap shortcuts and have the choice persist (research-10). Pure composition over
+the record defaults: no change to the closed `CommandRecord`.
+
+- **`bindHotkeys(registry, { keymap })`** — an optional `UserKeymap` (a sparse
+  `commandId → { replace | add | remove }` override map) layered over each
+  record's default `keybinding` at bind time. Default: an empty keymap, so
+  existing callers are unaffected. `useHotkeys` (React) forwards it and re-binds
+  on keymap identity change, so a live remap UI takes effect.
+- **`resolveKeys(cmd, keymap)`** — the pure override resolution; `collectBindings`
+  now accepts a keymap and orders user-touched bindings first on a shared key
+  (VS Code's "user override wins, scope still respected").
+- **`detectConflicts(registry, keymap?)`** — reports same-key clashes
+  (`definite` when no sharer is `when`-scoped, else `possible`) — the
+  highest-value remap affordance.
+- **Capture / display primitives:** `tokenFromEvent` (press-to-record),
+  `isReservedCombo` / `RESERVED_COMBOS` (reject browser-owned combos),
+  `formatKeybinding` (⌘/Ctrl labels), `layoutLabel` (`getLayoutMap` for physical
+  keys, with fallback).
+
+The reproducible zero-dependency equivalent is `docs/hand-written-keymap-override.md`;
+the full remap-UI React component stays the app's to build (the primitives cover it).
diff --git a/.claude/skills/acture-hotkeys/SKILL.md b/.claude/skills/acture-hotkeys/SKILL.md
index 842896c..683725f 100644
--- a/.claude/skills/acture-hotkeys/SKILL.md
+++ b/.claude/skills/acture-hotkeys/SKILL.md
@@ -45,7 +45,7 @@ This is a distinct, *composed* layer on top of the binder above — added when a
 - **Press-to-record capture** is the loved UX (Obsidian/JetBrains/games): listen → build the tinykeys token → reject browser/OS-reserved combos (`Cmd+W`, `Ctrl+T`, …) → conflict-check → commit to the keymap store. Persist the `UserKeymap` as JSON (localStorage/IndexedDB/server row); `$mod` keeps tokens portable across a user's machines.
 - **WCAG 2.1.4 (Level A) is mandatory once you ship single-key bindings** (`"d"`, `"g i"`): ship a global "disable character-key shortcuts" toggle or default single-key bindings off/focus-scoped. This is a legal requirement, not a nicety (research-10 §3.7).
 
-**Agent-written vs package-reuse** applies here too, decided per-piece: the `UserKeymap` + `resolveKeys` + keymap-aware `collectBindings` + conflict pass is ~50 hand-writable lines (the reference doc) that a project can own outright; the UI-and-browser-bound pieces — the press-to-record capture component, the `getLayoutMap()` display layer, preset loaders — are where an `acture-hotkeys` helper would earn its keep *if one ships*. Surface that split; it's the user's call (dev-tool-first). Handle every item on the research-10 §5.4 web-gotcha checklist (IME composition, macOS ⌘ keyup, `keydown` not `keypress`, `preventDefault` discipline).
+**Agent-written vs package-reuse** applies here too, decided per-piece — and the package accelerator **now ships**. The `UserKeymap` + `resolveKeys` + keymap-aware `collectBindings` + conflict pass is ~50 hand-writable lines (the reference doc) a project can own outright; OR install `acture-hotkeys`, which now exports the whole layer: `bindHotkeys(registry, { keymap })` (+ React `useHotkeys` re-binds on keymap change), `resolveKeys`, `detectConflicts`, and the capture/display primitives `tokenFromEvent` / `isReservedCombo` / `RESERVED_COMBOS` / `formatKeybinding` / `layoutLabel`. The **full remap-UI React component** stays the app's to build (the primitives cover it). Surface the split; it's the user's call (dev-tool-first). Handle every item on the research-10 §5.4 web-gotcha checklist (IME composition, macOS ⌘ keyup, `keydown` not `keypress`, `preventDefault` discipline).
 
 ## When working ON `acture-hotkeys`
 
diff --git a/docs/hand-written-keymap-override.md b/docs/hand-written-keymap-override.md
index 49db4c8..dd0f6b7 100644
--- a/docs/hand-written-keymap-override.md
+++ b/docs/hand-written-keymap-override.md
@@ -279,13 +279,16 @@ YAGNI applied softly — add these only when a real need appears:
 ## Faithfulness note
 
 The shapes here — `UserKeymap`, `KeybindingOverride`, `resolveKeys`,
-`collectBindings`, `detectConflicts` — are deliberately the shapes an
-`acture-hotkeys` customization helper would export, and `collectBindings` is a
-superset of the one already in `packages/hotkeys/src/bind.ts` (append a `km`
-argument *after* `tiers`; default it to `EMPTY_KEYMAP` so existing
-`collectBindings(registry, tiers)` calls are unaffected). An agent
-that hand-writes from this doc and later installs the helper finds the migration
-mechanical. If the package contract changes, this doc changes with it.
+`collectBindings`, `detectConflicts` — are deliberately the shapes
+**`acture-hotkeys` now exports** (`bindHotkeys({ keymap })`, `resolveKeys`,
+`detectConflicts`, plus the capture/display primitives `tokenFromEvent` /
+`isReservedCombo` / `formatKeybinding` / `layoutLabel`), and its `collectBindings`
+is a superset of this one (`collectBindings(registry, tiers?, keymap?)`; the
+`keymap` argument defaults to `EMPTY_KEYMAP` so existing
+`collectBindings(registry, tiers)` calls are unaffected). Hand-write from this
+doc, or install the package — the per-consumer choice (dev-tool-first). An agent
+that hand-writes and later installs finds the migration mechanical. If the
+package contract changes, this doc changes with it.
 
 ## See also
 
diff --git a/docs/roadmap.md b/docs/roadmap.md
index eb03402..2004805 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -4,7 +4,7 @@ The live forward-planning surface. `docs/v1_plan.md` and `docs/implementation_pl
 
 **How work proceeds:** phases are over. Work is small, tracked increments. Each picks one or two items from "Next" or "Deferred", ships them, updates this file, and replaces `docs/next_session.md` with the following handoff.
 
-Last updated: **2026-07-06** (v1.16 — acture-mcp read side completed with the portable `getState` tool; follows v1.15's resources projection).
+Last updated: **2026-07-06** (v1.17 — acture-hotkeys end-user keymap customization, the second v1.14-deferred accelerator).
 
 ---
 
@@ -147,6 +147,19 @@ Completes the read side started in v1.15. MCP **resources** are the correct read
 
 ---
 
+### v1.17 — acture-hotkeys: end-user keymap customization — complete (this increment)
+
+The second v1.14-deferred accelerator. Lets a **user** (not just the developer) remap shortcuts and have the choice persist (research-10) — pure composition over the record defaults, **no change to the closed `CommandRecord`**. The reproducible zero-dependency equivalent already shipped as `docs/hand-written-keymap-override.md` (v1.14); this is the tested `acture-hotkeys` accelerator.
+
+- **`bindHotkeys(registry, { keymap })`** — an optional `UserKeymap` (sparse `commandId → { replace | add | remove }`) layered over each record's default `keybinding` at bind time. Default empty → existing callers unaffected. `useHotkeys` (React) forwards it and re-binds on keymap identity change, so a live remap UI takes effect.
+- **Pure layer (`keymap.ts`):** `resolveKeys(cmd, keymap)` (override resolution); `collectBindings` gained a keymap param and orders user-touched bindings first on a shared key (VS Code's "user override wins, scope still respected"); `detectConflicts(registry, keymap?)` (`definite`/`possible` same-key clashes — the highest-value remap affordance).
+- **Capture / display primitives:** `tokenFromEvent` (press-to-record), `isReservedCombo` / `RESERVED_COMBOS` (reject browser-owned combos), `formatKeybinding` (⌘/Ctrl labels), `layoutLabel` (`getLayoutMap` for physical keys, with fallback).
+- **`McpToolDescriptor`-style discipline held:** the pure `keymap.ts` is tinykeys-free; `bind.ts` composes it. +14 tests (23 in the package; the 9 pre-existing bind tests still pass — backward-compatible). `minor` changeset (`acture-hotkeys` 1.0.1 → 1.1.0).
+- **Left to the app (the primitives cover it):** the full remap-UI React component, preset packs, cloud sync, WCAG "disable character-key shortcuts" toggle — documented, YAGNI-gated (research-10 §5 "deliberately omits").
+- **Still deferred:** the `sideEffect`/`requiresConfirmation` closed-surface question (the confirmation-gate work).
+
+---
+
 ## Next
 
 **The autonomous v1.12 + v1.13 chain is complete.** The remaining post-v1 items need user direction; the rewritten `docs/next_session.md` surfaces them. The candidates are: **`acture-state-jotai`** (atom-tree ↔ flat-state bridge is non-trivial per research-3; the adapter may not implement `PatchCapableAdapter` cleanly), **`acture-state-valtio`** (proxy-to-patch translation is non-trivial). (**`acture-sandbox`** is no longer a candidate — its isolation-only seam shipped in the extension-system increment; see below.) Pull-forward decisions are the user's; surface options with honest trade-offs when scheduled.
diff --git a/packages/hotkeys/README.md b/packages/hotkeys/README.md
index ce16e58..58bdadb 100644
--- a/packages/hotkeys/README.md
+++ b/packages/hotkeys/README.md
@@ -59,6 +59,36 @@ registry.register(commandB); // keybinding: 'g', when: '!editor.focused'
 
 If you want to *override* a base binding from a plugin, explicitly `unregister(id)` the base command first.
 
+## End-user customization — remapping shortcuts
+
+Let a **user** (not just the developer) remap shortcuts and have the choice persist. The record's `keybinding` stays the *developer default*; a sparse **`UserKeymap`** overrides it at bind time — pure composition, **no change to the `CommandRecord`** ([research-10](https://github.com/thorwhalen/acture/blob/main/docs/research/acture_research_10%20--%20End-User%20Keyboard-Shortcut%20Customization.md); reproducible core in [`docs/hand-written-keymap-override.md`](https://github.com/thorwhalen/acture/blob/main/docs/hand-written-keymap-override.md)).
+
+```ts
+import { bindHotkeys, type UserKeymap } from 'acture-hotkeys';
+
+const keymap: UserKeymap = {
+  version: 1,
+  overrides: {
+    'editor.save':   { kind: 'replace', keys: ['$mod+s'] }, // rebind
+    'editor.format': { kind: 'add',     keys: ['$mod+Shift+f'] }, // add a second binding
+    'app.help':      { kind: 'remove' }, // unbind
+  },
+};
+
+const stop = bindHotkeys(registry, { keymap });   // omit → record defaults, unchanged
+```
+
+`useHotkeys` forwards `keymap` and re-binds on its identity change, so a live settings UI takes effect. Persist the `UserKeymap` as JSON (localStorage / a server row); `$mod` keeps tokens portable across a user's machines.
+
+Build the remap UI from the exported primitives:
+
+- **`detectConflicts(registry, keymap?)`** → same-key clashes (`definite` / `possible`), for the "Already assigned to X — Reassign / Keep both / Cancel" flow.
+- **`tokenFromEvent(event)`** → a tinykeys token from a `keydown` (press-to-record); **`isReservedCombo(token)`** rejects browser-owned combos (`$mod+w`, `$mod+t`, …) that `preventDefault` can't reclaim.
+- **`formatKeybinding(token)`** → a ⌘/Ctrl label; **`layoutLabel(code)`** → a layout-correct label for physical (`event.code`) bindings via `navigator.keyboard.getLayoutMap()` (with fallback).
+- **`resolveKeys(cmd, keymap)`** / **`collectBindings(registry, tiers, keymap)`** → the resolution, if you build a custom binder.
+
+> **WCAG 2.1.4 (Level A):** if you ship single-key bindings (`"g i"`, `"d"`), also ship a "disable character-key shortcuts" toggle or default them off/focus-scoped — a legal requirement, not a nicety.
+
 ## Input-aware default
 
 By default, `bindHotkeys` skips firing when the target is an `<input>`, `<textarea>`, `<select>`, or `contentEditable` element — so users typing in a search box don't accidentally trigger the `g` key. Override via `shouldIgnoreEvent`.
diff --git a/packages/hotkeys/src/bind.ts b/packages/hotkeys/src/bind.ts
index 5713046..9e7c00c 100644
--- a/packages/hotkeys/src/bind.ts
+++ b/packages/hotkeys/src/bind.ts
@@ -16,6 +16,7 @@ import type {
   WhenClause,
 } from 'acture';
 import { evaluateWhen } from 'acture';
+import { resolveKeys, EMPTY_KEYMAP, type UserKeymap } from './keymap.js';
 
 /** Function that returns the current context for when-clause evaluation
  *  at hotkey-fire time. Kept as a provider (not a snapshot) so binding
@@ -47,6 +48,13 @@ export interface BindHotkeysOptions {
 
   /** Tier filter applied to candidate commands. Default: `['stable']`. */
   tiers?: readonly Tier[] | 'all';
+
+  /** Optional end-user keymap layered over the record defaults (research-10):
+   *  a sparse `commandId → { replace | add | remove }` override map. Captured
+   *  at bind time; to apply a *changed* keymap, `stop()` then re-`bindHotkeys`.
+   *  Default: an empty keymap (every command uses its record `keybinding`), so
+   *  existing callers are unaffected. See `./keymap.js`. */
+  keymap?: UserKeymap;
 }
 
 /** Internal: a binding-table entry. */
@@ -54,6 +62,10 @@ export interface HotkeyBindingDescriptor {
   readonly keySequence: string;
   readonly commandId: string;
   readonly when?: WhenClause;
+  /** True when this command carries a user keymap override. User-touched
+   *  descriptors sort BEFORE untouched defaults on the same key, so a user
+   *  rebinding wins the key (research-10 §5.2). Absent ⇒ default. */
+  readonly userTouched?: boolean;
 }
 
 const DEFAULT_IGNORE: (e: KeyboardEvent) => boolean = (event) => {
@@ -78,6 +90,7 @@ export function bindHotkeys(
   const contextProvider = options.contextProvider ?? (() => ({}));
   const shouldIgnoreEvent = options.shouldIgnoreEvent ?? DEFAULT_IGNORE;
   const tiers = options.tiers;
+  const keymap = options.keymap ?? EMPTY_KEYMAP;
 
   let teardown: (() => void) | null = null;
   let disposed = false;
@@ -85,7 +98,7 @@ export function bindHotkeys(
   function rebind(): void {
     teardown?.();
     if (disposed) return;
-    const table = collectBindings(registry, tiers);
+    const table = collectBindings(registry, tiers, keymap);
     if (table.size === 0) {
       teardown = () => {};
       return;
@@ -128,10 +141,17 @@ export function bindHotkeys(
 /**
  * Build the binding table: key-sequence → ordered list of candidates.
  * Exported for tests / debugging; not part of the day-to-day surface.
+ *
+ * `keymap` (default: empty) layers a user override over each record's default
+ * `keybinding` via {@link resolveKeys} — with an empty keymap this is exactly
+ * the record defaults, so the behaviour is unchanged. User-touched commands
+ * sort BEFORE untouched defaults on the same key, so a user rebinding wins the
+ * key while the fire-time when-clause scan (in `bindHotkeys`) is untouched.
  */
 export function collectBindings(
   registry: Registry,
   tiers?: readonly Tier[] | 'all',
+  keymap: UserKeymap = EMPTY_KEYMAP,
 ): Map<string, HotkeyBindingDescriptor[]> {
   const table = new Map<string, HotkeyBindingDescriptor[]>();
   // We intentionally do NOT pass `context` to `list()` — the when-clause
@@ -140,8 +160,8 @@ export function collectBindings(
   // when-clauses that depend on dynamic state (selection, focus, etc.).
   const list = registry.list(tiers !== undefined ? { tiers } : undefined);
   for (const cmd of list) {
-    const kbs = normalizeKeybinding(cmd.keybinding);
-    for (const kb of kbs) {
+    const userTouched = keymap.overrides[cmd.id] !== undefined;
+    for (const kb of resolveKeys(cmd, keymap)) {
       const key = parseKeybinding(kb);
       let arr = table.get(key);
       if (!arr) {
@@ -149,11 +169,17 @@ export function collectBindings(
         table.set(key, arr);
       }
       const desc: HotkeyBindingDescriptor = cmd.when !== undefined
-        ? { keySequence: key, commandId: cmd.id, when: cmd.when }
-        : { keySequence: key, commandId: cmd.id };
+        ? { keySequence: key, commandId: cmd.id, when: cmd.when, userTouched }
+        : { keySequence: key, commandId: cmd.id, userTouched };
       arr.push(desc);
     }
   }
+  // User-touched bindings win the key (research-10 §5.2). Array.sort is stable,
+  // so registration order is preserved within each group — and this is a no-op
+  // when no keymap is applied (every descriptor has userTouched === false).
+  for (const arr of table.values()) {
+    arr.sort((a, b) => Number(b.userTouched ?? false) - Number(a.userTouched ?? false));
+  }
   return table;
 }
 
@@ -166,11 +192,3 @@ export function collectBindings(
 export function parseKeybinding(kb: string): string {
   return kb.trim();
 }
-
-function normalizeKeybinding(
-  kb: AnyCommandRecord['keybinding'],
-): readonly string[] {
-  if (kb === undefined) return [];
-  if (typeof kb === 'string') return [kb];
-  return kb;
-}
diff --git a/packages/hotkeys/src/index.ts b/packages/hotkeys/src/index.ts
index 4b17e61..345f068 100644
--- a/packages/hotkeys/src/index.ts
+++ b/packages/hotkeys/src/index.ts
@@ -26,10 +26,34 @@
  *     useHotkeys(registry, { context });
  */
 
-export { bindHotkeys, parseKeybinding } from './bind.js';
+export { bindHotkeys, parseKeybinding, collectBindings } from './bind.js';
 export type {
   BindHotkeysOptions,
   HotkeyBindingDescriptor,
   HotkeyContextProvider,
   HotkeyDispatchListener,
 } from './bind.js';
+
+/**
+ * End-user keymap customization (research-10; `docs/hand-written-keymap-override.md`).
+ * Layer a sparse `UserKeymap` over the record defaults via `bindHotkeys`'s
+ * `keymap` option, and build a remap UI from the capture / conflict / display
+ * primitives:
+ *
+ *     import { detectConflicts, tokenFromEvent, formatKeybinding } from 'acture-hotkeys';
+ */
+export {
+  resolveKeys,
+  detectConflicts,
+  tokenFromEvent,
+  isReservedCombo,
+  formatKeybinding,
+  layoutLabel,
+  EMPTY_KEYMAP,
+  RESERVED_COMBOS,
+} from './keymap.js';
+export type {
+  UserKeymap,
+  KeybindingOverride,
+  KeymapConflict,
+} from './keymap.js';
diff --git a/packages/hotkeys/src/keymap.test.ts b/packages/hotkeys/src/keymap.test.ts
new file mode 100644
index 0000000..8689d45
--- /dev/null
+++ b/packages/hotkeys/src/keymap.test.ts
@@ -0,0 +1,135 @@
+/// <reference lib="dom" />
+
+import { describe, it, expect } from 'vitest';
+import { createRegistry, defineCommand, ok } from 'acture';
+import { collectBindings } from './bind.js';
+import {
+  resolveKeys,
+  detectConflicts,
+  tokenFromEvent,
+  isReservedCombo,
+  formatKeybinding,
+  EMPTY_KEYMAP,
+  type UserKeymap,
+} from './keymap.js';
+
+const cmd = (id: string, keybinding?: string | string[]) => ({ id, keybinding });
+
+describe('resolveKeys', () => {
+  it('returns the record default when no override exists', () => {
+    expect(resolveKeys(cmd('a', 'g'), EMPTY_KEYMAP)).toEqual(['g']);
+    expect(resolveKeys(cmd('a', ['g', 'h']), EMPTY_KEYMAP)).toEqual(['g', 'h']);
+    expect(resolveKeys(cmd('a'), EMPTY_KEYMAP)).toEqual([]);
+  });
+
+  it('replace / add / remove override the default', () => {
+    const km = (o: UserKeymap['overrides']): UserKeymap => ({ version: 1, overrides: o });
+    expect(resolveKeys(cmd('a', 'g'), km({ a: { kind: 'replace', keys: ['$mod+k'] } }))).toEqual([
+      '$mod+k',
+    ]);
+    expect(resolveKeys(cmd('a', 'g'), km({ a: { kind: 'add', keys: ['x'] } }))).toEqual(['g', 'x']);
+    expect(resolveKeys(cmd('a', 'g'), km({ a: { kind: 'remove' } }))).toEqual([]);
+  });
+});
+
+describe('collectBindings with a keymap', () => {
+  it('applies the override and sorts user-touched bindings first on a shared key', () => {
+    const registry = createRegistry();
+    registry.register(defineCommand({ id: 'default', title: 'D', keybinding: 'g', execute: () => ok(undefined) }));
+    registry.register(defineCommand({ id: 'user', title: 'U', keybinding: 'x', execute: () => ok(undefined) }));
+    // user remaps 'user' onto 'g', which 'default' already owns
+    const keymap: UserKeymap = { version: 1, overrides: { user: { kind: 'replace', keys: ['g'] } } };
+
+    const table = collectBindings(registry, undefined, keymap);
+    const onG = table.get('g')!.map((d) => d.commandId);
+    expect(onG).toEqual(['user', 'default']); // user-touched wins the key
+    expect(table.get('x')).toBeUndefined(); // 'x' was replaced away
+  });
+
+  it('is a no-op without a keymap (unchanged default behaviour)', () => {
+    const registry = createRegistry();
+    registry.register(defineCommand({ id: 'a', title: 'A', keybinding: 'g', execute: () => ok(undefined) }));
+    registry.register(defineCommand({ id: 'b', title: 'B', keybinding: 'g', execute: () => ok(undefined) }));
+    expect(collectBindings(registry).get('g')!.map((d) => d.commandId)).toEqual(['a', 'b']);
+  });
+});
+
+describe('detectConflicts', () => {
+  it('reports a definite conflict when two unscoped commands share a key', () => {
+    const registry = createRegistry();
+    registry.register(defineCommand({ id: 'a', title: 'A', keybinding: 'g', execute: () => ok(undefined) }));
+    registry.register(defineCommand({ id: 'b', title: 'B', keybinding: 'g', execute: () => ok(undefined) }));
+    const conflicts = detectConflicts(registry);
+    expect(conflicts).toEqual([
+      { keySequence: 'g', commandIds: ['a', 'b'], severity: 'definite' },
+    ]);
+  });
+
+  it('downgrades to "possible" when a sharer is when-scoped', () => {
+    const registry = createRegistry();
+    registry.register(defineCommand({ id: 'a', title: 'A', keybinding: 'g', execute: () => ok(undefined) }));
+    registry.register(defineCommand({ id: 'b', title: 'B', keybinding: 'g', when: 'editor.focused', execute: () => ok(undefined) }));
+    expect(detectConflicts(registry)[0]!.severity).toBe('possible');
+  });
+
+  it('reports nothing when keys are distinct', () => {
+    const registry = createRegistry();
+    registry.register(defineCommand({ id: 'a', title: 'A', keybinding: 'g', execute: () => ok(undefined) }));
+    registry.register(defineCommand({ id: 'b', title: 'B', keybinding: 'x', execute: () => ok(undefined) }));
+    expect(detectConflicts(registry)).toEqual([]);
+  });
+
+  it('surfaces a conflict introduced by a user override', () => {
+    const registry = createRegistry();
+    registry.register(defineCommand({ id: 'a', title: 'A', keybinding: 'g', execute: () => ok(undefined) }));
+    registry.register(defineCommand({ id: 'b', title: 'B', keybinding: 'x', execute: () => ok(undefined) }));
+    const keymap: UserKeymap = { version: 1, overrides: { b: { kind: 'replace', keys: ['g'] } } };
+    const conflicts = detectConflicts(registry, keymap);
+    expect(conflicts).toHaveLength(1);
+    expect(conflicts[0]!.commandIds.sort()).toEqual(['a', 'b']);
+  });
+});
+
+describe('tokenFromEvent', () => {
+  const ev = (init: KeyboardEventInit) => new KeyboardEvent('keydown', init);
+
+  it('builds a $mod token from a modified keypress', () => {
+    expect(tokenFromEvent(ev({ key: 'k', ctrlKey: true }))).toBe('$mod+k');
+    expect(tokenFromEvent(ev({ key: 'K', ctrlKey: true, shiftKey: true }))).toBe('$mod+Shift+k');
+    expect(tokenFromEvent(ev({ key: 'k', metaKey: true }))).toBe('$mod+k');
+  });
+
+  it('returns null for a lone modifier press', () => {
+    expect(tokenFromEvent(ev({ key: 'Control' }))).toBeNull();
+    expect(tokenFromEvent(ev({ key: 'Shift' }))).toBeNull();
+  });
+
+  it('emits event.code tokens in positional mode', () => {
+    expect(tokenFromEvent(ev({ key: 'w', code: 'KeyW', ctrlKey: true }), { mode: 'code' })).toBe(
+      '$mod+KeyW',
+    );
+  });
+});
+
+describe('isReservedCombo', () => {
+  it('flags browser/OS-reserved combos, order-independent', () => {
+    expect(isReservedCombo('$mod+w')).toBe(true);
+    expect(isReservedCombo('$mod+t')).toBe(true);
+    expect(isReservedCombo('$mod+Shift+w')).toBe(true);
+    expect(isReservedCombo('Shift+$mod+w')).toBe(true); // order-independent
+    expect(isReservedCombo('$mod+k')).toBe(false);
+    expect(isReservedCombo('g')).toBe(false);
+  });
+});
+
+describe('formatKeybinding', () => {
+  it('resolves $mod and symbols per platform', () => {
+    expect(formatKeybinding('$mod+k', { apple: false })).toBe('Ctrl+K');
+    expect(formatKeybinding('$mod+k', { apple: true })).toBe('⌘K');
+    expect(formatKeybinding('$mod+Shift+k', { apple: true })).toBe('⌘⇧K');
+  });
+
+  it('formats each combo of a chord', () => {
+    expect(formatKeybinding('g i', { apple: false })).toBe('G I');
+  });
+});
diff --git a/packages/hotkeys/src/keymap.ts b/packages/hotkeys/src/keymap.ts
new file mode 100644
index 0000000..ac731e8
--- /dev/null
+++ b/packages/hotkeys/src/keymap.ts
@@ -0,0 +1,215 @@
+/**
+ * End-user keymap customization — the layer that lets a *user* (not just the
+ * developer) remap shortcuts and have the choice persist. Pure and composed:
+ * the record's `keybinding` stays the developer default; a sparse `UserKeymap`
+ * overrides it at bind time, with **no change to the closed `CommandRecord`**
+ * (research-10 §5.1; reproducible reference: `docs/hand-written-keymap-override.md`).
+ *
+ * This module is tinykeys-free and (mostly) DOM-free — `resolveKeys` /
+ * `detectConflicts` are pure; `tokenFromEvent` / `isReservedCombo` /
+ * `formatKeybinding` are the capture/display primitives. `bindHotkeys`
+ * (in `bind.ts`) consumes `resolveKeys` via an optional `keymap` option.
+ */
+
+/// <reference lib="dom" />
+
+import type { AnyCommandRecord, Registry, Tier, WhenClause } from 'acture';
+import { evaluateWhen } from 'acture';
+
+/** One user override for a single command. `when` is deliberately NOT
+ *  overridable — users change keys, not availability scope — which dodges
+ *  VS Code's "empty-when shadows a scoped default" footgun (research-10 §3.2). */
+export type KeybindingOverride =
+  | { readonly kind: 'replace'; readonly keys: readonly string[] } // replace the record default
+  | { readonly kind: 'add'; readonly keys: readonly string[] } // keep default AND add these
+  | { readonly kind: 'remove' }; // unbind (VS Code's -command / Zed null)
+
+/** The persisted user keymap: SPARSE — only changed commands appear. A command
+ *  absent from `overrides` uses its record default. Survives registry churn:
+ *  a removed command just leaves a dead entry. JSON-serializable. */
+export interface UserKeymap {
+  readonly version: 1; // schema version, for future migration
+  readonly basePreset?: string; // e.g. 'vscode' | 'vim' — for portability
+  readonly overrides: Readonly<Record<string, KeybindingOverride>>;
+}
+
+/** The empty keymap — every command uses its record default. The default for
+ *  `bindHotkeys`'s `keymap` option, so existing callers are unaffected. */
+export const EMPTY_KEYMAP: UserKeymap = { version: 1, overrides: {} };
+
+/** Minimal record shape `resolveKeys` needs. `AnyCommandRecord` satisfies it. */
+type Keybindable = Pick<AnyCommandRecord, 'id' | 'keybinding'>;
+
+/** Normalize a record's `keybinding` (string | string[] | undefined) to an
+ *  array. Local copy — the binder's `normalizeKeybinding` is module-private. */
+function normalizeKeybinding(kb: Keybindable['keybinding']): string[] {
+  if (kb === undefined) return [];
+  return typeof kb === 'string' ? [kb] : [...kb];
+}
+
+/**
+ * Effective key sequences for one command, given the user layer. Returns the
+ * tinykeys tokens that should now trigger this command — the record default,
+ * replaced / augmented / removed per the override.
+ */
+export function resolveKeys(cmd: Keybindable, keymap: UserKeymap): string[] {
+  const override = keymap.overrides[cmd.id];
+  const base = normalizeKeybinding(cmd.keybinding);
+  if (!override) return base;
+  switch (override.kind) {
+    case 'remove':
+      return [];
+    case 'replace':
+      return [...override.keys];
+    case 'add':
+      return [...base, ...override.keys];
+  }
+}
+
+/** A same-key clash between two or more commands, after keymap resolution. */
+export interface KeymapConflict {
+  readonly keySequence: string;
+  readonly commandIds: string[];
+  /** `'definite'` when no command on the key has a `when` (they always
+   *  co-fire); `'possible'` when at least one is scoped (may be mutually
+   *  exclusive — acture can only prove exclusivity when neither is scoped). */
+  readonly severity: 'definite' | 'possible';
+}
+
+/**
+ * Report key sequences bound by ≥2 commands, after applying `keymap`. This is
+ * the highest-value customization affordance and the one most products get
+ * wrong (research-10 §3.5). Surface it at assignment time ("Already assigned
+ * to X — Reassign / Keep both / Cancel") and as a standing conflicts list.
+ *
+ * Same-key bindings whose `when` clauses are mutually exclusive are NOT a true
+ * conflict; acture can only *prove* that when neither is scoped, so anything
+ * with a `when` is reported `'possible'`, not `'definite'`.
+ */
+export function detectConflicts(
+  registry: Registry,
+  keymap: UserKeymap = EMPTY_KEYMAP,
+  options: { tiers?: readonly Tier[] | 'all' } = {},
+): KeymapConflict[] {
+  const table = new Map<string, Array<{ commandId: string; scoped: boolean }>>();
+  const list = registry.list(options.tiers !== undefined ? { tiers: options.tiers } : undefined);
+  for (const cmd of list) {
+    const scoped = (cmd as { when?: WhenClause }).when !== undefined;
+    for (const raw of resolveKeys(cmd, keymap)) {
+      const key = raw.trim();
+      const arr = table.get(key) ?? [];
+      arr.push({ commandId: cmd.id, scoped });
+      table.set(key, arr);
+    }
+  }
+  const conflicts: KeymapConflict[] = [];
+  for (const [keySequence, entries] of table) {
+    if (entries.length < 2) continue;
+    conflicts.push({
+      keySequence,
+      commandIds: entries.map((e) => e.commandId),
+      severity: entries.some((e) => e.scoped) ? 'possible' : 'definite',
+    });
+  }
+  return conflicts;
+}
+
+/* ─────────────────────────── capture primitives ─────────────────────────── */
+
+/**
+ * Build a tinykeys token from a `keydown` event — the core of press-to-record
+ * capture. Returns `null` for a lone modifier press (so the caller keeps
+ * listening). Matches on `event.key` by default (the tinykeys/acture mnemonic
+ * default); pass `mode: 'code'` for positional (WASD-style) tokens.
+ */
+export function tokenFromEvent(
+  event: KeyboardEvent,
+  options: { mode?: 'key' | 'code' } = {},
+): string | null {
+  const k = event.key;
+  if (k === 'Control' || k === 'Meta' || k === 'Shift' || k === 'Alt') return null;
+  const mods: string[] = [];
+  if (event.metaKey || event.ctrlKey) mods.push('$mod'); // portable primary modifier
+  if (event.shiftKey) mods.push('Shift');
+  if (event.altKey) mods.push('Alt');
+  const base = options.mode === 'code' ? event.code : k.length === 1 ? k.toLowerCase() : k;
+  return [...mods, base].join('+');
+}
+
+/** Browser/OS-reserved combos that `preventDefault()` cannot reclaim — a
+ *  rebind UI must reject them (research-10 §3.8). Stored as normalized tokens
+ *  (`$mod` for the primary modifier). Extend per the target environment. */
+export const RESERVED_COMBOS: ReadonlySet<string> = new Set([
+  '$mod+w',
+  '$mod+t',
+  '$mod+n',
+  '$mod+r',
+  '$mod+q',
+  '$mod+shift+w',
+  '$mod+shift+t',
+  '$mod+shift+n',
+  '$mod+l',
+]);
+
+/** Is this token a browser/OS-reserved combo the page cannot capture? */
+export function isReservedCombo(token: string): boolean {
+  const norm = token
+    .trim()
+    .toLowerCase()
+    .split('+')
+    .map((p) => p.trim())
+    .sort()
+    .join('+');
+  for (const reserved of RESERVED_COMBOS) {
+    const rn = reserved.toLowerCase().split('+').map((p) => p.trim()).sort().join('+');
+    if (rn === norm) return true;
+  }
+  return false;
+}
+
+/* ──────────────────────────── display helpers ───────────────────────────── */
+
+const IS_APPLE =
+  typeof navigator !== 'undefined' && /Mac|iPhone|iPod|iPad/.test(navigator.platform);
+
+/** Human-readable label for a tinykeys token, resolving `$mod` per platform
+ *  (⌘ on Apple, Ctrl elsewhere) and using symbols for modifiers. For a
+ *  chord (`"g i"`), each combo is formatted and joined with a space. */
+export function formatKeybinding(token: string, options: { apple?: boolean } = {}): string {
+  const apple = options.apple ?? IS_APPLE;
+  const mod = apple ? '⌘' : 'Ctrl';
+  const symbols: Record<string, string> = apple
+    ? { $mod: mod, shift: '⇧', alt: '⌥', ctrl: '⌃', meta: '⌘' }
+    : { $mod: mod, shift: 'Shift', alt: 'Alt', ctrl: 'Ctrl', meta: 'Meta' };
+  return token
+    .trim()
+    .split(/\s+/)
+    .map((combo) =>
+      combo
+        .split('+')
+        .map((part) => symbols[part.toLowerCase()] ?? (part.length === 1 ? part.toUpperCase() : part))
+        .join(apple ? '' : '+'),
+    )
+    .join(' ');
+}
+
+/**
+ * Layout-correct label for a **physical** (`event.code`) token, via
+ * `navigator.keyboard.getLayoutMap()` — so `KeyW` reads as "Z" on AZERTY
+ * (research-10 §3.4). Chromium-only and unavailable in cross-origin iframes;
+ * falls back to the raw code. Async by nature of the API.
+ */
+export async function layoutLabel(code: string): Promise<string> {
+  try {
+    const kb = (navigator as { keyboard?: { getLayoutMap?: () => Promise<Map<string, string>> } })
+      .keyboard;
+    if (kb?.getLayoutMap) {
+      const map = await kb.getLayoutMap();
+      const label = map.get(code);
+      if (label) return label.toUpperCase();
+    }
+  } catch {
+    // getLayoutMap can reject in cross-origin iframes — fall through.
+  }
+  return code;
+}
diff --git a/packages/hotkeys/src/react.ts b/packages/hotkeys/src/react.ts
index 7425bd9..39bb5b1 100644
--- a/packages/hotkeys/src/react.ts
+++ b/packages/hotkeys/src/react.ts
@@ -45,11 +45,11 @@ export function useHotkeys(
       contextProvider: () => ctxRef.current,
     });
     return stop;
-    // We deliberately do NOT depend on `rest` keys individually; the
-    // surface is small enough that callers who change `target` or
-    // `tiers` mid-flight should remount.
+    // Re-bind on `keymap` identity change so a live end-user remap UI takes
+    // effect (research-10). Other options (`target`, `tiers`) are static —
+    // callers who change those mid-flight should remount.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [registry, enabled]);
+  }, [registry, enabled, options.keymap]);
 }
 
 export type { BindHotkeysOptions, HotkeyDispatchListener };