entangled-worlds-orbiters-shared 4.1.0 → 4.2.0

package/src/shortcuts/entangledWorlds.ts

@@ -0,0 +1,51 @@
+// The Entangled Worlds catalogues: the studio (where a world's clip is made) and the full-window
+// player. Escape and Enter inside dialogs stay with the dialogs and are not listed here.
+
+import type { ShortcutAction } from './match.js'
+
+export const EW_STUDIO_SECTION = 'ew-studio'
+export const EW_PLAYER_SECTION = 'ew-player'
+
+/** The studio's actions all act on what is open in it; the player has no other scope. */
+export type EntangledWorldsShortcut = ShortcutAction<'studio' | 'player'>
+
+const studio = (id: string, label: string, defaultKeys: readonly string[], group: string, command?: false): EntangledWorldsShortcut =>
+  Object.freeze({
+    id: `ew.studio.${id}`, section: EW_STUDIO_SECTION, label, defaultKeys: Object.freeze([...defaultKeys]), scope: 'studio' as const,
+    group, ...(command === false ? { command } : {}),
+  })
+
+/** How the studio's command menu groups its actions, in its order. */
+export const EW_STUDIO_COMMAND_GROUPS = Object.freeze([
+  { id: 'edit', label: 'Edit' },
+  { id: 'playback', label: 'Playback' },
+  { id: 'steps', label: 'Steps' },
+  { id: 'help', label: 'Help' },
+] as const)
+
+export const EW_STUDIO_SHORTCUTS: readonly EntangledWorldsShortcut[] = Object.freeze([
+  studio('undo', 'Undo', ['Mod+KeyZ'], 'edit'),
+  studio('redo', 'Redo', ['Mod+Shift+KeyZ'], 'edit'),
+  studio('duplicate', 'Duplicate the selection', ['Mod+KeyD'], 'edit'),
+  studio('copy', 'Copy the selection', ['Mod+KeyC'], 'edit'),
+  studio('paste', 'Paste', ['Mod+KeyV'], 'edit'),
+  studio('playPause', 'Play or pause', ['Shift?+Space'], 'playback'),
+  studio('remove', 'Remove the selection', ['Shift?+Delete', 'Shift?+Backspace'], 'edit'),
+  studio('step.audio', 'Audio step', ['Digit1', 'Numpad1'], 'steps'),
+  studio('step.animations', 'Animations step', ['Digit2', 'Numpad2'], 'steps'),
+  studio('step.third', 'Export step (Release where there is no export)', ['Digit3', 'Numpad3'], 'steps'),
+  studio('step.release', 'Release step', ['Digit4', 'Numpad4'], 'steps'),
+  studio('help', 'Keyboard shortcuts', ['Shift?+Slash'], 'help'),
+  // Opens the menu itself, so the menu does not list it.
+  studio('commands', 'Commands', ['Mod+KeyK'], 'help', false),
+])
+
+export const EW_PLAYER_SHORTCUTS: readonly EntangledWorldsShortcut[] = Object.freeze([
+  Object.freeze({
+    id: 'ew.player.playPause',
+    section: EW_PLAYER_SECTION,
+    label: 'Play or pause',
+    defaultKeys: Object.freeze(['Shift?+Alt?+Ctrl?+Meta?+Space']),
+    scope: 'player' as const,
+  }),
+])

package/src/shortcuts/format.ts

@@ -0,0 +1,143 @@
+// A key string for people: how a chord is shown (`⌘⇧Z`, `Ctrl+Shift+Z`, `Q`), and the key string a
+// press makes when someone sets a key ("press a key to change").
+
+import { isModifierCode, parseChord, type Chord } from './chord.js'
+
+/** Apple keyboards show modifiers as symbols, and their command key is ⌘ (`Mod`); others write words and Ctrl. */
+export type ShortcutPlatform = 'apple' | 'other'
+
+/** The platform of this browser, by its own report; `other` outside a browser. */
+export function shortcutPlatform(): ShortcutPlatform {
+  const nav = (globalThis as { navigator?: { platform?: string; userAgentData?: { platform?: string } } }).navigator
+  const name = nav?.userAgentData?.platform ?? nav?.platform ?? ''
+  return /mac|iphone|ipad|ipod/i.test(name) ? 'apple' : 'other'
+}
+
+/**
+ * The character a key place prints on this person's keyboard, when the browser can say
+ * (`navigator.keyboard.getLayoutMap()`, Chromium only); a key place it does not know is shown from
+ * its name.
+ */
+export type KeyLayout = ReadonlyMap<string, string>
+
+const NAMED: Readonly<Record<string, string>> = {
+  Space: 'Space', Enter: 'Enter', Escape: 'Esc', Tab: 'Tab', Backspace: 'Backspace', Delete: 'Delete',
+  Insert: 'Insert', Home: 'Home', End: 'End', PageUp: 'Page up', PageDown: 'Page down',
+  ArrowUp: '↑', ArrowDown: '↓', ArrowLeft: '←', ArrowRight: '→',
+  Minus: '-', Equal: '=', BracketLeft: '[', BracketRight: ']', Backslash: '\\', Semicolon: ';', Quote: "'",
+  Backquote: '`', Comma: ',', Period: '.', Slash: '/', IntlBackslash: '§',
+  NumpadAdd: 'Num +', NumpadSubtract: 'Num -', NumpadMultiply: 'Num *', NumpadDivide: 'Num /',
+  NumpadDecimal: 'Num .', NumpadEnter: 'Num Enter',
+}
+
+/** What a key place is called on a keyboard: `KeyQ` → `Q`, `Digit1` → `1`, `Numpad4` → `Num 4`. */
+export function keyLabel(code: string, layout?: KeyLayout): string {
+  const printed = layout?.get(code)
+  if (printed && printed.trim()) return printed.length === 1 ? printed.toUpperCase() : printed
+  if (/^Key[A-Z]$/.test(code)) return code.slice(3)
+  if (/^Digit\d$/.test(code)) return code.slice(5)
+  if (/^Numpad\d$/.test(code)) return `Num ${code.slice(6)}`
+  return NAMED[code] ?? code
+}
+
+const SYMBOLS = { ctrl: '⌃', alt: '⌥', shift: '⇧', meta: '⌘' } as const
+const WORDS = { ctrl: 'Ctrl', alt: 'Alt', shift: 'Shift', meta: 'Meta' } as const
+
+/**
+ * The parts a chord is shown as, one per key to press: modifiers first, in the order the platform
+ * writes them, then the key. A modifier the chord merely allows (`Shift?`) is not shown — it is not
+ * a key anyone has to press. `null` for a key string that names no chord.
+ */
+export function chordParts(keys: string, platform: ShortcutPlatform = shortcutPlatform(), layout?: KeyLayout): string[] | null {
+  // A sequence: each key's parts, one after the other (`G`, `H`).
+  if (typeof keys === 'string' && keys.includes(' ')) {
+    const steps = keys.split(' ').map((step) => (step.includes(' ') ? null : chordParts(step, platform, layout)))
+    return steps.length === 2 && steps.every(Boolean) ? (steps as string[][]).flat() : null
+  }
+  const chord = parseChord(keys)
+  if (!chord) return null
+  const held = (rule: Chord['shift']) => rule === 'held'
+  const ctrl = held(chord.ctrl) || (held(chord.mod) && platform === 'other')
+  const meta = held(chord.meta) || (held(chord.mod) && platform === 'apple')
+  const names = platform === 'apple' ? SYMBOLS : WORDS
+  // Apple's order is ⌃⌥⇧⌘; elsewhere Ctrl, Alt, Shift (and the rare Meta last).
+  const parts: string[] = []
+  if (ctrl) parts.push(names.ctrl)
+  if (held(chord.alt)) parts.push(platform === 'apple' ? names.alt : 'Alt')
+  if (held(chord.shift)) parts.push(names.shift)
+  if (meta) parts.push(names.meta)
+  // The help key is `?` wherever it lets Shift be held (its place is `/`): show what people press.
+  parts.push(chord.code === 'Slash' && chord.shift === 'any' && !layout ? '?' : keyLabel(chord.code, layout))
+  return parts
+}
+
+/** One line for a chord: `⌘⇧Z` on Apple keyboards, `Ctrl+Shift+Z` elsewhere. */
+export function formatChord(keys: string, platform: ShortcutPlatform = shortcutPlatform(), layout?: KeyLayout): string {
+  if (keys.includes(' ')) return keys.split(' ').map((step) => formatChord(step, platform, layout)).join(' ')
+  const parts = chordParts(keys, platform, layout)
+  if (!parts) return keys
+  return parts.join(platform === 'apple' ? '' : '+')
+}
+
+
+/**
+ * The key string a press makes, for someone setting a key: exactly the modifiers held, the command
+ * key of their platform written `Mod` (⌘ on Apple, Ctrl elsewhere) so the key works on both. `null`
+ * while only modifiers are down, or for a press with no key place.
+ */
+export function chordFromEvent(
+  event: { code: string; shiftKey: boolean; altKey: boolean; ctrlKey: boolean; metaKey: boolean },
+  platform: ShortcutPlatform = shortcutPlatform(),
+): string | null {
+  if (!event.code || isModifierCode(event.code)) return null
+  const parts: string[] = []
+  // ⌘ (Ctrl elsewhere) is written Mod so the key works on both — unless Ctrl and ⌘ are both held,
+  // which Mod cannot say: then both by name.
+  if (event.ctrlKey && event.metaKey) parts.push('Ctrl', 'Meta')
+  else if (platform === 'apple' ? event.metaKey : event.ctrlKey) parts.push('Mod')
+  else if (event.ctrlKey) parts.push('Ctrl')
+  else if (event.metaKey) parts.push('Meta')
+  if (event.altKey) parts.push('Alt')
+  if (event.shiftKey) parts.push('Shift')
+  parts.push(event.code)
+  const keys = parts.join('+')
+  return parseChord(keys) ? keys : null
+}
+
+const sameModifiers = (a: Chord, b: Chord) =>
+  a.shift === b.shift && a.alt === b.alt && a.ctrl === b.ctrl && a.meta === b.meta && a.mod === b.mod
+
+/**
+ * The keys of several actions shown as one ("1 2 3", "Q W E", "⌥ 0–9"): when each has exactly one
+ * key and they differ only in the last key, the shared modifiers once and then the keys. Otherwise
+ * every key of every action, as it is. Read from the keys in force, so a person's own keys show.
+ */
+export function mergedKeyParts(
+  keysPerAction: ReadonlyArray<readonly string[]>,
+  platform: ShortcutPlatform = shortcutPlatform(),
+  layout?: KeyLayout,
+): string[][] {
+  const chords = keysPerAction.map((keys) => (keys.length === 1 ? parseChord(keys[0]) : null))
+  const first = chords[0]
+  if (keysPerAction.length > 1 && first && chords.every((c) => c && sameModifiers(c, first))) {
+    const modifiers = (chordParts(keysPerAction[0][0], platform, layout) ?? []).slice(0, -1)
+    const labels = chords.map((c) => keyLabel(c!.code, layout))
+    const digits = labels.join('')
+    // The whole number row, in the row's order: one range.
+    const tail = digits === '1234567890' ? ['0–9'] : [labels.join(' ')]
+    return [[...modifiers, ...tail]]
+  }
+  return keysPerAction.flatMap((keys) => keys.map((k) => chordParts(k, platform, layout) ?? [k]))
+}
+
+/**
+ * A key someone just pressed for an action, as it is stored: when every default key of the action
+ * lets Shift be held (`Shift?`, the play keys that work while selecting several Orbiters) and the
+ * press had no Shift, the new key lets it be held too, so the action keeps working the same way.
+ */
+export function recordedKeys(defaultKeys: readonly string[], pressed: string): string {
+  const chord = parseChord(pressed)
+  if (!chord || chord.shift !== 'free' || defaultKeys.length === 0) return pressed
+  const shiftFree = defaultKeys.every((keys) => parseChord(keys)?.shift === 'any')
+  return shiftFree ? `Shift?+${pressed}` : pressed
+}

package/src/shortcuts/index.ts

@@ -0,0 +1,69 @@
+// Keyboard shortcuts, one system for every app: each app's catalogue of actions (id, section, label,
+// default keys, scope) and one matcher that says which action a key press is. Keys are named by
+// their place on the keyboard (`KeyboardEvent.code`). Framework-free: no React, no DOM beyond reading
+// a key event.
+
+export {
+  parseChord,
+  parseKeys,
+  keysOverlap,
+  chordMatches,
+  chordsOverlap,
+  isCommandChord,
+  type Chord,
+  type ModifierRule,
+  type ModifierState,
+} from './chord.js'
+export {
+  matchShortcut,
+  createShortcutMatcher,
+  SEQUENCE_WAIT_MS,
+  resolveBindings,
+  findClashes,
+  claimKeys,
+  isKeyClaimed,
+  isTypingTarget,
+  type ShortcutAction,
+  type ShortcutBindings,
+  type ShortcutOverrides,
+  type ShortcutEvent,
+} from './match.js'
+export {
+  ORBITERS_PLAY_SHORTCUTS,
+  ORBITERS_STUDIO_SHORTCUTS,
+  ORBITERS_PLAY_SECTION,
+  ORBITERS_STUDIO_SECTION,
+  ORBITERS_KEYBOARD_SURFACE_KEYS,
+  ORBITERS_COMMAND_GROUPS,
+  ORBITERS_PLAY_SHEET,
+  type OrbitersShortcut,
+  type OrbitersShortcutScope,
+} from './orbiters.js'
+export {
+  shortcutPlatform,
+  keyLabel,
+  chordParts,
+  formatChord,
+  chordFromEvent,
+  mergedKeyParts,
+  recordedKeys,
+  type ShortcutPlatform,
+  type KeyLayout,
+} from './format.js'
+export { SHORTCUT_SECTIONS, SHORTCUT_APPS, type ShortcutSection, type ShortcutAppId } from './sections.js'
+export { SITE_SHORTCUTS, SITE_SECTION, type SiteShortcut } from './site.js'
+export {
+  EW_STUDIO_SHORTCUTS,
+  EW_PLAYER_SHORTCUTS,
+  EW_STUDIO_SECTION,
+  EW_PLAYER_SECTION,
+  EW_STUDIO_COMMAND_GROUPS,
+  type EntangledWorldsShortcut,
+} from './entangledWorlds.js'
+export { shortcutLabel, shortcutSectionLabel, shortcutName } from './labels.js'
+export {
+  createShortcutOverridesSource,
+  parseOverrides,
+  type ShortcutOverridesSource,
+  type ReadAccountSettings,
+} from './overrides.js'

package/src/shortcuts/labels.ts

@@ -0,0 +1,139 @@
+// What the actions and sections are called in each language the platform speaks, beside the
+// English in the catalogues. One table, read by every app and the settings page, so a name is
+// translated once.
+
+import type { ShortcutAction } from './match.js'
+
+type Names = Readonly<Record<string, string>>
+
+const ES: Names = Object.freeze({
+  "ew.player.playPause": "Reproducir o pausar",
+  "ew.studio.commands": "Comandos",
+  "ew.studio.copy": "Copiar la selección",
+  "ew.studio.duplicate": "Duplicar la selección",
+  "ew.studio.help": "Atajos de teclado",
+  "ew.studio.paste": "Pegar",
+  "ew.studio.playPause": "Reproducir o pausar",
+  "ew.studio.redo": "Rehacer",
+  "ew.studio.remove": "Quitar la selección",
+  "ew.studio.step.animations": "Paso de animaciones",
+  "ew.studio.step.audio": "Paso de audio",
+  "ew.studio.step.release": "Paso de publicación",
+  "ew.studio.step.third": "Paso de exportación (Publicación donde no hay exportación)",
+  "ew.studio.undo": "Deshacer",
+  "orbiters.play.body.moon": "Luna",
+  "orbiters.play.body.star": "Estrella",
+  "orbiters.play.body.world": "Mundo",
+  "orbiters.play.dimension.1": "Primera dimensión",
+  "orbiters.play.dimension.2": "Segunda dimensión",
+  "orbiters.play.dimension.3": "Tercera dimensión",
+  "orbiters.play.help": "Atajos de teclado",
+  "orbiters.play.history.redo": "Rehacer",
+  "orbiters.play.history.undo": "Deshacer",
+  "orbiters.play.midiLearn": "MIDI learn",
+  "orbiters.play.panel.cosmicLfo": "Cosmic LFO",
+  "orbiters.play.panel.jamming": "Jamming",
+  "orbiters.play.panel.playback": "Reproducción",
+  "orbiters.play.panel.sensors": "Sensores",
+  "orbiters.play.performanceMode": "Modo rendimiento",
+  "orbiters.play.rec.hold": "Grabar mientras se mantiene",
+  "orbiters.play.rec.toggle": "Activar o desactivar Rec",
+  "orbiters.play.snapshot.recall.0": "Recuperar instantánea 0",
+  "orbiters.play.snapshot.recall.1": "Recuperar instantánea 1",
+  "orbiters.play.snapshot.recall.2": "Recuperar instantánea 2",
+  "orbiters.play.snapshot.recall.3": "Recuperar instantánea 3",
+  "orbiters.play.snapshot.recall.4": "Recuperar instantánea 4",
+  "orbiters.play.snapshot.recall.5": "Recuperar instantánea 5",
+  "orbiters.play.snapshot.recall.6": "Recuperar instantánea 6",
+  "orbiters.play.snapshot.recall.7": "Recuperar instantánea 7",
+  "orbiters.play.snapshot.recall.8": "Recuperar instantánea 8",
+  "orbiters.play.snapshot.recall.9": "Recuperar instantánea 9",
+  "orbiters.play.snapshot.store.0": "Guardar instantánea 0",
+  "orbiters.play.snapshot.store.1": "Guardar instantánea 1",
+  "orbiters.play.snapshot.store.2": "Guardar instantánea 2",
+  "orbiters.play.snapshot.store.3": "Guardar instantánea 3",
+  "orbiters.play.snapshot.store.4": "Guardar instantánea 4",
+  "orbiters.play.snapshot.store.5": "Guardar instantánea 5",
+  "orbiters.play.snapshot.store.6": "Guardar instantánea 6",
+  "orbiters.play.snapshot.store.7": "Guardar instantánea 7",
+  "orbiters.play.snapshot.store.8": "Guardar instantánea 8",
+  "orbiters.play.snapshot.store.9": "Guardar instantánea 9",
+  "orbiters.play.transport.restart": "Reproducir desde el principio",
+  "orbiters.play.transport.toggle": "Reproducir o pausar",
+  "orbiters.studio.map": "Mapear",
+  "orbiters.studio.redo": "Rehacer",
+  "orbiters.studio.undo": "Deshacer",
+  "site.commands": "Comandos",
+  "site.search": "Buscar",
+  "site.go.home": "Inicio",
+  "site.go.playground": "Playground",
+  "site.go.notifications": "Notificaciones",
+  "site.go.audios": "Mis audios",
+  "site.go.orbiters": "Mis Orbiters",
+  "site.go.worlds": "Mis Entangled Worlds",
+  "site.go.collections": "Mis colecciones",
+  "site.go.stars": "Mis estrellas",
+  "site.new.orbiter": "Nuevo Orbiter",
+  "site.new.audio": "Nuevo audio",
+  "site.new.world": "Nuevo Entangled World",
+  "site.settings": "Abrir la configuración",
+  "section:site": "Plantasia Space",
+  "app:plantasia-space": "Plantasia Space",
+  "app:orbiters": "Orbiters",
+  "app:entangled-worlds": "Entangled Worlds",
+  "part:orbiters-play": "Tocar",
+  "part:orbiters-studio": "Estudio",
+  "part:ew-studio": "Estudio",
+  "part:ew-player": "Reproductor",
+  "section:orbiters-play": "Orbiters: tocar",
+  "section:orbiters-studio": "Orbiter Studio",
+  "section:ew-studio": "Estudio de Entangled Worlds",
+  "section:ew-player": "Reproductor de Entangled Worlds",
+  "orbiters.play.screenCapture": "Captura de pantalla",
+  "orbiters.play.share": "Compartir",
+  "orbiters.play.fullscreen": "Pantalla completa",
+  "orbiters.play.commands": "Comandos",
+  "group:edit": "Edición",
+  "group:playback": "Reproducción",
+  "group:steps": "Pasos",
+  "group:help": "Ayuda",
+  "group:transport": "Transporte",
+  "group:view": "Vista",
+  "group:snapshots": "Instantáneas",
+  "group:panels": "Paneles",
+  "group:orbiter": "Orbiter",
+  "group:studio": "Estudio",
+  "row:playPause": "Reproducir / pausar",
+  "row:playFromStart": "Reproducir desde el inicio",
+  "row:recHeld": "REC mientras se mantiene",
+  "row:recLatch": "REC fijo",
+  "row:undo": "Deshacer",
+  "row:redo": "Rehacer",
+  "row:dimensions": "Dimensión I · II · III",
+  "row:bodies": "Mundo · Luna · Estrella",
+  "row:snapshotRecall": "Recuperar instantánea",
+  "row:snapshotStore": "Guardar instantánea",
+  "row:jamming": "Jamming",
+  "row:playback": "Reproducción",
+  "row:cosmicLfo": "Cosmic LFO",
+  "row:sensors": "Sensores",
+  "row:midiLearn": "MIDI learn",
+  "row:performanceMode": "Modo rendimiento",
+})
+
+const NAMES: Readonly<Record<string, Names>> = Object.freeze({ es: ES })
+
+/** An action's name in a language (`es`, `es-AR`), falling back to the catalogue's English. */
+export function shortcutLabel(action: Pick<ShortcutAction, 'id' | 'label'>, locale?: string): string {
+  return NAMES[(locale ?? '').slice(0, 2).toLowerCase()]?.[action.id] ?? action.label
+}
+
+/** A section's name in a language, falling back to the English. */
+export function shortcutSectionLabel(section: { id: string; label: string }, locale?: string): string {
+  return NAMES[(locale ?? '').slice(0, 2).toLowerCase()]?.[`section:${section.id}`] ?? section.label
+}
+
+/** Any other named thing of the shortcuts (a command group `group:<id>`, a sheet row `row:<id>`). */
+export function shortcutName(key: string, english: string, locale?: string): string {
+  return NAMES[(locale ?? '').slice(0, 2).toLowerCase()]?.[key] ?? english
+}

package/src/shortcuts/match.ts

@@ -0,0 +1,195 @@
+// Which action a key press is. Each app keeps what its actions DO; this only answers which one a
+// press names, so every app reads keys the same way: the modifiers, a field being typed in, and a
+// surface that holds letters of its own are decided here, once.
+
+import { chordMatches, isCommandChord, isModifierCode, keysOverlap, parseChord, parseKeys, type Chord, type ModifierState } from './chord.js'
+
+/** One thing a key can do, as an app's catalogue declares it. */
+export interface ShortcutAction<Scope extends string = string> {
+  /** `<app>.<area>.<action>`, e.g. `orbiters.play.panel.jamming`: the key a person's override is stored under. */
+  readonly id: string
+  /** The group it is shown in, one per app surface (`orbiters-play`). Keys clash only inside a section. */
+  readonly section: string
+  /** What it does, in sentence case. */
+  readonly label: string
+  /** The keys it has until the person changes them (chord strings, see `chord.ts`). */
+  readonly defaultKeys: readonly string[]
+  /** What it acts on, in the app's own terms (Orbiters: one deck, or this machine). */
+  readonly scope: Scope
+  /** Where a command menu lists it (`panels`, `snapshots`); unset, under the section itself. */
+  readonly group?: string
+  /** `false`: a key only, never a command to pick from a list (a key held down, the menu itself). */
+  readonly command?: boolean
+}
+
+/** The keys of each action, in the order they are tried: the first action a press matches is the one. */
+export type ShortcutBindings = Iterable<readonly [actionId: string, keys: readonly string[]]>
+
+/**
+ * A person's changes, as their settings store them: an action's own keys (`[]` = no key). An action
+ * left out keeps its defaults, so a default changed in code reaches everyone who never touched it.
+ */
+export type ShortcutOverrides = ReadonlyArray<{ readonly id: string; readonly keys: readonly string[] }>
+
+/** The key press as the matcher reads it: a `KeyboardEvent` has all of it. */
+export interface ShortcutEvent extends ModifierState {
+  readonly code: string
+  readonly key: string
+  readonly target?: unknown
+}
+
+/**
+ * Every action's keys: its defaults, or the person's override (unknown actions and keys that name no
+ * chord are dropped). Catalogue order is kept, so the earlier catalogue wins where two match one press.
+ */
+export function resolveBindings(
+  catalogue: Iterable<ShortcutAction>,
+  overrides: ShortcutOverrides = [],
+): Map<string, readonly string[]> {
+  const own = new Map<string, readonly string[]>()
+  for (const entry of Array.isArray(overrides) ? overrides : []) {
+    if (entry && typeof entry.id === 'string' && Array.isArray(entry.keys)) own.set(entry.id, entry.keys)
+  }
+  const bindings = new Map<string, readonly string[]>()
+  for (const action of catalogue) {
+    const keys = own.get(action.id) ?? action.defaultKeys
+    bindings.set(action.id, keys.filter((key) => typeof key === 'string' && parseKeys(key) !== null))
+  }
+  return bindings
+}
+
+/** Two actions one press could be: `[first, second, the key of the first that clashes]`. */
+export function findClashes(bindings: ShortcutBindings): Array<readonly [string, string, string]> {
+  const entries = [...bindings]
+  const clashes: Array<readonly [string, string, string]> = []
+  entries.forEach(([a, aKeys], i) => {
+    for (const [b, bKeys] of entries.slice(i + 1)) {
+      const key = aKeys.find((ak) => bKeys.some((bk) => keysOverlap(ak, bk)))
+      if (key !== undefined) clashes.push([a, b, key])
+    }
+  })
+  return clashes
+}
+
+// ---------------------------------------------------------------------------------------------
+// Surface claims
+
+const claims = new Set<ReadonlySet<string>>()
+
+/**
+ * Take letters away from the shortcuts while a surface is on screen, until the returned release is
+ * called. An on-screen keyboard plays from the computer keyboard, and a note key that also switched a
+ * panel would take the keyboard away mid-phrase. Keys are `event.key` values, lower-cased (the
+ * character, as the keyboard surface reads them).
+ */
+export function claimKeys(keys: Iterable<string>): () => void {
+  const claim: ReadonlySet<string> = new Set([...keys].map((key) => key.toLowerCase()))
+  claims.add(claim)
+  return () => {
+    claims.delete(claim)
+  }
+}
+
+/** Whether a surface holds this key. A key with Ctrl, ⌘ or Option is never claimed (⌘Z stays undo). */
+export function isKeyClaimed(event: Pick<ShortcutEvent, 'key' | 'metaKey' | 'ctrlKey' | 'altKey'>): boolean {
+  if (!claims.size || typeof event.key !== 'string' || event.metaKey || event.ctrlKey || event.altKey) return false
+  const key = event.key.toLowerCase()
+  for (const claim of claims) if (claim.has(key)) return true
+  return false
+}
+
+// ---------------------------------------------------------------------------------------------
+// Typing
+
+interface TargetLike {
+  readonly isContentEditable?: boolean
+  readonly tagName?: unknown
+  readonly type?: unknown
+  getAttribute?(name: string): string | null
+}
+
+const asTarget = (target: unknown): TargetLike | null =>
+  target !== null && typeof target === 'object' ? (target as TargetLike) : null
+
+const roleOf = (el: TargetLike) => (typeof el.getAttribute === 'function' ? el.getAttribute('role') : null)
+
+/** Inputs that take no typing: a slider keeps the shortcuts working while it holds focus. */
+const UNTYPED_INPUTS = new Set(['range', 'color', 'file'])
+
+/** A text field: every key typed there is the field's, ⌘Z included (it undoes the typing). */
+export function isTypingTarget(target: unknown): boolean {
+  const el = asTarget(target)
+  if (!el) return false
+  if (el.isContentEditable === true || roleOf(el) === 'textbox') return true
+  const tag = typeof el.tagName === 'string' ? el.tagName.toUpperCase() : ''
+  if (tag === 'INPUT') return !UNTYPED_INPUTS.has(typeof el.type === 'string' ? el.type.toLowerCase() : '')
+  return tag === 'TEXTAREA' || tag === 'SELECT'
+}
+
+/** A widget that reads typed characters (a combobox's type-to-find), though it is no text field. */
+function readsCharacters(target: unknown): boolean {
+  const el = asTarget(target)
+  return el !== null && roleOf(el) === 'combobox'
+}
+
+/**
+ * The action this press is, or `null`. Not one while the person is typing in a field, nor a key a
+ * surface holds; a widget that reads characters keeps its characters but not the ⌘ commands.
+ */
+export function matchShortcut(event: ShortcutEvent, bindings: ShortcutBindings): string | null {
+  if (!event.code || isTypingTarget(event.target) || isKeyClaimed(event)) return null
+  const characters = readsCharacters(event.target)
+  for (const [actionId, keys] of bindings) {
+    for (const key of keys) {
+      const chord = parseChord(key)
+      if (!chord || !chordMatches(chord, event.code, event)) continue
+      if (characters && !isCommandChord(chord)) return null
+      return actionId
+    }
+  }
+  return null
+}
+
+// ---------------------------------------------------------------------------------------------
+// Sequences
+
+/** How long the second key of a sequence (`G`, then `H`) may follow the first. */
+export const SEQUENCE_WAIT_MS = 1500
+
+// The sequences of a set of bindings, read once per bindings object (they change with the overrides).
+const sequencesOf = new WeakMap<object, Array<readonly [string, Chord[]]>>()
+function sequences(bindings: ShortcutBindings): Array<readonly [string, Chord[]]> {
+  const known = typeof bindings === 'object' ? sequencesOf.get(bindings) : undefined
+  if (known) return known
+  const found = [...bindings].flatMap(([id, keys]) =>
+    keys.map((k) => [id, parseKeys(k)] as const).filter((entry): entry is readonly [string, Chord[]] => entry[1]?.length === 2))
+  if (typeof bindings === 'object') sequencesOf.set(bindings, found)
+  return found
+}
+
+/**
+ * A matcher that also knows sequences: it remembers the first key of one for a moment and answers
+ * the action when the second follows. One per listener (it holds that moment). A first key answers
+ * nothing; any other key, a typed one or a wait past `waitMs` forgets it.
+ */
+export function createShortcutMatcher(waitMs: number = SEQUENCE_WAIT_MS, now: () => number = Date.now) {
+  let first: (ModifierState & { code: string; at: number }) | null = null
+  return function match(event: ShortcutEvent, bindings: ShortcutBindings): string | null {
+    if (event.code && isModifierCode(event.code)) return null
+    const pending = first && now() - first.at <= waitMs ? first : null
+    first = null
+    if (!event.code || isTypingTarget(event.target) || isKeyClaimed(event)) return null
+    // A widget that reads characters keeps them: no sequence starts or ends there.
+    const characters = readsCharacters(event.target)
+    const known = characters ? [] : sequences(bindings)
+    if (pending) {
+      for (const [id, [one, two]] of known)
+        if (chordMatches(one, pending.code, pending) && chordMatches(two, event.code, event)) return id
+    }
+    if (known.some(([, [one]]) => chordMatches(one, event.code, event))) {
+      first = { code: event.code, shiftKey: event.shiftKey, altKey: event.altKey, ctrlKey: event.ctrlKey, metaKey: event.metaKey, at: now() }
+      return null
+    }
+    return matchShortcut(event, bindings)
+  }
+}