entangled-worlds-orbiters-shared 2.2.0 → 2.4.0

package/dist/clock/sync.js

@@ -1,5 +1,5 @@
-// BeatTimeline — leaderless shared beat-timeline sync (conceptually based on Ableton Link). Design doc
-// planning/shared-timeline/ORB-102-beat-timeline-sync.md. Replaces the authority/conductor sync model.
+// BeatTimeline — leaderless shared beat-timeline sync (conceptually based on Ableton Link). Design doc:
+// see this package's clock design docs. Replaces the authority/conductor sync model.
 //
 // What's shared: a BEAT TIMELINE (tempo + a beat<->sessionTime bijection). NOT a transport position.
 //   - Tempo is LEADERLESS: any peer proposes; each adopts the newest proposal (last-writer-wins);

package/dist/clock/track-metadata.js

@@ -2,7 +2,7 @@
 // (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.
+// startSec: gridSec, bpm }] })`. Promoted out of the orbiters app so EW reuses it verbatim.
 function toPositiveNumber(value) {
     const numeric = Number(value);
     return Number.isFinite(numeric) && numeric > 0 ? numeric : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.2.0",
+  "version": "2.4.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/clock/sync.ts

@@ -1,5 +1,5 @@
-// BeatTimeline — leaderless shared beat-timeline sync (conceptually based on Ableton Link). Design doc
-// planning/shared-timeline/ORB-102-beat-timeline-sync.md. Replaces the authority/conductor sync model.
+// BeatTimeline — leaderless shared beat-timeline sync (conceptually based on Ableton Link). Design doc:
+// see this package's clock design docs. Replaces the authority/conductor sync model.
 //
 // What's shared: a BEAT TIMELINE (tempo + a beat<->sessionTime bijection). NOT a transport position.
 //   - Tempo is LEADERLESS: any peer proposes; each adopts the newest proposal (last-writer-wins);

package/src/clock/track-metadata.ts

@@ -2,7 +2,7 @@
 // (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.
+// startSec: gridSec, bpm }] })`. Promoted out of the orbiters app so EW reuses it verbatim.
 
 /**
  * The slice of a track's data these resolvers read (tempo here; meter in `./clock/meter`). Every field

package/src/core/lights.js

@@ -3,7 +3,7 @@ import * as THREE from 'three';
 /**
  * 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
+ * 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

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

@@ -1,6 +1,6 @@
 /**
  * @file src/render/viewportCompositor.js
- * @description ORB-128 — a multi-view render host: ONE canvas, ONE `WebGLRenderer`, ONE rAF loop.
+ * @description A multi-view render host: ONE `WebGLRenderer`, ONE rAF loop, many cells.
  * 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
@@ -14,17 +14,36 @@
  *   - 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.
  *
+ * ## Presentation modes
+ * How rendered pixels reach the screen is a per-host choice (`presentation` option):
+ *
+ * - `'fixed-overlay'` (default): the WebGL canvas itself is displayed — appended to `document.body`,
+ *   `position:fixed;inset:0`, each voice scissor-rendered at its cell's on-screen rect. Right for
+ *   full-screen stage layouts the compositor was built for. Its structural limit: cell positions are
+ *   re-read on the main thread each frame, while the page scrolls on the compositor thread — so
+ *   inside a scrolling document the painted rect trails the DOM by a frame or more (the "viewport
+ *   detaches from the page" symptom). Don't use it under scrolling content.
+ *
+ * - `'per-cell'`: the WebGL canvas stays detached and is only a render source. Every voice gets a
+ *   compositor-owned 2D canvas inside its cell (`position:absolute;inset:0`), and each frame the
+ *   voice is rendered at the buffer's origin and blitted into that canvas (`drawImage`, a GPU-side
+ *   copy). The DOM owns the pixels' position, so cells scroll glued to the page — scroll can never
+ *   detach them, no matter how the rAF loop is scheduled. One WebGL context still serves
+ *   every voice, so the KTX2 single-context constraint holds. Requires each cell to be a positioned
+ *   element (the compositor makes a `static` cell `relative`); browser-fullscreen needs no canvas
+ *   reparenting in this mode — the cell brings its own canvas into the top layer.
+ *
  * ## 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`.
+ * - `'fixed-overlay'` only: the canvas is appended to `document.body`, `position:fixed;inset:0`,
+ *   `z-index:40`, opaque black CSS background; browser-fullscreen on a registered CELL reparents the
+ *   shared canvas into that cell. The host must not move the canvas itself.
+ * - 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.
+ * @see `devHandleKey` — the one window global it can write, opt-in.
  */
 import * as THREE from 'three';
 
@@ -39,18 +58,21 @@ const DEFAULT_RENDERER_PROFILE = {
   maxDevicePixelRatio: 1.5,
 };
 
+/** `'per-cell'`: how far past the viewport (CSS px) a cell still renders. Cull geometry is a cached
+ *  rect that can be a frame stale during fast scrolls — the slop keeps a cell entering the viewport
+ *  from flashing empty on that frame. */
+const CULL_SLOP_PX = 256;
+
 /**
  * @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 {'fixed-overlay'|'per-cell'} [opts.presentation='fixed-overlay'] how pixels reach the
+ *   screen — the displayed fixed canvas (full-screen stage layouts) or a per-cell blit canvas the
+ *   DOM positions (cells inside scrolling content). See the module doc.
  * @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.
@@ -66,62 +88,72 @@ const DEFAULT_RENDERER_PROFILE = {
  */
 export function createViewportCompositor({
   cellSource = null,
+  presentation = 'fixed-overlay',
   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 perCell = presentation === 'per-cell';
+  // The one WebGL canvas. Fixed-overlay: full-bleed behind the grid, it owns the pixels for ALL
+  // voices. Per-cell: never enters the DOM — a render source the per-cell canvases copy from.
   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);
+  if (!perCell) {
+    // 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 } */
+  /** voiceId → { cell, controller, lastW, lastH, rect, blit } — `rect` is the GL draw rect
+   *  (fixed-overlay) or the viewport-relative cull/size box (per-cell); `blit` is the per-cell
+   *  presentation canvas + its 2d context (per-cell only). */
   const voices = new Map();
   let grid = null;
   let raf = null;
   let disposed = false;
   let lastCanvasW = 0;
   let lastCanvasH = 0;
+  let viewportH = 0; // per-cell cull band (CSS px), refreshed with the rects
+  let viewportW = 0;
 
-  // ORB-162: the rAF loop must NOT read layout every frame. `getBoundingClientRect()` / `clientHeight`
+  // 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.
+  // (Per-cell mode keeps the same cache: there the rect only culls and sizes — a stale frame merely
+  // renders one extra cell; it can't misplace pixels, the DOM owns their position.)
   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.
+  // The BODY observer catches layout shifts with no scroll/resize event at all: content above a cell
+  // expanding or collapsing moves the cell (and changes the body box) while every cell keeps its own
+  // size — without it, per-cell culling could keep skipping a voice that shifted into the viewport.
   if (typeof window !== 'undefined') {
     window.addEventListener('scroll', markRectsDirty, { passive: true, capture: true });
     window.addEventListener('resize', markRectsDirty);
   }
+  if (typeof document !== 'undefined' && document.body) cellObserver?.observe(document.body);
 
-  // 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.
+  // Browser-fullscreen ownership for a voice. Fixed-overlay: 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. Per-cell: the cell's own canvas rides into the top
+  // layer with it — no reparenting, only the solo-render (and the buffer grows to the cell's new
+  // size through the normal resize path).
   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 = () =>
@@ -149,6 +181,13 @@ export function createViewportCompositor({
     const enteringId = voiceIdForCell(fullscreenElement());
     if (enteringId) {
       if (fullscreenVoiceId === enteringId) return;
+      if (perCell) {
+        // The fullscreened cell carries its own presentation canvas into the top layer; solo-render
+        // is all the compositor contributes here.
+        fullscreenVoiceId = enteringId;
+        markRectsDirty();
+        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();
@@ -171,10 +210,37 @@ export function createViewportCompositor({
     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. */
+  /** Recompute + cache every voice's rect (and the buffer size) in ONE layout pass. Called from the
+   *  loop only when `rectsDirty`, so the steady state does no forced layout.
+   *  Fixed-overlay: rect = GL draw rect on the displayed canvas (bottom-left origin, so y flips
+   *  against the fixed full-viewport canvas height). Per-cell: rect = the cell's viewport-relative
+   *  box (top-left origin) — used only to cull and size; the buffer grows (never shrinks) to hold
+   *  the largest cell, since every voice renders at the buffer origin. */
   function refreshRects() {
+    if (perCell) {
+      viewportW = window.innerWidth;
+      viewportH = window.innerHeight;
+      let maxW = lastCanvasW;
+      let maxH = lastCanvasH;
+      for (const voice of voices.values()) {
+        const box = voice.cell?.getBoundingClientRect();
+        voice.rect = box
+          ? { x: box.left, y: box.top, width: box.width, height: box.height }
+          : null;
+        if (box) {
+          if (box.width > maxW) maxW = Math.ceil(box.width);
+          if (box.height > maxH) maxH = Math.ceil(box.height);
+        }
+      }
+      if (maxW > lastCanvasW || maxH > lastCanvasH) {
+        lastCanvasW = maxW;
+        lastCanvasH = maxH;
+        renderer.setSize(maxW, maxH, false);
+        applyPixelRatio(renderer, profile);
+      }
+      rectsDirty = false;
+      return;
+    }
     syncCanvasSize();
     const canvasH = lastCanvasH || canvas.clientHeight || window.innerHeight;
     for (const voice of voices.values()) {
@@ -218,7 +284,7 @@ export function createViewportCompositor({
     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
+    // 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;';
@@ -226,9 +292,29 @@ export function createViewportCompositor({
     return cell;
   }
 
+  /** Per-cell mode: the compositor-owned presentation canvas living INSIDE a voice's cell. The DOM
+   *  positions it (absolute, inset:0), so it scrolls with the page on the compositor thread — the
+   *  whole point of the mode. First child + z-index:0 keeps it under the cell's chrome; pointer
+   *  events pass through to the cell, which owns the voice's camera input binding. */
+  function createBlitCanvas(cell) {
+    // An absolutely-positioned child anchors to the nearest positioned ancestor — make sure that's
+    // the cell itself, not something above it.
+    if (typeof getComputedStyle === 'function' && getComputedStyle(cell).position === 'static') {
+      cell.style.position = 'relative';
+    }
+    const el = document.createElement('canvas');
+    el.className = 'multi-orbiter-cell-canvas';
+    el.style.cssText =
+      'position:absolute;inset:0;width:100%;height:100%;display:block;pointer-events:none;z-index:0;';
+    cell.insertBefore(el, cell.firstChild);
+    const ctx = el.getContext('2d');
+    return { el, ctx };
+  }
+
   function addVoice({ voiceId, cell, controller }) {
     if (!voiceId || !cell || !controller) return;
-    voices.set(voiceId, { cell, controller, lastW: 0, lastH: 0, rect: null });
+    const blit = perCell ? createBlitCanvas(cell) : null;
+    voices.set(voiceId, { cell, controller, lastW: 0, lastH: 0, rect: null, blit });
     cellObserver?.observe(cell); // resize of this tile → recompute its cached rect
     markRectsDirty();
   }
@@ -236,11 +322,13 @@ export function createViewportCompositor({
   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
+    // 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);
+    // The blit canvas is compositor-owned even when the HOST owns the cell — always take it out.
+    voice.blit?.el.remove();
     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.
@@ -252,7 +340,8 @@ export function createViewportCompositor({
     }
   }
 
-  /** Keep the renderer's drawing buffer matched to the canvas's CSS box (handles window resize). */
+  /** Keep the renderer's drawing buffer matched to the canvas's CSS box (handles window resize).
+   *  Fixed-overlay only — per-cell sizes the buffer to the largest cell in `refreshRects`. */
   function syncCanvasSize() {
     const w = canvas.clientWidth || window.innerWidth;
     const h = canvas.clientHeight || window.innerHeight;
@@ -263,15 +352,9 @@ export function createViewportCompositor({
     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();
-
+  /** Fixed-overlay frame: clear the displayed canvas, then scissor-render every visible voice at its
+   *  on-screen rect. */
+  function renderOverlayFrame() {
     // 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
@@ -285,7 +368,7 @@ export function createViewportCompositor({
     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
+      // 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;
@@ -307,6 +390,74 @@ export function createViewportCompositor({
     }
   }
 
+  /** Per-cell frame: render each visible voice at the buffer ORIGIN, then blit that region into the
+   *  voice's own canvas. Every voice reuses the same origin region (cleared per voice), so the
+   *  buffer only ever needs to hold the largest single cell. The blit is `drawImage` straight from
+   *  the WebGL canvas — same-task with the render, so `preserveDrawingBuffer:false` stays safe. */
+  function renderPerCellFrame() {
+    renderer.setClearColor(0x000000, 0);
+    const dpr = renderer.getPixelRatio();
+    // The blit reads DEVICE pixels; the canvas attribute is the buffer's true height (three floors
+    // internally — recomputing from CSS px could drift by a pixel).
+    const bufH = canvas.height;
+    for (const [voiceId, voice] of voices) {
+      if (fullscreenVoiceId && voiceId !== fullscreenVoiceId) continue;
+      const { controller, rect, blit } = voice;
+      if (!controller.renderActive || !rect || !blit?.ctx) continue;
+      const { width, height } = rect;
+      if (width <= 0 || height <= 0) continue;
+      // Cull cells fully outside the viewport (+slop: the cached rect may be a frame stale during a
+      // fast scroll — better one extra render than a blank cell entering the screen).
+      if (
+        rect.y + height <= -CULL_SLOP_PX ||
+        rect.y >= viewportH + CULL_SLOP_PX ||
+        rect.x + width <= -CULL_SLOP_PX ||
+        rect.x >= viewportW + CULL_SLOP_PX
+      ) {
+        continue;
+      }
+      // Floor to match three's own device-px math (setViewport/setScissor floor after the dpr
+      // multiply) — rounding UP would blit a stale 1px edge the render never touched.
+      const sw = Math.floor(width * dpr);
+      const sh = Math.floor(height * dpr);
+      if (width !== voice.lastW || height !== voice.lastH) {
+        controller.setViewportSize(width, height);
+        voice.lastW = width;
+        voice.lastH = height;
+      }
+      // Setting a canvas's backing-store size clears it, so only do it on actual change.
+      if (blit.el.width !== sw || blit.el.height !== sh) {
+        blit.el.width = sw;
+        blit.el.height = sh;
+      }
+      // Clear this voice's region (previous voice's pixels live there), then let it render.
+      renderer.setViewport(0, 0, width, height);
+      renderer.setScissor(0, 0, width, height);
+      renderer.setScissorTest(true);
+      renderer.clear();
+      controller.renderViewport({ x: 0, y: 0, width, height });
+      // GL origin is bottom-left: the region sits at the BOTTOM of the buffer in 2D (top-left) coords.
+      // 'copy' replaces the destination (alpha included) — no clearRect pass needed.
+      blit.ctx.globalCompositeOperation = 'copy';
+      blit.ctx.drawImage(canvas, 0, bufH - sh, sw, sh, 0, 0, sw, sh);
+    }
+  }
+
+  /** 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();
+    if (perCell) {
+      renderPerCellFrame();
+    } else {
+      renderOverlayFrame();
+    }
+  }
+
   function tick() {
     if (disposed) return;
     raf = requestAnimationFrame(tick);
@@ -329,12 +480,10 @@ export function createViewportCompositor({
     }
     // If disposed while a voice was fullscreen, put the canvas style back before `canvas.remove()`.
     restoreCanvasHome();
+    for (const voice of voices.values()) voice.blit?.el.remove();
     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/worldManager.js

@@ -7,8 +7,8 @@ export class WorldManager {
   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
@@ -29,7 +29,7 @@ export class WorldManager {
     if (!this.externalTick || !this.current) return;
     const updater = this.current.userData?.update;
     if (typeof updater !== 'function') return;
-    const renderer = this.renderer ?? (typeof window !== 'undefined' ? window.__EW_RENDERER : null);
+    const renderer = this.renderer;
     if (!renderer) return;
     try {
       updater(renderer, timeSec);
@@ -60,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)) {

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