entangled-worlds-orbiters-shared 1.2.1 → 1.4.0

package/dist/clock/track-metadata.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The slice of a track's data these resolvers read. Every field is optional and untyped at the leaf
+ * because the runtime objects come from different app layers (release metadata, effective owner
+ * settings, per-user overrides, audio analysis). Resolvers coerce leaves with Number(...) and ignore
+ * anything non-finite, so a permissive shape here is intentional — not every consumer fills every path.
+ */
+export interface SyncSettingsLike {
+    trackBpm?: unknown;
+    primaryGridMarkerTimeSec?: unknown;
+    gridMarkers?: ReadonlyArray<{
+        sourceTimeSec?: unknown;
+    } | null | undefined> | null;
+    gridStartTimeSec?: unknown;
+}
+export interface TrackMetadataLike {
+    trackBpm?: unknown;
+    primaryGridMarkerTimeSec?: unknown;
+    effectiveSettings?: {
+        sync?: SyncSettingsLike | null;
+    } | null;
+    audioAnalysis?: {
+        analysis?: {
+            tempo_bpm?: unknown;
+        } | null;
+    } | null;
+    wrap?: {
+        gridMarkers?: ReadonlyArray<{
+            sourceTimeSec?: unknown;
+        } | null | undefined> | null;
+        gridStartTimeSec?: unknown;
+    } | null;
+}
+export interface TrackDataLike {
+    track?: {
+        metadata?: TrackMetadataLike | null;
+    } | null;
+    release?: {
+        metadata?: TrackMetadataLike | null;
+    } | null;
+    metadata?: TrackMetadataLike | null;
+    trackUserSettings?: {
+        sync?: SyncSettingsLike | null;
+    } | null;
+}
+/**
+ * Resolve the effective track BPM. Precedence (first finite, > 0 wins):
+ * owner `trackBpm` → owner `effectiveSettings.sync.trackBpm` → per-user `trackUserSettings.sync.trackBpm`
+ * → auto-detected `audioAnalysis.analysis.tempo_bpm`. Returns null when nothing resolves.
+ */
+export declare function resolveTrackBpmFromTrackData(trackData?: TrackDataLike | null): number | null;
+/**
+ * Resolve the primary grid-marker (downbeat) time in seconds — the grid offset that becomes
+ * `tempoMap[0].startSec`. Precedence (first finite, >= 0 wins) walks the explicit
+ * `primaryGridMarkerTimeSec`, then per-user grid markers / start time, then the wrap fallback.
+ * Returns null when nothing resolves (consumers default to 0).
+ */
+export declare function resolvePrimaryGridMarkerTimeSecFromTrackData(trackData?: TrackDataLike | null): number | null;

package/dist/clock/track-metadata.js

@@ -0,0 +1,66 @@
+// ./clock/track-metadata — pure resolution of a track's tempo (BPM) and its primary grid-marker
+// (downbeat) time from the loosely-typed metadata both apps already carry. Framework-free, no three,
+// no react: it walks a fixed precedence (owner setting → per-user setting → auto-detected analysis)
+// and returns the first finite value, so a consumer can feed `new MusicalProjection({ tempoMap: [{
+// startSec: gridSec, bpm }] })`. Promoted out of the orbiters app (ORB-137) so EW reuses it verbatim.
+function toPositiveNumber(value) {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) && numeric > 0 ? numeric : null;
+}
+function toNonNegativeNumber(value) {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) && numeric >= 0 ? numeric : null;
+}
+function firstResolvedValue(candidates, parser) {
+    for (const candidate of candidates) {
+        const resolved = parser(candidate);
+        if (resolved !== null) {
+            return resolved;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the effective track BPM. Precedence (first finite, > 0 wins):
+ * owner `trackBpm` → owner `effectiveSettings.sync.trackBpm` → per-user `trackUserSettings.sync.trackBpm`
+ * → auto-detected `audioAnalysis.analysis.tempo_bpm`. Returns null when nothing resolves.
+ */
+export function resolveTrackBpmFromTrackData(trackData = null) {
+    return firstResolvedValue([
+        trackData?.track?.metadata?.trackBpm,
+        trackData?.release?.metadata?.trackBpm,
+        trackData?.metadata?.trackBpm,
+        trackData?.track?.metadata?.effectiveSettings?.sync?.trackBpm,
+        trackData?.release?.metadata?.effectiveSettings?.sync?.trackBpm,
+        trackData?.metadata?.effectiveSettings?.sync?.trackBpm,
+        trackData?.trackUserSettings?.sync?.trackBpm,
+        trackData?.track?.metadata?.audioAnalysis?.analysis?.tempo_bpm,
+        trackData?.release?.metadata?.audioAnalysis?.analysis?.tempo_bpm,
+        trackData?.metadata?.audioAnalysis?.analysis?.tempo_bpm,
+    ], toPositiveNumber);
+}
+/**
+ * Resolve the primary grid-marker (downbeat) time in seconds — the grid offset that becomes
+ * `tempoMap[0].startSec`. Precedence (first finite, >= 0 wins) walks the explicit
+ * `primaryGridMarkerTimeSec`, then per-user grid markers / start time, then the wrap fallback.
+ * Returns null when nothing resolves (consumers default to 0).
+ */
+export function resolvePrimaryGridMarkerTimeSecFromTrackData(trackData = null) {
+    return firstResolvedValue([
+        trackData?.track?.metadata?.primaryGridMarkerTimeSec,
+        trackData?.release?.metadata?.primaryGridMarkerTimeSec,
+        trackData?.metadata?.primaryGridMarkerTimeSec,
+        trackData?.track?.metadata?.effectiveSettings?.sync?.primaryGridMarkerTimeSec,
+        trackData?.release?.metadata?.effectiveSettings?.sync?.primaryGridMarkerTimeSec,
+        trackData?.metadata?.effectiveSettings?.sync?.primaryGridMarkerTimeSec,
+        trackData?.trackUserSettings?.sync?.primaryGridMarkerTimeSec,
+        trackData?.trackUserSettings?.sync?.gridMarkers?.[0]?.sourceTimeSec,
+        trackData?.trackUserSettings?.sync?.gridStartTimeSec,
+        trackData?.track?.metadata?.wrap?.gridMarkers?.[0]?.sourceTimeSec,
+        trackData?.release?.metadata?.wrap?.gridMarkers?.[0]?.sourceTimeSec,
+        trackData?.metadata?.wrap?.gridMarkers?.[0]?.sourceTimeSec,
+        trackData?.track?.metadata?.wrap?.gridStartTimeSec,
+        trackData?.release?.metadata?.wrap?.gridStartTimeSec,
+        trackData?.metadata?.wrap?.gridStartTimeSec,
+    ], toNonNegativeNumber);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "1.2.1",
+  "version": "1.4.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,26 @@
     "./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/track-metadata": {
+      "types": "./dist/clock/track-metadata.d.ts",
+      "import": "./dist/clock/track-metadata.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/track-metadata.ts

@@ -0,0 +1,113 @@
+// ./clock/track-metadata — pure resolution of a track's tempo (BPM) and its primary grid-marker
+// (downbeat) time from the loosely-typed metadata both apps already carry. Framework-free, no three,
+// no react: it walks a fixed precedence (owner setting → per-user setting → auto-detected analysis)
+// and returns the first finite value, so a consumer can feed `new MusicalProjection({ tempoMap: [{
+// startSec: gridSec, bpm }] })`. Promoted out of the orbiters app (ORB-137) so EW reuses it verbatim.
+
+/**
+ * The slice of a track's data these resolvers read. Every field is optional and untyped at the leaf
+ * because the runtime objects come from different app layers (release metadata, effective owner
+ * settings, per-user overrides, audio analysis). Resolvers coerce leaves with Number(...) and ignore
+ * anything non-finite, so a permissive shape here is intentional — not every consumer fills every path.
+ */
+export interface SyncSettingsLike {
+  trackBpm?: unknown;
+  primaryGridMarkerTimeSec?: unknown;
+  gridMarkers?: ReadonlyArray<{ sourceTimeSec?: unknown } | null | undefined> | null;
+  gridStartTimeSec?: unknown;
+}
+
+export interface TrackMetadataLike {
+  trackBpm?: unknown;
+  primaryGridMarkerTimeSec?: unknown;
+  effectiveSettings?: { sync?: SyncSettingsLike | null } | null;
+  audioAnalysis?: { analysis?: { tempo_bpm?: unknown } | null } | null;
+  wrap?: {
+    gridMarkers?: ReadonlyArray<{ sourceTimeSec?: unknown } | null | undefined> | null;
+    gridStartTimeSec?: unknown;
+  } | null;
+}
+
+export interface TrackDataLike {
+  track?: { metadata?: TrackMetadataLike | null } | null;
+  release?: { metadata?: TrackMetadataLike | null } | null;
+  metadata?: TrackMetadataLike | null;
+  trackUserSettings?: { sync?: SyncSettingsLike | null } | null;
+}
+
+function toPositiveNumber(value: unknown): number | null {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric > 0 ? numeric : null;
+}
+
+function toNonNegativeNumber(value: unknown): number | null {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric >= 0 ? numeric : null;
+}
+
+function firstResolvedValue(
+  candidates: ReadonlyArray<unknown>,
+  parser: (value: unknown) => number | null,
+): number | null {
+  for (const candidate of candidates) {
+    const resolved = parser(candidate);
+    if (resolved !== null) {
+      return resolved;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the effective track BPM. Precedence (first finite, > 0 wins):
+ * owner `trackBpm` → owner `effectiveSettings.sync.trackBpm` → per-user `trackUserSettings.sync.trackBpm`
+ * → auto-detected `audioAnalysis.analysis.tempo_bpm`. Returns null when nothing resolves.
+ */
+export function resolveTrackBpmFromTrackData(trackData: TrackDataLike | null = null): number | null {
+  return firstResolvedValue(
+    [
+      trackData?.track?.metadata?.trackBpm,
+      trackData?.release?.metadata?.trackBpm,
+      trackData?.metadata?.trackBpm,
+      trackData?.track?.metadata?.effectiveSettings?.sync?.trackBpm,
+      trackData?.release?.metadata?.effectiveSettings?.sync?.trackBpm,
+      trackData?.metadata?.effectiveSettings?.sync?.trackBpm,
+      trackData?.trackUserSettings?.sync?.trackBpm,
+      trackData?.track?.metadata?.audioAnalysis?.analysis?.tempo_bpm,
+      trackData?.release?.metadata?.audioAnalysis?.analysis?.tempo_bpm,
+      trackData?.metadata?.audioAnalysis?.analysis?.tempo_bpm,
+    ],
+    toPositiveNumber,
+  );
+}
+
+/**
+ * Resolve the primary grid-marker (downbeat) time in seconds — the grid offset that becomes
+ * `tempoMap[0].startSec`. Precedence (first finite, >= 0 wins) walks the explicit
+ * `primaryGridMarkerTimeSec`, then per-user grid markers / start time, then the wrap fallback.
+ * Returns null when nothing resolves (consumers default to 0).
+ */
+export function resolvePrimaryGridMarkerTimeSecFromTrackData(
+  trackData: TrackDataLike | null = null,
+): number | null {
+  return firstResolvedValue(
+    [
+      trackData?.track?.metadata?.primaryGridMarkerTimeSec,
+      trackData?.release?.metadata?.primaryGridMarkerTimeSec,
+      trackData?.metadata?.primaryGridMarkerTimeSec,
+      trackData?.track?.metadata?.effectiveSettings?.sync?.primaryGridMarkerTimeSec,
+      trackData?.release?.metadata?.effectiveSettings?.sync?.primaryGridMarkerTimeSec,
+      trackData?.metadata?.effectiveSettings?.sync?.primaryGridMarkerTimeSec,
+      trackData?.trackUserSettings?.sync?.primaryGridMarkerTimeSec,
+      trackData?.trackUserSettings?.sync?.gridMarkers?.[0]?.sourceTimeSec,
+      trackData?.trackUserSettings?.sync?.gridStartTimeSec,
+      trackData?.track?.metadata?.wrap?.gridMarkers?.[0]?.sourceTimeSec,
+      trackData?.release?.metadata?.wrap?.gridMarkers?.[0]?.sourceTimeSec,
+      trackData?.metadata?.wrap?.gridMarkers?.[0]?.sourceTimeSec,
+      trackData?.track?.metadata?.wrap?.gridStartTimeSec,
+      trackData?.release?.metadata?.wrap?.gridStartTimeSec,
+      trackData?.metadata?.wrap?.gridStartTimeSec,
+    ],
+    toNonNegativeNumber,
+  );
+}

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;