entangled-worlds-orbiters-shared 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.0.0",
+  "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/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));
+}