entangled-worlds-orbiters-shared 3.3.0 → 4.0.0

package/src/render/{frameBudget.js → frameBudget.ts}

@@ -1,5 +1,5 @@
 /**
- * @file src/render/frameBudget.js
+ * @file src/render/frameBudget.ts
  * @description "Has enough time passed to draw again?" — the whole of a frame cap, kept apart from
  * whatever is being capped so it can be reasoned about and tested on its own.
  *
@@ -15,25 +15,32 @@ export const CAPPED_FPS = 30;
 /** Slack for rAF landing on display ticks — see the file note. */
 export const FRAME_TOLERANCE_MS = 4;
 
+/** A frame gate (`createFrameBudget`). */
+export type FrameBudget = {
+  /** True when `nowMs` is far enough past the last accepted frame; true without a finite time. */
+  shouldRender(nowMs?: number): boolean;
+  /** Forget the last frame. */
+  reset(): void;
+};
+
 /**
  * A frame gate. Not a clock and not a scheduler: it answers one question and remembers the last time
  * the answer was yes.
- *
- * @param {{ fps?: number, toleranceMs?: number }} [options]
- * @returns {{ shouldRender(nowMs: number): boolean, reset(): void }}
  */
-export function createFrameBudget({ fps = CAPPED_FPS, toleranceMs = FRAME_TOLERANCE_MS } = {}) {
+export function createFrameBudget(
+  { fps = CAPPED_FPS, toleranceMs = FRAME_TOLERANCE_MS }: { fps?: number; toleranceMs?: number } = {},
+): FrameBudget {
   const intervalMs = 1000 / (Number.isFinite(fps) && fps > 0 ? fps : CAPPED_FPS);
   const minElapsedMs = Math.max(0, intervalMs - toleranceMs);
-  let lastAtMs = null;
+  let lastAtMs: number | null = null;
 
   return {
     /**
      * True when `nowMs` is far enough past the last accepted frame. Accepting records the time, so
      * the caller must only ask when it intends to act on the answer.
      */
-    shouldRender(nowMs) {
-      if (!Number.isFinite(nowMs)) return true;
+    shouldRender(nowMs?: number) {
+      if (nowMs === undefined || !Number.isFinite(nowMs)) return true;
       if (lastAtMs !== null && nowMs - lastAtMs < minElapsedMs) return false;
       lastAtMs = nowMs;
       return true;

package/src/render/index.ts

@@ -0,0 +1,14 @@
+// Render-host exports
+export { createViewportCompositor } from './viewportCompositor.js';
+export type {
+  ViewportCompositor,
+  ViewportCompositorOptions,
+  RendererProfile,
+  VoiceController,
+  CompositorVoice,
+  CellSource,
+  FrameProbe,
+  ViewportRect,
+} from './viewportCompositor.js';
+export { createFrameBudget, CAPPED_FPS, FRAME_TOLERANCE_MS } from './frameBudget.js';
+export type { FrameBudget } from './frameBudget.js';

package/src/render/{viewportCompositor.js → viewportCompositor.ts}

@@ -1,5 +1,5 @@
 /**
- * @file src/render/viewportCompositor.js
+ * @file src/render/viewportCompositor.ts
  * @description A multi-view render host: ONE `WebGLRenderer`, ONE rAF loop, many cells.
  * Each frame it iterates the registered voices and renders each voice's scene into its own cell via
  * `setViewport`/`setScissor` (three's "multiple views, one renderer"). This replaces the N-canvas
@@ -50,8 +50,60 @@ import { createFrameBudget } from './frameBudget.js';
 
 const GRID_ID = 'multi-orbiter-grid';
 
+/** The renderer settings a host can override (`rendererProfile`, any subset). */
+export type RendererProfile = {
+  antialias: boolean;
+  alpha: boolean;
+  preserveDrawingBuffer: boolean;
+  powerPreference: WebGLPowerPreference;
+  maxDevicePixelRatio: number;
+};
+
+/** CSS px. GL bottom-left origin in fixed-overlay, viewport top-left in per-cell. */
+export type ViewportRect = { x: number; y: number; width: number; height: number };
+
+/** What the compositor calls on a voice's controller (see the host contract in the module doc). */
+export type VoiceController = {
+  renderActive: boolean;
+  renderViewport: (rect: ViewportRect) => void;
+  setViewportSize: (width: number, height: number) => void;
+};
+
+/** One voice as `addVoice` takes it. */
+export type CompositorVoice = { voiceId: string; cell: HTMLElement; controller: VoiceController };
+
+/** An external owner of the cell DOM (`cellSource`). */
+export type CellSource = {
+  acquireCell: (index: number, total: number) => HTMLElement;
+  releaseCell?: (index: number) => void;
+};
+
+/** One registered voice: its cell, its controller, the last size it was told, its cached rect and,
+ *  per-cell only, its presentation canvas. */
+type VoiceState = {
+  cell: HTMLElement;
+  controller: VoiceController;
+  lastW: number;
+  lastH: number;
+  rect: ViewportRect | null;
+  blit: { el: HTMLCanvasElement; ctx: CanvasRenderingContext2D | null } | null;
+};
+
+/** A load meter's watch on the realm's frames (`setFrameProbe`). */
+export type FrameProbe = {
+  everyMs: number;
+  onFrame?: (nowMs: number) => void;
+  onDraw: (workMs: number, calls: number, triangles: number) => void;
+};
+
+/** The vendor-prefixed fullscreen element older Safari still reports; not in the DOM lib. */
+type WebkitDocument = Document & { webkitFullscreenElement?: Element | null };
+
+/** `window` read as a bag of host-named slots, for the opt-in dev handle. */
+type DevHandleWindow = Record<string, { renderer?: unknown } | undefined>;
+
 /** Renderer defaults. Overridable via `rendererProfile`; these values are the historical constants. */
-const DEFAULT_RENDERER_PROFILE = {
+const DEFAULT_RENDERER_PROFILE: RendererProfile = {
   antialias: true,
   alpha: true,
   preserveDrawingBuffer: false,
@@ -64,33 +116,44 @@ const DEFAULT_RENDERER_PROFILE = {
  *  from flashing empty on that frame. */
 const CULL_SLOP_PX = 256;
 
+/** The `createViewportCompositor` options (all optional; see the function). */
+export type ViewportCompositorOptions = {
+  cellSource?: CellSource | null;
+  presentation?: 'fixed-overlay' | 'per-cell';
+  rendererProfile?: Partial<RendererProfile> | null;
+  performanceMode?: boolean;
+  devHandleKey?: string | null;
+};
+
+/** The compositor `createViewportCompositor` returns. */
+export type ViewportCompositor = {
+  renderer: THREE.WebGLRenderer;
+  canvas: HTMLCanvasElement;
+  createCell: (index: number, total: number) => HTMLElement;
+  addVoice: (voice: CompositorVoice) => void;
+  removeVoice: (voiceId: string) => void;
+  renderOnce: () => void;
+  setPerformanceMode: (enabled: boolean) => boolean;
+  /** Watch the realm's frames for a load meter; `null` stops it. */
+  setFrameProbe: (probe: FrameProbe | null) => void;
+  dispose: () => void;
+};
+
 /**
- * @param {object} [opts]
- * @param {{ acquireCell: (index:number, total:number) => HTMLElement, releaseCell?: (index:number) => void } | null} [opts.cellSource]
- *   external owner of the cell DOM. When present, `createCell` delegates to it and the compositor
- *   builds no grid of its own; when absent, the default `⌈√n⌉` grid is used.
- * @param {'fixed-overlay'|'per-cell'} [opts.presentation='fixed-overlay'] how pixels reach the
- *   screen — the displayed fixed canvas (full-screen stage layouts) or a per-cell blit canvas the
- *   DOM positions (cells inside scrolling content). See the module doc.
- * @param {Partial<typeof DEFAULT_RENDERER_PROFILE>} [opts.rendererProfile] renderer construction +
- *   pixel-ratio cap. Omit for the historical defaults.
- * @param {boolean} [opts.performanceMode=false] start with the realm's renderer savings on — pixel
- *   ratio clamped to 1, shadow map off, this loop capped at 30fps. Off by default, and off means the
+ * Options, all optional:
+ * - `cellSource`: external owner of the cell DOM. When present, `createCell` delegates to it and the
+ *   compositor builds no grid of its own; when absent, the default `⌈√n⌉` grid is used.
+ * - `presentation` (default `'fixed-overlay'`): how pixels reach the screen — the displayed fixed
+ *   canvas (full-screen stage layouts) or a per-cell blit canvas the DOM positions (cells inside
+ *   scrolling content). See the module doc.
+ * - `rendererProfile`: renderer construction + pixel-ratio cap. Omit for the historical defaults.
+ * - `performanceMode` (default false): start with the realm's renderer savings on — pixel ratio
+ *   clamped to 1, shadow map off, this loop capped at 30fps. Off by default, and off means the
  *   renderer and the cadence are exactly what they were before this option existed. Toggle it live
  *   with `setPerformanceMode`.
- * @param {string|null} [opts.devHandleKey=null] when set, publish the returned api on
- *   `window[devHandleKey]` so tooling can force a composited frame while rAF is throttled (a hidden
- *   tab during automated checks). Off by default — a library does not name globals for its host.
- * @returns {{
- *   renderer: THREE.WebGLRenderer,
- *   canvas: HTMLCanvasElement,
- *   createCell: (index: number, total: number) => HTMLElement,
- *   addVoice: (voice: { voiceId: string, cell: HTMLElement, controller: object }) => void,
- *   removeVoice: (voiceId: string) => void,
- *   renderOnce: () => void,
- *   setPerformanceMode: (enabled: boolean) => boolean,
- *   dispose: () => void,
- * }}
+ * - `devHandleKey` (default null): when set, publish the returned api on `window[devHandleKey]` so
+ *   tooling can force a composited frame while rAF is throttled (a hidden tab during automated
+ *   checks). Off by default — a library does not name globals for its host.
  */
 export function createViewportCompositor({
   cellSource = null,
@@ -98,7 +161,7 @@ export function createViewportCompositor({
   rendererProfile = null,
   devHandleKey = null,
   performanceMode = false,
-} = {}) {
+}: ViewportCompositorOptions = {}): ViewportCompositor {
   const profile = { ...DEFAULT_RENDERER_PROFILE, ...(rendererProfile || {}) };
   // The realm's renderer and the realm's loop are this module's, and they are the only things a
   // single voice cannot change for itself: pixel ratio, shadow map and frame rate are one per realm,
@@ -110,7 +173,7 @@ export function createViewportCompositor({
   let performanceOn = Boolean(performanceMode);
   // What the realm's shadow map was before performance mode touched it, so turning the mode off puts
   // the host's own choice back rather than asserting a default over it.
-  let baseShadowMapEnabled = null;
+  let baseShadowMapEnabled: boolean | null = null;
   const frameBudget = createFrameBudget();
   const perCell = presentation === 'per-cell';
   // The one WebGL canvas. Fixed-overlay: full-bleed behind the grid, it owns the pixels for ALL
@@ -142,7 +205,8 @@ export function createViewportCompositor({
   /** Re-assert the realm-wide knobs. Called at construction and whenever the mode changes. */
   function applyRealmRendererProfile() {
     applyPixelRatio(renderer, effectiveProfile());
-    renderer.shadowMap.enabled = performanceOn ? false : baseShadowMapEnabled;
+    // Only ever called after construction has read the base value, so it is a boolean here.
+    renderer.shadowMap.enabled = performanceOn ? false : (baseShadowMapEnabled as boolean);
   }
 
   const renderer = createRenderer(canvas, effectiveProfile());
@@ -154,14 +218,14 @@ export function createViewportCompositor({
   /** voiceId → { cell, controller, lastW, lastH, rect, blit } — `rect` is the GL draw rect
    *  (fixed-overlay) or the viewport-relative cull/size box (per-cell); `blit` is the per-cell
    *  presentation canvas + its 2d context (per-cell only). */
-  const voices = new Map();
-  let grid = null;
-  let raf = null;
+  const voices = new Map<string, VoiceState>();
+  let grid: HTMLDivElement | null = null;
+  let raf: number | null = null;
   let disposed = false;
   // A load meter's watch on the realm's frames (`setFrameProbe`): null when nobody is watching.
-  let frameProbe = null;
+  let frameProbe: FrameProbe | null = null;
   let frameProbeAt = 0;
-  let probePixel = null;
+  let probePixel: Uint8Array | null = null;
   let lastCanvasW = 0;
   let lastCanvasH = 0;
   let viewportH = 0; // per-cell cull band (CSS px), refreshed with the rects
@@ -200,13 +264,13 @@ export function createViewportCompositor({
   // compositor the single owner of its canvas. Per-cell: the cell's own canvas rides into the top
   // layer with it — no reparenting, only the solo-render (and the buffer grows to the cell's new
   // size through the normal resize path).
-  let fullscreenVoiceId = null; // voiceId rendered solo full-bleed while fullscreen, else null
-  let canvasHome = null; // { parent, next, cssText } to restore the canvas to its realm home on exit
+  let fullscreenVoiceId: string | null = null; // voiceId rendered solo full-bleed while fullscreen, else null
+  let canvasHome: { parent: ParentNode | null; next: ChildNode | null; cssText: string } | null = null; // { parent, next, cssText } to restore the canvas to its realm home on exit
   const fullscreenElement = () =>
     (typeof document !== 'undefined'
-      ? document.fullscreenElement || document.webkitFullscreenElement || null
+      ? document.fullscreenElement || (document as WebkitDocument).webkitFullscreenElement || null
       : null);
-  const voiceIdForCell = (el) => {
+  const voiceIdForCell = (el: Element | null) => {
     if (!el) return null;
     for (const [id, voice] of voices) if (voice.cell === el) return id;
     return null;
@@ -237,7 +301,8 @@ export function createViewportCompositor({
       // Direct switch from another fullscreen cell (no intervening exit): restore FIRST so canvasHome
       // captures the true realm home, not the previous cell / already-mutated style.
       if (fullscreenVoiceId) restoreCanvasHome();
-      const cell = voices.get(enteringId)?.cell; // enteringId came from a cell match, so this is set
+      // enteringId came from a cell match, so this is set.
+      const cell = voices.get(enteringId)?.cell as HTMLElement;
       // Remember where the canvas belongs, then move it into the fullscreened cell. z-index:0 keeps
       // it BEHIND the cell's pointer-events:none chrome host (a positioned, z-auto later sibling), so
       // the buttons still show; it stays position:fixed;inset:0 to fill the now-full-viewport cell.
@@ -301,7 +366,7 @@ export function createViewportCompositor({
   }
 
   /** Create-or-get the CSS grid that lays the cells out (square-ish: ⌈√n⌉ columns). */
-  function ensureGrid(total) {
+  function ensureGrid(total: number) {
     if (grid) return grid;
     const cols = Math.ceil(Math.sqrt(total));
     const rows = Math.ceil(total / cols);
@@ -323,7 +388,7 @@ export function createViewportCompositor({
     return grid;
   }
 
-  function createCell(index, total) {
+  function createCell(index: number, total: number) {
     // Collection mode: the slot layout owns the cell DOM (a resizable slot). Borrow its element as this
     // voice's viewport rect + GUI mount — the compositor builds no grid of its own.
     if (cellSource) {
@@ -344,7 +409,7 @@ export function createViewportCompositor({
    *  positions it (absolute, inset:0), so it scrolls with the page on the compositor thread — the
    *  whole point of the mode. First child + z-index:0 keeps it under the cell's chrome; pointer
    *  events pass through to the cell, which owns the voice's camera input binding. */
-  function createBlitCanvas(cell) {
+  function createBlitCanvas(cell: HTMLElement) {
     // An absolutely-positioned child anchors to the nearest positioned ancestor — make sure that's
     // the cell itself, not something above it.
     if (typeof getComputedStyle === 'function' && getComputedStyle(cell).position === 'static') {
@@ -359,7 +424,7 @@ export function createViewportCompositor({
     return { el, ctx };
   }
 
-  function addVoice({ voiceId, cell, controller }) {
+  function addVoice({ voiceId, cell, controller }: CompositorVoice) {
     if (!voiceId || !cell || !controller) return;
     const blit = perCell ? createBlitCanvas(cell) : null;
     voices.set(voiceId, { cell, controller, lastW: 0, lastH: 0, rect: null, blit });
@@ -367,7 +432,7 @@ export function createViewportCompositor({
     markRectsDirty();
   }
 
-  function removeVoice(voiceId) {
+  function removeVoice(voiceId: string) {
     const voice = voices.get(voiceId);
     if (!voice) return;
     // If this voice is fullscreen its cell hosts the shared canvas — restore the canvas to its
@@ -509,7 +574,7 @@ export function createViewportCompositor({
     }
   }
 
-  function tick(nowMs) {
+  function tick(nowMs: number) {
     if (disposed) return;
     raf = requestAnimationFrame(tick);
     // The cap belongs HERE, to the realm's own loop — never to a voice declining to draw inside
@@ -566,22 +631,18 @@ export function createViewportCompositor({
    * every `everyMs` timed to the end of its drawing (`onDraw(workMs, calls, triangles)`, every cell
    * together). Only the timed frame waits for the graphics chip; every other frame is untouched.
    * `null` stops it.
-   *
-   * @param {{ everyMs: number, onFrame?: (nowMs: number) => void, onDraw: (workMs: number, calls: number, triangles: number) => void } | null} probe
    */
-  function setFrameProbe(probe) {
+  function setFrameProbe(probe: FrameProbe | null) {
     frameProbe = probe ?? null;
     frameProbeAt = 0;
   }
 
   /**
    * Turn the realm's performance mode on or off, live. Clamps the realm pixel ratio to 1, turns the
-   * shadow map off and caps this loop at 30fps while on; puts all three back when off.
-   *
-   * @param {boolean} enabled
-   * @returns {boolean} whether the mode actually changed
+   * shadow map off and caps this loop at 30fps while on; puts all three back when off. Returns
+   * whether the mode actually changed.
    */
-  function setPerformanceMode(enabled) {
+  function setPerformanceMode(enabled: boolean) {
     const next = Boolean(enabled);
     if (disposed || next === performanceOn) return false;
     performanceOn = next;
@@ -610,8 +671,9 @@ export function createViewportCompositor({
     restoreCanvasHome();
     for (const voice of voices.values()) voice.blit?.el.remove();
     voices.clear();
-    if (typeof window !== 'undefined' && devHandleKey && window[devHandleKey]?.renderer === renderer) {
-      delete window[devHandleKey];
+    if (typeof window !== 'undefined' && devHandleKey) {
+      const devWindow = window as unknown as DevHandleWindow;
+      if (devWindow[devHandleKey]?.renderer === renderer) delete devWindow[devHandleKey];
     }
     renderer.dispose();
     grid?.remove();
@@ -621,7 +683,7 @@ export function createViewportCompositor({
 
   raf = requestAnimationFrame(tick);
 
-  const api = {
+  const api: ViewportCompositor = {
     renderer,
     canvas,
     createCell,
@@ -635,12 +697,12 @@ export function createViewportCompositor({
   // Dev handle: lets tooling force a composited frame when rAF is throttled (e.g. a hidden/background
   // tab during automated checks). The HOST names it — this module invents no global of its own.
   if (devHandleKey && typeof window !== 'undefined') {
-    window[devHandleKey] = api;
+    (window as unknown as DevHandleWindow)[devHandleKey] = api;
   }
   return api;
 }
 
-function createRenderer(canvas, profile) {
+function createRenderer(canvas: HTMLCanvasElement, profile: RendererProfile) {
   const renderer = new THREE.WebGLRenderer({
     canvas,
     antialias: profile.antialias,
@@ -654,7 +716,7 @@ function createRenderer(canvas, profile) {
   return renderer;
 }
 
-function applyPixelRatio(renderer, profile) {
+function applyPixelRatio(renderer: THREE.WebGLRenderer, profile: RendererProfile) {
   const dpr =
     typeof window !== 'undefined' && Number.isFinite(window.devicePixelRatio) ? window.devicePixelRatio : 1;
   renderer.setPixelRatio(Math.min(dpr, profile.maxDevicePixelRatio));

package/src/studio/headerBroadcast.ts

@@ -15,7 +15,20 @@ type Setter = (arg: never) => void
 /** A header sink implements any subset of the setters. */
 export type HeaderSinkOf<K extends string> = Partial<Record<K, Setter>>
 
-export type HeaderBroadcast<Shell extends object, K extends string> = Shell & {
+/** The setter the wrapper puts on `P`: the shell's own one-argument signature, or any argument. */
+type ForwardingSetter<Shell, P extends string> = P extends keyof Shell
+  ? Exclude<Shell[P], undefined> extends (arg: infer A) => unknown
+    ? (arg: A) => void
+    : (arg: unknown) => void
+  : (arg: unknown) => void
+
+/**
+ * The wrapped shell: the shell's own members, a forwarding setter (always there) for every header
+ * key, including keys the shell lacks (they reach the sink only), and `replayInto`. Header keys
+ * typed only as `string` name no setter.
+ */
+export type HeaderBroadcast<Shell extends object, K extends string> = Shell &
+  (string extends K ? unknown : { [P in K]-?: ForwardingSetter<Shell, P> }) & {
   /** Push the last value of every header setter into a freshly registered sink. */
   replayInto(sink: HeaderSinkOf<K> | null | undefined): void
 }

package/src/studio/hostTransport.ts

@@ -8,7 +8,8 @@
 // The app-specific half — what a draft looks like, which API saves it, which message types exist
 // — stays in each app and drives an AutosaveSession.
 
-interface WindowLike {
+/** The part of a window the host transport reads: its origin, its parent and `postMessage`. */
+export interface WindowLike {
   location: { origin: string }
   parent: WindowLike | null
   postMessage(message: unknown, targetOrigin: string, transfer?: Transferable[]): void

package/src/studio/index.ts

@@ -27,4 +27,4 @@ export {
   type StatusSink,
   type StatusShowOptions,
 } from './statusChannel.js'
-export { isTrustedHostOrigin, isEmbedded, postToHost } from './hostTransport.js'
+export { isTrustedHostOrigin, isEmbedded, postToHost, type WindowLike } from './hostTransport.js'

package/src/utils/dispose.ts

@@ -0,0 +1,47 @@
+// Three.js GPU resources are not garbage-collected — geometries, materials, and
+// the textures hanging off materials must be disposed explicitly on teardown, or
+// the consuming app leaks VRAM on every world swap / moon rebuild.
+import type * as THREE from 'three';
+
+/** Anything with a `dispose()` method, as a material's fields are probed for. */
+type MaybeDisposable = { dispose?: unknown } | null | undefined;
+
+/** Disposes one material or an array of them, and every disposable value hanging off each. */
+export function disposeMaterial(material: THREE.Material | readonly (THREE.Material | null | undefined)[] | null | undefined): void {
+  if (!material) return;
+  // A mesh can carry a single material or an array (multi-material meshes, some GLB).
+  const materials: readonly (THREE.Material | null | undefined)[] = Array.isArray(material) ? material : [material];
+  for (const mat of materials) {
+    if (!mat) continue;
+    // Free the textures (and any other disposable values) hanging off the material…
+    for (const key in mat) {
+      const val = (mat as unknown as Record<string, MaybeDisposable>)[key];
+      if (val && typeof val.dispose === 'function') {
+        try { (val as { dispose(): void }).dispose(); } catch {}
+      }
+    }
+    // …then free the material's own GPU program. Without this the shader program
+    // leaks even though its textures were released. `dispose` is a prototype method,
+    // so the loop above never reaches it — no double-dispose.
+    if (typeof mat.dispose === 'function') {
+      try { mat.dispose(); } catch {}
+    }
+  }
+}
+
+/** Disposes the geometry and materials of every mesh under `obj`, then detaches it from its parent. */
+export function disposeObject3D(obj: THREE.Object3D | null | undefined): void {
+  if (!obj) return;
+  const root = obj;
+  root.traverse((child) => {
+    if ((child as THREE.Mesh).isMesh) {
+      const mesh = child as THREE.Mesh;
+      if (mesh.geometry) mesh.geometry.dispose();
+      disposeMaterial(mesh.material);
+      // An InstancedMesh also owns `instanceMatrix` / `instanceColor` GPU buffers, which hang off the
+      // mesh rather than the (shared) geometry — only its own dispose() frees them.
+      if ((child as THREE.InstancedMesh).isInstancedMesh) (child as THREE.InstancedMesh).dispose();
+    }
+  });
+  if (root.parent) root.parent.remove(root);
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+// Utilities exports
+export { ensureStandardMaterial, applyFlagsToMaterial } from './materials.js';
+export type { MaterialFlags } from './materials.js';
+export { disposeObject3D } from './dispose.js';

package/src/utils/materials.ts

@@ -0,0 +1,44 @@
+import * as THREE from 'three';
+
+/** The material fields `applyFlagsToMaterial` touches; `transmission` exists on physical materials only. */
+type FlaggableMaterial = THREE.Material & { wireframe?: boolean; transmission?: number };
+
+/** The flags `applyFlagsToMaterial` reads; other fields are ignored. */
+export interface MaterialFlags {
+  forceOpaque?: boolean;
+  wireframe?: boolean;
+}
+
+/** Gives a mesh a MeshStandardMaterial (keeping its map) unless it has one; anything that is not a mesh is left alone. */
+export function ensureStandardMaterial(mesh: THREE.Object3D | null | undefined): void {
+  if (!mesh || !(mesh as THREE.Mesh).isMesh) return;
+  const m = mesh as THREE.Mesh;
+  const mat = m.material as THREE.Material & { map?: THREE.Texture | null };
+  if (mat && !(mat instanceof THREE.MeshStandardMaterial)) {
+    m.material = new THREE.MeshStandardMaterial({
+      map: mat.map || null,
+      metalness: 0.3,
+      roughness: 0.7,
+    });
+  }
+}
+
+/** Applies `flags` to one material (not an array); nothing happens without a material. */
+export function applyFlagsToMaterial(material: THREE.Material | null | undefined, flags: MaterialFlags = {}): void {
+  if (!material) return;
+  const mat = material as FlaggableMaterial;
+  const { forceOpaque, wireframe } = flags;
+  if (forceOpaque) {
+    if (mat.transparent || (mat.transmission && mat.transmission > 0)) {
+      mat.transparent = false;
+      mat.opacity = 1;
+      if ('transmission' in mat) mat.transmission = 0;
+      mat.alphaTest = 0;
+      mat.needsUpdate = true;
+    }
+  }
+  if (wireframe) {
+    mat.wireframe = true;
+    mat.needsUpdate = true;
+  }
+}

package/src/world/{cloudShell.js → cloudShell.ts}

@@ -8,6 +8,12 @@ async function makeTextureMaterial({
   textureUrl,
   speed = 0.015,
   renderer = null,
+}: {
+  color?: number;
+  opacity?: number;
+  textureUrl?: string | undefined;
+  speed?: number;
+  renderer?: THREE.WebGLRenderer | null;
 } = {}) {
   // Diffuse-only (Lambert): the star's key light costs no specular pass.
   const mat = new THREE.MeshLambertMaterial({
@@ -41,7 +47,7 @@ async function makeTextureMaterial({
   // Randomize wind direction per instance (0..360)
   const dirRad = (Math.random() * 360 * Math.PI) / 180;
   const wind = new THREE.Vector2(Math.cos(dirRad), Math.sin(dirRad)).multiplyScalar(speed);
-  mat.userData.update = (timeSec) => {
+  mat.userData.update = (timeSec: number) => {
     const t = mat.alphaMap;
     if (t) {
       t.offset.x = wind.x * timeSec;
@@ -54,17 +60,8 @@ async function makeTextureMaterial({
 }
 
 /**
- * @param {object} [opts]
- * @param {import('three').BufferGeometry} [opts.baseGeometry] cloned for the shell; when absent a
- *   sphere is built from `baseRadius` and the segment counts.
- * @param {number} [opts.baseRadius=0.5]
- * @param {number} [opts.widthSegments=64]
- * @param {number} [opts.heightSegments=64]
- * @param {string} [opts.textureUrl]
- * @param {number} [opts.color=0xffffff]
- * @param {number} [opts.opacity=0.6]
- * @param {number} [opts.speed=0.015]
- * @param {import('three').WebGLRenderer | null} [opts.renderer]
+ * `baseGeometry` is cloned for the shell; when absent a sphere is built from `baseRadius` (0.5) and
+ * the segment counts (64 × 64). Defaults: `color` 0xffffff, `opacity` 0.6, `speed` 0.015.
  */
 export async function createCloudShell({
   baseGeometry,
@@ -76,6 +73,16 @@ export async function createCloudShell({
   opacity = 0.6,
   speed = 0.015,
   renderer = null,
+}: {
+  baseGeometry?: THREE.BufferGeometry | undefined;
+  baseRadius?: number | undefined;
+  widthSegments?: number | undefined;
+  heightSegments?: number | undefined;
+  textureUrl?: string | undefined;
+  color?: number | undefined;
+  opacity?: number | undefined;
+  speed?: number | undefined;
+  renderer?: THREE.WebGLRenderer | null | undefined;
 } = {}) {
   const geom = baseGeometry
     ? baseGeometry.clone()

package/src/world/index.ts

@@ -0,0 +1,7 @@
+// World system exports
+export { WorldManager } from './worldManager.js';
+export { makeSphere, EARTH_RADIUS_UNITS } from './worldTexture.js';
+export { makeNormalSphere } from './worldNormal.js';
+export { makeGLB } from './worldGLB.js';
+export { createCloudShell } from './cloudShell.js';
+export type { WorldCreator, WorldModeArgs } from './worldManager.js';

package/src/world/worldGLB.ts

@@ -0,0 +1,41 @@
+import type * as THREE from 'three';
+import { loadGLB } from '../loaders/glbLoader.js';
+
+/**
+ * `emissiveIntensity`: textured self-glow (1 = old flat-lit look; ≈0.15 under a star light).
+ * - `modelUrl`: REQUIRED; throws without it.
+ * - `flags`: material flags (`forceOpaque`, `wireframe`).
+ * - `retries` (3), `withCredentials` (false).
+ * - `renderer`: REQUIRED at runtime (`loadGLB` throws without one); nullable here because
+ *   `WorldManager` threads its own, which may be null.
+ */
+export async function makeGLB(
+  {
+    modelUrl,
+    flags,
+    retries = 3,
+    withCredentials = false,
+    renderer,
+    emissiveIntensity,
+  }: {
+    modelUrl: string;
+    flags?: object | undefined;
+    retries?: number | undefined;
+    withCredentials?: boolean | undefined;
+    renderer?: THREE.WebGLRenderer | null | undefined;
+    emissiveIntensity?: number | undefined;
+    // Optional as a whole, as the JSDoc had it: without them the `modelUrl` guard below throws.
+  } = {} as { modelUrl: string },
+  // What `loadGLB` resolves to: the loaded scene (`undefined` only when `retries` is 0 or less).
+): Promise<THREE.Group | undefined> {
+  if (!modelUrl) throw new Error('modelUrl is required');
+  // A null or missing renderer makes `loadGLB` throw, as it always did (see above).
+  const obj = await loadGLB(modelUrl, {
+    retries,
+    applyFlags: flags,
+    withCredentials,
+    renderer: renderer as THREE.WebGLRenderer,
+    emissiveIntensity,
+  });
+  return obj;
+}