entangled-worlds-orbiters-shared 3.3.0 → 4.0.0

package/dist/world/worldTexture.js

@@ -0,0 +1,299 @@
+import * as THREE from 'three';
+import { loadTexture } from '../loaders/bodyTextureLoader.js';
+import { applyFlagsToMaterial } from '../utils/materials.js';
+import { getLightFresnel } from '../core/lightFresnel.js';
+import { createCloudShell } from './cloudShell.js';
+import { resolvePublicUrl } from '../config/env.js';
+// Debug tag so you can verify the loaded file version in console
+export const WORLD_TEXTURE_DEBUG_TAG = 'WT:vFlipGeom-r3@2025-10-28T17:22:00Z';
+// Enable debug if query/localStorage says so; expose tag
+if (typeof window !== 'undefined') {
+    const q = (window.location && window.location.search) || '';
+    const qsDebug = /(?:[?&])debugTextures=1(?:&|$)/.test(q);
+    const lsDebug = (window.localStorage && window.localStorage.DEBUG_TEXTURE_FLIP === '1') || false;
+    if (!window.DEBUG_TEXTURE_FLIP && (qsDebug || lsDebug)) {
+        window.DEBUG_TEXTURE_FLIP = true;
+    }
+    window.EW_WT_DEBUG_TAG = WORLD_TEXTURE_DEBUG_TAG;
+    if (window.DEBUG_TEXTURE_FLIP) {
+        console.info('[worldTexture] loaded', WORLD_TEXTURE_DEBUG_TAG);
+    }
+}
+const WT_LOGGED_FIRST_CALL = false;
+export const EARTH_RADIUS_UNITS = 0.5; // scene units
+/**
+ * Simplified detection: width = height -> rectangular, width = 2×height -> equirectangular
+ */
+function isLikelyEquirectangular(img) {
+    const aspectRatio = img.width / img.height;
+    // Check for 2:1 aspect ratio (equirectangular)
+    const is2to1 = Math.abs(aspectRatio - 2.0) < 0.1;
+    // Check for 1:1 aspect ratio (square -> treat as rectangular)
+    const is1to1 = Math.abs(aspectRatio - 1.0) < 0.1;
+    if (is1to1) {
+        return false; // Square images are rectangular
+    }
+    if (is2to1) {
+        return true; // 2:1 images are equirectangular
+    }
+    // For other aspect ratios, default to rectangular
+    return false;
+}
+/**
+ * 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 async function makeSphere({ textureUrl, renderer, flags, uOffset, textureOffsetDeg, mirrorX, mirrorDuplicateX, // optional, still supported for explicit override
+autoDetectEquirectangular = true, forceEquirectangular = false, forceRectangular = false, 
+// Wrapping params
+wrapS = 'repeat', wrapT = 'clamp', repeatX, repeatY, rotationDeg, center = [0.5, 0.5], flipY, 
+// NEW: sphere geometry controls (optional)
+sphereRadius, sphereWidthSegments, sphereHeightSegments, 
+// PBR material tuning (optional)
+materialRoughness, materialMetalness, 
+// NEW: glow controls
+glow = true, glowRimHex = 0x66ccff, glowFacingHex = 0x000000, glowScale = 1.18, glowBias = 0.02, glowFresnelScale = 1.0, glowPower = 3.5, 
+// texture clouds controls (simplified)
+cloudsEnabled = false, cloudsTextureUrl = '/assets/texture/2k_earth_clouds.jpg', cloudsColor = 0xffffff, cloudsOpacity = 0.6, cloudsSpeed = 0.015, } = {}) {
+    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);
+    let meshGeometry = geometry; // may clone/flip UVs for compressed textures
+    // Diffuse-only (Lambert) at every tier: under the star's key light the physical (Standard) material
+    // cost +20% GPU on low for a barely visible sheen. `materialRoughness` /
+    // `materialMetalness` stay accepted from saved worlds but no longer change the look.
+    const material = new THREE.MeshLambertMaterial({ color: 0xffffff });
+    const WRAP = {
+        clamp: THREE.ClampToEdgeWrapping,
+        repeat: THREE.RepeatWrapping,
+        mirror: THREE.MirroredRepeatWrapping,
+    };
+    // For compressed textures (e.g., KTX2) WebGL cannot apply UNPACK_FLIP_Y at upload.
+    // To normalize orientation across loaders, emulate vertical flip in UV sampling:
+    // v' = 1 - v  => repeat.y = -repeat.y, offset.y = 1 - offset.y
+    const normalizeCompressedFlip = (t) => {
+        if (!t || !t.isCompressedTexture)
+            return;
+        const wantFlip = (typeof flipY === 'boolean') ? flipY : true; // match uncompressed default
+        if (!wantFlip)
+            return;
+        const rY = (t.repeat && typeof t.repeat.y === 'number') ? t.repeat.y : 1;
+        const oY = (t.offset && typeof t.offset.y === 'number') ? t.offset.y : 0;
+        t.repeat.y = -rY;
+        t.offset.y = 1 - oY;
+        t.needsUpdate = true;
+    };
+    // Emulate vertical flip for compressed textures (e.g., KTX2) using UV transform
+    const normalizeCompressedFlipY = (t, desired) => {
+        if (!t || !t.isCompressedTexture)
+            return;
+        const wantFlip = (typeof desired === 'boolean') ? desired : true; // default to match uncompressed loader
+        const rY = t.repeat?.y ?? 1;
+        const oY = t.offset?.y ?? 0;
+        if (wantFlip) {
+            t.repeat.y = -Math.abs(rY);
+            t.offset.y = 1 - oY;
+        }
+        else {
+            t.repeat.y = Math.abs(rY);
+            t.offset.y = 0;
+        }
+        t.needsUpdate = true;
+    };
+    // Flip UV.y on a cloned geometry (keeps other layers safe)
+    const flipGeometryUVY = (geom) => {
+        if (!geom || !geom.attributes || !geom.attributes.uv)
+            return 0;
+        const uv = geom.attributes.uv;
+        const arr = uv.array;
+        for (let i = 1; i < arr.length; i += 2) {
+            arr[i] = 1 - arr[i]; // v = 1 - v
+        }
+        uv.needsUpdate = true;
+        return uv.count;
+    };
+    // Attach a Fresnel glow mesh as a child of the sphere mesh
+    function createGlow(rimHex, facingHex) {
+        const fresnelMat = getLightFresnel({ rimHex, facingHex });
+        // tweak uniforms for stronger rim
+        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);
+        // Slightly larger to avoid z-fighting and create a halo
+        const s = Math.max(glowScale, 1.0);
+        fresnelMesh.scale.set(s, s, s);
+        fresnelMesh.renderOrder = 999; // render after base mesh
+        fresnelMesh.name = 'worldTextureGlow';
+        return fresnelMesh;
+    }
+    const chosenTexture = textureUrl; // require explicit textureUrl — no implicit default
+    if (chosenTexture) {
+        try {
+            const tex = await loadTexture(chosenTexture, { renderer });
+            tex.colorSpace = THREE.SRGBColorSpace;
+            tex.anisotropy = 8;
+            if (typeof flipY === 'boolean')
+                tex.flipY = flipY;
+            // Only enable mipmaps for non-compressed, power-of-two textures
+            // A KTX2 load is a CompressedTexture, which says so; a plain Texture has no such field.
+            const isCompressed = tex.isCompressedTexture;
+            const img = tex.image;
+            const isPowerOfTwo = img && ((img.width & (img.width - 1)) === 0) && ((img.height & (img.height - 1)) === 0);
+            tex.generateMipmaps = !isCompressed && isPowerOfTwo;
+            // Decide mapping approach
+            let shouldMirrorDuplicate = mirrorDuplicateX;
+            if (tex.image) {
+                const img = tex.image;
+                let isEquirectangular = false;
+                if (forceEquirectangular) {
+                    isEquirectangular = true;
+                }
+                else if (forceRectangular) {
+                    isEquirectangular = false;
+                }
+                else if (autoDetectEquirectangular && typeof mirrorDuplicateX === 'undefined') {
+                    const aspectDetection = isLikelyEquirectangular(img);
+                    isEquirectangular = aspectDetection && Math.abs(img.width / img.height - 2.0) < 0.05;
+                }
+                else {
+                    isEquirectangular = !shouldMirrorDuplicate;
+                }
+                shouldMirrorDuplicate = !isEquirectangular;
+            }
+            // Default to rectangular duplicate if still undefined
+            if (typeof shouldMirrorDuplicate === 'undefined') {
+                shouldMirrorDuplicate = true;
+            }
+            // Seam alignment (offset only)
+            let offsetX = 0;
+            if (typeof uOffset === 'number') {
+                offsetX = ((uOffset % 1) + 1) % 1;
+            }
+            else if (typeof textureOffsetDeg === 'number') {
+                offsetX = (((textureOffsetDeg / 360) % 1) + 1) % 1;
+            }
+            const applyWrapOptions = (t) => {
+                t.wrapS = WRAP[wrapS] ?? THREE.RepeatWrapping;
+                t.wrapT = WRAP[wrapT] ?? THREE.ClampToEdgeWrapping;
+                // Compressed textures + NPOT prefer clamp to avoid artifacts
+                if (isCompressed) {
+                    t.wrapS = THREE.ClampToEdgeWrapping;
+                    t.wrapT = THREE.ClampToEdgeWrapping;
+                }
+                if (Array.isArray(center) && center.length === 2)
+                    t.center.set(center[0], center[1]);
+                if (typeof rotationDeg === 'number')
+                    t.rotation = (rotationDeg * Math.PI) / 180;
+                if (typeof repeatX === 'number' || typeof repeatY === 'number') {
+                    t.repeat.set(typeof repeatX === 'number' ? repeatX : t.repeat.x, typeof repeatY === 'number' ? repeatY : t.repeat.y);
+                }
+                t.offset.x = offsetX;
+                if (mirrorX) {
+                    t.repeat.x = -Math.abs(t.repeat.x || 1);
+                    t.offset.x = (t.offset.x + 1) % 1;
+                }
+                t.needsUpdate = true;
+            };
+            if (shouldMirrorDuplicate && tex.image && typeof document !== 'undefined') {
+                // Create a mirrored duplicate without any blending
+                const img = tex.image;
+                try {
+                    const canvas = document.createElement('canvas');
+                    canvas.width = img.width * 2;
+                    canvas.height = img.height;
+                    // A missing 2D context throws on first use and lands in the fallback below, as before.
+                    const ctx = canvas.getContext('2d');
+                    // Left half: original
+                    ctx.drawImage(img, 0, 0, img.width, img.height);
+                    // Right half: horizontally flipped copy
+                    ctx.save();
+                    ctx.translate(img.width, 0);
+                    ctx.scale(-1, 1);
+                    ctx.drawImage(img, -img.width, 0, img.width, img.height);
+                    ctx.restore();
+                    const processedTex = new THREE.CanvasTexture(canvas);
+                    processedTex.colorSpace = THREE.SRGBColorSpace;
+                    processedTex.generateMipmaps = true;
+                    processedTex.anisotropy = 8;
+                    applyWrapOptions(processedTex);
+                    material.map = processedTex;
+                    material.needsUpdate = true;
+                }
+                catch (e) {
+                    // Fallback: use mirrored repeat directly
+                    tex.wrapS = THREE.MirroredRepeatWrapping;
+                    tex.wrapT = WRAP[wrapT] ?? THREE.ClampToEdgeWrapping;
+                    tex.repeat.x = Math.max(2, typeof repeatX === 'number' ? repeatX : 2);
+                    applyWrapOptions(tex);
+                    // If compressed (e.g., KTX2), normalize vertical orientation using sampling transform
+                    normalizeCompressedFlip(tex);
+                    material.map = tex;
+                    material.needsUpdate = true;
+                }
+            }
+            else {
+                // Equirectangular or no canvas: just use original texture
+                applyWrapOptions(tex);
+                const wantFlip = (typeof flipY === 'boolean') ? flipY : true;
+                if (isCompressed && wantFlip) {
+                    meshGeometry = geometry.clone();
+                    flipGeometryUVY(meshGeometry);
+                }
+                else if (isCompressed) {
+                    tex.repeat.y = Math.abs(tex.repeat?.y ?? 1);
+                    tex.offset.y = 0;
+                    tex.needsUpdate = true;
+                }
+                material.map = tex;
+                material.needsUpdate = true;
+            }
+        }
+        catch (e) {
+            console.warn('[worldTexture] Failed to load texture:', e);
+        }
+    }
+    if (flags)
+        applyFlagsToMaterial(material, flags);
+    const mesh = new THREE.Mesh(meshGeometry, material);
+    // Named so consumers can find the planet body by name (mirrors the
+    // normal-mode body's `worldNormalSphere`) — e.g. to modulate its material.
+    mesh.name = 'worldTextureSphere';
+    mesh.position.set(0, 0, 0);
+    // NEW: add cloud shell before glow
+    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);
+    }
+    // Optionally add glow as a child of the mesh so it follows transforms
+    if (glow) {
+        const glowMesh = createGlow(glowRimHex, glowFacingHex);
+        mesh.add(glowMesh);
+    }
+    return mesh;
+}

package/package.json

@@ -1,43 +1,43 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "3.3.0",
+  "version": "4.0.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",
+  "main": "dist/index.js",
+  "types": "./dist/index.d.ts",
   "sideEffects": false,
   "exports": {
     ".": {
-      "types": "./dist/types/index.d.ts",
-      "default": "./src/index.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./world": {
-      "types": "./dist/types/world/index.d.ts",
-      "default": "./src/world/index.js"
+      "types": "./dist/world/index.d.ts",
+      "default": "./dist/world/index.js"
     },
     "./moons": {
-      "types": "./dist/types/moons/index.d.ts",
-      "default": "./src/moons/index.js"
+      "types": "./dist/moons/index.d.ts",
+      "default": "./dist/moons/index.js"
     },
     "./loaders": {
-      "types": "./dist/types/loaders/index.d.ts",
-      "default": "./src/loaders/index.js"
+      "types": "./dist/loaders/index.d.ts",
+      "default": "./dist/loaders/index.js"
     },
     "./render": {
-      "types": "./dist/types/render/index.d.ts",
-      "default": "./src/render/index.js"
+      "types": "./dist/render/index.d.ts",
+      "default": "./dist/render/index.js"
     },
     "./core": {
-      "types": "./dist/types/core/index.d.ts",
-      "default": "./src/core/index.js"
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
     },
     "./config": {
-      "types": "./dist/types/config/index.d.ts",
-      "default": "./src/config/index.js"
+      "types": "./dist/config/index.d.ts",
+      "default": "./dist/config/index.js"
     },
     "./utils": {
-      "types": "./dist/types/utils/index.d.ts",
-      "default": "./src/utils/index.js"
+      "types": "./dist/utils/index.d.ts",
+      "default": "./dist/utils/index.js"
     },
     "./clock": {
       "types": "./dist/clock/index.d.ts",
@@ -91,7 +91,6 @@
   "files": [
     "src/**/*",
     "!src/**/*.test.ts",
-    "!src/**/*.test.js",
     "!src/**/fixtures/**",
     "dist/**/*",
     "public/**/*",
@@ -111,21 +110,19 @@
   "author": "Plantasia Space",
   "license": "MIT",
   "peerDependencies": {
-    "three": "^0.166.1",
-    "three-stdlib": "^2.34.0"
+    "three": "^0.166.1"
   },
   "peerDependenciesMeta": {
     "three": {
       "optional": true
-    },
-    "three-stdlib": {
-      "optional": true
     }
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^20.19.0",
     "@types/three": "^0.166.0",
+    "@typescript-eslint/eslint-plugin": "^8.72.1",
+    "@typescript-eslint/parser": "^8.72.1",
     "eslint": "^10.0.0",
     "globals": "^17.3.0",
     "three": "^0.166.1",
@@ -144,21 +141,14 @@
   "scripts": {
     "lint": "eslint .",
     "lint:strict": "eslint . --max-warnings=0",
-    "lint:fallback": "node scripts/lint.js",
-    "build:ts": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
-    "build:clock": "npm run build:ts",
-    "prepare": "npm run build:ts",
+    "build": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+    "build:ts": "npm run build",
+    "prepare": "npm run build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test:clock": "node --test --import tsx src/clock/*.test.ts",
-    "test:notes": "node --test --import tsx src/notes/*.test.ts",
-    "test:faust": "node --test --import tsx src/faust/*.test.ts",
-    "test:studio": "node --test --import tsx src/studio/*.test.js",
-    "test:uploads": "node --test --import tsx src/uploads/*.test.js",
-    "test:audio": "node --test --import tsx src/audio/*.test.ts",
-    "test:render": "node --test src/render/*.test.js",
-    "test": "npm run test:clock && npm run test:notes && npm run test:faust && npm run test:studio && npm run test:uploads && npm run test:audio && npm run test:render && npm run test:moons && npm run test:star",
-    "test:moons": "node --test src/moons/*.test.js",
-    "test:star": "node --test --import tsx src/star/*.test.ts",
+    "test": "node --test --import tsx $(find src -name '*.test.ts' | sort)",
+    "baseline:update": "tsx scripts/api-baseline.ts update",
+    "baseline:release": "tsx scripts/api-baseline.ts release",
+    "check:exports": "tsx scripts/check-exports.ts",
     "bench:star:build": "esbuild bench/star/main.ts --bundle --format=esm --target=es2022 --outfile=bench/star/build/main.js --log-level=warning",
     "bench:star": "npm run bench:star:build && tsx bench/star/run.ts"
   }

package/src/config/env.ts

@@ -0,0 +1,48 @@
+// Runtime public base URL helper for building absolute asset URLs at runtime
+
+/**
+ * `import.meta` as this module reads it. A consumer's bundler (Vite) fills `import.meta.env` and
+ * replaces `import.meta.env.X` at build time; under plain Node `env` is undefined, so the read keeps
+ * its guard. The cast compiles to the same `import.meta.env.X`. Not exported: no global type is added.
+ */
+type ViteImportMeta = { env?: Record<string, string | undefined> };
+
+/** The `window` global this module mirrors the public base to. Not exported: no global type is added. */
+type PublicBaseWindow = Window & { VITE_PUBLIC_HERBARIUM_BASE?: string | null };
+
+// Mutable module-scoped variable to allow apps to override at startup
+export let __PUBLIC_BASE: string | null = null;
+
+// Set the public base (strips trailing slash) and mirror to window for convenience
+export function setPublicBase(url: string | null | undefined): void {
+  __PUBLIC_BASE = (url || '').replace(/\/$/, '');
+  if (typeof window !== 'undefined') (window as PublicBaseWindow).VITE_PUBLIC_HERBARIUM_BASE = __PUBLIC_BASE;
+}
+
+// Get the current public base from (in order): explicit set value, envs, or default
+export function getPublicBase(): string {
+  // The cast stays inline on each read so the emitted JS is the literal `import.meta.env.X` a
+  // bundler looks for.
+  const envVal =
+    (typeof import.meta !== 'undefined' &&
+      (import.meta as ViteImportMeta).env &&
+      (import.meta as ViteImportMeta).env!.VITE_PUBLIC_HERBARIUM_BASE) ||
+    (typeof window !== 'undefined' && (window as PublicBaseWindow).VITE_PUBLIC_HERBARIUM_BASE) ||
+    null;
+  const base = (__PUBLIC_BASE || envVal || '').toString();
+  return base ? base.replace(/\/$/, '') : '';
+}
+
+// Resolve a possibly-relative path against the current public base
+/**
+ * @param path root-relative, relative, or an absolute http(s) URL (returned unchanged).
+ *   An empty string comes back as is.
+ */
+export function resolvePublicUrl(path: string): string {
+  if (!path) return path;
+  if (/^https?:\/\//i.test(path)) return path;
+  const base = getPublicBase();
+  const p = path.startsWith('/') ? path : `/${path}`;
+  // If base is empty, return a root-relative path (same-origin)
+  return base ? `${base}${p}` : p;
+}

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

@@ -8,6 +8,13 @@ export {
   getDefaultSkybox,
   getTextureFallbackUrl
 } from './textureConfig.js';
+export type {
+  TextureConfig,
+  TextureCategory,
+  TextureItem,
+  TextureChoice,
+  TextureConfigMetadata
+} from './textureConfig.js';
 
 // runtime base helpers
 export {