entangled-worlds-orbiters-shared 4.2.0 → 5.1.0

package/README.md

@@ -99,12 +99,13 @@ The capability registry (`createCapabilityRegistry`, `validate` / `assertValid`,
 - `largestFunction`, `shrinkWasm` - The size check and the shrink step
 
 ### Keyboard shortcuts (`entangled-worlds-orbiters-shared/shortcuts`)
-- `ShortcutAction` - One catalogue entry: `id`, `section`, `label`, `defaultKeys` (by key place, `event.code`), `scope`
+- `ShortcutAction` - One catalogue entry: `id`, `label` (+ `names` by language), `defaultKeys` (named as a US keyboard names them, `event.code`; a press matches by the character it types, by its place only where it types no US character, so keys work on any keyboard), `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
-- `ORBITERS_PLAY_SHORTCUTS`, `ORBITERS_STUDIO_SHORTCUTS` - The Orbiters catalogues
+- `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

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

@@ -18,8 +18,30 @@ export interface ModifierState {
 }
 /** 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 press as a chord reads it: the modifiers, the key's place and, when the browser says, the character it typed. */
+export interface ChordPress extends ModifierState {
+    readonly code: string;
+    readonly key?: string;
+}
+/** How a press is this chord: by the character it typed, by the key's place, or not at all. */
+export type ChordMatch = 'character' | 'place' | null;
+/**
+ * How a press is this chord. `character` beats `place`: on a Spanish keyboard Shift+7 types `/`, so it
+ * is the `/` key before it is the `7` key. A press with no `key` (an old caller) matches by place only.
+ */
+export declare function chordMatch(chord: Chord, press: ChordPress): ChordMatch;
+/** Whether a press of `code` with these modifiers (and, when given, the character it typed) is this chord. */
+export declare function chordMatches(chord: Chord, code: string, state: ModifierState & {
+    readonly key?: string;
+}): boolean;
+/**
+ * The key string a typed character names (`/` → `Slash`, `?` → `Shift+Slash`, `q` → `KeyQ`), for
+ * someone setting a key; `null` for a character a US keyboard does not have, or none.
+ */
+export declare function typedKey(key: string | undefined): {
+    readonly code: string;
+    readonly shift?: boolean;
+} | null;
 /** 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. */

package/dist/shortcuts/chord.js

@@ -1,7 +1,13 @@
 // 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:
+// The last part names the key the way a US keyboard does (`KeyboardEvent.code`: `KeyQ`, `Slash`,
+// `Digit1`). A press matches it by the CHARACTER it types wherever it types one, so `/` is the key
+// that prints `/` on this person's keyboard (Shift+7 on a Spanish one), and `KeyQ` is the key that
+// prints Q (top left on a French one). Only where the key types no character the US keyboard has
+// (a Greek or Cyrillic letter, ⌥ on a Mac changing it, a dead key, no letter on a letter key) is the
+// key matched by its place.
+// Digits match by character first, then by place: a French keyboard types `&` there.
+// Before the key, 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.
@@ -48,18 +54,90 @@ function parse(keys) {
     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;
+/**
+ * The punctuation keys a chord may name, and what a US keyboard types there without and with Shift:
+ * what the chord means on every keyboard. With these, Shift is part of the character (`?` is
+ * `Shift+Slash`), so a keyboard that needs Shift, or AltGr, for a `/` still types the `/`.
+ */
+const PUNCTUATION = {
+    Minus: ['-', '_'], Equal: ['=', '+'], BracketLeft: ['[', '{'], BracketRight: [']', '}'], Backslash: ['\\', '|'],
+    Semicolon: [';', ':'], Quote: ["'", '"'], Backquote: ['`', '~'], Comma: [',', '<'], Period: ['.', '>'], Slash: ['/', '?'],
+};
+/** The code a US keyboard types each punctuation character at, and whether it takes Shift. */
+const PUNCTUATION_PLACE = new Map(Object.entries(PUNCTUATION).flatMap(([code, [plain, shifted]]) => [[plain, [code, false]], [shifted, [code, true]]]));
+/** The character a press typed, when it is one a US keyboard has (printable ASCII); else `null`. */
+function typed(key) {
+    return typeof key === 'string' && key.length === 1 && key >= '!' && key <= '~' ? key : null;
+}
+function commandFits(chord, state) {
     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);
 }
+function placeMatch(chord, code, state) {
+    return chord.code === code && fits(chord.shift, state.shiftKey) && fits(chord.alt, state.altKey) && commandFits(chord, state);
+}
+/**
+ * How a press is this chord. `character` beats `place`: on a Spanish keyboard Shift+7 types `/`, so it
+ * is the `/` key before it is the `7` key. A press with no `key` (an old caller) matches by place only.
+ */
+export function chordMatch(chord, press) {
+    const char = typed(press.key);
+    if (char === null)
+        return placeMatch(chord, press.code, press) ? 'place' : null;
+    const punctuation = PUNCTUATION[chord.code];
+    if (punctuation) {
+        // Shift is in the character (a Spanish `/` is Shift+7); with ⌘ some browsers report the key
+        // unshifted, so `⇧⌘,` is also a `,` with Shift held. Alt only when the chord asks for it (AltGr
+        // and ⌥ type characters).
+        const [plain, shifted] = punctuation;
+        const asShifted = char === shifted || (isCommandChord(chord) && char === plain && press.shiftKey);
+        const ok = chord.shift === 'held' ? asShifted : chord.shift === 'any' ? char === plain || asShifted : char === plain;
+        // A command (⇧⌘,) where this keyboard types another character there: the key's place, as menus do.
+        if (!ok)
+            return isCommandChord(chord) && placeMatch(chord, press.code, press) ? 'place' : null;
+        if (chord.alt === 'held' && !press.altKey)
+            return null;
+        // AltGr arrives as Ctrl+Alt on Windows: that Ctrl typed the character, it is no command.
+        const altGr = press.altKey && press.ctrlKey && !press.metaKey;
+        return commandFits(chord, { ctrlKey: press.ctrlKey && !altGr, metaKey: press.metaKey, shiftKey: press.shiftKey, altKey: press.altKey }) ? 'character' : null;
+    }
+    const letter = /^Key([A-Z])$/.exec(chord.code)?.[1];
+    if (letter) {
+        // A key that types no letter (`;` where Q is on a Greek keyboard) is read by its place.
+        if (!/^[a-zA-Z]$/.test(char))
+            return placeMatch(chord, press.code, press) ? 'place' : null;
+        if (char.toUpperCase() !== letter)
+            return null;
+        return fits(chord.shift, press.shiftKey) && fits(chord.alt, press.altKey) && commandFits(chord, press) ? 'character' : null;
+    }
+    const digit = /^Digit(\d)$/.exec(chord.code)?.[1];
+    // A digit typed; where the keyboard types something else there (`&` on a French one), its place.
+    if (digit && char === digit && fits(chord.shift, press.shiftKey) && fits(chord.alt, press.altKey) && commandFits(chord, press))
+        return 'character';
+    return placeMatch(chord, press.code, press) ? 'place' : null;
+}
+/** Whether a press of `code` with these modifiers (and, when given, the character it typed) is this chord. */
+export function chordMatches(chord, code, state) {
+    // Field by field: a browser's KeyboardEvent keeps them on its prototype, where a spread does not reach.
+    const { shiftKey, altKey, ctrlKey, metaKey, key } = state;
+    return chordMatch(chord, { code, key, shiftKey, altKey, ctrlKey, metaKey }) !== null;
+}
+/**
+ * The key string a typed character names (`/` → `Slash`, `?` → `Shift+Slash`, `q` → `KeyQ`), for
+ * someone setting a key; `null` for a character a US keyboard does not have, or none.
+ */
+export function typedKey(key) {
+    const char = typed(key);
+    if (char === null)
+        return null;
+    if (/^[a-zA-Z]$/.test(char))
+        return { code: `Key${char.toUpperCase()}` };
+    const place = PUNCTUATION_PLACE.get(char);
+    return place ? { code: place[0], shift: place[1] } : null;
+}
 /** 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';

package/dist/shortcuts/format.d.ts

@@ -4,8 +4,8 @@ export type ShortcutPlatform = 'apple' | 'other';
 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.
+ * (`navigator.keyboard.getLayoutMap()`, Chromium only). Only keys matched by their place use it:
+ * a letter, digit or punctuation key matches the character it names, so it shows that character.
  */
 export type KeyLayout = ReadonlyMap<string, string>;
 /** What a key place is called on a keyboard: `KeyQ` → `Q`, `Digit1` → `1`, `Numpad4` → `Num 4`. */
@@ -20,11 +20,14 @@ export declare function chordParts(keys: string, platform?: ShortcutPlatform, la
 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.
+ * key of their platform written `Mod` (⌘ on Apple, Ctrl elsewhere) so the key works on both. A letter
+ * or punctuation character typed is written as the key that types it on a US keyboard (`/` is
+ * `Slash` whichever keys typed it), the way the matcher reads it back. `null` while only modifiers
+ * are down, or for a press with no key place.
  */
 export declare function chordFromEvent(event: {
     code: string;
+    key?: string;
     shiftKey: boolean;
     altKey: boolean;
     ctrlKey: boolean;

package/dist/shortcuts/format.js

@@ -1,6 +1,6 @@
 // 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';
+import { isModifierCode, parseChord, typedKey } from './chord.js';
 /** The platform of this browser, by its own report; `other` outside a browser. */
 export function shortcutPlatform() {
     const nav = globalThis.navigator;
@@ -18,7 +18,8 @@ const NAMED = {
 };
 /** 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);
+    const byCharacter = /^(Key[A-Z]|Digit\d)$/.test(code) || typedKey(NAMED[code])?.code === code;
+    const printed = byCharacter ? undefined : layout?.get(code);
     if (printed && printed.trim())
         return printed.length === 1 ? printed.toUpperCase() : printed;
     if (/^Key[A-Z]$/.test(code))
@@ -29,6 +30,11 @@ export function keyLabel(code, layout) {
         return `Num ${code.slice(6)}`;
     return NAMED[code] ?? code;
 }
+/** What a US keyboard types with Shift at each punctuation key. */
+const SHIFTED = {
+    Minus: '_', Equal: '+', BracketLeft: '{', BracketRight: '}', Backslash: '|', Semicolon: ':', Quote: '"',
+    Backquote: '~', Comma: '<', Period: '>', Slash: '?',
+};
 const SYMBOLS = { ctrl: '⌃', alt: '⌥', shift: '⇧', meta: '⌘' };
 const WORDS = { ctrl: 'Ctrl', alt: 'Alt', shift: 'Shift', meta: 'Meta' };
 /**
@@ -55,12 +61,16 @@ export function chordParts(keys, platform = shortcutPlatform(), layout) {
         parts.push(names.ctrl);
     if (held(chord.alt))
         parts.push(platform === 'apple' ? names.alt : 'Alt');
-    if (held(chord.shift))
+    // A punctuation key is the character it types, Shift included: `Shift+Slash` is `?`.
+    // A command (⇧⌘,) is shown as written: its Shift is a key to press, not part of a character.
+    const punctuation = !ctrl && !meta && typedKey(NAMED[chord.code])?.code === chord.code ? SHIFTED[chord.code] : undefined;
+    if (held(chord.shift) && !punctuation)
         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));
+    // The help key is `?` wherever it lets Shift be held (`/` or `?`): show what people press.
+    const shifted = punctuation && (held(chord.shift) || (chord.code === 'Slash' && chord.shift === 'any'));
+    parts.push(shifted ? punctuation : keyLabel(chord.code, layout));
     return parts;
 }
 /** One line for a chord: `⌘⇧Z` on Apple keyboards, `Ctrl+Shift+Z` elsewhere. */
@@ -74,28 +84,44 @@ export function formatChord(keys, platform = shortcutPlatform(), layout) {
 }
 /**
  * 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.
+ * key of their platform written `Mod` (⌘ on Apple, Ctrl elsewhere) so the key works on both. A letter
+ * or punctuation character typed is written as the key that types it on a US keyboard (`/` is
+ * `Slash` whichever keys typed it), the way the matcher reads it back. `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 typed = typedKey(event.key);
+    const punctuation = typed?.shift !== undefined;
+    // A punctuation character carries its own Shift, and the AltGr or ⌥ that typed it is no modifier.
+    const altGr = punctuation && event.altKey && event.ctrlKey && !event.metaKey;
+    // Field by field: a browser's KeyboardEvent keeps them on its prototype, where a spread does not reach.
+    const press = punctuation
+        ? {
+            // With ⌘ or Ctrl some browsers report the key unshifted: the Shift held is then part of the chord.
+            shiftKey: Boolean(typed.shift) || (event.shiftKey && !altGr && (event.ctrlKey || event.metaKey)),
+            altKey: false,
+            ctrlKey: altGr ? false : event.ctrlKey,
+            metaKey: event.metaKey,
+        }
+        : event;
     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)
+    if (press.ctrlKey && press.metaKey)
         parts.push('Ctrl', 'Meta');
-    else if (platform === 'apple' ? event.metaKey : event.ctrlKey)
+    else if (platform === 'apple' ? press.metaKey : press.ctrlKey)
         parts.push('Mod');
-    else if (event.ctrlKey)
+    else if (press.ctrlKey)
         parts.push('Ctrl');
-    else if (event.metaKey)
+    else if (press.metaKey)
         parts.push('Meta');
-    if (event.altKey)
+    if (press.altKey)
         parts.push('Alt');
-    if (event.shiftKey)
+    if (press.shiftKey)
         parts.push('Shift');
-    parts.push(event.code);
+    parts.push(typed?.code ?? event.code);
     const keys = parts.join('+');
     return parseChord(keys) ? keys : null;
 }

package/dist/shortcuts/index.d.ts

@@ -1,9 +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 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 { parseChord, parseKeys, keysOverlap, chordMatch, chordMatches, chordsOverlap, typedKey, isCommandChord, type Chord, type ModifierRule, type ModifierState, type ChordMatch, type ChordPress, } 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 { 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';
+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

@@ -1,13 +1,10 @@
-// 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';
+// 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 as a US keyboard names them
+// (`KeyboardEvent.code`) and matched by the character a press types, so they work on any keyboard.
+// Framework-free: no React, no DOM beyond reading a key event.
+export { parseChord, parseKeys, keysOverlap, chordMatch, chordMatches, chordsOverlap, typedKey, 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';
+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

@@ -1,12 +1,12 @@
 import { type ModifierState } from './chord.js';
-/** One thing a key can do, as an app's catalogue declares it. */
+/** 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;
-    /** 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. */
+    /** 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). */
@@ -15,12 +15,18 @@ export interface ShortcutAction<Scope extends string = string> {
     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 code reaches everyone who never touched it.
+ * 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;
@@ -52,7 +58,9 @@ export declare function isKeyClaimed(event: Pick<ShortcutEvent, 'key' | 'metaKey
 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.
+ * surface holds; a widget that reads characters keeps its characters but not the ⌘ commands. A key
+ * that matches by the character typed wins over one that only matches by the key's place, whatever
+ * their order (Shift+7 types `/` on a Spanish keyboard: the `/` action, not the `7` one).
  */
 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. */

package/dist/shortcuts/match.js

@@ -1,7 +1,7 @@
 // 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';
+import { chordMatch, 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.
@@ -81,23 +81,29 @@ function readsCharacters(target) {
 }
 /**
  * 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.
+ * surface holds; a widget that reads characters keeps its characters but not the ⌘ commands. A key
+ * that matches by the character typed wins over one that only matches by the key's place, whatever
+ * their order (Shift+7 types `/` on a Spanish keyboard: the `/` action, not the `7` one).
  */
 export function matchShortcut(event, bindings) {
     if (!event.code || isTypingTarget(event.target) || isKeyClaimed(event))
         return null;
     const characters = readsCharacters(event.target);
+    let byPlace = null;
     for (const [actionId, keys] of bindings) {
         for (const key of keys) {
             const chord = parseChord(key);
-            if (!chord || !chordMatches(chord, event.code, event))
+            const how = chord && chordMatch(chord, event);
+            if (!chord || !how)
                 continue;
-            if (characters && !isCommandChord(chord))
-                return null;
-            return actionId;
+            if (how === 'character')
+                return characters && !isCommandChord(chord) ? null : actionId;
+            byPlace ??= { id: actionId, command: isCommandChord(chord) };
         }
     }
-    return null;
+    if (!byPlace || (characters && !byPlace.command))
+        return null;
+    return byPlace.id;
 }
 // ---------------------------------------------------------------------------------------------
 // Sequences
@@ -137,7 +143,7 @@ export function createShortcutMatcher(waitMs = SEQUENCE_WAIT_MS, now = Date.now)
                     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() };
+            first = { code: event.code, key: event.key, shiftKey: event.shiftKey, altKey: event.altKey, ctrlKey: event.ctrlKey, metaKey: event.metaKey, at: now() };
             return null;
         }
         return matchShortcut(event, bindings);