entangled-worlds-orbiters-shared 4.1.0 → 5.0.0

package/README.md

@@ -98,6 +98,15 @@ The capability registry (`createCapabilityRegistry`, `validate` / `assertValid`,
 - `recipesFingerprint`, `readRecipes`, `readHeadShape`, `programsNamespace` - The recipes file a build publishes, and the checks a release step makes on it
 - `largestFunction`, `shrinkWasm` - The size check and the shrink step
 
+### Keyboard shortcuts (`entangled-worlds-orbiters-shared/shortcuts`)
+- `ShortcutAction` - One catalogue entry: `id`, `label` (+ `names` by language), `defaultKeys` (by key place, `event.code`), `scope`
+- `matchShortcut(event, bindings)` - Which action a press is, or `null`: modifiers, a field being typed in and surface claims decided in one place
+- Key strings: `Shift+KeyR`, `Mod+KeyZ` (Ctrl or ⌘), `Shift?+KeyQ` (Shift may be held); `parseChord`, `chordsOverlap`
+- `resolveBindings(catalogue, overrides)`, `findClashes` - Defaults plus a person's overrides (`[{ id, keys }]` as their settings store them, `keys: []` unbinds), and the clash check
+- `claimKeys`, `isKeyClaimed` - A surface (an on-screen keyboard) takes letters away from the shortcuts while it is up
+- `createShortcutSource({ readCatalogue, readAccount })` - The catalogue (every app's actions and default keys, served by the backend: this package holds none) and a person's own keys, read at start and again when the page comes back to the front; `actions(...sectionIds)`, `bindings(actions)`, `subscribe`
+- `parseCatalogue`, `sectionActions`, `findSection`, `shortcutApps`, `localName` - Reading a served catalogue and its names in a language
+
 ### Uploads (`entangled-worlds-orbiters-shared/uploads`)
 - `uploadViaSignedUrl` - The API's signed-URL upload: `/spaces/upload-init` → PUT → `/spaces/upload-complete`, over the app's own authenticated JSON caller
 - `putToSignedUrl` - The storage PUT alone, with progress and abort

package/dist/shortcuts/catalogue.d.ts

@@ -0,0 +1,72 @@
+import type { ShortcutAction, ShortcutNames } from './match.js';
+/** Something with a name: English `label`, other languages in `names`. */
+export interface ShortcutNamed {
+    readonly id: string;
+    readonly label: string;
+    readonly names?: ShortcutNames;
+}
+/** A row of a keys sheet (`?`): one line for one or more actions whose keys show together. */
+export interface ShortcutSheetRow extends ShortcutNamed {
+    readonly actions: readonly string[];
+}
+export interface ShortcutSheetColumn extends ShortcutNamed {
+    readonly rows: readonly ShortcutSheetRow[];
+}
+/** One surface's keys (`orbiters-play`, `ew-studio`, `site`). Two actions clash only inside a section. */
+export interface ShortcutSection {
+    readonly id: string;
+    /** The app it belongs to (`orbiters`) and that app's name. */
+    readonly app: string;
+    readonly appLabel: string;
+    readonly appNames?: ShortcutNames;
+    readonly label: string;
+    readonly names?: ShortcutNames;
+    /** Its name inside the app (`Play`, `Studio`); none when the app has only this section. */
+    readonly part?: string;
+    readonly partNames?: ShortcutNames;
+    /** How a command menu groups the actions, in its order. */
+    readonly groups: readonly ShortcutNamed[];
+    /** The keys sheet, where the app shows one in columns. */
+    readonly sheet?: readonly ShortcutSheetColumn[];
+    readonly actions: readonly ShortcutAction[];
+    /**
+     * Letters a surface of this section plays while it is open (`event.key`, lower-case; the Orbiters
+     * on-screen keyboard): a shortcut on one of them waits until it closes.
+     */
+    readonly heldKeys?: readonly string[];
+}
+export interface ShortcutCatalogue {
+    /** Changes whenever the catalogue is edited. */
+    readonly version: string;
+    readonly sections: readonly ShortcutSection[];
+}
+/** Before the catalogue is read: no sections, so no key does anything yet. */
+export declare const EMPTY_CATALOGUE: ShortcutCatalogue;
+/**
+ * The catalogue a response holds (`{ version, sections }`), or `null` when it holds none. A malformed
+ * section or action is left out rather than failing the whole read.
+ */
+export declare function parseCatalogue(value: unknown): ShortcutCatalogue | null;
+/** A name in a language (`es`, `es-AR`), the English when there is none in it. */
+export declare function localName(item: {
+    readonly label: string;
+    readonly names?: ShortcutNames;
+}, locale?: string): string;
+/** A section's app name in a language. */
+export declare function localAppName(section: Pick<ShortcutSection, 'appLabel' | 'appNames'>, locale?: string): string;
+/** A section's part name (`Play`, `Studio`) in a language; `undefined` when it has none. */
+export declare function localPartName(section: Pick<ShortcutSection, 'part' | 'partNames'>, locale?: string): string | undefined;
+/** The apps the catalogue has, in its order. */
+export declare function shortcutApps(catalogue: ShortcutCatalogue): ReadonlyArray<{
+    id: string;
+    label: string;
+    names?: ShortcutNames;
+}>;
+/**
+ * The actions of these sections, in the order named: where two sections hold one key, the first
+ * named wins (the Orbiter Studio lies over play). The same list object for as long as the catalogue
+ * is the same, so a cache keyed by it holds.
+ */
+export declare function sectionActions(catalogue: ShortcutCatalogue, ...sectionIds: string[]): readonly ShortcutAction[];
+/** One section, if the catalogue has it. */
+export declare function findSection(catalogue: ShortcutCatalogue, sectionId: string): ShortcutSection | undefined;

package/dist/shortcuts/catalogue.js

@@ -0,0 +1,118 @@
+// The shortcut catalogue as the apps read it: every app's sections of actions, their default keys and
+// names, as the backend serves them (from its config, so a key or a name changes without a library
+// release). This file only reads what was served; it holds no actions of its own.
+/** Before the catalogue is read: no sections, so no key does anything yet. */
+export const EMPTY_CATALOGUE = Object.freeze({ version: '', sections: Object.freeze([]) });
+const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const isString = (value) => typeof value === 'string' && value.length > 0;
+function names(value) {
+    if (!isRecord(value))
+        return undefined;
+    const out = {};
+    for (const [locale, name] of Object.entries(value))
+        if (isString(name))
+            out[locale] = name;
+    return Object.freeze(out);
+}
+function named(value) {
+    if (!isRecord(value) || !isString(value.id) || !isString(value.label))
+        return null;
+    return { id: value.id, label: value.label, names: names(value.names) };
+}
+function action(value) {
+    const base = named(value);
+    if (!base || !isRecord(value) || !isString(value.scope) || !Array.isArray(value.defaultKeys))
+        return null;
+    return Object.freeze({
+        ...base,
+        defaultKeys: Object.freeze(value.defaultKeys.filter(isString)),
+        scope: value.scope,
+        ...(isString(value.group) ? { group: value.group } : {}),
+        ...(value.command === false ? { command: false } : {}),
+        ...(isString(value.href) ? { href: value.href } : {}),
+        ...(value.signedIn === true ? { signedIn: true } : {}),
+    });
+}
+const list = (value, read) => Object.freeze(Array.isArray(value) ? value.map(read).filter((item) => item !== null) : []);
+function section(value) {
+    const base = named(value);
+    if (!base || !isRecord(value) || !isString(value.app) || !isString(value.appLabel))
+        return null;
+    return Object.freeze({
+        ...base,
+        app: value.app,
+        appLabel: value.appLabel,
+        appNames: names(value.appNames),
+        ...(isString(value.part) ? { part: value.part, partNames: names(value.partNames) } : {}),
+        groups: list(value.groups, named),
+        ...(Array.isArray(value.sheet)
+            ? {
+                sheet: list(value.sheet, (column) => {
+                    const head = named(column);
+                    if (!head || !isRecord(column))
+                        return null;
+                    return Object.freeze({
+                        ...head,
+                        rows: list(column.rows, (row) => {
+                            const line = named(row);
+                            return line && isRecord(row) ? Object.freeze({ ...line, actions: list(row.actions, (id) => (isString(id) ? id : null)) }) : null;
+                        }),
+                    });
+                }),
+            }
+            : {}),
+        actions: list(value.actions, action),
+        ...(Array.isArray(value.heldKeys) ? { heldKeys: list(value.heldKeys, (key) => (isString(key) ? key : null)) } : {}),
+    });
+}
+/**
+ * The catalogue a response holds (`{ version, sections }`), or `null` when it holds none. A malformed
+ * section or action is left out rather than failing the whole read.
+ */
+export function parseCatalogue(value) {
+    if (!isRecord(value) || !Array.isArray(value.sections))
+        return null;
+    return Object.freeze({ version: typeof value.version === 'string' ? value.version : '', sections: list(value.sections, section) });
+}
+/** A name in a language (`es`, `es-AR`), the English when there is none in it. */
+export function localName(item, locale) {
+    return item.names?.[(locale ?? '').slice(0, 2).toLowerCase()] ?? item.label;
+}
+/** A section's app name in a language. */
+export function localAppName(section, locale) {
+    return localName({ label: section.appLabel, names: section.appNames }, locale);
+}
+/** A section's part name (`Play`, `Studio`) in a language; `undefined` when it has none. */
+export function localPartName(section, locale) {
+    return section.part === undefined ? undefined : localName({ label: section.part, names: section.partNames }, locale);
+}
+/** The apps the catalogue has, in its order. */
+export function shortcutApps(catalogue) {
+    const seen = new Map();
+    for (const s of catalogue.sections)
+        if (!seen.has(s.app))
+            seen.set(s.app, { id: s.app, label: s.appLabel, names: s.appNames });
+    return [...seen.values()];
+}
+const actionLists = new WeakMap();
+/**
+ * The actions of these sections, in the order named: where two sections hold one key, the first
+ * named wins (the Orbiter Studio lies over play). The same list object for as long as the catalogue
+ * is the same, so a cache keyed by it holds.
+ */
+export function sectionActions(catalogue, ...sectionIds) {
+    let lists = actionLists.get(catalogue);
+    if (!lists)
+        actionLists.set(catalogue, (lists = new Map()));
+    const key = sectionIds.join('\n');
+    let found = lists.get(key);
+    if (!found) {
+        found = Object.freeze(sectionIds.flatMap((id) => catalogue.sections.find((s) => s.id === id)?.actions ?? []));
+        lists.set(key, found);
+    }
+    return found;
+}
+/** One section, if the catalogue has it. */
+export function findSection(catalogue, sectionId) {
+    return catalogue.sections.find((s) => s.id === sectionId);
+}

package/dist/shortcuts/chord.d.ts

@@ -0,0 +1,35 @@
+/** 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;
+}
+/** The chord a key string names, or `null` when it names none (an unknown modifier, a doubled one, no key). */
+export declare function parseChord(keys: string): Chord | null;
+/** Whether a press of `code` with these modifiers is this chord. */
+export declare function chordMatches(chord: Chord, code: string, state: ModifierState): boolean;
+/** A chord that needs Ctrl or ⌘: a command, never a character typed. */
+export declare function isCommandChord(chord: Chord): boolean;
+/** Whether one press could be both chords — the test for a clash. */
+export declare function chordsOverlap(a: Chord, b: Chord): boolean;
+/** The chords a key string names, one or two (a sequence); `null` when it names none. */
+export declare function parseKeys(keys: string): Chord[] | 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 declare function keysOverlap(a: string, b: string): boolean;
+/** A key that is only a modifier (or Caps Lock, Fn): never a shortcut's key on its own. */
+export declare const isModifierCode: (code: string) => boolean;

package/dist/shortcuts/chord.js

@@ -0,0 +1,99 @@
+// 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.
+const MODIFIERS = { Shift: 'shift', Alt: 'alt', Ctrl: 'ctrl', Meta: 'meta', Mod: 'mod' };
+const CODE = /^[A-Za-z][A-Za-z0-9]*$/;
+const parsed = new Map();
+/** The chord a key string names, or `null` when it names none (an unknown modifier, a doubled one, no key). */
+export function parseChord(keys) {
+    const known = parsed.get(keys);
+    if (known !== undefined)
+        return known;
+    const chord = parse(keys);
+    parsed.set(keys, chord);
+    return chord;
+}
+function parse(keys) {
+    if (typeof keys !== 'string')
+        return null;
+    const parts = keys.split('+');
+    const code = parts.pop();
+    if (!code || !CODE.test(code))
+        return null;
+    const rules = {
+        shift: 'free', alt: 'free', ctrl: 'free', meta: 'free', mod: 'free',
+    };
+    const seen = new Set();
+    for (const part of parts) {
+        const optional = part.endsWith('?');
+        const name = (optional ? part.slice(0, -1) : part);
+        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, down) => rule === 'any' || (rule === 'held') === Boolean(down);
+/** Whether a press of `code` with these modifiers is this chord. */
+export function chordMatches(chord, code, state) {
+    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) {
+    return chord.mod === 'held' || chord.ctrl === 'held' || chord.meta === 'held';
+}
+const STATES = 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, b) {
+    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) {
+    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 !== 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, b) {
+    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) => MODIFIER_CODES.has(code);

package/dist/shortcuts/format.d.ts

@@ -0,0 +1,44 @@
+/** 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 declare function shortcutPlatform(): ShortcutPlatform;
+/**
+ * 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>;
+/** What a key place is called on a keyboard: `KeyQ` → `Q`, `Digit1` → `1`, `Numpad4` → `Num 4`. */
+export declare function keyLabel(code: string, layout?: KeyLayout): string;
+/**
+ * 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 declare function chordParts(keys: string, platform?: ShortcutPlatform, layout?: KeyLayout): string[] | null;
+/** One line for a chord: `⌘⇧Z` on Apple keyboards, `Ctrl+Shift+Z` elsewhere. */
+export declare function formatChord(keys: string, platform?: ShortcutPlatform, layout?: KeyLayout): string;
+/**
+ * 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 declare function chordFromEvent(event: {
+    code: string;
+    shiftKey: boolean;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+}, platform?: ShortcutPlatform): string | null;
+/**
+ * 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 declare function mergedKeyParts(keysPerAction: ReadonlyArray<readonly string[]>, platform?: ShortcutPlatform, layout?: KeyLayout): string[][];
+/**
+ * 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 declare function recordedKeys(defaultKeys: readonly string[], pressed: string): string;

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,5 @@
+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 ShortcutNames, type ShortcutBindings, type ShortcutOverrides, type ShortcutEvent, } from './match.js';
+export { shortcutPlatform, keyLabel, chordParts, formatChord, chordFromEvent, mergedKeyParts, recordedKeys, type ShortcutPlatform, type KeyLayout, } from './format.js';
+export { EMPTY_CATALOGUE, parseCatalogue, localName, localAppName, localPartName, shortcutApps, sectionActions, findSection, type ShortcutCatalogue, type ShortcutSection, type ShortcutNamed, type ShortcutSheetColumn, type ShortcutSheetRow, } from './catalogue.js';
+export { createShortcutSource, localShortcutCatalogueStore, CATALOGUE_STORAGE_KEY, parseOverrides, type ShortcutCatalogueStore, type ShortcutSource, type ReadAccountSettings, type ReadShortcutCatalogue, } from './source.js';

package/dist/shortcuts/index.js

@@ -0,0 +1,9 @@
+// Keyboard shortcuts, one system for every app: the reader of the shortcut catalogue (every app's
+// actions and default keys, served by the backend) and of a person's own keys, 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 { shortcutPlatform, keyLabel, chordParts, formatChord, chordFromEvent, mergedKeyParts, recordedKeys, } from './format.js';
+export { EMPTY_CATALOGUE, parseCatalogue, localName, localAppName, localPartName, shortcutApps, sectionActions, findSection, } from './catalogue.js';
+export { createShortcutSource, localShortcutCatalogueStore, CATALOGUE_STORAGE_KEY, parseOverrides, } from './source.js';

package/dist/shortcuts/match.d.ts

@@ -0,0 +1,71 @@
+import { type ModifierState } from './chord.js';
+/** One thing a key can do, as the shortcut catalogue (served by the backend) lists 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;
+    /** What it does, in sentence case, in English. */
+    readonly label: string;
+    /** Its name in other languages, by locale (`{ es: '…' }`); see `localName`. */
+    readonly names?: ShortcutNames;
+    /** 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;
+    /** A site action: the page it opens (`{username}` stands for the signed-in person's). */
+    readonly href?: string;
+    /** It needs someone signed in. */
+    readonly signedIn?: boolean;
+}
+/** A name in other languages than English, by locale (`es`). */
+export type ShortcutNames = Readonly<Record<string, string>>;
+/** 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 the catalogue 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;