entangled-worlds-orbiters-shared 3.3.0 → 4.0.0

package/dist/moons/index.d.ts

@@ -0,0 +1,3 @@
+export { MoonsManager } from './moonsManager.js';
+export type { MoonAmountOptions } from './moonsManager.js';
+export { generateMoons, DEFAULT_MOON_TEX_KTX2, DEFAULT_MOON_TEX_PNG, MOON_BASE_RADIUS, MOON_SCALE_MIN, MOON_SCALE_SPAN, MOON_MAX_RADIUS, MOON_ORBIT_SCATTER, MOON_HEIGHT_SCATTER, } from './moonsGeneration.js';

package/dist/moons/index.js

@@ -0,0 +1,3 @@
+// Moons system exports
+export { MoonsManager } from './moonsManager.js';
+export { generateMoons, DEFAULT_MOON_TEX_KTX2, DEFAULT_MOON_TEX_PNG, MOON_BASE_RADIUS, MOON_SCALE_MIN, MOON_SCALE_SPAN, MOON_MAX_RADIUS, MOON_ORBIT_SCATTER, MOON_HEIGHT_SCATTER, } from './moonsGeneration.js';

package/dist/moons/moonsGeneration.d.ts

@@ -0,0 +1,64 @@
+import * as THREE from 'three';
+export declare const DEFAULT_MOON_TEX_KTX2: string;
+export declare const DEFAULT_MOON_TEX_PNG: string;
+/** Radius of the shared moon sphere before per-moon scale. */
+export declare const MOON_BASE_RADIUS = 0.1;
+/** Per-moon scale range: MIN + random * SPAN. */
+export declare const MOON_SCALE_MIN = 0.07;
+export declare const MOON_SCALE_SPAN = 0.15;
+/** Largest moon radius in scene units (base radius × largest scale). */
+export declare const MOON_MAX_RADIUS: number;
+/** Each moon's orbit radius varies by ± half of this around the requested orbit. */
+export declare const MOON_ORBIT_SCATTER = 0.22;
+/** Each moon sits up to ± half of this above or below the orbit plane. */
+export declare const MOON_HEIGHT_SCATTER = 0.12;
+/**
+ * - `count` (0): 0 or less resolves to null. `orbitRadius` 1.5.
+ * - `textureFallback`: used instead of `texturePNG` when set.
+ * - `seed`: deterministic positions when set.
+ * - `textureKey`: replaces `textureKTX2` when set (the fallback stays `textureFallback` or
+ *   `texturePNG`).
+ * - `emissiveLift`: night-side self-glow 0..1; omitted = `emissiveIntensity`.
+ * - `renderer`: binds the KTX2 moon texture.
+ * - Defaults: `moonColor` '#ffffff', `brightness` 1.15, `emissiveColor` 0x333333,
+ *   `emissiveIntensity` 0.18, `roughness` 0.85, `metalness` 0, `debug` true, `smooth` true,
+ *   `geometryWidthSegments` 16, `geometryHeightSegments` 12, `useBumpFromColor` true, `bumpScale`
+ *   0.15, `debugShowUvGrid` false, `debugShowReferenceMoon` false, `referenceMoonScale` 0.25,
+ *   `useEmissiveMapFromTexture` true.
+ */
+export declare function generateMoons({ count, orbitRadius, textureKTX2, texturePNG, textureFallback, useTexture, seed, // if provided, ensures consistent moon positions
+textureKey, // if provided, overrides textureKTX2/texturePNG
+moonColor, // NEW: moon color
+brightness, emissiveColor, emissiveIntensity, emissiveLift, roughness, metalness, debug, smooth, // set false to keep flatShading
+geometryWidthSegments, // Reduced from 24 for better performance
+geometryHeightSegments, // Reduced from 24 for better performance
+useBumpFromColor, bumpScale, debugShowUvGrid, debugShowReferenceMoon, // changed from true to prevent extra moon
+referenceMoonScale, useEmissiveMapFromTexture, // reuse color texture as emissiveMap to lift dark sides
+renderer, }?: {
+    count?: number | undefined;
+    orbitRadius?: number | undefined;
+    textureKTX2?: string | undefined;
+    texturePNG?: string | undefined;
+    textureFallback?: string | null | undefined;
+    useTexture?: boolean | undefined;
+    seed?: string | number | null | undefined;
+    textureKey?: string | null | undefined;
+    moonColor?: string | undefined;
+    brightness?: number | undefined;
+    emissiveColor?: number | undefined;
+    emissiveIntensity?: number | undefined;
+    emissiveLift?: number | undefined;
+    roughness?: number | undefined;
+    metalness?: number | undefined;
+    debug?: boolean | undefined;
+    smooth?: boolean | undefined;
+    geometryWidthSegments?: number | undefined;
+    geometryHeightSegments?: number | undefined;
+    useBumpFromColor?: boolean | undefined;
+    bumpScale?: number | undefined;
+    debugShowUvGrid?: boolean | undefined;
+    debugShowReferenceMoon?: boolean | undefined;
+    referenceMoonScale?: number | undefined;
+    useEmissiveMapFromTexture?: boolean | undefined;
+    renderer?: THREE.WebGLRenderer | null | undefined;
+}): Promise<THREE.Group<THREE.Object3DEventMap> | null>;

package/dist/moons/moonsGeneration.js

@@ -0,0 +1,238 @@
+import * as THREE from 'three';
+import { loadTexture } from '../loaders/bodyTextureLoader.js';
+import { resolvePublicUrl } from '../config/env.js';
+function moonTexPath(file) {
+    return resolvePublicUrl(`default/textures/moons/${file}`);
+}
+export const DEFAULT_MOON_TEX_KTX2 = moonTexPath('moon-equirectangular.ktx2');
+export const DEFAULT_MOON_TEX_PNG = moonTexPath('moon-equirectangular.png');
+// Moon layout sizes, exported so hosts can keep other bodies clear of the moons without copying numbers.
+/** Radius of the shared moon sphere before per-moon scale. */
+export const MOON_BASE_RADIUS = 0.1;
+/** Per-moon scale range: MIN + random * SPAN. */
+export const MOON_SCALE_MIN = 0.07;
+export const MOON_SCALE_SPAN = 0.15;
+/** Largest moon radius in scene units (base radius × largest scale). */
+export const MOON_MAX_RADIUS = MOON_BASE_RADIUS * (MOON_SCALE_MIN + MOON_SCALE_SPAN);
+/** Each moon's orbit radius varies by ± half of this around the requested orbit. */
+export const MOON_ORBIT_SCATTER = 0.22;
+/** Each moon sits up to ± half of this above or below the orbit plane. */
+export const MOON_HEIGHT_SCATTER = 0.12;
+/**
+ * - `count` (0): 0 or less resolves to null. `orbitRadius` 1.5.
+ * - `textureFallback`: used instead of `texturePNG` when set.
+ * - `seed`: deterministic positions when set.
+ * - `textureKey`: replaces `textureKTX2` when set (the fallback stays `textureFallback` or
+ *   `texturePNG`).
+ * - `emissiveLift`: night-side self-glow 0..1; omitted = `emissiveIntensity`.
+ * - `renderer`: binds the KTX2 moon texture.
+ * - Defaults: `moonColor` '#ffffff', `brightness` 1.15, `emissiveColor` 0x333333,
+ *   `emissiveIntensity` 0.18, `roughness` 0.85, `metalness` 0, `debug` true, `smooth` true,
+ *   `geometryWidthSegments` 16, `geometryHeightSegments` 12, `useBumpFromColor` true, `bumpScale`
+ *   0.15, `debugShowUvGrid` false, `debugShowReferenceMoon` false, `referenceMoonScale` 0.25,
+ *   `useEmissiveMapFromTexture` true.
+ */
+export async function generateMoons({ count = 0, orbitRadius = 1.5, textureKTX2 = DEFAULT_MOON_TEX_KTX2, texturePNG = DEFAULT_MOON_TEX_PNG, textureFallback = null, useTexture = true, 
+// NEW: seed for deterministic positioning
+seed = null, // if provided, ensures consistent moon positions
+// NEW: specific texture key/path
+textureKey = null, // if provided, overrides textureKTX2/texturePNG
+moonColor = '#ffffff', // NEW: moon color
+// lighting tweaks
+brightness = 1.15, emissiveColor = 0x333333, emissiveIntensity = 0.18, 
+// Self-glow that lifts the night side. Defaults to `emissiveIntensity` (today's look, for the old
+// flat lighting). With a directional star light, pass something low (≈0.05) so night sides read.
+emissiveLift = undefined, roughness = 0.85, metalness = 0.0, 
+// debug & appearance controls
+debug = true, smooth = true, // set false to keep flatShading
+// debug / appearance params
+geometryWidthSegments = 16, // Reduced from 24 for better performance
+geometryHeightSegments = 12, // Reduced from 24 for better performance
+useBumpFromColor = true, bumpScale = 0.15, debugShowUvGrid = false, debugShowReferenceMoon = false, // changed from true to prevent extra moon
+referenceMoonScale = 0.25, 
+// behavior flags
+useEmissiveMapFromTexture = true, // reuse color texture as emissiveMap to lift dark sides
+// The renderer whose KTX2 transcoder decodes the moon texture. REQUIRED for the KTX2 texture (3.0:
+// the loader has no global fallback).
+renderer, } = {}) {
+    if (count <= 0)
+        return null;
+    // Seeded random number generator for deterministic positioning
+    let seedValue = seed;
+    if (typeof seed === 'string') {
+        // Convert string seed to number using simple hash
+        seedValue = 0;
+        for (let i = 0; i < seed.length; i++) {
+            const char = seed.charCodeAt(i);
+            seedValue = ((seedValue << 5) - seedValue) + char;
+            seedValue = seedValue & seedValue; // Convert to 32-bit integer
+        }
+    }
+    // Seeded random function (Linear Congruential Generator)
+    // A string seed was hashed to a number above.
+    let currentSeed = seedValue !== null ? Math.abs(seedValue) : Date.now();
+    const seededRandom = () => {
+        if (seedValue !== null) {
+            currentSeed = (currentSeed * 1664525 + 1013904223) % 4294967296;
+            return currentSeed / 4294967296;
+        }
+        return Math.random(); // Use regular random if no seed
+    };
+    const moonGeometry = new THREE.SphereGeometry(MOON_BASE_RADIUS, geometryWidthSegments, geometryHeightSegments);
+    // Optional UV grid override
+    let sharedTexture = null;
+    let usedUvGrid = false;
+    async function buildUvGridTexture() {
+        const w = 512, h = 256; // 2:1 aspect
+        const canvas = document.createElement('canvas');
+        canvas.width = w;
+        canvas.height = h;
+        // A missing 2D context throws on first use; the caller catches it, as before.
+        const ctx = canvas.getContext('2d');
+        ctx.fillStyle = '#101018';
+        ctx.fillRect(0, 0, w, h);
+        for (let lon = 0; lon <= 12; lon++) {
+            const x = (lon / 12) * w;
+            ctx.strokeStyle = lon % 3 === 0 ? '#ff4d4d' : '#444';
+            ctx.lineWidth = lon % 3 === 0 ? 2 : 1;
+            ctx.beginPath();
+            ctx.moveTo(x, 0);
+            ctx.lineTo(x, h);
+            ctx.stroke();
+        }
+        for (let lat = 0; lat <= 6; lat++) {
+            const y = (lat / 6) * h;
+            ctx.strokeStyle = lat % 3 === 0 ? '#4dff7a' : '#444';
+            ctx.lineWidth = lat % 3 === 0 ? 2 : 1;
+            ctx.beginPath();
+            ctx.moveTo(0, y);
+            ctx.lineTo(w, y);
+            ctx.stroke();
+        }
+        ctx.fillStyle = 'white';
+        ctx.font = '20px monospace';
+        ctx.fillText('UV GRID', 10, 24);
+        const tex = new THREE.CanvasTexture(canvas);
+        tex.colorSpace = THREE.SRGBColorSpace;
+        tex.anisotropy = 4;
+        return tex;
+    }
+    if (debugShowUvGrid) {
+        try {
+            sharedTexture = await buildUvGridTexture();
+            usedUvGrid = true;
+        }
+        catch (_) { }
+    }
+    else if (useTexture) {
+        // Use textureKey if provided, otherwise fall back to default textures
+        const primaryTexture = textureKey ? resolvePublicUrl(textureKey) : textureKTX2;
+        const fallbackTexture = textureFallback || texturePNG;
+        try {
+            sharedTexture = await loadTexture(primaryTexture, { renderer });
+        }
+        catch (eKTX) {
+            if (debug)
+                console.warn('[Moons] Primary texture failed, trying fallback:', eKTX);
+            try {
+                sharedTexture = await loadTexture(fallbackTexture, { renderer });
+            }
+            catch (ePNG) {
+                if (debug)
+                    console.warn('[Moons] Both primary and fallback texture loading failed');
+            }
+        }
+    }
+    if (sharedTexture) {
+        try {
+            sharedTexture.colorSpace = THREE.SRGBColorSpace;
+            sharedTexture.anisotropy = 2; // Reduced from 4 for better performance
+        }
+        catch (e) {
+            if (debug)
+                console.warn('[Moons] Texture processing failed:', e);
+        }
+    }
+    // `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.
+    // Diffuse-only (Lambert): the star's key light costs no specular pass, so
+    // `roughness` / `metalness` are accepted for older callers but no longer change the look.
+    const moonMaterial = new THREE.MeshLambertMaterial({
+        map: sharedTexture || null,
+        emissive: new THREE.Color(emissiveColor),
+        emissiveIntensity: typeof emissiveLift === 'number' && Number.isFinite(emissiveLift) ? Math.min(1, Math.max(0, emissiveLift)) : emissiveIntensity,
+        flatShading: !smooth,
+        transparent: false,
+        depthWrite: true,
+        depthTest: true,
+    });
+    if (sharedTexture && useEmissiveMapFromTexture) {
+        moonMaterial.emissiveMap = sharedTexture; // boosts subtle texture detail
+    }
+    if (!sharedTexture && debug && !debugShowUvGrid) {
+        console.warn('[Moons] No texture assigned (using pure color instancing).');
+    }
+    if (sharedTexture) {
+        moonMaterial.map = sharedTexture;
+        if (useBumpFromColor) {
+            moonMaterial.bumpMap = sharedTexture;
+            moonMaterial.bumpScale = bumpScale;
+        }
+    }
+    // Pre-computed color palette for variation (white to dark gray)
+    const colorPalette = [
+        0xffffff, 0xf5f5f5, 0xeeeeee, 0xe8e8e8, 0xdddddd, 0xd3d3d3,
+        0xcccccc, 0xc0c0c0, 0xb8b8b8, 0xaaaaaa, 0x999999, 0x888888
+    ].map(hex => new THREE.Color(hex));
+    const instanced = new THREE.InstancedMesh(moonGeometry, moonMaterial, count + (debugShowReferenceMoon ? 1 : 0));
+    // Set render order to ensure proper rendering above glow effects
+    instanced.renderOrder = 2000;
+    const dummy = new THREE.Object3D();
+    let instanceIndex = 0;
+    for (let i = 0; i < count; i++) {
+        const angle = (i / Math.max(1, count)) * Math.PI * 2;
+        const radiusVar = orbitRadius + (seededRandom() - 0.5) * MOON_ORBIT_SCATTER;
+        const yOffset = (seededRandom() - 0.5) * MOON_HEIGHT_SCATTER;
+        dummy.position.set(radiusVar * Math.cos(angle), yOffset, radiusVar * Math.sin(angle));
+        const s = MOON_SCALE_MIN + seededRandom() * MOON_SCALE_SPAN;
+        dummy.scale.set(s, s, s);
+        dummy.rotation.y = seededRandom() * Math.PI * 2;
+        dummy.rotation.x = seededRandom() * 0.3 - 0.15;
+        dummy.updateMatrix();
+        instanced.setMatrixAt(instanceIndex, dummy.matrix);
+        // Always set instance color as tint, even if texture is present
+        const base = new THREE.Color(moonColor || '#ffffff');
+        instanced.setColorAt(instanceIndex, base);
+        instanceIndex++;
+    }
+    if (debugShowReferenceMoon) {
+        dummy.position.set(orbitRadius * 0.6, 0.05, orbitRadius * 0.2);
+        dummy.scale.set(referenceMoonScale, referenceMoonScale, referenceMoonScale);
+        dummy.rotation.y = seededRandom() * Math.PI * 2;
+        dummy.rotation.x = seededRandom() * 0.3 - 0.15;
+        dummy.updateMatrix();
+        instanced.setMatrixAt(instanceIndex, dummy.matrix);
+        const refColor = new THREE.Color('#ffffff');
+        instanced.setColorAt(instanceIndex, refColor);
+    }
+    instanced.instanceMatrix.needsUpdate = true;
+    if (instanced.instanceColor)
+        instanced.instanceColor.needsUpdate = true;
+    const group = new THREE.Group();
+    group.rotation.x = THREE.MathUtils.degToRad(15);
+    group.add(instanced);
+    group.name = 'moonsGroup';
+    // Teardown goes through `disposeObject3D` (MoonsManager.dispose / setAmount), which frees the
+    // geometry, the material's textures and the instance buffers.
+    return group;
+}

package/dist/moons/moonsManager.d.ts

@@ -0,0 +1,43 @@
+import * as THREE from 'three';
+/** The `setAmount` options: what the moons look like and where they orbit. */
+export interface MoonAmountOptions {
+    /** 1.5 by default. */
+    orbitRadius?: number;
+    textureKTX2?: string;
+    texturePNG?: string;
+    /** true by default. */
+    useTexture?: boolean;
+    /** Deterministic positions when set. */
+    seed?: string | number | null;
+    /** Replaces `textureKTX2` when set. */
+    textureKey?: string | null;
+    /** '#ffffff' by default. */
+    moonColor?: string;
+    /** Used instead of `texturePNG` when set. */
+    textureFallback?: string | null;
+    /** Night-side self-glow 0..1, kept for later rebuilds; anything but a number is ignored. */
+    emissiveLift?: number;
+}
+export declare class MoonsManager {
+    scene: THREE.Scene;
+    renderer: THREE.WebGLRenderer | null | undefined;
+    group: THREE.Group | null;
+    _opId: number;
+    _emissiveLift: number | undefined;
+    /** `renderer`: the renderer the moon texture binds to (KTX2). */
+    constructor(scene: THREE.Scene, { renderer }?: {
+        renderer?: THREE.WebGLRenderer | null | undefined;
+    });
+    /** Replace the moons with `count` new ones; 0 or less (or none) just removes them. */
+    setAmount(count: number | null | undefined, opts?: MoonAmountOptions): Promise<void>;
+    /**
+     * Night-side self-glow 0..1, applied in place to the live moons and kept for later rebuilds.
+     * Low values (≈0.05) let a star-lit scene show the moons' dark sides.
+     */
+    setEmissiveLift(v: number): void;
+    /**
+     * Remove the moons from the scene and free their GPU resources. `scene.remove(group)` alone leaks
+     * the instanced geometry, materials and the shared moon texture on every view teardown.
+     */
+    dispose(): void;
+}

package/dist/moons/moonsManager.js

@@ -0,0 +1,93 @@
+import { disposeObject3D } from '../utils/dispose.js';
+import * as THREE from 'three';
+import { generateMoons } from './moonsGeneration.js';
+export class MoonsManager {
+    /** `renderer`: the renderer the moon texture binds to (KTX2). */
+    constructor(scene, { renderer } = {}) {
+        this.scene = scene;
+        this.renderer = renderer;
+        this.group = null;
+        this._opId = 0; // concurrency guard
+        this._emissiveLift = undefined; // night-side self-glow; undefined = generator default
+    }
+    /** Replace the moons with `count` new ones; 0 or less (or none) just removes them. */
+    async setAmount(count, opts = {}) {
+        // Increment operation id to invalidate older async calls
+        const opId = ++this._opId;
+        // remove existing
+        if (this.group) {
+            disposeObject3D(this.group);
+            this.group = null;
+        }
+        if (!count || count <= 0)
+            return;
+        // Gather options for texture sharing / orbit params
+        const { orbitRadius = 1.5, textureKTX2, texturePNG, useTexture = true, seed = null, // seed for deterministic positioning
+        textureKey = null, // NEW: specific texture key/path to use
+        moonColor = '#ffffff', // NEW: moon color
+        textureFallback = null, emissiveLift, // night-side self-glow 0..1 (undefined = today's look)
+         } = opts;
+        if (typeof emissiveLift === 'number')
+            this._emissiveLift = emissiveLift;
+        let newGroup = null;
+        try {
+            newGroup = await generateMoons({
+                count,
+                orbitRadius,
+                textureKTX2,
+                texturePNG,
+                useTexture,
+                seed,
+                textureKey, // Pass texture key for custom moon textures
+                textureFallback,
+                moonColor, // Pass moon color to generator
+                emissiveLift: this._emissiveLift,
+                renderer: this.renderer,
+            });
+        }
+        catch (e) {
+            console.warn('[MoonsManager] Failed to generate moons:', e);
+            return;
+        }
+        // If another call started meanwhile, abandon this result
+        if (opId !== this._opId) {
+            if (newGroup)
+                disposeObject3D(newGroup);
+            return;
+        }
+        if (newGroup instanceof THREE.Object3D) {
+            this.group = newGroup;
+            this.scene.add(this.group);
+        }
+        else if (newGroup) {
+            console.warn('[MoonsManager] generateMoons did not return an Object3D');
+        }
+    }
+    /**
+     * Night-side self-glow 0..1, applied in place to the live moons and kept for later rebuilds.
+     * Low values (≈0.05) let a star-lit scene show the moons' dark sides.
+     */
+    setEmissiveLift(v) {
+        if (typeof v !== 'number' || !Number.isFinite(v))
+            return;
+        this._emissiveLift = Math.min(1, Math.max(0, v));
+        this.group?.traverse((object) => {
+            // Only a mesh whose material has `emissiveIntensity` is changed; the value was just set above.
+            const child = object;
+            if (child.isMesh && child.material && 'emissiveIntensity' in child.material) {
+                child.material.emissiveIntensity = this._emissiveLift;
+            }
+        });
+    }
+    /**
+     * Remove the moons from the scene and free their GPU resources. `scene.remove(group)` alone leaks
+     * the instanced geometry, materials and the shared moon texture on every view teardown.
+     */
+    dispose() {
+        this._opId++; // abandon any in-flight setAmount
+        if (this.group) {
+            disposeObject3D(this.group);
+            this.group = null;
+        }
+    }
+}

package/dist/{types/render → render}/frameBudget.d.ts

@@ -1,19 +1,5 @@
 /**
- * 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, toleranceMs }?: {
-    fps?: number;
-    toleranceMs?: number;
-}): {
-    shouldRender(nowMs: number): boolean;
-    reset(): void;
-};
-/**
- * @file src/render/frameBudget.js
+ * @file src/render/frameBudget.ts
  * @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.
  *
@@ -24,6 +10,21 @@ export function createFrameBudget({ fps, toleranceMs }?: {
  * near enough through, and the cap lands where it was aimed.
  */
 /** Frames a capped loop is allowed per second. */
-export const CAPPED_FPS: 30;
+export declare const CAPPED_FPS = 30;
 /** Slack for rAF landing on display ticks — see the file note. */
-export const FRAME_TOLERANCE_MS: 4;
+export declare const FRAME_TOLERANCE_MS = 4;
+/** A frame gate (`createFrameBudget`). */
+export type FrameBudget = {
+    /** True when `nowMs` is far enough past the last accepted frame; true without a finite time. */
+    shouldRender(nowMs?: number): boolean;
+    /** Forget the last frame. */
+    reset(): void;
+};
+/**
+ * A frame gate. Not a clock and not a scheduler: it answers one question and remembers the last time
+ * the answer was yes.
+ */
+export declare function createFrameBudget({ fps, toleranceMs }?: {
+    fps?: number;
+    toleranceMs?: number;
+}): FrameBudget;

package/dist/render/frameBudget.js

@@ -0,0 +1,42 @@
+/**
+ * @file src/render/frameBudget.ts
+ * @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.
+ */
+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 (nowMs === undefined || !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/dist/render/index.d.ts

@@ -0,0 +1,4 @@
+export { createViewportCompositor } from './viewportCompositor.js';
+export type { ViewportCompositor, ViewportCompositorOptions, RendererProfile, VoiceController, CompositorVoice, CellSource, FrameProbe, ViewportRect, } from './viewportCompositor.js';
+export { createFrameBudget, CAPPED_FPS, FRAME_TOLERANCE_MS } from './frameBudget.js';
+export type { FrameBudget } from './frameBudget.js';

package/dist/render/viewportCompositor.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @file src/render/viewportCompositor.ts
+ * @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
+ * 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.
+ *
+ * ## 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:
+ * - `'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.
+ * - 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.
+ */
+import * as THREE from 'three';
+/** The renderer settings a host can override (`rendererProfile`, any subset). */
+export type RendererProfile = {
+    antialias: boolean;
+    alpha: boolean;
+    preserveDrawingBuffer: boolean;
+    powerPreference: WebGLPowerPreference;
+    maxDevicePixelRatio: number;
+};
+/** CSS px. GL bottom-left origin in fixed-overlay, viewport top-left in per-cell. */
+export type ViewportRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** What the compositor calls on a voice's controller (see the host contract in the module doc). */
+export type VoiceController = {
+    renderActive: boolean;
+    renderViewport: (rect: ViewportRect) => void;
+    setViewportSize: (width: number, height: number) => void;
+};
+/** One voice as `addVoice` takes it. */
+export type CompositorVoice = {
+    voiceId: string;
+    cell: HTMLElement;
+    controller: VoiceController;
+};
+/** An external owner of the cell DOM (`cellSource`). */
+export type CellSource = {
+    acquireCell: (index: number, total: number) => HTMLElement;
+    releaseCell?: (index: number) => void;
+};
+/** A load meter's watch on the realm's frames (`setFrameProbe`). */
+export type FrameProbe = {
+    everyMs: number;
+    onFrame?: (nowMs: number) => void;
+    onDraw: (workMs: number, calls: number, triangles: number) => void;
+};
+/** The `createViewportCompositor` options (all optional; see the function). */
+export type ViewportCompositorOptions = {
+    cellSource?: CellSource | null;
+    presentation?: 'fixed-overlay' | 'per-cell';
+    rendererProfile?: Partial<RendererProfile> | null;
+    performanceMode?: boolean;
+    devHandleKey?: string | null;
+};
+/** The compositor `createViewportCompositor` returns. */
+export type ViewportCompositor = {
+    renderer: THREE.WebGLRenderer;
+    canvas: HTMLCanvasElement;
+    createCell: (index: number, total: number) => HTMLElement;
+    addVoice: (voice: CompositorVoice) => void;
+    removeVoice: (voiceId: string) => void;
+    renderOnce: () => void;
+    setPerformanceMode: (enabled: boolean) => boolean;
+    /** Watch the realm's frames for a load meter; `null` stops it. */
+    setFrameProbe: (probe: FrameProbe | null) => void;
+    dispose: () => void;
+};
+/**
+ * Options, all optional:
+ * - `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.
+ * - `presentation` (default `'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.
+ * - `rendererProfile`: renderer construction + pixel-ratio cap. Omit for the historical defaults.
+ * - `performanceMode` (default 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`.
+ * - `devHandleKey` (default 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.
+ */
+export declare function createViewportCompositor({ cellSource, presentation, rendererProfile, devHandleKey, performanceMode, }?: ViewportCompositorOptions): ViewportCompositor;