entangled-worlds-orbiters-shared 5.1.0 → 6.0.0

package/README.md

@@ -6,7 +6,7 @@ A shared library containing core components for 3D world rendering, moons system
 
 - **World System**: Core world rendering with textured spheres, normal materials, GLB models, and cloud shells
 - **Moons System**: Orbital moon generation and management
-- **Loaders**: Texture, GLB, and cubemap loading utilities
+- **Loaders**: Texture and GLB loading utilities
 - **Core Rendering**: Lighting, Fresnel effects, and material utilities
 - **Configuration**: Texture and configuration management system
 
@@ -57,7 +57,6 @@ import * as EntangledWorlds from 'entangled-worlds-orbiters-shared';
 - `moonsGeneration` - Moon generation logic
 
 ### Loaders
-- `cubeMapLoader` - Skybox loading
 - `glbLoader` - GLB loading utilities
 - `bodyTextureLoader` - Texture loading
 
@@ -150,7 +149,7 @@ Defaults:
 
 Effects:
 - All URLs returned by `config/textureConfig` helpers are absolute.
-- Skybox loader and moons generation resolve relative paths against the configured base.
+- Moons generation resolves relative paths against the configured base.
 - Cloud shell textures passed to `world.makeSphere` are resolved to absolute URLs.
 
 ## Peer Dependencies

package/dist/config/index.d.ts

@@ -1,3 +1,3 @@
-export { loadTextureConfig, getTextureOptions, getTextureChoices, getDefaultTexture, getSkyboxOptions, getDefaultSkybox, getTextureFallbackUrl } from './textureConfig.js';
+export { loadTextureConfig, getTextureOptions, getTextureChoices, getDefaultTexture, getTextureFallbackUrl } from './textureConfig.js';
 export type { TextureConfig, TextureCategory, TextureItem, TextureChoice, TextureConfigMetadata } from './textureConfig.js';
 export { setPublicBase, getPublicBase, resolvePublicUrl } from './env.js';

package/dist/config/index.js

@@ -1,4 +1,4 @@
 // Configuration exports
-export { loadTextureConfig, getTextureOptions, getTextureChoices, getDefaultTexture, getSkyboxOptions, getDefaultSkybox, getTextureFallbackUrl } from './textureConfig.js';
+export { loadTextureConfig, getTextureOptions, getTextureChoices, getDefaultTexture, getTextureFallbackUrl } from './textureConfig.js';
 // runtime base helpers
 export { setPublicBase, getPublicBase, resolvePublicUrl } from './env.js';

package/dist/config/textureConfig.d.ts

@@ -9,12 +9,11 @@ export interface TextureItem {
     fallback?: string;
     tags?: string[];
 }
-/** One catalogue category (clouds, moons, skyboxes, …). */
+/** One catalogue category (clouds, moons, …). */
 export interface TextureCategory {
     category?: string;
     basePath?: string;
     defaultTexture?: string;
-    defaultSkybox?: string;
     items?: TextureItem[];
 }
 /** The texture catalogue as loaded from the config URL. */
@@ -70,7 +69,7 @@ export type TextureChoice = {
 export declare function getTextureChoices(category: string, config?: TextureConfig | null): Promise<TextureChoice[]>;
 /**
  * Get texture options for a specific category (clouds, moons, etc.)
- * @param {string} category - Texture category (clouds, moons, skyboxes)
+ * @param {string} category - Texture category (clouds, moons)
  * @param {TextureConfig} config - Optional pre-loaded config object
  * @returns {Promise<Record<string, string>>} `{ label: url }`, suitable for dropdown option lists
  */
@@ -114,18 +113,6 @@ export declare function getTextureUrl(category: string, textureId: string, confi
  * @returns {Promise<TextureItem[]>} Array of matching texture definitions
  */
 export declare function searchTexturesByTags(category: string, tags: string[], config?: TextureConfig | null): Promise<TextureItem[]>;
-/**
- * Get skybox options formatted for GUI dropdowns
- * @param {TextureConfig} config - Optional pre-loaded config object
- * @returns {Promise<Record<string, string>>} `{ label: id }`
- */
-export declare function getSkyboxOptions(config?: TextureConfig | null): Promise<Record<string, string>>;
-/**
- * Get default skybox ID
- * @param {TextureConfig} config - Optional pre-loaded config object
- * @returns {Promise<string>} Default skybox ID
- */
-export declare function getDefaultSkybox(config?: TextureConfig | null): Promise<string>;
 /**
  * Reload configuration (force refresh)
  * @param {string} configUrl - Override config URL

package/dist/config/textureConfig.js

@@ -117,7 +117,7 @@ export async function getTextureChoices(category, config) {
 }
 /**
  * Get texture options for a specific category (clouds, moons, etc.)
- * @param {string} category - Texture category (clouds, moons, skyboxes)
+ * @param {string} category - Texture category (clouds, moons)
  * @param {TextureConfig} config - Optional pre-loaded config object
  * @returns {Promise<Record<string, string>>} `{ label: url }`, suitable for dropdown option lists
  */
@@ -215,40 +215,6 @@ export async function searchTexturesByTags(category, tags, config) {
     }
     return categoryConfig.items.filter(item => item.tags && tags.some(tag => item.tags.includes(tag)));
 }
-/**
- * Get skybox options formatted for GUI dropdowns
- * @param {TextureConfig} config - Optional pre-loaded config object
- * @returns {Promise<Record<string, string>>} `{ label: id }`
- */
-export async function getSkyboxOptions(config) {
-    const textureConfig = await resolveConfig(config);
-    const skyboxConfig = textureConfig.textures.skyboxes;
-    if (!skyboxConfig) {
-        console.warn('[TextureConfig] Skyboxes category not found');
-        return {};
-    }
-    const options = {};
-    // Reads `items` unguarded, unlike the other readers: a skyboxes category without items throws here.
-    skyboxConfig.items.forEach(item => {
-        const label = item.label || item.id;
-        const id = item.id;
-        options[label] = id;
-    });
-    return options;
-}
-/**
- * Get default skybox ID
- * @param {TextureConfig} config - Optional pre-loaded config object
- * @returns {Promise<string>} Default skybox ID
- */
-export async function getDefaultSkybox(config) {
-    const textureConfig = await resolveConfig(config);
-    const skyboxConfig = textureConfig.textures.skyboxes;
-    if (!skyboxConfig) {
-        return '001'; // fallback
-    }
-    return skyboxConfig.defaultSkybox || '001';
-}
 /**
  * Hardcoded fallback configuration (minimal)
  * Used when remote config loading fails
@@ -275,14 +241,6 @@ function getHardcodedFallback() {
                 items: [
                     { id: "default-moon", filename: "moon-equirectangular.ktx2", label: "Default Moon", tags: ["lunar"] }
                 ]
-            },
-            skyboxes: {
-                category: "environment",
-                basePath: "/skybox",
-                defaultSkybox: "001",
-                items: [
-                    { id: "001", label: "Deep Space", tags: ["space"] }
-                ]
             }
         }
     };

package/dist/loaders/index.d.ts

@@ -1,5 +1,3 @@
-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/dist/loaders/index.js

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

package/dist/loaders/ktx2.js

@@ -4,12 +4,12 @@ import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
  *
  * `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
+ * every other view's planets 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.)
+ * (Was: a single `window.__EW_KTX2_LOADER` global shared by the bodyTexture/glb loaders.)
  */
 const loadersByRenderer = new WeakMap();
 function makeLoader(renderer) {

package/dist/sky/index.js

@@ -1,6 +1,6 @@
 // ./sky — the sky behind a world: a parametric star field (seeded, or the world's own sky as seen
 // from its host star, read from the backend's precomputed file), an optional nebula + Milky Way
-// baked once per change, and constellation figures. Replaces the six-face painted skycube.
+// baked once per change, and constellation figures.
 export { createSky } from './sky.js';
 export { DEFAULT_SKY_PARAMS, SKY_PARAM_RANGES, SKY_LOOK_KEYS, SKY_SHAPE_KEYS, normalizeSkyParams, } from './params.js';
 export { parseWorldSky, WORLD_SKY_MAGIC, WORLD_SKY_FORMAT } from './worldSkyFile.js';

package/dist/sky/sky.js

@@ -4,7 +4,7 @@
 // LineSegments). All three draw after the opaque bodies with depth test
 // on, so sky behind a planet costs nothing.
 //
-// Cost, measured against the six-face painted skycube it replaces (bench/sky): stars alone about
+// Cost, measured against the six-face painted sky it replaced (bench/sky/results): stars alone about
 // 40% of its frame time; with the nebula about the same frame time, at 1/5–1/15 of its GPU memory
 // and with nothing to download.
 import * as THREE from 'three';

package/dist/star/bounds.d.ts

@@ -30,7 +30,7 @@ export interface MinStarDistanceInput extends Partial<SceneSizes> {
  * that the primary spans at most `MAX_STAR_ANGULAR_RADIUS_DEG`. Pure.
  */
 export declare function minStarDistance(input: MinStarDistanceInput): number;
-/** Sky margin: the system keeps this fraction of the sky radius clear of the skybox. */
+/** Sky margin: the system keeps this fraction of the sky radius clear of the sky. */
 export declare const SKY_MARGIN_FRACTION = 0.02;
 /**
  * Farthest barycentre distance that keeps a system of `systemExtent` inside a sky of `skyRadius`

package/dist/star/bounds.js

@@ -34,7 +34,7 @@ export function minStarDistance(input) {
     const angular = pos(input.primaryRadius, 0) / Math.tan((MAX_STAR_ANGULAR_RADIUS_DEG * Math.PI) / 180);
     return Math.max(clear, angular);
 }
-/** Sky margin: the system keeps this fraction of the sky radius clear of the skybox. */
+/** Sky margin: the system keeps this fraction of the sky radius clear of the sky. */
 export const SKY_MARGIN_FRACTION = 0.02;
 /**
  * Farthest barycentre distance that keeps a system of `systemExtent` inside a sky of `skyRadius`

package/dist/star/params.d.ts

@@ -45,7 +45,7 @@ export declare const DEFAULT_STAR_PARAMS: Readonly<StarParams>;
 /**
  * Accepted ranges; values outside are clamped (azimuth wraps). Sized so the star reads as a
  * background host star: at the minimum (and default) distance the largest radius spans ~10° from the
- * planet, 220 stays inside a 500-unit skybox, and no distance puts it among the planet's moons (hosts pass their scene size to StarManager for the
+ * planet, 220 stays inside a 500-unit sky, and no distance puts it among the planet's moons (hosts pass their scene size to StarManager for the
  * exact, non-colliding minimum — see `minStarDistance`).
  */
 export declare const STAR_PARAM_RANGES: Readonly<{

package/dist/star/params.js

@@ -26,7 +26,7 @@ export const DEFAULT_STAR_PARAMS = Object.freeze({
 /**
  * Accepted ranges; values outside are clamped (azimuth wraps). Sized so the star reads as a
  * background host star: at the minimum (and default) distance the largest radius spans ~10° from the
- * planet, 220 stays inside a 500-unit skybox, and no distance puts it among the planet's moons (hosts pass their scene size to StarManager for the
+ * planet, 220 stays inside a 500-unit sky, and no distance puts it among the planet's moons (hosts pass their scene size to StarManager for the
  * exact, non-colliding minimum — see `minStarDistance`).
  */
 export const STAR_PARAM_RANGES = Object.freeze({

package/dist/star/starBody.d.ts

@@ -30,7 +30,7 @@ export interface StarBody {
     setMinDistance(d: number): void;
     /**
      * Upper bound for the barycentre distance (0 / Infinity = none), e.g. to stay inside the host's
-     * skybox. The minimum wins when the two conflict.
+     * sky. The minimum wins when the two conflict.
      */
     setMaxDistance(d: number): void;
     /** The distance actually used: max(minDistance, min(params.distance, maxDistance)). */

package/dist/star/starManager.d.ts

@@ -6,7 +6,7 @@ import { type StarQuality } from './quality.js';
 import { type MinStarDistanceInput } from './bounds.js';
 /** The host's scene sizes: `outerRadius` directly, or the planet/glow/moon sizes to derive it. */
 export type StarSceneBounds = Pick<MinStarDistanceInput, 'planetRadius' | 'moonOrbitRadius' | 'moonRadius' | 'cloudOrGlowScale' | 'outerRadius' | 'margin'> & {
-    /** Radius of the host's sky (e.g. 250 for a 500-unit skybox): the whole system stays inside it. */
+    /** Radius of the host's sky (e.g. 250 for a 500-unit sky): the whole system stays inside it. */
     skyRadius?: number;
 };
 export interface StarManagerOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "5.1.0",
+  "version": "6.0.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "dist/index.js",

package/public/config/textures.json

@@ -286,79 +286,6 @@
           "fallback": "silver-glow.jpg"
         }
       ]
-    },
-    "skyboxes": {
-      "category": "environment",
-      "basePath": "/skybox",
-      "defaultSkybox": "001",
-      "items": [
-        {
-          "id": "001",
-          "label": "Deep Space",
-          "description": "Deep space with distant stars",
-          "tags": ["space", "dark", "minimal"]
-        },
-        {
-          "id": "002",
-          "label": "Nebula Field",
-          "description": "Colorful nebula formations",
-          "tags": ["nebula", "colorful", "cosmic"]
-        },
-        {
-          "id": "003",
-          "label": "Galaxy Center",
-          "description": "Dense galactic core region",
-          "tags": ["galaxy", "dense", "bright"]
-        },
-        {
-          "id": "004",
-          "label": "Binary System",
-          "description": "Binary star system environment",
-          "tags": ["binary", "stars", "orange"]
-        },
-        {
-          "id": "005",
-          "label": "Cosmic Web",
-          "description": "Large-scale cosmic structure",
-          "tags": ["cosmic", "web", "structure"]
-        },
-        {
-          "id": "006",
-          "label": "Stellar Nursery",
-          "description": "Star formation region",
-          "tags": ["formation", "young", "bright"]
-        },
-        {
-          "id": "007",
-          "label": "Dark Matter",
-          "description": "Dark matter visualization",
-          "tags": ["dark", "matter", "theoretical"]
-        },
-        {
-          "id": "008",
-          "label": "Quantum Foam",
-          "description": "Quantum scale space-time",
-          "tags": ["quantum", "foam", "microscopic"]
-        },
-        {
-          "id": "009",
-          "label": "Event Horizon",
-          "description": "Black hole event horizon",
-          "tags": ["black hole", "horizon", "gravity"]
-        },
-        {
-          "id": "010",
-          "label": "Multiverse",
-          "description": "Multiple universe visualization",
-          "tags": ["multiverse", "infinite", "parallel"]
-        },
-        {
-          "id": "011",
-          "label": "Void Space",
-          "description": "Empty cosmic void region",
-          "tags": ["void", "empty", "minimal"]
-        }
-      ]
     }
   }
 }

package/src/config/index.ts

@@ -4,8 +4,6 @@ export {
   getTextureOptions,
   getTextureChoices,
   getDefaultTexture,
-  getSkyboxOptions, 
-  getDefaultSkybox,
   getTextureFallbackUrl
 } from './textureConfig.js';
 export type {

package/src/config/textureConfig.ts

@@ -16,12 +16,11 @@ export interface TextureItem {
   tags?: string[];
 }
 
-/** One catalogue category (clouds, moons, skyboxes, …). */
+/** One catalogue category (clouds, moons, …). */
 export interface TextureCategory {
   category?: string;
   basePath?: string;
   defaultTexture?: string;
-  defaultSkybox?: string;
   items?: TextureItem[];
 }
 
@@ -196,7 +195,7 @@ export async function getTextureChoices(category: string, config?: TextureConfig
 
 /**
  * Get texture options for a specific category (clouds, moons, etc.)
- * @param {string} category - Texture category (clouds, moons, skyboxes)
+ * @param {string} category - Texture category (clouds, moons)
  * @param {TextureConfig} config - Optional pre-loaded config object
  * @returns {Promise<Record<string, string>>} `{ label: url }`, suitable for dropdown option lists
  */
@@ -309,48 +308,6 @@ export async function searchTexturesByTags(category: string, tags: string[], con
   );
 }
 
-/**
- * Get skybox options formatted for GUI dropdowns
- * @param {TextureConfig} config - Optional pre-loaded config object
- * @returns {Promise<Record<string, string>>} `{ label: id }`
- */
-export async function getSkyboxOptions(config?: TextureConfig | null): Promise<Record<string, string>> {
-  const textureConfig = await resolveConfig(config);
-  const skyboxConfig = textureConfig.textures.skyboxes;
-  
-  if (!skyboxConfig) {
-    console.warn('[TextureConfig] Skyboxes category not found');
-    return {};
-  }
-
-  const options: Record<string, string> = {};
-  
-  // Reads `items` unguarded, unlike the other readers: a skyboxes category without items throws here.
-  skyboxConfig.items!.forEach(item => {
-    const label = item.label || item.id;
-    const id = item.id;
-    options[label] = id;
-  });
-
-  return options;
-}
-
-/**
- * Get default skybox ID
- * @param {TextureConfig} config - Optional pre-loaded config object
- * @returns {Promise<string>} Default skybox ID
- */
-export async function getDefaultSkybox(config?: TextureConfig | null): Promise<string> {
-  const textureConfig = await resolveConfig(config);
-  const skyboxConfig = textureConfig.textures.skyboxes;
-  
-  if (!skyboxConfig) {
-    return '001'; // fallback
-  }
-
-  return skyboxConfig.defaultSkybox || '001';
-}
-
 /**
  * Hardcoded fallback configuration (minimal)
  * Used when remote config loading fails
@@ -377,14 +334,6 @@ function getHardcodedFallback(): TextureConfig {
         items: [
           { id: "default-moon", filename: "moon-equirectangular.ktx2", label: "Default Moon", tags: ["lunar"] }
         ]
-      },
-      skyboxes: {
-        category: "environment",
-        basePath: "/skybox",
-        defaultSkybox: "001",
-        items: [
-          { id: "001", label: "Deep Space", tags: ["space"] }
-        ]
       }
     }
   };

package/src/loaders/index.ts

@@ -1,6 +1,4 @@
 // Loaders exports
-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/loaders/ktx2.ts

@@ -6,12 +6,12 @@ import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
  *
  * `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
+ * every other view's planets 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.)
+ * (Was: a single `window.__EW_KTX2_LOADER` global shared by the bodyTexture/glb loaders.)
  */
 const loadersByRenderer = new WeakMap<THREE.WebGLRenderer, KTX2Loader>();
 

package/src/sky/index.ts

@@ -1,6 +1,6 @@
 // ./sky — the sky behind a world: a parametric star field (seeded, or the world's own sky as seen
 // from its host star, read from the backend's precomputed file), an optional nebula + Milky Way
-// baked once per change, and constellation figures. Replaces the six-face painted skycube.
+// baked once per change, and constellation figures.
 
 export { createSky } from './sky.js';
 export type { Sky, CreateSkyOptions } from './sky.js';

package/src/sky/sky.ts

@@ -4,7 +4,7 @@
 // LineSegments). All three draw after the opaque bodies with depth test
 // on, so sky behind a planet costs nothing.
 //
-// Cost, measured against the six-face painted skycube it replaces (bench/sky): stars alone about
+// Cost, measured against the six-face painted sky it replaced (bench/sky/results): stars alone about
 // 40% of its frame time; with the nebula about the same frame time, at 1/5–1/15 of its GPU memory
 // and with nothing to download.
 

package/src/star/bounds.ts

@@ -59,7 +59,7 @@ export function minStarDistance(input: MinStarDistanceInput): number {
   return Math.max(clear, angular);
 }
 
-/** Sky margin: the system keeps this fraction of the sky radius clear of the skybox. */
+/** Sky margin: the system keeps this fraction of the sky radius clear of the sky. */
 export const SKY_MARGIN_FRACTION = 0.02;
 
 /**

package/src/star/params.ts

@@ -72,7 +72,7 @@ export const DEFAULT_STAR_PARAMS: Readonly<StarParams> = Object.freeze({
 /**
  * Accepted ranges; values outside are clamped (azimuth wraps). Sized so the star reads as a
  * background host star: at the minimum (and default) distance the largest radius spans ~10° from the
- * planet, 220 stays inside a 500-unit skybox, and no distance puts it among the planet's moons (hosts pass their scene size to StarManager for the
+ * planet, 220 stays inside a 500-unit sky, and no distance puts it among the planet's moons (hosts pass their scene size to StarManager for the
  * exact, non-colliding minimum — see `minStarDistance`).
  */
 export const STAR_PARAM_RANGES = Object.freeze({

package/src/star/starBody.ts

@@ -49,7 +49,7 @@ export interface StarBody {
   setMinDistance(d: number): void;
   /**
    * Upper bound for the barycentre distance (0 / Infinity = none), e.g. to stay inside the host's
-   * skybox. The minimum wins when the two conflict.
+   * sky. The minimum wins when the two conflict.
    */
   setMaxDistance(d: number): void;
   /** The distance actually used: max(minDistance, min(params.distance, maxDistance)). */

package/src/star/starManager.ts

@@ -30,7 +30,7 @@ import { maxStarDistance, minStarDistance, type MinStarDistanceInput } from './b
 
 /** The host's scene sizes: `outerRadius` directly, or the planet/glow/moon sizes to derive it. */
 export type StarSceneBounds = Pick<MinStarDistanceInput, 'planetRadius' | 'moonOrbitRadius' | 'moonRadius' | 'cloudOrGlowScale' | 'outerRadius' | 'margin'> & {
-  /** Radius of the host's sky (e.g. 250 for a 500-unit skybox): the whole system stays inside it. */
+  /** Radius of the host's sky (e.g. 250 for a 500-unit sky): the whole system stays inside it. */
   skyRadius?: number;
 };
 

package/dist/loaders/cubeMapLoader.d.ts

@@ -1,58 +0,0 @@
-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

@@ -1,291 +0,0 @@
-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/src/loaders/cubeMapLoader.ts

@@ -1,342 +0,0 @@
-import * as THREE from 'three';
-import { getPublicBase } from '../config/env.js';
-import { getKTX2LoaderForRenderer } from './ktx2.js';
-
-// Base URL is resolved at runtime via helper
-
-/** One skybox face, in the order cube maps list them. */
-type FaceName = 'right' | 'left' | 'top' | 'bottom' | 'front' | 'back';
-/** A URL for each of the six faces. */
-type FaceKeys = Record<FaceName, string>;
-
-/** The scene field `setBackground` keeps the current skybox mesh in. It stays a field on the scene,
- * not a private map, because the apps read it to tell whether a sky is already showing. */
-type SkyScene = THREE.Scene & { __EW_SKYBOX_MESH?: THREE.Mesh | null };
-
-/** A skycube id (`'7'`, `'07_skycube'`, `'skybox-007'`, …) as its three-digit folder name; `'001'` when none. */
-export function normalizeSkycubeName(raw: string | null | undefined): string {
-  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: FaceName[] = ['right', 'left', 'top', 'bottom', 'front', 'back'];
-
-// Build complete face URL sets for a given skycube ID (now returns relative paths)
-export function buildSkycubefaceKeys(skycubeId: string | null | undefined, 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 as Navigator & { deviceMemory?: number }).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: unknown): faceKeys is FaceKeys {
-  if (!faceKeys || typeof faceKeys !== 'object') return false;
-  const keys = faceKeys as Record<string, unknown>;
-  return FACE_ORDER.every(face => keys[face] && typeof keys[face] === 'string');
-}
-
-// Detect extension type from face URLs
-function detectExtension(faceKeys: FaceKeys): 'ktx2' | 'jpg' {
-  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: FaceKeys, renderer: THREE.WebGLRenderer): Promise<SkyboxResource> {
-  const loader = getKTX2LoaderForRenderer(renderer);
-  const anisotropy = Math.min(8, renderer.capabilities.getMaxAnisotropy());
-
-  const loadFace = async (face: FaceName) => {
-    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: Awaited<ReturnType<typeof loadFace>>[] = [];
-  let failure: unknown = 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: Record<FaceName, number> = { right:0, left:1, top:3, bottom:2, front:4, back:5 };
-  const mats: (THREE.MeshBasicMaterial | null)[] = 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 as THREE.MeshBasicMaterial[]);
-  mesh.name = 'SkyboxKTX2Mesh';
-  return { __ewType: 'skybox-mesh', mesh };
-}
-
-// Load JPG/PNG faces and create CubeTexture
-function loadFacesJPG(faceKeys: FaceKeys): Promise<THREE.CubeTexture> {
-  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: FaceKeys): FaceKeys {
-  const PUBLIC_BASE = getPublicBase();
-  // Every face is set below.
-  const resolved = {} as FaceKeys;
-  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,
-}: {
-  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> {
-
-  // 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 = {} as FaceKeys;
-  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: THREE.Mesh) {
-  try {
-    // The skybox mesh's materials are the MeshBasicMaterials `loadFacesKTX2` made.
-    const material = mesh.material as THREE.MeshBasicMaterial | THREE.MeshBasicMaterial[];
-    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);
-  }
-}
-
-/**
- * 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 function setBackground(scene: THREE.Scene, resource: unknown): void {
-  const sky = scene as SkyScene;
-  // Read as whatever it may be: a skybox wrapper, a texture, or anything else (which clears).
-  const res = resource as
-    | { __ewType?: unknown; mesh: THREE.Mesh; isCubeTexture?: boolean; isTexture?: boolean }
-    | null
-    | undefined;
-  // 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 as { isCubeTexture?: boolean; dispose(): void } | null;
-  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 as THREE.Texture;
-  } 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: THREE.Scene,
-  { renderer }: { renderer?: THREE.WebGLRenderer | null } = {},
-): Promise<void> {
-  const faceKeys = buildSkycubefaceKeys('001');
-  const cube = await loadCubeMap({ faceKeys, preferKTX2: true, renderer });
-  setBackground(scene, cube);
-}