entangled-worlds-orbiters-shared 3.3.0 → 4.0.0

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

@@ -4,7 +4,17 @@ import { getKTX2LoaderForRenderer } from './ktx2.js';
 
 // Base URL is resolved at runtime via helper
 
-export function normalizeSkycubeName(raw) {
+/** 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');
@@ -14,10 +24,10 @@ export function normalizeSkycubeName(raw) {
 }
 
 // Standard face order for cube maps
-const FACE_ORDER = ['right', 'left', 'top', 'bottom', 'front', 'back'];
+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, extension = 'ktx2') {
+export function buildSkycubefaceKeys(skycubeId: string | null | undefined, extension = 'ktx2') {
   const id = normalizeSkycubeName(skycubeId);
   const base = `/default/skybox/${id}`;
   return {
@@ -35,7 +45,8 @@ function isLowPerformanceDevice() {
   try {
     const ua = navigator.userAgent.toLowerCase();
     const isMobileUA = /mobi|android|iphone|ipad|ipod/.test(ua);
-    const mem = navigator.deviceMemory || 0; // GB
+    // `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);
@@ -43,13 +54,14 @@ function isLowPerformanceDevice() {
 }
 
 // Validate face URLs object
-function validatefaceKeys(faceKeys) {
+function validatefaceKeys(faceKeys: unknown): faceKeys is FaceKeys {
   if (!faceKeys || typeof faceKeys !== 'object') return false;
-  return FACE_ORDER.every(face => faceKeys[face] && typeof faceKeys[face] === 'string');
+  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) {
+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';
@@ -63,11 +75,11 @@ function detectExtension(faceKeys) {
 const FACES_IN_FLIGHT = 3;
 
 // Load KTX2 faces and create skybox mesh
-async function loadFacesKTX2(faceKeys, renderer) {
+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 => {
+  const loadFace = async (face: FaceName) => {
     const tex = await loader.loadAsync(faceKeys[face]);
     tex.flipY = false;
     tex.wrapS = THREE.ClampToEdgeWrapping;
@@ -86,8 +98,8 @@ async function loadFacesKTX2(faceKeys, renderer) {
 
   // 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;
+  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;
@@ -102,8 +114,8 @@ async function loadFacesKTX2(faceKeys, renderer) {
   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);
+  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({ 
@@ -124,13 +136,14 @@ async function loadFacesKTX2(faceKeys, renderer) {
     }
   }
   
-  const mesh = new THREE.Mesh(box, mats);
+  // 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) {
+function loadFacesJPG(faceKeys: FaceKeys): Promise<THREE.CubeTexture> {
   const urls = FACE_ORDER.map(face => faceKeys[face]);
   return new Promise((resolve, reject) => {
     new THREE.CubeTextureLoader().load(
@@ -148,9 +161,10 @@ function loadFacesJPG(faceKeys) {
 }
 
 // Resolve relative paths to full URLs
-function resolveUrls(faceKeys) {
+function resolveUrls(faceKeys: FaceKeys): FaceKeys {
   const PUBLIC_BASE = getPublicBase();
-  const resolved = {};
+  // Every face is set below.
+  const resolved = {} as FaceKeys;
   FACE_ORDER.forEach(face => {
     const url = faceKeys[face];
     if (url && url.startsWith('/')) {
@@ -168,16 +182,26 @@ function resolveUrls(faceKeys) {
  * 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.)
  *
- * @param {object} [opts]
- * @param {{ right: string, left: string, top: string, bottom: string, front: string, back: string }} [opts.faceKeys]
- *   explicit face URLs; when absent they are built from `skycubeName`.
- * @param {string} [opts.skycubeName] skybox id (e.g. `'001'`), used when `faceKeys` is absent.
- * @param {boolean} [opts.preferKTX2=true]
- * @param {boolean} [opts.forceLow] force (or forbid) the low-resolution faces; omitted = detect the device.
- * @param {import('three').WebGLRenderer | null} [opts.renderer]
- * @returns {Promise<SkyboxResource>} pass it to `setBackground`.
+ * - `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 } = {}) {
+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) {
@@ -216,7 +240,8 @@ export async function loadCubeMap({ faceKeys, skycubeName, preferKTX2 = true, fo
   }
   
   // Try PNG fallback (convert URLs if needed)
-  const pngUrls = {};
+  // Every face is set below.
+  const pngUrls = {} as FaceKeys;
   FACE_ORDER.forEach(face => {
     pngUrls[face] = resolvedUrls[face].replace(/\.ktx2$/, '.png');
   });
@@ -230,9 +255,11 @@ export async function loadCubeMap({ faceKeys, skycubeName, preferKTX2 = true, fo
 }
 
 // Dispose helpers to ensure clean swaps
-function disposeSkyboxMesh(mesh) {
+function disposeSkyboxMesh(mesh: THREE.Mesh) {
   try {
-    const mats = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+    // 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();
@@ -247,42 +274,50 @@ function disposeSkyboxMesh(mesh) {
 /**
  * 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.
- * @typedef {{ __ewType: 'skybox-mesh', mesh: import('three').Mesh } | (import('three').CubeTexture & { mesh?: undefined })} SkyboxResource
  */
+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.
  *
- * @param {import('three').Scene} scene
- * @param {unknown} resource
  */
-export function setBackground(scene, resource) {
+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 (scene.__EW_SKYBOX_MESH && scene.__EW_SKYBOX_MESH.parent === scene) {
-    const oldMesh = scene.__EW_SKYBOX_MESH;
+  if (sky.__EW_SKYBOX_MESH && sky.__EW_SKYBOX_MESH.parent === scene) {
+    const oldMesh = sky.__EW_SKYBOX_MESH;
     scene.remove(oldMesh);
     disposeSkyboxMesh(oldMesh);
-    scene.__EW_SKYBOX_MESH = null;
+    sky.__EW_SKYBOX_MESH = null;
   }
   
   // Dispose previous CubeTexture background
-  if (scene.background && scene.background.isCubeTexture) {
+  // 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 { 
-      scene.background.dispose(); 
+      background.dispose(); 
     } catch(e) {
       console.warn('[CubeMapLoader] Background disposal error:', e);
     }
   }
   
   // Set new background
-  if (resource?.__ewType === 'skybox-mesh') {
+  if (res?.__ewType === 'skybox-mesh') {
     scene.background = null;
-    scene.__EW_SKYBOX_MESH = resource.mesh;
-    scene.add(resource.mesh);
-  } else if (resource?.isCubeTexture || resource?.isTexture) {
-    scene.background = resource;
+    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;
   }
@@ -290,18 +325,17 @@ export function setBackground(scene, resource) {
   // Dispatch update event for reactive systems
   try {
     window.dispatchEvent(new CustomEvent('ew:skycube-updated', { 
-      detail: { type: resource?.__ewType || 'texture' } 
+      detail: { type: res?.__ewType || 'texture' } 
     }));
   } catch(e) {
     console.warn('[CubeMapLoader] Event dispatch error:', e);
   }
 }
 
-/**
- * @param {import('three').Scene} scene
- * @param {{ renderer?: import('three').WebGLRenderer | null }} [opts]
- */
-export async function initSpaceScene(scene, { renderer } = {}) {
+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);

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

@@ -1,24 +1,44 @@
 import * as THREE from 'three';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
-import { ensureStandardMaterial, applyFlagsToMaterial } from '../utils/materials.js';
+import { ensureStandardMaterial, applyFlagsToMaterial, type MaterialFlags } from '../utils/materials.js';
 import { getKTX2LoaderForRenderer } from './ktx2.js';
 
 /**
- * @param {string} url
- * @param {object} [opts] `renderer` is REQUIRED at runtime (throws without one).
- * @param {number} [opts.retries=3] load attempts before giving up.
- * @param {AbortSignal} [opts.signal] rejects the load on abort.
- * @param {(event: ProgressEvent) => void} [opts.onProgress]
- * @param {object} [opts.applyFlags] material flags (`forceOpaque`, `wireframe`) applied to every mesh.
- * @param {boolean} [opts.withCredentials=false]
- * @param {number} [opts.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.
- * @param {import('three').WebGLRenderer} opts.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.
+ * `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 } = {}) {
+export async function loadGLB(
+  url: string,
+  {
+    retries = 3,
+    signal,
+    onProgress,
+    applyFlags,
+    withCredentials = false,
+    renderer,
+    emissiveIntensity = 1.0,
+  }: {
+    retries?: number | undefined;
+    signal?: AbortSignal | undefined;
+    onProgress?: ((event: ProgressEvent) => void) | undefined;
+    applyFlags?: MaterialFlags | undefined;
+    withCredentials?: boolean | undefined;
+    emissiveIntensity?: number | undefined;
+    renderer: THREE.WebGLRenderer;
+    // The options stay optional as a whole, as the JSDoc had them: without them `renderer` is
+    // missing and the guard below throws, as it always did.
+  } = {} as { renderer: THREE.WebGLRenderer },
+  // The loaded scene. `undefined` only when `retries` is 0 or less: no attempt is made.
+): Promise<THREE.Group | undefined> {
   if (!renderer) throw new Error('[glb] loadGLB requires the owning renderer (KTX2 textures bind per WebGL context).');
 
   let attempt = 0;
@@ -29,7 +49,7 @@ export async function loadGLB(url, { retries = 3, signal, onProgress, applyFlags
         .setWithCredentials(Boolean(withCredentials))
         .setKTX2Loader(getKTX2LoaderForRenderer(renderer));
 
-      const root = await new Promise((resolve, reject) => {
+      const root = await new Promise<THREE.Group>((resolve, reject) => {
         loader.load(
           url,
             (gltf) => resolve(gltf.scene),
@@ -42,7 +62,10 @@ export async function loadGLB(url, { retries = 3, signal, onProgress, applyFlags
       });
 
       // Post-process materials
-      root.traverse((child) => {
+      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 as THREE.Mesh<THREE.BufferGeometry, THREE.MeshStandardMaterial>;
         if (child.isMesh && child.material) {
           ensureStandardMaterial(child);
           if (applyFlags) applyFlagsToMaterial(child.material, applyFlags);
@@ -69,7 +92,7 @@ export async function loadGLB(url, { retries = 3, signal, onProgress, applyFlags
       root.position.set(0, 0, 0);
       return root;
     } catch (e) {
-      console.warn(`GLB load attempt ${attempt + 1} failed:`, e.message);
+      console.warn(`GLB load attempt ${attempt + 1} failed:`, (e as Error).message);
       if (signal?.aborted || attempt >= retries - 1) throw e;
       attempt++;
       await new Promise(resolve => setTimeout(resolve, 500)); // Brief delay between retries

package/src/loaders/index.ts

@@ -0,0 +1,6 @@
+// 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.js → ktx2.ts}

@@ -1,3 +1,4 @@
+import type * as THREE from 'three';
 import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
 
 /**
@@ -12,9 +13,9 @@ import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
  * (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();
+const loadersByRenderer = new WeakMap<THREE.WebGLRenderer, KTX2Loader>();
 
-function makeLoader(renderer) {
+function makeLoader(renderer: THREE.WebGLRenderer): KTX2Loader {
   return new KTX2Loader().setTranscoderPath('/basis/').detectSupport(renderer);
 }
 
@@ -23,10 +24,8 @@ function makeLoader(renderer) {
  * 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.
- * @param {import('three').WebGLRenderer} renderer
- * @returns {KTX2Loader}
  */
-export function getKTX2LoaderForRenderer(renderer) {
+export function getKTX2LoaderForRenderer(renderer: THREE.WebGLRenderer): KTX2Loader {
   if (!renderer) {
     throw new Error('[ktx2] getKTX2LoaderForRenderer requires the owning renderer — thread it from the view that renders this texture.');
   }
@@ -41,9 +40,8 @@ export function getKTX2LoaderForRenderer(renderer) {
 /**
  * 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).
- * @param {import('three').WebGLRenderer} renderer
  */
-export function disposeKTX2LoaderForRenderer(renderer) {
+export function disposeKTX2LoaderForRenderer(renderer: THREE.WebGLRenderer): void {
   const loader = renderer && loadersByRenderer.get(renderer);
   if (loader) {
     try { loader.dispose?.(); } catch { /* already gone */ }

package/src/moons/{index.js → index.ts}

@@ -1,5 +1,6 @@
 // Moons system exports
 export { MoonsManager } from './moonsManager.js';
+export type { MoonAmountOptions } from './moonsManager.js';
 export {
   generateMoons,
   DEFAULT_MOON_TEX_KTX2,

package/src/moons/{moonsGeneration.js → moonsGeneration.ts}

@@ -2,7 +2,7 @@ import * as THREE from 'three';
 import { loadTexture } from '../loaders/bodyTextureLoader.js';
 import { resolvePublicUrl } from '../config/env.js';
 
-function moonTexPath(file) {
+function moonTexPath(file: string): string {
   return resolvePublicUrl(`default/textures/moons/${file}`);
 }
 export const DEFAULT_MOON_TEX_KTX2 = moonTexPath('moon-equirectangular.ktx2');
@@ -22,34 +22,18 @@ export const MOON_ORBIT_SCATTER = 0.22;
 export const MOON_HEIGHT_SCATTER = 0.12;
 
 /**
- * @param {object} [opts]
- * @param {number} [opts.count=0] 0 or less resolves to null.
- * @param {number} [opts.orbitRadius=1.5]
- * @param {string} [opts.textureKTX2]
- * @param {string} [opts.texturePNG]
- * @param {string | null} [opts.textureFallback] used instead of `texturePNG` when set.
- * @param {boolean} [opts.useTexture=true]
- * @param {number | string | null} [opts.seed] deterministic positions when set.
- * @param {string | null} [opts.textureKey] replaces `textureKTX2` when set (the fallback stays
- *   `textureFallback` or `texturePNG`).
- * @param {string} [opts.moonColor='#ffffff']
- * @param {number} [opts.brightness=1.15]
- * @param {number} [opts.emissiveColor=0x333333]
- * @param {number} [opts.emissiveIntensity=0.18]
- * @param {number} [opts.emissiveLift] night-side self-glow 0..1; omitted = `emissiveIntensity`.
- * @param {number} [opts.roughness=0.85]
- * @param {number} [opts.metalness=0]
- * @param {boolean} [opts.debug=true]
- * @param {boolean} [opts.smooth=true]
- * @param {number} [opts.geometryWidthSegments=16]
- * @param {number} [opts.geometryHeightSegments=12]
- * @param {boolean} [opts.useBumpFromColor=true]
- * @param {number} [opts.bumpScale=0.15]
- * @param {boolean} [opts.debugShowUvGrid=false]
- * @param {boolean} [opts.debugShowReferenceMoon=false]
- * @param {number} [opts.referenceMoonScale=0.25]
- * @param {boolean} [opts.useEmissiveMapFromTexture=true]
- * @param {import('three').WebGLRenderer | null} [opts.renderer] binds the KTX2 moon texture.
+ * - `count` (0): 0 or less resolves to null. `orbitRadius` 1.5.
+ * - `textureFallback`: used instead of `texturePNG` when set.
+ * - `seed`: deterministic positions when set.
+ * - `textureKey`: replaces `textureKTX2` when set (the fallback stays `textureFallback` or
+ *   `texturePNG`).
+ * - `emissiveLift`: night-side self-glow 0..1; omitted = `emissiveIntensity`.
+ * - `renderer`: binds the KTX2 moon texture.
+ * - Defaults: `moonColor` '#ffffff', `brightness` 1.15, `emissiveColor` 0x333333,
+ *   `emissiveIntensity` 0.18, `roughness` 0.85, `metalness` 0, `debug` true, `smooth` true,
+ *   `geometryWidthSegments` 16, `geometryHeightSegments` 12, `useBumpFromColor` true, `bumpScale`
+ *   0.15, `debugShowUvGrid` false, `debugShowReferenceMoon` false, `referenceMoonScale` 0.25,
+ *   `useEmissiveMapFromTexture` true.
  */
 export async function generateMoons({
   count = 0,
@@ -88,6 +72,33 @@ export async function generateMoons({
   // The renderer whose KTX2 transcoder decodes the moon texture. REQUIRED for the KTX2 texture (3.0:
   // the loader has no global fallback).
   renderer,
+}: {
+  count?: number | undefined;
+  orbitRadius?: number | undefined;
+  textureKTX2?: string | undefined;
+  texturePNG?: string | undefined;
+  textureFallback?: string | null | undefined;
+  useTexture?: boolean | undefined;
+  seed?: string | number | null | undefined;
+  textureKey?: string | null | undefined;
+  moonColor?: string | undefined;
+  brightness?: number | undefined;
+  emissiveColor?: number | undefined;
+  emissiveIntensity?: number | undefined;
+  emissiveLift?: number | undefined;
+  roughness?: number | undefined;
+  metalness?: number | undefined;
+  debug?: boolean | undefined;
+  smooth?: boolean | undefined;
+  geometryWidthSegments?: number | undefined;
+  geometryHeightSegments?: number | undefined;
+  useBumpFromColor?: boolean | undefined;
+  bumpScale?: number | undefined;
+  debugShowUvGrid?: boolean | undefined;
+  debugShowReferenceMoon?: boolean | undefined;
+  referenceMoonScale?: number | undefined;
+  useEmissiveMapFromTexture?: boolean | undefined;
+  renderer?: THREE.WebGLRenderer | null | undefined;
 } = {}) {
   if (count <= 0) return null;
 
@@ -104,7 +115,8 @@ export async function generateMoons({
   }
   
   // Seeded random function (Linear Congruential Generator)
-  let currentSeed = seedValue !== null ? Math.abs(seedValue) : Date.now();
+  // A string seed was hashed to a number above.
+  let currentSeed = seedValue !== null ? Math.abs(seedValue as number) : Date.now();
   const seededRandom = () => {
     if (seedValue !== null) {
       currentSeed = (currentSeed * 1664525 + 1013904223) % 4294967296;
@@ -116,13 +128,14 @@ export async function generateMoons({
   const moonGeometry = new THREE.SphereGeometry(MOON_BASE_RADIUS, geometryWidthSegments, geometryHeightSegments);
 
   // Optional UV grid override
-  let sharedTexture = null;
+  let sharedTexture: THREE.Texture | null = null;
   let usedUvGrid = false;
   async function buildUvGridTexture() {
     const w = 512, h = 256; // 2:1 aspect
     const canvas = document.createElement('canvas');
     canvas.width = w; canvas.height = h;
-    const ctx = canvas.getContext('2d');
+    // A missing 2D context throws on first use; the caller catches it, as before.
+    const ctx = canvas.getContext('2d') as CanvasRenderingContext2D;
     ctx.fillStyle = '#101018'; ctx.fillRect(0,0,w,h);
     for (let lon=0; lon<=12; lon++) {
       const x = (lon/12)*w; ctx.strokeStyle = lon % 3 ===0 ? '#ff4d4d':'#444'; ctx.lineWidth = lon%3===0?2:1; ctx.beginPath(); ctx.moveTo(x,0); ctx.lineTo(x,h); ctx.stroke();

package/src/moons/{moonsManager.js → moonsManager.ts}

@@ -2,13 +2,36 @@ import { disposeObject3D } from '../utils/dispose.js';
 import * as THREE from 'three';
 import { generateMoons } from './moonsGeneration.js';
 
+/** The `setAmount` options: what the moons look like and where they orbit. */
+export interface MoonAmountOptions {
+  /** 1.5 by default. */
+  orbitRadius?: number;
+  textureKTX2?: string;
+  texturePNG?: string;
+  /** true by default. */
+  useTexture?: boolean;
+  /** Deterministic positions when set. */
+  seed?: string | number | null;
+  /** Replaces `textureKTX2` when set. */
+  textureKey?: string | null;
+  /** '#ffffff' by default. */
+  moonColor?: string;
+  /** Used instead of `texturePNG` when set. */
+  textureFallback?: string | null;
+  /** Night-side self-glow 0..1, kept for later rebuilds; anything but a number is ignored. */
+  emissiveLift?: number;
+}
+
 export class MoonsManager {
-  /**
-   * @param {import('three').Scene} scene
-   * @param {object} [opts]
-   * @param {import('three').WebGLRenderer | null} [opts.renderer]  renderer the moon texture binds to (KTX2).
-   */
-  constructor(scene, { renderer } = {}) {
+  // `declare`d so the emitted class assigns them in the constructor only, as the JS did.
+  declare scene: THREE.Scene;
+  declare renderer: THREE.WebGLRenderer | null | undefined;
+  declare group: THREE.Group | null;
+  declare _opId: number;
+  declare _emissiveLift: number | undefined;
+
+  /** `renderer`: the renderer the moon texture binds to (KTX2). */
+  constructor(scene: THREE.Scene, { renderer }: { renderer?: THREE.WebGLRenderer | null | undefined } = {}) {
     this.scene = scene;
     this.renderer = renderer;
     this.group = null;
@@ -16,7 +39,8 @@ export class MoonsManager {
     this._emissiveLift = undefined; // night-side self-glow; undefined = generator default
   }
 
-  async setAmount(count, opts = {}) {
+  /** Replace the moons with `count` new ones; 0 or less (or none) just removes them. */
+  async setAmount(count: number | null | undefined, opts: MoonAmountOptions = {}): Promise<void> {
     // Increment operation id to invalidate older async calls
     const opId = ++this._opId;
 
@@ -41,7 +65,7 @@ export class MoonsManager {
     } = opts;
     if (typeof emissiveLift === 'number') this._emissiveLift = emissiveLift;
 
-    let newGroup = null;
+    let newGroup: THREE.Group | null = null;
     try {
       newGroup = await generateMoons({
         count,
@@ -79,12 +103,14 @@ export class MoonsManager {
    * Night-side self-glow 0..1, applied in place to the live moons and kept for later rebuilds.
    * Low values (≈0.05) let a star-lit scene show the moons' dark sides.
    */
-  setEmissiveLift(v) {
+  setEmissiveLift(v: number): void {
     if (typeof v !== 'number' || !Number.isFinite(v)) return;
     this._emissiveLift = Math.min(1, Math.max(0, v));
-    this.group?.traverse((child) => {
+    this.group?.traverse((object) => {
+      // Only a mesh whose material has `emissiveIntensity` is changed; the value was just set above.
+      const child = object as THREE.Mesh<THREE.BufferGeometry, THREE.MeshLambertMaterial>;
       if (child.isMesh && child.material && 'emissiveIntensity' in child.material) {
-        child.material.emissiveIntensity = this._emissiveLift;
+        child.material.emissiveIntensity = this._emissiveLift as number;
       }
     });
   }