entangled-worlds-orbiters-shared 1.2.0 → 1.3.0

package/dist/clock/sync.d.ts

@@ -20,15 +20,15 @@ export interface PeerIntent {
 }
 /** Messages exchanged over the relay seam. */
 export type SyncMessage = {
-    kind: 'link:hello';
+    kind: 'beat:hello';
     id: string;
 } | {
-    kind: 'link:timeline';
+    kind: 'beat:timeline';
     timeline: BeatTimelineState;
     ts: TimelineStamp;
     id: string;
 } | {
-    kind: 'link:transport';
+    kind: 'beat:transport';
     id: string;
     playing: boolean;
     atSessionMs: number;

package/dist/clock/sync.js

@@ -91,7 +91,7 @@ export class BeatTimeline {
     /** Broadcast presence (peers reply with their timeline). Safe to call periodically as a heartbeat. */
     announce() {
         if (this.enabled)
-            this.relay.send(this.id, { kind: 'link:hello', id: this.id });
+            this.relay.send(this.id, { kind: 'beat:hello', id: this.id });
     }
     /** Toggle participation. Off = solo (no broadcast, no adoption). On = re-announce + re-adopt. */
     setEnabled(on) {
@@ -135,7 +135,7 @@ export class BeatTimeline {
         this.timeline = { ...timeline };
         this._ts = { time: this.sessionNowMs(), id: this.id };
         if (this.enabled)
-            this.relay.send(this.id, { kind: 'link:timeline', timeline: this.timeline, ts: this._ts, id: this.id });
+            this.relay.send(this.id, { kind: 'beat:timeline', timeline: this.timeline, ts: this._ts, id: this.id });
         if (this.onChange)
             this.onChange();
     }
@@ -177,7 +177,7 @@ export class BeatTimeline {
     // ---- start/stop intent (opt-in; never adopted on join) ------------------------------
     setLocalPlaying(playing) {
         this.localPlaying = playing;
-        this.relay.send(this.id, { kind: 'link:transport', id: this.id, playing, atSessionMs: this.sessionNowMs() });
+        this.relay.send(this.id, { kind: 'beat:transport', id: this.id, playing, atSessionMs: this.sessionNowMs() });
         if (this.onChange)
             this.onChange();
     }
@@ -186,14 +186,14 @@ export class BeatTimeline {
         if (!this.enabled)
             return; // solo: ignore everything from the network
         switch (msg.kind) {
-            case 'link:hello':
+            case 'beat:hello':
                 this.peers.add(msg.id);
                 // reply with our current timeline (tagged with our id) so the joiner adopts tempo/phase + learns us
-                this.relay.send(this.id, { kind: 'link:timeline', timeline: this.timeline, ts: this._ts, id: this.id }, msg.id);
+                this.relay.send(this.id, { kind: 'beat:timeline', timeline: this.timeline, ts: this._ts, id: this.id }, msg.id);
                 if (this.onChange)
                     this.onChange();
                 break;
-            case 'link:timeline':
+            case 'beat:timeline':
                 if (msg.id)
                     this.peers.add(msg.id);
                 if (newerTs(msg.ts, this._ts)) {
@@ -203,7 +203,7 @@ export class BeatTimeline {
                 if (this.onChange)
                     this.onChange();
                 break;
-            case 'link:transport':
+            case 'beat:transport':
                 // OBSERVE by default (Link v3: never auto-adopt). `onPeerTransport` lets the app opt into
                 // following (the "Sync play" toggle) — it decides whether to launch/stop locally.
                 this.peers.add(msg.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",
@@ -13,10 +13,22 @@
     "./core": "./src/core/index.js",
     "./config": "./src/config/index.js",
     "./utils": "./src/utils/index.js",
-    "./clock": { "types": "./dist/clock/index.d.ts", "import": "./dist/clock/index.js" },
-    "./clock/musical": { "types": "./dist/clock/musical.d.ts", "import": "./dist/clock/musical.js" },
-    "./clock/sync": { "types": "./dist/clock/sync.d.ts", "import": "./dist/clock/sync.js" },
-    "./clock/curves": { "types": "./dist/clock/curves.d.ts", "import": "./dist/clock/curves.js" }
+    "./clock": {
+      "types": "./dist/clock/index.d.ts",
+      "import": "./dist/clock/index.js"
+    },
+    "./clock/musical": {
+      "types": "./dist/clock/musical.d.ts",
+      "import": "./dist/clock/musical.js"
+    },
+    "./clock/sync": {
+      "types": "./dist/clock/sync.d.ts",
+      "import": "./dist/clock/sync.js"
+    },
+    "./clock/curves": {
+      "types": "./dist/clock/curves.d.ts",
+      "import": "./dist/clock/curves.js"
+    }
   },
   "files": [
     "src/**/*",

package/src/clock/sync.ts

@@ -38,9 +38,9 @@ export interface PeerIntent {
 
 /** Messages exchanged over the relay seam. */
 export type SyncMessage =
-  | { kind: 'link:hello'; id: string }
-  | { kind: 'link:timeline'; timeline: BeatTimelineState; ts: TimelineStamp; id: string }
-  | { kind: 'link:transport'; id: string; playing: boolean; atSessionMs: number };
+  | { kind: 'beat:hello'; id: string }
+  | { kind: 'beat:timeline'; timeline: BeatTimelineState; ts: TimelineStamp; id: string }
+  | { kind: 'beat:transport'; id: string; playing: boolean; atSessionMs: number };
 
 /** A node the relay can register + deliver to. */
 export interface RelayNode {
@@ -183,7 +183,7 @@ export class BeatTimeline implements RelayNode {
   }
   /** Broadcast presence (peers reply with their timeline). Safe to call periodically as a heartbeat. */
   announce(): void {
-    if (this.enabled) this.relay.send(this.id, { kind: 'link:hello', id: this.id });
+    if (this.enabled) this.relay.send(this.id, { kind: 'beat:hello', id: this.id });
   }
 
   /** Toggle participation. Off = solo (no broadcast, no adoption). On = re-announce + re-adopt. */
@@ -228,7 +228,7 @@ export class BeatTimeline implements RelayNode {
     this.timeline = { ...timeline };
     this._ts = { time: this.sessionNowMs(), id: this.id };
     if (this.enabled)
-      this.relay.send(this.id, { kind: 'link:timeline', timeline: this.timeline, ts: this._ts, id: this.id });
+      this.relay.send(this.id, { kind: 'beat:timeline', timeline: this.timeline, ts: this._ts, id: this.id });
     if (this.onChange) this.onChange();
   }
   /** Propose a tempo. Keeps the beat value continuous at the moment of change (no jump). */
@@ -269,7 +269,7 @@ 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: 'link:transport', id: this.id, playing, atSessionMs: this.sessionNowMs() });
+    this.relay.send(this.id, { kind: 'beat:transport', id: this.id, playing, atSessionMs: this.sessionNowMs() });
     if (this.onChange) this.onChange();
   }
 
@@ -277,17 +277,17 @@ export class BeatTimeline implements RelayNode {
   receive(msg: SyncMessage): void {
     if (!this.enabled) return; // solo: ignore everything from the network
     switch (msg.kind) {
-      case 'link:hello':
+      case 'beat:hello':
         this.peers.add(msg.id);
         // reply with our current timeline (tagged with our id) so the joiner adopts tempo/phase + learns us
         this.relay.send(
           this.id,
-          { kind: 'link:timeline', timeline: this.timeline, ts: this._ts, id: this.id },
+          { kind: 'beat:timeline', timeline: this.timeline, ts: this._ts, id: this.id },
           msg.id,
         );
         if (this.onChange) this.onChange();
         break;
-      case 'link:timeline':
+      case 'beat:timeline':
         if (msg.id) this.peers.add(msg.id);
         if (newerTs(msg.ts, this._ts)) {
           this.timeline = { ...msg.timeline };
@@ -295,7 +295,7 @@ export class BeatTimeline implements RelayNode {
         }
         if (this.onChange) this.onChange();
         break;
-      case 'link:transport':
+      case 'beat:transport':
         // OBSERVE by default (Link v3: never auto-adopt). `onPeerTransport` lets the app opt into
         // following (the "Sync play" toggle) — it decides whether to launch/stop locally.
         this.peers.add(msg.id);

package/src/core/lights.js

@@ -1,21 +1,38 @@
 import * as THREE from 'three';
 
+// `hemiRef`/`ambientRef` track the MOST-RECENTLY ensured scene's lights, only so the legacy
+// `updateDefaultLights()` (which takes no scene) keeps targeting the active scene. They are NOT a
+// "lights already created" cache — see ensureDefaultLights.
 let hemiRef = null;
 let ambientRef = null;
 
+/**
+ * Ensure a scene has the default hemisphere + ambient lights. Idempotent PER SCENE.
+ *
+ * ORB-128: a multi-orbiter realm renders N independent scenes through one renderer. A module-level
+ * singleton light is wrong twice over — it's only added to the FIRST scene, and a THREE light can
+ * live in just one scene (adding it to a second removes it from the first), so scenes 2..N rendered
+ * DARK ("only one entangled world"). So create + add the lights PER scene, keyed by name so a
+ * re-call on the same scene is a no-op. Single-orbiter (one scene) is unchanged.
+ */
 export function ensureDefaultLights(scene) {
-  if (!hemiRef) {
-    hemiRef = new THREE.HemisphereLight(0xffffff, 0xffffff, 1.0);
-    hemiRef.position.set(1, 1, 1);
-    hemiRef.name = 'ew_HemisphereLight';
-    scene.add(hemiRef);
+  let hemi = scene.getObjectByName('ew_HemisphereLight');
+  if (!hemi) {
+    hemi = new THREE.HemisphereLight(0xffffff, 0xffffff, 1.0);
+    hemi.position.set(1, 1, 1);
+    hemi.name = 'ew_HemisphereLight';
+    scene.add(hemi);
   }
-  if (!ambientRef) {
-    ambientRef = new THREE.AmbientLight(0xffffff, 1.0);
-    ambientRef.name = 'ew_AmbientLight';
-    scene.add(ambientRef);
+  let ambient = scene.getObjectByName('ew_AmbientLight');
+  if (!ambient) {
+    ambient = new THREE.AmbientLight(0xffffff, 1.0);
+    ambient.name = 'ew_AmbientLight';
+    scene.add(ambient);
   }
-  return { hemi: hemiRef, ambient: ambientRef };
+  // updateDefaultLights() (no scene arg) targets the most-recently ensured scene's lights.
+  hemiRef = hemi;
+  ambientRef = ambient;
+  return { hemi, ambient };
 }
 
 export function updateDefaultLights({ ambientIntensity, diffuseIntensity, lightColor, lightDirection } = {}) {

package/src/loaders/bodyTextureLoader.js

@@ -1,21 +1,12 @@
 import * as THREE from 'three';
-import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+import { getKTX2LoaderForRenderer } from './ktx2.js';
 
 const textureLoader = new THREE.TextureLoader();
 
-// Shared singleton accessor (align with cubeMapLoader)
-function getSharedKTX2Loader() {
-  if (window.__EW_KTX2_LOADER) return window.__EW_KTX2_LOADER;
-  const renderer = window.__EW_RENDERER;
-  const loader = new KTX2Loader().setTranscoderPath('/basis/').detectSupport(renderer);
-  window.__EW_KTX2_LOADER = loader;
-  return loader;
-}
-
-export function loadTexture(url, { signal } = {}) {
+export function loadTexture(url, { signal, renderer } = {}) {
   return new Promise((resolve, reject) => {
     if (url && url.endsWith('.ktx2')) {
-      const ktx2 = getSharedKTX2Loader();
+      const ktx2 = getKTX2LoaderForRenderer(renderer);
       const onAbort = () => reject(new Error('aborted'));
       if (signal) signal.addEventListener('abort', onAbort, { once: true });
       ktx2.load(

package/src/loaders/cubeMapLoader.js

@@ -1,19 +1,9 @@
 import * as THREE from 'three';
-import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
 import { getPublicBase } from '../config/env.js';
+import { getKTX2LoaderForRenderer } from './ktx2.js';
 
 // Base URL is resolved at runtime via helper
 
-// Shared loader + caches
-const ktx2SupportCache = new Map(); // base -> true|false
-
-function getSharedKTX2Loader(renderer) {
-  if (window.__EW_KTX2_LOADER) return window.__EW_KTX2_LOADER;
-  const loader = new KTX2Loader().setTranscoderPath('/basis/').detectSupport(renderer);
-  window.__EW_KTX2_LOADER = loader;
-  return loader;
-}
-
 export function normalizeSkycubeName(raw) {
   if (!raw) return '001';
   const legacy = raw.match(/^(\d{1,2})_skycube(?:_low)?$/);
@@ -68,7 +58,7 @@ function detectExtension(faceKeys) {
 
 // Load KTX2 faces and create skybox mesh
 async function loadFacesKTX2(faceKeys, renderer) {
-  const loader = getSharedKTX2Loader(renderer);
+  const loader = getKTX2LoaderForRenderer(renderer);
   const loaded = [];
   
   for (const face of FACE_ORDER) {

package/src/loaders/glbLoader.js

@@ -1,14 +1,7 @@
 import * as THREE from 'three';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
-import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
 import { ensureStandardMaterial, applyFlagsToMaterial } from '../utils/materials.js';
-
-function getSharedKTX2Loader(renderer) {
-  if (window.__EW_KTX2_LOADER) return window.__EW_KTX2_LOADER;
-  const loader = new KTX2Loader().setTranscoderPath('/basis/').detectSupport(renderer);
-  window.__EW_KTX2_LOADER = loader;
-  return loader;
-}
+import { getKTX2LoaderForRenderer } from './ktx2.js';
 
 export async function loadGLB(url, { retries = 3, signal, onProgress, applyFlags, withCredentials = false } = {}) {
   const renderer = window.__EW_RENDERER;
@@ -20,7 +13,7 @@ export async function loadGLB(url, { retries = 3, signal, onProgress, applyFlags
       const loader = new GLTFLoader()
         .setCrossOrigin(withCredentials ? 'use-credentials' : 'anonymous')
         .setWithCredentials(Boolean(withCredentials))
-        .setKTX2Loader(getSharedKTX2Loader(renderer));
+        .setKTX2Loader(getKTX2LoaderForRenderer(renderer));
 
       const root = await new Promise((resolve, reject) => {
         loader.load(

package/src/loaders/ktx2.js

@@ -0,0 +1,54 @@
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+
+/**
+ * One KTX2Loader PER RENDERER.
+ *
+ * `KTX2Loader.detectSupport(renderer)` binds the loader's Basis transcoder worker pool to ONE WebGL
+ * context. A single shared loader therefore only decodes textures for the FIRST renderer it saw —
+ * every other view's planets/skyboxes silently fail and render untextured (dark). That breaks any
+ * multi-view page: N orbiters in one realm, or N Entangled World planets shown together.
+ *
+ * Keying the loader by renderer gives each view its own correctly-bound loader. Single-renderer apps
+ * (a single orbiter, today's Entangled World) get exactly ONE entry, so behaviour is byte-identical.
+ * (Was: a single `window.__EW_KTX2_LOADER` global shared by bodyTexture/glb/cubeMap loaders.)
+ */
+const loadersByRenderer = new WeakMap();
+let fallbackLoader = null;
+
+function makeLoader(renderer) {
+  return new KTX2Loader().setTranscoderPath('/basis/').detectSupport(renderer);
+}
+
+/**
+ * The KTX2Loader bound to `renderer`. Defaults to the current `window.__EW_RENDERER` so existing call
+ * sites need no change; pass the renderer explicitly when it is in scope (preferred).
+ * @param {import('three').WebGLRenderer} [renderer]
+ * @returns {KTX2Loader}
+ */
+export function getKTX2LoaderForRenderer(
+  renderer = (typeof window !== 'undefined' ? window.__EW_RENDERER : null),
+) {
+  if (!renderer) {
+    if (!fallbackLoader) fallbackLoader = makeLoader(renderer);
+    return fallbackLoader;
+  }
+  let loader = loadersByRenderer.get(renderer);
+  if (!loader) {
+    loader = makeLoader(renderer);
+    loadersByRenderer.set(renderer, loader);
+  }
+  return loader;
+}
+
+/**
+ * Dispose and forget the KTX2Loader for a renderer — call on that renderer's / scene's teardown so the
+ * transcoder workers are terminated (avoids leaking worker threads + GPU memory across view churn).
+ * @param {import('three').WebGLRenderer} renderer
+ */
+export function disposeKTX2LoaderForRenderer(renderer) {
+  const loader = renderer && loadersByRenderer.get(renderer);
+  if (loader) {
+    try { loader.dispose?.(); } catch { /* already gone */ }
+    loadersByRenderer.delete(renderer);
+  }
+}

package/src/world/worldManager.js

@@ -4,8 +4,12 @@ import { makeSphere } from './worldTexture.js';
 import { makeNormalSphere } from './worldNormal.js';
 
 export class WorldManager {
-  constructor(scene, { onLoadStart, onLoadEnd } = {}) {
+  constructor(scene, { onLoadStart, onLoadEnd, renderer } = {}) {
     this.scene = scene;
+    // The renderer this world belongs to — threaded to the texture loaders so each view's textures
+    // bind to its OWN WebGL context (multi-view: N orbiters / N planets in one page). Falls back to
+    // window.__EW_RENDERER for callers that don't pass one, keeping single-renderer apps unchanged.
+    this.renderer = renderer ?? null;
     this.current = null;
     this.flags = {};
     this.onLoadStart = onLoadStart;
@@ -37,20 +41,22 @@ export class WorldManager {
     this.onLoadStart?.();
     try {
       let obj;
-      
+      const renderer = this.renderer ?? (typeof window !== 'undefined' ? window.__EW_RENDERER : null);
+
       // Check for custom creators first
       if (this.customCreators.has(mode)) {
-        obj = await this.customCreators.get(mode)({ flags: this.flags, ...args });
+        obj = await this.customCreators.get(mode)({ flags: this.flags, ...args, renderer });
       } else if (mode === 2) {
         obj = await makeGLB({
           modelUrl: args.modelUrl,
           flags: this.flags,
           withCredentials: Boolean(args.withCredentials),
+          renderer,
         });
       } else if (mode === 3) {
-        obj = await makeNormalSphere({ flags: this.flags, ...args });
+        obj = await makeNormalSphere({ flags: this.flags, ...args, renderer });
       } else {
-        obj = await makeSphere({ textureUrl: args.textureUrl, flags: this.flags, ...args });
+        obj = await makeSphere({ textureUrl: args.textureUrl, flags: this.flags, ...args, renderer });
       }
 
       if (this.token !== myToken) {
@@ -61,12 +67,12 @@ export class WorldManager {
       this.current = obj;
 
       // If the object exposes a frame updater, run a render-time loop
-      if (obj && obj.userData && typeof obj.userData.update === 'function' && window.__EW_RENDERER) {
+      if (obj && obj.userData && typeof obj.userData.update === 'function' && renderer) {
         const updater = obj.userData.update;
         const tick = () => {
           if (this.current === obj) {
             try {
-              updater(window.__EW_RENDERER, performance.now() * 0.001);
+              updater(renderer, performance.now() * 0.001);
             } catch (e) {
               console.warn('[WorldManager] update loop error:', e);
             }

package/src/world/worldTexture.js

@@ -52,6 +52,7 @@ function isLikelyEquirectangular(img) {
 
 export async function makeSphere({
   textureUrl,
+  renderer,
   flags,
   uOffset,
   textureOffsetDeg,
@@ -169,7 +170,7 @@ export async function makeSphere({
   const chosenTexture = textureUrl; // require explicit textureUrl — no implicit default
   if (chosenTexture) {
     try {
-      const tex = await loadTexture(chosenTexture);
+      const tex = await loadTexture(chosenTexture, { renderer });
       tex.colorSpace = THREE.SRGBColorSpace;
       tex.anisotropy = 8;
       if (typeof flipY === 'boolean') tex.flipY = flipY;