entangled-worlds-orbiters-shared 3.1.0 → 3.3.0

package/README.md

@@ -76,7 +76,7 @@ import * as EntangledWorlds from 'entangled-worlds-orbiters-shared';
 - `DEFAULT_STAR_PARAMS`, `normalizeStarParams` - Author params (temperature, radius, luminosity, activity, multiplicity, separation, seed, placement) + validator for stored params
 - `starParamsFromStellarData` - Catalogue host-star data (Teff, radius, mass, luminosity, spectral type, star count or a "(AB)b" name suffix) → params
 - `blackbodyColor`, `spectralClass`, `starLayout`, `starPositions` - Pure colour / layout / orbit helpers
-- `getFocus` (on `createStar` / `StarManager`), `framingDistance`, `defaultStarPlacement` - Camera focus on the system barycentre and host-camera-aware placement
+- `getFocus` (on `createStar` / `StarManager`), `framingDistance`, `defaultStarPlacement` - Camera focus on the system barycentre and the default placement (over the camera's shoulder, so worlds open on their day side)
 - The star lights the scene: `StarManager` key + camera-side fill lights, `setLighting`, `lightingFromLegacy`, `DEFAULT_AMBIENT` (pair with `setHemisphereEnabled(scene, false)` from `./core`; moons `emissiveLift`, GLB `emissiveIntensity` for night sides)
 - Real binaries (close pair from component masses, a distant companion for wide pairs) and an optional debris disc; `mainSequenceTemperature` / `Radius` / `Luminosity` helpers
 - Perf + look harness: `npm run bench:star` (see `bench/star/results/REPORT.md`)

package/dist/star/framing.d.ts

@@ -19,13 +19,24 @@ export interface StarPlacementInput {
 export interface StarPlacement {
     azimuth: number;
     elevation: number;
-    /** False when no in-frame spot clears the planet (it fills the frame); the star is then just above it. */
+    /** Always true (kept for older hosts): the spot is behind any camera closer than ~0.79 × the star's distance (≥ 15.8 units). */
     fits: boolean;
 }
 /**
- * Azimuth / elevation that put the primary's disc (plus its bright glow) just outside the planet's
- * angular disc and inside the frame of a camera on +Z looking at the origin — upper-right when there
- * is room, swinging towards straight up as the frame narrows (portrait). Hosts use it only when the
- * author has not set azimuth/elevation; `DEFAULT_STAR_PARAMS` stays the host-agnostic fallback.
+ * The opening light: the star over the camera's right shoulder (behind it, a little up and to the
+ * right), so the planet opens on its day side — about 90% of the face the camera sees is lit, the
+ * night edge on the left — and the star itself shows when the viewer orbits round. 145° / 15° is
+ * ~38° off the view axis. It is `DEFAULT_STAR_PARAMS`' direction, so a host with no camera gets it too.
  */
-export declare function defaultStarPlacement(input: StarPlacementInput): StarPlacement;
+export declare const OVER_THE_SHOULDER: {
+    readonly azimuth: number;
+    readonly elevation: number;
+};
+/**
+ * Azimuth / elevation of the default star for a camera on +Z looking at the origin: over the
+ * camera's shoulder (`OVER_THE_SHOULDER`), so the world opens lit. The star sits ≥ 0.79 × its
+ * distance (≥ 15.8 units) out on +Z, behind any host camera, so the frame never changes it. Hosts
+ * use it only when the author has not set azimuth/elevation; `DEFAULT_STAR_PARAMS` stays the
+ * host-agnostic fallback.
+ */
+export declare function defaultStarPlacement(_input?: StarPlacementInput): StarPlacement;

package/dist/star/framing.js

@@ -1,7 +1,6 @@
 // Camera framing helpers (pure, no three): how far a camera must sit to fit a focus sphere, and a
-// host-camera-aware default placement for the star so it reads beside the planet, not behind it.
-import { FOCUS_GLOW_RADII } from './layout.js';
-import { DEFAULT_STAR_PARAMS, STAR_PARAM_RANGES } from './params.js';
+// default placement for the star that lights the planet's side facing the camera.
+import { DEFAULT_STAR_PARAMS } from './params.js';
 const DEG = Math.PI / 180;
 /**
  * Camera distance (from the sphere's centre) at which a sphere of `radius` fits inside both the
@@ -15,54 +14,19 @@ export function framingDistance(radius, fovDeg, aspect, margin = 1.15) {
     return r / Math.sin(Math.min(halfV, halfH));
 }
 /**
- * Azimuth / elevation that put the primary's disc (plus its bright glow) just outside the planet's
- * angular disc and inside the frame of a camera on +Z looking at the origin — upper-right when there
- * is room, swinging towards straight up as the frame narrows (portrait). Hosts use it only when the
- * author has not set azimuth/elevation; `DEFAULT_STAR_PARAMS` stays the host-agnostic fallback.
+ * The opening light: the star over the camera's right shoulder (behind it, a little up and to the
+ * right), so the planet opens on its day side — about 90% of the face the camera sees is lit, the
+ * night edge on the left — and the star itself shows when the viewer orbits round. 145° / 15° is
+ * ~38° off the view axis. It is `DEFAULT_STAR_PARAMS`' direction, so a host with no camera gets it too.
  */
-export function defaultStarPlacement(input) {
-    const fov = Number.isFinite(input.fovDeg) && input.fovDeg > 0 ? input.fovDeg : 45;
-    const aspect = Number.isFinite(input.aspect) && input.aspect > 0 ? input.aspect : 1;
-    const cd = Number.isFinite(input.cameraDistance) && input.cameraDistance > 0 ? input.cameraDistance : 4;
-    const pr = Math.max(0, Number.isFinite(input.planetRadius) ? input.planetRadius : 1);
-    const starRadius = input.starRadius ?? DEFAULT_STAR_PARAMS.radius;
-    const [dLo, dHi] = STAR_PARAM_RANGES.distance;
-    const D = Math.min(dHi, Math.max(dLo, input.distance ?? DEFAULT_STAR_PARAMS.distance));
-    // Work on the image plane at unit distance (tangent units): positions and radii both scale by tan.
-    const tanV = Math.tan((fov * DEG) / 2);
-    const tanH = tanV * aspect;
-    const planetTan = cd > pr ? pr / Math.sqrt(cd * cd - pr * pr) : Infinity;
-    const starTan = (starRadius * FOCUS_GLOW_RADII) / Math.sqrt(D * D + cd * cd);
-    const rho = planetTan + starTan * 1.35; // centre distance from the view axis: disc + glow clear the planet
-    const maxX = tanH * 0.97 - starTan * 0.5; // centre in frame, disc mostly in frame
-    const maxY = tanV * 0.97 - starTan * 0.5;
-    let x = 0;
-    let y = Number.isFinite(rho) ? rho : maxY;
-    let fits = false;
-    for (let phiDeg = 30; phiDeg <= 90; phiDeg += 2) {
-        const px = rho * Math.cos(phiDeg * DEG);
-        const py = rho * Math.sin(phiDeg * DEG);
-        if (px <= maxX && py <= maxY) {
-            x = px;
-            y = py;
-            fits = true;
-            break;
-        }
-    }
-    // Ray from the camera through (x, y) on the image plane, hit on the sphere |P| = D.
-    const len = Math.hypot(x, y, 1);
-    const ux = x / len;
-    const uy = y / len;
-    const uz = -1 / len;
-    const cu = cd * uz; // C · u with C = (0, 0, cd)
-    const t = -cu + Math.sqrt(Math.max(0, cu * cu - cd * cd + D * D));
-    const px = ux * t;
-    const py = uy * t;
-    const pz = cd + uz * t;
-    const round = (v) => Math.round(v * 10) / 10;
-    return {
-        azimuth: round(Math.atan2(px, -pz) / DEG),
-        elevation: round(Math.asin(Math.max(-1, Math.min(1, py / D))) / DEG),
-        fits,
-    };
+export const OVER_THE_SHOULDER = { azimuth: DEFAULT_STAR_PARAMS.azimuth, elevation: DEFAULT_STAR_PARAMS.elevation };
+/**
+ * Azimuth / elevation of the default star for a camera on +Z looking at the origin: over the
+ * camera's shoulder (`OVER_THE_SHOULDER`), so the world opens lit. The star sits ≥ 0.79 × its
+ * distance (≥ 15.8 units) out on +Z, behind any host camera, so the frame never changes it. Hosts
+ * use it only when the author has not set azimuth/elevation; `DEFAULT_STAR_PARAMS` stays the
+ * host-agnostic fallback.
+ */
+export function defaultStarPlacement(_input) {
+    return { azimuth: OVER_THE_SHOULDER.azimuth, elevation: OVER_THE_SHOULDER.elevation, fits: true };
 }

package/dist/star/index.d.ts

@@ -9,7 +9,7 @@ export type { StarParams, StarMultiplicity, SpectralClass } from './params.js';
 export { blackbodyColor } from './blackbody.js';
 export type { RGB } from './blackbody.js';
 export { starLayout, starPositions, starSystemPosition, starFocusRadius, flareAt } from './layout.js';
-export { framingDistance, defaultStarPlacement } from './framing.js';
+export { framingDistance, defaultStarPlacement, OVER_THE_SHOULDER } from './framing.js';
 export type { StarPlacement, StarPlacementInput } from './framing.js';
 export type { StarLayout, LaidOutStar, StarOrbit, StarRole, FlareState } from './layout.js';
 export { starParamsFromStellarData, temperatureFromSpectralType, starCountFromPlanetName, luminosityClassFromSpectralType, mainSequenceLuminosity, mainSequenceRadius, mainSequenceTemperature, separationFromAu, youthFromAge, } from './stellarData.js';

package/dist/star/index.js

@@ -8,7 +8,7 @@ export { STAR_QUALITY, normalizeStarQuality } from './quality.js';
 export { DEFAULT_STAR_PARAMS, STAR_PARAM_RANGES, normalizeStarParams, spectralClass, } from './params.js';
 export { blackbodyColor } from './blackbody.js';
 export { starLayout, starPositions, starSystemPosition, starFocusRadius, flareAt } from './layout.js';
-export { framingDistance, defaultStarPlacement } from './framing.js';
+export { framingDistance, defaultStarPlacement, OVER_THE_SHOULDER } from './framing.js';
 export { starParamsFromStellarData, temperatureFromSpectralType, starCountFromPlanetName, luminosityClassFromSpectralType, mainSequenceLuminosity, mainSequenceRadius, mainSequenceTemperature, separationFromAu, youthFromAge, } from './stellarData.js';
 export { DEFAULT_AMBIENT, DEFAULT_STAR_LIGHTING, systemLightColor, keyLightIntensity, fillLightIntensity, lightingFromLegacy, LEGACY_AMBIENT_REFERENCE, LEGACY_AMBIENT_MAX, normalizeStarLighting, parseTint, } from './lighting.js';
 export { minStarDistance, maxStarDistance, SKY_MARGIN_FRACTION, sceneOuterRadius, STAR_DISTANCE_MARGIN, MAX_STAR_ANGULAR_RADIUS_DEG, } from './bounds.js';

package/dist/star/layout.js

@@ -124,8 +124,7 @@ function distantFor(p, reach) {
     if (!p.distantCompanion)
         return null;
     const r = createLcg(`${p.seed}|distant`);
-    // Default: up and back towards the frame's centre from the host — above the planet rather than
-    // behind it, and inside a typical frame when the host itself is placed beside the planet.
+    // Default: a little above the host and swung towards the scene's −Z axis — never on top of it.
     const inward = p.azimuth >= 0 ? -1 : 1;
     let azimuth = p.distantAzimuth ?? wrapDeg(p.azimuth + inward * lerp(12, 22, r()));
     let elevation = p.distantElevation ?? Math.min(60, p.elevation + lerp(6, 11, r()));

package/dist/star/params.js

@@ -10,8 +10,9 @@ export const DEFAULT_STAR_PARAMS = Object.freeze({
     separation: 2,
     seed: 1,
     distance: 20,
-    azimuth: 16,
-    elevation: 10,
+    // Over the camera's shoulder (`OVER_THE_SHOULDER` in framing.ts): worlds open on their day side.
+    azimuth: 145,
+    elevation: 15,
     companionTemperatureK: 0,
     companionRadius: 0,
     distantCompanion: false,

package/dist/types/config/env.d.ts

@@ -0,0 +1,12 @@
+/** @param {string | null | undefined} url */
+export function setPublicBase(url: string | null | undefined): void;
+/** @returns {string} */
+export function getPublicBase(): string;
+/**
+ * @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: string): string;
+/** @type {string | null} */
+export let __PUBLIC_BASE: string | null;

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

@@ -0,0 +1,2 @@
+export { loadTextureConfig, getTextureOptions, getTextureChoices, getDefaultTexture, getSkyboxOptions, getDefaultSkybox, getTextureFallbackUrl } from "./textureConfig.js";
+export { setPublicBase, getPublicBase, resolvePublicUrl } from "./env.js";

package/dist/types/config/textureConfig.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 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
+ */
+export function loadTextureConfig(configUrl?: string, useCache?: boolean): Promise<Object>;
+/**
+ * @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.
+ *
+ * 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).
+ */
+/**
+ * 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
+ * @returns {Promise<TextureChoice[]>} Choice records in catalogue order
+ */
+export function getTextureChoices(category: string, config?: Object): Promise<TextureChoice[]>;
+/**
+ * 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
+ */
+export function getTextureOptions(category: string, config?: Object): Promise<Object>;
+/**
+ * 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
+ */
+export function getDefaultTexture(category: string, config?: Object): Promise<string>;
+/**
+ * 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
+ * @returns {string|null} Resolved fallback texture URL or null
+ */
+export function getTextureFallbackUrl(category: string, textureUrl: string, config?: Object | null): string | 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
+ */
+export function getTextureById(category: string, textureId: string, config?: Object): Promise<Object | 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
+ * @returns {Promise<string|null>} Full texture URL
+ */
+export function getTextureUrl(category: string, textureId: string, config?: Object): Promise<string | 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
+ */
+export function searchTexturesByTags(category: string, tags: string[], config?: Object): Promise<Object[]>;
+/**
+ * Get skybox options formatted for GUI dropdowns
+ * @param {Object} config - Optional pre-loaded config object
+ * @returns {Promise<Object>} Options object with labels and IDs
+ */
+export function getSkyboxOptions(config?: Object): Promise<Object>;
+/**
+ * Get default skybox ID
+ * @param {Object} config - Optional pre-loaded config object
+ * @returns {Promise<string>} Default skybox ID
+ */
+export function getDefaultSkybox(config?: Object): Promise<string>;
+/**
+ * Reload configuration (force refresh)
+ * @param {string} configUrl - Override config URL
+ * @returns {Promise<Object>} Fresh configuration object
+ */
+export function reloadTextureConfig(configUrl?: string): Promise<Object>;
+/**
+ * Get configuration metadata
+ * @param {Object} config - Optional pre-loaded config object
+ * @returns {Promise<Object>} Configuration metadata
+ */
+export function getConfigMetadata(config?: Object): Promise<Object>;
+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.
+     *
+     * 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).
+     */
+    still: string | null;
+};

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

@@ -0,0 +1,2 @@
+export { getLightFresnel } from "./lightFresnel.js";
+export { ensureDefaultLights, updateDefaultLights, setHemisphereEnabled } from "./lights.js";

package/dist/types/core/lightFresnel.d.ts

@@ -0,0 +1,5 @@
+export function getLightFresnel({ rimHex, facingHex }?: {
+    rimHex?: number | undefined;
+    facingHex?: number | undefined;
+}): THREE.ShaderMaterial;
+import * as THREE from "three";

package/dist/types/core/lights.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Ensure a scene has the default hemisphere + ambient lights. Idempotent PER SCENE.
+ *
+ * A multi-orbiter realm renders N independent scenes through one renderer. A module-level
+ * singleton light is wrong twice over — it's only added to the FIRST scene, and a THREE light can
+ * live in just one scene (adding it to a second removes it from the first), so scenes 2..N rendered
+ * DARK ("only one entangled world"). So create + add the lights PER scene, keyed by name so a
+ * re-call on the same scene is a no-op. Single-orbiter (one scene) is unchanged.
+ *
+ * @param {import('three').Scene} scene
+ * @returns {{ hemi: import('three').HemisphereLight, ambient: import('three').AmbientLight }}
+ */
+export function ensureDefaultLights(scene: import("three").Scene): {
+    hemi: import("three").HemisphereLight;
+    ambient: import("three").AmbientLight;
+};
+/**
+ * Apply a lighting patch to ONE scene's default lights.
+ *
+ * The scene is required. This used to address module-global light refs pointing at whichever scene
+ * was ensured last, so on a page rendering several scenes every lighting update landed on one of
+ * them — a shared-renderer page (N feed worlds, N orbiters) lit the wrong world.
+ *
+ * Every field is optional; an omitted one leaves that part of the lighting as it is.
+ *
+ * @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: import("three").Scene, { ambientIntensity, diffuseIntensity, lightColor, lightDirection, hemisphere }?: {
+    ambientIntensity?: number | undefined;
+    diffuseIntensity?: number | undefined;
+    lightColor?: string | number | THREE.Color | undefined;
+    lightDirection?: {
+        x: number;
+        y?: number;
+        z?: number;
+    } | undefined;
+    hemisphere?: boolean | undefined;
+}): void;
+/**
+ * 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: import("three").Scene, on: boolean): void;
+/** @param {import('three').Scene} scene */
+export function addDefaultLights(scene: import("three").Scene): {
+    hemi: import("three").HemisphereLight;
+    ambient: import("three").AmbientLight;
+};
+import * as THREE from 'three';

package/dist/types/index.d.ts

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

package/dist/types/loaders/bodyTextureLoader.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @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: string, { signal, renderer }?: {
+    signal?: AbortSignal | undefined;
+    renderer?: THREE.WebGLRenderer | null | undefined;
+}): Promise<any>;
+import * as THREE from 'three';

package/dist/types/loaders/cubeMapLoader.d.ts

@@ -0,0 +1,70 @@
+export function normalizeSkycubeName(raw: any): string;
+export function buildSkycubefaceKeys(skycubeId: any, 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.)
+ *
+ * @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 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.
+ * @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: import("three").Scene, resource: unknown): void;
+/**
+ * @param {import('three').Scene} scene
+ * @param {{ renderer?: import('three').WebGLRenderer | null }} [opts]
+ */
+export function initSpaceScene(scene: import("three").Scene, { renderer }?: {
+    renderer?: import("three").WebGLRenderer | null;
+}): Promise<void>;
+/**
+ * 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: import("three").Mesh;
+} | (import("three").CubeTexture & {
+    mesh?: undefined;
+});
+import * as THREE from 'three';

package/dist/types/loaders/glbLoader.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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.
+ */
+export function loadGLB(url: string, { retries, signal, onProgress, applyFlags, withCredentials, renderer, emissiveIntensity }?: {
+    retries?: number | undefined;
+    signal?: AbortSignal | undefined;
+    onProgress?: ((event: ProgressEvent) => void) | undefined;
+    applyFlags?: object | undefined;
+    withCredentials?: boolean | undefined;
+    emissiveIntensity?: number | undefined;
+    renderer: import("three").WebGLRenderer;
+}): Promise<any>;

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

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

package/dist/types/loaders/ktx2.d.ts

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

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

@@ -0,0 +1,2 @@
+export { MoonsManager } from "./moonsManager.js";
+export { generateMoons, DEFAULT_MOON_TEX_KTX2, DEFAULT_MOON_TEX_PNG, MOON_BASE_RADIUS, MOON_SCALE_MIN, MOON_SCALE_SPAN, MOON_MAX_RADIUS, MOON_ORBIT_SCATTER, MOON_HEIGHT_SCATTER } from "./moonsGeneration.js";

package/dist/types/moons/moonsGeneration.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @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 function generateMoons({ count, orbitRadius, textureKTX2, texturePNG, textureFallback, useTexture, seed, textureKey, moonColor, brightness, emissiveColor, emissiveIntensity, emissiveLift, roughness, metalness, debug, smooth, geometryWidthSegments, geometryHeightSegments, useBumpFromColor, bumpScale, debugShowUvGrid, debugShowReferenceMoon, referenceMoonScale, useEmissiveMapFromTexture, 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;
+}): Promise<THREE.Group<THREE.Object3DEventMap> | null>;
+export const DEFAULT_MOON_TEX_KTX2: string;
+export const DEFAULT_MOON_TEX_PNG: string;
+/** Radius of the shared moon sphere before per-moon scale. */
+export const MOON_BASE_RADIUS: 0.1;
+/** Per-moon scale range: MIN + random * SPAN. */
+export const MOON_SCALE_MIN: 0.07;
+export const MOON_SCALE_SPAN: 0.15;
+/** Largest moon radius in scene units (base radius × largest scale). */
+export const MOON_MAX_RADIUS: number;
+/** Each moon's orbit radius varies by ± half of this around the requested orbit. */
+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;
+import * as THREE from 'three';

package/dist/types/moons/moonsManager.d.ts

@@ -0,0 +1,27 @@
+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: import("three").Scene, { renderer }?: {
+        renderer?: THREE.WebGLRenderer | null | undefined;
+    });
+    scene: THREE.Scene;
+    renderer: THREE.WebGLRenderer | null | undefined;
+    group: THREE.Group<THREE.Object3DEventMap> | null;
+    _opId: number;
+    _emissiveLift: number | undefined;
+    setAmount(count: any, opts?: {}): Promise<void>;
+    /**
+     * 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: any): void;
+    /**
+     * Remove the moons from the scene and free their GPU resources. `scene.remove(group)` alone leaks
+     * the instanced geometry, materials and the shared moon texture on every view teardown.
+     */
+    dispose(): void;
+}
+import * as THREE from 'three';