entangled-worlds-orbiters-shared 3.1.0 → 4.0.0

package/dist/core/lights.js

@@ -0,0 +1,79 @@
+import * as THREE from 'three';
+/**
+ * Ensure a scene has the default hemisphere + ambient lights. Idempotent PER SCENE.
+ *
+ * A multi-orbiter realm renders N independent scenes through one renderer. A module-level
+ * singleton light is wrong twice over — it's only added to the FIRST scene, and a THREE light can
+ * live in just one scene (adding it to a second removes it from the first), so scenes 2..N rendered
+ * DARK ("only one entangled world"). So create + add the lights PER scene, keyed by name so a
+ * re-call on the same scene is a no-op. Single-orbiter (one scene) is unchanged.
+ */
+export function ensureDefaultLights(scene) {
+    // Found by name: the objects under these names are the lights this function added.
+    let hemi = scene.getObjectByName('ew_HemisphereLight');
+    if (!hemi) {
+        hemi = new THREE.HemisphereLight(0xffffff, 0xffffff, 1.0);
+        hemi.position.set(1, 1, 1);
+        hemi.name = 'ew_HemisphereLight';
+        scene.add(hemi);
+    }
+    let ambient = scene.getObjectByName('ew_AmbientLight');
+    if (!ambient) {
+        ambient = new THREE.AmbientLight(0xffffff, 1.0);
+        ambient.name = 'ew_AmbientLight';
+        scene.add(ambient);
+    }
+    return { hemi, ambient };
+}
+/**
+ * Apply a lighting patch to ONE scene's default lights.
+ *
+ * The scene is required. This used to address module-global light refs pointing at whichever scene
+ * was ensured last, so on a page rendering several scenes every lighting update landed on one of
+ * them — a shared-renderer page (N feed worlds, N orbiters) lit the wrong world.
+ *
+ * Every field is optional; an omitted one leaves that part of the lighting as it is.
+ */
+export function updateDefaultLights(scene, { ambientIntensity, diffuseIntensity, lightColor, lightDirection, hemisphere } = {}) {
+    if (!scene?.isObject3D) {
+        console.error('[lights] updateDefaultLights(scene, patch) requires the scene to update; ignoring patch.');
+        return;
+    }
+    const { hemi, ambient } = ensureDefaultLights(scene);
+    // `hemisphere: false` switches the white hemisphere off (e.g. when a star lights the scene);
+    // omitted = unchanged, so old callers keep today's look.
+    if (typeof hemisphere === 'boolean')
+        hemi.visible = hemisphere;
+    if (typeof ambientIntensity === 'number')
+        ambient.intensity = Math.max(0, ambientIntensity);
+    if (typeof diffuseIntensity === 'number')
+        hemi.intensity = Math.max(0, diffuseIntensity);
+    if (lightColor != null) {
+        if (lightColor instanceof THREE.Color) {
+            hemi.color.copy(lightColor);
+        }
+        else if (typeof lightColor === 'number') {
+            hemi.color.setHex(lightColor);
+        }
+        else if (typeof lightColor === 'string') {
+            hemi.color.set(lightColor);
+        }
+    }
+    if (lightDirection && typeof lightDirection.x === 'number') {
+        hemi.position.set(lightDirection.x, lightDirection.y ?? 0, lightDirection.z ?? 0).normalize();
+    }
+}
+/**
+ * Switch a scene's default hemisphere light on or off (the ambient light is untouched). Hosts turn it
+ * off when a directional light — the star — lights the scene, so night sides can read.
+ */
+export function setHemisphereEnabled(scene, on) {
+    if (!scene?.isObject3D)
+        return;
+    const { hemi } = ensureDefaultLights(scene);
+    hemi.visible = Boolean(on);
+}
+// Back-compat helper
+export function addDefaultLights(scene) {
+    return ensureDefaultLights(scene);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './world/index.js';
+export * from './moons/index.js';
+export * from './loaders/index.js';
+export * from './core/index.js';
+export * from './config/index.js';
+export * from './utils/index.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+// Main exports for entangled-worlds-orbiters-shared library
+export * from './world/index.js';
+export * from './moons/index.js';
+export * from './loaders/index.js';
+export * from './core/index.js';
+export * from './config/index.js';
+export * from './utils/index.js';

package/dist/loaders/bodyTextureLoader.d.ts

@@ -0,0 +1,10 @@
+import * as THREE from 'three';
+/**
+ * `url`: `.ktx2` goes through the renderer's KTX2 transcoder; anything else through
+ * THREE.TextureLoader. `signal`: an abort during the load rejects the promise. `renderer`: REQUIRED
+ * for a `.ktx2` url.
+ */
+export declare function loadTexture(url: string, { signal, renderer }?: {
+    signal?: AbortSignal | undefined;
+    renderer?: THREE.WebGLRenderer | null | undefined;
+}): Promise<THREE.Texture>;

package/dist/loaders/bodyTextureLoader.js

@@ -0,0 +1,28 @@
+import * as THREE from 'three';
+import { getKTX2LoaderForRenderer } from './ktx2.js';
+const textureLoader = new THREE.TextureLoader();
+/**
+ * `url`: `.ktx2` goes through the renderer's KTX2 transcoder; anything else through
+ * THREE.TextureLoader. `signal`: an abort during the load rejects the promise. `renderer`: REQUIRED
+ * for a `.ktx2` url.
+ */
+export function loadTexture(url, { signal, renderer } = {}) {
+    return new Promise((resolve, reject) => {
+        if (url && url.endsWith('.ktx2')) {
+            // A missing renderer throws inside (as before): the type allows `null` only because the
+            // non-KTX2 path never needs one.
+            const ktx2 = getKTX2LoaderForRenderer(renderer);
+            const onAbort = () => reject(new Error('aborted'));
+            if (signal)
+                signal.addEventListener('abort', onAbort, { once: true });
+            ktx2.load(url, (tex) => { if (signal)
+                signal.removeEventListener('abort', onAbort); resolve(tex); }, undefined, (err) => { if (signal)
+                signal.removeEventListener('abort', onAbort); reject(err); });
+            return;
+        }
+        const tex = textureLoader.load(url, () => resolve(tex), undefined, (err) => reject(err));
+        if (signal) {
+            signal.addEventListener('abort', () => reject(new Error('aborted')));
+        }
+    });
+}

package/dist/loaders/cubeMapLoader.d.ts

@@ -0,0 +1,58 @@
+import * as THREE from 'three';
+/** A skycube id (`'7'`, `'07_skycube'`, `'skybox-007'`, …) as its three-digit folder name; `'001'` when none. */
+export declare function normalizeSkycubeName(raw: string | null | undefined): string;
+export declare function buildSkycubefaceKeys(skycubeId: string | null | undefined, extension?: string): {
+    right: string;
+    left: string;
+    top: string;
+    bottom: string;
+    front: string;
+    back: string;
+};
+/**
+ * Main loader function - always uses explicit face URLs.
+ * `renderer` binds the KTX2 transcoder to the right WebGL context. REQUIRED (3.0) when the KTX2
+ * path is taken — the old `window.__EW_RENDERER` fallback is gone; thread the owning view's
+ * renderer. (The PNG/JPG path is renderer-agnostic, so its absence only bites on KTX2.)
+ *
+ * - `faceKeys`: explicit face URLs; when absent they are built from `skycubeName`.
+ * - `skycubeName`: skybox id (e.g. `'001'`), used when `faceKeys` is absent.
+ * - `preferKTX2` (true).
+ * - `forceLow`: force (or forbid) the low-resolution faces; omitted = detect the device.
+ *
+ * Resolves to what `setBackground` takes.
+ */
+export declare function loadCubeMap({ faceKeys, skycubeName, preferKTX2, forceLow, renderer, }?: {
+    faceKeys?: {
+        right: string;
+        left: string;
+        top: string;
+        bottom: string;
+        front: string;
+        back: string;
+    } | undefined;
+    skycubeName?: string | undefined;
+    preferKTX2?: boolean | undefined;
+    forceLow?: boolean | undefined;
+    renderer?: THREE.WebGLRenderer | null | undefined;
+}): Promise<SkyboxResource>;
+/**
+ * What `loadCubeMap` resolves to: a skybox mesh wrapper (the KTX2 path) or a cube texture (the
+ * PNG/JPG path). Read `mesh` to tell them apart.
+ */
+export type SkyboxResource = {
+    __ewType: 'skybox-mesh';
+    mesh: THREE.Mesh;
+} | (THREE.CubeTexture & {
+    mesh?: undefined;
+});
+/**
+ * Show a loaded skybox as the scene's background. A previous skybox mesh or cube-texture background is
+ * disposed (a plain-texture background is not). Takes what `loadCubeMap` resolved to (or any texture);
+ * anything else, `null` included, clears it.
+ *
+ */
+export declare function setBackground(scene: THREE.Scene, resource: unknown): void;
+export declare function initSpaceScene(scene: THREE.Scene, { renderer }?: {
+    renderer?: THREE.WebGLRenderer | null;
+}): Promise<void>;

package/dist/loaders/cubeMapLoader.js

@@ -0,0 +1,291 @@
+import * as THREE from 'three';
+import { getPublicBase } from '../config/env.js';
+import { getKTX2LoaderForRenderer } from './ktx2.js';
+/** A skycube id (`'7'`, `'07_skycube'`, `'skybox-007'`, …) as its three-digit folder name; `'001'` when none. */
+export function normalizeSkycubeName(raw) {
+    if (!raw)
+        return '001';
+    const legacy = raw.match(/^(\d{1,2})_skycube(?:_low)?$/);
+    if (legacy)
+        return String(parseInt(legacy[1], 10)).padStart(3, '0');
+    const num = raw.match(/(\d{1,3})/);
+    if (num)
+        return String(parseInt(num[1], 10)).padStart(3, '0');
+    return '001';
+}
+// Standard face order for cube maps
+const FACE_ORDER = ['right', 'left', 'top', 'bottom', 'front', 'back'];
+// Build complete face URL sets for a given skycube ID (now returns relative paths)
+export function buildSkycubefaceKeys(skycubeId, extension = 'ktx2') {
+    const id = normalizeSkycubeName(skycubeId);
+    const base = `/default/skybox/${id}`;
+    return {
+        right: `${base}/right.${extension}`,
+        left: `${base}/left.${extension}`,
+        top: `${base}/top.${extension}`,
+        bottom: `${base}/bottom.${extension}`,
+        front: `${base}/front.${extension}`,
+        back: `${base}/back.${extension}`
+    };
+}
+// Heuristic low-performance detection
+function isLowPerformanceDevice() {
+    try {
+        const ua = navigator.userAgent.toLowerCase();
+        const isMobileUA = /mobi|android|iphone|ipad|ipod/.test(ua);
+        // `deviceMemory` is not in every browser, nor in the DOM types.
+        const mem = navigator.deviceMemory || 0; // GB
+        const cores = navigator.hardwareConcurrency || 0;
+        const dpr = window.devicePixelRatio || 1;
+        return isMobileUA || mem && mem <= 4 || cores && cores <= 4 || (dpr > 2 && cores <= 6);
+    }
+    catch {
+        return false;
+    }
+}
+// Validate face URLs object
+function validatefaceKeys(faceKeys) {
+    if (!faceKeys || typeof faceKeys !== 'object')
+        return false;
+    const keys = faceKeys;
+    return FACE_ORDER.every(face => keys[face] && typeof keys[face] === 'string');
+}
+// Detect extension type from face URLs
+function detectExtension(faceKeys) {
+    const url = faceKeys.right || '';
+    if (url.toLowerCase().includes('.ktx2'))
+        return 'ktx2';
+    if (url.toLowerCase().match(/\.(jpg|jpeg|png)$/))
+        return 'jpg';
+    return 'ktx2'; // default assumption
+}
+// How many faces may be in flight at once. Not six: the KTX2 worker pool three.js gives us holds
+// four transcoder workers, each carrying its own copy of the basis wasm, and that same pool also
+// serves body textures and GLBs. Asking for all six together spawned every worker and queued the
+// other loaders behind the whole sky; measured on cold fetches it was no faster than three.
+const FACES_IN_FLIGHT = 3;
+// Load KTX2 faces and create skybox mesh
+async function loadFacesKTX2(faceKeys, renderer) {
+    const loader = getKTX2LoaderForRenderer(renderer);
+    const anisotropy = Math.min(8, renderer.capabilities.getMaxAnisotropy());
+    const loadFace = async (face) => {
+        const tex = await loader.loadAsync(faceKeys[face]);
+        tex.flipY = false;
+        tex.wrapS = THREE.ClampToEdgeWrapping;
+        tex.wrapT = THREE.ClampToEdgeWrapping;
+        tex.anisotropy = anisotropy;
+        return { face, tex };
+    };
+    // Faces overlap instead of chaining. Awaiting each one in turn made every face wait on the
+    // previous face's download *and* its transcode, so the sky arrived six round trips deep.
+    const settled = [];
+    for (let i = 0; i < FACE_ORDER.length; i += FACES_IN_FLIGHT) {
+        const wave = FACE_ORDER.slice(i, i + FACES_IN_FLIGHT).map(face => loadFace(face));
+        settled.push(...await Promise.allSettled(wave));
+    }
+    // allSettled, not all: a bare Promise.all rejects on the first failure and leaks the faces that
+    // land after it. Settle every face first, then dispose everything that arrived before rethrowing.
+    const loaded = [];
+    let failure = null;
+    for (const result of settled) {
+        if (result.status === 'fulfilled')
+            loaded.push(result.value);
+        else if (!failure)
+            failure = result.reason;
+    }
+    if (failure) {
+        // Dispose already loaded textures on failure
+        loaded.forEach(f => f.tex.dispose?.());
+        throw failure;
+    }
+    const size = 500;
+    const box = new THREE.BoxGeometry(size, size, size);
+    // Map faces to geometry indices (corrected for orientation)
+    const orderMap = { right: 0, left: 1, top: 3, bottom: 2, front: 4, back: 5 };
+    const mats = new Array(6).fill(null);
+    loaded.forEach(({ face, tex }) => {
+        mats[orderMap[face]] = new THREE.MeshBasicMaterial({
+            map: tex,
+            side: THREE.BackSide,
+            depthWrite: false
+        });
+    });
+    // Fill any missing materials with black
+    for (let i = 0; i < 6; i++) {
+        if (!mats[i]) {
+            mats[i] = new THREE.MeshBasicMaterial({
+                color: 0x000000,
+                side: THREE.BackSide,
+                depthWrite: false
+            });
+        }
+    }
+    // Every slot is filled by now (a face's material or black).
+    const mesh = new THREE.Mesh(box, mats);
+    mesh.name = 'SkyboxKTX2Mesh';
+    return { __ewType: 'skybox-mesh', mesh };
+}
+// Load JPG/PNG faces and create CubeTexture
+function loadFacesJPG(faceKeys) {
+    const urls = FACE_ORDER.map(face => faceKeys[face]);
+    return new Promise((resolve, reject) => {
+        new THREE.CubeTextureLoader().load(urls, tex => {
+            tex.magFilter = THREE.LinearFilter;
+            tex.minFilter = THREE.LinearMipMapLinearFilter;
+            tex.anisotropy = 8;
+            resolve(tex);
+        }, undefined, err => reject(err));
+    });
+}
+// Resolve relative paths to full URLs
+function resolveUrls(faceKeys) {
+    const PUBLIC_BASE = getPublicBase();
+    // Every face is set below.
+    const resolved = {};
+    FACE_ORDER.forEach(face => {
+        const url = faceKeys[face];
+        if (url && url.startsWith('/')) {
+            resolved[face] = `${PUBLIC_BASE}${url}`;
+        }
+        else {
+            resolved[face] = url; // already absolute or invalid
+        }
+    });
+    return resolved;
+}
+/**
+ * Main loader function - always uses explicit face URLs.
+ * `renderer` binds the KTX2 transcoder to the right WebGL context. REQUIRED (3.0) when the KTX2
+ * path is taken — the old `window.__EW_RENDERER` fallback is gone; thread the owning view's
+ * renderer. (The PNG/JPG path is renderer-agnostic, so its absence only bites on KTX2.)
+ *
+ * - `faceKeys`: explicit face URLs; when absent they are built from `skycubeName`.
+ * - `skycubeName`: skybox id (e.g. `'001'`), used when `faceKeys` is absent.
+ * - `preferKTX2` (true).
+ * - `forceLow`: force (or forbid) the low-resolution faces; omitted = detect the device.
+ *
+ * Resolves to what `setBackground` takes.
+ */
+export async function loadCubeMap({ faceKeys, skycubeName, preferKTX2 = true, forceLow, renderer, } = {}) {
+    // If no face URLs provided, build them from skycube name
+    if (!faceKeys && skycubeName) {
+        const low = typeof forceLow === 'boolean' ? forceLow : isLowPerformanceDevice();
+        const extension = preferKTX2 ? 'ktx2' : 'jpg';
+        const id = normalizeSkycubeName(skycubeName);
+        const suffix = low ? '_low' : '';
+        const relativePath = `/default/skybox/${id}${suffix}`;
+        faceKeys = {
+            right: `${relativePath}/right.${extension}`,
+            left: `${relativePath}/left.${extension}`,
+            top: `${relativePath}/top.${extension}`,
+            bottom: `${relativePath}/bottom.${extension}`,
+            front: `${relativePath}/front.${extension}`,
+            back: `${relativePath}/back.${extension}`
+        };
+    }
+    if (!validatefaceKeys(faceKeys)) {
+        throw new Error('Invalid face URLs provided');
+    }
+    // Resolve relative paths to full URLs
+    const resolvedUrls = resolveUrls(faceKeys);
+    const extension = detectExtension(resolvedUrls);
+    // Try KTX2 first if preferred and supported
+    if (preferKTX2 && extension === 'ktx2' && renderer) {
+        try {
+            return await loadFacesKTX2(resolvedUrls, renderer);
+        }
+        catch (e) {
+            console.warn('[CubeMapLoader] KTX2 load failed, trying PNG fallback:', e);
+            // Fall through to PNG attempt
+        }
+    }
+    // Try PNG fallback (convert URLs if needed)
+    // Every face is set below.
+    const pngUrls = {};
+    FACE_ORDER.forEach(face => {
+        pngUrls[face] = resolvedUrls[face].replace(/\.ktx2$/, '.png');
+    });
+    try {
+        return await loadFacesJPG(pngUrls);
+    }
+    catch (e) {
+        console.error('[CubeMapLoader] All loading attempts failed:', e);
+        throw new Error('Failed to load cube map with any format');
+    }
+}
+// Dispose helpers to ensure clean swaps
+function disposeSkyboxMesh(mesh) {
+    try {
+        // The skybox mesh's materials are the MeshBasicMaterials `loadFacesKTX2` made.
+        const material = mesh.material;
+        const mats = Array.isArray(material) ? material : [material];
+        mats.forEach(mat => {
+            if (!mat)
+                return;
+            if (mat.map && mat.map.dispose)
+                mat.map.dispose();
+            if (mat.dispose)
+                mat.dispose();
+        });
+        if (mesh.geometry && mesh.geometry.dispose)
+            mesh.geometry.dispose();
+    }
+    catch (e) {
+        console.warn('[CubeMapLoader] Disposal error:', e);
+    }
+}
+/**
+ * Show a loaded skybox as the scene's background. A previous skybox mesh or cube-texture background is
+ * disposed (a plain-texture background is not). Takes what `loadCubeMap` resolved to (or any texture);
+ * anything else, `null` included, clears it.
+ *
+ */
+export function setBackground(scene, resource) {
+    const sky = scene;
+    // Read as whatever it may be: a skybox wrapper, a texture, or anything else (which clears).
+    const res = resource;
+    // Clean up previous skybox mesh
+    if (sky.__EW_SKYBOX_MESH && sky.__EW_SKYBOX_MESH.parent === scene) {
+        const oldMesh = sky.__EW_SKYBOX_MESH;
+        scene.remove(oldMesh);
+        disposeSkyboxMesh(oldMesh);
+        sky.__EW_SKYBOX_MESH = null;
+    }
+    // Dispose previous CubeTexture background
+    // A Color or a Texture; `dispose` is only called once it is a CubeTexture.
+    const background = scene.background;
+    if (background && background.isCubeTexture) {
+        try {
+            background.dispose();
+        }
+        catch (e) {
+            console.warn('[CubeMapLoader] Background disposal error:', e);
+        }
+    }
+    // Set new background
+    if (res?.__ewType === 'skybox-mesh') {
+        scene.background = null;
+        sky.__EW_SKYBOX_MESH = res.mesh;
+        scene.add(res.mesh);
+    }
+    else if (res?.isCubeTexture || res?.isTexture) {
+        scene.background = resource;
+    }
+    else {
+        scene.background = null;
+    }
+    // Dispatch update event for reactive systems
+    try {
+        window.dispatchEvent(new CustomEvent('ew:skycube-updated', {
+            detail: { type: res?.__ewType || 'texture' }
+        }));
+    }
+    catch (e) {
+        console.warn('[CubeMapLoader] Event dispatch error:', e);
+    }
+}
+export async function initSpaceScene(scene, { renderer } = {}) {
+    const faceKeys = buildSkycubefaceKeys('001');
+    const cube = await loadCubeMap({ faceKeys, preferKTX2: true, renderer });
+    setBackground(scene, cube);
+}

package/dist/loaders/glbLoader.d.ts

@@ -0,0 +1,24 @@
+import * as THREE from 'three';
+import { type MaterialFlags } from '../utils/materials.js';
+/**
+ * `renderer` is REQUIRED at runtime (throws without one).
+ * - `retries` (3): load attempts before giving up.
+ * - `signal`: rejects the load on abort.
+ * - `applyFlags`: material flags (`forceOpaque`, `wireframe`) applied to every mesh.
+ * - `withCredentials` (false).
+ * - `emissiveIntensity` (1): self-glow of textured materials (their map doubles as the emissive
+ *   map). 1 keeps the old flat-lit look; with a directional star light pass ≈0.1–0.15 so the night
+ *   side reads.
+ * - `renderer`: REQUIRED (3.0): the renderer this GLB's textures bind to. A page with several
+ *   renderers has no single correct global, so the old `window.__EW_RENDERER` fallback is gone —
+ *   thread the owning view's renderer.
+ */
+export declare function loadGLB(url: string, { retries, signal, onProgress, applyFlags, withCredentials, renderer, emissiveIntensity, }?: {
+    retries?: number | undefined;
+    signal?: AbortSignal | undefined;
+    onProgress?: ((event: ProgressEvent) => void) | undefined;
+    applyFlags?: MaterialFlags | undefined;
+    withCredentials?: boolean | undefined;
+    emissiveIntensity?: number | undefined;
+    renderer: THREE.WebGLRenderer;
+}): Promise<THREE.Group | undefined>;

package/dist/loaders/glbLoader.js

@@ -0,0 +1,72 @@
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { ensureStandardMaterial, applyFlagsToMaterial } from '../utils/materials.js';
+import { getKTX2LoaderForRenderer } from './ktx2.js';
+/**
+ * `renderer` is REQUIRED at runtime (throws without one).
+ * - `retries` (3): load attempts before giving up.
+ * - `signal`: rejects the load on abort.
+ * - `applyFlags`: material flags (`forceOpaque`, `wireframe`) applied to every mesh.
+ * - `withCredentials` (false).
+ * - `emissiveIntensity` (1): self-glow of textured materials (their map doubles as the emissive
+ *   map). 1 keeps the old flat-lit look; with a directional star light pass ≈0.1–0.15 so the night
+ *   side reads.
+ * - `renderer`: REQUIRED (3.0): the renderer this GLB's textures bind to. A page with several
+ *   renderers has no single correct global, so the old `window.__EW_RENDERER` fallback is gone —
+ *   thread the owning view's renderer.
+ */
+export async function loadGLB(url, { retries = 3, signal, onProgress, applyFlags, withCredentials = false, renderer, emissiveIntensity = 1.0, } = {}) {
+    if (!renderer)
+        throw new Error('[glb] loadGLB requires the owning renderer (KTX2 textures bind per WebGL context).');
+    let attempt = 0;
+    while (attempt < retries) {
+        try {
+            const loader = new GLTFLoader()
+                .setCrossOrigin(withCredentials ? 'use-credentials' : 'anonymous')
+                .setWithCredentials(Boolean(withCredentials))
+                .setKTX2Loader(getKTX2LoaderForRenderer(renderer));
+            const root = await new Promise((resolve, reject) => {
+                loader.load(url, (gltf) => resolve(gltf.scene), onProgress, reject);
+                if (signal) {
+                    signal.addEventListener('abort', () => reject(new Error('aborted')));
+                }
+            });
+            // Post-process materials
+            root.traverse((object) => {
+                // The meshes a GLB loads carry one material each, and `ensureStandardMaterial` just made it a
+                // MeshStandardMaterial, which is what the lines below write to.
+                const child = object;
+                if (child.isMesh && child.material) {
+                    ensureStandardMaterial(child);
+                    if (applyFlags)
+                        applyFlagsToMaterial(child.material, applyFlags);
+                    // Force texture updates for KTX2
+                    if (child.material.map) {
+                        child.material.map.anisotropy = Math.min(8, renderer.capabilities.getMaxAnisotropy());
+                        child.material.map.needsUpdate = true;
+                        // Ensure proper color space for compressed textures
+                        child.material.map.colorSpace = THREE.SRGBColorSpace;
+                        // Ensure material color doesn't block the texture
+                        child.material.color.setHex(0xffffff);
+                        // Add strong emissive to ensure visibility
+                        child.material.emissive.setHex(0x888888);
+                        child.material.emissiveMap = child.material.map;
+                        child.material.emissiveIntensity = Number.isFinite(emissiveIntensity) ? Math.max(0, emissiveIntensity) : 1.0;
+                    }
+                    child.material.needsUpdate = true;
+                    child.castShadow = false;
+                    child.receiveShadow = false;
+                }
+            });
+            root.position.set(0, 0, 0);
+            return root;
+        }
+        catch (e) {
+            console.warn(`GLB load attempt ${attempt + 1} failed:`, e.message);
+            if (signal?.aborted || attempt >= retries - 1)
+                throw e;
+            attempt++;
+            await new Promise(resolve => setTimeout(resolve, 500)); // Brief delay between retries
+        }
+    }
+}

package/dist/loaders/index.d.ts

@@ -0,0 +1,5 @@
+export { loadCubeMap, setBackground, normalizeSkycubeName, buildSkycubefaceKeys } from './cubeMapLoader.js';
+export { loadGLB } from './glbLoader.js';
+export { loadTexture } from './bodyTextureLoader.js';
+export { getKTX2LoaderForRenderer, disposeKTX2LoaderForRenderer } from './ktx2.js';
+export type { SkyboxResource } from './cubeMapLoader.js';

package/{src → dist}/loaders/index.js

@@ -2,4 +2,4 @@
 export { loadCubeMap, setBackground, normalizeSkycubeName, buildSkycubefaceKeys } from './cubeMapLoader.js';
 export { loadGLB } from './glbLoader.js';
 export { loadTexture } from './bodyTextureLoader.js';
-export { getKTX2LoaderForRenderer, disposeKTX2LoaderForRenderer } from './ktx2.js';
+export { getKTX2LoaderForRenderer, disposeKTX2LoaderForRenderer } from './ktx2.js';

package/dist/loaders/ktx2.d.ts

@@ -0,0 +1,14 @@
+import type * as THREE from 'three';
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+/**
+ * The KTX2Loader bound to `renderer` — REQUIRED (3.0). The old `window.__EW_RENDERER` fallback let
+ * call sites compile while silently binding the transcoder to whichever renderer a page published
+ * last; on any multi-view page that meant untextured worlds. Every caller now threads its own
+ * renderer, so a missing one is a caller bug and fails loudly here rather than as a dark planet.
+ */
+export declare function getKTX2LoaderForRenderer(renderer: THREE.WebGLRenderer): KTX2Loader;
+/**
+ * Dispose and forget the KTX2Loader for a renderer — call on that renderer's / scene's teardown so the
+ * transcoder workers are terminated (avoids leaking worker threads + GPU memory across view churn).
+ */
+export declare function disposeKTX2LoaderForRenderer(renderer: THREE.WebGLRenderer): void;

package/dist/loaders/ktx2.js

@@ -0,0 +1,48 @@
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+/**
+ * One KTX2Loader PER RENDERER.
+ *
+ * `KTX2Loader.detectSupport(renderer)` binds the loader's Basis transcoder worker pool to ONE WebGL
+ * context. A single shared loader therefore only decodes textures for the FIRST renderer it saw —
+ * every other view's planets/skyboxes silently fail and render untextured (dark). That breaks any
+ * multi-view page: N orbiters in one realm, or N Entangled World planets shown together.
+ *
+ * Keying the loader by renderer gives each view its own correctly-bound loader. Single-renderer apps
+ * (a single orbiter, today's Entangled World) get exactly ONE entry, so behaviour is byte-identical.
+ * (Was: a single `window.__EW_KTX2_LOADER` global shared by bodyTexture/glb/cubeMap loaders.)
+ */
+const loadersByRenderer = new WeakMap();
+function makeLoader(renderer) {
+    return new KTX2Loader().setTranscoderPath('/basis/').detectSupport(renderer);
+}
+/**
+ * The KTX2Loader bound to `renderer` — REQUIRED (3.0). The old `window.__EW_RENDERER` fallback let
+ * call sites compile while silently binding the transcoder to whichever renderer a page published
+ * last; on any multi-view page that meant untextured worlds. Every caller now threads its own
+ * renderer, so a missing one is a caller bug and fails loudly here rather than as a dark planet.
+ */
+export function getKTX2LoaderForRenderer(renderer) {
+    if (!renderer) {
+        throw new Error('[ktx2] getKTX2LoaderForRenderer requires the owning renderer — thread it from the view that renders this texture.');
+    }
+    let loader = loadersByRenderer.get(renderer);
+    if (!loader) {
+        loader = makeLoader(renderer);
+        loadersByRenderer.set(renderer, loader);
+    }
+    return loader;
+}
+/**
+ * Dispose and forget the KTX2Loader for a renderer — call on that renderer's / scene's teardown so the
+ * transcoder workers are terminated (avoids leaking worker threads + GPU memory across view churn).
+ */
+export function disposeKTX2LoaderForRenderer(renderer) {
+    const loader = renderer && loadersByRenderer.get(renderer);
+    if (loader) {
+        try {
+            loader.dispose?.();
+        }
+        catch { /* already gone */ }
+        loadersByRenderer.delete(renderer);
+    }
+}

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';