@joewinke/jatui 0.26.0 → 0.27.1

package/dist/utils/keyboardShortcutRegistry.js

@@ -37,9 +37,66 @@
  *    browser (Chrome won't hand some of them to the page at all). The sidebar
  *    convention across JAT apps is `mod+\` — see `SIDEBAR_TOGGLE_KEY`.
  *
+ * Rebinding (jatui-voc3i.1): a definition with an `id` is rebindable. Its
+ * `key` is the DEFAULT; the effective binding is the user's override from a
+ * `BindingStore` (or `rebind()`), and registered entries re-resolve on every
+ * binding change, so components never re-register because a key moved.
+ * `declare()` makes ids known before their component mounts (a settings page
+ * can list a route's shortcuts without visiting the route). Combos are
+ * stored and compared in the canonical form `normalizeCombo()` produces.
+ * A stored entry that can't be parsed is never dropped silently: it is
+ * logged once (`console.warn`) and listed by `rejectedBindings()` with its
+ * raw value, so a settings page can show it.
+ *
+ * Conflicts (jatui-voc3i.2): `findConflicts(keys, { id | context })` and
+ * `allConflicts()` report collisions by how the stack resolves keys — same
+ * context is an error (one of them is dead), contexts that can be co-active
+ * (`contextGraph`; `global` is beneath everything) shadow with a warning, a
+ * modal upper context is info (they never compete), and `reserved`
+ * browser combos carry their own severity. `rebind()` rejects on any error.
+ *
+ * Beyond combos (jatui-voc3i.3): `onRelease` fires on the keyup of the
+ * same physical key (push-to-talk); `onModifierChange` reports held
+ * modifiers and is reset on blur; `registerHandler()` adds raw handlers
+ * (count prefixes, chords) that run inside the context walk after the
+ * context's combos, so modals still suppress them; `pushContext` takes a
+ * `layer` (frames sort by layer, then push order) and, for modal frames, a
+ * `passthrough` list of ids/combos that still reach the contexts beneath.
+ *
+ * Known divergences from the JAT IDE's legacy `shortcutParser` (an importer
+ * passed to `localStorageBindingStore({ migrate })` must account for them):
+ *  - `cmd`: the IDE maps `Cmd+K` to META on every platform; here `cmd` is
+ *    an alias of `mod` (Ctrl on Linux/Windows). Rewrite `cmd` → `meta`
+ *    when importing so a stored `Cmd+K` keeps meaning ⌘/Win.
+ *  - Physical-key fallback: the IDE falls back to `event.code` for LETTER
+ *    keys under any modifier (non-Latin layouts: Ctrl+K on a Cyrillic
+ *    layout). Here the `event.code` fallback applies only to alt combos and
+ *    to `` ` `` / Space; `ctrl+k` does not fire for `ctrl+л`.
+ *
  * Pure TypeScript, no Svelte runes and no DOM globals at import time, so it
  * is SSR-safe and unit-testable under plain node.
  */
+/**
+ * Browser-owned combos. `mod+t/w/n` block: Chrome
+ * never hands them to the page. The editing/navigation combos (and Ctrl+B,
+ * the bookmarks bar) are delivered but warn.
+ */
+export const BROWSER_RESERVED_COMBOS = [
+    { key: 'mod+t', reason: 'Browser: new tab', severity: 'block' },
+    { key: 'mod+w', reason: 'Browser: close tab', severity: 'block' },
+    { key: 'mod+n', reason: 'Browser: new window', severity: 'block' },
+    { key: 'mod+b', reason: 'Browser: bookmarks bar', severity: 'warn' },
+    { key: 'mod+c', reason: 'Browser: copy', severity: 'warn' },
+    { key: 'mod+v', reason: 'Browser: paste', severity: 'warn' },
+    { key: 'mod+x', reason: 'Browser: cut', severity: 'warn' },
+    { key: 'mod+z', reason: 'Browser: undo', severity: 'warn' },
+    { key: 'mod+y', reason: 'Browser: redo', severity: 'warn' },
+    { key: 'mod+a', reason: 'Browser: select all', severity: 'warn' },
+    { key: 'mod+s', reason: 'Browser: save page', severity: 'warn' },
+    { key: 'mod+f', reason: 'Browser: find', severity: 'warn' },
+    { key: 'mod+p', reason: 'Browser: print', severity: 'warn' },
+    { key: 'mod+r', reason: 'Browser: reload', severity: 'warn' }
+];
 /** The sidebar-toggle convention. Ctrl+B is reserved by Chrome (bookmarks bar). */
 export const SIDEBAR_TOGGLE_KEY = 'mod+\\';
 const GLOBAL = 'global';
@@ -50,6 +107,33 @@ export function detectPlatform() {
     const p = nav.userAgentData?.platform || nav.platform || nav.userAgent || '';
     return /mac|iphone|ipad|ipod/i.test(p) ? 'mac' : 'other';
 }
+/** Every spelling of a modifier the IDE (or a human) has ever written. */
+const MODIFIER_ALIASES = {
+    mod: 'mod',
+    cmd: 'mod',
+    meta: 'meta',
+    command: 'meta',
+    win: 'meta',
+    windows: 'meta',
+    super: 'meta',
+    ctrl: 'ctrl',
+    control: 'ctrl',
+    shift: 'shift',
+    alt: 'alt',
+    option: 'alt',
+    opt: 'alt'
+};
+/** Named-key aliases (case-insensitive) → the lowercased `KeyboardEvent.key` value. */
+const KEY_ALIASES = {
+    esc: 'escape',
+    space: ' ',
+    spacebar: ' ',
+    del: 'delete',
+    up: 'arrowup',
+    down: 'arrowdown',
+    left: 'arrowleft',
+    right: 'arrowright'
+};
 /** Parse `'mod+shift+k'` (plus any extra modifiers) into a normalized combo. */
 export function parseCombo(key, extra) {
     const combo = { key: '', mod: false, meta: false, ctrl: false, shift: false, alt: false };
@@ -61,15 +145,12 @@ export function parseCombo(key, extra) {
         base = parts.pop() ?? '';
         for (const p of parts) {
             const m = p.trim().toLowerCase();
-            if (m === 'mod' || m === 'cmd' || m === 'meta' || m === 'ctrl' || m === 'shift' || m === 'alt') {
-                mods.push(m);
-            }
-            else if (m === 'control')
-                mods.push('ctrl');
-            else if (m === 'option')
-                mods.push('alt');
-            else if (m)
+            if (!m)
+                continue;
+            const alias = MODIFIER_ALIASES[m];
+            if (!alias)
                 throw new Error(`keyboardShortcutRegistry: unknown modifier "${p}" in "${key}"`);
+            mods.push(alias);
         }
     }
     for (const m of mods) {
@@ -82,18 +163,42 @@ export function parseCombo(key, extra) {
     return combo;
 }
 function normalizeKey(key) {
-    if (key === 'Esc')
-        return 'escape';
-    if (key === 'Space' || key === 'Spacebar')
-        return ' ';
-    if (key === 'Del')
-        return 'delete';
-    return key.toLowerCase();
+    const k = key.toLowerCase();
+    return key.length > 1 ? (KEY_ALIASES[k] ?? k) : k;
+}
+const MODIFIER_ORDER = ['mod', 'meta', 'ctrl', 'alt', 'shift'];
+function comboToString(c) {
+    const parts = MODIFIER_ORDER.filter((m) => c[m]);
+    parts.push(c.key === ' ' ? 'space' : c.key);
+    return parts.join('+');
+}
+/**
+ * Canonical, order-stable form used for storage and equality:
+ * `"alt+shift+s"`, `"mod+k"`, `"ctrl+\`"`, `"space"`, `"mod++"`. Modifier
+ * order is mod, meta, ctrl, alt, shift. `mod` is never introduced: a stored
+ * `Ctrl+K` stays `ctrl+k`. Throws on an unknown modifier (see `validateCombo`).
+ */
+export function normalizeCombo(key, extra) {
+    return comboToString(parseCombo(key, extra));
 }
 /** A single printable non-letter (`?`, `/`, `\`, `1`): its shift state is baked into the char. */
 function isSymbolKey(key) {
     return key.length === 1 && key.toLowerCase() === key.toUpperCase() && key !== ' ';
 }
+const CODE_KEYS = {
+    Backslash: '\\',
+    Slash: '/',
+    Backquote: '`',
+    Space: ' ',
+    Minus: '-',
+    Equal: '=',
+    BracketLeft: '[',
+    BracketRight: ']',
+    Semicolon: ';',
+    Quote: "'",
+    Comma: ',',
+    Period: '.'
+};
 function codeToKey(code) {
     if (!code)
         return null;
@@ -101,19 +206,17 @@ function codeToKey(code) {
         return code.slice(3).toLowerCase();
     if (/^Digit\d$/.test(code))
         return code.slice(5);
-    if (code === 'Backslash')
-        return '\\';
-    if (code === 'Slash')
-        return '/';
-    return null;
+    return CODE_KEYS[code] ?? null;
 }
 function matches(event, combo, platform) {
     const evKey = normalizeKey(event.key ?? '');
     let keyHit = evKey === combo.key;
-    // macOS Option (and some layouts) rewrite event.key for alt combos — fall
-    // back to the physical key when alt is part of the shortcut.
-    if (!keyHit && combo.alt)
+    // macOS Option (and some layouts) rewrite event.key for alt combos, and
+    // `` ` `` / Space vary by layout with any modifier — fall back to the
+    // physical key for those.
+    if (!keyHit && (combo.alt || combo.key === '`' || combo.key === ' ')) {
         keyHit = codeToKey(event.code) === combo.key;
+    }
     if (!keyHit)
         return false;
     const wantMeta = combo.meta || (combo.mod && platform === 'mac');
@@ -129,6 +232,76 @@ function matches(event, combo, platform) {
         return true;
     return !!event.shiftKey === combo.shift;
 }
+const MODIFIER_KEY_NAMES = new Set([
+    'control', 'ctrl', 'shift', 'alt', 'option', 'meta', 'os', 'super', 'hyper', 'altgraph',
+    'capslock', 'fn', 'fnlock', 'numlock', 'scrolllock', 'symbol', 'symbollock', 'cmd', 'command', 'win', 'windows'
+]);
+const NAMED_KEYS = new Set([
+    'escape', 'enter', 'tab', 'backspace', 'delete', 'insert', 'home', 'end', 'pageup', 'pagedown',
+    'arrowup', 'arrowdown', 'arrowleft', 'arrowright', 'contextmenu', 'pause', 'printscreen',
+    'mediaplaypause', 'mediatracknext', 'mediatrackprevious', 'mediastop',
+    'audiovolumeup', 'audiovolumedown', 'audiovolumemute'
+]);
+/**
+ * Canonical combo for a live keydown (a settings "press the new shortcut"
+ * recorder). Null while only modifiers are down, or when the key can't be
+ * identified. Ctrl/Meta are reported literally (never `mod`). Uses the
+ * physical key when macOS Option (or a dead key / non-ASCII layout) hides it.
+ */
+export function comboFromEvent(event, platform = detectPlatform()) {
+    const raw = event.key ?? '';
+    if (!raw || MODIFIER_KEY_NAMES.has(raw.toLowerCase()))
+        return null;
+    const fromCode = codeToKey(event.code);
+    const unusable = raw === 'Dead' || raw === 'Unidentified' || raw === 'Process';
+    let key = normalizeKey(raw);
+    let usedCode = false;
+    const nonAscii = key.length === 1 && !/^[\x20-\x7e]$/.test(key);
+    if (fromCode && (unusable || (event.altKey && (platform === 'mac' || nonAscii)))) {
+        key = fromCode;
+        usedCode = true;
+    }
+    else if (unusable) {
+        return null;
+    }
+    return comboToString({
+        key,
+        mod: false,
+        meta: !!event.metaKey,
+        ctrl: !!event.ctrlKey,
+        alt: !!event.altKey,
+        // `?` is already Shift+/ — keep shift implied, exactly as matching does.
+        shift: !!event.shiftKey && !(isSymbolKey(key) && !usedCode)
+    });
+}
+/**
+ * Structural validation for a user-entered binding. Null means valid,
+ * otherwise a human-readable reason. `requireModifier` demands Ctrl, Alt,
+ * Meta or mod (Shift alone doesn't count) — the IDE's rule for global ids.
+ */
+export function validateCombo(key, options = {}) {
+    if (!key || !key.trim())
+        return 'Shortcut is empty';
+    let c;
+    try {
+        c = parseCombo(key);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message.replace(/^keyboardShortcutRegistry: /, '') : String(err);
+        return msg.charAt(0).toUpperCase() + msg.slice(1);
+    }
+    if (!c.key)
+        return 'Shortcut must include a key (e.g. A, 1, Enter)';
+    if (MODIFIER_KEY_NAMES.has(c.key))
+        return 'Shortcut must include a non-modifier key';
+    if (c.key.length > 1 && !NAMED_KEYS.has(c.key) && !/^f([1-9]|1\d|2[0-4])$/.test(c.key)) {
+        return `Unknown key "${key.split('+').pop()}"`;
+    }
+    if (options.requireModifier && !(c.mod || c.meta || c.ctrl || c.alt)) {
+        return 'Shortcut must include Ctrl, Alt or Meta';
+    }
+    return null;
+}
 const NON_TEXT_INPUT_TYPES = new Set([
     'button', 'checkbox', 'color', 'file', 'hidden', 'image', 'radio', 'range', 'reset', 'submit'
 ]);
@@ -162,12 +335,7 @@ const KEY_GLYPHS = {
     home: 'Home',
     end: 'End'
 };
-/** Keycap label: `⌘⇧K` on macOS, `Ctrl+Shift+K` elsewhere. */
-export function formatShortcut(shortcut, platform = detectPlatform()) {
-    const def = typeof shortcut === 'string' ? null : shortcut;
-    if (def?.label)
-        return def.label;
-    const combo = def ? parseCombo(def.key, def.modifiers) : parseCombo(shortcut);
+function formatCombo(combo, platform) {
     const k = combo.key;
     const keyLabel = KEY_GLYPHS[k] ?? (/^f\d{1,2}$/.test(k) ? k.toUpperCase() : k.length === 1 ? k.toUpperCase() : k);
     if (platform === 'mac') {
@@ -194,51 +362,682 @@ export function formatShortcut(shortcut, platform = detectPlatform()) {
     parts.push(keyLabel);
     return parts.join('+');
 }
+/** Keycap label: `⌘⇧K` on macOS, `Ctrl+Shift+K` elsewhere. Several keys join with `' / '`. */
+export function formatShortcut(shortcut, platform = detectPlatform()) {
+    if (typeof shortcut === 'string')
+        return formatCombo(parseCombo(shortcut), platform);
+    if (shortcut.label)
+        return shortcut.label;
+    return toArray(shortcut.key)
+        .map((k) => formatCombo(parseCombo(k, shortcut.modifiers), platform))
+        .join(' / ');
+}
+function toArray(v) {
+    return Array.isArray(v) ? v : [v];
+}
+function hasOwn(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+/**
+ * Canonicalize stored overrides. Anything unusable — a non-object blob, a
+ * non-array value, an unparsable combo — is handed to `reject`, never just
+ * dropped.
+ */
+function sanitizeOverrides(raw, reject) {
+    const out = {};
+    if (raw === null || raw === undefined)
+        return out;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        reject({ id: '*', raw, reason: 'Stored bindings are not an object of id → combos' });
+        return out;
+    }
+    for (const [id, value] of Object.entries(raw)) {
+        if (!Array.isArray(value)) {
+            reject({ id, raw: value, reason: 'Expected an array of combos' });
+            continue;
+        }
+        const combos = [];
+        for (const k of value) {
+            const err = typeof k === 'string' ? validateCombo(k) : 'Combo is not a string';
+            if (err !== null) {
+                reject({ id, raw: k, reason: err });
+                continue;
+            }
+            const n = normalizeCombo(k);
+            if (!combos.includes(n))
+                combos.push(n);
+        }
+        // A non-empty list with nothing usable is a bad record, not "unbound".
+        if (value.length > 0 && combos.length === 0)
+            continue;
+        out[id] = combos;
+    }
+    return out;
+}
+function isThenable(v) {
+    return !!v && typeof v.then === 'function';
+}
+function defaultDev() {
+    try {
+        const env = import.meta.env;
+        if (env && typeof env.DEV === 'boolean')
+            return env.DEV;
+    }
+    catch {
+        // import.meta.env absent outside vite
+    }
+    const proc = globalThis.process;
+    return proc?.env?.NODE_ENV !== 'production';
+}
+function warnStore(error) {
+    console.warn('keyboardShortcutRegistry: binding store failed', error);
+}
+function isRejectedBinding(v) {
+    const r = v;
+    return !!r && typeof r === 'object' && typeof r.id === 'string' && typeof r.reason === 'string' && 'raw' in r;
+}
+/** A rejected-entry collector that warns once per distinct entry. */
+function rejectCollector() {
+    let list = [];
+    const warned = new Set();
+    const keyOf = (r) => `${r.id}\u0000${JSON.stringify(r.raw) ?? String(r.raw)}`;
+    return {
+        add(r) {
+            const k = keyOf(r);
+            if (list.some((x) => keyOf(x) === k))
+                return;
+            list.push(r);
+            if (warned.has(k))
+                return;
+            warned.add(k);
+            console.warn(`keyboardShortcutRegistry: rejected stored binding "${r.id}" (${JSON.stringify(r.raw)}): ${r.reason}`);
+        },
+        reset() {
+            list = [];
+        },
+        list: () => [...list]
+    };
+}
+/**
+ * Versioned localStorage `BindingStore`: `{ v: 1, bindings, rejected? }`.
+ * Tolerates corrupt JSON, a foreign shape and unavailable storage (private
+ * mode, SSR) — all read as "no overrides". `migrate` runs only when
+ * `storageKey` is absent, and its result (even an empty one) is written so
+ * it runs once. Entries it can't parse (from storage or from `migrate`) are
+ * warned once, exposed via `rejected()`, and kept in the stored `rejected`
+ * list so a later save doesn't lose them.
+ * `syncTabs` (default true) forwards other tabs' writes via `storage` events.
+ */
+export function localStorageBindingStore(storageKey, options = {}) {
+    function storage() {
+        try {
+            return globalThis.localStorage ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    const rejected = rejectCollector();
+    /** Read a stored blob; refreshes `rejected` to what this blob carries. */
+    function decode(raw) {
+        rejected.reset();
+        if (raw === null)
+            return {};
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            rejected.add({ id: '*', raw, reason: 'Stored bindings are not valid JSON' });
+            return {};
+        }
+        if (!parsed || typeof parsed !== 'object' || parsed.v !== 1) {
+            rejected.add({ id: '*', raw, reason: 'Unrecognised bindings format (expected { v: 1, bindings })' });
+            return {};
+        }
+        if (Array.isArray(parsed.rejected)) {
+            for (const r of parsed.rejected)
+                if (isRejectedBinding(r))
+                    rejected.add(r);
+        }
+        return sanitizeOverrides(parsed.bindings, rejected.add);
+    }
+    function write(overrides) {
+        const list = rejected.list();
+        try {
+            storage()?.setItem(storageKey, JSON.stringify({ v: 1, bindings: overrides, ...(list.length ? { rejected: list } : {}) }));
+        }
+        catch (err) {
+            warnStore(err);
+        }
+    }
+    return {
+        load() {
+            let raw = null;
+            try {
+                raw = storage()?.getItem(storageKey) ?? null;
+            }
+            catch {
+                return {};
+            }
+            if (raw !== null || !options.migrate)
+                return decode(raw);
+            let migrated = {};
+            rejected.reset();
+            try {
+                migrated = sanitizeOverrides(options.migrate(), rejected.add);
+            }
+            catch (err) {
+                warnStore(err);
+            }
+            write(migrated);
+            return migrated;
+        },
+        save: write,
+        subscribe(listener) {
+            const w = globalThis.window;
+            if (options.syncTabs === false || !w || typeof w.addEventListener !== 'function')
+                return () => { };
+            const onStorage = (e) => {
+                // key === null is localStorage.clear()
+                if (e.key !== storageKey && e.key !== null)
+                    return;
+                listener(decode(e.key === null ? null : e.newValue));
+            };
+            w.addEventListener('storage', onStorage);
+            return () => w.removeEventListener('storage', onStorage);
+        },
+        rejected: rejected.list
+    };
+}
 export function createShortcutRegistry(options = {}) {
     const platform = options.platform ?? detectPlatform();
     const labels = { [GLOBAL]: 'General', ...options.contextLabels };
     const onError = options.onError ??
         ((error) => console.error('keyboardShortcutRegistry: shortcut action failed', error));
+    const dev = options.dev ?? defaultDev();
+    const store = options.bindings;
+    const graph = options.contextGraph ?? {};
+    // Remembered for conflict reporting: a context once pushed modal stays modal.
+    const modalContexts = new Set(options.modalContexts ?? []);
+    const reservedPhysical = (options.reserved ?? BROWSER_RESERVED_COMBOS).map((r) => ({
+        physical: physical(normalizeCombo(r.key)),
+        reason: r.reason,
+        severity: r.severity
+    }));
     const entries = [];
+    const declarations = [];
+    const handlers = [];
     const stack = [];
     const listeners = new Set();
     let seq = 0;
+    let pushSeq = 0;
+    const typingTest = options.isTypingTarget ?? ((target) => isTypingTarget(target));
+    // Pending `onRelease` calls, keyed by physical key.
+    const pendingReleases = new Map();
+    let modifiers = { alt: false, ctrl: false, shift: false, meta: false };
+    let overrides = {};
+    // Edits made before the store finished loading are replayed on top of it.
+    let loaded = !store;
+    const preLoadEdits = new Map();
+    let preLoadResetAll = false;
+    // Entries a custom store handed back unparsed (localStorageBindingStore
+    // rejects its own before they get here).
+    const rejected = rejectCollector();
     function notify() {
         for (const l of [...listeners])
             l();
     }
+    function isRebindable(def) {
+        return !!def.id && (def.rebindable ?? true);
+    }
+    function isCustom(def) {
+        return isRebindable(def) && hasOwn(overrides, def.id);
+    }
+    function defaultsOf(def) {
+        const out = [];
+        for (const k of toArray(def.key)) {
+            const n = normalizeCombo(k, def.modifiers);
+            if (!out.includes(n))
+                out.push(n);
+        }
+        return out;
+    }
+    function currentOf(def) {
+        return isCustom(def) ? [...overrides[def.id]] : defaultsOf(def);
+    }
+    /** Same physical combo on this platform (`mod` resolved, implied shift dropped). */
+    function physical(canonical) {
+        const c = parseCombo(canonical);
+        if (c.mod) {
+            c.mod = false;
+            if (platform === 'mac')
+                c.meta = true;
+            else
+                c.ctrl = true;
+        }
+        if (isSymbolKey(c.key))
+            c.shift = false;
+        return comboToString(c);
+    }
+    function resolve(entry) {
+        entry.canon = currentOf(entry.def);
+        entry.combos = entry.canon.map((c) => parseCombo(c));
+    }
+    function reresolveAll() {
+        for (const e of entries)
+            if (e.def.id)
+                resolve(e);
+    }
+    function persist() {
+        if (!store || !loaded)
+            return;
+        try {
+            const r = store.save({ ...overrides });
+            if (isThenable(r))
+                Promise.resolve(r).catch(warnStore);
+        }
+        catch (err) {
+            warnStore(err);
+        }
+    }
+    function applyOverrides(next, { replay }) {
+        const hadEdits = replay && (preLoadResetAll || preLoadEdits.size > 0);
+        const base = replay && preLoadResetAll ? {} : next;
+        if (replay) {
+            for (const [id, v] of preLoadEdits) {
+                if (v === null)
+                    delete base[id];
+                else
+                    base[id] = v;
+            }
+            preLoadEdits.clear();
+            preLoadResetAll = false;
+        }
+        overrides = base;
+        loaded = true;
+        reresolveAll();
+        if (hadEdits)
+            persist();
+        notify();
+    }
+    function setOverride(id, keys, defaults) {
+        const same = keys.length === defaults.length && keys.every((k) => defaults.includes(k));
+        if (same)
+            delete overrides[id];
+        else
+            overrides[id] = keys;
+        if (!loaded)
+            preLoadEdits.set(id, same ? null : keys);
+    }
+    function commit() {
+        reresolveAll();
+        persist();
+        notify();
+    }
+    /** Latest live registration for `id`, else its latest declaration. */
+    function sourceOf(id) {
+        for (let i = entries.length - 1; i >= 0; i--) {
+            if (entries[i].def.id === id)
+                return entries[i];
+        }
+        for (let i = declarations.length - 1; i >= 0; i--) {
+            if (declarations[i].def.id === id)
+                return declarations[i];
+        }
+        return undefined;
+    }
+    function binding(id) {
+        const src = sourceOf(id);
+        if (!src)
+            return undefined;
+        const defaults = defaultsOf(src.def);
+        const custom = isCustom(src.def);
+        return {
+            id,
+            description: src.def.description,
+            context: src.context,
+            group: src.def.group,
+            defaults,
+            current: custom ? [...overrides[id]] : defaults,
+            isCustom: custom,
+            rebindable: isRebindable(src.def)
+        };
+    }
+    function bindings() {
+        const firstSeen = new Map();
+        for (const x of [...declarations, ...entries]) {
+            const id = x.def.id;
+            if (id && (!firstSeen.has(id) || x.seq < firstSeen.get(id)))
+                firstSeen.set(id, x.seq);
+        }
+        return [...firstSeen.entries()]
+            .sort((a, b) => a[1] - b[1])
+            .map(([id]) => binding(id))
+            .filter(Boolean);
+    }
+    /** Every live definition: registrations, plus declarations no registration covers yet. */
+    function units() {
+        const live = new Set(entries.filter((e) => e.def.id).map((e) => `${e.def.id}\u0000${e.context}`));
+        return [
+            ...entries,
+            ...declarations
+                .filter((d) => !live.has(`${d.def.id}\u0000${d.context}`))
+                .map((d) => ({ ...d, canon: currentOf(d.def) }))
+        ];
+    }
+    function contextsOf(id) {
+        const out = [];
+        for (const x of [...entries, ...declarations]) {
+            if (x.def.id === id && !out.includes(x.context))
+                out.push(x.context);
+        }
+        return out;
+    }
+    /** Can `upper` be on the stack ABOVE `lower`? (`contextGraph`, transitive; `global` is beneath all.) */
+    function above(upper, lower) {
+        if (upper === lower || upper === GLOBAL)
+            return false;
+        if (lower === GLOBAL)
+            return true;
+        const seen = new Set();
+        const todo = [...(graph[upper] ?? [])];
+        while (todo.length) {
+            const c = todo.pop();
+            if (c === lower)
+                return true;
+            if (seen.has(c))
+                continue;
+            seen.add(c);
+            todo.push(...(graph[c] ?? []));
+        }
+        return false;
+    }
+    function isModalContext(ctx) {
+        return modalContexts.has(ctx);
+    }
+    /** How a candidate in `cand` relates to a definition in `other` on the same combo. */
+    function classify(cand, other) {
+        if (cand === other)
+            return { kind: 'same-context', severity: 'error' };
+        const upper = above(cand, other) ? cand : above(other, cand) ? other : null;
+        if (upper === null)
+            return null; // never on the stack together
+        if (isModalContext(upper))
+            return { kind: 'modal-blocked', severity: 'info' };
+        return upper === cand ? { kind: 'shadows', severity: 'warning' } : { kind: 'shadowed-by', severity: 'warning' };
+    }
+    function reservedConflicts(combo) {
+        const p = physical(combo);
+        return reservedPhysical
+            .filter((r) => r.physical === p)
+            .map((r) => ({
+            combo,
+            description: r.reason,
+            context: 'browser',
+            kind: 'reserved',
+            severity: r.severity === 'block' ? 'error' : 'warning'
+        }));
+    }
+    function findConflicts(keys, target = {}) {
+        const combos = [];
+        for (const k of toArray(keys)) {
+            if (validateCombo(k) !== null)
+                continue;
+            const n = normalizeCombo(k);
+            if (!combos.some((c) => physical(c) === physical(n)))
+                combos.push(n);
+        }
+        if (!combos.length)
+            return [];
+        const known = target.id ? contextsOf(target.id) : [];
+        const contexts = target.context ? [target.context] : known.length ? known : [GLOBAL];
+        const wanted = new Map(combos.map((c) => [physical(c), c]));
+        const out = [];
+        const seen = new Set();
+        for (const ctx of contexts) {
+            for (const u of units()) {
+                if (target.id && u.def.id === target.id)
+                    continue;
+                const rel = classify(ctx, u.context);
+                if (!rel)
+                    continue;
+                for (const c of u.canon) {
+                    const combo = wanted.get(physical(c));
+                    if (combo === undefined)
+                        continue;
+                    const key = `${u.def.id ?? `#${u.seq}`}|${u.context}|${combo}|${rel.kind}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    out.push({
+                        combo,
+                        ...(u.def.id ? { id: u.def.id } : {}),
+                        description: u.def.description,
+                        context: u.context,
+                        ...rel
+                    });
+                }
+            }
+        }
+        for (const c of combos)
+            out.push(...reservedConflicts(c));
+        return out;
+    }
+    const SEVERITY_RANK = { info: 0, warning: 1, error: 2 };
+    function allConflicts(opts = {}) {
+        const min = SEVERITY_RANK[opts.minSeverity ?? 'info'];
+        const all = units().sort((a, b) => a.seq - b.seq);
+        const out = [];
+        const sourceOfUnit = (u) => ({
+            ...(u.def.id ? { id: u.def.id } : {}),
+            description: u.def.description,
+            context: u.context
+        });
+        for (let i = 0; i < all.length; i++) {
+            const cand = all[i];
+            // The candidate is the NEWER of each pair, so it is compared with older units only.
+            for (let j = 0; j < i; j++) {
+                const other = all[j];
+                if (cand.def.id && cand.def.id === other.def.id)
+                    continue;
+                const rel = classify(cand.context, other.context);
+                if (!rel || SEVERITY_RANK[rel.severity] < min)
+                    continue;
+                const theirs = new Set(other.canon.map(physical));
+                for (const c of cand.canon) {
+                    if (!theirs.has(physical(c)))
+                        continue;
+                    out.push({
+                        combo: c,
+                        ...(other.def.id ? { id: other.def.id } : {}),
+                        description: other.def.description,
+                        context: other.context,
+                        ...rel,
+                        source: sourceOfUnit(cand)
+                    });
+                }
+            }
+            for (const c of cand.canon) {
+                for (const r of reservedConflicts(c)) {
+                    if (SEVERITY_RANK[r.severity] >= min)
+                        out.push({ ...r, source: sourceOfUnit(cand) });
+                }
+            }
+        }
+        return out;
+    }
+    function rebind(id, keys, opts = {}) {
+        const fail = (error, conflicts = []) => ({ ok: false, error, conflicts });
+        const src = sourceOf(id);
+        if (!src)
+            return fail(`Unknown shortcut id "${id}"`);
+        if (!isRebindable(src.def))
+            return fail(`"${src.def.description}" can't be rebound`);
+        const next = [];
+        for (const k of keys === null ? [] : toArray(keys)) {
+            const err = validateCombo(k);
+            if (err)
+                return fail(err);
+            const n = normalizeCombo(k);
+            if (!next.some((x) => physical(x) === physical(n)))
+                next.push(n);
+        }
+        const conflicts = findConflicts(next, { id });
+        const errors = conflicts.filter((c) => c.severity === 'error');
+        const mode = opts.onConflict ?? 'reject';
+        const displaced = [];
+        if (errors.length && mode !== 'allow') {
+            // The browser never delivers a blocked combo; no swap can fix that.
+            const blocked = errors.find((c) => c.kind === 'reserved');
+            if (blocked) {
+                return fail(`${formatShortcut(blocked.combo, platform)} is reserved (${blocked.description})`, conflicts);
+            }
+            const first = errors[0];
+            const msg = `${formatShortcut(first.combo, platform)} is already used by "${first.description}"`;
+            if (mode === 'reject')
+                return fail(msg, conflicts);
+            // swap: only possible when every owner is itself rebindable.
+            const fixed = errors.find((c) => {
+                const owner = c.id ? sourceOf(c.id) : undefined;
+                return !owner || !isRebindable(owner.def);
+            });
+            if (fixed) {
+                return fail(`${formatShortcut(fixed.combo, platform)} belongs to "${fixed.description}", which can't be rebound`, conflicts);
+            }
+            for (const c of errors) {
+                const other = binding(c.id);
+                const remaining = other.current.filter((k) => physical(k) !== physical(c.combo));
+                setOverride(c.id, remaining, other.defaults);
+                if (!displaced.includes(c.id))
+                    displaced.push(c.id);
+            }
+        }
+        setOverride(id, next, defaultsOf(src.def));
+        commit();
+        const remaining = mode === 'allow' ? conflicts : conflicts.filter((c) => c.severity !== 'error');
+        return { ok: true, binding: binding(id), displaced, conflicts: remaining };
+    }
+    function resetBinding(id) {
+        if (loaded && !hasOwn(overrides, id))
+            return;
+        delete overrides[id];
+        if (!loaded)
+            preLoadEdits.set(id, null);
+        commit();
+    }
+    function resetAllBindings() {
+        overrides = {};
+        if (!loaded) {
+            preLoadEdits.clear();
+            preLoadResetAll = true;
+        }
+        commit();
+    }
+    function declare(defs) {
+        const added = toArray(defs)
+            .filter((def) => !!def.id)
+            .map((def) => {
+            defaultsOf(def); // throw on a malformed key now, not at render time
+            const d = { def, context: def.context ?? GLOBAL, seq: seq++ };
+            declarations.push(d);
+            return d;
+        });
+        notify();
+        let done = false;
+        return () => {
+            if (done)
+                return;
+            done = true;
+            for (const d of added) {
+                const i = declarations.indexOf(d);
+                if (i !== -1)
+                    declarations.splice(i, 1);
+            }
+            notify();
+        };
+    }
+    /**
+     * The walk order, top first: frames sorted by layer then push order. A
+     * modal frame ends the walk unless it has a passthrough list, in which case
+     * the contexts beneath are visited with that frame as a filter. A context
+     * already visited higher up is not visited again.
+     */
+    function liveContexts() {
+        const frames = [...stack].sort((a, b) => a.layer - b.layer || a.order - b.order);
+        const out = [];
+        const seen = new Set();
+        const filters = [];
+        const visit = (name) => {
+            if (seen.has(name))
+                return;
+            seen.add(name);
+            out.push({ name, filters: [...filters] });
+        };
+        for (let i = frames.length - 1; i >= 0; i--) {
+            const f = frames[i];
+            visit(f.name);
+            if (f.modal) {
+                if (!f.passIds.size && !f.passPhysical.size)
+                    return out;
+                filters.push(f);
+            }
+        }
+        visit(GLOBAL);
+        return out;
+    }
+    /** Does a definition beneath passthrough modal frames get through all of them? */
+    function passes(def, canon, filters) {
+        return filters.every((f) => (!!def.id && f.passIds.has(def.id)) || canon.some((c) => f.passPhysical.has(physical(c))));
+    }
     function activeContexts() {
-        const live = [];
-        for (let i = stack.length - 1; i >= 0; i--) {
-            const f = stack[i];
-            if (!live.includes(f.name))
-                live.push(f.name);
-            if (f.modal)
-                return live;
-        }
-        if (!live.includes(GLOBAL))
-            live.push(GLOBAL);
-        return live;
+        return liveContexts()
+            .filter((c) => c.filters.length === 0)
+            .map((c) => c.name);
+    }
+    function registerHandler(handler) {
+        const h = { handler, context: handler.context ?? GLOBAL, seq: seq++ };
+        handlers.push(h);
+        notify();
+        let done = false;
+        return () => {
+            if (done)
+                return;
+            done = true;
+            const i = handlers.indexOf(h);
+            if (i !== -1)
+                handlers.splice(i, 1);
+            notify();
+        };
     }
     function register(shortcuts) {
-        const defs = Array.isArray(shortcuts) ? shortcuts : [shortcuts];
-        const added = defs.map((def) => {
-            const entry = {
-                def,
-                combo: parseCombo(def.key, def.modifiers),
-                context: def.context ?? GLOBAL,
-                seq: seq++
-            };
+        const defs = toArray(shortcuts);
+        const batch = [];
+        for (const def of defs) {
+            const entry = { def, canon: [], combos: [], context: def.context ?? GLOBAL, seq: 0 };
+            resolve(entry); // throws on a malformed key before anything is added
+            if (def.id) {
+                const dup = [...entries, ...batch].some((e) => e.def.id === def.id && e.context === entry.context);
+                if (dup) {
+                    const msg = `keyboardShortcutRegistry: duplicate shortcut id "${def.id}" in context "${entry.context}"`;
+                    if (dev)
+                        throw new Error(msg);
+                    console.warn(`${msg} — the later registration wins`);
+                }
+            }
+            batch.push(entry);
+        }
+        for (const entry of batch) {
+            entry.seq = seq++;
             entries.push(entry);
-            return entry;
-        });
+        }
         notify();
         let done = false;
         return () => {
             if (done)
                 return;
             done = true;
-            for (const e of added) {
+            for (const e of batch) {
                 const i = entries.indexOf(e);
                 if (i !== -1)
                     entries.splice(i, 1);
@@ -247,9 +1046,27 @@ export function createShortcutRegistry(options = {}) {
         };
     }
     function pushContext(name, opts = {}) {
-        const frame = { name, modal: !!opts.modal, token: {} };
+        const passIds = new Set();
+        const passPhysical = new Set();
+        if (opts.modal) {
+            for (const p of opts.passthrough ?? []) {
+                passIds.add(p);
+                if (validateCombo(p) === null)
+                    passPhysical.add(physical(normalizeCombo(p)));
+            }
+        }
+        const frame = {
+            name,
+            modal: !!opts.modal,
+            layer: opts.layer ?? 0,
+            order: pushSeq++,
+            passIds,
+            passPhysical
+        };
         if (opts.label)
             labels[name] = opts.label;
+        if (frame.modal)
+            modalContexts.add(name);
         stack.push(frame);
         notify();
         return () => {
@@ -262,18 +1079,48 @@ export function createShortcutRegistry(options = {}) {
             notify();
         };
     }
+    function trackModifiers(next) {
+        const cb = options.onModifierChange;
+        if (!cb)
+            return;
+        const prev = modifiers;
+        if (prev.alt === next.alt && prev.ctrl === next.ctrl && prev.shift === next.shift && prev.meta === next.meta) {
+            return;
+        }
+        modifiers = next;
+        try {
+            cb({ ...next });
+        }
+        catch (err) {
+            console.error('keyboardShortcutRegistry: onModifierChange failed', err);
+        }
+    }
+    function modifiersOf(event) {
+        return { alt: !!event.altKey, ctrl: !!event.ctrlKey, shift: !!event.shiftKey, meta: !!event.metaKey };
+    }
+    /** Physical identity of a key for release matching; `event.key` when `code` is absent (synthetic events). */
+    function releaseKey(event) {
+        return event.code ? `code:${event.code}` : `key:${normalizeKey(event.key ?? '')}`;
+    }
+    /** A raw handler error is reported through `onError` with a stand-in definition. */
+    function handlerAsDefinition(h) {
+        return { key: [], description: 'Raw shortcut handler', context: h.context, action: () => { } };
+    }
     function handleKeydown(event) {
+        trackModifiers(modifiersOf(event));
         if (event.defaultPrevented || event.isComposing || event.key === 'Process')
             return false;
         const path = typeof event.composedPath === 'function' ? event.composedPath() : [];
-        const typing = isTypingTarget(path[0] ?? event.target);
-        for (const ctx of activeContexts()) {
+        const typing = typingTest(path[0] ?? event.target ?? null, event);
+        for (const { name: ctx, filters } of liveContexts()) {
             // Later registrations shadow earlier ones within a context.
             for (let i = entries.length - 1; i >= 0; i--) {
                 const e = entries[i];
                 if (e.context !== ctx)
                     continue;
-                if (!matches(event, e.combo, platform))
+                if (!e.combos.some((c) => matches(event, c, platform)))
+                    continue;
+                if (filters.length && !passes(e.def, e.canon, filters))
                     continue;
                 if (typing && !e.def.allowInInput)
                     continue;
@@ -283,6 +1130,8 @@ export function createShortcutRegistry(options = {}) {
                     continue;
                 if (e.def.preventDefault !== false)
                     event.preventDefault();
+                if (e.def.onRelease)
+                    pendingReleases.set(releaseKey(event), e.def);
                 try {
                     const result = e.def.action(event);
                     if (result && typeof result.catch === 'function') {
@@ -294,67 +1143,212 @@ export function createShortcutRegistry(options = {}) {
                 }
                 return true;
             }
+            // Raw handlers: after the context's combos, never through a modal.
+            if (filters.length)
+                continue;
+            for (let i = handlers.length - 1; i >= 0; i--) {
+                const h = handlers[i];
+                if (h.context !== ctx)
+                    continue;
+                if (typing && !h.handler.allowInInput)
+                    continue;
+                let handled = false;
+                try {
+                    handled = h.handler.handle(event) === true;
+                }
+                catch (err) {
+                    onError(err, handlerAsDefinition(h));
+                }
+                if (!handled)
+                    continue;
+                if (h.handler.preventDefault !== false)
+                    event.preventDefault();
+                return true;
+            }
         }
         return false;
     }
+    function handleKeyup(event) {
+        trackModifiers(modifiersOf(event));
+        const k = releaseKey(event);
+        const def = pendingReleases.get(k);
+        if (!def)
+            return false;
+        pendingReleases.delete(k);
+        try {
+            def.onRelease?.(event);
+        }
+        catch (err) {
+            onError(err, def);
+        }
+        return true;
+    }
+    function handleBlur() {
+        pendingReleases.clear();
+        trackModifiers({ alt: false, ctrl: false, shift: false, meta: false });
+    }
     function attach(target) {
         const t = target ?? (typeof window !== 'undefined' ? window : null);
         if (!t)
             return () => { };
-        const listener = (e) => {
+        const onDown = (e) => {
             handleKeydown(e);
         };
-        t.addEventListener('keydown', listener);
-        return () => t.removeEventListener('keydown', listener);
+        const onUp = (e) => {
+            handleKeyup(e);
+        };
+        const onBlur = () => handleBlur();
+        // keydown last: a pre-A3 custom target that ignores `type` keeps the keydown.
+        t.addEventListener('keyup', onUp);
+        t.addEventListener('blur', onBlur);
+        t.addEventListener('keydown', onDown);
+        return () => {
+            t.removeEventListener('keyup', onUp);
+            t.removeEventListener('blur', onBlur);
+            t.removeEventListener('keydown', onDown);
+        };
+    }
+    /** Overlay keycap for a definition's live binding; null when unbound. */
+    function labelOf(def, canon) {
+        if (!canon.length)
+            return null;
+        if (def.label && !isCustom(def))
+            return def.label;
+        return canon.map((c) => formatCombo(parseCombo(c), platform)).join(' / ');
     }
     function toSections(opts = {}) {
+        // Registrations, plus (opt-in) declarations nothing has registered yet.
+        const pool = opts.includeDeclared ? units().sort((a, b) => a.seq - b.seq) : entries;
         const contexts = opts.scope === 'all'
-            ? [...new Set(entries.map((e) => e.context))].sort((a, b) => a === GLOBAL ? 1 : b === GLOBAL ? -1 : 0)
-            : activeContexts();
+            ? [...new Set([...pool.map((e) => e.context), ...handlers.map((h) => h.context)])]
+                .sort((a, b) => (a === GLOBAL ? 1 : b === GLOBAL ? -1 : 0))
+                .map((name) => ({ name, filters: [] }))
+            : liveContexts();
         const sections = new Map();
+        const sectionFor = (title) => {
+            let section = sections.get(title);
+            if (!section) {
+                section = { title, shortcuts: [] };
+                sections.set(title, section);
+            }
+            return section;
+        };
         const seen = new Set();
-        for (const ctx of contexts) {
+        for (const { name: ctx, filters } of contexts) {
             // Walk newest-first so a shadowed combo (same context, or a lower
             // context) is the one dropped, then restore registration order.
             const kept = [];
-            for (let i = entries.length - 1; i >= 0; i--) {
-                const e = entries[i];
+            for (let i = pool.length - 1; i >= 0; i--) {
+                const e = pool[i];
                 if (e.context !== ctx || e.def.hidden)
                     continue;
+                if (filters.length && !passes(e.def, e.canon, filters))
+                    continue;
                 if (opts.onlyEnabled && e.def.enabled && !e.def.enabled())
                     continue;
-                const comboId = JSON.stringify(e.combo);
-                if (opts.scope !== 'all' && seen.has(comboId))
+                const label = labelOf(e.def, e.canon);
+                if (label === null)
+                    continue;
+                const ids = e.canon.map(physical);
+                if (opts.scope !== 'all' && ids.every((id) => seen.has(id)))
                     continue;
-                seen.add(comboId);
-                kept.unshift(e);
+                for (const id of ids)
+                    seen.add(id);
+                kept.unshift({ e, label });
             }
-            for (const e of kept) {
-                const title = e.def.group ?? labels[ctx] ?? ctx;
-                let section = sections.get(title);
-                if (!section) {
-                    section = { title, shortcuts: [] };
-                    sections.set(title, section);
+            for (const { e, label } of kept) {
+                sectionFor(e.def.group ?? labels[ctx] ?? ctx).shortcuts.push({ key: label, description: e.def.description });
+            }
+            if (filters.length)
+                continue;
+            for (const h of handlers) {
+                if (h.context !== ctx || !h.handler.describe)
+                    continue;
+                let rows = [];
+                try {
+                    rows = h.handler.describe() ?? [];
+                }
+                catch (err) {
+                    console.error('keyboardShortcutRegistry: raw handler describe() failed', err);
+                }
+                for (const row of rows) {
+                    sectionFor(row.group ?? labels[ctx] ?? ctx).shortcuts.push({ key: row.key, description: row.description });
                 }
-                section.shortcuts.push({ key: formatShortcut(e.def, platform), description: e.def.description });
             }
         }
         return [...sections.values()];
     }
+    function format(s) {
+        if (typeof s === 'string' || !s.id)
+            return formatShortcut(s, platform);
+        return labelOf(s, currentOf(s)) ?? '';
+    }
+    function formatBinding(id) {
+        const src = sourceOf(id);
+        if (!src)
+            return null;
+        return labelOf(src.def, currentOf(src.def));
+    }
+    // Load the store last, once everything it re-resolves exists.
+    let ready = Promise.resolve();
+    if (store) {
+        let result;
+        try {
+            result = store.load();
+        }
+        catch (err) {
+            warnStore(err);
+            result = {};
+        }
+        if (isThenable(result)) {
+            ready = Promise.resolve(result).then((o) => applyOverrides(sanitizeOverrides(o, rejected.add), { replay: true }), (err) => {
+                warnStore(err);
+                applyOverrides({}, { replay: true });
+            });
+        }
+        else {
+            applyOverrides(sanitizeOverrides(result, rejected.add), { replay: true });
+        }
+        store.subscribe?.((o) => applyOverrides(sanitizeOverrides(o, rejected.add), { replay: !loaded }));
+    }
     return {
         register,
         pushContext,
         activeContexts,
         attach,
         handleKeydown,
+        handleKeyup,
+        handleBlur,
+        registerHandler,
+        formatBinding,
         toSections,
         list: () => [...entries].sort((a, b) => a.seq - b.seq).map((e) => e.def),
-        format: (s) => formatShortcut(s, platform),
+        format,
         subscribe(listener) {
             listeners.add(listener);
             return () => listeners.delete(listener);
         },
-        platform
+        platform,
+        ready,
+        bindings,
+        binding,
+        rebind,
+        resetBinding,
+        resetAllBindings,
+        findConflicts,
+        allConflicts,
+        rejectedBindings() {
+            const fromStore = (() => {
+                try {
+                    return store?.rejected?.() ?? [];
+                }
+                catch {
+                    return [];
+                }
+            })();
+            return [...fromStore, ...rejected.list()];
+        },
+        declare
     };
 }
 let defaultRegistry = null;