entangled-worlds-orbiters-shared 4.2.0 → 5.1.0

package/src/shortcuts/format.ts

@@ -1,7 +1,7 @@
 // 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, type Chord } from './chord.js'
+import { isModifierCode, parseChord, typedKey, type Chord } from './chord.js'
 
 /** Apple keyboards show modifiers as symbols, and their command key is ⌘ (`Mod`); others write words and Ctrl. */
 export type ShortcutPlatform = 'apple' | 'other'
@@ -15,8 +15,8 @@ export 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>
 
@@ -32,7 +32,8 @@ const NAMED: Readonly<Record<string, string>> = {
 
 /** What a key place is called on a keyboard: `KeyQ` → `Q`, `Digit1` → `1`, `Numpad4` → `Num 4`. */
 export function keyLabel(code: string, layout?: KeyLayout): string {
-  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)) return code.slice(3)
   if (/^Digit\d$/.test(code)) return code.slice(5)
@@ -40,6 +41,12 @@ export function keyLabel(code: string, layout?: KeyLayout): string {
   return NAMED[code] ?? code
 }
 
+/** What a US keyboard types with Shift at each punctuation key. */
+const SHIFTED: Readonly<Record<string, string>> = {
+  Minus: '_', Equal: '+', BracketLeft: '{', BracketRight: '}', Backslash: '|', Semicolon: ':', Quote: '"',
+  Backquote: '~', Comma: '<', Period: '>', Slash: '?',
+}
+
 const SYMBOLS = { ctrl: '⌃', alt: '⌥', shift: '⇧', meta: '⌘' } as const
 const WORDS = { ctrl: 'Ctrl', alt: 'Alt', shift: 'Shift', meta: 'Meta' } as const
 
@@ -64,10 +71,14 @@ export function chordParts(keys: string, platform: ShortcutPlatform = shortcutPl
   const parts: string[] = []
   if (ctrl) parts.push(names.ctrl)
   if (held(chord.alt)) parts.push(platform === 'apple' ? names.alt : 'Alt')
-  if (held(chord.shift)) parts.push(names.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
 }
 
@@ -82,24 +93,40 @@ export function formatChord(keys: string, platform: ShortcutPlatform = shortcutP
 
 /**
  * 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: { code: string; shiftKey: boolean; altKey: boolean; ctrlKey: boolean; metaKey: boolean },
+  event: { code: string; key?: string; shiftKey: boolean; altKey: boolean; ctrlKey: boolean; metaKey: boolean },
   platform: ShortcutPlatform = shortcutPlatform(),
 ): string | null {
   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: string[] = []
   // ⌘ (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) parts.push('Ctrl', 'Meta')
-  else if (platform === 'apple' ? event.metaKey : event.ctrlKey) parts.push('Mod')
-  else if (event.ctrlKey) parts.push('Ctrl')
-  else if (event.metaKey) parts.push('Meta')
-  if (event.altKey) parts.push('Alt')
-  if (event.shiftKey) parts.push('Shift')
-  parts.push(event.code)
+  if (press.ctrlKey && press.metaKey) parts.push('Ctrl', 'Meta')
+  else if (platform === 'apple' ? press.metaKey : press.ctrlKey) parts.push('Mod')
+  else if (press.ctrlKey) parts.push('Ctrl')
+  else if (press.metaKey) parts.push('Meta')
+  if (press.altKey) parts.push('Alt')
+  if (press.shiftKey) parts.push('Shift')
+  parts.push(typed?.code ?? event.code)
   const keys = parts.join('+')
   return parseChord(keys) ? keys : null
 }

package/src/shortcuts/index.ts

@@ -1,18 +1,23 @@
-// Keyboard shortcuts, one system for every app: each app's catalogue of actions (id, section, label,
-// default keys, scope) 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.
+// 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 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,
   type Chord,
   type ModifierRule,
   type ModifierState,
+  type ChordMatch,
+  type ChordPress,
 } from './chord.js'
 export {
   matchShortcut,
@@ -24,21 +29,11 @@ export {
   isKeyClaimed,
   isTypingTarget,
   type ShortcutAction,
+  type ShortcutNames,
   type ShortcutBindings,
   type ShortcutOverrides,
   type ShortcutEvent,
 } from './match.js'
-export {
-  ORBITERS_PLAY_SHORTCUTS,
-  ORBITERS_STUDIO_SHORTCUTS,
-  ORBITERS_PLAY_SECTION,
-  ORBITERS_STUDIO_SECTION,
-  ORBITERS_KEYBOARD_SURFACE_KEYS,
-  ORBITERS_COMMAND_GROUPS,
-  ORBITERS_PLAY_SHEET,
-  type OrbitersShortcut,
-  type OrbitersShortcutScope,
-} from './orbiters.js'
 export {
   shortcutPlatform,
   keyLabel,
@@ -50,20 +45,28 @@ export {
   type ShortcutPlatform,
   type KeyLayout,
 } from './format.js'
-export { SHORTCUT_SECTIONS, SHORTCUT_APPS, type ShortcutSection, type ShortcutAppId } from './sections.js'
-export { SITE_SHORTCUTS, SITE_SECTION, type SiteShortcut } from './site.js'
 export {
-  EW_STUDIO_SHORTCUTS,
-  EW_PLAYER_SHORTCUTS,
-  EW_STUDIO_SECTION,
-  EW_PLAYER_SECTION,
-  EW_STUDIO_COMMAND_GROUPS,
-  type EntangledWorldsShortcut,
-} from './entangledWorlds.js'
-export { shortcutLabel, shortcutSectionLabel, shortcutName } from './labels.js'
+  EMPTY_CATALOGUE,
+  parseCatalogue,
+  localName,
+  localAppName,
+  localPartName,
+  shortcutApps,
+  sectionActions,
+  findSection,
+  type ShortcutCatalogue,
+  type ShortcutSection,
+  type ShortcutNamed,
+  type ShortcutSheetColumn,
+  type ShortcutSheetRow,
+} from './catalogue.js'
 export {
-  createShortcutOverridesSource,
+  createShortcutSource,
+  localShortcutCatalogueStore,
+  CATALOGUE_STORAGE_KEY,
   parseOverrides,
-  type ShortcutOverridesSource,
+  type ShortcutCatalogueStore,
+  type ShortcutSource,
   type ReadAccountSettings,
-} from './overrides.js'
+  type ReadShortcutCatalogue,
+} from './source.js'

package/src/shortcuts/match.ts

@@ -2,16 +2,16 @@
 // 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, type Chord, type ModifierState } from './chord.js'
+import { chordMatch, chordMatches, isCommandChord, isModifierCode, keysOverlap, parseChord, parseKeys, type Chord, type ModifierState } from './chord.js'
 
-/** One thing a key can do, as an app's catalogue declares it. */
+/** One thing a key can do, as the shortcut catalogue (served by the backend) lists it. */
 export interface ShortcutAction<Scope extends string = string> {
   /** `<app>.<area>.<action>`, e.g. `orbiters.play.panel.jamming`: the key a person's override is stored under. */
   readonly id: string
-  /** The group it is shown in, one per app surface (`orbiters-play`). Keys clash only inside a section. */
-  readonly section: string
-  /** What it does, in sentence case. */
+  /** What it does, in sentence case, in English. */
   readonly label: string
+  /** Its name in other languages, by locale (`{ es: '…' }`); see `localName`. */
+  readonly names?: ShortcutNames
   /** The keys it has until the person changes them (chord strings, see `chord.ts`). */
   readonly defaultKeys: readonly string[]
   /** What it acts on, in the app's own terms (Orbiters: one deck, or this machine). */
@@ -20,14 +20,21 @@ export interface ShortcutAction<Scope extends string = string> {
   readonly group?: string
   /** `false`: a key only, never a command to pick from a list (a key held down, the menu itself). */
   readonly command?: boolean
+  /** A site action: the page it opens (`{username}` stands for the signed-in person's). */
+  readonly href?: string
+  /** It needs someone signed in. */
+  readonly signedIn?: boolean
 }
 
+/** A name in other languages than English, by locale (`es`). */
+export type ShortcutNames = Readonly<Record<string, string>>
+
 /** The keys of each action, in the order they are tried: the first action a press matches is the one. */
 export type ShortcutBindings = Iterable<readonly [actionId: string, keys: readonly string[]]>
 
 /**
  * A person's changes, as their settings store them: an action's own keys (`[]` = no key). An action
- * left out keeps its defaults, so a default changed in code reaches everyone who never touched it.
+ * left out keeps its defaults, so a default changed in the catalogue reaches everyone who never touched it.
  */
 export type ShortcutOverrides = ReadonlyArray<{ readonly id: string; readonly keys: readonly string[] }>
 
@@ -134,20 +141,25 @@ function readsCharacters(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 function matchShortcut(event: ShortcutEvent, bindings: ShortcutBindings): string | null {
   if (!event.code || isTypingTarget(event.target) || isKeyClaimed(event)) return null
   const characters = readsCharacters(event.target)
+  let byPlace: { id: string; command: boolean } | null = null
   for (const [actionId, keys] of bindings) {
     for (const key of keys) {
       const chord = parseChord(key)
-      if (!chord || !chordMatches(chord, event.code, event)) continue
-      if (characters && !isCommandChord(chord)) return null
-      return actionId
+      const how = chord && chordMatch(chord, event)
+      if (!chord || !how) continue
+      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
 }
 
 // ---------------------------------------------------------------------------------------------
@@ -173,7 +185,7 @@ function sequences(bindings: ShortcutBindings): Array<readonly [string, Chord[]]
  * nothing; any other key, a typed one or a wait past `waitMs` forgets it.
  */
 export function createShortcutMatcher(waitMs: number = SEQUENCE_WAIT_MS, now: () => number = Date.now) {
-  let first: (ModifierState & { code: string; at: number }) | null = null
+  let first: (ModifierState & { code: string; key: string; at: number }) | null = null
   return function match(event: ShortcutEvent, bindings: ShortcutBindings): string | null {
     if (event.code && isModifierCode(event.code)) return null
     const pending = first && now() - first.at <= waitMs ? first : null
@@ -187,7 +199,7 @@ export function createShortcutMatcher(waitMs: number = SEQUENCE_WAIT_MS, now: ()
         if (chordMatches(one, pending.code, pending) && chordMatches(two, event.code, event)) 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/src/shortcuts/source.ts

@@ -0,0 +1,204 @@
+// 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, type ShortcutCatalogue } from './catalogue.js'
+import { resolveBindings, 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 function parseOverrides(value: unknown): ShortcutOverrides | null {
+  if (!Array.isArray(value)) return null
+  return value.filter(
+    (entry): entry is { id: string; keys: string[] } =>
+      !!entry && typeof entry.id === 'string' && Array.isArray(entry.keys) && entry.keys.every((k: unknown) => typeof k === 'string'),
+  )
+}
+
+/**
+ * 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 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(): ShortcutCatalogueStore | null {
+  const storage = (globalThis as { localStorage?: Storage }).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<T>(read: (fresh: boolean) => Promise<T | undefined>, apply: (value: T) => void) {
+  let latest = 0
+  let applied = 0
+  return async (fresh: boolean) => {
+    const ticket = ++latest
+    let value: T | undefined
+    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(),
+}: {
+  readCatalogue: ReadShortcutCatalogue
+  readAccount: ReadAccountSettings
+  /** Where the last catalogue read is kept (this browser's localStorage by default; `null`: nowhere). */
+  store?: ShortcutCatalogueStore | null
+}): ShortcutSource {
+  let catalogue: ShortcutCatalogue = (store && parseCatalogue(store.load())) || EMPTY_CATALOGUE
+  let overrides: ShortcutOverrides = []
+  let resolved = new WeakMap<readonly ShortcutAction[], Map<string, readonly string[]>>()
+  let lastRefreshAt = -Infinity
+  let bound = false
+  const listeners = new Set<() => void>()
+
+  const changed = () => {
+    resolved = new WeakMap()
+    listeners.forEach((listener) => listener())
+  }
+  const applyOverrides = (next: ShortcutOverrides) => {
+    if (JSON.stringify(next) === JSON.stringify(overrides)) return
+    overrides = next
+    changed()
+  }
+  const applyCatalogue = (next: ShortcutCatalogue) => {
+    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 }: { fresh?: boolean } = {}) => {
+    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 as unknown as {
+        addEventListener?: (type: string, fn: () => void) => void
+        document?: { visibilityState?: string; addEventListener?: (type: string, fn: () => void) => void }
+      }
+      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/src/sky/geometry.ts

@@ -0,0 +1,99 @@
+// 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';
+import type { WorldSky } from './worldSkyFile.js';
+
+const INT16 = 32767;
+
+/** 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 function equatorial(raDeg: number, decDeg: number, out = new THREE.Vector3()): 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: number, tiltDeg: number): BandFrame {
+  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(): BandFrame {
+  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: { seed: number; count: number; band: number; frame: BandFrame; world?: WorldSky | null }): THREE.BufferGeometry {
+  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: WorldSky): THREE.BufferGeometry {
+  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/src/sky/index.ts

@@ -0,0 +1,16 @@
+// ./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 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';