entangled-worlds-orbiters-shared 3.3.0 → 4.1.0

package/dist/world/worldTexture.js

@@ -0,0 +1,299 @@
+import * as THREE from 'three';
+import { loadTexture } from '../loaders/bodyTextureLoader.js';
+import { applyFlagsToMaterial } from '../utils/materials.js';
+import { getLightFresnel } from '../core/lightFresnel.js';
+import { createCloudShell } from './cloudShell.js';
+import { resolvePublicUrl } from '../config/env.js';
+// Debug tag so you can verify the loaded file version in console
+export const WORLD_TEXTURE_DEBUG_TAG = 'WT:vFlipGeom-r3@2025-10-28T17:22:00Z';
+// Enable debug if query/localStorage says so; expose tag
+if (typeof window !== 'undefined') {
+    const q = (window.location && window.location.search) || '';
+    const qsDebug = /(?:[?&])debugTextures=1(?:&|$)/.test(q);
+    const lsDebug = (window.localStorage && window.localStorage.DEBUG_TEXTURE_FLIP === '1') || false;
+    if (!window.DEBUG_TEXTURE_FLIP && (qsDebug || lsDebug)) {
+        window.DEBUG_TEXTURE_FLIP = true;
+    }
+    window.EW_WT_DEBUG_TAG = WORLD_TEXTURE_DEBUG_TAG;
+    if (window.DEBUG_TEXTURE_FLIP) {
+        console.info('[worldTexture] loaded', WORLD_TEXTURE_DEBUG_TAG);
+    }
+}
+const WT_LOGGED_FIRST_CALL = false;
+export const EARTH_RADIUS_UNITS = 0.5; // scene units
+/**
+ * Simplified detection: width = height -> rectangular, width = 2×height -> equirectangular
+ */
+function isLikelyEquirectangular(img) {
+    const aspectRatio = img.width / img.height;
+    // Check for 2:1 aspect ratio (equirectangular)
+    const is2to1 = Math.abs(aspectRatio - 2.0) < 0.1;
+    // Check for 1:1 aspect ratio (square -> treat as rectangular)
+    const is1to1 = Math.abs(aspectRatio - 1.0) < 0.1;
+    if (is1to1) {
+        return false; // Square images are rectangular
+    }
+    if (is2to1) {
+        return true; // 2:1 images are equirectangular
+    }
+    // For other aspect ratios, default to rectangular
+    return false;
+}
+/**
+ * The textured world sphere. Every option is optional. The offset, repeat, rotation, flip and sphere
+ * geometry options are read only when they have their type; the rest are used as given (`glow`,
+ * `cloudsEnabled` and `mirrorX` by truthiness).
+ *
+ * - `renderer`: REQUIRED for a KTX2 texture. `flags`: material flags (`forceOpaque`, `wireframe`).
+ * - `uOffset`: horizontal texture offset, 0..1 (wins over `textureOffsetDeg`, in degrees).
+ * - `mirrorDuplicateX`: explicit override of the equirectangular detection
+ *   (`autoDetectEquirectangular` true, `forceEquirectangular` / `forceRectangular` false).
+ * - `wrapS` ('repeat') / `wrapT` ('clamp'): `'clamp'`, `'repeat'` or `'mirror'`.
+ * - `center` ([0.5, 0.5]): texture rotation centre, `[u, v]`.
+ * - `materialRoughness` / `materialMetalness`: accepted from saved worlds; no longer change the look.
+ * - Defaults: `glow` true, `glowRimHex` 0x66ccff, `glowFacingHex` 0x000000, `glowScale` 1.18,
+ *   `glowBias` 0.02, `glowFresnelScale` 1, `glowPower` 3.5, `cloudsEnabled` false, `cloudsColor`
+ *   0xffffff, `cloudsOpacity` 0.6, `cloudsSpeed` 0.015.
+ */
+export async function makeSphere({ textureUrl, renderer, flags, uOffset, textureOffsetDeg, mirrorX, mirrorDuplicateX, // optional, still supported for explicit override
+autoDetectEquirectangular = true, forceEquirectangular = false, forceRectangular = false, 
+// Wrapping params
+wrapS = 'repeat', wrapT = 'clamp', repeatX, repeatY, rotationDeg, center = [0.5, 0.5], flipY, 
+// NEW: sphere geometry controls (optional)
+sphereRadius, sphereWidthSegments, sphereHeightSegments, 
+// PBR material tuning (optional)
+materialRoughness, materialMetalness, 
+// NEW: glow controls
+glow = true, glowRimHex = 0x66ccff, glowFacingHex = 0x000000, glowScale = 1.18, glowBias = 0.02, glowFresnelScale = 1.0, glowPower = 3.5, 
+// texture clouds controls (simplified)
+cloudsEnabled = false, cloudsTextureUrl = '/assets/texture/2k_earth_clouds.jpg', cloudsColor = 0xffffff, cloudsOpacity = 0.6, cloudsSpeed = 0.015, } = {}) {
+    const radius = typeof sphereRadius === 'number' ? Math.max(0.0001, sphereRadius) : EARTH_RADIUS_UNITS;
+    // `Number.isFinite` does not narrow: past it, each count is a number.
+    const widthSegs = Number.isFinite(sphereWidthSegments) ? Math.max(3, Math.floor(sphereWidthSegments)) : 64;
+    const heightSegs = Number.isFinite(sphereHeightSegments) ? Math.max(2, Math.floor(sphereHeightSegments)) : 64;
+    const geometry = new THREE.SphereGeometry(radius, widthSegs, heightSegs);
+    let meshGeometry = geometry; // may clone/flip UVs for compressed textures
+    // Diffuse-only (Lambert) at every tier: under the star's key light the physical (Standard) material
+    // cost +20% GPU on low for a barely visible sheen. `materialRoughness` /
+    // `materialMetalness` stay accepted from saved worlds but no longer change the look.
+    const material = new THREE.MeshLambertMaterial({ color: 0xffffff });
+    const WRAP = {
+        clamp: THREE.ClampToEdgeWrapping,
+        repeat: THREE.RepeatWrapping,
+        mirror: THREE.MirroredRepeatWrapping,
+    };
+    // For compressed textures (e.g., KTX2) WebGL cannot apply UNPACK_FLIP_Y at upload.
+    // To normalize orientation across loaders, emulate vertical flip in UV sampling:
+    // v' = 1 - v  => repeat.y = -repeat.y, offset.y = 1 - offset.y
+    const normalizeCompressedFlip = (t) => {
+        if (!t || !t.isCompressedTexture)
+            return;
+        const wantFlip = (typeof flipY === 'boolean') ? flipY : true; // match uncompressed default
+        if (!wantFlip)
+            return;
+        const rY = (t.repeat && typeof t.repeat.y === 'number') ? t.repeat.y : 1;
+        const oY = (t.offset && typeof t.offset.y === 'number') ? t.offset.y : 0;
+        t.repeat.y = -rY;
+        t.offset.y = 1 - oY;
+        t.needsUpdate = true;
+    };
+    // Emulate vertical flip for compressed textures (e.g., KTX2) using UV transform
+    const normalizeCompressedFlipY = (t, desired) => {
+        if (!t || !t.isCompressedTexture)
+            return;
+        const wantFlip = (typeof desired === 'boolean') ? desired : true; // default to match uncompressed loader
+        const rY = t.repeat?.y ?? 1;
+        const oY = t.offset?.y ?? 0;
+        if (wantFlip) {
+            t.repeat.y = -Math.abs(rY);
+            t.offset.y = 1 - oY;
+        }
+        else {
+            t.repeat.y = Math.abs(rY);
+            t.offset.y = 0;
+        }
+        t.needsUpdate = true;
+    };
+    // Flip UV.y on a cloned geometry (keeps other layers safe)
+    const flipGeometryUVY = (geom) => {
+        if (!geom || !geom.attributes || !geom.attributes.uv)
+            return 0;
+        const uv = geom.attributes.uv;
+        const arr = uv.array;
+        for (let i = 1; i < arr.length; i += 2) {
+            arr[i] = 1 - arr[i]; // v = 1 - v
+        }
+        uv.needsUpdate = true;
+        return uv.count;
+    };
+    // Attach a Fresnel glow mesh as a child of the sphere mesh
+    function createGlow(rimHex, facingHex) {
+        const fresnelMat = getLightFresnel({ rimHex, facingHex });
+        // tweak uniforms for stronger rim
+        fresnelMat.uniforms.fresnelBias.value = glowBias;
+        fresnelMat.uniforms.fresnelScale.value = glowFresnelScale;
+        fresnelMat.uniforms.fresnelPower.value = glowPower;
+        const glowGeom = geometry.clone();
+        const fresnelMesh = new THREE.Mesh(glowGeom, fresnelMat);
+        // Slightly larger to avoid z-fighting and create a halo
+        const s = Math.max(glowScale, 1.0);
+        fresnelMesh.scale.set(s, s, s);
+        fresnelMesh.renderOrder = 999; // render after base mesh
+        fresnelMesh.name = 'worldTextureGlow';
+        return fresnelMesh;
+    }
+    const chosenTexture = textureUrl; // require explicit textureUrl — no implicit default
+    if (chosenTexture) {
+        try {
+            const tex = await loadTexture(chosenTexture, { renderer });
+            tex.colorSpace = THREE.SRGBColorSpace;
+            tex.anisotropy = 8;
+            if (typeof flipY === 'boolean')
+                tex.flipY = flipY;
+            // Only enable mipmaps for non-compressed, power-of-two textures
+            // A KTX2 load is a CompressedTexture, which says so; a plain Texture has no such field.
+            const isCompressed = tex.isCompressedTexture;
+            const img = tex.image;
+            const isPowerOfTwo = img && ((img.width & (img.width - 1)) === 0) && ((img.height & (img.height - 1)) === 0);
+            tex.generateMipmaps = !isCompressed && isPowerOfTwo;
+            // Decide mapping approach
+            let shouldMirrorDuplicate = mirrorDuplicateX;
+            if (tex.image) {
+                const img = tex.image;
+                let isEquirectangular = false;
+                if (forceEquirectangular) {
+                    isEquirectangular = true;
+                }
+                else if (forceRectangular) {
+                    isEquirectangular = false;
+                }
+                else if (autoDetectEquirectangular && typeof mirrorDuplicateX === 'undefined') {
+                    const aspectDetection = isLikelyEquirectangular(img);
+                    isEquirectangular = aspectDetection && Math.abs(img.width / img.height - 2.0) < 0.05;
+                }
+                else {
+                    isEquirectangular = !shouldMirrorDuplicate;
+                }
+                shouldMirrorDuplicate = !isEquirectangular;
+            }
+            // Default to rectangular duplicate if still undefined
+            if (typeof shouldMirrorDuplicate === 'undefined') {
+                shouldMirrorDuplicate = true;
+            }
+            // Seam alignment (offset only)
+            let offsetX = 0;
+            if (typeof uOffset === 'number') {
+                offsetX = ((uOffset % 1) + 1) % 1;
+            }
+            else if (typeof textureOffsetDeg === 'number') {
+                offsetX = (((textureOffsetDeg / 360) % 1) + 1) % 1;
+            }
+            const applyWrapOptions = (t) => {
+                t.wrapS = WRAP[wrapS] ?? THREE.RepeatWrapping;
+                t.wrapT = WRAP[wrapT] ?? THREE.ClampToEdgeWrapping;
+                // Compressed textures + NPOT prefer clamp to avoid artifacts
+                if (isCompressed) {
+                    t.wrapS = THREE.ClampToEdgeWrapping;
+                    t.wrapT = THREE.ClampToEdgeWrapping;
+                }
+                if (Array.isArray(center) && center.length === 2)
+                    t.center.set(center[0], center[1]);
+                if (typeof rotationDeg === 'number')
+                    t.rotation = (rotationDeg * Math.PI) / 180;
+                if (typeof repeatX === 'number' || typeof repeatY === 'number') {
+                    t.repeat.set(typeof repeatX === 'number' ? repeatX : t.repeat.x, typeof repeatY === 'number' ? repeatY : t.repeat.y);
+                }
+                t.offset.x = offsetX;
+                if (mirrorX) {
+                    t.repeat.x = -Math.abs(t.repeat.x || 1);
+                    t.offset.x = (t.offset.x + 1) % 1;
+                }
+                t.needsUpdate = true;
+            };
+            if (shouldMirrorDuplicate && tex.image && typeof document !== 'undefined') {
+                // Create a mirrored duplicate without any blending
+                const img = tex.image;
+                try {
+                    const canvas = document.createElement('canvas');
+                    canvas.width = img.width * 2;
+                    canvas.height = img.height;
+                    // A missing 2D context throws on first use and lands in the fallback below, as before.
+                    const ctx = canvas.getContext('2d');
+                    // Left half: original
+                    ctx.drawImage(img, 0, 0, img.width, img.height);
+                    // Right half: horizontally flipped copy
+                    ctx.save();
+                    ctx.translate(img.width, 0);
+                    ctx.scale(-1, 1);
+                    ctx.drawImage(img, -img.width, 0, img.width, img.height);
+                    ctx.restore();
+                    const processedTex = new THREE.CanvasTexture(canvas);
+                    processedTex.colorSpace = THREE.SRGBColorSpace;
+                    processedTex.generateMipmaps = true;
+                    processedTex.anisotropy = 8;
+                    applyWrapOptions(processedTex);
+                    material.map = processedTex;
+                    material.needsUpdate = true;
+                }
+                catch (e) {
+                    // Fallback: use mirrored repeat directly
+                    tex.wrapS = THREE.MirroredRepeatWrapping;
+                    tex.wrapT = WRAP[wrapT] ?? THREE.ClampToEdgeWrapping;
+                    tex.repeat.x = Math.max(2, typeof repeatX === 'number' ? repeatX : 2);
+                    applyWrapOptions(tex);
+                    // If compressed (e.g., KTX2), normalize vertical orientation using sampling transform
+                    normalizeCompressedFlip(tex);
+                    material.map = tex;
+                    material.needsUpdate = true;
+                }
+            }
+            else {
+                // Equirectangular or no canvas: just use original texture
+                applyWrapOptions(tex);
+                const wantFlip = (typeof flipY === 'boolean') ? flipY : true;
+                if (isCompressed && wantFlip) {
+                    meshGeometry = geometry.clone();
+                    flipGeometryUVY(meshGeometry);
+                }
+                else if (isCompressed) {
+                    tex.repeat.y = Math.abs(tex.repeat?.y ?? 1);
+                    tex.offset.y = 0;
+                    tex.needsUpdate = true;
+                }
+                material.map = tex;
+                material.needsUpdate = true;
+            }
+        }
+        catch (e) {
+            console.warn('[worldTexture] Failed to load texture:', e);
+        }
+    }
+    if (flags)
+        applyFlagsToMaterial(material, flags);
+    const mesh = new THREE.Mesh(meshGeometry, material);
+    // Named so consumers can find the planet body by name (mirrors the
+    // normal-mode body's `worldNormalSphere`) — e.g. to modulate its material.
+    mesh.name = 'worldTextureSphere';
+    mesh.position.set(0, 0, 0);
+    // NEW: add cloud shell before glow
+    if (cloudsEnabled) {
+        const cloudMesh = await createCloudShell({
+            baseGeometry: geometry,
+            baseRadius: radius,
+            widthSegments: widthSegs,
+            heightSegments: heightSegs,
+            textureUrl: resolvePublicUrl(cloudsTextureUrl),
+            color: cloudsColor,
+            opacity: cloudsOpacity,
+            speed: cloudsSpeed,
+            renderer,
+        });
+        mesh.add(cloudMesh);
+    }
+    // Optionally add glow as a child of the mesh so it follows transforms
+    if (glow) {
+        const glowMesh = createGlow(glowRimHex, glowFacingHex);
+        mesh.add(glowMesh);
+    }
+    return mesh;
+}

package/package.json

@@ -1,43 +1,43 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "3.3.0",
+  "version": "4.1.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
-  "main": "src/index.js",
-  "types": "./dist/types/index.d.ts",
+  "main": "dist/index.js",
+  "types": "./dist/index.d.ts",
   "sideEffects": false,
   "exports": {
     ".": {
-      "types": "./dist/types/index.d.ts",
-      "default": "./src/index.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./world": {
-      "types": "./dist/types/world/index.d.ts",
-      "default": "./src/world/index.js"
+      "types": "./dist/world/index.d.ts",
+      "default": "./dist/world/index.js"
     },
     "./moons": {
-      "types": "./dist/types/moons/index.d.ts",
-      "default": "./src/moons/index.js"
+      "types": "./dist/moons/index.d.ts",
+      "default": "./dist/moons/index.js"
     },
     "./loaders": {
-      "types": "./dist/types/loaders/index.d.ts",
-      "default": "./src/loaders/index.js"
+      "types": "./dist/loaders/index.d.ts",
+      "default": "./dist/loaders/index.js"
     },
     "./render": {
-      "types": "./dist/types/render/index.d.ts",
-      "default": "./src/render/index.js"
+      "types": "./dist/render/index.d.ts",
+      "default": "./dist/render/index.js"
     },
     "./core": {
-      "types": "./dist/types/core/index.d.ts",
-      "default": "./src/core/index.js"
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
     },
     "./config": {
-      "types": "./dist/types/config/index.d.ts",
-      "default": "./src/config/index.js"
+      "types": "./dist/config/index.d.ts",
+      "default": "./dist/config/index.js"
     },
     "./utils": {
-      "types": "./dist/types/utils/index.d.ts",
-      "default": "./src/utils/index.js"
+      "types": "./dist/utils/index.d.ts",
+      "default": "./dist/utils/index.js"
     },
     "./clock": {
       "types": "./dist/clock/index.d.ts",
@@ -91,7 +91,6 @@
   "files": [
     "src/**/*",
     "!src/**/*.test.ts",
-    "!src/**/*.test.js",
     "!src/**/fixtures/**",
     "dist/**/*",
     "public/**/*",
@@ -111,21 +110,19 @@
   "author": "Plantasia Space",
   "license": "MIT",
   "peerDependencies": {
-    "three": "^0.166.1",
-    "three-stdlib": "^2.34.0"
+    "three": "^0.166.1"
   },
   "peerDependenciesMeta": {
     "three": {
       "optional": true
-    },
-    "three-stdlib": {
-      "optional": true
     }
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^20.19.0",
     "@types/three": "^0.166.0",
+    "@typescript-eslint/eslint-plugin": "^8.72.1",
+    "@typescript-eslint/parser": "^8.72.1",
     "eslint": "^10.0.0",
     "globals": "^17.3.0",
     "three": "^0.166.1",
@@ -144,21 +141,14 @@
   "scripts": {
     "lint": "eslint .",
     "lint:strict": "eslint . --max-warnings=0",
-    "lint:fallback": "node scripts/lint.js",
-    "build:ts": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
-    "build:clock": "npm run build:ts",
-    "prepare": "npm run build:ts",
+    "build": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+    "build:ts": "npm run build",
+    "prepare": "npm run build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test:clock": "node --test --import tsx src/clock/*.test.ts",
-    "test:notes": "node --test --import tsx src/notes/*.test.ts",
-    "test:faust": "node --test --import tsx src/faust/*.test.ts",
-    "test:studio": "node --test --import tsx src/studio/*.test.js",
-    "test:uploads": "node --test --import tsx src/uploads/*.test.js",
-    "test:audio": "node --test --import tsx src/audio/*.test.ts",
-    "test:render": "node --test src/render/*.test.js",
-    "test": "npm run test:clock && npm run test:notes && npm run test:faust && npm run test:studio && npm run test:uploads && npm run test:audio && npm run test:render && npm run test:moons && npm run test:star",
-    "test:moons": "node --test src/moons/*.test.js",
-    "test:star": "node --test --import tsx src/star/*.test.ts",
+    "test": "node --test --import tsx $(find src -name '*.test.ts' | sort)",
+    "baseline:update": "tsx scripts/api-baseline.ts update",
+    "baseline:release": "tsx scripts/api-baseline.ts release",
+    "check:exports": "tsx scripts/check-exports.ts",
     "bench:star:build": "esbuild bench/star/main.ts --bundle --format=esm --target=es2022 --outfile=bench/star/build/main.js --log-level=warning",
     "bench:star": "npm run bench:star:build && tsx bench/star/run.ts"
   }

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;
         }