entangled-worlds-orbiters-shared 2.4.2 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",
@@ -88,6 +88,8 @@
     "build:clock": "tsc -p tsconfig.build.json",
     "prepare": "npm run build:clock",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test:clock": "node --test --import tsx src/clock/*.test.ts"
+    "test:clock": "node --test --import tsx src/clock/*.test.ts",
+    "test:render": "node --test src/render/*.test.js",
+    "test": "npm run test:clock && npm run test:render"
   }
 }

package/src/render/frameBudget.js

@@ -0,0 +1,46 @@
+/**
+ * @file src/render/frameBudget.js
+ * @description "Has enough time passed to draw again?" — the whole of a frame cap, kept apart from
+ * whatever is being capped so it can be reasoned about and tested on its own.
+ *
+ * The tolerance is the part that is easy to get wrong. rAF does not deliver frames at arbitrary
+ * times; it delivers them on the display's ticks. On a 60Hz display those arrive every ~16.7ms, so a
+ * strict `elapsed >= 33.3` test rejects the frame at 33.3ms by a hair and waits for the next one at
+ * 50ms — 20fps, not the 30 that was asked for. A few milliseconds of slack lets the frame that is
+ * near enough through, and the cap lands where it was aimed.
+ */
+
+/** Frames a capped loop is allowed per second. */
+export const CAPPED_FPS = 30;
+/** Slack for rAF landing on display ticks — see the file note. */
+export const FRAME_TOLERANCE_MS = 4;
+
+/**
+ * A frame gate. Not a clock and not a scheduler: it answers one question and remembers the last time
+ * the answer was yes.
+ *
+ * @param {{ fps?: number, toleranceMs?: number }} [options]
+ * @returns {{ shouldRender(nowMs: number): boolean, reset(): void }}
+ */
+export function createFrameBudget({ fps = CAPPED_FPS, toleranceMs = FRAME_TOLERANCE_MS } = {}) {
+  const intervalMs = 1000 / (Number.isFinite(fps) && fps > 0 ? fps : CAPPED_FPS);
+  const minElapsedMs = Math.max(0, intervalMs - toleranceMs);
+  let lastAtMs = null;
+
+  return {
+    /**
+     * True when `nowMs` is far enough past the last accepted frame. Accepting records the time, so
+     * the caller must only ask when it intends to act on the answer.
+     */
+    shouldRender(nowMs) {
+      if (!Number.isFinite(nowMs)) return true;
+      if (lastAtMs !== null && nowMs - lastAtMs < minElapsedMs) return false;
+      lastAtMs = nowMs;
+      return true;
+    },
+    /** Forget the last frame, so the next question is answered as if none had been drawn. */
+    reset() {
+      lastAtMs = null;
+    },
+  };
+}

package/src/render/frameBudget.test.js

@@ -0,0 +1,62 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createFrameBudget, CAPPED_FPS } from './frameBudget.js';
+
+test('the first frame is always allowed', () => {
+  const budget = createFrameBudget();
+  assert.equal(budget.shouldRender(0), true);
+});
+
+test('a 60Hz display yields 30fps, not 20', () => {
+  // The whole reason the tolerance exists. rAF on a 60Hz display delivers at ~16.7ms intervals; a
+  // strict >= 33.3 test rejects the frame at 33.3 and waits for 50, which is 20fps.
+  const budget = createFrameBudget();
+  const accepted = [];
+  for (let i = 0; i < 12; i += 1) {
+    const now = i * (1000 / 60);
+    if (budget.shouldRender(now)) accepted.push(i);
+  }
+  // Every other frame: 0, 2, 4, ... — half of 60 is the 30 that was asked for.
+  assert.deepEqual(accepted, [0, 2, 4, 6, 8, 10]);
+});
+
+test('a 120Hz display is capped to the same rate', () => {
+  const budget = createFrameBudget();
+  let accepted = 0;
+  for (let i = 0; i < 120; i += 1) {
+    if (budget.shouldRender(i * (1000 / 120))) accepted += 1;
+  }
+  // One second of 120Hz ticks, capped at 30 — allow the boundary frame either way.
+  assert.ok(accepted >= CAPPED_FPS && accepted <= CAPPED_FPS + 1, `accepted ${accepted}`);
+});
+
+test('a rejected frame does not move the clock forward', () => {
+  // Otherwise a burst of rejected frames would keep pushing the next allowed one further out.
+  const budget = createFrameBudget();
+  budget.shouldRender(0);
+  assert.equal(budget.shouldRender(10), false);
+  assert.equal(budget.shouldRender(20), false);
+  assert.equal(budget.shouldRender(30), true);
+});
+
+test('reset makes the next frame the first one again', () => {
+  const budget = createFrameBudget();
+  budget.shouldRender(0);
+  assert.equal(budget.shouldRender(5), false);
+  budget.reset();
+  assert.equal(budget.shouldRender(5), true);
+});
+
+test('a missing timestamp never blocks a frame', () => {
+  // rAF always supplies one, but `renderOnce` can be driven by tooling that does not.
+  const budget = createFrameBudget();
+  assert.equal(budget.shouldRender(undefined), true);
+  assert.equal(budget.shouldRender(Number.NaN), true);
+});
+
+test('a custom rate is honoured', () => {
+  const budget = createFrameBudget({ fps: 10, toleranceMs: 0 });
+  assert.equal(budget.shouldRender(0), true);
+  assert.equal(budget.shouldRender(99), false);
+  assert.equal(budget.shouldRender(100), true);
+});

package/src/render/index.js

@@ -1,2 +1,3 @@
 // Render-host exports
 export { createViewportCompositor } from './viewportCompositor.js';
+export { createFrameBudget, CAPPED_FPS, FRAME_TOLERANCE_MS } from './frameBudget.js';

package/src/render/viewportCompositor.js

@@ -46,6 +46,7 @@
  * @see `devHandleKey` — the one window global it can write, opt-in.
  */
 import * as THREE from 'three';
+import { createFrameBudget } from './frameBudget.js';
 
 const GRID_ID = 'multi-orbiter-grid';
 
@@ -73,6 +74,10 @@ const CULL_SLOP_PX = 256;
  *   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.performanceMode=false] start with the realm's renderer savings on — pixel
+ *   ratio clamped to 1, shadow map off, this loop capped at 30fps. Off by default, and off means the
+ *   renderer and the cadence are exactly what they were before this option existed. Toggle it live
+ *   with `setPerformanceMode`.
  * @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.
@@ -83,6 +88,7 @@ const CULL_SLOP_PX = 256;
  *   addVoice: (voice: { voiceId: string, cell: HTMLElement, controller: object }) => void,
  *   removeVoice: (voiceId: string) => void,
  *   renderOnce: () => void,
+ *   setPerformanceMode: (enabled: boolean) => boolean,
  *   dispose: () => void,
  * }}
  */
@@ -91,8 +97,21 @@ export function createViewportCompositor({
   presentation = 'fixed-overlay',
   rendererProfile = null,
   devHandleKey = null,
+  performanceMode = false,
 } = {}) {
   const profile = { ...DEFAULT_RENDERER_PROFILE, ...(rendererProfile || {}) };
+  // The realm's renderer and the realm's loop are this module's, and they are the only things a
+  // single voice cannot change for itself: pixel ratio, shadow map and frame rate are one per realm,
+  // so a voice reaching for them would be deciding for its siblings. When the host says the realm is
+  // in performance mode, this is where that decision is made once, for all of them.
+  //
+  // Off is the default and off means untouched — a host that never mentions it (the feed embeds)
+  // gets exactly the renderer and the cadence it got before this existed.
+  let performanceOn = Boolean(performanceMode);
+  // What the realm's shadow map was before performance mode touched it, so turning the mode off puts
+  // the host's own choice back rather than asserting a default over it.
+  let baseShadowMapEnabled = null;
+  const frameBudget = createFrameBudget();
   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.
@@ -107,7 +126,30 @@ export function createViewportCompositor({
     document.body.appendChild(canvas);
   }
 
-  const renderer = createRenderer(canvas, profile);
+  /**
+   * The renderer settings actually in force. Performance mode overrides the host's profile rather
+   * than replacing it, so whatever the host asked for comes back untouched when the mode goes off.
+   *
+   * `antialias` is deliberately not in here: it is fixed when the WebGL context is created, so
+   * turning it off would cost the host its antialiasing for the rest of the session the moment the
+   * mode was switched back on. The saving that IS live is the pixel ratio, and at dpr 2 that is
+   * three quarters of the fragments.
+   */
+  function effectiveProfile() {
+    return performanceOn ? { ...profile, maxDevicePixelRatio: 1 } : profile;
+  }
+
+  /** Re-assert the realm-wide knobs. Called at construction and whenever the mode changes. */
+  function applyRealmRendererProfile() {
+    applyPixelRatio(renderer, effectiveProfile());
+    renderer.shadowMap.enabled = performanceOn ? false : baseShadowMapEnabled;
+  }
+
+  const renderer = createRenderer(canvas, effectiveProfile());
+  // Read before the mode has touched anything, so leaving performance mode restores the host's own
+  // setting instead of asserting three's default over it.
+  baseShadowMapEnabled = renderer.shadowMap.enabled;
+  if (performanceOn) renderer.shadowMap.enabled = false;
 
   /** 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
@@ -236,7 +278,9 @@ export function createViewportCompositor({
         lastCanvasW = maxW;
         lastCanvasH = maxH;
         renderer.setSize(maxW, maxH, false);
-        applyPixelRatio(renderer, profile);
+        // The EFFECTIVE profile, not the host's: a cell growing must not quietly hand the realm its
+        // full pixel ratio back while performance mode is still on.
+        applyPixelRatio(renderer, effectiveProfile());
       }
       rectsDirty = false;
       return;
@@ -349,7 +393,10 @@ export function createViewportCompositor({
     lastCanvasW = w;
     lastCanvasH = h;
     renderer.setSize(w, h, false);
-    applyPixelRatio(renderer, profile);
+    // The EFFECTIVE profile, not the host's. A window resize — or dragging the window to a display
+    // with a different pixel ratio — must not restore full-resolution fragments while performance
+    // mode is still on, which is what re-applying the raw profile here would do.
+    applyPixelRatio(renderer, effectiveProfile());
   }
 
   /** Fixed-overlay frame: clear the displayed canvas, then scissor-render every visible voice at its
@@ -458,12 +505,36 @@ export function createViewportCompositor({
     }
   }
 
-  function tick() {
+  function tick(nowMs) {
     if (disposed) return;
     raf = requestAnimationFrame(tick);
+    // The cap belongs HERE, to the realm's own loop — never to a voice declining to draw inside
+    // `renderViewport`. A composited frame clears the whole canvas and then scissor-renders each cell
+    // into it, so a voice that skipped its draw would leave a black hole where its cell is and flash
+    // at half the realm's rate. Skipping the whole frame instead leaves every cell showing the last
+    // frame that was drawn — together, which is the only way a shared canvas can be consistent.
+    if (performanceOn && !frameBudget.shouldRender(nowMs)) return;
     renderOnce();
   }
 
+  /**
+   * Turn the realm's performance mode on or off, live. Clamps the realm pixel ratio to 1, turns the
+   * shadow map off and caps this loop at 30fps while on; puts all three back when off.
+   *
+   * @param {boolean} enabled
+   * @returns {boolean} whether the mode actually changed
+   */
+  function setPerformanceMode(enabled) {
+    const next = Boolean(enabled);
+    if (disposed || next === performanceOn) return false;
+    performanceOn = next;
+    applyRealmRendererProfile();
+    // The next frame is the first of the new cadence — it must not be judged against a frame drawn
+    // under the old one.
+    frameBudget.reset();
+    return true;
+  }
+
   function dispose() {
     if (disposed) return;
     disposed = true;
@@ -500,6 +571,7 @@ export function createViewportCompositor({
     addVoice,
     removeVoice,
     renderOnce,
+    setPerformanceMode,
     dispose,
   };
   // Dev handle: lets tooling force a composited frame when rAF is throttled (e.g. a hidden/background