entangled-worlds-orbiters-shared 4.2.0 → 5.1.0

package/dist/shortcuts/source.d.ts

@@ -0,0 +1,62 @@
+import { type ShortcutCatalogue } from './catalogue.js';
+import { type ShortcutAction, type ShortcutOverrides } from './match.js';
+/** The overrides in a stored value, or `null` when it is not a list of `{ id, keys }`. */
+export declare function parseOverrides(value: unknown): ShortcutOverrides | null;
+/**
+ * How the app reads the signed-in person's settings: `null` when no one is signed in (the
+ * default keys); `undefined` when the read failed (the overrides in force are kept: a blip must not
+ * swap someone's keys for the defaults).
+ */
+export type ReadAccountSettings = (options: {
+    fresh: boolean;
+}) => Promise<{
+    shortcuts?: unknown;
+} | null | undefined>;
+/**
+ * How the app reads the catalogue (`{ version, sections }`); `undefined` or a throw when the read
+ * failed (the catalogue in force is kept). There is no copy in the app: until the first read
+ * answers, no key does anything.
+ */
+export type ReadShortcutCatalogue = (options: {
+    fresh: boolean;
+}) => Promise<unknown>;
+export interface ShortcutSource {
+    /** The catalogue in force (empty until it is read). */
+    catalogue(): ShortcutCatalogue;
+    /** The actions of these sections, the first named winning a shared key; the same list until the catalogue changes. */
+    actions(...sectionIds: string[]): readonly ShortcutAction[];
+    /** The person's overrides in force. */
+    overrides(): ShortcutOverrides;
+    /** A list of actions with their keys now (kept until the catalogue or the overrides change). */
+    bindings(actions: readonly ShortcutAction[]): Map<string, readonly string[]>;
+    /** Called whenever the catalogue or the overrides change; returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** Read both again (`fresh`: past the app's own cached read). The newest read of each wins, whatever order they end in. */
+    refresh(options?: {
+        fresh?: boolean;
+    }): Promise<void>;
+    /** Read now, and again whenever the page comes back to the front; once per source. */
+    bind(): void;
+    /** For tests: set the overrides directly. */
+    setOverrides(overrides: ShortcutOverrides): void;
+    /** For tests: set the catalogue directly. */
+    setCatalogue(catalogue: ShortcutCatalogue): void;
+}
+/**
+ * Where a device keeps the last catalogue it read: offline (the desktop app with no connection) the
+ * keys are the ones it last had, and on every start they answer before the read comes back. A copy of
+ * what was served, never a list of its own.
+ */
+export interface ShortcutCatalogueStore {
+    load(): unknown;
+    save(value: unknown): void;
+}
+export declare const CATALOGUE_STORAGE_KEY = "ps.shortcutCatalogue";
+/** This browser's localStorage, when there is one and it may be used; otherwise nothing is kept. */
+export declare function localShortcutCatalogueStore(): ShortcutCatalogueStore | null;
+export declare function createShortcutSource({ readCatalogue, readAccount, store, }: {
+    readCatalogue: ReadShortcutCatalogue;
+    readAccount: ReadAccountSettings;
+    /** Where the last catalogue read is kept (this browser's localStorage by default; `null`: nowhere). */
+    store?: ShortcutCatalogueStore | null;
+}): ShortcutSource;

package/dist/shortcuts/source.js

@@ -0,0 +1,139 @@
+// Where an app's keys come from, read the same way by every app: the catalogue (every action and its
+// default keys, from the backend) and the person's own changes (their account's settings; someone
+// signed out has the defaults). Both are read at start and again whenever the page comes back to the
+// front, so a key changed in the catalogue or on the settings page applies on return, without a reload.
+//
+// Framework-free: the app hands in how it reads each (its own API client) and gets the catalogue, the
+// overrides, and each list of actions' resolved keys back, kept until either changes.
+import { EMPTY_CATALOGUE, parseCatalogue, sectionActions } from './catalogue.js';
+import { resolveBindings } from './match.js';
+/** The overrides in a stored value, or `null` when it is not a list of `{ id, keys }`. */
+export function parseOverrides(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.filter((entry) => !!entry && typeof entry.id === 'string' && Array.isArray(entry.keys) && entry.keys.every((k) => typeof k === 'string'));
+}
+export const CATALOGUE_STORAGE_KEY = 'ps.shortcutCatalogue';
+/** This browser's localStorage, when there is one and it may be used; otherwise nothing is kept. */
+export function localShortcutCatalogueStore() {
+    const storage = globalThis.localStorage;
+    if (!storage)
+        return null;
+    return {
+        load() {
+            try {
+                const raw = storage.getItem(CATALOGUE_STORAGE_KEY);
+                return raw ? JSON.parse(raw) : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        save(value) {
+            try {
+                storage.setItem(CATALOGUE_STORAGE_KEY, JSON.stringify(value));
+            }
+            catch {
+                // Full or refused (a private window): the next start reads the backend first, as without a store.
+            }
+        },
+    };
+}
+/** Coming back to the front twice in a row (visible, then focus) reads once. */
+const REFRESH_GAP_MS = 2000;
+/** Keeps the answer of the newest read that answered: an older one ending later says nothing new. */
+function newestRead(read, apply) {
+    let latest = 0;
+    let applied = 0;
+    return async (fresh) => {
+        const ticket = ++latest;
+        let value;
+        try {
+            value = await read(fresh);
+        }
+        catch {
+            value = undefined;
+        }
+        if (value === undefined || ticket < applied)
+            return;
+        applied = ticket;
+        apply(value);
+    };
+}
+export function createShortcutSource({ readCatalogue, readAccount, store = localShortcutCatalogueStore(), }) {
+    let catalogue = (store && parseCatalogue(store.load())) || EMPTY_CATALOGUE;
+    let overrides = [];
+    let resolved = new WeakMap();
+    let lastRefreshAt = -Infinity;
+    let bound = false;
+    const listeners = new Set();
+    const changed = () => {
+        resolved = new WeakMap();
+        listeners.forEach((listener) => listener());
+    };
+    const applyOverrides = (next) => {
+        if (JSON.stringify(next) === JSON.stringify(overrides))
+            return;
+        overrides = next;
+        changed();
+    };
+    const applyCatalogue = (next) => {
+        if (next === catalogue || (next.version && next.version === catalogue.version && next.sections.length === catalogue.sections.length))
+            return;
+        catalogue = next;
+        changed();
+    };
+    const refreshCatalogue = newestRead(async (fresh) => {
+        const value = await readCatalogue({ fresh });
+        const read = value === undefined ? null : parseCatalogue(value);
+        if (!read)
+            return undefined;
+        if (read.version !== catalogue.version)
+            store?.save(value);
+        return read;
+    }, applyCatalogue);
+    const refreshAccount = newestRead(async (fresh) => {
+        const settings = await readAccount({ fresh });
+        return settings === undefined ? undefined : settings === null ? [] : (parseOverrides(settings.shortcuts) ?? []);
+    }, applyOverrides);
+    const refresh = async ({ fresh = false } = {}) => {
+        lastRefreshAt = Date.now();
+        await Promise.all([refreshCatalogue(fresh), refreshAccount(fresh)]);
+    };
+    return {
+        catalogue: () => catalogue,
+        actions: (...sectionIds) => sectionActions(catalogue, ...sectionIds),
+        overrides: () => overrides,
+        bindings(actions) {
+            let map = resolved.get(actions);
+            if (!map) {
+                map = resolveBindings(actions, overrides);
+                resolved.set(actions, map);
+            }
+            return map;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        refresh,
+        bind() {
+            const win = globalThis;
+            if (bound || typeof win.addEventListener !== 'function' || !win.document?.addEventListener)
+                return;
+            bound = true;
+            void refresh();
+            const onFront = () => {
+                if (win.document?.visibilityState !== 'visible' || Date.now() - lastRefreshAt < REFRESH_GAP_MS)
+                    return;
+                void refresh({ fresh: true });
+            };
+            win.document.addEventListener('visibilitychange', onFront);
+            win.addEventListener('focus', onFront);
+        },
+        setOverrides: applyOverrides,
+        setCatalogue: applyCatalogue,
+    };
+}

package/dist/sky/geometry.d.ts

@@ -0,0 +1,31 @@
+import * as THREE from 'three';
+import type { WorldSky } from './worldSkyFile.js';
+/** The band's frame: `basis` maps band space (x toward the core, y the band's pole) to the scene. */
+export interface BandFrame {
+    basis: THREE.Matrix4;
+    core: THREE.Vector3;
+}
+/** An equatorial direction in the scene frame (y = celestial north). */
+export declare function equatorial(raDeg: number, decDeg: number, out?: THREE.Vector3): THREE.Vector3;
+/** A seeded band, tilted `tiltDeg` from the equator, its core at a seeded longitude. */
+export declare function seededBandFrame(seed: number, tiltDeg: number): BandFrame;
+/**
+ * The Milky Way: the galactic plane (J2000 north pole and centre). From every catalogued host it
+ * is the same plane to well under a degree, so it holds for every world sky.
+ */
+export declare function galacticBandFrame(): BandFrame;
+/**
+ * The star buffer, exactly `count` stars (the device's star budget). A world sky first: its
+ * catalogue stars copied as they are (brightest first, so a small budget keeps the brightest), then
+ * its stand-ins, then seeded faint fill; a seeded sky is `count` seeded stars. Stars gather into the
+ * band by `band`.
+ */
+export declare function buildStarGeometry(opts: {
+    seed: number;
+    count: number;
+    band: number;
+    frame: BandFrame;
+    world?: WorldSky | null;
+}): THREE.BufferGeometry;
+/** The constellation figures of a world sky, straight from the file. */
+export declare function buildLineGeometry(world: WorldSky): THREE.BufferGeometry;

package/dist/sky/geometry.js

@@ -0,0 +1,84 @@
+// Star and line buffers. One layout for every sky: direction `Int16 × 3` (normalised) + colour and
+// brightness `Uint8 × 4` (normalised) = 10 bytes a star, the world-sky file's own layout, so a world
+// sky's catalogue stars are copied in as they are and only the seeded stars are worked out here.
+import * as THREE from 'three';
+import { blackbodyColor } from '../star/blackbody.js';
+import { createLcg } from '../star/layout.js';
+const INT16 = 32767;
+/** An equatorial direction in the scene frame (y = celestial north). */
+export function equatorial(raDeg, decDeg, out = new THREE.Vector3()) {
+    const a = THREE.MathUtils.degToRad(raDeg);
+    const d = THREE.MathUtils.degToRad(decDeg);
+    return out.set(Math.cos(d) * Math.cos(a), Math.sin(d), -Math.cos(d) * Math.sin(a));
+}
+/** A seeded band, tilted `tiltDeg` from the equator, its core at a seeded longitude. */
+export function seededBandFrame(seed, tiltDeg) {
+    const basis = new THREE.Matrix4().makeRotationX(THREE.MathUtils.degToRad(tiltDeg));
+    const lon = createLcg(seed ^ 0x5bd1e995)() * Math.PI * 2;
+    basis.multiply(new THREE.Matrix4().makeRotationY(-lon));
+    return { basis, core: new THREE.Vector3(1, 0, 0).applyMatrix4(basis).normalize() };
+}
+/**
+ * The Milky Way: the galactic plane (J2000 north pole and centre). From every catalogued host it
+ * is the same plane to well under a degree, so it holds for every world sky.
+ */
+export function galacticBandFrame() {
+    const pole = equatorial(192.85948, 27.12825);
+    const centre = equatorial(266.40499, -28.93617);
+    const x = centre.sub(pole.clone().multiplyScalar(centre.dot(pole))).normalize();
+    const z = new THREE.Vector3().crossVectors(x, pole);
+    return { basis: new THREE.Matrix4().makeBasis(x, pole, z), core: x.clone() };
+}
+/** Naked-eye stand-ins reach this brightness (0..1), under the glow tier so only real stars glow; faint fill stays under the catalogue's limit. */
+const STAND_IN_BRIGHTNESS = 0.7;
+const FILL_BRIGHTNESS = 0.22;
+/**
+ * The star buffer, exactly `count` stars (the device's star budget). A world sky first: its
+ * catalogue stars copied as they are (brightest first, so a small budget keeps the brightest), then
+ * its stand-ins, then seeded faint fill; a seeded sky is `count` seeded stars. Stars gather into the
+ * band by `band`.
+ */
+export function buildStarGeometry(opts) {
+    const { seed, band, frame, world } = opts;
+    const total = Math.max(0, opts.count);
+    const worldStars = world ? Math.min(world.starCount, total) : 0;
+    const standIns = world ? Math.min(world.standIns, total - worldStars) : 0;
+    const dir = new Int16Array(total * 3);
+    const cb = new Uint8Array(total * 4);
+    if (world) {
+        dir.set(world.directions.subarray(0, worldStars * 3));
+        cb.set(world.colourBrightness.subarray(0, worldStars * 4));
+    }
+    const rand = createLcg(seed);
+    const v = new THREE.Vector3();
+    const bandShare = 0.1 + 0.5 * band;
+    for (let i = worldStars; i < total; i++) {
+        const inBand = rand() < bandShare;
+        const lon = rand() * Math.PI * 2;
+        const lat = inBand ? (rand() + rand() + rand() - 1.5) * 0.2 : Math.asin(rand() * 2 - 1);
+        v.set(Math.cos(lat) * Math.cos(lon), Math.sin(lat), Math.cos(lat) * Math.sin(lon)).applyMatrix4(frame.basis);
+        dir[i * 3] = Math.round(v.x * INT16);
+        dir[i * 3 + 1] = Math.round(v.y * INT16);
+        dir[i * 3 + 2] = Math.round(v.z * INT16);
+        // Many faint, few bright. Under a world sky: stand-ins at naked-eye brightness, then faint fill.
+        const scale = !world ? 1 : i < worldStars + standIns ? STAND_IN_BRIGHTNESS : FILL_BRIGHTNESS;
+        const c = blackbodyColor(2800 + Math.pow(rand(), 2.2) * 12000);
+        cb[i * 4] = Math.round(c.r * 255);
+        cb[i * 4 + 1] = Math.round(c.g * 255);
+        cb[i * 4 + 2] = Math.round(c.b * 255);
+        cb[i * 4 + 3] = Math.round(Math.pow(rand(), 4) * scale * 255);
+    }
+    const geo = new THREE.BufferGeometry();
+    geo.setAttribute('position', new THREE.BufferAttribute(dir, 3, true));
+    geo.setAttribute('aColourBrightness', new THREE.BufferAttribute(cb, 4, true));
+    // Stars sit at infinity in every direction: never frustum-cull them.
+    geo.boundingSphere = new THREE.Sphere(new THREE.Vector3(), Infinity);
+    return geo;
+}
+/** The constellation figures of a world sky, straight from the file. */
+export function buildLineGeometry(world) {
+    const geo = new THREE.BufferGeometry();
+    geo.setAttribute('position', new THREE.BufferAttribute(world.lines, 3, true));
+    geo.boundingSphere = new THREE.Sphere(new THREE.Vector3(), Infinity);
+    return geo;
+}

package/dist/sky/index.d.ts

@@ -0,0 +1,6 @@
+export { createSky } from './sky.js';
+export type { Sky, CreateSkyOptions } from './sky.js';
+export { DEFAULT_SKY_PARAMS, SKY_PARAM_RANGES, SKY_LOOK_KEYS, SKY_SHAPE_KEYS, normalizeSkyParams, } from './params.js';
+export type { SkyParams, SkySource } from './params.js';
+export { parseWorldSky, WORLD_SKY_MAGIC, WORLD_SKY_FORMAT } from './worldSkyFile.js';
+export type { WorldSky } from './worldSkyFile.js';

package/dist/sky/index.js

@@ -0,0 +1,6 @@
+// ./sky — the sky behind a world: a parametric star field (seeded, or the world's own sky as seen
+// from its host star, read from the backend's precomputed file), an optional nebula + Milky Way
+// baked once per change, and constellation figures. Replaces the six-face painted skycube.
+export { createSky } from './sky.js';
+export { DEFAULT_SKY_PARAMS, SKY_PARAM_RANGES, SKY_LOOK_KEYS, SKY_SHAPE_KEYS, normalizeSkyParams, } from './params.js';
+export { parseWorldSky, WORLD_SKY_MAGIC, WORLD_SKY_FORMAT } from './worldSkyFile.js';

package/dist/sky/params.d.ts

@@ -0,0 +1,44 @@
+/** Where the stars come from: a seed, or the world's own sky (the backend's file for its host star). */
+export type SkySource = 'seeded' | 'world';
+export interface SkyParams {
+    source: SkySource;
+    /** Same seed → same sky. Also seeds the stand-in stars and the nebula under a world sky. */
+    seed: number;
+    /** Stars drawn: the device's star budget. A world sky spends it on its catalogue stars first
+     * (brightest first), then its stand-ins, then faint fill. */
+    count: number;
+    /** Star brightness multiplier. */
+    brightness: number;
+    /** Star size in pixels at a 1080-pixel-tall frame, for the brightest ordinary star. */
+    size: number;
+    /** 0 = every star white, 1 = full blackbody colour. */
+    colour: number;
+    /** 0 = steady, 1 = full twinkle. */
+    twinkle: number;
+    /** Nebula amount, 0 = no nebula layer at all (the cheapest sky). */
+    nebula: number;
+    /** Nebula hue, degrees. */
+    hue: number;
+    /** How far the nebula's hue wanders around `hue`, degrees. */
+    hueSpread: number;
+    /** How much stars and clouds gather into a Milky Way band, 0..1. */
+    band: number;
+    /** Band tilt, degrees. Seeded skies only: a world sky's band is the galactic plane. */
+    bandTilt: number;
+    /** Constellation figures' strength, 0 = hidden. World skies only. */
+    constellations: number;
+}
+export declare const DEFAULT_SKY_PARAMS: Readonly<SkyParams>;
+type NumericKey = Exclude<keyof SkyParams, 'source'>;
+/** Valid range of every numeric param, for UIs and for `normalizeSkyParams`. */
+export declare const SKY_PARAM_RANGES: Readonly<Record<NumericKey, {
+    min: number;
+    max: number;
+}>>;
+/** Params that only change uniforms: no rebuild, no re-bake. */
+export declare const SKY_LOOK_KEYS: readonly ["brightness", "size", "colour", "twinkle", "constellations", "nebula", "hue", "hueSpread"];
+/** Params that rebuild the star buffer (at most once a frame); all but `count` also re-bake the glow's shape. */
+export declare const SKY_SHAPE_KEYS: readonly ["source", "seed", "count", "band", "bandTilt"];
+/** A complete, in-range set from anything stored: missing or invalid fields take the default. */
+export declare function normalizeSkyParams(input: unknown): SkyParams;
+export {};

package/dist/sky/params.js

@@ -0,0 +1,52 @@
+// What a world sets on its sky. Plain data, so it persists as-is; `normalizeSkyParams` is the one
+// boundary that turns whatever was stored (or nothing) into a complete, in-range set.
+export const DEFAULT_SKY_PARAMS = Object.freeze({
+    source: 'seeded',
+    seed: 1,
+    count: 40000,
+    brightness: 1,
+    size: 3,
+    colour: 0.7,
+    twinkle: 0.4,
+    nebula: 0.6,
+    hue: 255,
+    hueSpread: 50,
+    band: 0.6,
+    bandTilt: 60,
+    constellations: 0,
+});
+/** Valid range of every numeric param, for UIs and for `normalizeSkyParams`. */
+export const SKY_PARAM_RANGES = Object.freeze({
+    seed: { min: 0, max: 2 ** 31 - 1 },
+    count: { min: 0, max: 100000 },
+    brightness: { min: 0, max: 3 },
+    size: { min: 0.5, max: 5 },
+    colour: { min: 0, max: 1 },
+    twinkle: { min: 0, max: 1 },
+    nebula: { min: 0, max: 1 },
+    hue: { min: 0, max: 360 },
+    hueSpread: { min: 0, max: 180 },
+    band: { min: 0, max: 1 },
+    bandTilt: { min: 0, max: 180 },
+    constellations: { min: 0, max: 1 },
+});
+/** Params that only change uniforms: no rebuild, no re-bake. */
+export const SKY_LOOK_KEYS = ['brightness', 'size', 'colour', 'twinkle', 'constellations', 'nebula', 'hue', 'hueSpread'];
+/** Params that rebuild the star buffer (at most once a frame); all but `count` also re-bake the glow's shape. */
+export const SKY_SHAPE_KEYS = ['source', 'seed', 'count', 'band', 'bandTilt'];
+/** A complete, in-range set from anything stored: missing or invalid fields take the default. */
+export function normalizeSkyParams(input) {
+    const raw = (input && typeof input === 'object' ? input : {});
+    const out = { ...DEFAULT_SKY_PARAMS };
+    out.source = raw.source === 'world' ? 'world' : 'seeded';
+    for (const key of Object.keys(SKY_PARAM_RANGES)) {
+        const v = raw[key];
+        if (typeof v !== 'number' || !Number.isFinite(v))
+            continue;
+        const { min, max } = SKY_PARAM_RANGES[key];
+        out[key] = Math.min(max, Math.max(min, v));
+    }
+    out.seed = Math.round(out.seed);
+    out.count = Math.round(out.count);
+    return out;
+}

package/dist/sky/shaders.d.ts

@@ -0,0 +1,14 @@
+/** Ordinary stars are never drawn bigger than this (pixels at a 1080-pixel-tall frame); glow stars 3.2×. */
+export declare const MAX_STAR_SIZE = 5;
+/** Brightness (0..1) above which a star joins the glow tier: ~1% of a seeded sky; on a world sky,
+ * every catalogue star brighter than apparent magnitude ~1. */
+export declare const GLOW_SEEDED = 0.965;
+export declare const GLOW_WORLD = 0.73;
+export declare const STAR_VERTEX: string;
+export declare const STAR_FRAGMENT = "\n  varying vec3 vColour;\n  varying float vAlpha;\n  varying float vGlow;\n  void main() {\n    vec2 d = gl_PointCoord - 0.5;\n    float r2 = dot(d, d) * 4.0;\n    // Ordinary star: a soft core. Glow star: a tighter core plus a wide halo and a thin cross, so a\n    // handful of stars read as bright without a bloom pass.\n    float core = exp(-r2 * mix(3.5, 11.0, vGlow));\n    float halo = vGlow * (0.4 * exp(-r2 * 3.0) + 0.3 * exp(-abs(d.x * d.y) * 700.0) * (1.0 - r2));\n    // No discard (it defeats early depth on tile GPUs); additive black adds nothing.\n    gl_FragColor = vec4(vColour * (core + max(halo, 0.0)) * vAlpha, 1.0);\n  }\n";
+export declare const NEBULA_VERTEX = "\n  uniform float uFar;\n  varying vec3 vDir;\n  void main() {\n    vDir = position;\n    gl_Position = projectionMatrix * vec4(mat3(modelViewMatrix) * position * uFar * 0.5, 1.0);\n  }\n";
+export declare const NEBULA_FRAGMENT = "\n  varying vec3 vDir;\n  uniform samplerCube uNebula;\n  uniform float uAmount;\n  uniform float uHue;\n  uniform float uSpread;\n  vec3 hsv(float h, float s, float v) {\n    vec3 k = clamp(abs(mod(h / 60.0 + vec3(0.0, 4.0, 2.0), 6.0) - 3.0) - 1.0, 0.0, 1.0);\n    return v * mix(vec3(1.0), k, s);\n  }\n  void main() {\n    vec3 f = textureCube(uNebula, vDir).rgb;\n    vec3 c = hsv(uHue + uSpread * (f.g - 0.5) * 3.0, 0.7 - 0.3 * f.b, 1.0) * f.r * uAmount;\n    // Under a pixel of dither (interleaved gradient noise): the 8-bit screen would otherwise band\n    // the glow's last faint steps into black.\n    float dither = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715)))) - 0.5;\n    gl_FragColor = vec4(max(c + dither / 255.0, 0.0), 1.0);\n  }\n";
+export declare const LINE_VERTEX = "\n  uniform float uFar;\n  void main() {\n    gl_Position = projectionMatrix * vec4(mat3(modelViewMatrix) * normalize(position) * uFar * 0.9, 1.0);\n  }\n";
+export declare const LINE_FRAGMENT = "\n  uniform float uLines;\n  void main() { gl_FragColor = vec4(vec3(0.45, 0.6, 0.9) * uLines * 0.35, 1.0); }\n";
+export declare const BAKE_VERTEX = "\n  varying vec3 vDir;\n  void main() {\n    vDir = position;\n    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n  }\n";
+export declare const BAKE_FRAGMENT = "\n  varying vec3 vDir;\n  uniform float uSeed;\n  uniform float uBand;\n  uniform mat3 uToBand;\n  uniform vec3 uCoreDir;\n  float hash(vec3 p) {\n    p = fract(p * 0.3183099 + vec3(0.71, 0.113, 0.419) * (1.0 + uSeed * 0.137));\n    p *= 17.0;\n    return fract(p.x * p.y * p.z * (p.x + p.y + p.z));\n  }\n  float noise(vec3 x) {\n    vec3 i = floor(x);\n    vec3 f = fract(x);\n    f = f * f * (3.0 - 2.0 * f);\n    return mix(mix(mix(hash(i), hash(i + vec3(1, 0, 0)), f.x), mix(hash(i + vec3(0, 1, 0)), hash(i + vec3(1, 1, 0)), f.x), f.y),\n               mix(mix(hash(i + vec3(0, 0, 1)), hash(i + vec3(1, 0, 1)), f.x), mix(hash(i + vec3(0, 1, 1)), hash(i + vec3(1, 1, 1)), f.x), f.y), f.z);\n  }\n  float fbm(vec3 p) {\n    float a = 0.5, s = 0.0;\n    for (int i = 0; i < 7; i++) { s += a * noise(p); p = p * 2.03 + vec3(1.7, 9.2, 4.1); a *= 0.5; }\n    return s;\n  }\n  void main() {\n    vec3 d = normalize(vDir);\n    vec3 q = d * 2.2 + vec3(uSeed * 3.17, uSeed * 1.31, uSeed * 2.07);\n    vec3 w = vec3(fbm(q), fbm(q + vec3(5.2, 1.3, 2.8)), fbm(q + vec3(9.1, 4.7, 7.3)));\n    float n = fbm(q + 1.9 * w);\n    float lat = (uToBand * d).y;\n    float bandMask = exp(-lat * lat / 0.06);\n    float density = smoothstep(0.42, 0.9, n) * mix(1.0, 0.25 + 1.6 * bandMask, uBand);\n    float core = exp(-(1.0 - dot(d, uCoreDir)) * 5.0) * bandMask * uBand;\n    density *= 1.0 + 1.8 * core;\n    float dust = smoothstep(0.5, 0.75, fbm(q * 2.7 + w * 1.3 + 3.0));\n    density *= 1.0 - 0.75 * dust * bandMask * uBand;\n    density += 0.12 * uBand * bandMask * (0.6 + 0.4 * n);\n    gl_FragColor = vec4(density * 0.42, w.x, bandMask * uBand, 1.0);\n  }\n";

package/dist/sky/shaders.js

@@ -0,0 +1,149 @@
+// The sky's shaders. Only the nebula bake runs noise, and only once per change; every per-frame
+// shader is a handful of instructions.
+/** Ordinary stars are never drawn bigger than this (pixels at a 1080-pixel-tall frame); glow stars 3.2×. */
+export const MAX_STAR_SIZE = 5;
+/** Brightness (0..1) above which a star joins the glow tier: ~1% of a seeded sky; on a world sky,
+ * every catalogue star brighter than apparent magnitude ~1. */
+export const GLOW_SEEDED = 0.965;
+export const GLOW_WORLD = 0.73;
+export const STAR_VERTEX = /* glsl */ `
+  attribute vec4 aColourBrightness;
+  uniform float uTime;
+  uniform float uBrightness;
+  uniform float uSize;
+  uniform float uColour;
+  uniform float uTwinkle;
+  uniform float uPixelScale;
+  uniform float uGlowAt;
+  varying vec3 vColour;
+  varying float vAlpha;
+  varying float vGlow;
+  float hash(float n) { return fract(sin(n) * 43758.5453); }
+  void main() {
+    // Rotation only: the sky is at infinity. xyww pins depth to the far plane, so bodies in front
+    // hide the stars behind them before their fragments run. (Points cannot streak at w = 0.)
+    vec4 p = projectionMatrix * vec4(mat3(modelViewMatrix) * normalize(position), 1.0);
+    gl_Position = p.xyww;
+    float mag = aColourBrightness.a;
+    float h = hash(float(gl_VertexID) * 1.618);
+    // Twinkle reads the playback clock, so a recording is the same every time.
+    float tw = 1.0 + uTwinkle * 0.45 * sin(uTime * (1.3 + 3.0 * h) + h * 6.2831) * (0.4 + 0.6 * (1.0 - mag));
+    vGlow = step(uGlowAt, mag);
+    float px = (0.8 + (uSize - 0.8) * pow(mag, 0.6)) * uPixelScale;
+    px = min(px, ${MAX_STAR_SIZE.toFixed(1)} * uPixelScale);
+    // Glow stars: a bigger sprite whose rim is the halo; the core stays star-sized.
+    px *= 1.0 + 2.2 * vGlow;
+    // Sub-pixel stars: draw one pixel and fade, so energy stays and nothing shimmers.
+    float fade = clamp(px, 0.0, 1.0);
+    gl_PointSize = max(px, 1.0);
+    float lum = dot(aColourBrightness.rgb, vec3(0.2126, 0.7152, 0.0722));
+    vColour = mix(vec3(lum), aColourBrightness.rgb, uColour) / max(lum, 0.2);
+    vAlpha = uBrightness * fade * tw * (0.55 + 0.45 * mag);
+  }
+`;
+export const STAR_FRAGMENT = /* glsl */ `
+  varying vec3 vColour;
+  varying float vAlpha;
+  varying float vGlow;
+  void main() {
+    vec2 d = gl_PointCoord - 0.5;
+    float r2 = dot(d, d) * 4.0;
+    // Ordinary star: a soft core. Glow star: a tighter core plus a wide halo and a thin cross, so a
+    // handful of stars read as bright without a bloom pass.
+    float core = exp(-r2 * mix(3.5, 11.0, vGlow));
+    float halo = vGlow * (0.4 * exp(-r2 * 3.0) + 0.3 * exp(-abs(d.x * d.y) * 700.0) * (1.0 - r2));
+    // No discard (it defeats early depth on tile GPUs); additive black adds nothing.
+    gl_FragColor = vec4(vColour * (core + max(halo, 0.0)) * vAlpha, 1.0);
+  }
+`;
+// Lines and the nebula box sit at a real radius just inside the far plane, not at xyww: pinning z to
+// w breaks clipping at w = 0, and an edge that crosses behind the camera then streaks across the
+// frame. The box's corners are √3 out, hence 0.5 of the far plane.
+export const NEBULA_VERTEX = /* glsl */ `
+  uniform float uFar;
+  varying vec3 vDir;
+  void main() {
+    vDir = position;
+    gl_Position = projectionMatrix * vec4(mat3(modelViewMatrix) * position * uFar * 0.5, 1.0);
+  }
+`;
+// Colours the baked glow field: R its strength, G where its hue wanders, B how much it is the
+// band. Glow, hue and hue spread are uniforms here, so dragging them never re-bakes.
+export const NEBULA_FRAGMENT = /* glsl */ `
+  varying vec3 vDir;
+  uniform samplerCube uNebula;
+  uniform float uAmount;
+  uniform float uHue;
+  uniform float uSpread;
+  vec3 hsv(float h, float s, float v) {
+    vec3 k = clamp(abs(mod(h / 60.0 + vec3(0.0, 4.0, 2.0), 6.0) - 3.0) - 1.0, 0.0, 1.0);
+    return v * mix(vec3(1.0), k, s);
+  }
+  void main() {
+    vec3 f = textureCube(uNebula, vDir).rgb;
+    vec3 c = hsv(uHue + uSpread * (f.g - 0.5) * 3.0, 0.7 - 0.3 * f.b, 1.0) * f.r * uAmount;
+    // Under a pixel of dither (interleaved gradient noise): the 8-bit screen would otherwise band
+    // the glow's last faint steps into black.
+    float dither = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715)))) - 0.5;
+    gl_FragColor = vec4(max(c + dither / 255.0, 0.0), 1.0);
+  }
+`;
+export const LINE_VERTEX = /* glsl */ `
+  uniform float uFar;
+  void main() {
+    gl_Position = projectionMatrix * vec4(mat3(modelViewMatrix) * normalize(position) * uFar * 0.9, 1.0);
+  }
+`;
+export const LINE_FRAGMENT = /* glsl */ `
+  uniform float uLines;
+  void main() { gl_FragColor = vec4(vec3(0.45, 0.6, 0.9) * uLines * 0.35, 1.0); }
+`;
+export const BAKE_VERTEX = /* glsl */ `
+  varying vec3 vDir;
+  void main() {
+    vDir = position;
+    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+  }
+`;
+// Runs once per bake over the cube's texels: domain-warped fbm clouds, gathered into the band,
+// brighter toward its core, cut by dust lanes. It bakes the glow's shape only (strength, hue
+// driver, band share); NEBULA_FRAGMENT colours it.
+export const BAKE_FRAGMENT = /* glsl */ `
+  varying vec3 vDir;
+  uniform float uSeed;
+  uniform float uBand;
+  uniform mat3 uToBand;
+  uniform vec3 uCoreDir;
+  float hash(vec3 p) {
+    p = fract(p * 0.3183099 + vec3(0.71, 0.113, 0.419) * (1.0 + uSeed * 0.137));
+    p *= 17.0;
+    return fract(p.x * p.y * p.z * (p.x + p.y + p.z));
+  }
+  float noise(vec3 x) {
+    vec3 i = floor(x);
+    vec3 f = fract(x);
+    f = f * f * (3.0 - 2.0 * f);
+    return mix(mix(mix(hash(i), hash(i + vec3(1, 0, 0)), f.x), mix(hash(i + vec3(0, 1, 0)), hash(i + vec3(1, 1, 0)), f.x), f.y),
+               mix(mix(hash(i + vec3(0, 0, 1)), hash(i + vec3(1, 0, 1)), f.x), mix(hash(i + vec3(0, 1, 1)), hash(i + vec3(1, 1, 1)), f.x), f.y), f.z);
+  }
+  float fbm(vec3 p) {
+    float a = 0.5, s = 0.0;
+    for (int i = 0; i < 7; i++) { s += a * noise(p); p = p * 2.03 + vec3(1.7, 9.2, 4.1); a *= 0.5; }
+    return s;
+  }
+  void main() {
+    vec3 d = normalize(vDir);
+    vec3 q = d * 2.2 + vec3(uSeed * 3.17, uSeed * 1.31, uSeed * 2.07);
+    vec3 w = vec3(fbm(q), fbm(q + vec3(5.2, 1.3, 2.8)), fbm(q + vec3(9.1, 4.7, 7.3)));
+    float n = fbm(q + 1.9 * w);
+    float lat = (uToBand * d).y;
+    float bandMask = exp(-lat * lat / 0.06);
+    float density = smoothstep(0.42, 0.9, n) * mix(1.0, 0.25 + 1.6 * bandMask, uBand);
+    float core = exp(-(1.0 - dot(d, uCoreDir)) * 5.0) * bandMask * uBand;
+    density *= 1.0 + 1.8 * core;
+    float dust = smoothstep(0.5, 0.75, fbm(q * 2.7 + w * 1.3 + 3.0));
+    density *= 1.0 - 0.75 * dust * bandMask * uBand;
+    density += 0.12 * uBand * bandMask * (0.6 + 0.4 * n);
+    gl_FragColor = vec4(density * 0.42, w.x, bandMask * uBand, 1.0);
+  }
+`;

package/dist/sky/sky.d.ts

@@ -0,0 +1,24 @@
+import * as THREE from 'three';
+import { type SkyParams } from './params.js';
+import type { WorldSky } from './worldSkyFile.js';
+export interface CreateSkyOptions {
+    /** The world's sky (`parseWorldSky`), used when `params.source` is `'world'`. */
+    world?: WorldSky | null;
+    /** Nebula cube face size: 512 on desktops, 256 on phones (the clouds are soft either way). */
+    nebulaSize?: number;
+}
+export interface Sky {
+    /** Add to the scene. Rotate it to turn the sky. */
+    readonly object: THREE.Group;
+    /** Applies a partial change: uniforms only for look params, a re-bake for nebula params, a rebuild for shape params. */
+    setParams(next: Partial<SkyParams>): void;
+    /** Swaps the world sky (a new host, or none). Rebuilds when the source is `'world'`. */
+    setWorld(world: WorldSky | null): void;
+    /** Call once a frame before rendering: clock time in seconds (the playback clock) and the drawing
+     * buffer's height in pixels. Runs a pending nebula bake. */
+    update(timeSec: number, drawingBufferHeight: number): void;
+    /** Bytes the sky holds on the GPU. */
+    gpuBytes(): number;
+    dispose(): void;
+}
+export declare function createSky(renderer: THREE.WebGLRenderer, initial?: Partial<SkyParams>, options?: CreateSkyOptions): Sky;