entangled-worlds-orbiters-shared 2.3.0 → 2.4.1

package/README.md

@@ -6,7 +6,6 @@ A shared library containing core components for 3D world rendering, moons system
 
 - **World System**: Core world rendering with textured spheres, normal materials, GLB models, and cloud shells
 - **Moons System**: Orbital moon generation and management
-- **Arrow UI**: Reusable UI component system based on lil-gui
 - **Loaders**: Texture, GLB, and cubemap loading utilities
 - **Core Rendering**: Lighting, Fresnel effects, and material utilities
 - **Configuration**: Texture and configuration management system
@@ -38,7 +37,6 @@ npm link entangled-worlds-orbiters-shared
 // Import specific modules
 import { WorldManager } from 'entangled-worlds-orbiters-shared/world';
 import { MoonsManager } from 'entangled-worlds-orbiters-shared/moons';
-import { GUI } from 'entangled-worlds-orbiters-shared/arrow-ui';
 
 // Or import everything
 import * as EntangledWorlds from 'entangled-worlds-orbiters-shared';
@@ -57,10 +55,6 @@ import * as EntangledWorlds from 'entangled-worlds-orbiters-shared';
 - `MoonsManager` - Moons orchestration
 - `moonsGeneration` - Moon generation logic
 
-### Arrow UI
-- Complete UI component system based on lil-gui
-- Controllers for boolean, color, function, number, option, and string inputs
-
 ### Loaders
 - `cubeMapLoader` - Skybox loading
 - `glbLoader` - GLB loading utilities
@@ -129,6 +123,4 @@ npm install three three-stdlib
 
 ## License
 
-[MIT](LICENSE) © Plantasia Space.
-
-`src/arrow-ui/` is derived from [lil-gui](https://github.com/georgealways/lil-gui) (MIT) — see [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).
+[MIT](LICENSE) © Plantasia Space.

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.3.0",
+  "version": "2.4.1",
   "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/config/textureConfig.js

@@ -94,7 +94,7 @@ export async function loadTextureConfig(configUrl = null, useCache = true) {
  * Get texture options for a specific category (clouds, moons, etc.)
  * @param {string} category - Texture category (clouds, moons, skyboxes)
  * @param {Object} config - Optional pre-loaded config object
- * @returns {Promise<Object>} Options object suitable for lil-gui dropdowns
+ * @returns {Promise<Object>} Options object suitable for dropdown option lists
  */
 export async function getTextureOptions(category, config = null) {
   const textureConfig = config || await loadTextureConfig();

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/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,14 +14,33 @@
  *   - 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 `devHandleKey` — the one window global it can write, opt-in.
@@ -39,11 +58,19 @@ 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 {string|null} [opts.devHandleKey=null] when set, publish the returned api on
@@ -61,55 +88,72 @@ const DEFAULT_RENDERER_PROFILE = {
  */
 export function createViewportCompositor({
   cellSource = null,
+  presentation = 'fixed-overlay',
   rendererProfile = null,
   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);
 
-  /** 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 = () =>
@@ -137,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();
@@ -159,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()) {
@@ -206,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;';
@@ -214,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();
   }
@@ -224,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.
@@ -240,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;
@@ -251,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
@@ -273,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;
@@ -295,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);
@@ -317,6 +480,7 @@ 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' && devHandleKey && window[devHandleKey]?.renderer === renderer) {
       delete window[devHandleKey];

package/src/world/worldTexture.js

@@ -296,6 +296,9 @@ export async function makeSphere({
 
   if (flags) applyFlagsToMaterial(material, flags);
   const mesh = new THREE.Mesh(meshGeometry, material);
+  // Named so consumers can find the planet body by name (mirrors the
+  // normal-mode body's `worldNormalSphere`) — e.g. to modulate its material.
+  mesh.name = 'worldTextureSphere';
   mesh.position.set(0, 0, 0);
 
   // NEW: add cloud shell before glow

package/THIRD-PARTY-NOTICES.md

@@ -1,5 +0,0 @@
-# Third-party notices
-
-## Arrow UI (`src/arrow-ui/`)
-
-Derived from [lil-gui](https://github.com/georgealways/lil-gui) by George Michael Brower, licensed under the [MIT License](https://github.com/georgealways/lil-gui/blob/master/LICENSE). The controllers and GUI core have been adapted for the Entangled Worlds / Orbiters apps (external stylesheet loading, custom controllers and behavior); the original license applies to the derived portions alongside this project's MIT license.