entangled-worlds-orbiters-shared 3.1.0 → 3.3.0

package/dist/types/render/frameBudget.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A frame gate. Not a clock and not a scheduler: it answers one question and remembers the last time
+ * the answer was yes.
+ *
+ * @param {{ fps?: number, toleranceMs?: number }} [options]
+ * @returns {{ shouldRender(nowMs: number): boolean, reset(): void }}
+ */
+export function createFrameBudget({ fps, toleranceMs }?: {
+    fps?: number;
+    toleranceMs?: number;
+}): {
+    shouldRender(nowMs: number): boolean;
+    reset(): void;
+};
+/**
+ * @file src/render/frameBudget.js
+ * @description "Has enough time passed to draw again?" — the whole of a frame cap, kept apart from
+ * whatever is being capped so it can be reasoned about and tested on its own.
+ *
+ * The tolerance is the part that is easy to get wrong. rAF does not deliver frames at arbitrary
+ * times; it delivers them on the display's ticks. On a 60Hz display those arrive every ~16.7ms, so a
+ * strict `elapsed >= 33.3` test rejects the frame at 33.3ms by a hair and waits for the next one at
+ * 50ms — 20fps, not the 30 that was asked for. A few milliseconds of slack lets the frame that is
+ * near enough through, and the cap lands where it was aimed.
+ */
+/** Frames a capped loop is allowed per second. */
+export const CAPPED_FPS: 30;
+/** Slack for rAF landing on display ticks — see the file note. */
+export const FRAME_TOLERANCE_MS: 4;

package/dist/types/render/index.d.ts

@@ -0,0 +1,2 @@
+export { createViewportCompositor } from "./viewportCompositor.js";
+export { createFrameBudget, CAPPED_FPS, FRAME_TOLERANCE_MS } from "./frameBudget.js";

package/dist/types/render/viewportCompositor.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @param {object} [opts]
+ * @param {{ acquireCell: (index:number, total:number) => HTMLElement, releaseCell?: (index:number) => void } | null} [opts.cellSource]
+ *   external owner of the cell DOM. When present, `createCell` delegates to it and the compositor
+ *   builds no grid of its own; when absent, the default `⌈√n⌉` grid is used.
+ * @param {'fixed-overlay'|'per-cell'} [opts.presentation='fixed-overlay'] how pixels reach the
+ *   screen — the displayed fixed canvas (full-screen stage layouts) or a per-cell blit canvas the
+ *   DOM positions (cells inside scrolling content). See the module doc.
+ * @param {Partial<typeof DEFAULT_RENDERER_PROFILE>} [opts.rendererProfile] renderer construction +
+ *   pixel-ratio cap. Omit for the historical defaults.
+ * @param {boolean} [opts.performanceMode=false] start with the realm's renderer savings on — pixel
+ *   ratio clamped to 1, shadow map off, this loop capped at 30fps. Off by default, and off means the
+ *   renderer and the cadence are exactly what they were before this option existed. Toggle it live
+ *   with `setPerformanceMode`.
+ * @param {string|null} [opts.devHandleKey=null] when set, publish the returned api on
+ *   `window[devHandleKey]` so tooling can force a composited frame while rAF is throttled (a hidden
+ *   tab during automated checks). Off by default — a library does not name globals for its host.
+ * @returns {{
+ *   renderer: THREE.WebGLRenderer,
+ *   canvas: HTMLCanvasElement,
+ *   createCell: (index: number, total: number) => HTMLElement,
+ *   addVoice: (voice: { voiceId: string, cell: HTMLElement, controller: object }) => void,
+ *   removeVoice: (voiceId: string) => void,
+ *   renderOnce: () => void,
+ *   setPerformanceMode: (enabled: boolean) => boolean,
+ *   dispose: () => void,
+ * }}
+ */
+export function createViewportCompositor({ cellSource, presentation, rendererProfile, devHandleKey, performanceMode, }?: {
+    cellSource?: {
+        acquireCell: (index: number, total: number) => HTMLElement;
+        releaseCell?: (index: number) => void;
+    } | null | undefined;
+    presentation?: "fixed-overlay" | "per-cell" | undefined;
+    rendererProfile?: Partial<{
+        antialias: boolean;
+        alpha: boolean;
+        preserveDrawingBuffer: boolean;
+        powerPreference: string;
+        maxDevicePixelRatio: number;
+    }> | undefined;
+    performanceMode?: boolean | undefined;
+    devHandleKey?: string | null | undefined;
+}): {
+    renderer: THREE.WebGLRenderer;
+    canvas: HTMLCanvasElement;
+    createCell: (index: number, total: number) => HTMLElement;
+    addVoice: (voice: {
+        voiceId: string;
+        cell: HTMLElement;
+        controller: object;
+    }) => void;
+    removeVoice: (voiceId: string) => void;
+    renderOnce: () => void;
+    setPerformanceMode: (enabled: boolean) => boolean;
+    dispose: () => void;
+};
+import * as THREE from 'three';

package/dist/types/utils/dispose.d.ts

@@ -0,0 +1,2 @@
+export function disposeMaterial(material: any): void;
+export function disposeObject3D(obj: any): void;

package/dist/types/utils/index.d.ts

@@ -0,0 +1,2 @@
+export { disposeObject3D } from "./dispose.js";
+export { ensureStandardMaterial, applyFlagsToMaterial } from "./materials.js";

package/dist/types/utils/materials.d.ts

@@ -0,0 +1,2 @@
+export function ensureStandardMaterial(mesh: any): void;
+export function applyFlagsToMaterial(material: any, flags?: {}): void;

package/dist/types/world/cloudShell.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @param {object} [opts]
+ * @param {import('three').BufferGeometry} [opts.baseGeometry] cloned for the shell; when absent a
+ *   sphere is built from `baseRadius` and the segment counts.
+ * @param {number} [opts.baseRadius=0.5]
+ * @param {number} [opts.widthSegments=64]
+ * @param {number} [opts.heightSegments=64]
+ * @param {string} [opts.textureUrl]
+ * @param {number} [opts.color=0xffffff]
+ * @param {number} [opts.opacity=0.6]
+ * @param {number} [opts.speed=0.015]
+ * @param {import('three').WebGLRenderer | null} [opts.renderer]
+ */
+export function createCloudShell({ baseGeometry, baseRadius, widthSegments, heightSegments, textureUrl, color, opacity, speed, renderer, }?: {
+    baseGeometry?: THREE.BufferGeometry<THREE.NormalBufferAttributes> | undefined;
+    baseRadius?: number | undefined;
+    widthSegments?: number | undefined;
+    heightSegments?: number | undefined;
+    textureUrl?: string | undefined;
+    color?: number | undefined;
+    opacity?: number | undefined;
+    speed?: number | undefined;
+    renderer?: THREE.WebGLRenderer | null | undefined;
+}): Promise<THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes>, THREE.MeshLambertMaterial, THREE.Object3DEventMap>>;
+import * as THREE from 'three';

package/dist/types/world/index.d.ts

@@ -0,0 +1,6 @@
+export { WorldManager } from "./worldManager.js";
+export { makeNormalSphere } from "./worldNormal.js";
+export { makeGLB } from "./worldGLB.js";
+export { createCloudShell } from "./cloudShell.js";
+export type WorldCreator = import("./worldManager.js").WorldCreator;
+export { makeSphere, EARTH_RADIUS_UNITS } from "./worldTexture.js";

package/dist/types/world/worldGLB.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `emissiveIntensity`: textured self-glow (1 = old flat-lit look; ≈0.15 under a star light).
+ *
+ * @param {object} [opts]
+ * @param {string} opts.modelUrl REQUIRED; throws without it.
+ * @param {object} [opts.flags] material flags (`forceOpaque`, `wireframe`).
+ * @param {number} [opts.retries=3]
+ * @param {boolean} [opts.withCredentials=false]
+ * @param {import('three').WebGLRenderer | null} [opts.renderer] REQUIRED at runtime (`loadGLB` throws
+ *   without one); nullable here because `WorldManager` threads its own, which may be null.
+ * @param {number} [opts.emissiveIntensity]
+ */
+export function makeGLB({ modelUrl, flags, retries, withCredentials, renderer, emissiveIntensity }?: {
+    modelUrl: string;
+    flags?: object | undefined;
+    retries?: number | undefined;
+    withCredentials?: boolean | undefined;
+    renderer?: import("three").WebGLRenderer | null | undefined;
+    emissiveIntensity?: number | undefined;
+}): Promise<any>;

package/dist/types/world/worldManager.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Builds a world object for a mode registered with `registerWorldCreator`. It receives the manager's
+ * flags, the `setMode` args and the renderer, and may return the object or a promise of it (the
+ * manager awaits either).
+ * @typedef {(args: { flags: object, renderer: import('three').WebGLRenderer | null, [key: string]: unknown }) => import('three').Object3D | Promise<import('three').Object3D>} WorldCreator
+ */
+export class WorldManager {
+    /**
+     * @param {import('three').Scene} scene
+     * @param {object} [opts]
+     * @param {() => void} [opts.onLoadStart]
+     * @param {() => void} [opts.onLoadEnd]
+     * @param {import('three').WebGLRenderer | null} [opts.renderer]
+     * @param {boolean} [opts.externalTick=false]
+     */
+    constructor(scene: import("three").Scene, { onLoadStart, onLoadEnd, renderer, externalTick }?: {
+        onLoadStart?: (() => void) | undefined;
+        onLoadEnd?: (() => void) | undefined;
+        renderer?: import("three").WebGLRenderer | null | undefined;
+        externalTick?: boolean | undefined;
+    });
+    scene: import("three").Scene;
+    renderer: import("three").WebGLRenderer | null;
+    externalTick: boolean;
+    current: any;
+    /** @type {Record<string, any>} */
+    flags: Record<string, any>;
+    onLoadStart: (() => void) | undefined;
+    onLoadEnd: (() => void) | undefined;
+    token: number;
+    customCreators: Map<any, any>;
+    /**
+     * Run the current world's per-frame updater once (externalTick hosts only; no-op otherwise).
+     * @param {number} timeSec
+     */
+    tick(timeSec: number): void;
+    /** @param {object} flags merged over the current flags */
+    setFlags(flags: object): void;
+    disposeCurrent(): void;
+    /**
+     * @param {number} mode
+     * @param {WorldCreator} creatorFunction
+     */
+    registerWorldCreator(mode: number, creatorFunction: WorldCreator): void;
+    /**
+     * Build and show the world for `mode` (a registered creator, 2 = GLB, 3 = normal sphere, else the
+     * textured sphere), replacing the current one. A newer call supersedes one still loading.
+     * @param {number} mode
+     * @param {Record<string, any>} [args]
+     * @returns {Promise<void>}
+     */
+    setMode(mode: number, args?: Record<string, any>): Promise<void>;
+}
+/**
+ * Builds a world object for a mode registered with `registerWorldCreator`. It receives the manager's
+ * flags, the `setMode` args and the renderer, and may return the object or a promise of it (the
+ * manager awaits either).
+ */
+export type WorldCreator = (args: {
+    flags: object;
+    renderer: import("three").WebGLRenderer | null;
+    [key: string]: unknown;
+}) => import("three").Object3D | Promise<import("three").Object3D>;

package/dist/types/world/worldNormal.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Create a simple sphere using THREE.MeshNormalMaterial.
+ * Accepts the same basic geometry params as textured sphere so the manager API is consistent.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.sphereRadius]
+ * @param {number} [opts.sphereWidthSegments]
+ * @param {number} [opts.sphereHeightSegments]
+ * @param {object} [opts.flags] material flags (`forceOpaque`, `wireframe`).
+ * @param {boolean} [opts.glow] add the fresnel halo.
+ * @param {number} [opts.glowScale=1.18]
+ * @param {number} [opts.glowRimHex=0x66ccff]
+ * @param {number} [opts.glowFacingHex=0x000000]
+ * @param {number} [opts.glowBias=0.02]
+ * @param {number} [opts.glowFresnelScale=1]
+ * @param {number} [opts.glowPower=3.5]
+ * @param {boolean} [opts.cloudsEnabled]
+ * @param {string} [opts.cloudsTextureUrl]
+ * @param {number} [opts.cloudsColor=0xffffff]
+ * @param {number} [opts.cloudsOpacity=0.6]
+ * @param {number} [opts.cloudsSpeed=0.015]
+ * @param {import('three').WebGLRenderer | null} [opts.renderer]
+ */
+export function makeNormalSphere({ sphereRadius, sphereWidthSegments, sphereHeightSegments, flags, glow, glowScale, glowRimHex, glowFacingHex, glowBias, glowFresnelScale, glowPower, cloudsEnabled, cloudsTextureUrl, cloudsColor, cloudsOpacity, cloudsSpeed, renderer, }?: {
+    sphereRadius?: number | undefined;
+    sphereWidthSegments?: number | undefined;
+    sphereHeightSegments?: number | undefined;
+    flags?: object | undefined;
+    glow?: boolean | undefined;
+    glowScale?: number | undefined;
+    glowRimHex?: number | undefined;
+    glowFacingHex?: number | undefined;
+    glowBias?: number | undefined;
+    glowFresnelScale?: number | undefined;
+    glowPower?: number | undefined;
+    cloudsEnabled?: boolean | undefined;
+    cloudsTextureUrl?: string | undefined;
+    cloudsColor?: number | undefined;
+    cloudsOpacity?: number | undefined;
+    cloudsSpeed?: number | undefined;
+    renderer?: THREE.WebGLRenderer | null | undefined;
+}): Promise<THREE.Mesh<THREE.SphereGeometry, THREE.MeshNormalMaterial, THREE.Object3DEventMap>>;
+import * as THREE from 'three';

package/dist/types/world/worldTexture.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The textured world sphere. Every option is optional. The offset, repeat, rotation, flip and sphere
+ * geometry options are read only when they have their type; the rest are used as given (`glow`,
+ * `cloudsEnabled` and `mirrorX` by truthiness).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.textureUrl]
+ * @param {import('three').WebGLRenderer | null} [opts.renderer] REQUIRED for a KTX2 texture.
+ * @param {object} [opts.flags] material flags (`forceOpaque`, `wireframe`).
+ * @param {number} [opts.uOffset] horizontal texture offset, 0..1 (wins over `textureOffsetDeg`).
+ * @param {number} [opts.textureOffsetDeg] horizontal texture offset in degrees.
+ * @param {boolean} [opts.mirrorX]
+ * @param {boolean} [opts.mirrorDuplicateX] explicit override of the equirectangular detection.
+ * @param {boolean} [opts.autoDetectEquirectangular=true]
+ * @param {boolean} [opts.forceEquirectangular=false]
+ * @param {boolean} [opts.forceRectangular=false]
+ * @param {string} [opts.wrapS='repeat'] `'clamp'`, `'repeat'` or `'mirror'`.
+ * @param {string} [opts.wrapT='clamp'] `'clamp'`, `'repeat'` or `'mirror'`.
+ * @param {number} [opts.repeatX]
+ * @param {number} [opts.repeatY]
+ * @param {number} [opts.rotationDeg]
+ * @param {number[]} [opts.center=[0.5, 0.5]] texture rotation centre, `[u, v]`.
+ * @param {boolean} [opts.flipY]
+ * @param {number} [opts.sphereRadius]
+ * @param {number} [opts.sphereWidthSegments]
+ * @param {number} [opts.sphereHeightSegments]
+ * @param {number} [opts.materialRoughness] accepted from saved worlds; no longer changes the look.
+ * @param {number} [opts.materialMetalness] accepted from saved worlds; no longer changes the look.
+ * @param {boolean} [opts.glow=true]
+ * @param {number} [opts.glowRimHex=0x66ccff]
+ * @param {number} [opts.glowFacingHex=0x000000]
+ * @param {number} [opts.glowScale=1.18]
+ * @param {number} [opts.glowBias=0.02]
+ * @param {number} [opts.glowFresnelScale=1]
+ * @param {number} [opts.glowPower=3.5]
+ * @param {boolean} [opts.cloudsEnabled=false]
+ * @param {string} [opts.cloudsTextureUrl]
+ * @param {number} [opts.cloudsColor=0xffffff]
+ * @param {number} [opts.cloudsOpacity=0.6]
+ * @param {number} [opts.cloudsSpeed=0.015]
+ */
+export function makeSphere({ textureUrl, renderer, flags, uOffset, textureOffsetDeg, mirrorX, mirrorDuplicateX, autoDetectEquirectangular, forceEquirectangular, forceRectangular, wrapS, wrapT, repeatX, repeatY, rotationDeg, center, flipY, sphereRadius, sphereWidthSegments, sphereHeightSegments, materialRoughness, materialMetalness, glow, glowRimHex, glowFacingHex, glowScale, glowBias, glowFresnelScale, glowPower, cloudsEnabled, cloudsTextureUrl, cloudsColor, cloudsOpacity, cloudsSpeed, }?: {
+    textureUrl?: string | undefined;
+    renderer?: THREE.WebGLRenderer | null | undefined;
+    flags?: object | undefined;
+    uOffset?: number | undefined;
+    textureOffsetDeg?: number | undefined;
+    mirrorX?: boolean | undefined;
+    mirrorDuplicateX?: boolean | undefined;
+    autoDetectEquirectangular?: boolean | undefined;
+    forceEquirectangular?: boolean | undefined;
+    forceRectangular?: boolean | undefined;
+    wrapS?: string | undefined;
+    wrapT?: string | undefined;
+    repeatX?: number | undefined;
+    repeatY?: number | undefined;
+    rotationDeg?: number | undefined;
+    center?: number[] | undefined;
+    flipY?: boolean | undefined;
+    sphereRadius?: number | undefined;
+    sphereWidthSegments?: number | undefined;
+    sphereHeightSegments?: number | undefined;
+    materialRoughness?: number | undefined;
+    materialMetalness?: number | undefined;
+    glow?: boolean | undefined;
+    glowRimHex?: number | undefined;
+    glowFacingHex?: number | undefined;
+    glowScale?: number | undefined;
+    glowBias?: number | undefined;
+    glowFresnelScale?: number | undefined;
+    glowPower?: number | undefined;
+    cloudsEnabled?: boolean | undefined;
+    cloudsTextureUrl?: string | undefined;
+    cloudsColor?: number | undefined;
+    cloudsOpacity?: number | undefined;
+    cloudsSpeed?: number | undefined;
+}): Promise<THREE.Mesh<THREE.SphereGeometry, THREE.MeshLambertMaterial, THREE.Object3DEventMap>>;
+export const WORLD_TEXTURE_DEBUG_TAG: "WT:vFlipGeom-r3@2025-10-28T17:22:00Z";
+export const EARTH_RADIUS_UNITS: 0.5;
+import * as THREE from 'three';

package/package.json

@@ -1,19 +1,44 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",
+  "types": "./dist/types/index.d.ts",
   "sideEffects": false,
   "exports": {
-    ".": "./src/index.js",
-    "./world": "./src/world/index.js",
-    "./moons": "./src/moons/index.js",
-    "./loaders": "./src/loaders/index.js",
-    "./render": "./src/render/index.js",
-    "./core": "./src/core/index.js",
-    "./config": "./src/config/index.js",
-    "./utils": "./src/utils/index.js",
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./world": {
+      "types": "./dist/types/world/index.d.ts",
+      "default": "./src/world/index.js"
+    },
+    "./moons": {
+      "types": "./dist/types/moons/index.d.ts",
+      "default": "./src/moons/index.js"
+    },
+    "./loaders": {
+      "types": "./dist/types/loaders/index.d.ts",
+      "default": "./src/loaders/index.js"
+    },
+    "./render": {
+      "types": "./dist/types/render/index.d.ts",
+      "default": "./src/render/index.js"
+    },
+    "./core": {
+      "types": "./dist/types/core/index.d.ts",
+      "default": "./src/core/index.js"
+    },
+    "./config": {
+      "types": "./dist/types/config/index.d.ts",
+      "default": "./src/config/index.js"
+    },
+    "./utils": {
+      "types": "./dist/types/utils/index.d.ts",
+      "default": "./src/utils/index.js"
+    },
     "./clock": {
       "types": "./dist/clock/index.d.ts",
       "import": "./dist/clock/index.js"
@@ -120,7 +145,7 @@
     "lint": "eslint .",
     "lint:strict": "eslint . --max-warnings=0",
     "lint:fallback": "node scripts/lint.js",
-    "build:ts": "tsc -p tsconfig.build.json",
+    "build:ts": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
     "build:clock": "npm run build:ts",
     "prepare": "npm run build:ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",

package/src/config/env.js

@@ -1,15 +1,18 @@
 // Runtime public base URL helper for building absolute asset URLs at runtime
 
 // Mutable module-scoped variable to allow apps to override at startup
+/** @type {string | null} */
 export let __PUBLIC_BASE = null;
 
 // Set the public base (strips trailing slash) and mirror to window for convenience
+/** @param {string | null | undefined} url */
 export function setPublicBase(url) {
   __PUBLIC_BASE = (url || '').replace(/\/$/, '');
   if (typeof window !== 'undefined') window.VITE_PUBLIC_HERBARIUM_BASE = __PUBLIC_BASE;
 }
 
 // Get the current public base from (in order): explicit set value, envs, or default
+/** @returns {string} */
 export function getPublicBase() {
   const envVal =
     (typeof import.meta !== 'undefined' && import.meta.env && import.meta.env.VITE_PUBLIC_HERBARIUM_BASE) ||
@@ -20,6 +23,11 @@ export function getPublicBase() {
 }
 
 // Resolve a possibly-relative path against the current public base
+/**
+ * @param {string} path root-relative, relative, or an absolute http(s) URL (returned unchanged).
+ *   An empty string comes back as is.
+ * @returns {string}
+ */
 export function resolvePublicUrl(path) {
   if (!path) return path;
   if (/^https?:\/\//i.test(path)) return path;

package/src/core/lights.js

@@ -8,6 +8,9 @@ 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');
@@ -33,7 +36,15 @@ export function ensureDefaultLights(scene) {
  * was ensured last, so on a page rendering several scenes every lighting update landed on one of
  * them — a shared-renderer page (N feed worlds, N orbiters) lit the wrong world.
  *
+ * Every field is optional; an omitted one leaves that part of the lighting as it is.
+ *
  * @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 } = {}) {
   if (!scene?.isObject3D) {
@@ -75,6 +86,7 @@ export function setHemisphereEnabled(scene, on) {
 }
 
 // Back-compat helper
+/** @param {import('three').Scene} scene */
 export function addDefaultLights(scene) {
   return ensureDefaultLights(scene);
 }

package/src/loaders/bodyTextureLoader.js

@@ -3,6 +3,13 @@ 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.
+ */
 export function loadTexture(url, { signal, renderer } = {}) {
   return new Promise((resolve, reject) => {
     if (url && url.endsWith('.ktx2')) {

package/src/loaders/cubeMapLoader.js

@@ -167,6 +167,15 @@ function resolveUrls(faceKeys) {
  * `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.)
+ *
+ * @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`.
  */
 export async function loadCubeMap({ faceKeys, skycubeName, preferKTX2 = true, forceLow, renderer } = {}) {
 
@@ -235,6 +244,20 @@ 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
+ */
+
+/**
+ * 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) {
   // Clean up previous skybox mesh
   if (scene.__EW_SKYBOX_MESH && scene.__EW_SKYBOX_MESH.parent === scene) {
@@ -274,6 +297,10 @@ export function setBackground(scene, resource) {
   }
 }
 
+/**
+ * @param {import('three').Scene} scene
+ * @param {{ renderer?: import('three').WebGLRenderer | null }} [opts]
+ */
 export async function initSpaceScene(scene, { renderer } = {}) {
   const faceKeys = buildSkycubefaceKeys('001');
   const cube = await loadCubeMap({ faceKeys, preferKTX2: true, renderer });

package/src/loaders/glbLoader.js

@@ -4,7 +4,13 @@ import { ensureStandardMaterial, applyFlagsToMaterial } from '../utils/materials
 import { getKTX2LoaderForRenderer } from './ktx2.js';
 
 /**
- * @param {object} [opts]
+ * @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.

package/src/loaders/index.js

@@ -2,4 +2,6 @@
 export { loadCubeMap, setBackground, normalizeSkycubeName, buildSkycubefaceKeys } from './cubeMapLoader.js';
 export { loadGLB } from './glbLoader.js';
 export { loadTexture } from './bodyTextureLoader.js';
-export { getKTX2LoaderForRenderer, disposeKTX2LoaderForRenderer } from './ktx2.js';
+export { getKTX2LoaderForRenderer, disposeKTX2LoaderForRenderer } from './ktx2.js';
+
+/** @typedef {import('./cubeMapLoader.js').SkyboxResource} SkyboxResource */

package/src/moons/moonsGeneration.js

@@ -21,6 +21,36 @@ export const MOON_ORBIT_SCATTER = 0.22;
 /** Each moon sits up to ± half of this above or below the orbit plane. */
 export const MOON_HEIGHT_SCATTER = 0.12;
 
+/**
+ * @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.
+ */
 export async function generateMoons({
   count = 0,
   orbitRadius = 1.5,
@@ -55,8 +85,8 @@ export async function generateMoons({
   referenceMoonScale = 0.25,
   // behavior flags
   useEmissiveMapFromTexture = true,  // reuse color texture as emissiveMap to lift dark sides
-  // The renderer whose KTX2 transcoder decodes the moon texture. Required on any page with more than
-  // one renderer; falls back to the standalone app's global inside the loader.
+  // The renderer whose KTX2 transcoder decodes the moon texture. REQUIRED for the KTX2 texture (3.0:
+  // the loader has no global fallback).
   renderer,
 } = {}) {
   if (count <= 0) return null;

package/src/moons/moonsManager.js

@@ -6,7 +6,7 @@ export class MoonsManager {
   /**
    * @param {import('three').Scene} scene
    * @param {object} [opts]
-   * @param {import('three').WebGLRenderer} [opts.renderer]  renderer the moon texture binds to (KTX2).
+   * @param {import('three').WebGLRenderer | null} [opts.renderer]  renderer the moon texture binds to (KTX2).
    */
   constructor(scene, { renderer } = {}) {
     this.scene = scene;