entangled-worlds-orbiters-shared 2.1.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",

package/src/loaders/cubeMapLoader.js

@@ -142,11 +142,11 @@ function resolveUrls(faceKeys) {
 
 /**
  * Main loader function - always uses explicit face URLs.
- * `renderer` binds the KTX2 transcoder to the right WebGL context; it falls back to the standalone
- * app's `window.__EW_RENDERER` only transitionally. Pass it explicitly.
+ * `renderer` binds the KTX2 transcoder to the right WebGL context. REQUIRED (3.0) when the KTX2
+ * path is taken — the old `window.__EW_RENDERER` fallback is gone; thread the owning view's
+ * renderer. (The PNG/JPG path is renderer-agnostic, so its absence only bites on KTX2.)
  */
-export async function loadCubeMap({ faceKeys, skycubeName, preferKTX2 = true, forceLow, renderer: rendererOpt } = {}) {
-  const renderer = rendererOpt ?? (typeof window !== 'undefined' ? window.__EW_RENDERER : null);
+export async function loadCubeMap({ faceKeys, skycubeName, preferKTX2 = true, forceLow, renderer } = {}) {
 
   // If no face URLs provided, build them from skycube name
   if (!faceKeys && skycubeName) {

package/src/loaders/glbLoader.js

@@ -5,13 +5,12 @@ import { getKTX2LoaderForRenderer } from './ktx2.js';
 
 /**
  * @param {object} [opts]
- * @param {import('three').WebGLRenderer} [opts.renderer]  the renderer this GLB's textures bind to.
- *   Transitional default: `window.__EW_RENDERER` (the standalone app's publisher). Pass it explicitly
- *   — a page with several renderers has no single correct global, and the default goes away with it.
+ * @param {import('three').WebGLRenderer} opts.renderer  REQUIRED (3.0): the renderer this GLB's
+ *   textures bind to. A page with several renderers has no single correct global, so the old
+ *   `window.__EW_RENDERER` fallback is gone — thread the owning view's renderer.
  */
-export async function loadGLB(url, { retries = 3, signal, onProgress, applyFlags, withCredentials = false, renderer: rendererOpt } = {}) {
-  const renderer = rendererOpt ?? (typeof window !== 'undefined' ? window.__EW_RENDERER : null);
-  if (!renderer) throw new Error('Renderer not ready for KTX2');
+export async function loadGLB(url, { retries = 3, signal, onProgress, applyFlags, withCredentials = false, renderer } = {}) {
+  if (!renderer) throw new Error('[glb] loadGLB requires the owning renderer (KTX2 textures bind per WebGL context).');
 
   let attempt = 0;
   while (attempt < retries) {

package/src/loaders/ktx2.js

@@ -13,27 +13,22 @@ import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
  * (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]
+ * The KTX2Loader bound to `renderer` — REQUIRED (3.0). The old `window.__EW_RENDERER` fallback let
+ * call sites compile while silently binding the transcoder to whichever renderer a page published
+ * last; on any multi-view page that meant untextured worlds. Every caller now threads its own
+ * renderer, so a missing one is a caller bug and fails loudly here rather than as a dark planet.
+ * @param {import('three').WebGLRenderer} renderer
  * @returns {KTX2Loader}
  */
-export function getKTX2LoaderForRenderer(rendererArg) {
-  // `??` not a default param: callers thread an OPTIONAL renderer down several layers, so `null`
-  // arrives as often as `undefined` and must fall back the same way.
-  const renderer = rendererArg ?? (typeof window !== 'undefined' ? window.__EW_RENDERER : null);
+export function getKTX2LoaderForRenderer(renderer) {
   if (!renderer) {
-    // No renderer anywhere: an unbound loader can't transcode (detectSupport needs a context), but
-    // returning one keeps the caller's error local to the texture instead of throwing mid-scene.
-    if (!fallbackLoader) fallbackLoader = new KTX2Loader().setTranscoderPath('/basis/');
-    return fallbackLoader;
+    throw new Error('[ktx2] getKTX2LoaderForRenderer requires the owning renderer — thread it from the view that renders this texture.');
   }
   let loader = loadersByRenderer.get(renderer);
   if (!loader) {

package/src/render/viewportCompositor.js

@@ -24,7 +24,7 @@
  *   solo-renders that voice. The host must not move the canvas itself.
  * - It owns the realm clear: every frame it re-asserts a fully transparent clear colour.
  *
- * @see `publishRendererGlobal` and `devHandleKey` — the two window globals it can write, both opt-in.
+ * @see `devHandleKey` — the one window global it can write, opt-in.
  */
 import * as THREE from 'three';
 
@@ -46,11 +46,6 @@ const DEFAULT_RENDERER_PROFILE = {
  *   builds no grid of its own; when absent, the default `⌈√n⌉` grid is used.
  * @param {Partial<typeof DEFAULT_RENDERER_PROFILE>} [opts.rendererProfile] renderer construction +
  *   pixel-ratio cap. Omit for the historical defaults.
- * @param {boolean} [opts.publishRendererGlobal=false] write `window.__EW_RENDERER = renderer`.
- *   OPT-IN, and at most ONE compositor per page may set it: it is the fallback the shared loaders read
- *   when no renderer is threaded to them, so two realms both publishing would make one realm's loads
- *   bind their KTX2 transcoder to the OTHER realm's context (untextured worlds). Consumers that thread
- *   the renderer explicitly must leave this off.
  * @param {string|null} [opts.devHandleKey=null] when set, publish the returned api on
  *   `window[devHandleKey]` so tooling can force a composited frame while rAF is throttled (a hidden
  *   tab during automated checks). Off by default — a library does not name globals for its host.
@@ -67,7 +62,6 @@ const DEFAULT_RENDERER_PROFILE = {
 export function createViewportCompositor({
   cellSource = null,
   rendererProfile = null,
-  publishRendererGlobal = false,
   devHandleKey = null,
 } = {}) {
   const profile = { ...DEFAULT_RENDERER_PROFILE, ...(rendererProfile || {}) };
@@ -83,12 +77,6 @@ export function createViewportCompositor({
   document.body.appendChild(canvas);
 
   const renderer = createRenderer(canvas, profile);
-  // The loaders fall back to `window.__EW_RENDERER` when nothing threads a renderer to them. Publishing
-  // it lets a realm whose voices still rely on that fallback upload every texture to THIS context.
-  // Opt-in, single-writer: see `publishRendererGlobal`.
-  if (publishRendererGlobal && typeof window !== 'undefined') {
-    window.__EW_RENDERER = renderer;
-  }
 
   /** voiceId → { cell, controller, lastW, lastH, rect } */
   const voices = new Map();
@@ -330,11 +318,8 @@ export function createViewportCompositor({
     // If disposed while a voice was fullscreen, put the canvas style back before `canvas.remove()`.
     restoreCanvasHome();
     voices.clear();
-    if (typeof window !== 'undefined') {
-      if (window.__EW_RENDERER === renderer) delete window.__EW_RENDERER;
-      if (devHandleKey && window[devHandleKey]?.renderer === renderer) {
-        delete window[devHandleKey];
-      }
+    if (typeof window !== 'undefined' && devHandleKey && window[devHandleKey]?.renderer === renderer) {
+      delete window[devHandleKey];
     }
     renderer.dispose();
     grid?.remove();

package/src/world/cloudShell.js

@@ -7,6 +7,7 @@ async function makeTextureMaterial({
   opacity = 0.6,
   textureUrl,
   speed = 0.015,
+  renderer = null,
 } = {}) {
   const mat = new THREE.MeshStandardMaterial({
     color,
@@ -21,7 +22,9 @@ async function makeTextureMaterial({
   });
 
   if (textureUrl) {
-    const tex = await loadTexture(textureUrl);
+    // Thread the owning view's renderer: KTX2 cloud textures must transcode against the caller's
+    // context, not the global fallback (which shared-renderer pages don't publish at all).
+    const tex = await loadTexture(textureUrl, { renderer });
     tex.wrapS = THREE.RepeatWrapping;
     tex.wrapT = THREE.RepeatWrapping;
     // Use linear space for alpha masks if available
@@ -60,6 +63,7 @@ export async function createCloudShell({
   color = 0xffffff,
   opacity = 0.6,
   speed = 0.015,
+  renderer = null,
 } = {}) {
   const geom = baseGeometry
     ? baseGeometry.clone()
@@ -70,6 +74,7 @@ export async function createCloudShell({
     opacity,
     textureUrl,
     speed,
+    renderer,
   });
 
   const mesh = new THREE.Mesh(geom, material);

package/src/world/worldManager.js

@@ -4,12 +4,17 @@ import { makeSphere } from './worldTexture.js';
 import { makeNormalSphere } from './worldNormal.js';
 
 export class WorldManager {
-  constructor(scene, { onLoadStart, onLoadEnd, renderer } = {}) {
+  constructor(scene, { onLoadStart, onLoadEnd, renderer, externalTick = false } = {}) {
     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.
+    // bind to its OWN WebGL context (multi-view: N orbiters / N planets in one page). REQUIRED for
+    // textured worlds (3.0): the window.__EW_RENDERER fallback is gone.
     this.renderer = renderer ?? null;
+    // Shared-renderer hosts drive world animation from THEIR loop: with `externalTick` this manager
+    // starts no internal rAF for `userData.update` worlds — the host calls `tick(timeSec)` per
+    // rendered frame instead. Otherwise N animated worlds on one page would each run their own loop,
+    // defeating the one-loop compositor.
+    this.externalTick = Boolean(externalTick);
     this.current = null;
     this.flags = {};
     this.onLoadStart = onLoadStart;
@@ -19,6 +24,20 @@ export class WorldManager {
     this.customCreators = new Map();
   }
 
+  /** Run the current world's per-frame updater once (externalTick hosts only; no-op otherwise). */
+  tick(timeSec) {
+    if (!this.externalTick || !this.current) return;
+    const updater = this.current.userData?.update;
+    if (typeof updater !== 'function') return;
+    const renderer = this.renderer;
+    if (!renderer) return;
+    try {
+      updater(renderer, timeSec);
+    } catch (e) {
+      console.warn('[WorldManager] update tick error:', e);
+    }
+  }
+
   setFlags(flags) {
     this.flags = { ...this.flags, ...flags };
   }
@@ -41,7 +60,7 @@ export class WorldManager {
     this.onLoadStart?.();
     try {
       let obj;
-      const renderer = this.renderer ?? (typeof window !== 'undefined' ? window.__EW_RENDERER : null);
+      const renderer = this.renderer;
 
       // Check for custom creators first
       if (this.customCreators.has(mode)) {
@@ -66,8 +85,9 @@ export class WorldManager {
       this.scene.add(obj);
       this.current = obj;
 
-      // If the object exposes a frame updater, run a render-time loop
-      if (obj && obj.userData && typeof obj.userData.update === 'function' && renderer) {
+      // If the object exposes a frame updater, run a render-time loop — unless an external host
+      // drives it via tick() (shared-renderer compositor: one loop for all worlds).
+      if (!this.externalTick && obj && obj.userData && typeof obj.userData.update === 'function' && renderer) {
         const updater = obj.userData.update;
         const tick = () => {
           if (this.current === obj) {

package/src/world/worldNormal.js

@@ -27,6 +27,7 @@ export async function makeNormalSphere({
   cloudsColor = 0xffffff,
   cloudsOpacity = 0.6,
   cloudsSpeed = 0.015,
+  renderer = null,
 } = {}) {
   const radius = typeof sphereRadius === 'number' ? Math.max(0.0001, sphereRadius) : EARTH_RADIUS_UNITS;
   const widthSegs = Number.isFinite(sphereWidthSegments) ? Math.max(3, Math.floor(sphereWidthSegments)) : 64;
@@ -63,6 +64,7 @@ export async function makeNormalSphere({
       color: cloudsColor,
       opacity: cloudsOpacity,
       speed: cloudsSpeed,
+      renderer,
     });
     mesh.add(cloudMesh);
   }

package/src/world/worldTexture.js

@@ -309,6 +309,7 @@ export async function makeSphere({
       color: cloudsColor,
       opacity: cloudsOpacity,
       speed: cloudsSpeed,
+      renderer,
     });
     mesh.add(cloudMesh);
   }