entangled-worlds-orbiters-shared 4.0.0 → 4.2.0

package/README.md

@@ -98,6 +98,14 @@ 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`, `section`, `label`, `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
+- `ORBITERS_PLAY_SHORTCUTS`, `ORBITERS_STUDIO_SHORTCUTS` - The Orbiters catalogues
+
 ### 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/clock/Transport.d.ts

@@ -71,9 +71,15 @@ export declare class Transport {
     private _nextDist;
     setProjection(projection: MusicalProjectionLike | null): void;
     musicalPosition(): unknown;
-    applyAnchoredState(s: AnchoredState): void;
+    /**
+     * Apply a peer's anchored state. A malformed one (unknown playState, non-finite position, anchor or
+     * loop bounds, or a rate that is not a finite number > 0) is DROPPED whole and `false` is returned: the transport keeps its last
+     * good state until the next good one arrives. It never throws — this runs inside `tick()`.
+     */
+    applyAnchoredState(s: AnchoredState): boolean;
     /** Arm an anchored state (with optional control) to apply when audio time reaches `atAudioSec`. */
-    scheduleStateChange(atAudioSec: number, state: AnchoredState, meta?: ScheduleStateMeta): void;
+    /** Returns `false` (and arms nothing) for a non-finite `atAudioSec` or a malformed state. */
+    scheduleStateChange(atAudioSec: number, state: AnchoredState, meta?: ScheduleStateMeta): boolean;
     /** Drop pending changes older than a freshly-applied (term,seq) — supersession (Codex fix #4). */
     dropPendingOlderThan(term: number, seq: number): void;
     private _drainPending;

package/dist/clock/Transport.js

@@ -11,6 +11,22 @@
 //   - Looping is handled by computing each event's NEXT occurrence distance (wrapping across the loop
 //     boundary), so events just after loopStart are armed during the pre-wrap look-ahead.
 const EPS = 1e-9;
+function isValidRate(rate) {
+    return Number.isFinite(rate) && rate > 0;
+}
+function isValidAnchoredState(s) {
+    if (s.playState !== 'playing' && s.playState !== 'paused')
+        return false;
+    if (!Number.isFinite(s.positionSec))
+        return false;
+    if (s.anchorAudioSec != null && !Number.isFinite(s.anchorAudioSec))
+        return false;
+    if (s.rate != null && !isValidRate(s.rate))
+        return false;
+    if (s.loop && !(Number.isFinite(s.loop.startSec) && Number.isFinite(s.loop.endSec)))
+        return false;
+    return true;
+}
 export class Transport {
     backend;
     lookaheadSec;
@@ -63,13 +79,15 @@ export class Transport {
         this._cancelArmed(); // armed future audio must not sound during pause; re-armed on resume
     }
     seekSec(sec) {
+        if (!Number.isFinite(sec))
+            return; // a NaN seek is ignored, never freezes the transport
         this._reanchor(Math.max(0, sec));
         this._cancelArmed();
         this._reopenEvents(); // a seek MOVES position -> fired events may replay
     }
     setRate(rate) {
-        if (rate <= 0)
-            throw new Error('rate must be > 0');
+        if (!isValidRate(rate))
+            throw new Error('rate must be a finite number > 0');
         this._reanchor();
         this._rate = rate;
         this._cancelArmed(); // window/audio-time changed -> re-arm pending events (NOT replay fired ones)
@@ -81,6 +99,8 @@ export class Transport {
         return this._playing;
     }
     setLoopSec(loop) {
+        if (loop && !(Number.isFinite(loop.startSec) && Number.isFinite(loop.endSec)))
+            return; // ignored
         this._loop = loop ? { startSec: loop.startSec, endSec: loop.endSec } : null;
         this._cancelArmed();
         this._reopenEvents(); // loop topology changed -> events may re-enter/leave the loop window
@@ -149,6 +169,11 @@ export class Transport {
                     d += len; // wrapped into the next pass
                 return d;
             }
+            // At or past the loop end: the transport wraps back to startSec before getting there, so the
+            // event never occurs while looping. Without this, its look-ahead distance came out positive just
+            // before the wrap and it armed (and sounded) at the wrap instant, at a position never reached.
+            if (len > 0 && ev.atSec >= endSec - EPS)
+                return null;
         }
         const d = ev.atSec - pos;
         return d >= -EPS ? d : null; // non-loop: a passed event won't fire again until a seek
@@ -161,7 +186,14 @@ export class Transport {
         return this._projection ? this._projection.musicalAt(this.positionSec()) : null;
     }
     // ---- sync apply (Inc 3) -------------------------------------------------------------
+    /**
+     * Apply a peer's anchored state. A malformed one (unknown playState, non-finite position, anchor or
+     * loop bounds, or a rate that is not a finite number > 0) is DROPPED whole and `false` is returned: the transport keeps its last
+     * good state until the next good one arrives. It never throws — this runs inside `tick()`.
+     */
     applyAnchoredState(s) {
+        if (!isValidAnchoredState(s))
+            return false;
         this._playing = s.playState === 'playing';
         if (s.rate != null)
             this._rate = s.rate;
@@ -171,9 +203,14 @@ export class Transport {
             this._loop = s.loop ? { ...s.loop } : null;
         this._cancelArmed();
         this._reopenEvents(); // anchored apply repositions the timeline -> events re-evaluate
+        return true;
     }
     /** Arm an anchored state (with optional control) to apply when audio time reaches `atAudioSec`. */
+    /** Returns `false` (and arms nothing) for a non-finite `atAudioSec` or a malformed state. */
     scheduleStateChange(atAudioSec, state, meta = {}) {
+        // checked at intake too: a NaN time would never drain and would block every later change
+        if (!Number.isFinite(atAudioSec) || !isValidAnchoredState(state))
+            return false;
         this._pending.push({
             atAudioSec,
             state,
@@ -182,6 +219,7 @@ export class Transport {
             onApply: meta.onApply ?? null,
         });
         this._pending.sort((a, b) => a.atAudioSec - b.atAudioSec);
+        return true;
     }
     /** Drop pending changes older than a freshly-applied (term,seq) — supersession (Codex fix #4). */
     dropPendingOlderThan(term, seq) {
@@ -191,9 +229,10 @@ export class Transport {
         const now = this.backend.nowSec();
         while (this._pending.length && this._pending[0].atAudioSec <= now + EPS) {
             const p = this._pending.shift();
-            this.applyAnchoredState({ ...p.state, anchorAudioSec: p.state.anchorAudioSec ?? now });
-            if (p.onApply)
-                p.onApply(); // control rides WITH the state, applied atomically here (fix #5)
+            const applied = this.applyAnchoredState({ ...p.state, anchorAudioSec: p.state.anchorAudioSec ?? now });
+            // control rides WITH the state, applied atomically here (fix #5) — a dropped state drops its control too
+            if (applied && p.onApply)
+                p.onApply();
         }
     }
     // ---- the pump -----------------------------------------------------------------------
@@ -248,8 +287,8 @@ export class Transport {
             return;
         const { startSec, endSec } = this._loop;
         const len = endSec - startSec;
-        if (len <= 0)
-            return;
+        if (!(len > 0))
+            return; // also catches NaN
         const pos = this.positionSec();
         if (pos < endSec - EPS)
             return;

package/dist/clock/musical.js

@@ -14,20 +14,25 @@ export class MusicalProjection {
     _sig;
     constructor(spec = {}) {
         this.ppq = spec.ppq ?? DEFAULT_PPQ;
-        const tempo = (spec.tempoMap && spec.tempoMap.length ? spec.tempoMap : [{ startSec: 0, bpm: 120 }])
-            .slice()
-            .sort((a, b) => a.startSec - b.startSec);
+        // An entry with bpm <= 0, a NaN bpm or a non-finite start would make beat <-> seconds return
+        // Infinity/NaN — skip it. If nothing usable is left, fall back to the same 120 BPM default as an
+        // empty map.
+        const usable = (spec.tempoMap ?? []).filter((e) => Number.isFinite(e.startSec) && Number.isFinite(e.bpm) && e.bpm > 0);
+        const tempo = (usable.length ? usable : [{ startSec: 0, bpm: 120 }]).sort((a, b) => a.startSec - b.startSec);
         // precompute the cumulative beat position at each tempo segment boundary
         this._tempo = tempo.map((s) => ({ ...s, startBeat: 0 }));
         for (let i = 1; i < this._tempo.length; i++) {
             const prev = this._tempo[i - 1];
             this._tempo[i].startBeat = prev.startBeat + (this._tempo[i].startSec - prev.startSec) * (prev.bpm / 60);
         }
-        const sig = (spec.signatureMap && spec.signatureMap.length
-            ? spec.signatureMap
-            : [{ startBar: 0, numerator: 4, denominator: 4 }])
-            .slice()
-            .sort((a, b) => a.startBar - b.startBar);
+        // Same rule for signatures: a zero/negative/NaN numerator or denominator, or a non-finite start
+        // bar, would give Infinity/NaN bars — skip it, and fall back to 4/4 if nothing usable is left.
+        const usableSig = (spec.signatureMap ?? []).filter((e) => Number.isFinite(e.startBar) &&
+            Number.isFinite(e.numerator) &&
+            e.numerator > 0 &&
+            Number.isFinite(e.denominator) &&
+            e.denominator > 0);
+        const sig = (usableSig.length ? usableSig : [{ startBar: 0, numerator: 4, denominator: 4 }]).sort((a, b) => a.startBar - b.startBar);
         // precompute the cumulative beat position at each signature segment's startBar
         this._sig = sig.map((s) => ({ ...s, beatsPerBar: (s.numerator * 4) / s.denominator, startBeat: 0 }));
         for (let i = 1; i < this._sig.length; i++) {

package/dist/clock/sync.js

@@ -12,6 +12,13 @@
 // Reuses the session-time substrate offset estimation; the server `sessionEpoch` gives every peer a
 // shared `sessionMs`; the beat timeline is anchored to that.
 const mod = (n, m) => ((n % m) + m) % m;
+/** A usable timeline: a finite tempo above zero and finite anchors. Anything else makes every beat
+ *  <-> time conversion NaN or Infinity, for this peer and for every peer that adopts it. */
+const isValidTimeline = (t) => !!t &&
+    Number.isFinite(t.tempoBpm) &&
+    t.tempoBpm > 0 &&
+    Number.isFinite(t.anchorBeat) &&
+    Number.isFinite(t.anchorSessionMs);
 const newerTs = (a, b) => a.time > b.time || (a.time === b.time && a.id > b.id);
 /** Cristian/SNTP offset estimate: median of (serverStamp + rtt/2 - t1). Asymmetry biases by (up-down)/2. */
 export function estimateOffset(node, relay, { samples = 7, upMs = relay.upMs, downMs = relay.downMs, jitterFn = () => 0 } = {}) {
@@ -132,6 +139,9 @@ export class BeatTimeline {
     }
     // ---- timeline mutations (all leaderless: broadcast + last-writer-wins) ---------------
     _commit(timeline) {
+        // Validated before it is broadcast: last-writer-wins would hand a broken timeline to every peer.
+        if (!isValidTimeline(timeline))
+            throw new Error('beat timeline needs a finite tempo > 0 and finite anchors');
         this.timeline = { ...timeline };
         this._ts = { time: this.sessionNowMs(), id: this.id };
         if (this.enabled)
@@ -177,7 +187,9 @@ export class BeatTimeline {
     // ---- start/stop intent (opt-in; never adopted on join) ------------------------------
     setLocalPlaying(playing) {
         this.localPlaying = playing;
-        this.relay.send(this.id, { kind: 'beat:transport', id: this.id, playing, atSessionMs: this.sessionNowMs() });
+        // Solo (`enabled` false) broadcasts nothing, as with the timeline and hello messages.
+        if (this.enabled)
+            this.relay.send(this.id, { kind: 'beat:transport', id: this.id, playing, atSessionMs: this.sessionNowMs() });
         if (this.onChange)
             this.onChange();
     }
@@ -196,7 +208,8 @@ export class BeatTimeline {
             case 'beat:timeline':
                 if (msg.id)
                     this.peers.add(msg.id);
-                if (newerTs(msg.ts, this._ts)) {
+                // A malformed timeline (tempo 0, NaN anchor, from a buggy or older peer) is never adopted.
+                if (isValidTimeline(msg.timeline) && msg.ts && newerTs(msg.ts, this._ts)) {
                     this.timeline = { ...msg.timeline };
                     this._ts = msg.ts;
                 }

package/dist/loaders/glbLoader.js

@@ -2,6 +2,7 @@ import * as THREE from 'three';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import { ensureStandardMaterial, applyFlagsToMaterial } from '../utils/materials.js';
 import { getKTX2LoaderForRenderer } from './ktx2.js';
+import { disposeObject3D } from '../utils/dispose.js';
 /**
  * `renderer` is REQUIRED at runtime (throws without one).
  * - `retries` (3): load attempts before giving up.
@@ -20,16 +21,28 @@ export async function loadGLB(url, { retries = 3, signal, onProgress, applyFlags
         throw new Error('[glb] loadGLB requires the owning renderer (KTX2 textures bind per WebGL context).');
     let attempt = 0;
     while (attempt < retries) {
+        // An abort during the pause between attempts must stop here: a listener added to an
+        // already-aborted signal never fires, so the next attempt would load and resolve anyway.
+        if (signal?.aborted)
+            throw new Error('aborted');
         try {
             const loader = new GLTFLoader()
                 .setCrossOrigin(withCredentials ? 'use-credentials' : 'anonymous')
                 .setWithCredentials(Boolean(withCredentials))
                 .setKTX2Loader(getKTX2LoaderForRenderer(renderer));
             const root = await new Promise((resolve, reject) => {
-                loader.load(url, (gltf) => resolve(gltf.scene), onProgress, reject);
-                if (signal) {
-                    signal.addEventListener('abort', () => reject(new Error('aborted')));
-                }
+                const onAbort = () => reject(new Error('aborted'));
+                signal?.addEventListener('abort', onAbort, { once: true });
+                loader.load(url, (gltf) => {
+                    signal?.removeEventListener('abort', onAbort);
+                    // Aborted while loading: the promise has already rejected and nobody will own this
+                    // scene, so free its geometry, materials and textures now instead of leaking them.
+                    if (signal?.aborted) {
+                        disposeObject3D(gltf.scene);
+                        return;
+                    }
+                    resolve(gltf.scene);
+                }, onProgress, (err) => { signal?.removeEventListener('abort', onAbort); reject(err); });
             });
             // Post-process materials
             root.traverse((object) => {

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/entangledWorlds.d.ts

@@ -0,0 +1,21 @@
+import type { ShortcutAction } from './match.js';
+export declare const EW_STUDIO_SECTION = "ew-studio";
+export declare const EW_PLAYER_SECTION = "ew-player";
+/** The studio's actions all act on what is open in it; the player has no other scope. */
+export type EntangledWorldsShortcut = ShortcutAction<'studio' | 'player'>;
+/** How the studio's command menu groups its actions, in its order. */
+export declare const EW_STUDIO_COMMAND_GROUPS: readonly [{
+    readonly id: "edit";
+    readonly label: "Edit";
+}, {
+    readonly id: "playback";
+    readonly label: "Playback";
+}, {
+    readonly id: "steps";
+    readonly label: "Steps";
+}, {
+    readonly id: "help";
+    readonly label: "Help";
+}];
+export declare const EW_STUDIO_SHORTCUTS: readonly EntangledWorldsShortcut[];
+export declare const EW_PLAYER_SHORTCUTS: readonly EntangledWorldsShortcut[];

package/dist/shortcuts/entangledWorlds.js

@@ -0,0 +1,40 @@
+// The Entangled Worlds catalogues: the studio (where a world's clip is made) and the full-window
+// player. Escape and Enter inside dialogs stay with the dialogs and are not listed here.
+export const EW_STUDIO_SECTION = 'ew-studio';
+export const EW_PLAYER_SECTION = 'ew-player';
+const studio = (id, label, defaultKeys, group, command) => Object.freeze({
+    id: `ew.studio.${id}`, section: EW_STUDIO_SECTION, label, defaultKeys: Object.freeze([...defaultKeys]), scope: 'studio',
+    group, ...(command === false ? { command } : {}),
+});
+/** How the studio's command menu groups its actions, in its order. */
+export const EW_STUDIO_COMMAND_GROUPS = Object.freeze([
+    { id: 'edit', label: 'Edit' },
+    { id: 'playback', label: 'Playback' },
+    { id: 'steps', label: 'Steps' },
+    { id: 'help', label: 'Help' },
+]);
+export const EW_STUDIO_SHORTCUTS = Object.freeze([
+    studio('undo', 'Undo', ['Mod+KeyZ'], 'edit'),
+    studio('redo', 'Redo', ['Mod+Shift+KeyZ'], 'edit'),
+    studio('duplicate', 'Duplicate the selection', ['Mod+KeyD'], 'edit'),
+    studio('copy', 'Copy the selection', ['Mod+KeyC'], 'edit'),
+    studio('paste', 'Paste', ['Mod+KeyV'], 'edit'),
+    studio('playPause', 'Play or pause', ['Shift?+Space'], 'playback'),
+    studio('remove', 'Remove the selection', ['Shift?+Delete', 'Shift?+Backspace'], 'edit'),
+    studio('step.audio', 'Audio step', ['Digit1', 'Numpad1'], 'steps'),
+    studio('step.animations', 'Animations step', ['Digit2', 'Numpad2'], 'steps'),
+    studio('step.third', 'Export step (Release where there is no export)', ['Digit3', 'Numpad3'], 'steps'),
+    studio('step.release', 'Release step', ['Digit4', 'Numpad4'], 'steps'),
+    studio('help', 'Keyboard shortcuts', ['Shift?+Slash'], 'help'),
+    // Opens the menu itself, so the menu does not list it.
+    studio('commands', 'Commands', ['Mod+KeyK'], 'help', false),
+]);
+export const EW_PLAYER_SHORTCUTS = Object.freeze([
+    Object.freeze({
+        id: 'ew.player.playPause',
+        section: EW_PLAYER_SECTION,
+        label: 'Play or pause',
+        defaultKeys: Object.freeze(['Shift?+Alt?+Ctrl?+Meta?+Space']),
+        scope: 'player',
+    }),
+]);

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;