entangled-worlds-orbiters-shared 3.3.0 → 4.0.0

package/dist/studio/hostTransport.d.ts

@@ -1,4 +1,5 @@
-interface WindowLike {
+/** The part of a window the host transport reads: its origin, its parent and `postMessage`. */
+export interface WindowLike {
     location: {
         origin: string;
     };
@@ -17,4 +18,3 @@ export declare function isEmbedded(win?: WindowLike | null): boolean;
  * origin or no parent — never falls back to a '*' broadcast for payloads.
  */
 export declare function postToHost(message: unknown, targetOrigin: string | null | undefined, transfer?: Transferable[], win?: WindowLike | null): boolean;
-export {};

package/dist/studio/index.d.ts

@@ -3,4 +3,4 @@ export { createAutosaveSession, type AutosaveSession, type AutosaveState, type A
 export { createPatchStore, type PatchStore } from './patchStore.js';
 export { makeHeaderBroadcast, type HeaderBroadcast, type HeaderSinkOf } from './headerBroadcast.js';
 export { createStatusChannel, type StatusChannel, type StatusSink, type StatusShowOptions, } from './statusChannel.js';
-export { isTrustedHostOrigin, isEmbedded, postToHost } from './hostTransport.js';
+export { isTrustedHostOrigin, isEmbedded, postToHost, type WindowLike } from './hostTransport.js';

package/dist/utils/dispose.d.ts

@@ -0,0 +1,5 @@
+import type * as THREE from 'three';
+/** Disposes one material or an array of them, and every disposable value hanging off each. */
+export declare function disposeMaterial(material: THREE.Material | readonly (THREE.Material | null | undefined)[] | null | undefined): void;
+/** Disposes the geometry and materials of every mesh under `obj`, then detaches it from its parent. */
+export declare function disposeObject3D(obj: THREE.Object3D | null | undefined): void;

package/dist/utils/dispose.js

@@ -0,0 +1,50 @@
+/** Disposes one material or an array of them, and every disposable value hanging off each. */
+export function disposeMaterial(material) {
+    if (!material)
+        return;
+    // A mesh can carry a single material or an array (multi-material meshes, some GLB).
+    const materials = Array.isArray(material) ? material : [material];
+    for (const mat of materials) {
+        if (!mat)
+            continue;
+        // Free the textures (and any other disposable values) hanging off the material…
+        for (const key in mat) {
+            const val = mat[key];
+            if (val && typeof val.dispose === 'function') {
+                try {
+                    val.dispose();
+                }
+                catch { }
+            }
+        }
+        // …then free the material's own GPU program. Without this the shader program
+        // leaks even though its textures were released. `dispose` is a prototype method,
+        // so the loop above never reaches it — no double-dispose.
+        if (typeof mat.dispose === 'function') {
+            try {
+                mat.dispose();
+            }
+            catch { }
+        }
+    }
+}
+/** Disposes the geometry and materials of every mesh under `obj`, then detaches it from its parent. */
+export function disposeObject3D(obj) {
+    if (!obj)
+        return;
+    const root = obj;
+    root.traverse((child) => {
+        if (child.isMesh) {
+            const mesh = child;
+            if (mesh.geometry)
+                mesh.geometry.dispose();
+            disposeMaterial(mesh.material);
+            // An InstancedMesh also owns `instanceMatrix` / `instanceColor` GPU buffers, which hang off the
+            // mesh rather than the (shared) geometry — only its own dispose() frees them.
+            if (child.isInstancedMesh)
+                child.dispose();
+        }
+    });
+    if (root.parent)
+        root.parent.remove(root);
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,3 @@
+export { ensureStandardMaterial, applyFlagsToMaterial } from './materials.js';
+export type { MaterialFlags } from './materials.js';
+export { disposeObject3D } from './dispose.js';

package/{src → dist}/utils/index.js

@@ -1,3 +1,3 @@
 // Utilities exports
 export { ensureStandardMaterial, applyFlagsToMaterial } from './materials.js';
-export { disposeObject3D } from './dispose.js';
+export { disposeObject3D } from './dispose.js';

package/dist/utils/materials.d.ts

@@ -0,0 +1,10 @@
+import * as THREE from 'three';
+/** The flags `applyFlagsToMaterial` reads; other fields are ignored. */
+export interface MaterialFlags {
+    forceOpaque?: boolean;
+    wireframe?: boolean;
+}
+/** Gives a mesh a MeshStandardMaterial (keeping its map) unless it has one; anything that is not a mesh is left alone. */
+export declare function ensureStandardMaterial(mesh: THREE.Object3D | null | undefined): void;
+/** Applies `flags` to one material (not an array); nothing happens without a material. */
+export declare function applyFlagsToMaterial(material: THREE.Material | null | undefined, flags?: MaterialFlags): void;

package/dist/utils/materials.js

@@ -0,0 +1,36 @@
+import * as THREE from 'three';
+/** Gives a mesh a MeshStandardMaterial (keeping its map) unless it has one; anything that is not a mesh is left alone. */
+export function ensureStandardMaterial(mesh) {
+    if (!mesh || !mesh.isMesh)
+        return;
+    const m = mesh;
+    const mat = m.material;
+    if (mat && !(mat instanceof THREE.MeshStandardMaterial)) {
+        m.material = new THREE.MeshStandardMaterial({
+            map: mat.map || null,
+            metalness: 0.3,
+            roughness: 0.7,
+        });
+    }
+}
+/** Applies `flags` to one material (not an array); nothing happens without a material. */
+export function applyFlagsToMaterial(material, flags = {}) {
+    if (!material)
+        return;
+    const mat = material;
+    const { forceOpaque, wireframe } = flags;
+    if (forceOpaque) {
+        if (mat.transparent || (mat.transmission && mat.transmission > 0)) {
+            mat.transparent = false;
+            mat.opacity = 1;
+            if ('transmission' in mat)
+                mat.transmission = 0;
+            mat.alphaTest = 0;
+            mat.needsUpdate = true;
+        }
+    }
+    if (wireframe) {
+        mat.wireframe = true;
+        mat.needsUpdate = true;
+    }
+}

package/dist/world/cloudShell.d.ts

@@ -0,0 +1,16 @@
+import * as THREE from 'three';
+/**
+ * `baseGeometry` is cloned for the shell; when absent a sphere is built from `baseRadius` (0.5) and
+ * the segment counts (64 × 64). Defaults: `color` 0xffffff, `opacity` 0.6, `speed` 0.015.
+ */
+export declare function createCloudShell({ baseGeometry, baseRadius, widthSegments, heightSegments, textureUrl, color, opacity, speed, renderer, }?: {
+    baseGeometry?: THREE.BufferGeometry | 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>>;

package/dist/world/cloudShell.js

@@ -0,0 +1,73 @@
+import * as THREE from 'three';
+import { loadTexture } from '../loaders/bodyTextureLoader.js';
+// Texture-only clouds material (alpha mask + tint), UV-scrolled
+async function makeTextureMaterial({ color = 0xffffff, opacity = 0.6, textureUrl, speed = 0.015, renderer = null, } = {}) {
+    // Diffuse-only (Lambert): the star's key light costs no specular pass.
+    const mat = new THREE.MeshLambertMaterial({
+        color,
+        transparent: true,
+        opacity: 1.0, // drive alpha via alphaMap
+        depthTest: true,
+        depthWrite: false,
+        side: THREE.FrontSide,
+        toneMapped: true,
+    });
+    if (textureUrl) {
+        // Thread the owning view's renderer: KTX2 cloud textures must transcode against the caller's
+        // context, not the global fallback (which shared-renderer pages don't publish at all).
+        const tex = await loadTexture(textureUrl, { renderer });
+        tex.wrapS = THREE.RepeatWrapping;
+        tex.wrapT = THREE.RepeatWrapping;
+        // Use linear space for alpha masks if available
+        tex.colorSpace = THREE.LinearSRGBColorSpace || THREE.SRGBColorSpace;
+        tex.repeat.set(1, 1); // fixed tiling
+        tex.anisotropy = 2;
+        mat.alphaMap = tex;
+        mat.opacity = opacity; // material opacity multiplier
+        mat.needsUpdate = true;
+    }
+    else {
+        // No texture -> invisible shell
+        mat.opacity = 0.0;
+    }
+    // Randomize wind direction per instance (0..360)
+    const dirRad = (Math.random() * 360 * Math.PI) / 180;
+    const wind = new THREE.Vector2(Math.cos(dirRad), Math.sin(dirRad)).multiplyScalar(speed);
+    mat.userData.update = (timeSec) => {
+        const t = mat.alphaMap;
+        if (t) {
+            t.offset.x = wind.x * timeSec;
+            t.offset.y = wind.y * timeSec;
+            t.needsUpdate = true;
+        }
+    };
+    return mat;
+}
+/**
+ * `baseGeometry` is cloned for the shell; when absent a sphere is built from `baseRadius` (0.5) and
+ * the segment counts (64 × 64). Defaults: `color` 0xffffff, `opacity` 0.6, `speed` 0.015.
+ */
+export async function createCloudShell({ baseGeometry, baseRadius = 0.5, widthSegments = 64, heightSegments = 64, textureUrl = '/assets/texture/2k_earth_clouds.jpg', color = 0xffffff, opacity = 0.6, speed = 0.015, renderer = null, } = {}) {
+    const geom = baseGeometry
+        ? baseGeometry.clone()
+        : new THREE.SphereGeometry(baseRadius, widthSegments, heightSegments);
+    const material = await makeTextureMaterial({
+        color,
+        opacity,
+        textureUrl,
+        speed,
+        renderer,
+    });
+    const mesh = new THREE.Mesh(geom, material);
+    const s = 1.001; // fixed scale
+    mesh.scale.set(s, s, s);
+    mesh.name = 'worldCloudShell';
+    mesh.renderOrder = 998; // after planet, before glow
+    mesh.onBeforeRender = () => {
+        const t = performance.now() * 0.001;
+        if (material.userData && typeof material.userData.update === 'function') {
+            material.userData.update(t);
+        }
+    };
+    return mesh;
+}

package/dist/world/index.d.ts

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

package/{src → dist}/world/index.js

@@ -4,5 +4,3 @@ export { makeSphere, EARTH_RADIUS_UNITS } from './worldTexture.js';
 export { makeNormalSphere } from './worldNormal.js';
 export { makeGLB } from './worldGLB.js';
 export { createCloudShell } from './cloudShell.js';
-
-/** @typedef {import('./worldManager.js').WorldCreator} WorldCreator */

package/dist/world/worldGLB.d.ts

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

package/dist/world/worldGLB.js

@@ -0,0 +1,22 @@
+import { loadGLB } from '../loaders/glbLoader.js';
+/**
+ * `emissiveIntensity`: textured self-glow (1 = old flat-lit look; ≈0.15 under a star light).
+ * - `modelUrl`: REQUIRED; throws without it.
+ * - `flags`: material flags (`forceOpaque`, `wireframe`).
+ * - `retries` (3), `withCredentials` (false).
+ * - `renderer`: REQUIRED at runtime (`loadGLB` throws without one); nullable here because
+ *   `WorldManager` threads its own, which may be null.
+ */
+export async function makeGLB({ modelUrl, flags, retries = 3, withCredentials = false, renderer, emissiveIntensity, } = {}) {
+    if (!modelUrl)
+        throw new Error('modelUrl is required');
+    // A null or missing renderer makes `loadGLB` throw, as it always did (see above).
+    const obj = await loadGLB(modelUrl, {
+        retries,
+        applyFlags: flags,
+        withCredentials,
+        renderer: renderer,
+        emissiveIntensity,
+    });
+    return obj;
+}

package/dist/world/worldManager.d.ts

@@ -0,0 +1,57 @@
+import type * as THREE from 'three';
+import { makeSphere } from './worldTexture.js';
+import { makeNormalSphere } from './worldNormal.js';
+/**
+ * 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: THREE.WebGLRenderer | null;
+    [key: string]: unknown;
+}) => THREE.Object3D | Promise<THREE.Object3D>;
+/**
+ * What `setMode` takes: the options of the world it builds. Mode 2 reads `modelUrl` (required there:
+ * it throws without one), `withCredentials` and `emissiveIntensity`; mode 3 passes everything to
+ * `makeNormalSphere`, the textured sphere to `makeSphere`, a registered creator gets it all as given.
+ * The manager's own renderer is always used. `flags`, when given, replaces the manager's flags for
+ * that world in every mode but 2 (which always uses the manager's).
+ */
+export type WorldModeArgs = Omit<NonNullable<Parameters<typeof makeSphere>[0]>, 'renderer'> & Omit<NonNullable<Parameters<typeof makeNormalSphere>[0]>, 'renderer'> & {
+    modelUrl?: string;
+    withCredentials?: boolean;
+    emissiveIntensity?: number;
+    [key: string]: unknown;
+};
+export declare class WorldManager {
+    scene: THREE.Scene;
+    renderer: THREE.WebGLRenderer | null;
+    externalTick: boolean;
+    /** The world on show, or null. */
+    current: THREE.Object3D | null;
+    /** Merged by `setFlags`, handed to every world built (material flags such as `forceOpaque`). */
+    flags: Record<string, unknown>;
+    onLoadStart: (() => void) | undefined;
+    onLoadEnd: (() => void) | undefined;
+    token: number;
+    /** The creators `registerWorldCreator` added, by mode. */
+    customCreators: Map<number, WorldCreator>;
+    constructor(scene: THREE.Scene, { onLoadStart, onLoadEnd, renderer, externalTick, }?: {
+        onLoadStart?: (() => void) | undefined;
+        onLoadEnd?: (() => void) | undefined;
+        renderer?: THREE.WebGLRenderer | null | undefined;
+        externalTick?: boolean | undefined;
+    });
+    /** Run the current world's per-frame updater once (externalTick hosts only; no-op otherwise). */
+    tick(timeSec: number): void;
+    /** `flags` are merged over the current flags. */
+    setFlags(flags: object): void;
+    disposeCurrent(): void;
+    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.
+     */
+    setMode(mode: number, args?: WorldModeArgs): Promise<void>;
+}

package/dist/world/worldManager.js

@@ -0,0 +1,125 @@
+import { disposeObject3D } from '../utils/dispose.js';
+import { makeGLB } from './worldGLB.js';
+import { makeSphere } from './worldTexture.js';
+import { makeNormalSphere } from './worldNormal.js';
+export class WorldManager {
+    constructor(scene, { onLoadStart, onLoadEnd, renderer, externalTick = false, } = {}) {
+        this.scene = scene;
+        // The renderer this world belongs to — threaded to the texture loaders so each view's textures
+        // bind to its OWN WebGL context (multi-view: N orbiters / N planets in one page). REQUIRED for
+        // textured worlds (3.0): the window.__EW_RENDERER fallback is gone.
+        this.renderer = renderer ?? null;
+        // Shared-renderer hosts drive world animation from THEIR loop: with `externalTick` this manager
+        // starts no internal rAF for `userData.update` worlds — the host calls `tick(timeSec)` per
+        // rendered frame instead. Otherwise N animated worlds on one page would each run their own loop,
+        // defeating the one-loop compositor.
+        this.externalTick = Boolean(externalTick);
+        this.current = null;
+        this.flags = {};
+        this.onLoadStart = onLoadStart;
+        this.onLoadEnd = onLoadEnd;
+        this.token = 0;
+        // Registry for custom world creators
+        this.customCreators = new Map();
+    }
+    /** Run the current world's per-frame updater once (externalTick hosts only; no-op otherwise). */
+    tick(timeSec) {
+        if (!this.externalTick || !this.current)
+            return;
+        const updater = this.current.userData?.update;
+        if (typeof updater !== 'function')
+            return;
+        const renderer = this.renderer;
+        if (!renderer)
+            return;
+        try {
+            updater(renderer, timeSec);
+        }
+        catch (e) {
+            console.warn('[WorldManager] update tick error:', e);
+        }
+    }
+    /** `flags` are merged over the current flags. */
+    setFlags(flags) {
+        this.flags = { ...this.flags, ...flags };
+    }
+    disposeCurrent() {
+        if (this.current) {
+            disposeObject3D(this.current);
+            this.scene.remove(this.current);
+            this.current = null;
+        }
+    }
+    // Register custom world creators for app-specific world types
+    registerWorldCreator(mode, creatorFunction) {
+        this.customCreators.set(mode, creatorFunction);
+    }
+    /**
+     * 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.
+     */
+    async setMode(mode, args = {}) {
+        const myToken = ++this.token;
+        this.onLoadStart?.();
+        try {
+            let obj;
+            const renderer = this.renderer;
+            // Check for custom creators first
+            if (this.customCreators.has(mode)) {
+                // `has` just said it is there; a creator registered as nothing (untyped callers) throws, as always.
+                obj = await this.customCreators.get(mode)({ flags: this.flags, ...args, renderer });
+            }
+            else if (mode === 2) {
+                obj = await makeGLB({
+                    // `makeGLB` throws without a model, so a mode-2 call without one fails there, as always.
+                    modelUrl: args.modelUrl,
+                    flags: this.flags,
+                    withCredentials: Boolean(args.withCredentials),
+                    renderer,
+                    emissiveIntensity: args.emissiveIntensity,
+                });
+            }
+            else if (mode === 3) {
+                obj = await makeNormalSphere({ flags: this.flags, ...args, renderer });
+            }
+            else {
+                obj = await makeSphere({ textureUrl: args.textureUrl, flags: this.flags, ...args, renderer });
+            }
+            if (this.token !== myToken) {
+                return;
+            }
+            this.disposeCurrent();
+            // An object by every type here: a creator returns one, and `makeGLB` resolves to nothing only
+            // with `retries` of 0 or less, while this call keeps its default of 3. Cast, not checked, as
+            // the JS always took it.
+            const world = obj;
+            this.scene.add(world);
+            this.current = world;
+            // If the object exposes a frame updater, run a render-time loop — unless an external host
+            // drives it via tick() (shared-renderer compositor: one loop for all worlds).
+            if (!this.externalTick && obj && obj.userData && typeof obj.userData.update === 'function' && renderer) {
+                const updater = obj.userData.update;
+                const tick = () => {
+                    if (this.current === obj) {
+                        try {
+                            updater(renderer, performance.now() * 0.001);
+                        }
+                        catch (e) {
+                            console.warn('[WorldManager] update loop error:', e);
+                        }
+                        requestAnimationFrame(tick);
+                    }
+                };
+                requestAnimationFrame(tick);
+            }
+        }
+        catch (e) {
+            console.warn('[WorldManager] setMode error:', e);
+            throw e;
+        }
+        finally {
+            if (this.token === myToken)
+                this.onLoadEnd?.();
+        }
+    }
+}

package/dist/world/worldNormal.d.ts

@@ -0,0 +1,30 @@
+import * as THREE from 'three';
+/**
+ * Create a simple sphere using THREE.MeshNormalMaterial.
+ * Accepts the same basic geometry params as textured sphere so the manager API is consistent.
+ *
+ * `flags`: material flags (`forceOpaque`, `wireframe`); `glow` adds the fresnel halo. Defaults:
+ * `glowScale` 1.18, `glowRimHex` 0x66ccff, `glowFacingHex` 0x000000, `glowBias` 0.02,
+ * `glowFresnelScale` 1, `glowPower` 3.5, `cloudsColor` 0xffffff, `cloudsOpacity` 0.6,
+ * `cloudsSpeed` 0.015.
+ */
+export declare function makeNormalSphere({ sphereRadius, sphereWidthSegments, sphereHeightSegments, flags, glow, // halo (glow) enabled
+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>>;

package/dist/world/worldNormal.js

@@ -0,0 +1,58 @@
+// Normal world (MeshNormalMaterial) implementation
+import * as THREE from 'three';
+import { EARTH_RADIUS_UNITS } from './worldTexture.js';
+import { applyFlagsToMaterial } from '../utils/materials.js';
+import { getLightFresnel } from '../core/lightFresnel.js';
+import { createCloudShell } from './cloudShell.js';
+import { resolvePublicUrl } from '../config/env.js';
+/**
+ * Create a simple sphere using THREE.MeshNormalMaterial.
+ * Accepts the same basic geometry params as textured sphere so the manager API is consistent.
+ *
+ * `flags`: material flags (`forceOpaque`, `wireframe`); `glow` adds the fresnel halo. Defaults:
+ * `glowScale` 1.18, `glowRimHex` 0x66ccff, `glowFacingHex` 0x000000, `glowBias` 0.02,
+ * `glowFresnelScale` 1, `glowPower` 3.5, `cloudsColor` 0xffffff, `cloudsOpacity` 0.6,
+ * `cloudsSpeed` 0.015.
+ */
+export async function makeNormalSphere({ sphereRadius, sphereWidthSegments, sphereHeightSegments, flags, glow, // halo (glow) enabled
+glowScale = 1.18, glowRimHex = 0x66ccff, glowFacingHex = 0x000000, glowBias = 0.02, glowFresnelScale = 1.0, glowPower = 3.5, cloudsEnabled, cloudsTextureUrl = '/assets/texture/2k_earth_clouds.jpg', cloudsColor = 0xffffff, cloudsOpacity = 0.6, cloudsSpeed = 0.015, renderer = null, } = {}) {
+    const radius = typeof sphereRadius === 'number' ? Math.max(0.0001, sphereRadius) : EARTH_RADIUS_UNITS;
+    // `Number.isFinite` does not narrow: past it, each count is a number.
+    const widthSegs = Number.isFinite(sphereWidthSegments) ? Math.max(3, Math.floor(sphereWidthSegments)) : 64;
+    const heightSegs = Number.isFinite(sphereHeightSegments) ? Math.max(2, Math.floor(sphereHeightSegments)) : 64;
+    const geometry = new THREE.SphereGeometry(radius, widthSegs, heightSegs);
+    const material = new THREE.MeshNormalMaterial();
+    if (flags)
+        applyFlagsToMaterial(material, flags);
+    const mesh = new THREE.Mesh(geometry, material);
+    mesh.name = 'worldNormalSphere';
+    // Attach halo (glow) effect if enabled
+    if (glow) {
+        const fresnelMat = getLightFresnel({ rimHex: glowRimHex, facingHex: glowFacingHex });
+        fresnelMat.uniforms.fresnelBias.value = glowBias;
+        fresnelMat.uniforms.fresnelScale.value = glowFresnelScale;
+        fresnelMat.uniforms.fresnelPower.value = glowPower;
+        const glowGeom = geometry.clone();
+        const fresnelMesh = new THREE.Mesh(glowGeom, fresnelMat);
+        fresnelMesh.scale.set(glowScale, glowScale, glowScale);
+        fresnelMesh.renderOrder = 999;
+        fresnelMesh.name = 'worldNormalGlow';
+        mesh.add(fresnelMesh);
+    }
+    // Attach clouds effect if enabled
+    if (cloudsEnabled) {
+        const cloudMesh = await createCloudShell({
+            baseGeometry: geometry,
+            baseRadius: radius,
+            widthSegments: widthSegs,
+            heightSegments: heightSegs,
+            textureUrl: resolvePublicUrl(cloudsTextureUrl),
+            color: cloudsColor,
+            opacity: cloudsOpacity,
+            speed: cloudsSpeed,
+            renderer,
+        });
+        mesh.add(cloudMesh);
+    }
+    return mesh;
+}

package/dist/world/worldTexture.d.ts

@@ -0,0 +1,56 @@
+import * as THREE from 'three';
+export declare const WORLD_TEXTURE_DEBUG_TAG = "WT:vFlipGeom-r3@2025-10-28T17:22:00Z";
+export declare const EARTH_RADIUS_UNITS = 0.5;
+/**
+ * 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).
+ *
+ * - `renderer`: REQUIRED for a KTX2 texture. `flags`: material flags (`forceOpaque`, `wireframe`).
+ * - `uOffset`: horizontal texture offset, 0..1 (wins over `textureOffsetDeg`, in degrees).
+ * - `mirrorDuplicateX`: explicit override of the equirectangular detection
+ *   (`autoDetectEquirectangular` true, `forceEquirectangular` / `forceRectangular` false).
+ * - `wrapS` ('repeat') / `wrapT` ('clamp'): `'clamp'`, `'repeat'` or `'mirror'`.
+ * - `center` ([0.5, 0.5]): texture rotation centre, `[u, v]`.
+ * - `materialRoughness` / `materialMetalness`: accepted from saved worlds; no longer change the look.
+ * - Defaults: `glow` true, `glowRimHex` 0x66ccff, `glowFacingHex` 0x000000, `glowScale` 1.18,
+ *   `glowBias` 0.02, `glowFresnelScale` 1, `glowPower` 3.5, `cloudsEnabled` false, `cloudsColor`
+ *   0xffffff, `cloudsOpacity` 0.6, `cloudsSpeed` 0.015.
+ */
+export declare function makeSphere({ textureUrl, renderer, flags, uOffset, textureOffsetDeg, mirrorX, mirrorDuplicateX, // optional, still supported for explicit override
+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>>;