entangled-worlds-orbiters-shared 2.10.0 → 2.12.0

package/README.md

@@ -71,6 +71,16 @@ import * as EntangledWorlds from 'entangled-worlds-orbiters-shared';
 ### Configuration
 - `textureConfig` - Texture configuration system
 
+### Star (`entangled-worlds-orbiters-shared/star`)
+- `createStar`, `StarManager` - The host star of a world: single, binary or trinary, emissive, shader-only glow (two draw calls for any multiplicity; lights nothing)
+- `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
+- 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`)
+
 ### Capabilities (`entangled-worlds-orbiters-shared/capabilities`)
 - `createCapabilityRegistry` - Validated, named registry of studio actions (query / mutation / generative)
 - `validate`, `assertValid` - JSON-Schema-subset validator used for capability inputs

package/dist/notes/index.d.ts

@@ -0,0 +1,72 @@
+export type NoteEventType = 'on' | 'off';
+export interface NoteEvent {
+    type: NoteEventType;
+    /** Unique per sounding note; an `off` carries the id of the `on` it ends. */
+    id: string;
+    /** MIDI note number, 0 … 127 (integers today; the field allows fractions later). */
+    pitch: number;
+    /** 0 … 1. An `off` may carry a release velocity; nothing reads it yet. */
+    velocity: number;
+    /** Audio-context seconds when it should sound; at or before now means now. */
+    time: number;
+    /** Who sent it: a device, the keyboard, a MIDI effect's slot, a room client. */
+    source: string;
+}
+export declare const NOTE_PITCH_MIN = 0;
+export declare const NOTE_PITCH_MAX = 127;
+/** Whether `value` is a well-formed note event (the shape a room peer or an agent must send). */
+export declare function isNoteEvent(value: unknown): value is NoteEvent;
+/** What a channel message means to a note player. Channels are 0 … 15, as on the wire. */
+export type MidiNoteMessage = {
+    kind: 'on';
+    channel: number;
+    pitch: number;
+    velocity: number;
+} | {
+    kind: 'off';
+    channel: number;
+    pitch: number;
+    velocity: number;
+}
+/** Pitch bend, −1 … 1 (0 is the centre). */
+ | {
+    kind: 'bend';
+    channel: number;
+    value: number;
+}
+/** A control change, its value 0 … 1. */
+ | {
+    kind: 'cc';
+    channel: number;
+    controller: number;
+    value: number;
+};
+/** The mod wheel. */
+export declare const MIDI_CC_MOD_WHEEL = 1;
+/**
+ * Decode a channel message's bytes. A note-on with velocity 0 is a note-off (running status sends
+ * them that way). Anything a note player has no use for (aftertouch, program change, system) is null.
+ */
+export declare function decodeMidiMessage(status: number, data1?: number, data2?: number): MidiNoteMessage | null;
+/**
+ * A MIDI note-off names only a channel and a pitch. This gives each held key its note id, so the
+ * off pairs with its on by id like every other source.
+ *
+ * - `on` mints a fresh id. If that key was already held (a device that sends two ons without an off)
+ *   the old note's id comes back as `replaced`, so the caller can end it first: nothing sticks.
+ * - `off` returns the id the key was playing, or null when it was never down (an off arriving after
+ *   a panic, or from before the page listened).
+ * - `releaseDevice` hands back every id a device holds: it went away, and they all end.
+ */
+export interface MidiNoteIds {
+    on(device: string, channel: number, pitch: number): {
+        id: string;
+        replaced: string | null;
+    };
+    off(device: string, channel: number, pitch: number): string | null;
+    releaseDevice(device: string): string[];
+    releaseAll(): string[];
+    /** How many keys are down, across devices. */
+    readonly size: number;
+}
+export declare function createMidiNoteIds(prefix?: string): MidiNoteIds;

package/dist/notes/index.js

@@ -0,0 +1,94 @@
+// Notes as events, shared by every note source (MIDI in, the on-screen keyboard, a capability call, a
+// MIDI effect, a room peer) and everything that routes or sounds them.
+//
+// On and off are separate events with no duration: a live key has no known length when it goes
+// down. They pair by `id`, never by pitch, since two sources can hold the same pitch at once and a
+// chord or an echo plays the same pitch more than once. Pairing by pitch alone gives stuck notes.
+//
+// App-agnostic: nothing here knows about Orbiters, dimensions or the audio graph.
+export const NOTE_PITCH_MIN = 0;
+export const NOTE_PITCH_MAX = 127;
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+/** Whether `value` is a well-formed note event (the shape a room peer or an agent must send). */
+export function isNoteEvent(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const event = value;
+    return ((event.type === 'on' || event.type === 'off') &&
+        typeof event.id === 'string' &&
+        event.id.length > 0 &&
+        isFiniteNumber(event.pitch) &&
+        event.pitch >= NOTE_PITCH_MIN &&
+        event.pitch <= NOTE_PITCH_MAX &&
+        isFiniteNumber(event.velocity) &&
+        event.velocity >= 0 &&
+        event.velocity <= 1 &&
+        isFiniteNumber(event.time) &&
+        typeof event.source === 'string');
+}
+/** The mod wheel. */
+export const MIDI_CC_MOD_WHEEL = 1;
+const BEND_CENTRE = 8192;
+/**
+ * Decode a channel message's bytes. A note-on with velocity 0 is a note-off (running status sends
+ * them that way). Anything a note player has no use for (aftertouch, program change, system) is null.
+ */
+export function decodeMidiMessage(status, data1 = 0, data2 = 0) {
+    const channel = status & 0x0f;
+    switch (status & 0xf0) {
+        case 0x90:
+            return data2 > 0
+                ? { kind: 'on', channel, pitch: data1 & 0x7f, velocity: (data2 & 0x7f) / 127 }
+                : { kind: 'off', channel, pitch: data1 & 0x7f, velocity: 0 };
+        case 0x80:
+            return { kind: 'off', channel, pitch: data1 & 0x7f, velocity: (data2 & 0x7f) / 127 };
+        case 0xe0: {
+            // 14 bits, least significant first. The top is 8191 above the centre and the bottom 8192 below
+            // it, so each side is scaled on its own and both ends reach ±1.
+            const raw = ((data2 & 0x7f) << 7) | (data1 & 0x7f);
+            const offset = raw - BEND_CENTRE;
+            return { kind: 'bend', channel, value: offset >= 0 ? offset / (BEND_CENTRE - 1) : offset / BEND_CENTRE };
+        }
+        case 0xb0:
+            return { kind: 'cc', channel, controller: data1 & 0x7f, value: (data2 & 0x7f) / 127 };
+        default:
+            return null;
+    }
+}
+export function createMidiNoteIds(prefix = 'midi') {
+    const held = new Map();
+    let next = 0;
+    const keyOf = (device, channel, pitch) => `${device}\u0000${channel}\u0000${pitch}`;
+    const deviceOf = (key) => key.slice(0, key.indexOf('\u0000'));
+    const take = (predicate) => {
+        const ids = [];
+        for (const [key, id] of held) {
+            if (!predicate(key))
+                continue;
+            ids.push(id);
+            held.delete(key);
+        }
+        return ids;
+    };
+    return {
+        on(device, channel, pitch) {
+            const key = keyOf(device, channel, pitch);
+            const replaced = held.get(key) ?? null;
+            next += 1;
+            const id = `${prefix}:${next}`;
+            held.set(key, id);
+            return { id, replaced };
+        },
+        off(device, channel, pitch) {
+            const key = keyOf(device, channel, pitch);
+            const id = held.get(key) ?? null;
+            held.delete(key);
+            return id;
+        },
+        releaseDevice: (device) => take((key) => deviceOf(key) === device),
+        releaseAll: () => take(() => true),
+        get size() {
+            return held.size;
+        },
+    };
+}

package/dist/star/blackbody.d.ts

@@ -0,0 +1,12 @@
+export interface RGB {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * sRGB colour (channels 0..1, brightest channel = 1) of a blackbody at `temperatureK`.
+ * Clamped to 1000 K … 40000 K, the range the fit is valid for.
+ */
+export declare function blackbodyColor(temperatureK: number): RGB;
+/** Linear-light luminance-ish weight of an sRGB colour — handy for keeping companions balanced. */
+export declare function relativeLuminance({ r, g, b }: RGB): number;

package/dist/star/blackbody.js

@@ -0,0 +1,38 @@
+// Blackbody temperature → display colour.
+//
+// A fitted approximation of the Planck locus in sRGB (Tanner Helland's curve fit of Mitchell
+// Charity's blackbody table), normalised so the brightest channel is 1. It is a *chromaticity*:
+// brightness is the renderer's job. Pure and cheap — called on param changes, never per frame.
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/**
+ * sRGB colour (channels 0..1, brightest channel = 1) of a blackbody at `temperatureK`.
+ * Clamped to 1000 K … 40000 K, the range the fit is valid for.
+ */
+export function blackbodyColor(temperatureK) {
+    const tk = Number.isFinite(temperatureK) ? temperatureK : 5778;
+    const t = Math.min(40000, Math.max(1000, tk)) / 100;
+    let r;
+    let g;
+    let b;
+    if (t <= 66) {
+        r = 255;
+        g = 99.4708025861 * Math.log(t) - 161.1195681661;
+        b = t <= 19 ? 0 : 138.5177312231 * Math.log(t - 10) - 305.0447927307;
+    }
+    else {
+        r = 329.698727446 * Math.pow(t - 60, -0.1332047592);
+        g = 288.1221695283 * Math.pow(t - 60, -0.0755148492);
+        b = 255;
+    }
+    r = clamp01(r / 255);
+    g = clamp01(g / 255);
+    b = clamp01(b / 255);
+    const m = Math.max(r, g, b) || 1;
+    return { r: r / m, g: g / m, b: b / m };
+}
+/** Linear-light luminance-ish weight of an sRGB colour — handy for keeping companions balanced. */
+export function relativeLuminance({ r, g, b }) {
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}

package/dist/star/bounds.d.ts

@@ -0,0 +1,39 @@
+/** Largest moon radius (0.1 geometry × up to 0.22 scale). */
+export declare const DEFAULT_MOON_RADIUS = 0.022;
+/** How far a moon's orbit radius may stray from its nominal one, either way. */
+export declare const MOON_ORBIT_HALF_SCATTER = 0.11;
+/** Clear-space factor on (scene outer radius + system extent). */
+export declare const STAR_DISTANCE_MARGIN = 2;
+/** Largest angular radius the primary's disc may span seen from the planet, degrees. */
+export declare const MAX_STAR_ANGULAR_RADIUS_DEG = 10;
+export interface SceneSizes {
+    planetRadius: number;
+    /** Moon orbit radius (0 / omitted = no moons). */
+    moonOrbitRadius?: number;
+    moonRadius?: number;
+    /** Planet glow / cloud shell scale relative to the planet radius (e.g. 1.18). */
+    cloudOrGlowScale?: number;
+}
+/** Radius of the sphere around the planet that holds the planet, its glow and its moons. */
+export declare function sceneOuterRadius(s: SceneSizes): number;
+export interface MinStarDistanceInput extends Partial<SceneSizes> {
+    /** Or pass the outer radius directly (wins over the sizes above). */
+    outerRadius?: number;
+    /** The star system's full extent from its barycentre (every disc, orbit and corona). */
+    systemExtent?: number;
+    /** The primary's radius, for the angular-size cap. */
+    primaryRadius?: number;
+    margin?: number;
+}
+/**
+ * Minimum barycentre distance from the planet: `margin × (outer + systemExtent)`, and far enough
+ * that the primary spans at most `MAX_STAR_ANGULAR_RADIUS_DEG`. Pure.
+ */
+export declare function minStarDistance(input: MinStarDistanceInput): number;
+/** Sky margin: the system keeps this fraction of the sky radius clear of the skybox. */
+export declare const SKY_MARGIN_FRACTION = 0.02;
+/**
+ * Farthest barycentre distance that keeps a system of `systemExtent` inside a sky of `skyRadius`
+ * (with `SKY_MARGIN_FRACTION` of clearance). Never negative. Pure.
+ */
+export declare function maxStarDistance(skyRadius: number, systemExtent: number): number;

package/dist/star/bounds.js

@@ -0,0 +1,47 @@
+// Scene bounds (pure): how far the star system must sit so it never touches the planet, its glow
+// or its moons, and never looms over the planet. Hosts pass their scene sizes; hosts that pass
+// nothing keep the author's distance as-is.
+// The shared moons' sizes (`./moons` MOON_MAX_RADIUS and MOON_ORBIT_SCATTER / 2). Copied, not
+// imported: this subpath is built to dist/ and the moons ship as source; a test pins them together.
+/** Largest moon radius (0.1 geometry × up to 0.22 scale). */
+export const DEFAULT_MOON_RADIUS = 0.022;
+/** How far a moon's orbit radius may stray from its nominal one, either way. */
+export const MOON_ORBIT_HALF_SCATTER = 0.11;
+/** Clear-space factor on (scene outer radius + system extent). */
+export const STAR_DISTANCE_MARGIN = 2;
+/** Largest angular radius the primary's disc may span seen from the planet, degrees. */
+export const MAX_STAR_ANGULAR_RADIUS_DEG = 10;
+function pos(v, fallback) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : fallback;
+}
+/** Radius of the sphere around the planet that holds the planet, its glow and its moons. */
+export function sceneOuterRadius(s) {
+    const planet = pos(s.planetRadius, 0) * Math.max(1, pos(s.cloudOrGlowScale, 1));
+    const orbit = pos(s.moonOrbitRadius, 0);
+    const moons = orbit > 0 ? orbit + MOON_ORBIT_HALF_SCATTER + pos(s.moonRadius, DEFAULT_MOON_RADIUS) : 0;
+    return Math.max(planet, moons);
+}
+/**
+ * Minimum barycentre distance from the planet: `margin × (outer + systemExtent)`, and far enough
+ * that the primary spans at most `MAX_STAR_ANGULAR_RADIUS_DEG`. Pure.
+ */
+export function minStarDistance(input) {
+    const outer = typeof input.outerRadius === 'number' && Number.isFinite(input.outerRadius)
+        ? Math.max(0, input.outerRadius)
+        : sceneOuterRadius({ planetRadius: pos(input.planetRadius, 0), ...input });
+    const margin = typeof input.margin === 'number' && input.margin > 0 ? input.margin : STAR_DISTANCE_MARGIN;
+    const clear = margin * (outer + pos(input.systemExtent, 0));
+    const angular = pos(input.primaryRadius, 0) / Math.tan((MAX_STAR_ANGULAR_RADIUS_DEG * Math.PI) / 180);
+    return Math.max(clear, angular);
+}
+/** Sky margin: the system keeps this fraction of the sky radius clear of the skybox. */
+export const SKY_MARGIN_FRACTION = 0.02;
+/**
+ * Farthest barycentre distance that keeps a system of `systemExtent` inside a sky of `skyRadius`
+ * (with `SKY_MARGIN_FRACTION` of clearance). Never negative. Pure.
+ */
+export function maxStarDistance(skyRadius, systemExtent) {
+    const sky = typeof skyRadius === 'number' && Number.isFinite(skyRadius) ? Math.max(0, skyRadius) : Infinity;
+    const ext = typeof systemExtent === 'number' && Number.isFinite(systemExtent) ? Math.max(0, systemExtent) : 0;
+    return Math.max(0, sky * (1 - SKY_MARGIN_FRACTION) - ext);
+}

package/dist/star/framing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Camera distance (from the sphere's centre) at which a sphere of `radius` fits inside both the
+ * vertical and the horizontal field of view, with `margin` (1.15 = 15% breathing room).
+ */
+export declare function framingDistance(radius: number, fovDeg: number, aspect: number, margin?: number): number;
+export interface StarPlacementInput {
+    /** Vertical field of view of the host camera, degrees. */
+    fovDeg: number;
+    /** Width / height of the viewport. */
+    aspect: number;
+    /** Distance of the host camera from the planet (the scene origin), on +Z looking at it. */
+    cameraDistance: number;
+    planetRadius: number;
+    /** Primary radius, scene units (default: `DEFAULT_STAR_PARAMS.radius`). */
+    starRadius?: number;
+    /** Star system distance from the origin (default: `DEFAULT_STAR_PARAMS.distance`). */
+    distance?: number;
+}
+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. */
+    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.
+ */
+export declare function defaultStarPlacement(input: StarPlacementInput): StarPlacement;

package/dist/star/framing.js

@@ -0,0 +1,68 @@
+// 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';
+const DEG = Math.PI / 180;
+/**
+ * Camera distance (from the sphere's centre) at which a sphere of `radius` fits inside both the
+ * vertical and the horizontal field of view, with `margin` (1.15 = 15% breathing room).
+ */
+export function framingDistance(radius, fovDeg, aspect, margin = 1.15) {
+    const r = Math.max(0, Number.isFinite(radius) ? radius : 0) * (Number.isFinite(margin) && margin > 0 ? margin : 1.15);
+    const halfV = (Math.min(179, Math.max(1, Number.isFinite(fovDeg) ? fovDeg : 45)) * DEG) / 2;
+    const a = Number.isFinite(aspect) && aspect > 0 ? aspect : 1;
+    const halfH = Math.atan(Math.tan(halfV) * a);
+    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.
+ */
+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,
+    };
+}

package/dist/star/index.d.ts

@@ -0,0 +1,21 @@
+export { createStar } from './starBody.js';
+export type { StarBody, StarFocus, CreateStarOptions } from './starBody.js';
+export { StarManager } from './starManager.js';
+export type { StarManagerOptions, StarSceneBounds } from './starManager.js';
+export { STAR_QUALITY, normalizeStarQuality } from './quality.js';
+export type { StarQuality, StarQualityProfile } from './quality.js';
+export { DEFAULT_STAR_PARAMS, STAR_PARAM_RANGES, normalizeStarParams, spectralClass, } from './params.js';
+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 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';
+export type { StellarData, StellarBinary, LuminosityClass } 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 type { StarLighting, LegacyLighting, LegacyLightingResult } from './lighting.js';
+export { minStarDistance, maxStarDistance, SKY_MARGIN_FRACTION, sceneOuterRadius, STAR_DISTANCE_MARGIN, MAX_STAR_ANGULAR_RADIUS_DEG, } from './bounds.js';
+export type { SceneSizes, MinStarDistanceInput } from './bounds.js';
+export { separateDirection, starsReach } from './layout.js';

package/dist/star/index.js

@@ -0,0 +1,15 @@
+// ./star — the host star of a world: an emissive, shader-glowing body (single, binary or trinary,
+// plus an optional distant companion) in two draw calls, and — through StarManager — the scene's key
+// light and camera-side fill. Pure param/layout/colour helpers are exported too so hosts can validate
+// stored params and preview colours without WebGL.
+export { createStar } from './starBody.js';
+export { StarManager } from './starManager.js';
+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 { 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';
+export { separateDirection, starsReach } from './layout.js';

package/dist/star/layout.d.ts

@@ -0,0 +1,121 @@
+import { type RGB } from './blackbody.js';
+import { type StarParams } from './params.js';
+export type StarRole = 'primary' | 'companion' | 'wide' | 'distant';
+export interface StarOrbit {
+    /** Distance from the barycentre it orbits, scene units. */
+    radius: number;
+    /** Phase at t = 0, radians. */
+    phase: number;
+    /** Radians per second (0 for a single star). */
+    angularSpeed: number;
+}
+export interface LaidOutStar {
+    role: StarRole;
+    temperatureK: number;
+    color: RGB;
+    radius: number;
+    /** 0..1 corona intensity. */
+    luminosity: number;
+    /** 0..1 surface activity. */
+    activity: number;
+    /** Corona reach in radii (the billboard's half-size). */
+    coronaExtent: number;
+    /** Linear limb-darkening coefficient (cooler stars darken more towards the limb). */
+    limbDarkening: number;
+    /** 0..1 per-star noise offset so two stars never boil in sync. */
+    noiseSeed: number;
+    /** Photosphere brightness gain (1 for the system's stars; the distant companion is dimmer). */
+    gain: number;
+    orbit: StarOrbit;
+}
+export interface StarLayout {
+    stars: LaidOutStar[];
+    /** Tilt of the orbital plane from the local XZ plane, radians. */
+    inclination: number;
+    /** Rotation of the orbital plane about local Y, radians. */
+    node: number;
+    /** For trinaries: the close pair's barycentre orbit around the system barycentre. */
+    pairOrbit: StarOrbit | null;
+    /**
+     * The distant companion (S-type pair), or null: a lone star elsewhere in the sky at the system's
+     * distance, in the direction below (degrees). Not part of `stars`, orbits or the focus sphere.
+     */
+    distant: {
+        star: LaidOutStar;
+        azimuth: number;
+        elevation: number;
+    } | null;
+    /** Radius of a sphere (around the local origin) that contains every star and its corona. */
+    boundingRadius: number;
+    /**
+     * Camera-focus radius: a sphere around the barycentre enclosing every star's orbit + disc and the
+     * bright inner glow (`FOCUS_GLOW_RADII` radii), not the faint outer corona — frames the system.
+     */
+    focusRadius: number;
+}
+/** How much of the glow (in star radii) the focus sphere keeps around each disc. */
+export declare const FOCUS_GLOW_RADII = 1.5;
+/** Focus radius of a layout (pure): max over stars of (distance from barycentre + glow radius). */
+export declare function starFocusRadius(layout: Pick<StarLayout, 'stars' | 'pairOrbit'>): number;
+/** 32-bit string hash (the same one `generateMoons` uses). */
+export declare function hashSeed(seed: number | string): number;
+/** Linear congruential generator in [0, 1) (Numerical Recipes constants, as in the moons). */
+export declare function createLcg(seed: number | string): () => number;
+/** Linear limb-darkening coefficient vs temperature: ~0.85 for M dwarfs, ~0.6 Sun, ~0.3 O stars. */
+export declare function limbDarkeningFor(temperatureK: number): number;
+/** Corona half-size in radii for a luminosity 0..1. */
+export declare function coronaExtentFor(luminosity: number): number;
+/**
+ * Debris-disc orientation (pure, from the seed): the ring's plane is near-horizontal, tilted
+ * `tilt` radians towards a viewer on +Z (so it reads as a thin ellipse, ~0.2–0.45 axis ratio) and
+ * rolled `roll` radians about the view axis. Independent of the orbital plane so a face-on-ish
+ * binary orbit never turns the disc into a flat halo.
+ */
+export declare function discOrientation(seed: number | string): {
+    tilt: number;
+    roll: number;
+};
+/**
+ * Keep the distant companion's direction at least `minAngle` (radians) away from the system's,
+ * rotating it away along the great circle (or straight up when they coincide). Pure.
+ */
+export declare function separateDirection(sys: {
+    azimuth: number;
+    elevation: number;
+}, far: {
+    azimuth: number;
+    elevation: number;
+}, minAngle: number): {
+    azimuth: number;
+    elevation: number;
+};
+/** Farthest any system star's disc reaches from the barycentre (orbits + radius; no glow). */
+export declare function starsReach(layout: Pick<StarLayout, 'stars' | 'pairOrbit'>): number;
+/**
+ * Lay out the system for (possibly raw) params. Companions are always cooler and smaller than the
+ * primary and derived from it + the seed; the trinary's third is a small, cool, wide companion
+ * (an Alpha Centauri-like hierarchy). Deterministic: same params → same layout.
+ */
+export declare function starLayout(rawParams: Partial<StarParams> | unknown): StarLayout;
+/**
+ * Local positions (relative to the system barycentre) of every star at `timeSec`, written as
+ * xyz triplets into `out` (allocated when omitted). Orbits are circular, in a plane tilted by
+ * `inclination` about X and rotated by `node` about Y. Allocation-free when `out` is passed.
+ */
+export declare function starPositions(layout: StarLayout, timeSec: number, out?: Float32Array | number[]): Float32Array | number[];
+/** World-space position of the system barycentre for a distance/azimuth/elevation placement. */
+export declare function starSystemPosition(p: Pick<StarParams, 'distance' | 'azimuth' | 'elevation'>): [number, number, number];
+/** Length of one flare slot; at most one flare starts per slot. */
+export declare const FLARE_SLOT_SEC = 6;
+export interface FlareState {
+    /** 0..1 flare brightness right now. */
+    intensity: number;
+    /** Position angle of the flare on the limb, radians. */
+    angle: number;
+}
+/**
+ * Deterministic flare envelope for a star at `timeSec`: fast rise, exponential decay. The chance a
+ * slot holds a flare grows with `activity` (0 → never). Same (seed, time) → same answer on every
+ * machine, so all views of one world flare together.
+ */
+export declare function flareAt(noiseSeed: number, activity: number, timeSec: number, out?: FlareState): FlareState;