entangled-worlds-orbiters-shared 4.0.0 → 4.2.0

package/src/shortcuts/chord.ts

@@ -0,0 +1,122 @@
+// One key with its modifiers, written as a string: `Shift+KeyR`, `Mod+KeyZ`, `Shift?+Digit1`.
+//
+// The last part is the key's PLACE (`KeyboardEvent.code`), so a French or German keyboard keeps the
+// same layout: the key, not the letter it prints. Before it, the modifiers:
+//
+//   Shift, Alt, Ctrl, Meta   held. One left out must NOT be held.
+//   Mod                      Ctrl or ⌘ (either, or both), the command key of every platform.
+//   Shift? (any, with ?)     may be held or not: the action is the same either way.
+//
+// So `KeyQ` is Q alone, `Shift?+KeyQ` is Q with or without Shift, `Mod+Shift+KeyZ` is ⌘⇧Z or Ctrl⇧Z.
+//
+// Two chords with a space between are a sequence, pressed one after the other: `KeyG KeyH` is G,
+// then H. A sequence is never one press, so `parseChord` names none; `parseKeys` reads both kinds.
+
+/** What a modifier has to be for a chord to match: held, not held, or either. */
+export type ModifierRule = 'held' | 'free' | 'any'
+
+export interface Chord {
+  readonly code: string
+  readonly shift: ModifierRule
+  readonly alt: ModifierRule
+  readonly ctrl: ModifierRule
+  readonly meta: ModifierRule
+  /** Ctrl or ⌘: when `held`, at least one of the two is down, and neither is otherwise checked. */
+  readonly mod: ModifierRule
+}
+
+/** The modifier state of a key press: the four flags of a `KeyboardEvent`. */
+export interface ModifierState {
+  readonly shiftKey: boolean
+  readonly altKey: boolean
+  readonly ctrlKey: boolean
+  readonly metaKey: boolean
+}
+
+const MODIFIERS = { Shift: 'shift', Alt: 'alt', Ctrl: 'ctrl', Meta: 'meta', Mod: 'mod' } as const
+type ModifierName = keyof typeof MODIFIERS
+
+const CODE = /^[A-Za-z][A-Za-z0-9]*$/
+
+const parsed = new Map<string, Chord | null>()
+
+/** The chord a key string names, or `null` when it names none (an unknown modifier, a doubled one, no key). */
+export function parseChord(keys: string): Chord | null {
+  const known = parsed.get(keys)
+  if (known !== undefined) return known
+  const chord = parse(keys)
+  parsed.set(keys, chord)
+  return chord
+}
+
+function parse(keys: string): Chord | null {
+  if (typeof keys !== 'string') return null
+  const parts = keys.split('+')
+  const code = parts.pop()
+  if (!code || !CODE.test(code)) return null
+  const rules: Record<(typeof MODIFIERS)[ModifierName], ModifierRule> = {
+    shift: 'free', alt: 'free', ctrl: 'free', meta: 'free', mod: 'free',
+  }
+  const seen = new Set<string>()
+  for (const part of parts) {
+    const optional = part.endsWith('?')
+    const name = (optional ? part.slice(0, -1) : part) as ModifierName
+    if (!Object.hasOwn(MODIFIERS, name) || seen.has(name)) return null
+    seen.add(name)
+    rules[MODIFIERS[name]] = optional ? 'any' : 'held'
+  }
+  // Mod already speaks for Ctrl and ⌘: naming one of them beside it says two things about one key.
+  if (rules.mod !== 'free' && (rules.ctrl !== 'free' || rules.meta !== 'free')) return null
+  return { code, ...rules }
+}
+
+const fits = (rule: ModifierRule, down: boolean) => rule === 'any' || (rule === 'held') === Boolean(down)
+
+/** Whether a press of `code` with these modifiers is this chord. */
+export function chordMatches(chord: Chord, code: string, state: ModifierState): boolean {
+  if (chord.code !== code) return false
+  if (!fits(chord.shift, state.shiftKey) || !fits(chord.alt, state.altKey)) return false
+  if (chord.mod === 'held') return Boolean(state.ctrlKey || state.metaKey)
+  if (chord.mod === 'any') return true
+  return fits(chord.ctrl, state.ctrlKey) && fits(chord.meta, state.metaKey)
+}
+
+/** A chord that needs Ctrl or ⌘: a command, never a character typed. */
+export function isCommandChord(chord: Chord): boolean {
+  return chord.mod === 'held' || chord.ctrl === 'held' || chord.meta === 'held'
+}
+
+const STATES: ModifierState[] = Array.from({ length: 16 }, (_, i) => ({
+  shiftKey: Boolean(i & 1), altKey: Boolean(i & 2), ctrlKey: Boolean(i & 4), metaKey: Boolean(i & 8),
+}))
+
+/** Whether one press could be both chords — the test for a clash. */
+export function chordsOverlap(a: Chord, b: Chord): boolean {
+  return a.code === b.code && STATES.some((state) => chordMatches(a, a.code, state) && chordMatches(b, b.code, state))
+}
+
+/** The chords a key string names, one or two (a sequence); `null` when it names none. */
+export function parseKeys(keys: string): Chord[] | null {
+  if (typeof keys !== 'string') return null
+  const steps = keys.split(' ')
+  if (steps.length > 2) return null
+  const chords = steps.map(parseChord)
+  return chords.every((chord): chord is Chord => chord !== null) ? chords : null
+}
+
+/**
+ * Whether two key strings could answer the same presses — the test for a clash. A single key and a
+ * sequence that starts with it clash too: the single key would fire before the sequence went on.
+ */
+export function keysOverlap(a: string, b: string): boolean {
+  const as = parseKeys(a)
+  const bs = parseKeys(b)
+  if (!as || !bs) return false
+  if (as.length !== bs.length) return chordsOverlap(as[0], bs[0])
+  return as.every((chord, i) => chordsOverlap(chord, bs[i]))
+}
+
+const MODIFIER_CODES = new Set(['ShiftLeft', 'ShiftRight', 'AltLeft', 'AltRight', 'ControlLeft', 'ControlRight', 'MetaLeft', 'MetaRight', 'CapsLock', 'Fn', 'FnLock'])
+
+/** A key that is only a modifier (or Caps Lock, Fn): never a shortcut's key on its own. */
+export const isModifierCode = (code: string): boolean => MODIFIER_CODES.has(code)

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
+}