entangled-worlds-orbiters-shared 3.1.0 → 4.0.0

package/README.md

@@ -21,6 +21,7 @@ In `entangled-worlds-orbiters-shared/`:
 
 ```bash
 npm install
+npm run build   # consumers run dist/: build again after every change
 npm link
 ```
 
@@ -76,7 +77,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`)
@@ -145,10 +146,10 @@ Effects:
 
 ## Peer Dependencies
 
-This library requires Three.js and three-stdlib as peer dependencies:
+This library requires Three.js as a peer dependency:
 
 ```bash
-npm install three three-stdlib
+npm install three
 ```
 
 ## License

package/dist/config/env.d.ts

@@ -0,0 +1,8 @@
+export declare let __PUBLIC_BASE: string | null;
+export declare function setPublicBase(url: string | null | undefined): void;
+export declare function getPublicBase(): string;
+/**
+ * @param path root-relative, relative, or an absolute http(s) URL (returned unchanged).
+ *   An empty string comes back as is.
+ */
+export declare function resolvePublicUrl(path: string): string;

package/dist/config/env.js

@@ -0,0 +1,36 @@
+// Runtime public base URL helper for building absolute asset URLs at runtime
+// Mutable module-scoped variable to allow apps to override at startup
+export let __PUBLIC_BASE = null;
+// Set the public base (strips trailing slash) and mirror to window for convenience
+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
+export function getPublicBase() {
+    // 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.env &&
+        import.meta.env.VITE_PUBLIC_HERBARIUM_BASE) ||
+        (typeof window !== 'undefined' && window.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) {
+    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/dist/config/index.d.ts

@@ -0,0 +1,3 @@
+export { loadTextureConfig, getTextureOptions, getTextureChoices, getDefaultTexture, getSkyboxOptions, getDefaultSkybox, getTextureFallbackUrl } from './textureConfig.js';
+export type { TextureConfig, TextureCategory, TextureItem, TextureChoice, TextureConfigMetadata } from './textureConfig.js';
+export { setPublicBase, getPublicBase, resolvePublicUrl } from './env.js';

package/dist/config/index.js

@@ -0,0 +1,4 @@
+// Configuration exports
+export { loadTextureConfig, getTextureOptions, getTextureChoices, getDefaultTexture, getSkyboxOptions, getDefaultSkybox, getTextureFallbackUrl } from './textureConfig.js';
+// runtime base helpers
+export { setPublicBase, getPublicBase, resolvePublicUrl } from './env.js';

package/dist/config/textureConfig.d.ts

@@ -0,0 +1,140 @@
+/** One catalogue item. */
+export interface TextureItem {
+    id: string;
+    filename?: string;
+    label?: string;
+    /** Picture of the item (a thumbnail), relative like `filename`. */
+    still?: string;
+    /** Texture to use when this one fails to load, relative like `filename`. */
+    fallback?: string;
+    tags?: string[];
+}
+/** One catalogue category (clouds, moons, skyboxes, …). */
+export interface TextureCategory {
+    category?: string;
+    basePath?: string;
+    defaultTexture?: string;
+    defaultSkybox?: string;
+    items?: TextureItem[];
+}
+/** The texture catalogue as loaded from the config URL. */
+export interface TextureConfig {
+    version?: string;
+    lastUpdated?: string;
+    baseUrl?: string;
+    /** By category name; a category the catalogue does not list is missing. */
+    textures: Partial<Record<string, TextureCategory>>;
+}
+/** What `getConfigMetadata` reports about a catalogue. */
+export interface TextureConfigMetadata {
+    version: string | undefined;
+    lastUpdated: string | undefined;
+    categories: string[];
+    totalTextures: number;
+}
+/**
+ * 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<TextureConfig>} Texture configuration object
+ */
+export declare function loadTextureConfig(configUrl?: string, useCache?: boolean): Promise<TextureConfig>;
+/**
+ * A choice record for one catalogue item.
+ *
+ * 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).
+ */
+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.
+     */
+    still: string | null;
+};
+/**
+ * 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 {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureChoice[]>} Choice records in catalogue order
+ */
+export declare function getTextureChoices(category: string, config?: TextureConfig | null): Promise<TextureChoice[]>;
+/**
+ * Get texture options for a specific category (clouds, moons, etc.)
+ * @param {string} category - Texture category (clouds, moons, skyboxes)
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<Record<string, string>>} `{ label: url }`, suitable for dropdown option lists
+ */
+export declare function getTextureOptions(category: string, config?: TextureConfig | null): Promise<Record<string, string>>;
+/**
+ * Get default texture for a category
+ * @param {string} category - Texture category
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<string|null>} Default texture path, or null when the category has no texture
+ */
+export declare function getDefaultTexture(category: string, config?: TextureConfig | null): Promise<string | null>;
+/**
+ * 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 {TextureConfig|null} config - Optional texture config override
+ * @returns {string|null} Resolved fallback texture URL or null
+ */
+export declare function getTextureFallbackUrl(category: string, textureUrl: string, config?: TextureConfig | null): string | null;
+/**
+ * Get texture by ID within a category
+ * @param {string} category - Texture category
+ * @param {string} textureId - Texture ID
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureItem|null>} Texture definition object
+ */
+export declare function getTextureById(category: string, textureId: string, config?: TextureConfig | null): Promise<TextureItem | null>;
+/**
+ * Get full URL for a texture
+ * @param {string} category - Texture category
+ * @param {string} textureId - Texture ID
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<string|null>} Full texture URL
+ */
+export declare function getTextureUrl(category: string, textureId: string, config?: TextureConfig | null): Promise<string | null>;
+/**
+ * Search textures by tags
+ * @param {string} category - Texture category
+ * @param {string[]} tags - Tags to search for
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureItem[]>} Array of matching texture definitions
+ */
+export declare function searchTexturesByTags(category: string, tags: string[], config?: TextureConfig | null): Promise<TextureItem[]>;
+/**
+ * Get skybox options formatted for GUI dropdowns
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<Record<string, string>>} `{ label: id }`
+ */
+export declare function getSkyboxOptions(config?: TextureConfig | null): Promise<Record<string, string>>;
+/**
+ * Get default skybox ID
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<string>} Default skybox ID
+ */
+export declare function getDefaultSkybox(config?: TextureConfig | null): Promise<string>;
+/**
+ * Reload configuration (force refresh)
+ * @param {string} configUrl - Override config URL
+ * @returns {Promise<TextureConfig>} Fresh configuration object
+ */
+export declare function reloadTextureConfig(configUrl?: string): Promise<TextureConfig>;
+/**
+ * Get configuration metadata
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureConfigMetadata>} Configuration metadata
+ */
+export declare function getConfigMetadata(config?: TextureConfig | null): Promise<TextureConfigMetadata>;

package/dist/config/textureConfig.js

@@ -0,0 +1,318 @@
+/**
+ * Texture Configuration Loader
+ * Loads texture definitions from remote endpoint or uses passed config
+ */
+import { resolvePublicUrl } from './env.js';
+/** The catalogue a public function was handed, or the loaded one. */
+async function resolveConfig(config) {
+    return config || (await loadTextureConfig());
+}
+function buildTextureUrl(baseUrl, categoryPath, value) {
+    if (!value)
+        return null;
+    if (/^https?:\/\//i.test(value))
+        return value;
+    if (value.startsWith('/'))
+        return resolvePublicUrl(value);
+    const prefix = `${baseUrl || ''}${categoryPath || ''}`;
+    return resolvePublicUrl(`${prefix}/${value}`);
+}
+function findTextureItem(textureConfig, category, textureUrl) {
+    if (!textureUrl || !textureConfig)
+        return null;
+    const categoryConfig = textureConfig.textures?.[category];
+    if (!categoryConfig || !categoryConfig.items)
+        return null;
+    const baseUrl = textureConfig.baseUrl || '/default';
+    const categoryPath = categoryConfig.basePath || `/${category}`;
+    for (const item of categoryConfig.items) {
+        const resolved = buildTextureUrl(baseUrl, categoryPath, item.filename || item.id);
+        if (!resolved)
+            continue;
+        if (resolved === textureUrl) {
+            return { item, baseUrl, categoryPath };
+        }
+    }
+    return null;
+}
+let cachedConfig = null;
+let configPromise = null;
+let lastConfigUrl = null;
+/**
+ * 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<TextureConfig>} Texture configuration object
+ */
+export async function loadTextureConfig(configUrl, useCache = true) {
+    if (useCache && cachedConfig) {
+        return cachedConfig;
+    }
+    if (configPromise) {
+        return configPromise;
+    }
+    if (configUrl) {
+        lastConfigUrl = configUrl;
+    }
+    const targetUrl = configUrl || lastConfigUrl;
+    configPromise = (async () => {
+        try {
+            if (!targetUrl) {
+                throw new Error('No texture config URL provided');
+            }
+            const response = await fetch(targetUrl);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            const config = (await response.json());
+            // Validate configuration structure
+            if (!config.textures || typeof config.textures !== 'object') {
+                throw new Error('Invalid configuration: missing textures object');
+            }
+            cachedConfig = config;
+            return config;
+        }
+        catch (error) {
+            console.error('[TextureConfig] Failed to load config:', error);
+            // Return minimal fallback configuration when loading fails
+            console.warn('[TextureConfig] Using hardcoded fallback config');
+            const fallback = getHardcodedFallback();
+            cachedConfig = fallback;
+            return fallback;
+        }
+        finally {
+            configPromise = null;
+        }
+    })();
+    return configPromise;
+}
+/**
+ * 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 {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureChoice[]>} Choice records in catalogue order
+ */
+export async function getTextureChoices(category, config) {
+    const textureConfig = await resolveConfig(config);
+    const categoryConfig = textureConfig.textures[category];
+    if (!categoryConfig) {
+        console.warn(`[TextureConfig] Category '${category}' not found`);
+        return [];
+    }
+    const baseUrl = textureConfig.baseUrl || '/default';
+    const categoryPath = categoryConfig.basePath || `/${category}`;
+    return (categoryConfig.items || []).flatMap((item) => {
+        const url = buildTextureUrl(baseUrl, categoryPath, item.filename || item.id);
+        if (!url)
+            return [];
+        return [{
+                id: item.id,
+                label: item.label || item.id,
+                url,
+                still: item.still ? buildTextureUrl(baseUrl, categoryPath, item.still) : null,
+            }];
+    });
+}
+/**
+ * Get texture options for a specific category (clouds, moons, etc.)
+ * @param {string} category - Texture category (clouds, moons, skyboxes)
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<Record<string, string>>} `{ label: url }`, suitable for dropdown option lists
+ */
+export async function getTextureOptions(category, config) {
+    const choices = await getTextureChoices(category, config);
+    return Object.fromEntries(choices.map(c => [c.label, c.url]));
+}
+/**
+ * Get default texture for a category
+ * @param {string} category - Texture category
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<string|null>} Default texture path, or null when the category has no texture
+ */
+export async function getDefaultTexture(category, config) {
+    const textureConfig = await resolveConfig(config);
+    const categoryConfig = textureConfig.textures[category];
+    if (!categoryConfig) {
+        return null;
+    }
+    const baseUrl = textureConfig.baseUrl || '/default';
+    const categoryPath = categoryConfig.basePath || `/${category}`;
+    const defaultFilename = categoryConfig.defaultTexture;
+    if (defaultFilename) {
+        return resolvePublicUrl(`${baseUrl}${categoryPath}/${defaultFilename}`);
+    }
+    // Fallback to first item
+    if (categoryConfig.items && categoryConfig.items.length > 0) {
+        const firstItem = categoryConfig.items[0];
+        return resolvePublicUrl(`${baseUrl}${categoryPath}/${firstItem.filename || firstItem.id}`);
+    }
+    return null;
+}
+/**
+ * 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 {TextureConfig|null} config - Optional texture config override
+ * @returns {string|null} Resolved fallback texture URL or null
+ */
+export function getTextureFallbackUrl(category, textureUrl, config = null) {
+    const textureConfig = config || cachedConfig;
+    if (!textureConfig)
+        return null;
+    const found = findTextureItem(textureConfig, category, textureUrl);
+    if (!found || !found.item?.fallback)
+        return null;
+    return buildTextureUrl(found.baseUrl, found.categoryPath, found.item.fallback);
+}
+/**
+ * Get texture by ID within a category
+ * @param {string} category - Texture category
+ * @param {string} textureId - Texture ID
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureItem|null>} Texture definition object
+ */
+export async function getTextureById(category, textureId, config) {
+    const textureConfig = await resolveConfig(config);
+    const categoryConfig = textureConfig.textures[category];
+    if (!categoryConfig || !categoryConfig.items) {
+        return null;
+    }
+    return categoryConfig.items.find(item => item.id === textureId) || null;
+}
+/**
+ * Get full URL for a texture
+ * @param {string} category - Texture category
+ * @param {string} textureId - Texture ID
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<string|null>} Full texture URL
+ */
+export async function getTextureUrl(category, textureId, config) {
+    const texture = await getTextureById(category, textureId, config);
+    if (!texture)
+        return null;
+    const textureConfig = await resolveConfig(config);
+    // `getTextureById` just found the item in this category, so it is there (unless the catalogue
+    // was reloaded in between, which throws here, as it always did).
+    const categoryConfig = textureConfig.textures[category];
+    const baseUrl = textureConfig.baseUrl || '/default';
+    const categoryPath = categoryConfig.basePath || `/${category}`;
+    return resolvePublicUrl(`${baseUrl}${categoryPath}/${texture.filename || texture.id}`);
+}
+/**
+ * Search textures by tags
+ * @param {string} category - Texture category
+ * @param {string[]} tags - Tags to search for
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureItem[]>} Array of matching texture definitions
+ */
+export async function searchTexturesByTags(category, tags, config) {
+    const textureConfig = await resolveConfig(config);
+    const categoryConfig = textureConfig.textures[category];
+    if (!categoryConfig || !categoryConfig.items) {
+        return [];
+    }
+    return categoryConfig.items.filter(item => item.tags && tags.some(tag => item.tags.includes(tag)));
+}
+/**
+ * Get skybox options formatted for GUI dropdowns
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<Record<string, string>>} `{ label: id }`
+ */
+export async function getSkyboxOptions(config) {
+    const textureConfig = await resolveConfig(config);
+    const skyboxConfig = textureConfig.textures.skyboxes;
+    if (!skyboxConfig) {
+        console.warn('[TextureConfig] Skyboxes category not found');
+        return {};
+    }
+    const options = {};
+    // Reads `items` unguarded, unlike the other readers: a skyboxes category without items throws here.
+    skyboxConfig.items.forEach(item => {
+        const label = item.label || item.id;
+        const id = item.id;
+        options[label] = id;
+    });
+    return options;
+}
+/**
+ * Get default skybox ID
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<string>} Default skybox ID
+ */
+export async function getDefaultSkybox(config) {
+    const textureConfig = await resolveConfig(config);
+    const skyboxConfig = textureConfig.textures.skyboxes;
+    if (!skyboxConfig) {
+        return '001'; // fallback
+    }
+    return skyboxConfig.defaultSkybox || '001';
+}
+/**
+ * Hardcoded fallback configuration (minimal)
+ * Used when remote config loading fails
+ */
+function getHardcodedFallback() {
+    return {
+        version: "1.0-fallback",
+        lastUpdated: new Date().toISOString(),
+        baseUrl: "/default",
+        textures: {
+            clouds: {
+                category: "atmospheric",
+                basePath: "/clouds",
+                defaultTexture: "04-clouds.ktx2",
+                items: [
+                    { id: "clouds-1", filename: "04-clouds.ktx2", label: "Clouds", tags: ["natural"] },
+                    { id: "entangled-1", filename: "06-entangled.ktx2", label: "Entangled", tags: ["quantum"] }
+                ]
+            },
+            moons: {
+                category: "celestial",
+                basePath: "/textures/moons",
+                defaultTexture: "moon-equirectangular.ktx2",
+                items: [
+                    { id: "default-moon", filename: "moon-equirectangular.ktx2", label: "Default Moon", tags: ["lunar"] }
+                ]
+            },
+            skyboxes: {
+                category: "environment",
+                basePath: "/skybox",
+                defaultSkybox: "001",
+                items: [
+                    { id: "001", label: "Deep Space", tags: ["space"] }
+                ]
+            }
+        }
+    };
+}
+/**
+ * Reload configuration (force refresh)
+ * @param {string} configUrl - Override config URL
+ * @returns {Promise<TextureConfig>} Fresh configuration object
+ */
+export async function reloadTextureConfig(configUrl) {
+    cachedConfig = null;
+    configPromise = null;
+    return loadTextureConfig(configUrl || lastConfigUrl || undefined, false);
+}
+/**
+ * Get configuration metadata
+ * @param {TextureConfig} config - Optional pre-loaded config object
+ * @returns {Promise<TextureConfigMetadata>} Configuration metadata
+ */
+export async function getConfigMetadata(config) {
+    const textureConfig = await resolveConfig(config);
+    return {
+        version: textureConfig.version,
+        lastUpdated: textureConfig.lastUpdated,
+        categories: Object.keys(textureConfig.textures),
+        totalTextures: Object.values(textureConfig.textures).reduce(
+        // Only listed categories are values; a missing one is a key that is not there.
+        (sum, cat) => {
+            const items = cat.items;
+            return sum + (items ? items.length : 0);
+        }, 0)
+    };
+}

package/dist/core/index.d.ts

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

package/dist/core/index.js

@@ -0,0 +1,3 @@
+// Core rendering exports
+export { ensureDefaultLights, updateDefaultLights, setHemisphereEnabled } from './lights.js';
+export { getLightFresnel } from './lightFresnel.js';

package/dist/core/lightFresnel.d.ts

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

package/dist/core/lightFresnel.js

@@ -0,0 +1,63 @@
+import * as THREE from "three";
+function getLightFresnel({ rimHex = 0x0088ff, facingHex = 0x000000 } = {}) {
+    const uniforms = {
+        color1: { value: new THREE.Color(rimHex) },
+        color2: { value: new THREE.Color(facingHex) },
+        fresnelBias: { value: 0.1 },
+        fresnelScale: { value: 1.0 },
+        fresnelPower: { value: 4.0 },
+    };
+    const vs = `
+  uniform float fresnelBias;
+  uniform float fresnelScale;
+  uniform float fresnelPower;
+  
+  varying float vReflectionFactor;
+  
+  void main() {
+    vec4 mvPosition = modelViewMatrix * vec4( position, 1.0 );
+    vec4 worldPosition = modelMatrix * vec4( position, 1.0 );
+  
+    // Transform normal to world space
+    vec3 worldNormal = normalize( mat3( modelMatrix[0].xyz, modelMatrix[1].xyz, modelMatrix[2].xyz ) * normal );
+  
+    // Proper view direction (from surface point towards camera)
+    vec3 viewDir = normalize( cameraPosition - worldPosition.xyz );
+
+    // Classic rim: stronger at grazing angles
+    float ndotv = max( dot( worldNormal, viewDir ), 0.0 );
+    vReflectionFactor = fresnelBias + fresnelScale * pow( 1.0 - ndotv, fresnelPower );
+  
+    gl_Position = projectionMatrix * mvPosition;
+  }
+  `;
+    const fs = `
+  uniform vec3 color1;
+  uniform vec3 color2;
+  
+  varying float vReflectionFactor;
+  
+  void main() {
+    float f = clamp( vReflectionFactor, 0.0, 1.0 );
+    gl_FragColor = vec4(mix(color2, color1, vec3(f)), f);
+  }
+  `;
+    const lightFresnel = new THREE.ShaderMaterial({
+        uniforms: uniforms,
+        vertexShader: vs,
+        fragmentShader: fs,
+        transparent: true,
+        blending: THREE.CustomBlending,
+        blendSrc: THREE.OneFactor,
+        blendDst: THREE.OneFactor,
+        blendEquation: THREE.AddEquation,
+        depthWrite: false,
+        depthTest: true,
+        depthFunc: THREE.LessDepth,
+        side: THREE.FrontSide,
+        toneMapped: false,
+        // wireframe: true,
+    });
+    return lightFresnel;
+}
+export { getLightFresnel };

package/dist/core/lights.d.ts

@@ -0,0 +1,48 @@
+import * as THREE from 'three';
+/**
+ * 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.
+ */
+export declare function ensureDefaultLights(scene: THREE.Scene): {
+    hemi: THREE.HemisphereLight;
+    ambient: 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.
+ */
+export declare function updateDefaultLights(scene: THREE.Scene, { ambientIntensity, diffuseIntensity, lightColor, lightDirection, hemisphere }?: {
+    /** ambient light intensity (clamped at 0) */
+    ambientIntensity?: number;
+    /** hemisphere light intensity (clamped at 0) */
+    diffuseIntensity?: number;
+    /** hemisphere light colour */
+    lightColor?: THREE.Color | number | string;
+    /** hemisphere light direction */
+    lightDirection?: {
+        x: number;
+        y?: number;
+        z?: number;
+    };
+    /** switch the hemisphere light on or off */
+    hemisphere?: boolean;
+}): 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.
+ */
+export declare function setHemisphereEnabled(scene: THREE.Scene, on: boolean): void;
+export declare function addDefaultLights(scene: THREE.Scene): {
+    hemi: THREE.HemisphereLight;
+    ambient: THREE.AmbientLight;
+};