entangled-worlds-orbiters-shared 2.4.2 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.4.2",
+  "version": "2.6.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",
@@ -8,6 +8,7 @@
   "exports": {
     ".": "./src/index.js",
     "./world": "./src/world/index.js",
+    "./minimal": "./src/minimal/index.js",
     "./moons": "./src/moons/index.js",
     "./loaders": "./src/loaders/index.js",
     "./render": "./src/render/index.js",
@@ -42,6 +43,7 @@
   "files": [
     "src/**/*",
     "!src/**/*.test.ts",
+    "!src/**/*.test.js",
     "dist/**/*",
     "public/**/*",
     "README.md",
@@ -88,6 +90,10 @@
     "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:minimal": "node --test src/minimal/*.test.js",
+    "test": "npm run test:clock && npm run test:render && npm run test:minimal && npm run test:moons",
+    "test:moons": "node --test src/moons/*.test.js"
   }
 }

package/src/minimal/index.js

@@ -0,0 +1,26 @@
+/**
+ * The minimal ("performance mode") look: one cheap lit sphere, one key light, a weak ambient fill,
+ * and nothing else — no texture, no halo, no cloud shell, no skybox.
+ *
+ * Its own entry point rather than a few more names on `./world`, because both consumers want exactly
+ * this and nothing around it: the Orbiters renderer and the Entangled Worlds editor's performance
+ * preview. Keeping it separate means importing the look never drags in the texture/GLB/cloud loaders
+ * that the look exists to avoid.
+ */
+export {
+  createMinimalWorld,
+  resolvePlanetColor,
+  MINIMAL_WORLD_MODE,
+  MINIMAL_MATERIAL_KINDS,
+  MINIMAL_PLANET_COLOR_HEX,
+} from './minimalWorld.js';
+
+export {
+  applyMinimalLighting,
+  removeMinimalLighting,
+  updateMinimalKeyLight,
+  takeSceneLights,
+  DEFAULT_LIGHT_NAMES,
+  MINIMAL_LIGHT_NAME,
+  MINIMAL_FILL_NAME,
+} from './minimalLighting.js';

package/src/minimal/minimalLighting.js

@@ -0,0 +1,137 @@
+/**
+ * @file src/minimal/minimalLighting.js
+ * @description The one light the minimal look keeps.
+ *
+ * Shared for the same reason as `minimalWorld.js`, and more sharply: lighting is what makes two
+ * renders of the same world look like the same world. The editor's performance preview and the
+ * Orbiters render MUST take their key light, their fill and their restore behaviour from this one
+ * module, or an author would tune a world against lighting the public never sees.
+ *
+ * Minimal is not an unlit scene. The moons are a lit material, so a scene with no lights renders them
+ * as black discs, and the planet needs a light for its shape to be legible at all. What it does not
+ * need is the world's usual pair — a hemisphere and an ambient, both white-on-white at full strength,
+ * which light every surface identically and are themselves part of why a sphere reads as a flat disc.
+ *
+ * So: exactly one directional light, no shadows. Its colour and direction come from the world's own
+ * authored lighting where the world provides them, which is how a minimal scene still carries some of
+ * the world's identity without loading anything.
+ */
+import * as THREE from 'three';
+
+/** The shared default lights, by the names the shared package gives them. */
+export const DEFAULT_LIGHT_NAMES = Object.freeze(['ew_HemisphereLight', 'ew_AmbientLight']);
+/** The single light the minimal look keeps. */
+export const MINIMAL_LIGHT_NAME = 'orb_MinimalKeyLight';
+/** The weak ambient that keeps the unlit side from going pure black. */
+export const MINIMAL_FILL_NAME = 'orb_MinimalFillLight';
+
+const DEFAULT_INTENSITY = 1.8;
+const DEFAULT_DIRECTION = Object.freeze({ x: 1, y: 0.6, z: 1 });
+/**
+ * The fill. A single directional light alone puts the unlit side at pure black, which cuts the
+ * silhouette in half instead of rounding it — the terminator reads as a hard edge rather than a
+ * curve. A weak ambient lifts that side just enough for the shape to close.
+ *
+ * Ambient is the cheapest light there is: a constant added per fragment, no direction, no attenuation,
+ * no extra pass, and no shadow map. It is the right way to soften this and the only one worth its cost.
+ */
+const FILL_INTENSITY = 0.55;
+
+function removeLightByName(scene, name) {
+  const light = scene.getObjectByName(name);
+  if (!light) return;
+  scene.remove(light);
+  // Lights hold no geometry or texture, but they do hold a shadow map + camera once shadows have
+  // been on, and `dispose` is what releases it.
+  light.dispose?.();
+}
+
+/**
+ * Detach the world's default lights and hand them back — WITHOUT disposing them.
+ *
+ * They carry the world's authored colour, direction and intensities, and nothing re-applies those
+ * when the mode is switched off inside Studio. Keeping the objects means leaving minimal restores
+ * exactly what the world had, rather than a generic pair at 1.0/1.0.
+ *
+ * @param {THREE.Scene} scene
+ * @returns {THREE.Light[]} the detached lights, in the order they were found
+ */
+export function takeSceneLights(scene) {
+  if (!scene) return [];
+  const taken = [];
+  DEFAULT_LIGHT_NAMES.forEach((name) => {
+    const light = scene.getObjectByName(name);
+    if (!light) return;
+    scene.remove(light);
+    taken.push(light);
+  });
+  return taken;
+}
+
+/**
+ * Add the key light plus a weak ambient fill. Idempotent. Two lights, both of the cheapest kinds,
+ * and neither casting a shadow.
+ *
+ * The world's own lights are NOT removed here — that is `takeSceneLights`, so the caller decides
+ * whether it is keeping them to put back.
+ */
+export function applyMinimalLighting(scene) {
+  if (!scene) return null;
+
+  if (!scene.getObjectByName(MINIMAL_FILL_NAME)) {
+    const fill = new THREE.AmbientLight(0xffffff, FILL_INTENSITY);
+    fill.name = MINIMAL_FILL_NAME;
+    scene.add(fill);
+  }
+
+  const existing = scene.getObjectByName(MINIMAL_LIGHT_NAME);
+  if (existing) return existing;
+  const key = new THREE.DirectionalLight(0xffffff, DEFAULT_INTENSITY);
+  key.position.set(DEFAULT_DIRECTION.x, DEFAULT_DIRECTION.y, DEFAULT_DIRECTION.z);
+  key.castShadow = false;
+  key.name = MINIMAL_LIGHT_NAME;
+  scene.add(key);
+  return key;
+}
+
+export function removeMinimalLighting(scene) {
+  if (!scene) return;
+  removeLightByName(scene, MINIMAL_LIGHT_NAME);
+  removeLightByName(scene, MINIMAL_FILL_NAME);
+}
+
+/**
+ * Point the key light the way the world says its light points.
+ *
+ * DIRECTION only — the world's light COLOUR is deliberately not applied. Minimal is a monochrome
+ * look, and a world that authored a strongly tinted light would drag the whole scene into that hue
+ * and break the consistency the mode is for. Direction gives the shape somewhere to be lit from,
+ * which is what actually varies usefully between worlds.
+ *
+ * A no-op when the key light is not in the scene, so a full-profile world load never has to check
+ * which mode it is in.
+ *
+ * @param {THREE.Scene} scene
+ * @param {{ lightDirection?: object, direction?: object,
+ *           diffuseIntensity?: number, diffuse?: number }} lighting
+ */
+export function updateMinimalKeyLight(scene, lighting = {}) {
+  const key = scene?.getObjectByName(MINIMAL_LIGHT_NAME);
+  if (!key) return;
+
+  const direction = lighting.lightDirection ?? lighting.direction;
+  if (direction && typeof direction === 'object') {
+    const x = Number.isFinite(direction.x) ? direction.x : DEFAULT_DIRECTION.x;
+    const y = Number.isFinite(direction.y) ? direction.y : DEFAULT_DIRECTION.y;
+    const z = Number.isFinite(direction.z) ? direction.z : DEFAULT_DIRECTION.z;
+    // A direction of all zeros would put the light inside the planet and black the scene out.
+    if (x !== 0 || y !== 0 || z !== 0) key.position.set(x, y, z);
+  }
+
+  const intensity = lighting.diffuseIntensity ?? lighting.diffuse;
+  if (Number.isFinite(intensity) && intensity > 0) {
+    // The world's intensities are authored against TWO lights at full strength; this is one, so it
+    // keeps the default as a floor rather than dimming the only light in the scene.
+    key.intensity = Math.max(DEFAULT_INTENSITY, intensity);
+  }
+}

package/src/minimal/minimalWorld.js

@@ -0,0 +1,179 @@
+/**
+ * @file src/minimal/minimalWorld.js
+ * @description The planet as performance mode draws it: one sphere, one cheap lit material, no
+ * texture, no halo, no cloud shell.
+ *
+ * Shared, not Orbiters-local, because TWO surfaces draw this look: Orbiters renders it in
+ * performance mode, and the Entangled Worlds editor previews it so an author can see what they are
+ * authoring. If each kept its own copy the preview would drift from the render and start lying about
+ * what the public will see — the one failure this module exists to prevent.
+ *
+ * Why this exists rather than reusing the shared normal-material sphere: `MeshNormalMaterial` colours
+ * each pixel by the direction the surface faces, which is a gradient, not shading. It cannot respond
+ * to a light at all — so however many lights the scene has, the planet reads as a flat disc while the
+ * moons beside it (a lit material) read as spheres. A lit material is what makes the shape legible.
+ *
+ * The cost of that is close to nothing. Lambert is one dot product per fragment against a single
+ * directional light — no specular, no roughness, no environment lookup, no texture fetch. What it
+ * costs over the normal material is far less than what a texture, a halo or a cloud shell cost, all
+ * of which this mode drops.
+ *
+ * `kind` exists so the options can be compared on real hardware without a rebuild
+ * (`?minimalMaterial=lambert|phong|normal`), and so the choice is one line if a cheaper one wins.
+ */
+import * as THREE from 'three';
+
+export const MINIMAL_WORLD_MODE = 90;
+
+/**
+ * The minimal planet's colour when the world names none.
+ *
+ * Deliberately neutral, and deliberately NOT read from the `--color*` theme variables: those are the
+ * app chrome's palette (white, black, the UI accent), not the world's, so reading them would paint
+ * every planet the same interface colour. A world that DOES name a colour is honoured — see
+ * `resolvePlanetColor` — and what carries the identity of one that does not is its own authored
+ * light (`minimalLighting.js`).
+ */
+const DEFAULT_PLANET_COLOR = 0xb8c2cc;
+
+/**
+ * The same neutral as a CSS hex, for surfaces that have to SHOW it rather than render it — the
+ * editor's colour swatch displays this when a world has authored nothing, so the control never
+ * claims a colour the renderer is not actually using. Exported so there is one constant, not an
+ * editor copy that has to be kept equal to this one.
+ */
+export const MINIMAL_PLANET_COLOR_HEX = `#${DEFAULT_PLANET_COLOR.toString(16).padStart(6, '0')}`;
+
+/**
+ * The floor an authored colour is lifted to, as HSL lightness in the sRGB the author picked in.
+ *
+ * Minimal drops the skybox, so the planet is drawn against black (`SceneSpace` sets the background to
+ * BLACK when there is no cubemap). The scene's whole light budget is one key at 1.8 plus a 0.55
+ * ambient fill, so a near-black body reflects almost nothing and disappears into that background
+ * entirely — not a dark planet, no planet. Lifting the lightness while keeping hue and saturation
+ * means a world that authored near-black still reads as its own hue, just at the darkest level that
+ * is still a visible sphere.
+ *
+ * 0.10 sits below anything an author would recognise as a colour rather than as black: `#101030`, a
+ * genuinely dark navy, measures 0.125 and passes through untouched.
+ */
+const MIN_PLANET_LIGHTNESS = 0.1;
+
+export const MINIMAL_MATERIAL_KINDS = Object.freeze(['lambert', 'phong', 'normal']);
+
+/**
+ * Segment counts used only when the world names none.
+ *
+ * The world's OWN resolution is never overridden, including when it is very low. A low-segment world
+ * is a faceted world on purpose — that faceting is the world's shape, not a defect to be smoothed
+ * away — and performance mode changes what is DRAWN, never the world's configuration.
+ */
+const FALLBACK_WIDTH_SEGMENTS = 48;
+const FALLBACK_HEIGHT_SEGMENTS = 32;
+
+function resolveSegments(value, fallback) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric <= 0) return fallback;
+  return Math.round(numeric);
+}
+
+/**
+ * Parse a colour, or report that it could not be parsed.
+ *
+ * `new THREE.Color(x)` does NOT throw on a value it cannot read: `Color.set` ignores anything that is
+ * not a Color, a number or a string, and `setStyle` warns and leaves the colour untouched. Either way
+ * the object keeps whatever it was constructed with, so a `try/catch` around it catches nothing and
+ * the caller silently gets that starting value — white, by default.
+ *
+ * That matters here because the colour arrives from world metadata, which is `Schema.Types.Mixed` and
+ * validated nowhere: any non-empty string persists, so `'blueish'` would paint a WHITE planet rather
+ * than falling back to the neutral one.
+ *
+ * So: probe from black. If the result is black the value was either genuinely black or not read at
+ * all — probe again from white to tell those apart. The common case parses on the first probe and
+ * costs one object.
+ *
+ * @returns {THREE.Color|null} null when the value could not be read as a colour
+ */
+function parseColor(value) {
+  const fromBlack = new THREE.Color(0x000000).set(value);
+  if (fromBlack.getHex() !== 0x000000) return fromBlack;
+  const fromWhite = new THREE.Color(0xffffff).set(value);
+  return fromWhite.getHex() === 0x000000 ? fromBlack : null;
+}
+
+/**
+ * The planet colour to use, given the colour the world authored (if any).
+ *
+ * The only thing done to an authored colour is the legibility floor above. Hue and saturation are
+ * never touched: the point of the control is that the world picks its own colour, so anything that
+ * moved it toward a house palette would defeat it.
+ *
+ * @param {THREE.Color|number|string|null|undefined} override
+ * @returns {THREE.Color}
+ */
+export function resolvePlanetColor(override) {
+  if (override === undefined || override === null) return new THREE.Color(DEFAULT_PLANET_COLOR);
+  // An unreadable colour is never worth failing a world load over — the world just keeps the neutral.
+  const color = parseColor(override);
+  if (!color) return new THREE.Color(DEFAULT_PLANET_COLOR);
+  // Read and write HSL in sRGB — the space the author picked the colour in. The working space is
+  // linear, where the same swatch measures several times darker, so a floor applied there would
+  // lift colours the author would not call dark at all.
+  const hsl = { h: 0, s: 0, l: 0 };
+  color.getHSL(hsl, THREE.SRGBColorSpace);
+  if (hsl.l < MIN_PLANET_LIGHTNESS) {
+    color.setHSL(hsl.h, hsl.s, MIN_PLANET_LIGHTNESS, THREE.SRGBColorSpace);
+  }
+  return color;
+}
+
+function createMaterial(kind, color) {
+  switch (kind) {
+    case 'normal':
+      // The previous look, kept so it can be compared directly rather than from memory.
+      return new THREE.MeshNormalMaterial();
+    case 'phong':
+      // One specular highlight on top of Lambert. Reads glossier; costs a little more.
+      return new THREE.MeshPhongMaterial({ color, shininess: 12, specular: 0x222222 });
+    default:
+      return new THREE.MeshLambertMaterial({ color });
+  }
+}
+
+/**
+ * Build the minimal planet. Signature matches what `WorldManager.setMode` hands a custom creator.
+ *
+ * @param {{
+ *   sphereRadius?: number,
+ *   sphereWidthSegments?: number,
+ *   sphereHeightSegments?: number,
+ *   materialKind?: 'lambert'|'phong'|'normal',
+ *   planetColor?: THREE.Color|number|string,
+ * }} args
+ * @returns {Promise<THREE.Mesh>}
+ */
+export async function createMinimalWorld({
+  sphereRadius = 1,
+  sphereWidthSegments,
+  sphereHeightSegments,
+  materialKind = 'lambert',
+  planetColor,
+} = {}) {
+  const kind = MINIMAL_MATERIAL_KINDS.includes(materialKind) ? materialKind : 'lambert';
+  const color = resolvePlanetColor(planetColor);
+
+  // The world's own radius and segment counts, as authored. Same shape as the full look — this mode
+  // changes the material and what surrounds the planet, never the geometry the world describes.
+  const geometry = new THREE.SphereGeometry(
+    sphereRadius,
+    resolveSegments(sphereWidthSegments, FALLBACK_WIDTH_SEGMENTS),
+    resolveSegments(sphereHeightSegments, FALLBACK_HEIGHT_SEGMENTS),
+  );
+  const material = createMaterial(kind, color);
+  const mesh = new THREE.Mesh(geometry, material);
+  mesh.name = 'orb_MinimalWorld';
+  mesh.castShadow = false;
+  mesh.receiveShadow = false;
+  return mesh;
+}

package/src/moons/moonsGeneration.js

@@ -38,7 +38,6 @@ export async function generateMoons({
   debugShowReferenceMoon = false, // changed from true to prevent extra moon
   referenceMoonScale = 0.25,
   // behavior flags
-  preserveInstanceTint = false,      // keep per-instance color even when textured
   useEmissiveMapFromTexture = true,  // reuse color texture as emissiveMap to lift dark sides
   // The renderer whose KTX2 transcoder decodes the moon texture. Required on any page with more than
   // one renderer; falls back to the standalone app's global inside the loader.
@@ -118,10 +117,20 @@ export async function generateMoons({
     }
   }
 
-  const enableVertexColors = !sharedTexture || preserveInstanceTint;
+  // `vertexColors` is deliberately NOT set, and setting it here was a bug worth spelling out.
+  //
+  // The per-moon tint rides on `instanceColor` (set by `setColorAt` below). Three defines
+  // USE_INSTANCING_COLOR for that on its own and multiplies it into `vColor` — no material flag
+  // needed. `vertexColors` is a DIFFERENT feature: it multiplies by the geometry's `color`
+  // ATTRIBUTE. This geometry is a plain SphereGeometry and has no such attribute, so enabling it
+  // made the shader multiply by an absent attribute — zero — and every moon rendered BLACK, with the
+  // tint annihilated along with it.
+  //
+  // It only bit the untextured path (`!sharedTexture`), which is the one the performance look uses:
+  // moons there carry no texture, so their colour IS the moon, and it was the one case where the
+  // colour silently could not work.
   const moonMaterial = new THREE.MeshStandardMaterial({
     map: sharedTexture || null,
-    vertexColors: enableVertexColors,
     roughness,
     metalness,
     emissive: new THREE.Color(emissiveColor),

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/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