entangled-worlds-orbiters-shared 4.0.0 → 4.2.0

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.0.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/clock/Transport.ts

@@ -77,6 +77,19 @@ export interface TransportOptions {
   lookaheadSec?: number;
 }
 
+function isValidRate(rate: number): boolean {
+  return Number.isFinite(rate) && rate > 0;
+}
+
+function isValidAnchoredState(s: AnchoredState): boolean {
+  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: ClockBackend;
   lookaheadSec: number;
@@ -132,12 +145,13 @@ export class Transport {
     this._cancelArmed(); // armed future audio must not sound during pause; re-armed on resume
   }
   seekSec(sec: number): void {
+    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: number): void {
-    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)
@@ -149,6 +163,7 @@ export class Transport {
     return this._playing;
   }
   setLoopSec(loop: LoopSec | null): void {
+    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
@@ -218,6 +233,10 @@ export class Transport {
         if (d < -EPS) 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
@@ -232,7 +251,13 @@ export class Transport {
   }
 
   // ---- sync apply (Inc 3) -------------------------------------------------------------
-  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 {
+    if (!isValidAnchoredState(s)) return false;
     this._playing = s.playState === 'playing';
     if (s.rate != null) this._rate = s.rate;
     this._anchorPos = s.positionSec;
@@ -240,9 +265,13 @@ export class Transport {
     if (s.loop !== undefined) 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`. */
-  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 {
+    // 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,
@@ -251,6 +280,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: number, seq: number): void {
@@ -260,8 +290,9 @@ 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();
     }
   }
 
@@ -312,7 +343,7 @@ export class Transport {
     if (!this._loop) 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;
     const overshoot = (pos - startSec) % len;

package/src/clock/musical.ts

@@ -58,9 +58,13 @@ export class MusicalProjection {
   constructor(spec: MusicalProjectionSpec = {}) {
     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++) {
@@ -68,11 +72,17 @@ export class MusicalProjection {
       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/src/clock/sync.ts

@@ -72,6 +72,14 @@ export interface EstimateOffsetOpts {
 }
 
 const mod = (n: number, m: number): number => ((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: BeatTimelineState | null | undefined): t is BeatTimelineState =>
+  !!t &&
+  Number.isFinite(t.tempoBpm) &&
+  t.tempoBpm > 0 &&
+  Number.isFinite(t.anchorBeat) &&
+  Number.isFinite(t.anchorSessionMs);
 const newerTs = (a: TimelineStamp, b: TimelineStamp): boolean =>
   a.time > b.time || (a.time === b.time && a.id > b.id);
 
@@ -225,6 +233,8 @@ export class BeatTimeline implements RelayNode {
 
   // ---- timeline mutations (all leaderless: broadcast + last-writer-wins) ---------------
   private _commit(timeline: BeatTimelineState): void {
+    // 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)
@@ -269,7 +279,9 @@ export class BeatTimeline implements RelayNode {
   // ---- start/stop intent (opt-in; never adopted on join) ------------------------------
   setLocalPlaying(playing: boolean): void {
     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();
   }
 
@@ -289,7 +301,8 @@ export class BeatTimeline implements RelayNode {
         break;
       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/src/loaders/glbLoader.ts

@@ -2,6 +2,7 @@ import * as THREE from 'three';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import { ensureStandardMaterial, applyFlagsToMaterial, type MaterialFlags } from '../utils/materials.js';
 import { getKTX2LoaderForRenderer } from './ktx2.js';
+import { disposeObject3D } from '../utils/dispose.js';
 
 /**
  * `renderer` is REQUIRED at runtime (throws without one).
@@ -43,6 +44,9 @@ export async function loadGLB(
 
   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')
@@ -50,15 +54,20 @@ export async function loadGLB(
         .setKTX2Loader(getKTX2LoaderForRenderer(renderer));
 
       const root = await new Promise<THREE.Group>((resolve, reject) => {
+        const onAbort = () => reject(new Error('aborted'));
+        signal?.addEventListener('abort', onAbort, { once: true });
         loader.load(
           url,
-            (gltf) => resolve(gltf.scene),
-            onProgress,
-            reject
+          (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); }
         );
-        if (signal) {
-          signal.addEventListener('abort', () => reject(new Error('aborted')));
-        }
       });
 
       // Post-process materials