entangled-worlds-orbiters-shared 3.3.0 → 4.1.0

package/README.md

@@ -21,6 +21,7 @@ In `entangled-worlds-orbiters-shared/`:
 
 ```bash
 npm install
+npm run build   # consumers run dist/: build again after every change
 npm link
 ```
 
@@ -145,10 +146,10 @@ Effects:
 
 ## Peer Dependencies
 
-This library requires Three.js and three-stdlib as peer dependencies:
+This library requires Three.js as a peer dependency:
 
 ```bash
-npm install three three-stdlib
+npm install three
 ```
 
 ## License

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

@@ -0,0 +1,8 @@
+export declare let __PUBLIC_BASE: string | null;
+export declare function setPublicBase(url: string | null | undefined): void;
+export declare function getPublicBase(): string;
+/**
+ * @param path root-relative, relative, or an absolute http(s) URL (returned unchanged).
+ *   An empty string comes back as is.
+ */
+export declare function resolvePublicUrl(path: string): string;

package/dist/config/env.js

@@ -0,0 +1,36 @@
+// Runtime public base URL helper for building absolute asset URLs at runtime
+// Mutable module-scoped variable to allow apps to override at startup
+export let __PUBLIC_BASE = null;
+// Set the public base (strips trailing slash) and mirror to window for convenience
+export function setPublicBase(url) {
+    __PUBLIC_BASE = (url || '').replace(/\/$/, '');
+    if (typeof window !== 'undefined')
+        window.VITE_PUBLIC_HERBARIUM_BASE = __PUBLIC_BASE;
+}
+// Get the current public base from (in order): explicit set value, envs, or default
+export function getPublicBase() {
+    // The cast stays inline on each read so the emitted JS is the literal `import.meta.env.X` a
+    // bundler looks for.
+    const envVal = (typeof import.meta !== 'undefined' &&
+        import.meta.env &&
+        import.meta.env.VITE_PUBLIC_HERBARIUM_BASE) ||
+        (typeof window !== 'undefined' && window.VITE_PUBLIC_HERBARIUM_BASE) ||
+        null;
+    const base = (__PUBLIC_BASE || envVal || '').toString();
+    return base ? base.replace(/\/$/, '') : '';
+}
+// Resolve a possibly-relative path against the current public base
+/**
+ * @param path root-relative, relative, or an absolute http(s) URL (returned unchanged).
+ *   An empty string comes back as is.
+ */
+export function resolvePublicUrl(path) {
+    if (!path)
+        return path;
+    if (/^https?:\/\//i.test(path))
+        return path;
+    const base = getPublicBase();
+    const p = path.startsWith('/') ? path : `/${path}`;
+    // If base is empty, return a root-relative path (same-origin)
+    return base ? `${base}${p}` : p;
+}

package/dist/config/index.d.ts

@@ -0,0 +1,3 @@
+export { loadTextureConfig, getTextureOptions, getTextureChoices, getDefaultTexture, getSkyboxOptions, getDefaultSkybox, getTextureFallbackUrl } from './textureConfig.js';
+export type { TextureConfig, TextureCategory, TextureItem, TextureChoice, TextureConfigMetadata } from './textureConfig.js';
+export { setPublicBase, getPublicBase, resolvePublicUrl } from './env.js';

package/dist/config/index.js

@@ -0,0 +1,4 @@
+// Configuration exports
+export { loadTextureConfig, getTextureOptions, getTextureChoices, getDefaultTexture, getSkyboxOptions, getDefaultSkybox, getTextureFallbackUrl } from './textureConfig.js';
+// runtime base helpers
+export { setPublicBase, getPublicBase, resolvePublicUrl } from './env.js';

package/dist/config/textureConfig.d.ts

@@ -0,0 +1,140 @@
+/** One catalogue item. */
+export interface TextureItem {
+    id: string;
+    filename?: string;
+    label?: string;
+    /** Picture of the item (a thumbnail), relative like `filename`. */
+    still?: string;
+    /** Texture to use when this one fails to load, relative like `filename`. */
+    fallback?: string;
+    tags?: string[];
+}
+/** One catalogue category (clouds, moons, skyboxes, …). */
+export interface TextureCategory {
+    category?: string;
+    basePath?: string;
+    defaultTexture?: string;
+    defaultSkybox?: string;
+    items?: TextureItem[];
+}
+/** The texture catalogue as loaded from the config URL. */
+export interface TextureConfig {
+    version?: string;
+    lastUpdated?: string;
+    baseUrl?: string;
+    /** By category name; a category the catalogue does not list is missing. */
+    textures: Partial<Record<string, TextureCategory>>;
+}
+/** What `getConfigMetadata` reports about a catalogue. */
+export interface TextureConfigMetadata {
+    version: string | undefined;
+    lastUpdated: string | undefined;
+    categories: string[];
+    totalTextures: number;
+}
+/**
+ * Load texture configuration from remote endpoint or use passed config
+ * @param {string} configUrl - Override config URL
+ * @param {boolean} useCache - Whether to use cached config if available
+ * @returns {Promise<TextureConfig>} Texture configuration object
+ */
+export declare function loadTextureConfig(configUrl?: string, useCache?: boolean): Promise<TextureConfig>;
+/**
+ * A choice record for one catalogue item.
+ *
+ * Every catalogue item IS a picture, so a chooser should show it rather than its name. `still` is
+ * read straight from the catalogue and never derived from `filename`: the stills do not share one
+ * extension, and a wrong guess fails silently (a broken `<img>` just shows nothing).
+ */
+export type TextureChoice = {
+    /** Catalogue id. */
+    id: string;
+    /** Human-readable name. */
+    label: string;
+    /** Resolved texture URL (the .ktx2 the world renders). */
+    url: string;
+    /**
+     * Resolved URL of the item's picture — a small thumbnail suitable for showing the texture in a
+     * picker. `null` when the catalogue names none.
+     */
+    still: string | null;
+};
+/**
+ * Get the full choice records for a category (clouds, moons, etc.) — label, texture URL, and the
+ * picture to show for it. The single resolution point for a category's items; `getTextureOptions`
+ * is the flat `{ label: url }` projection of this.
+ * @param {string} category - Texture category (clouds, moons)
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureChoice[]>} Choice records in catalogue order
+ */
+export declare function getTextureChoices(category: string, config?: TextureConfig | null): Promise<TextureChoice[]>;
+/**
+ * Get texture options for a specific category (clouds, moons, etc.)
+ * @param {string} category - Texture category (clouds, moons, skyboxes)
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<Record<string, string>>} `{ label: url }`, suitable for dropdown option lists
+ */
+export declare function getTextureOptions(category: string, config?: TextureConfig | null): Promise<Record<string, string>>;
+/**
+ * Get default texture for a category
+ * @param {string} category - Texture category
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<string|null>} Default texture path, or null when the category has no texture
+ */
+export declare function getDefaultTexture(category: string, config?: TextureConfig | null): Promise<string | null>;
+/**
+ * Return the configured fallback URL for a given texture if defined.
+ * @param {string} category - Texture category (clouds, moons, etc.)
+ * @param {string} textureUrl - Resolved texture URL
+ * @param {TextureConfig|null} config - Optional texture config override
+ * @returns {string|null} Resolved fallback texture URL or null
+ */
+export declare function getTextureFallbackUrl(category: string, textureUrl: string, config?: TextureConfig | null): string | null;
+/**
+ * Get texture by ID within a category
+ * @param {string} category - Texture category
+ * @param {string} textureId - Texture ID
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureItem|null>} Texture definition object
+ */
+export declare function getTextureById(category: string, textureId: string, config?: TextureConfig | null): Promise<TextureItem | null>;
+/**
+ * Get full URL for a texture
+ * @param {string} category - Texture category
+ * @param {string} textureId - Texture ID
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<string|null>} Full texture URL
+ */
+export declare function getTextureUrl(category: string, textureId: string, config?: TextureConfig | null): Promise<string | null>;
+/**
+ * Search textures by tags
+ * @param {string} category - Texture category
+ * @param {string[]} tags - Tags to search for
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureItem[]>} Array of matching texture definitions
+ */
+export declare function searchTexturesByTags(category: string, tags: string[], config?: TextureConfig | null): Promise<TextureItem[]>;
+/**
+ * Get skybox options formatted for GUI dropdowns
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<Record<string, string>>} `{ label: id }`
+ */
+export declare function getSkyboxOptions(config?: TextureConfig | null): Promise<Record<string, string>>;
+/**
+ * Get default skybox ID
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<string>} Default skybox ID
+ */
+export declare function getDefaultSkybox(config?: TextureConfig | null): Promise<string>;
+/**
+ * Reload configuration (force refresh)
+ * @param {string} configUrl - Override config URL
+ * @returns {Promise<TextureConfig>} Fresh configuration object
+ */
+export declare function reloadTextureConfig(configUrl?: string): Promise<TextureConfig>;
+/**
+ * Get configuration metadata
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureConfigMetadata>} Configuration metadata
+ */
+export declare function getConfigMetadata(config?: TextureConfig | null): Promise<TextureConfigMetadata>;