entangled-worlds-orbiters-shared 3.3.0 → 4.0.0

package/src/config/{textureConfig.js → textureConfig.ts}

@@ -4,7 +4,57 @@
  */
 import { resolvePublicUrl } from './env.js';
 
-function buildTextureUrl(baseUrl, categoryPath, value) {
+/** One catalogue item. */
+export interface TextureItem {
+  id: string;
+  filename?: string;
+  label?: string;
+  /** Picture of the item (a thumbnail), relative like `filename`. */
+  still?: string;
+  /** Texture to use when this one fails to load, relative like `filename`. */
+  fallback?: string;
+  tags?: string[];
+}
+
+/** One catalogue category (clouds, moons, skyboxes, …). */
+export interface TextureCategory {
+  category?: string;
+  basePath?: string;
+  defaultTexture?: string;
+  defaultSkybox?: string;
+  items?: TextureItem[];
+}
+
+/** The texture catalogue as loaded from the config URL. */
+export interface TextureConfig {
+  version?: string;
+  lastUpdated?: string;
+  baseUrl?: string;
+  /** By category name; a category the catalogue does not list is missing. */
+  textures: Partial<Record<string, TextureCategory>>;
+}
+
+/** A catalogue item found by its resolved URL, with the base and path it resolved against. */
+interface FoundTextureItem {
+  item: TextureItem;
+  baseUrl: string;
+  categoryPath: string;
+}
+
+/** What `getConfigMetadata` reports about a catalogue. */
+export interface TextureConfigMetadata {
+  version: string | undefined;
+  lastUpdated: string | undefined;
+  categories: string[];
+  totalTextures: number;
+}
+
+/** The catalogue a public function was handed, or the loaded one. */
+async function resolveConfig(config: TextureConfig | null | undefined): Promise<TextureConfig> {
+  return config || (await loadTextureConfig());
+}
+
+function buildTextureUrl(baseUrl: string, categoryPath: string, value: string | undefined): string | null {
   if (!value) return null;
   if (/^https?:\/\//i.test(value)) return value;
   if (value.startsWith('/')) return resolvePublicUrl(value);
@@ -12,7 +62,7 @@ function buildTextureUrl(baseUrl, categoryPath, value) {
   return resolvePublicUrl(`${prefix}/${value}`);
 }
 
-function findTextureItem(textureConfig, category, textureUrl) {
+function findTextureItem(textureConfig: TextureConfig, category: string, textureUrl: string): FoundTextureItem | null {
   if (!textureUrl || !textureConfig) return null;
   const categoryConfig = textureConfig.textures?.[category];
   if (!categoryConfig || !categoryConfig.items) return null;
@@ -30,17 +80,17 @@ function findTextureItem(textureConfig, category, textureUrl) {
   return null;
 }
 
-let cachedConfig = null;
-let configPromise = null;
-let lastConfigUrl = null;
+let cachedConfig: TextureConfig | null = null;
+let configPromise: Promise<TextureConfig> | null = null;
+let lastConfigUrl: string | null = null;
 
 /**
  * Load texture configuration from remote endpoint or use passed config
  * @param {string} configUrl - Override config URL
  * @param {boolean} useCache - Whether to use cached config if available
- * @returns {Promise<Object>} Texture configuration object
+ * @returns {Promise<TextureConfig>} Texture configuration object
  */
-export async function loadTextureConfig(configUrl = null, useCache = true) {
+export async function loadTextureConfig(configUrl?: string, useCache = true): Promise<TextureConfig> {
   if (useCache && cachedConfig) {
     return cachedConfig;
   }
@@ -67,7 +117,7 @@ export async function loadTextureConfig(configUrl = null, useCache = true) {
         throw new Error(`HTTP ${response.status}: ${response.statusText}`);
       }
 
-      const config = await response.json();
+      const config = (await response.json()) as TextureConfig;
       
       // Validate configuration structure
       if (!config.textures || typeof config.textures !== 'object') {
@@ -80,8 +130,9 @@ export async function loadTextureConfig(configUrl = null, useCache = true) {
       console.error('[TextureConfig] Failed to load config:', error);
       // Return minimal fallback configuration when loading fails
       console.warn('[TextureConfig] Using hardcoded fallback config');
-      cachedConfig = getHardcodedFallback();
-      return cachedConfig;
+      const fallback = getHardcodedFallback();
+      cachedConfig = fallback;
+      return fallback;
     } finally {
       configPromise = null;
     }
@@ -91,28 +142,36 @@ export async function loadTextureConfig(configUrl = null, useCache = true) {
 }
 
 /**
- * @typedef {Object} TextureChoice
- * @property {string} id      Catalogue id.
- * @property {string} label   Human-readable name.
- * @property {string} url     Resolved texture URL (the .ktx2 the world renders).
- * @property {string|null} still  Resolved URL of the item's picture — a small thumbnail suitable
- *   for showing the texture in a picker. `null` when the catalogue names none.
+ * A choice record for one catalogue item.
  *
  * Every catalogue item IS a picture, so a chooser should show it rather than its name. `still` is
  * read straight from the catalogue and never derived from `filename`: the stills do not share one
  * extension, and a wrong guess fails silently (a broken `<img>` just shows nothing).
  */
+export type TextureChoice = {
+  /** Catalogue id. */
+  id: string;
+  /** Human-readable name. */
+  label: string;
+  /** Resolved texture URL (the .ktx2 the world renders). */
+  url: string;
+  /**
+   * Resolved URL of the item's picture — a small thumbnail suitable for showing the texture in a
+   * picker. `null` when the catalogue names none.
+   */
+  still: string | null;
+};
 
 /**
  * Get the full choice records for a category (clouds, moons, etc.) — label, texture URL, and the
  * picture to show for it. The single resolution point for a category's items; `getTextureOptions`
  * is the flat `{ label: url }` projection of this.
  * @param {string} category - Texture category (clouds, moons)
- * @param {Object} config - Optional pre-loaded config object
+ * @param {TextureConfig} config - Optional pre-loaded config object
  * @returns {Promise<TextureChoice[]>} Choice records in catalogue order
  */
-export async function getTextureChoices(category, config = null) {
-  const textureConfig = config || await loadTextureConfig();
+export async function getTextureChoices(category: string, config?: TextureConfig | null): Promise<TextureChoice[]> {
+  const textureConfig = await resolveConfig(config);
   const categoryConfig = textureConfig.textures[category];
 
   if (!categoryConfig) {
@@ -123,7 +182,7 @@ export async function getTextureChoices(category, config = null) {
   const baseUrl = textureConfig.baseUrl || '/default';
   const categoryPath = categoryConfig.basePath || `/${category}`;
 
-  return (categoryConfig.items || []).flatMap(item => {
+  return (categoryConfig.items || []).flatMap((item): TextureChoice[] => {
     const url = buildTextureUrl(baseUrl, categoryPath, item.filename || item.id);
     if (!url) return [];
     return [{
@@ -138,10 +197,10 @@ export async function getTextureChoices(category, config = null) {
 /**
  * Get texture options for a specific category (clouds, moons, etc.)
  * @param {string} category - Texture category (clouds, moons, skyboxes)
- * @param {Object} config - Optional pre-loaded config object
- * @returns {Promise<Object>} Options object suitable for dropdown option lists
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<Record<string, string>>} `{ label: url }`, suitable for dropdown option lists
  */
-export async function getTextureOptions(category, config = null) {
+export async function getTextureOptions(category: string, config?: TextureConfig | null): Promise<Record<string, string>> {
   const choices = await getTextureChoices(category, config);
   return Object.fromEntries(choices.map(c => [c.label, c.url]));
 }
@@ -149,11 +208,11 @@ export async function getTextureOptions(category, config = null) {
 /**
  * Get default texture for a category
  * @param {string} category - Texture category
- * @param {Object} config - Optional pre-loaded config object
- * @returns {Promise<string>} Default texture path
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<string|null>} Default texture path, or null when the category has no texture
  */
-export async function getDefaultTexture(category, config = null) {
-  const textureConfig = config || await loadTextureConfig();
+export async function getDefaultTexture(category: string, config?: TextureConfig | null): Promise<string | null> {
+  const textureConfig = await resolveConfig(config);
   const categoryConfig = textureConfig.textures[category];
   
   if (!categoryConfig) {
@@ -181,10 +240,10 @@ export async function getDefaultTexture(category, config = null) {
  * Return the configured fallback URL for a given texture if defined.
  * @param {string} category - Texture category (clouds, moons, etc.)
  * @param {string} textureUrl - Resolved texture URL
- * @param {Object|null} config - Optional texture config override
+ * @param {TextureConfig|null} config - Optional texture config override
  * @returns {string|null} Resolved fallback texture URL or null
  */
-export function getTextureFallbackUrl(category, textureUrl, config = null) {
+export function getTextureFallbackUrl(category: string, textureUrl: string, config: TextureConfig | null = null): string | null {
   const textureConfig = config || cachedConfig;
   if (!textureConfig) return null;
   const found = findTextureItem(textureConfig, category, textureUrl);
@@ -196,11 +255,11 @@ export function getTextureFallbackUrl(category, textureUrl, config = null) {
  * Get texture by ID within a category
  * @param {string} category - Texture category
  * @param {string} textureId - Texture ID
- * @param {Object} config - Optional pre-loaded config object
- * @returns {Promise<Object|null>} Texture definition object
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureItem|null>} Texture definition object
  */
-export async function getTextureById(category, textureId, config = null) {
-  const textureConfig = config || await loadTextureConfig();
+export async function getTextureById(category: string, textureId: string, config?: TextureConfig | null): Promise<TextureItem | null> {
+  const textureConfig = await resolveConfig(config);
   const categoryConfig = textureConfig.textures[category];
   
   if (!categoryConfig || !categoryConfig.items) {
@@ -214,15 +273,17 @@ export async function getTextureById(category, textureId, config = null) {
  * Get full URL for a texture
  * @param {string} category - Texture category
  * @param {string} textureId - Texture ID
- * @param {Object} config - Optional pre-loaded config object
+ * @param {TextureConfig} config - Optional pre-loaded config object
  * @returns {Promise<string|null>} Full texture URL
  */
-export async function getTextureUrl(category, textureId, config = null) {
+export async function getTextureUrl(category: string, textureId: string, config?: TextureConfig | null): Promise<string | null> {
   const texture = await getTextureById(category, textureId, config);
   if (!texture) return null;
 
-  const textureConfig = config || await loadTextureConfig();
-  const categoryConfig = textureConfig.textures[category];
+  const textureConfig = await resolveConfig(config);
+  // `getTextureById` just found the item in this category, so it is there (unless the catalogue
+  // was reloaded in between, which throws here, as it always did).
+  const categoryConfig = textureConfig.textures[category]!;
   const baseUrl = textureConfig.baseUrl || '/default';
   const categoryPath = categoryConfig.basePath || `/${category}`;
   return resolvePublicUrl(`${baseUrl}${categoryPath}/${texture.filename || texture.id}`);
@@ -232,11 +293,11 @@ export async function getTextureUrl(category, textureId, config = null) {
  * Search textures by tags
  * @param {string} category - Texture category
  * @param {string[]} tags - Tags to search for
- * @param {Object} config - Optional pre-loaded config object
- * @returns {Promise<Object[]>} Array of matching texture definitions
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureItem[]>} Array of matching texture definitions
  */
-export async function searchTexturesByTags(category, tags, config = null) {
-  const textureConfig = config || await loadTextureConfig();
+export async function searchTexturesByTags(category: string, tags: string[], config?: TextureConfig | null): Promise<TextureItem[]> {
+  const textureConfig = await resolveConfig(config);
   const categoryConfig = textureConfig.textures[category];
   
   if (!categoryConfig || !categoryConfig.items) {
@@ -244,17 +305,17 @@ export async function searchTexturesByTags(category, tags, config = null) {
   }
 
   return categoryConfig.items.filter(item => 
-    item.tags && tags.some(tag => item.tags.includes(tag))
+    item.tags && tags.some(tag => item.tags!.includes(tag))
   );
 }
 
 /**
  * Get skybox options formatted for GUI dropdowns
- * @param {Object} config - Optional pre-loaded config object
- * @returns {Promise<Object>} Options object with labels and IDs
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<Record<string, string>>} `{ label: id }`
  */
-export async function getSkyboxOptions(config = null) {
-  const textureConfig = config || await loadTextureConfig();
+export async function getSkyboxOptions(config?: TextureConfig | null): Promise<Record<string, string>> {
+  const textureConfig = await resolveConfig(config);
   const skyboxConfig = textureConfig.textures.skyboxes;
   
   if (!skyboxConfig) {
@@ -262,9 +323,10 @@ export async function getSkyboxOptions(config = null) {
     return {};
   }
 
-  const options = {};
+  const options: Record<string, string> = {};
   
-  skyboxConfig.items.forEach(item => {
+  // 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;
@@ -275,11 +337,11 @@ export async function getSkyboxOptions(config = null) {
 
 /**
  * Get default skybox ID
- * @param {Object} config - Optional pre-loaded config object
+ * @param {TextureConfig} config - Optional pre-loaded config object
  * @returns {Promise<string>} Default skybox ID
  */
-export async function getDefaultSkybox(config = null) {
-  const textureConfig = config || await loadTextureConfig();
+export async function getDefaultSkybox(config?: TextureConfig | null): Promise<string> {
+  const textureConfig = await resolveConfig(config);
   const skyboxConfig = textureConfig.textures.skyboxes;
   
   if (!skyboxConfig) {
@@ -293,7 +355,7 @@ export async function getDefaultSkybox(config = null) {
  * Hardcoded fallback configuration (minimal)
  * Used when remote config loading fails
  */
-function getHardcodedFallback() {
+function getHardcodedFallback(): TextureConfig {
   return {
     version: "1.0-fallback",
     lastUpdated: new Date().toISOString(),
@@ -331,27 +393,31 @@ function getHardcodedFallback() {
 /**
  * Reload configuration (force refresh)
  * @param {string} configUrl - Override config URL
- * @returns {Promise<Object>} Fresh configuration object
+ * @returns {Promise<TextureConfig>} Fresh configuration object
  */
-export async function reloadTextureConfig(configUrl = null) {
+export async function reloadTextureConfig(configUrl?: string): Promise<TextureConfig> {
   cachedConfig = null;
   configPromise = null;
-  return loadTextureConfig(configUrl || lastConfigUrl, false);
+  return loadTextureConfig(configUrl || lastConfigUrl || undefined, false);
 }
 
 /**
  * Get configuration metadata
- * @param {Object} config - Optional pre-loaded config object
- * @returns {Promise<Object>} Configuration metadata
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureConfigMetadata>} Configuration metadata
  */
-export async function getConfigMetadata(config = null) {
-  const textureConfig = config || await loadTextureConfig();
+export async function getConfigMetadata(config?: TextureConfig | null): Promise<TextureConfigMetadata> {
+  const textureConfig = await resolveConfig(config);
   return {
     version: textureConfig.version,
     lastUpdated: textureConfig.lastUpdated,
     categories: Object.keys(textureConfig.textures),
     totalTextures: Object.values(textureConfig.textures).reduce(
-      (sum, cat) => sum + (cat.items ? cat.items.length : 0), 0
+      // Only listed categories are values; a missing one is a key that is not there.
+      (sum, cat) => {
+        const items = (cat as TextureCategory).items;
+        return sum + (items ? items.length : 0);
+      }, 0
     )
   };
 }

package/src/core/{lightFresnel.js → lightFresnel.ts}

@@ -1,6 +1,6 @@
 import * as THREE from "three";
 
-function getLightFresnel({rimHex = 0x0088ff, facingHex = 0x000000} = {}) {
+function getLightFresnel({ rimHex = 0x0088ff, facingHex = 0x000000 }: { rimHex?: number; facingHex?: number } = {}): THREE.ShaderMaterial {
   const uniforms = {
     color1: { value: new THREE.Color(rimHex) },
     color2: { value: new THREE.Color(facingHex) },

package/src/core/{lights.js → lights.ts}

@@ -8,19 +8,17 @@ import * as THREE from 'three';
  * 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.
- *
- * @param {import('three').Scene} scene
- * @returns {{ hemi: import('three').HemisphereLight, ambient: import('three').AmbientLight }}
  */
-export function ensureDefaultLights(scene) {
-  let hemi = scene.getObjectByName('ew_HemisphereLight');
+export function ensureDefaultLights(scene: THREE.Scene): { hemi: THREE.HemisphereLight; ambient: THREE.AmbientLight } {
+  // Found by name: the objects under these names are the lights this function added.
+  let hemi = scene.getObjectByName('ew_HemisphereLight') as THREE.HemisphereLight | undefined;
   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');
+  let ambient = scene.getObjectByName('ew_AmbientLight') as THREE.AmbientLight | undefined;
   if (!ambient) {
     ambient = new THREE.AmbientLight(0xffffff, 1.0);
     ambient.name = 'ew_AmbientLight';
@@ -37,16 +35,22 @@ export function ensureDefaultLights(scene) {
  * 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.
- *
- * @param {import('three').Scene} scene
- * @param {object} [patch]
- * @param {number} [patch.ambientIntensity] ambient light intensity (clamped at 0)
- * @param {number} [patch.diffuseIntensity] hemisphere light intensity (clamped at 0)
- * @param {import('three').Color | number | string} [patch.lightColor] hemisphere light colour
- * @param {{ x: number, y?: number, z?: number }} [patch.lightDirection] hemisphere light direction
- * @param {boolean} [patch.hemisphere] switch the hemisphere light on or off
  */
-export function updateDefaultLights(scene, { ambientIntensity, diffuseIntensity, lightColor, lightDirection, hemisphere } = {}) {
+export function updateDefaultLights(
+  scene: THREE.Scene,
+  { ambientIntensity, diffuseIntensity, lightColor, lightDirection, hemisphere }: {
+    /** ambient light intensity (clamped at 0) */
+    ambientIntensity?: number;
+    /** hemisphere light intensity (clamped at 0) */
+    diffuseIntensity?: number;
+    /** hemisphere light colour */
+    lightColor?: THREE.Color | number | string;
+    /** hemisphere light direction */
+    lightDirection?: { x: number; y?: number; z?: number };
+    /** switch the hemisphere light on or off */
+    hemisphere?: boolean;
+  } = {},
+): void {
   if (!scene?.isObject3D) {
     console.error('[lights] updateDefaultLights(scene, patch) requires the scene to update; ignoring patch.');
     return;
@@ -75,18 +79,14 @@ export function updateDefaultLights(scene, { ambientIntensity, diffuseIntensity,
 /**
  * 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.
- *
- * @param {import('three').Scene} scene
- * @param {boolean} on
  */
-export function setHemisphereEnabled(scene, on) {
+export function setHemisphereEnabled(scene: THREE.Scene, on: boolean): void {
   if (!scene?.isObject3D) return;
   const { hemi } = ensureDefaultLights(scene);
   hemi.visible = Boolean(on);
 }
 
 // Back-compat helper
-/** @param {import('three').Scene} scene */
-export function addDefaultLights(scene) {
+export function addDefaultLights(scene: THREE.Scene): { hemi: THREE.HemisphereLight; ambient: THREE.AmbientLight } {
   return ensureDefaultLights(scene);
 }

package/src/loaders/{bodyTextureLoader.js → bodyTextureLoader.ts}

@@ -4,16 +4,19 @@ import { getKTX2LoaderForRenderer } from './ktx2.js';
 const textureLoader = new THREE.TextureLoader();
 
 /**
- * @param {string} url `.ktx2` goes through the renderer's KTX2 transcoder; anything else through
- *   THREE.TextureLoader.
- * @param {object} [opts]
- * @param {AbortSignal} [opts.signal] an abort during the load rejects the promise.
- * @param {import('three').WebGLRenderer | null} [opts.renderer] REQUIRED for a `.ktx2` url.
+ * `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 } = {}) {
+export function loadTexture(
+  url: string,
+  { signal, renderer }: { signal?: AbortSignal | undefined; renderer?: THREE.WebGLRenderer | null | undefined } = {},
+): Promise<THREE.Texture> {
   return new Promise((resolve, reject) => {
     if (url && url.endsWith('.ktx2')) {
-      const ktx2 = getKTX2LoaderForRenderer(renderer);
+      // A missing renderer throws inside (as before): the type allows `null` only because the
+      // non-KTX2 path never needs one.
+      const ktx2 = getKTX2LoaderForRenderer(renderer as THREE.WebGLRenderer);
       const onAbort = () => reject(new Error('aborted'));
       if (signal) signal.addEventListener('abort', onAbort, { once: true });
       ktx2.load(