entangled-worlds-orbiters-shared 1.5.1 → 2.1.0

package/package.json

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

package/src/core/lights.js

@@ -1,11 +1,5 @@
 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.
  *
@@ -29,29 +23,39 @@ export function ensureDefaultLights(scene) {
     ambient.name = 'ew_AmbientLight';
     scene.add(ambient);
   }
-  // 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 } = {}) {
-  if (typeof ambientIntensity === 'number' && ambientRef) ambientRef.intensity = Math.max(0, ambientIntensity);
-  if (hemiRef) {
-    if (typeof diffuseIntensity === 'number') hemiRef.intensity = Math.max(0, diffuseIntensity);
-    if (lightColor != null) {
-      if (lightColor instanceof THREE.Color) {
-        hemiRef.color.copy(lightColor);
-      } else if (typeof lightColor === 'number') {
-        hemiRef.color.setHex(lightColor);
-      } else if (typeof lightColor === 'string') {
-        hemiRef.color.set(lightColor);
-      }
-    }
-    if (lightDirection && typeof lightDirection.x === 'number') {
-      hemiRef.position.set(lightDirection.x, lightDirection.y ?? 0, lightDirection.z ?? 0).normalize();
+/**
+ * Apply a lighting patch to ONE scene's default lights.
+ *
+ * The scene is required. This used to address module-global light refs pointing at whichever scene
+ * was ensured last, so on a page rendering several scenes every lighting update landed on one of
+ * them — a shared-renderer page (N feed worlds, N orbiters) lit the wrong world.
+ *
+ * @param {import('three').Scene} scene
+ */
+export function updateDefaultLights(scene, { ambientIntensity, diffuseIntensity, lightColor, lightDirection } = {}) {
+  if (!scene?.isObject3D) {
+    console.error('[lights] updateDefaultLights(scene, patch) requires the scene to update; ignoring patch.');
+    return;
+  }
+  const { hemi, ambient } = ensureDefaultLights(scene);
+
+  if (typeof ambientIntensity === 'number') ambient.intensity = Math.max(0, ambientIntensity);
+  if (typeof diffuseIntensity === 'number') hemi.intensity = Math.max(0, diffuseIntensity);
+  if (lightColor != null) {
+    if (lightColor instanceof THREE.Color) {
+      hemi.color.copy(lightColor);
+    } else if (typeof lightColor === 'number') {
+      hemi.color.setHex(lightColor);
+    } else if (typeof lightColor === 'string') {
+      hemi.color.set(lightColor);
     }
   }
+  if (lightDirection && typeof lightDirection.x === 'number') {
+    hemi.position.set(lightDirection.x, lightDirection.y ?? 0, lightDirection.z ?? 0).normalize();
+  }
 }
 
 // Back-compat helper

package/src/loaders/cubeMapLoader.js

@@ -140,10 +140,14 @@ function resolveUrls(faceKeys) {
   return resolved;
 }
 
-// Main loader function - always uses explicit face URLs
-export async function loadCubeMap({ faceKeys, skycubeName, preferKTX2 = true, forceLow } = {}) {
-  const renderer = window.__EW_RENDERER;
-  
+/**
+ * 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.
+ */
+export async function loadCubeMap({ faceKeys, skycubeName, preferKTX2 = true, forceLow, renderer: rendererOpt } = {}) {
+  const renderer = rendererOpt ?? (typeof window !== 'undefined' ? window.__EW_RENDERER : null);
+
   // If no face URLs provided, build them from skycube name
   if (!faceKeys && skycubeName) {
     const low = typeof forceLow === 'boolean' ? forceLow : isLowPerformanceDevice();
@@ -248,8 +252,8 @@ export function setBackground(scene, resource) {
   }
 }
 
-export async function initSpaceScene(scene) {
+export async function initSpaceScene(scene, { renderer } = {}) {
   const faceKeys = buildSkycubefaceKeys('001');
-  const cube = await loadCubeMap({ faceKeys, preferKTX2: true });
+  const cube = await loadCubeMap({ faceKeys, preferKTX2: true, renderer });
   setBackground(scene, cube);
 }

package/src/loaders/glbLoader.js

@@ -3,8 +3,14 @@ import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import { ensureStandardMaterial, applyFlagsToMaterial } from '../utils/materials.js';
 import { getKTX2LoaderForRenderer } from './ktx2.js';
 
-export async function loadGLB(url, { retries = 3, signal, onProgress, applyFlags, withCredentials = false } = {}) {
-  const renderer = window.__EW_RENDERER;
+/**
+ * @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.
+ */
+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');
 
   let attempt = 0;

package/src/loaders/index.js

@@ -1,4 +1,5 @@
 // Loaders exports
 export { loadCubeMap, setBackground, normalizeSkycubeName, buildSkycubefaceKeys } from './cubeMapLoader.js';
 export { loadGLB } from './glbLoader.js';
-export { loadTexture } from './bodyTextureLoader.js';
+export { loadTexture } from './bodyTextureLoader.js';
+export { getKTX2LoaderForRenderer, disposeKTX2LoaderForRenderer } from './ktx2.js';

package/src/loaders/ktx2.js

@@ -25,11 +25,14 @@ function makeLoader(renderer) {
  * @param {import('three').WebGLRenderer} [renderer]
  * @returns {KTX2Loader}
  */
-export function getKTX2LoaderForRenderer(
-  renderer = (typeof window !== 'undefined' ? window.__EW_RENDERER : null),
-) {
+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);
   if (!renderer) {
-    if (!fallbackLoader) fallbackLoader = makeLoader(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;
   }
   let loader = loadersByRenderer.get(renderer);

package/src/moons/moonsGeneration.js

@@ -40,6 +40,9 @@ export async function generateMoons({
   // behavior flags
   preserveInstanceTint = false,      // keep per-instance color even when textured
   useEmissiveMapFromTexture = true,  // reuse color texture as emissiveMap to lift dark sides
+  // The renderer whose KTX2 transcoder decodes the moon texture. Required on any page with more than
+  // one renderer; falls back to the standalone app's global inside the loader.
+  renderer,
 } = {}) {
   if (count <= 0) return null;
 
@@ -95,11 +98,11 @@ export async function generateMoons({
     const fallbackTexture = textureFallback || texturePNG;
     
     try {
-      sharedTexture = await loadTexture(primaryTexture);
+      sharedTexture = await loadTexture(primaryTexture, { renderer });
     } catch (eKTX) {
       if (debug) console.warn('[Moons] Primary texture failed, trying fallback:', eKTX);
       try {
-        sharedTexture = await loadTexture(fallbackTexture);
+        sharedTexture = await loadTexture(fallbackTexture, { renderer });
       } catch (ePNG) {
         if (debug) console.warn('[Moons] Both primary and fallback texture loading failed');
       }
@@ -195,15 +198,7 @@ export async function generateMoons({
   group.add(instanced);
   group.name = 'moonsGroup';
 
-  // Add disposal method for cleanup
-  group.dispose = () => {
-    if (moonGeometry) moonGeometry.dispose();
-    if (moonMaterial.map && moonMaterial.map !== sharedTexture) moonMaterial.map.dispose();
-    if (moonMaterial.emissiveMap && moonMaterial.emissiveMap !== sharedTexture) moonMaterial.emissiveMap.dispose();
-    if (moonMaterial.bumpMap && moonMaterial.bumpMap !== sharedTexture) moonMaterial.bumpMap.dispose();
-    moonMaterial.dispose();
-    instanced.dispose();
-  };
-
+  // Teardown goes through `disposeObject3D` (MoonsManager.dispose / setAmount), which frees the
+  // geometry, the material's textures and the instance buffers.
   return group;
 }

package/src/moons/moonsManager.js

@@ -3,8 +3,14 @@ import * as THREE from 'three';
 import { generateMoons } from './moonsGeneration.js';
 
 export class MoonsManager {
-  constructor(scene) {
+  /**
+   * @param {import('three').Scene} scene
+   * @param {object} [opts]
+   * @param {import('three').WebGLRenderer} [opts.renderer]  renderer the moon texture binds to (KTX2).
+   */
+  constructor(scene, { renderer } = {}) {
     this.scene = scene;
+    this.renderer = renderer;
     this.group = null;
     this._opId = 0; // concurrency guard
   }
@@ -44,6 +50,7 @@ export class MoonsManager {
         textureKey, // Pass texture key for custom moon textures
         textureFallback,
         moonColor, // Pass moon color to generator
+        renderer: this.renderer,
       });
     } catch (e) {
       console.warn('[MoonsManager] Failed to generate moons:', e);
@@ -63,4 +70,16 @@ export class MoonsManager {
       console.warn('[MoonsManager] generateMoons did not return an Object3D');
     }
   }
+
+  /**
+   * Remove the moons from the scene and free their GPU resources. `scene.remove(group)` alone leaks
+   * the instanced geometry, materials and the shared moon texture on every view teardown.
+   */
+  dispose() {
+    this._opId++; // abandon any in-flight setAmount
+    if (this.group) {
+      disposeObject3D(this.group);
+      this.group = null;
+    }
+  }
 }

package/src/render/index.js

@@ -0,0 +1,2 @@
+// Render-host exports
+export { createViewportCompositor } from './viewportCompositor.js';

package/src/render/viewportCompositor.js

@@ -0,0 +1,382 @@
+/**
+ * @file src/render/viewportCompositor.js
+ * @description ORB-128 — a multi-view render host: ONE canvas, ONE `WebGLRenderer`, ONE rAF loop.
+ * Each frame it iterates the registered voices and renders each voice's scene into its own cell via
+ * `setViewport`/`setScissor` (three's "multiple views, one renderer"). This replaces the N-canvas
+ * spike, which hit a hard wall: N canvases = N WebGL contexts, and KTX2/compressed textures only
+ * upload to the FIRST context, so only voice-0 ever textured. One context → every voice textures.
+ *
+ * Each voice's controller runs in `sharedRenderer` mode — it contributes a scene+camera and per-frame
+ * callbacks but owns no renderer and no loop; this host drives it through `renderViewport(rect)`.
+ *
+ * Cell geometry has two sources:
+ *   - default: the compositor builds its own `⌈√n⌉` square grid (`ensureGrid`).
+ *   - external: a `cellSource` supplies the cells — real DOM the layout owns, so the compositor
+ *     renders each voice into its cell's rect and never builds or removes grid DOM.
+ *
+ * ## Host contract (this module is app-agnostic, but NOT assumption-free)
+ * A host adopting it must accept all of the following, or wrap it:
+ * - The canvas is appended to `document.body`, `position:fixed;inset:0`, `z-index:40`, opaque black
+ *   CSS background. The default grid it may build is `#multi-orbiter-grid` at `z-index:41`.
+ * - A voice is `{ voiceId, cell, controller }`, where `controller` exposes `renderActive`,
+ *   `renderViewport(rect)` and `setViewportSize(w, h)`. Rects are CSS px, GL bottom-left origin.
+ * - Browser-fullscreen on a registered CELL reparents the shared canvas into that cell and
+ *   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.
+ */
+import * as THREE from 'three';
+
+const GRID_ID = 'multi-orbiter-grid';
+
+/** Renderer defaults. Overridable via `rendererProfile`; these values are the historical constants. */
+const DEFAULT_RENDERER_PROFILE = {
+  antialias: true,
+  alpha: true,
+  preserveDrawingBuffer: false,
+  powerPreference: 'high-performance',
+  maxDevicePixelRatio: 1.5,
+};
+
+/**
+ * @param {object} [opts]
+ * @param {{ acquireCell: (index:number, total:number) => HTMLElement, releaseCell?: (index:number) => void } | null} [opts.cellSource]
+ *   external owner of the cell DOM. When present, `createCell` delegates to it and the compositor
+ *   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.
+ * @returns {{
+ *   renderer: THREE.WebGLRenderer,
+ *   canvas: HTMLCanvasElement,
+ *   createCell: (index: number, total: number) => HTMLElement,
+ *   addVoice: (voice: { voiceId: string, cell: HTMLElement, controller: object }) => void,
+ *   removeVoice: (voiceId: string) => void,
+ *   renderOnce: () => void,
+ *   dispose: () => void,
+ * }}
+ */
+export function createViewportCompositor({
+  cellSource = null,
+  rendererProfile = null,
+  publishRendererGlobal = false,
+  devHandleKey = null,
+} = {}) {
+  const profile = { ...DEFAULT_RENDERER_PROFILE, ...(rendererProfile || {}) };
+  // ONE full-bleed canvas behind the grid; the grid cells are transparent and only define geometry
+  // (and host the per-tile GUI later — G2). The canvas owns the pixels for ALL voices.
+  const canvas = document.createElement('canvas');
+  canvas.id = 'multi-orbiter-canvas';
+  // A <canvas> is a REPLACED element: `inset:0` alone leaves it at its intrinsic 300×150 (unlike a
+  // div, it does not stretch to the inset box). Explicit width/height make it fill the viewport so the
+  // drawing buffer matches the grid — without this every voice renders into a 300×150 buffer (off-screen).
+  canvas.style.cssText =
+    'position:fixed;inset:0;width:100%;height:100%;z-index:40;display:block;background:#000;';
+  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();
+  let grid = null;
+  let raf = null;
+  let disposed = false;
+  let lastCanvasW = 0;
+  let lastCanvasH = 0;
+
+  // ORB-162: the rAF loop must NOT read layout every frame. `getBoundingClientRect()` / `clientHeight`
+  // force a synchronous reflow, and while dragging the camera the per-tile knob re-renders dirty the
+  // layout every frame — so N per-frame reads = N reflows = the janky, irregular knob response in multi.
+  // Instead we CACHE each cell's rect + the canvas size and refresh only when something actually changes
+  // (a cell resizes, the stack scrolls, or the window resizes). A steady drag then reads zero layout.
+  let rectsDirty = true;
+  const markRectsDirty = () => { rectsDirty = true; };
+  const cellObserver =
+    typeof ResizeObserver !== 'undefined' ? new ResizeObserver(markRectsDirty) : null;
+  // Cells move (without resizing) when the mobile vertical stage stack scrolls — capture-phase catches
+  // scrolling of any ancestor container, not just the window. Window resize changes the canvas box too.
+  if (typeof window !== 'undefined') {
+    window.addEventListener('scroll', markRectsDirty, { passive: true, capture: true });
+    window.addEventListener('resize', markRectsDirty);
+  }
+
+  // ORB-190: browser-fullscreen ownership for a voice. The shared canvas lives on `<body>` (fixed,
+  // inset:0) and scissor-renders every cell; a cell is a transparent div on top of it. When a voice's
+  // header fullscreens ITS cell, the fullscreen "top layer" draws the cell (and its chrome) above an
+  // opaque backdrop that HIDES the body-level canvas — so the orbiter's 3D pixels would vanish. Fix:
+  // reparent the one shared canvas INTO the fullscreened cell (so it paints inside the top layer) and
+  // solo-render that voice full-bleed; restore both on exit. Single-orbiter never builds a compositor,
+  // so this path is realm-only. The header only calls `requestFullscreen()` on the cell — this listener
+  // owns the canvas move + solo, keeping the compositor the single owner of its canvas.
+  let fullscreenVoiceId = null; // voiceId rendered solo full-bleed while fullscreen, else null
+  let canvasHome = null; // { parent, next, cssText } to restore the canvas to its realm home on exit
+  const fullscreenElement = () =>
+    (typeof document !== 'undefined'
+      ? document.fullscreenElement || document.webkitFullscreenElement || null
+      : null);
+  const voiceIdForCell = (el) => {
+    if (!el) return null;
+    for (const [id, voice] of voices) if (voice.cell === el) return id;
+    return null;
+  };
+  /** Put the canvas back to its realm home (`<body>`) and un-mutate its style. Safe to call when not
+   *  fullscreen (no-op). `next` may have been detached from `parent` during fullscreen, so fall back
+   *  to append rather than let `insertBefore` throw NotFoundError. Clears `fullscreenVoiceId`. */
+  const restoreCanvasHome = () => {
+    if (canvasHome) {
+      const { parent, next, cssText } = canvasHome;
+      canvas.style.cssText = cssText;
+      if (parent) parent.insertBefore(canvas, next && next.parentNode === parent ? next : null);
+      canvasHome = null;
+    }
+    fullscreenVoiceId = null;
+  };
+  const onFullscreenChange = () => {
+    const enteringId = voiceIdForCell(fullscreenElement());
+    if (enteringId) {
+      if (fullscreenVoiceId === enteringId) return;
+      // Direct switch from another fullscreen cell (no intervening exit): restore FIRST so canvasHome
+      // captures the true realm home, not the previous cell / already-mutated style.
+      if (fullscreenVoiceId) restoreCanvasHome();
+      const cell = voices.get(enteringId)?.cell; // enteringId came from a cell match, so this is set
+      // Remember where the canvas belongs, then move it into the fullscreened cell. z-index:0 keeps
+      // it BEHIND the cell's pointer-events:none chrome host (a positioned, z-auto later sibling), so
+      // the buttons still show; it stays position:fixed;inset:0 to fill the now-full-viewport cell.
+      canvasHome = { parent: canvas.parentNode, next: canvas.nextSibling, cssText: canvas.style.cssText };
+      canvas.style.zIndex = '0';
+      cell.insertBefore(canvas, cell.firstChild);
+      fullscreenVoiceId = enteringId;
+    } else if (fullscreenVoiceId) {
+      // Exit (or fullscreen moved off our cells): restore the canvas to its realm home and resume the grid.
+      restoreCanvasHome();
+    }
+    markRectsDirty();
+  };
+  if (typeof document !== 'undefined') {
+    document.addEventListener('fullscreenchange', onFullscreenChange);
+    document.addEventListener('webkitfullscreenchange', onFullscreenChange);
+  }
+
+  /** Recompute + cache every voice's GL rect (and the canvas size) in ONE layout pass. Called from the
+   *  loop only when `rectsDirty`, so the steady state does no forced layout. GL uses a bottom-left origin,
+   *  so y flips against the (fixed, full-viewport) canvas height. */
+  function refreshRects() {
+    syncCanvasSize();
+    const canvasH = lastCanvasH || canvas.clientHeight || window.innerHeight;
+    for (const voice of voices.values()) {
+      const box = voice.cell?.getBoundingClientRect();
+      voice.rect = box
+        ? { x: box.left, y: canvasH - box.bottom, width: box.width, height: box.height }
+        : null;
+    }
+    rectsDirty = false;
+  }
+
+  /** Create-or-get the CSS grid that lays the cells out (square-ish: ⌈√n⌉ columns). */
+  function ensureGrid(total) {
+    if (grid) return grid;
+    const cols = Math.ceil(Math.sqrt(total));
+    const rows = Math.ceil(total / cols);
+    grid = document.createElement('div');
+    grid.id = GRID_ID;
+    // Above the canvas, but transparent + click-through: cells exist to define viewport rects (and to
+    // anchor per-tile GUI later); the canvas underneath paints every voice.
+    grid.style.cssText = [
+      'position:fixed',
+      'inset:0',
+      'z-index:41',
+      'display:grid',
+      'gap:2px',
+      'pointer-events:none',
+      `grid-template-columns:repeat(${cols},1fr)`,
+      `grid-template-rows:repeat(${rows},1fr)`,
+    ].join(';');
+    document.body.appendChild(grid);
+    return grid;
+  }
+
+  function createCell(index, total) {
+    // Collection mode: the slot layout owns the cell DOM (a resizable slot). Borrow its element as this
+    // voice's viewport rect + GUI mount — the compositor builds no grid of its own.
+    if (cellSource) {
+      return cellSource.acquireCell(index, total);
+    }
+    const cell = document.createElement('div');
+    cell.className = 'multi-orbiter-cell';
+    cell.dataset.voiceIndex = String(index);
+    // ORB-176: the cell is this voice's own interactive input surface (pointer-events:auto), so its
+    // CameraController receives its planet drags directly and DOM hit-testing routes clicks to the right
+    // tile. The grid CONTAINER stays pointer-events:none, so the 2px inter-tile gaps still click through.
+    cell.style.cssText = 'position:relative;overflow:hidden;min-width:0;min-height:0;pointer-events:auto;';
+    ensureGrid(total).appendChild(cell);
+    return cell;
+  }
+
+  function addVoice({ voiceId, cell, controller }) {
+    if (!voiceId || !cell || !controller) return;
+    voices.set(voiceId, { cell, controller, lastW: 0, lastH: 0, rect: null });
+    cellObserver?.observe(cell); // resize of this tile → recompute its cached rect
+    markRectsDirty();
+  }
+
+  function removeVoice(voiceId) {
+    const voice = voices.get(voiceId);
+    if (!voice) return;
+    // ORB-190: if this voice is fullscreen its cell hosts the shared canvas — restore the canvas to its
+    // realm home FIRST, so removing the cell below (grid mode) can't take the canvas down with it.
+    if (voiceId === fullscreenVoiceId) restoreCanvasHome();
+    voices.delete(voiceId);
+    if (voice.cell) cellObserver?.unobserve(voice.cell);
+    markRectsDirty();
+    // Collection mode: the slot layout owns the cell DOM — leave it in place (the layout reclaims or
+    // re-fills the slot). Only the compositor-built grid removes its own cells.
+    if (cellSource) return;
+    voice.cell?.remove();
+    if (grid && grid.childElementCount === 0) {
+      grid.remove();
+      grid = null;
+    }
+  }
+
+  /** Keep the renderer's drawing buffer matched to the canvas's CSS box (handles window resize). */
+  function syncCanvasSize() {
+    const w = canvas.clientWidth || window.innerWidth;
+    const h = canvas.clientHeight || window.innerHeight;
+    if (!w || !h || (w === lastCanvasW && h === lastCanvasH)) return;
+    lastCanvasW = w;
+    lastCanvasH = h;
+    renderer.setSize(w, h, false);
+    applyPixelRatio(renderer, profile);
+  }
+
+  /** Render exactly ONE composited frame (every active voice into its cell). Also the unit the rAF
+   *  loop runs each tick. Exposed on the dev handle so a paused/hidden tab can force a frame.
+   *  three's setViewport/setScissor multiply by the renderer's pixelRatio internally, so the cached
+   *  rects are CSS px — pre-multiplying by dpr would double-scale (correct only at dpr=1, broken on retina). */
+  function renderOnce() {
+    if (disposed) return;
+    // Refresh cached rects/canvas size ONLY when layout changed (never per frame — see refreshRects).
+    if (rectsDirty) refreshRects();
+
+    // Clear the WHOLE buffer once (scissor off) so the gridline gaps and any paused/empty cell show
+    // the canvas CSS background, not stale pixels — then each voice scissor-renders into its own
+    // rect. The compositor owns the realm clear: re-assert a fully transparent clear color, because
+    // a voice's boot can leave an opaque clear on the SHARED renderer, which would paint the entire
+    // canvas over an embedding host page (the app's own full-screen canvas hides this — its CSS
+    // background is already black).
+    renderer.setClearColor(0x000000, 0);
+    renderer.setScissorTest(false);
+    renderer.clear();
+
+    const canvasW = lastCanvasW;
+    const canvasH = lastCanvasH;
+    for (const [voiceId, voice] of voices) {
+      // ORB-190: while one voice is browser-fullscreen its cell hosts the shared canvas in the top
+      // layer and fills the viewport (rect = whole canvas). Render ONLY that voice — the other cells
+      // sit behind the fullscreen backdrop, so scissor-rendering them would stamp stray tiles over it.
+      if (fullscreenVoiceId && voiceId !== fullscreenVoiceId) continue;
+      const { controller, rect } = voice;
+      if (!controller.renderActive || !rect) continue;
+      if (rect.width <= 0 || rect.height <= 0) continue;
+      // Cull stages scrolled fully off-canvas (the mobile vertical stage stack) — no point scissor-
+      // rendering a viewport with no on-screen pixels. rect is GL bottom-left; visible band is [0,canvasH].
+      if (rect.y + rect.height <= 0 || rect.y >= canvasH || rect.x + rect.width <= 0 || rect.x >= canvasW) {
+        continue;
+      }
+      // Re-aspect the camera only when the cell's box actually changed (avoids a per-frame projection rebuild).
+      if (rect.width !== voice.lastW || rect.height !== voice.lastH) {
+        controller.setViewportSize(rect.width, rect.height);
+        voice.lastW = rect.width;
+        voice.lastH = rect.height;
+      }
+      controller.renderViewport(rect);
+    }
+  }
+
+  function tick() {
+    if (disposed) return;
+    raf = requestAnimationFrame(tick);
+    renderOnce();
+  }
+
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    if (raf != null) cancelAnimationFrame(raf);
+    raf = null;
+    cellObserver?.disconnect();
+    if (typeof window !== 'undefined') {
+      window.removeEventListener('scroll', markRectsDirty, { capture: true });
+      window.removeEventListener('resize', markRectsDirty);
+    }
+    if (typeof document !== 'undefined') {
+      document.removeEventListener('fullscreenchange', onFullscreenChange);
+      document.removeEventListener('webkitfullscreenchange', onFullscreenChange);
+    }
+    // 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];
+      }
+    }
+    renderer.dispose();
+    grid?.remove();
+    grid = null;
+    canvas.remove();
+  }
+
+  raf = requestAnimationFrame(tick);
+
+  const api = {
+    renderer,
+    canvas,
+    createCell,
+    addVoice,
+    removeVoice,
+    renderOnce,
+    dispose,
+  };
+  // Dev handle: lets tooling force a composited frame when rAF is throttled (e.g. a hidden/background
+  // tab during automated checks). The HOST names it — this module invents no global of its own.
+  if (devHandleKey && typeof window !== 'undefined') {
+    window[devHandleKey] = api;
+  }
+  return api;
+}
+
+function createRenderer(canvas, profile) {
+  const renderer = new THREE.WebGLRenderer({
+    canvas,
+    antialias: profile.antialias,
+    alpha: profile.alpha,
+    preserveDrawingBuffer: profile.preserveDrawingBuffer,
+    powerPreference: profile.powerPreference,
+  });
+  applyPixelRatio(renderer, profile);
+  renderer.setSize(canvas.clientWidth || window.innerWidth, canvas.clientHeight || window.innerHeight, false);
+  renderer.outputColorSpace = THREE.SRGBColorSpace;
+  return renderer;
+}
+
+function applyPixelRatio(renderer, profile) {
+  const dpr =
+    typeof window !== 'undefined' && Number.isFinite(window.devicePixelRatio) ? window.devicePixelRatio : 1;
+  renderer.setPixelRatio(Math.min(dpr, profile.maxDevicePixelRatio));
+}

package/src/utils/dispose.js

@@ -30,6 +30,9 @@ export function disposeObject3D(obj) {
     if (child.isMesh) {
       if (child.geometry) child.geometry.dispose();
       disposeMaterial(child.material);
+      // An InstancedMesh also owns `instanceMatrix` / `instanceColor` GPU buffers, which hang off the
+      // mesh rather than the (shared) geometry — only its own dispose() frees them.
+      if (child.isInstancedMesh) child.dispose();
     }
   });
   if (obj.parent) obj.parent.remove(obj);

package/src/world/worldGLB.js

@@ -1,7 +1,7 @@
 import { loadGLB } from '../loaders/glbLoader.js';
 
-export async function makeGLB({ modelUrl, flags, retries = 3, withCredentials = false } = {}) {
+export async function makeGLB({ modelUrl, flags, retries = 3, withCredentials = false, renderer } = {}) {
   if (!modelUrl) throw new Error('modelUrl is required');
-  const obj = await loadGLB(modelUrl, { retries, applyFlags: flags, withCredentials });
+  const obj = await loadGLB(modelUrl, { retries, applyFlags: flags, withCredentials, renderer });
   return obj;
 }