entangled-worlds-orbiters-shared 5.0.0 → 5.1.0

package/README.md

@@ -99,7 +99,7 @@ The capability registry (`createCapabilityRegistry`, `validate` / `assertValid`,
 - `largestFunction`, `shrinkWasm` - The size check and the shrink step
 
 ### Keyboard shortcuts (`entangled-worlds-orbiters-shared/shortcuts`)
-- `ShortcutAction` - One catalogue entry: `id`, `label` (+ `names` by language), `defaultKeys` (by key place, `event.code`), `scope`
+- `ShortcutAction` - One catalogue entry: `id`, `label` (+ `names` by language), `defaultKeys` (named as a US keyboard names them, `event.code`; a press matches by the character it types, by its place only where it types no US character, so keys work on any keyboard), `scope`
 - `matchShortcut(event, bindings)` - Which action a press is, or `null`: modifiers, a field being typed in and surface claims decided in one place
 - Key strings: `Shift+KeyR`, `Mod+KeyZ` (Ctrl or ⌘), `Shift?+KeyQ` (Shift may be held); `parseChord`, `chordsOverlap`
 - `resolveBindings(catalogue, overrides)`, `findClashes` - Defaults plus a person's overrides (`[{ id, keys }]` as their settings store them, `keys: []` unbinds), and the clash check

package/dist/shortcuts/chord.d.ts

@@ -18,8 +18,30 @@ export interface ModifierState {
 }
 /** The chord a key string names, or `null` when it names none (an unknown modifier, a doubled one, no key). */
 export declare function parseChord(keys: string): Chord | null;
-/** Whether a press of `code` with these modifiers is this chord. */
-export declare function chordMatches(chord: Chord, code: string, state: ModifierState): boolean;
+/** A press as a chord reads it: the modifiers, the key's place and, when the browser says, the character it typed. */
+export interface ChordPress extends ModifierState {
+    readonly code: string;
+    readonly key?: string;
+}
+/** How a press is this chord: by the character it typed, by the key's place, or not at all. */
+export type ChordMatch = 'character' | 'place' | null;
+/**
+ * How a press is this chord. `character` beats `place`: on a Spanish keyboard Shift+7 types `/`, so it
+ * is the `/` key before it is the `7` key. A press with no `key` (an old caller) matches by place only.
+ */
+export declare function chordMatch(chord: Chord, press: ChordPress): ChordMatch;
+/** Whether a press of `code` with these modifiers (and, when given, the character it typed) is this chord. */
+export declare function chordMatches(chord: Chord, code: string, state: ModifierState & {
+    readonly key?: string;
+}): boolean;
+/**
+ * The key string a typed character names (`/` → `Slash`, `?` → `Shift+Slash`, `q` → `KeyQ`), for
+ * someone setting a key; `null` for a character a US keyboard does not have, or none.
+ */
+export declare function typedKey(key: string | undefined): {
+    readonly code: string;
+    readonly shift?: boolean;
+} | null;
 /** A chord that needs Ctrl or ⌘: a command, never a character typed. */
 export declare function isCommandChord(chord: Chord): boolean;
 /** Whether one press could be both chords — the test for a clash. */

package/dist/shortcuts/chord.js

@@ -1,7 +1,13 @@
 // One key with its modifiers, written as a string: `Shift+KeyR`, `Mod+KeyZ`, `Shift?+Digit1`.
 //
-// The last part is the key's PLACE (`KeyboardEvent.code`), so a French or German keyboard keeps the
-// same layout: the key, not the letter it prints. Before it, the modifiers:
+// The last part names the key the way a US keyboard does (`KeyboardEvent.code`: `KeyQ`, `Slash`,
+// `Digit1`). A press matches it by the CHARACTER it types wherever it types one, so `/` is the key
+// that prints `/` on this person's keyboard (Shift+7 on a Spanish one), and `KeyQ` is the key that
+// prints Q (top left on a French one). Only where the key types no character the US keyboard has
+// (a Greek or Cyrillic letter, ⌥ on a Mac changing it, a dead key, no letter on a letter key) is the
+// key matched by its place.
+// Digits match by character first, then by place: a French keyboard types `&` there.
+// Before the key, the modifiers:
 //
 //   Shift, Alt, Ctrl, Meta   held. One left out must NOT be held.
 //   Mod                      Ctrl or ⌘ (either, or both), the command key of every platform.
@@ -48,18 +54,90 @@ function parse(keys) {
     return { code, ...rules };
 }
 const fits = (rule, down) => rule === 'any' || (rule === 'held') === Boolean(down);
-/** Whether a press of `code` with these modifiers is this chord. */
-export function chordMatches(chord, code, state) {
-    if (chord.code !== code)
-        return false;
-    if (!fits(chord.shift, state.shiftKey) || !fits(chord.alt, state.altKey))
-        return false;
+/**
+ * The punctuation keys a chord may name, and what a US keyboard types there without and with Shift:
+ * what the chord means on every keyboard. With these, Shift is part of the character (`?` is
+ * `Shift+Slash`), so a keyboard that needs Shift, or AltGr, for a `/` still types the `/`.
+ */
+const PUNCTUATION = {
+    Minus: ['-', '_'], Equal: ['=', '+'], BracketLeft: ['[', '{'], BracketRight: [']', '}'], Backslash: ['\\', '|'],
+    Semicolon: [';', ':'], Quote: ["'", '"'], Backquote: ['`', '~'], Comma: [',', '<'], Period: ['.', '>'], Slash: ['/', '?'],
+};
+/** The code a US keyboard types each punctuation character at, and whether it takes Shift. */
+const PUNCTUATION_PLACE = new Map(Object.entries(PUNCTUATION).flatMap(([code, [plain, shifted]]) => [[plain, [code, false]], [shifted, [code, true]]]));
+/** The character a press typed, when it is one a US keyboard has (printable ASCII); else `null`. */
+function typed(key) {
+    return typeof key === 'string' && key.length === 1 && key >= '!' && key <= '~' ? key : null;
+}
+function commandFits(chord, state) {
     if (chord.mod === 'held')
         return Boolean(state.ctrlKey || state.metaKey);
     if (chord.mod === 'any')
         return true;
     return fits(chord.ctrl, state.ctrlKey) && fits(chord.meta, state.metaKey);
 }
+function placeMatch(chord, code, state) {
+    return chord.code === code && fits(chord.shift, state.shiftKey) && fits(chord.alt, state.altKey) && commandFits(chord, state);
+}
+/**
+ * How a press is this chord. `character` beats `place`: on a Spanish keyboard Shift+7 types `/`, so it
+ * is the `/` key before it is the `7` key. A press with no `key` (an old caller) matches by place only.
+ */
+export function chordMatch(chord, press) {
+    const char = typed(press.key);
+    if (char === null)
+        return placeMatch(chord, press.code, press) ? 'place' : null;
+    const punctuation = PUNCTUATION[chord.code];
+    if (punctuation) {
+        // Shift is in the character (a Spanish `/` is Shift+7); with ⌘ some browsers report the key
+        // unshifted, so `⇧⌘,` is also a `,` with Shift held. Alt only when the chord asks for it (AltGr
+        // and ⌥ type characters).
+        const [plain, shifted] = punctuation;
+        const asShifted = char === shifted || (isCommandChord(chord) && char === plain && press.shiftKey);
+        const ok = chord.shift === 'held' ? asShifted : chord.shift === 'any' ? char === plain || asShifted : char === plain;
+        // A command (⇧⌘,) where this keyboard types another character there: the key's place, as menus do.
+        if (!ok)
+            return isCommandChord(chord) && placeMatch(chord, press.code, press) ? 'place' : null;
+        if (chord.alt === 'held' && !press.altKey)
+            return null;
+        // AltGr arrives as Ctrl+Alt on Windows: that Ctrl typed the character, it is no command.
+        const altGr = press.altKey && press.ctrlKey && !press.metaKey;
+        return commandFits(chord, { ctrlKey: press.ctrlKey && !altGr, metaKey: press.metaKey, shiftKey: press.shiftKey, altKey: press.altKey }) ? 'character' : null;
+    }
+    const letter = /^Key([A-Z])$/.exec(chord.code)?.[1];
+    if (letter) {
+        // A key that types no letter (`;` where Q is on a Greek keyboard) is read by its place.
+        if (!/^[a-zA-Z]$/.test(char))
+            return placeMatch(chord, press.code, press) ? 'place' : null;
+        if (char.toUpperCase() !== letter)
+            return null;
+        return fits(chord.shift, press.shiftKey) && fits(chord.alt, press.altKey) && commandFits(chord, press) ? 'character' : null;
+    }
+    const digit = /^Digit(\d)$/.exec(chord.code)?.[1];
+    // A digit typed; where the keyboard types something else there (`&` on a French one), its place.
+    if (digit && char === digit && fits(chord.shift, press.shiftKey) && fits(chord.alt, press.altKey) && commandFits(chord, press))
+        return 'character';
+    return placeMatch(chord, press.code, press) ? 'place' : null;
+}
+/** Whether a press of `code` with these modifiers (and, when given, the character it typed) is this chord. */
+export function chordMatches(chord, code, state) {
+    // Field by field: a browser's KeyboardEvent keeps them on its prototype, where a spread does not reach.
+    const { shiftKey, altKey, ctrlKey, metaKey, key } = state;
+    return chordMatch(chord, { code, key, shiftKey, altKey, ctrlKey, metaKey }) !== null;
+}
+/**
+ * The key string a typed character names (`/` → `Slash`, `?` → `Shift+Slash`, `q` → `KeyQ`), for
+ * someone setting a key; `null` for a character a US keyboard does not have, or none.
+ */
+export function typedKey(key) {
+    const char = typed(key);
+    if (char === null)
+        return null;
+    if (/^[a-zA-Z]$/.test(char))
+        return { code: `Key${char.toUpperCase()}` };
+    const place = PUNCTUATION_PLACE.get(char);
+    return place ? { code: place[0], shift: place[1] } : null;
+}
 /** A chord that needs Ctrl or ⌘: a command, never a character typed. */
 export function isCommandChord(chord) {
     return chord.mod === 'held' || chord.ctrl === 'held' || chord.meta === 'held';

package/dist/shortcuts/format.d.ts

@@ -4,8 +4,8 @@ export type ShortcutPlatform = 'apple' | 'other';
 export declare function shortcutPlatform(): ShortcutPlatform;
 /**
  * The character a key place prints on this person's keyboard, when the browser can say
- * (`navigator.keyboard.getLayoutMap()`, Chromium only); a key place it does not know is shown from
- * its name.
+ * (`navigator.keyboard.getLayoutMap()`, Chromium only). Only keys matched by their place use it:
+ * a letter, digit or punctuation key matches the character it names, so it shows that character.
  */
 export type KeyLayout = ReadonlyMap<string, string>;
 /** What a key place is called on a keyboard: `KeyQ` → `Q`, `Digit1` → `1`, `Numpad4` → `Num 4`. */
@@ -20,11 +20,14 @@ export declare function chordParts(keys: string, platform?: ShortcutPlatform, la
 export declare function formatChord(keys: string, platform?: ShortcutPlatform, layout?: KeyLayout): string;
 /**
  * The key string a press makes, for someone setting a key: exactly the modifiers held, the command
- * key of their platform written `Mod` (⌘ on Apple, Ctrl elsewhere) so the key works on both. `null`
- * while only modifiers are down, or for a press with no key place.
+ * key of their platform written `Mod` (⌘ on Apple, Ctrl elsewhere) so the key works on both. A letter
+ * or punctuation character typed is written as the key that types it on a US keyboard (`/` is
+ * `Slash` whichever keys typed it), the way the matcher reads it back. `null` while only modifiers
+ * are down, or for a press with no key place.
  */
 export declare function chordFromEvent(event: {
     code: string;
+    key?: string;
     shiftKey: boolean;
     altKey: boolean;
     ctrlKey: boolean;

package/dist/shortcuts/format.js

@@ -1,6 +1,6 @@
 // A key string for people: how a chord is shown (`⌘⇧Z`, `Ctrl+Shift+Z`, `Q`), and the key string a
 // press makes when someone sets a key ("press a key to change").
-import { isModifierCode, parseChord } from './chord.js';
+import { isModifierCode, parseChord, typedKey } from './chord.js';
 /** The platform of this browser, by its own report; `other` outside a browser. */
 export function shortcutPlatform() {
     const nav = globalThis.navigator;
@@ -18,7 +18,8 @@ const NAMED = {
 };
 /** What a key place is called on a keyboard: `KeyQ` → `Q`, `Digit1` → `1`, `Numpad4` → `Num 4`. */
 export function keyLabel(code, layout) {
-    const printed = layout?.get(code);
+    const byCharacter = /^(Key[A-Z]|Digit\d)$/.test(code) || typedKey(NAMED[code])?.code === code;
+    const printed = byCharacter ? undefined : layout?.get(code);
     if (printed && printed.trim())
         return printed.length === 1 ? printed.toUpperCase() : printed;
     if (/^Key[A-Z]$/.test(code))
@@ -29,6 +30,11 @@ export function keyLabel(code, layout) {
         return `Num ${code.slice(6)}`;
     return NAMED[code] ?? code;
 }
+/** What a US keyboard types with Shift at each punctuation key. */
+const SHIFTED = {
+    Minus: '_', Equal: '+', BracketLeft: '{', BracketRight: '}', Backslash: '|', Semicolon: ':', Quote: '"',
+    Backquote: '~', Comma: '<', Period: '>', Slash: '?',
+};
 const SYMBOLS = { ctrl: '⌃', alt: '⌥', shift: '⇧', meta: '⌘' };
 const WORDS = { ctrl: 'Ctrl', alt: 'Alt', shift: 'Shift', meta: 'Meta' };
 /**
@@ -55,12 +61,16 @@ export function chordParts(keys, platform = shortcutPlatform(), layout) {
         parts.push(names.ctrl);
     if (held(chord.alt))
         parts.push(platform === 'apple' ? names.alt : 'Alt');
-    if (held(chord.shift))
+    // A punctuation key is the character it types, Shift included: `Shift+Slash` is `?`.
+    // A command (⇧⌘,) is shown as written: its Shift is a key to press, not part of a character.
+    const punctuation = !ctrl && !meta && typedKey(NAMED[chord.code])?.code === chord.code ? SHIFTED[chord.code] : undefined;
+    if (held(chord.shift) && !punctuation)
         parts.push(names.shift);
     if (meta)
         parts.push(names.meta);
-    // The help key is `?` wherever it lets Shift be held (its place is `/`): show what people press.
-    parts.push(chord.code === 'Slash' && chord.shift === 'any' && !layout ? '?' : keyLabel(chord.code, layout));
+    // The help key is `?` wherever it lets Shift be held (`/` or `?`): show what people press.
+    const shifted = punctuation && (held(chord.shift) || (chord.code === 'Slash' && chord.shift === 'any'));
+    parts.push(shifted ? punctuation : keyLabel(chord.code, layout));
     return parts;
 }
 /** One line for a chord: `⌘⇧Z` on Apple keyboards, `Ctrl+Shift+Z` elsewhere. */
@@ -74,28 +84,44 @@ export function formatChord(keys, platform = shortcutPlatform(), layout) {
 }
 /**
  * The key string a press makes, for someone setting a key: exactly the modifiers held, the command
- * key of their platform written `Mod` (⌘ on Apple, Ctrl elsewhere) so the key works on both. `null`
- * while only modifiers are down, or for a press with no key place.
+ * key of their platform written `Mod` (⌘ on Apple, Ctrl elsewhere) so the key works on both. A letter
+ * or punctuation character typed is written as the key that types it on a US keyboard (`/` is
+ * `Slash` whichever keys typed it), the way the matcher reads it back. `null` while only modifiers
+ * are down, or for a press with no key place.
  */
 export function chordFromEvent(event, platform = shortcutPlatform()) {
     if (!event.code || isModifierCode(event.code))
         return null;
+    const typed = typedKey(event.key);
+    const punctuation = typed?.shift !== undefined;
+    // A punctuation character carries its own Shift, and the AltGr or ⌥ that typed it is no modifier.
+    const altGr = punctuation && event.altKey && event.ctrlKey && !event.metaKey;
+    // Field by field: a browser's KeyboardEvent keeps them on its prototype, where a spread does not reach.
+    const press = punctuation
+        ? {
+            // With ⌘ or Ctrl some browsers report the key unshifted: the Shift held is then part of the chord.
+            shiftKey: Boolean(typed.shift) || (event.shiftKey && !altGr && (event.ctrlKey || event.metaKey)),
+            altKey: false,
+            ctrlKey: altGr ? false : event.ctrlKey,
+            metaKey: event.metaKey,
+        }
+        : event;
     const parts = [];
     // ⌘ (Ctrl elsewhere) is written Mod so the key works on both — unless Ctrl and ⌘ are both held,
     // which Mod cannot say: then both by name.
-    if (event.ctrlKey && event.metaKey)
+    if (press.ctrlKey && press.metaKey)
         parts.push('Ctrl', 'Meta');
-    else if (platform === 'apple' ? event.metaKey : event.ctrlKey)
+    else if (platform === 'apple' ? press.metaKey : press.ctrlKey)
         parts.push('Mod');
-    else if (event.ctrlKey)
+    else if (press.ctrlKey)
         parts.push('Ctrl');
-    else if (event.metaKey)
+    else if (press.metaKey)
         parts.push('Meta');
-    if (event.altKey)
+    if (press.altKey)
         parts.push('Alt');
-    if (event.shiftKey)
+    if (press.shiftKey)
         parts.push('Shift');
-    parts.push(event.code);
+    parts.push(typed?.code ?? event.code);
     const keys = parts.join('+');
     return parseChord(keys) ? keys : null;
 }

package/dist/shortcuts/index.d.ts

@@ -1,4 +1,4 @@
-export { parseChord, parseKeys, keysOverlap, chordMatches, chordsOverlap, isCommandChord, type Chord, type ModifierRule, type ModifierState, } from './chord.js';
+export { parseChord, parseKeys, keysOverlap, chordMatch, chordMatches, chordsOverlap, typedKey, isCommandChord, type Chord, type ModifierRule, type ModifierState, type ChordMatch, type ChordPress, } from './chord.js';
 export { matchShortcut, createShortcutMatcher, SEQUENCE_WAIT_MS, resolveBindings, findClashes, claimKeys, isKeyClaimed, isTypingTarget, type ShortcutAction, type ShortcutNames, type ShortcutBindings, type ShortcutOverrides, type ShortcutEvent, } from './match.js';
 export { shortcutPlatform, keyLabel, chordParts, formatChord, chordFromEvent, mergedKeyParts, recordedKeys, type ShortcutPlatform, type KeyLayout, } from './format.js';
 export { EMPTY_CATALOGUE, parseCatalogue, localName, localAppName, localPartName, shortcutApps, sectionActions, findSection, type ShortcutCatalogue, type ShortcutSection, type ShortcutNamed, type ShortcutSheetColumn, type ShortcutSheetRow, } from './catalogue.js';

package/dist/shortcuts/index.js

@@ -1,8 +1,9 @@
 // Keyboard shortcuts, one system for every app: the reader of the shortcut catalogue (every app's
 // actions and default keys, served by the backend) and of a person's own keys, and one matcher that
-// says which action a key press is. Keys are named by their place on the keyboard
-// (`KeyboardEvent.code`). Framework-free: no React, no DOM beyond reading a key event.
-export { parseChord, parseKeys, keysOverlap, chordMatches, chordsOverlap, isCommandChord, } from './chord.js';
+// says which action a key press is. Keys are named as a US keyboard names them
+// (`KeyboardEvent.code`) and matched by the character a press types, so they work on any keyboard.
+// Framework-free: no React, no DOM beyond reading a key event.
+export { parseChord, parseKeys, keysOverlap, chordMatch, chordMatches, chordsOverlap, typedKey, isCommandChord, } from './chord.js';
 export { matchShortcut, createShortcutMatcher, SEQUENCE_WAIT_MS, resolveBindings, findClashes, claimKeys, isKeyClaimed, isTypingTarget, } from './match.js';
 export { shortcutPlatform, keyLabel, chordParts, formatChord, chordFromEvent, mergedKeyParts, recordedKeys, } from './format.js';
 export { EMPTY_CATALOGUE, parseCatalogue, localName, localAppName, localPartName, shortcutApps, sectionActions, findSection, } from './catalogue.js';

package/dist/shortcuts/match.d.ts

@@ -58,7 +58,9 @@ export declare function isKeyClaimed(event: Pick<ShortcutEvent, 'key' | 'metaKey
 export declare function isTypingTarget(target: unknown): boolean;
 /**
  * The action this press is, or `null`. Not one while the person is typing in a field, nor a key a
- * surface holds; a widget that reads characters keeps its characters but not the ⌘ commands.
+ * surface holds; a widget that reads characters keeps its characters but not the ⌘ commands. A key
+ * that matches by the character typed wins over one that only matches by the key's place, whatever
+ * their order (Shift+7 types `/` on a Spanish keyboard: the `/` action, not the `7` one).
  */
 export declare function matchShortcut(event: ShortcutEvent, bindings: ShortcutBindings): string | null;
 /** How long the second key of a sequence (`G`, then `H`) may follow the first. */

package/dist/shortcuts/match.js

@@ -1,7 +1,7 @@
 // Which action a key press is. Each app keeps what its actions DO; this only answers which one a
 // press names, so every app reads keys the same way: the modifiers, a field being typed in, and a
 // surface that holds letters of its own are decided here, once.
-import { chordMatches, isCommandChord, isModifierCode, keysOverlap, parseChord, parseKeys } from './chord.js';
+import { chordMatch, chordMatches, isCommandChord, isModifierCode, keysOverlap, parseChord, parseKeys } from './chord.js';
 /**
  * Every action's keys: its defaults, or the person's override (unknown actions and keys that name no
  * chord are dropped). Catalogue order is kept, so the earlier catalogue wins where two match one press.
@@ -81,23 +81,29 @@ function readsCharacters(target) {
 }
 /**
  * The action this press is, or `null`. Not one while the person is typing in a field, nor a key a
- * surface holds; a widget that reads characters keeps its characters but not the ⌘ commands.
+ * surface holds; a widget that reads characters keeps its characters but not the ⌘ commands. A key
+ * that matches by the character typed wins over one that only matches by the key's place, whatever
+ * their order (Shift+7 types `/` on a Spanish keyboard: the `/` action, not the `7` one).
  */
 export function matchShortcut(event, bindings) {
     if (!event.code || isTypingTarget(event.target) || isKeyClaimed(event))
         return null;
     const characters = readsCharacters(event.target);
+    let byPlace = null;
     for (const [actionId, keys] of bindings) {
         for (const key of keys) {
             const chord = parseChord(key);
-            if (!chord || !chordMatches(chord, event.code, event))
+            const how = chord && chordMatch(chord, event);
+            if (!chord || !how)
                 continue;
-            if (characters && !isCommandChord(chord))
-                return null;
-            return actionId;
+            if (how === 'character')
+                return characters && !isCommandChord(chord) ? null : actionId;
+            byPlace ??= { id: actionId, command: isCommandChord(chord) };
         }
     }
-    return null;
+    if (!byPlace || (characters && !byPlace.command))
+        return null;
+    return byPlace.id;
 }
 // ---------------------------------------------------------------------------------------------
 // Sequences
@@ -137,7 +143,7 @@ export function createShortcutMatcher(waitMs = SEQUENCE_WAIT_MS, now = Date.now)
                     return id;
         }
         if (known.some(([, [one]]) => chordMatches(one, event.code, event))) {
-            first = { code: event.code, shiftKey: event.shiftKey, altKey: event.altKey, ctrlKey: event.ctrlKey, metaKey: event.metaKey, at: now() };
+            first = { code: event.code, key: event.key, shiftKey: event.shiftKey, altKey: event.altKey, ctrlKey: event.ctrlKey, metaKey: event.metaKey, at: now() };
             return null;
         }
         return matchShortcut(event, bindings);

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";