entangled-worlds-orbiters-shared 4.0.0 → 4.2.0

package/dist/shortcuts/format.js

@@ -0,0 +1,132 @@
+// 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 } from './chord.js';
+/** The platform of this browser, by its own report; `other` outside a browser. */
+export function shortcutPlatform() {
+    const nav = globalThis.navigator;
+    const name = nav?.userAgentData?.platform ?? nav?.platform ?? '';
+    return /mac|iphone|ipad|ipod/i.test(name) ? 'apple' : 'other';
+}
+const NAMED = {
+    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, layout) {
+    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: '⌘' };
+const WORDS = { ctrl: 'Ctrl', alt: 'Alt', shift: 'Shift', meta: 'Meta' };
+/**
+ * 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, platform = shortcutPlatform(), layout) {
+    // 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.flat() : null;
+    }
+    const chord = parseChord(keys);
+    if (!chord)
+        return null;
+    const held = (rule) => 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 = [];
+    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, platform = shortcutPlatform(), layout) {
+    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, platform = shortcutPlatform()) {
+    if (!event.code || isModifierCode(event.code))
+        return null;
+    const parts = [];
+    // ⌘ (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, b) => 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, platform = shortcutPlatform(), layout) {
+    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, pressed) {
+    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/dist/shortcuts/index.d.ts

@@ -0,0 +1,9 @@
+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/dist/shortcuts/index.js

@@ -0,0 +1,13 @@
+// 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, } from './chord.js';
+export { matchShortcut, createShortcutMatcher, SEQUENCE_WAIT_MS, resolveBindings, findClashes, claimKeys, isKeyClaimed, isTypingTarget, } 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, } from './orbiters.js';
+export { shortcutPlatform, keyLabel, chordParts, formatChord, chordFromEvent, mergedKeyParts, recordedKeys, } from './format.js';
+export { SHORTCUT_SECTIONS, SHORTCUT_APPS } from './sections.js';
+export { SITE_SHORTCUTS, SITE_SECTION } from './site.js';
+export { EW_STUDIO_SHORTCUTS, EW_PLAYER_SHORTCUTS, EW_STUDIO_SECTION, EW_PLAYER_SECTION, EW_STUDIO_COMMAND_GROUPS, } from './entangledWorlds.js';
+export { shortcutLabel, shortcutSectionLabel, shortcutName } from './labels.js';
+export { createShortcutOverridesSource, parseOverrides, } from './overrides.js';

package/dist/shortcuts/labels.d.ts

@@ -0,0 +1,10 @@
+import type { ShortcutAction } from './match.js';
+/** An action's name in a language (`es`, `es-AR`), falling back to the catalogue's English. */
+export declare function shortcutLabel(action: Pick<ShortcutAction, 'id' | 'label'>, locale?: string): string;
+/** A section's name in a language, falling back to the English. */
+export declare function shortcutSectionLabel(section: {
+    id: string;
+    label: string;
+}, locale?: string): string;
+/** Any other named thing of the shortcuts (a command group `group:<id>`, a sheet row `row:<id>`). */
+export declare function shortcutName(key: string, english: string, locale?: string): string;

package/dist/shortcuts/labels.js

@@ -0,0 +1,130 @@
+// 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.
+const ES = 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 = 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, locale) {
+    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, locale) {
+    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, english, locale) {
+    return NAMES[(locale ?? '').slice(0, 2).toLowerCase()]?.[key] ?? english;
+}

package/dist/shortcuts/match.d.ts

@@ -0,0 +1,65 @@
+import { 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 declare function resolveBindings(catalogue: Iterable<ShortcutAction>, overrides?: ShortcutOverrides): Map<string, readonly string[]>;
+/** Two actions one press could be: `[first, second, the key of the first that clashes]`. */
+export declare function findClashes(bindings: ShortcutBindings): Array<readonly [string, string, 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 declare function claimKeys(keys: Iterable<string>): () => void;
+/** Whether a surface holds this key. A key with Ctrl, ⌘ or Option is never claimed (⌘Z stays undo). */
+export declare function isKeyClaimed(event: Pick<ShortcutEvent, 'key' | 'metaKey' | 'ctrlKey' | 'altKey'>): boolean;
+/** A text field: every key typed there is the field's, ⌘Z included (it undoes the typing). */
+export declare function isTypingTarget(target: unknown): boolean;
+/**
+ * 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 declare function matchShortcut(event: ShortcutEvent, bindings: ShortcutBindings): string | null;
+/** How long the second key of a sequence (`G`, then `H`) may follow the first. */
+export declare const SEQUENCE_WAIT_MS = 1500;
+/**
+ * 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 declare function createShortcutMatcher(waitMs?: number, now?: () => number): (event: ShortcutEvent, bindings: ShortcutBindings) => string | null;

package/dist/shortcuts/match.js

@@ -0,0 +1,145 @@
+// 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 } from './chord.js';
+/**
+ * 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, overrides = []) {
+    const own = new Map();
+    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();
+    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) {
+    const entries = [...bindings];
+    const clashes = [];
+    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();
+/**
+ * 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) {
+    const claim = 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) {
+    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;
+}
+const asTarget = (target) => target !== null && typeof target === 'object' ? target : null;
+const roleOf = (el) => (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) {
+    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) {
+    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, bindings) {
+    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();
+function sequences(bindings) {
+    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)]).filter((entry) => 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 = SEQUENCE_WAIT_MS, now = Date.now) {
+    let first = null;
+    return function match(event, bindings) {
+        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);
+    };
+}

package/dist/shortcuts/orbiters.d.ts

@@ -0,0 +1,55 @@
+import type { ShortcutAction } from './match.js';
+export type OrbitersShortcutScope = 'voice' | 'client';
+export type OrbitersShortcut = ShortcutAction<OrbitersShortcutScope>;
+export declare const ORBITERS_PLAY_SECTION = "orbiters-play";
+export declare const ORBITERS_STUDIO_SECTION = "orbiters-studio";
+/** How a command menu groups the actions, in its order. */
+export declare const ORBITERS_COMMAND_GROUPS: readonly [{
+    readonly id: "transport";
+    readonly label: "Transport";
+}, {
+    readonly id: "view";
+    readonly label: "View";
+}, {
+    readonly id: "snapshots";
+    readonly label: "Snapshots";
+}, {
+    readonly id: "panels";
+    readonly label: "Panels";
+}, {
+    readonly id: "orbiter";
+    readonly label: "Orbiter";
+}, {
+    readonly id: "studio";
+    readonly label: "Studio";
+}];
+/**
+ * Playing an Orbiter. Shift is free on most keys (`Shift?`): it is held to select several decks,
+ * and a key pressed while selecting means what it means alone.
+ */
+export declare const ORBITERS_PLAY_SHORTCUTS: readonly OrbitersShortcut[];
+/**
+ * The keys sheet (`?`): what to look up at a glance, in three columns. A row may stand for several
+ * actions whose keys differ only in the last key ("Dimension I · II · III — 1 2 3"); the keys
+ * shown are always this person's (`mergedKeyParts`).
+ */
+export declare const ORBITERS_PLAY_SHEET: readonly Readonly<{
+    rows: readonly Readonly<{
+        actions: readonly string[];
+        id: string;
+        label: string;
+    }>[];
+    id: string;
+    label: string;
+}>[];
+/**
+ * The Studio. It is open over play, so the play keys above still work there; where both name a key,
+ * the Studio's action is the one.
+ */
+export declare const ORBITERS_STUDIO_SHORTCUTS: readonly OrbitersShortcut[];
+/**
+ * The letters the on-screen keyboard plays while it is open (`event.key`, lower-case): the piano row,
+ * then Z and X for the octave and C and V for velocity. While it is up they are its notes, and the
+ * shortcuts on them wait (`claimKeys`); a settings page says so beside those keys.
+ */
+export declare const ORBITERS_KEYBOARD_SURFACE_KEYS: readonly string[];