entangled-worlds-orbiters-shared 4.1.0 → 4.2.0

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[];

package/dist/shortcuts/orbiters.js

@@ -0,0 +1,109 @@
+// The Orbiters catalogues: every key Orbiters answers, with the keys it has by default.
+//
+// `voice` acts on the focused deck(s), so in a shared session it only reaches a deck this person
+// holds; `client` is about this machine and no deck (MIDI learn, performance mode, the Studio).
+export const ORBITERS_PLAY_SECTION = 'orbiters-play';
+export const ORBITERS_STUDIO_SECTION = 'orbiters-studio';
+const play = (id, label, defaultKeys, { scope = 'voice', group, command } = {}) => Object.freeze({
+    id: `orbiters.play.${id}`, section: ORBITERS_PLAY_SECTION, label, defaultKeys: Object.freeze([...defaultKeys]), scope,
+    ...(group ? { group } : {}), ...(command === false ? { command } : {}),
+});
+const studio = (id, label, defaultKeys) => Object.freeze({ id: `orbiters.studio.${id}`, section: ORBITERS_STUDIO_SECTION, label, defaultKeys: Object.freeze([...defaultKeys]), scope: 'client', group: 'studio' });
+/** How a command menu groups the actions, in its order. */
+export const ORBITERS_COMMAND_GROUPS = Object.freeze([
+    { id: 'transport', label: 'Transport' },
+    { id: 'view', label: 'View' },
+    { id: 'snapshots', label: 'Snapshots' },
+    { id: 'panels', label: 'Panels' },
+    { id: 'orbiter', label: 'Orbiter' },
+    { id: 'studio', label: 'Studio' },
+]);
+/** The snapshot slots, by the number each shows: the number row, 1 to 9, then 0. */
+const SLOT_NUMBERS = [1, 2, 3, 4, 5, 6, 7, 8, 9, 0];
+/** Undo and redo, the same keys wherever an edit can be taken back. */
+const UNDO_KEYS = ['Mod+KeyZ'];
+const REDO_KEYS = ['Mod+Shift+KeyZ', 'Ctrl+Shift?+KeyY'];
+/**
+ * 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 const ORBITERS_PLAY_SHORTCUTS = Object.freeze([
+    // Space takes Ctrl, Option and ⌘ as it comes: only Shift changes what it does.
+    play('transport.toggle', 'Play or pause', ['Alt?+Ctrl?+Meta?+Space'], { group: 'transport' }),
+    play('transport.restart', 'Play from the beginning', ['Shift+Alt?+Ctrl?+Meta?+Space'], { group: 'transport' }),
+    play('rec.hold', 'Record while held', ['KeyR'], { group: 'transport', command: false }),
+    play('rec.toggle', 'Rec on or off', ['Shift+KeyR'], { group: 'transport' }),
+    play('history.undo', 'Undo', UNDO_KEYS, { group: 'transport' }),
+    play('history.redo', 'Redo', REDO_KEYS, { group: 'transport' }),
+    play('dimension.1', 'First dimension', ['Shift?+Digit1'], { group: 'view' }),
+    play('dimension.2', 'Second dimension', ['Shift?+Digit2'], { group: 'view' }),
+    play('dimension.3', 'Third dimension', ['Shift?+Digit3'], { group: 'view' }),
+    play('body.world', 'World', ['Shift?+KeyQ'], { group: 'view' }),
+    play('body.moon', 'Moon', ['Shift?+KeyW'], { group: 'view' }),
+    play('body.star', 'Star', ['Shift?+KeyE'], { group: 'view' }),
+    ...SLOT_NUMBERS.map((n) => play(`snapshot.recall.${n}`, `Recall snapshot ${n}`, [`Alt+Digit${n}`], { group: 'snapshots' })),
+    ...SLOT_NUMBERS.map((n) => play(`snapshot.store.${n}`, `Store snapshot ${n}`, [`Alt+Shift+Digit${n}`], { group: 'snapshots' })),
+    // The panels, from the bottom of the rail up.
+    play('panel.jamming', 'Jamming', ['KeyA'], { group: 'panels' }),
+    play('panel.playback', 'Playback', ['KeyS'], { group: 'panels' }),
+    play('panel.cosmicLfo', 'Cosmic LFO', ['KeyD'], { group: 'panels' }),
+    play('panel.sensors', 'Sensors', ['KeyF'], { group: 'panels' }),
+    // The More menu, and this machine's switches.
+    play('midiLearn', 'MIDI learn', ['Shift?+KeyM'], { scope: 'client', group: 'orbiter' }),
+    play('performanceMode', 'Performance mode', ['Shift?+KeyP'], { scope: 'client', group: 'orbiter' }),
+    play('screenCapture', 'Screen capture', [], { scope: 'client', group: 'orbiter' }),
+    play('share', 'Share', [], { scope: 'client', group: 'orbiter' }),
+    play('fullscreen', 'Fullscreen', [], { scope: 'client', group: 'orbiter' }),
+    // `?` on a US keyboard: the key's place, whatever this keyboard prints there.
+    play('help', 'Keyboard shortcuts', ['Shift?+Slash'], { scope: 'client', group: 'orbiter', command: false }),
+    play('commands', 'Commands', ['Mod+KeyK'], { scope: 'client', group: 'orbiter', command: false }),
+]);
+/**
+ * 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 const ORBITERS_PLAY_SHEET = Object.freeze([
+    { id: 'transport', label: 'Transport', rows: [
+            { id: 'playPause', label: 'Play / pause', actions: ['transport.toggle'] },
+            { id: 'playFromStart', label: 'Play from start', actions: ['transport.restart'] },
+            { id: 'recHeld', label: 'REC while held', actions: ['rec.hold'] },
+            { id: 'recLatch', label: 'REC latch', actions: ['rec.toggle'] },
+            { id: 'undo', label: 'Undo', actions: ['history.undo'] },
+            { id: 'redo', label: 'Redo', actions: ['history.redo'] },
+        ] },
+    { id: 'view', label: 'View', rows: [
+            { id: 'dimensions', label: 'Dimension I · II · III', actions: ['dimension.1', 'dimension.2', 'dimension.3'] },
+            { id: 'bodies', label: 'World · Moon · Star', actions: ['body.world', 'body.moon', 'body.star'] },
+            { id: 'snapshotRecall', label: 'Snapshot recall', actions: SLOT_NUMBERS.map((n) => `snapshot.recall.${n}`) },
+            { id: 'snapshotStore', label: 'Snapshot store', actions: SLOT_NUMBERS.map((n) => `snapshot.store.${n}`) },
+        ] },
+    { id: 'panels', label: 'Panels', rows: [
+            { id: 'jamming', label: 'Jamming', actions: ['panel.jamming'] },
+            { id: 'playback', label: 'Playback', actions: ['panel.playback'] },
+            { id: 'cosmicLfo', label: 'Cosmic LFO', actions: ['panel.cosmicLfo'] },
+            { id: 'sensors', label: 'Sensors', actions: ['panel.sensors'] },
+            { id: 'midiLearn', label: 'MIDI learn', actions: ['midiLearn'] },
+            { id: 'performanceMode', label: 'Performance mode', actions: ['performanceMode'] },
+        ] },
+].map((column) => Object.freeze({
+    ...column,
+    rows: Object.freeze(column.rows.map((row) => Object.freeze({ ...row, actions: Object.freeze(row.actions.map((a) => `orbiters.play.${a}`)) }))),
+})));
+/**
+ * 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 const ORBITERS_STUDIO_SHORTCUTS = Object.freeze([
+    studio('undo', 'Undo', UNDO_KEYS),
+    studio('redo', 'Redo', REDO_KEYS),
+    studio('map', 'Map', ['Shift+KeyM']),
+]);
+/**
+ * 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 const ORBITERS_KEYBOARD_SURFACE_KEYS = Object.freeze([
+    'a', 'w', 's', 'e', 'd', 'f', 't', 'g', 'y', 'h', 'u', 'j', 'k', 'o', 'l', 'p', ';', "'", 'z', 'x', 'c', 'v',
+]);

package/dist/shortcuts/overrides.d.ts

@@ -0,0 +1,30 @@
+import { type ShortcutAction, type ShortcutOverrides } from './match.js';
+/** The overrides in a stored value, or `null` when it is not a list of `{ id, keys }`. */
+export declare function parseOverrides(value: unknown): ShortcutOverrides | null;
+/**
+ * How the app reads the signed-in person's settings: `null` when no one is signed in (the
+ * default keys); `undefined` when the read failed (the overrides in force are kept: a blip must not
+ * swap someone's keys for the defaults).
+ */
+export type ReadAccountSettings = (options: {
+    fresh: boolean;
+}) => Promise<{
+    shortcuts?: unknown;
+} | null | undefined>;
+export interface ShortcutOverridesSource {
+    /** The overrides in force. */
+    get(): ShortcutOverrides;
+    /** A catalogue's actions with their keys now (kept until the overrides change). */
+    bindings(catalogue: readonly ShortcutAction[]): Map<string, readonly string[]>;
+    /** Called whenever the overrides change; returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** Read again (`fresh`: past the app's own cached read). The newest read wins, whatever order they end in. */
+    refresh(options?: {
+        fresh?: boolean;
+    }): Promise<void>;
+    /** Read now, and again whenever the page comes back to the front; once per source. */
+    bind(): void;
+    /** For tests: set the overrides directly. */
+    set(overrides: ShortcutOverrides): void;
+}
+export declare function createShortcutOverridesSource(readAccount: ReadAccountSettings): ShortcutOverridesSource;

package/dist/shortcuts/overrides.js

@@ -0,0 +1,81 @@
+// A person's shortcut overrides, read the same way by every app: from their account when signed in
+// (someone signed out has the default keys), and again whenever the page comes back to the front (a key changed
+// on the settings page applies on return, without a reload).
+//
+// Framework-free: the app hands in how it reads the account (its own API client) and gets the
+// overrides and each catalogue's resolved keys back, kept until the overrides change.
+import { resolveBindings } from './match.js';
+/** The overrides in a stored value, or `null` when it is not a list of `{ id, keys }`. */
+export function parseOverrides(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.filter((entry) => !!entry && typeof entry.id === 'string' && Array.isArray(entry.keys) && entry.keys.every((k) => typeof k === 'string'));
+}
+/** Coming back to the front twice in a row (visible, then focus) asks the account once. */
+const REFRESH_GAP_MS = 2000;
+export function createShortcutOverridesSource(readAccount) {
+    let overrides = [];
+    let resolved = new WeakMap();
+    let latest = 0;
+    let applied = 0;
+    let lastRefreshAt = -Infinity;
+    let bound = false;
+    const listeners = new Set();
+    const apply = (next) => {
+        if (JSON.stringify(next) === JSON.stringify(overrides))
+            return;
+        overrides = next;
+        resolved = new WeakMap();
+        listeners.forEach((listener) => listener());
+    };
+    const refresh = async ({ fresh = false } = {}) => {
+        const ticket = ++latest;
+        lastRefreshAt = Date.now();
+        let settings;
+        try {
+            settings = await readAccount({ fresh });
+        }
+        catch {
+            settings = undefined;
+        }
+        // The newest read that answered wins: an older one ending after it says nothing new, and a newer
+        // one that failed does not throw away an older one's answer.
+        if (settings === undefined || ticket < applied)
+            return;
+        applied = ticket;
+        apply(settings === null ? [] : (parseOverrides(settings.shortcuts) ?? []));
+    };
+    return {
+        get: () => overrides,
+        bindings(catalogue) {
+            let map = resolved.get(catalogue);
+            if (!map) {
+                map = resolveBindings(catalogue, overrides);
+                resolved.set(catalogue, map);
+            }
+            return map;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        refresh,
+        bind() {
+            const win = globalThis;
+            if (bound || typeof win.addEventListener !== 'function' || !win.document?.addEventListener)
+                return;
+            bound = true;
+            void refresh();
+            const onFront = () => {
+                if (win.document?.visibilityState !== 'visible' || Date.now() - lastRefreshAt < REFRESH_GAP_MS)
+                    return;
+                void refresh({ fresh: true });
+            };
+            win.document.addEventListener('visibilitychange', onFront);
+            win.addEventListener('focus', onFront);
+        },
+        set: apply,
+    };
+}

package/dist/shortcuts/sections.d.ts

@@ -0,0 +1,23 @@
+import type { ShortcutAction } from './match.js';
+/** The apps a person tells apart, in the order a settings page shows them. */
+export declare const SHORTCUT_APPS: readonly [Readonly<{
+    id: "plantasia-space";
+    label: "Plantasia Space";
+}>, Readonly<{
+    id: "orbiters";
+    label: "Orbiters";
+}>, Readonly<{
+    id: "entangled-worlds";
+    label: "Entangled Worlds";
+}>];
+export type ShortcutAppId = (typeof SHORTCUT_APPS)[number]['id'];
+export interface ShortcutSection {
+    readonly id: string;
+    readonly label: string;
+    /** The app it belongs to. */
+    readonly app: ShortcutAppId;
+    /** Its name inside that app (`Play`, `Studio`); none when the app has only this section. */
+    readonly part?: string;
+    readonly actions: readonly ShortcutAction[];
+}
+export declare const SHORTCUT_SECTIONS: readonly ShortcutSection[];

package/dist/shortcuts/sections.js

@@ -0,0 +1,19 @@
+// Every app's catalogue in one place, in the order a settings page shows them. A section is one
+// surface's keys; two actions may share a key only across sections (the Orbiter Studio lies over
+// play, and takes ⌘Z from it while it is open).
+import { EW_PLAYER_SECTION, EW_PLAYER_SHORTCUTS, EW_STUDIO_SECTION, EW_STUDIO_SHORTCUTS } from './entangledWorlds.js';
+import { ORBITERS_PLAY_SECTION, ORBITERS_PLAY_SHORTCUTS, ORBITERS_STUDIO_SECTION, ORBITERS_STUDIO_SHORTCUTS } from './orbiters.js';
+import { SITE_SECTION, SITE_SHORTCUTS } from './site.js';
+/** The apps a person tells apart, in the order a settings page shows them. */
+export const SHORTCUT_APPS = Object.freeze([
+    Object.freeze({ id: 'plantasia-space', label: 'Plantasia Space' }),
+    Object.freeze({ id: 'orbiters', label: 'Orbiters' }),
+    Object.freeze({ id: 'entangled-worlds', label: 'Entangled Worlds' }),
+]);
+export const SHORTCUT_SECTIONS = Object.freeze([
+    Object.freeze({ id: SITE_SECTION, label: 'Plantasia Space', app: 'plantasia-space', actions: SITE_SHORTCUTS }),
+    Object.freeze({ id: ORBITERS_PLAY_SECTION, label: 'Orbiters play', app: 'orbiters', part: 'Play', actions: ORBITERS_PLAY_SHORTCUTS }),
+    Object.freeze({ id: ORBITERS_STUDIO_SECTION, label: 'Orbiter Studio', app: 'orbiters', part: 'Studio', actions: ORBITERS_STUDIO_SHORTCUTS }),
+    Object.freeze({ id: EW_STUDIO_SECTION, label: 'Entangled Worlds studio', app: 'entangled-worlds', part: 'Studio', actions: EW_STUDIO_SHORTCUTS }),
+    Object.freeze({ id: EW_PLAYER_SECTION, label: 'Entangled Worlds player', app: 'entangled-worlds', part: 'Player', actions: EW_PLAYER_SHORTCUTS }),
+]);

package/dist/shortcuts/site.d.ts

@@ -0,0 +1,9 @@
+import type { ShortcutAction } from './match.js';
+export type SiteShortcut = ShortcutAction<'client'>;
+export declare const SITE_SECTION = "site";
+/**
+ * Two-key sequences move around the site (G, then H for Home; N, then O for a new Orbiter), as on
+ * many sites: a single letter is an Orbiter's on a page that plays one, and the browser holds most
+ * ⌘ and ⇧⌘ letters.
+ */
+export declare const SITE_SHORTCUTS: readonly SiteShortcut[];

package/dist/shortcuts/site.js

@@ -0,0 +1,25 @@
+// The Plantasia Space site's own keys: the pages around the apps (home, explore, settings). They
+// work on any page of the site, outside an Orbiter or a world.
+export const SITE_SECTION = 'site';
+const site = (id, label, keys) => Object.freeze({ id: `site.${id}`, section: SITE_SECTION, label, defaultKeys: Object.freeze([keys]), scope: 'client' });
+/**
+ * Two-key sequences move around the site (G, then H for Home; N, then O for a new Orbiter), as on
+ * many sites: a single letter is an Orbiter's on a page that plays one, and the browser holds most
+ * ⌘ and ⇧⌘ letters.
+ */
+export const SITE_SHORTCUTS = Object.freeze([
+    site('settings', 'Open settings', 'Mod+Shift+Comma'),
+    site('commands', 'Commands', 'Mod+KeyK'),
+    site('search', 'Search', 'Slash'),
+    site('go.home', 'Home', 'KeyG KeyH'),
+    site('go.playground', 'Playground', 'KeyG KeyP'),
+    site('go.notifications', 'Notifications', 'KeyG KeyN'),
+    site('go.audios', 'My audios', 'KeyG KeyA'),
+    site('go.orbiters', 'My Orbiters', 'KeyG KeyO'),
+    site('go.worlds', 'My Entangled Worlds', 'KeyG KeyW'),
+    site('go.collections', 'My collections', 'KeyG KeyC'),
+    site('go.stars', 'My stars', 'KeyG KeyS'),
+    site('new.orbiter', 'New Orbiter', 'KeyN KeyO'),
+    site('new.audio', 'New audio', 'KeyN KeyA'),
+    site('new.world', 'New Entangled World', 'KeyN KeyW'),
+]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "dist/index.js",
@@ -86,6 +86,10 @@
     "./audio": {
       "types": "./dist/audio/index.d.ts",
       "import": "./dist/audio/index.js"
+    },
+    "./shortcuts": {
+      "types": "./dist/shortcuts/index.d.ts",
+      "import": "./dist/shortcuts/index.js"
     }
   },
   "files": [

package/src/shortcuts/chord.ts

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