entangled-worlds-orbiters-shared 2.6.0 → 2.8.0

package/dist/clock/track-metadata.d.ts

@@ -14,6 +14,16 @@ export interface SyncSettingsLike {
         sourceTimeSec?: unknown;
     } | null | undefined> | null;
     gridStartTimeSec?: unknown;
+    /** Whether this track time-stretches onto the grid. A BOOLEAN, so `false` is an answer rather than
+     *  an absence — see `resolveWarpEnabledFromTrackData`. */
+    warpEnabled?: unknown;
+    /** Whether this track plays looped. Same boolean rule as `warpEnabled`, and the same three states:
+     *  on, off, and nobody-said — see `resolveLoopEnabledFromTrackData`. */
+    loopEnabled?: unknown;
+    /** The loop region in SECONDS (storage's time unit; the audio engine works in ms and converts at
+     *  its edge). Only ever meaningful as a pair — see `resolveLoopRangeSecFromTrackData`. */
+    loopStartSec?: unknown;
+    loopEndSec?: unknown;
 }
 export interface TrackMetadataLike {
     trackBpm?: unknown;
@@ -71,3 +81,33 @@ export declare function resolveTrackBpmFromTrackData(trackData?: TrackDataLike |
  * Returns null when nothing resolves (consumers default to 0).
  */
 export declare function resolvePrimaryGridMarkerTimeSecFromTrackData(trackData?: TrackDataLike | null): number | null;
+/**
+ * Resolve whether this track should warp (time-stretch onto the grid) for the viewer.
+ *
+ * Returns null when nothing anywhere expressed a preference. Null means "no opinion", NOT "off" —
+ * the caller supplies its own default, because only the caller knows its runtime constraints (in
+ * orbiters, a deck with no tempo cannot warp at all, whatever was saved).
+ */
+export declare function resolveWarpEnabledFromTrackData(trackData?: TrackDataLike | null): boolean | null;
+/**
+ * Resolve whether this track should play looped for the viewer.
+ *
+ * Same three states as warp — on, off, nobody-said — but no smart default anywhere behind it: the
+ * server stops at the owner's setting, so null here is genuinely common and simply means the caller
+ * keeps whatever looping default it already had.
+ */
+export declare function resolveLoopEnabledFromTrackData(trackData?: TrackDataLike | null): boolean | null;
+/**
+ * Resolve the saved loop region, in seconds, or null when no layer holds a complete one.
+ *
+ * Resolved as a PAIR, never edge by edge: a start borrowed from one layer and an end from another
+ * describes a loop nobody set, and can invert. `start` of 0 is a real value, so the guard is a
+ * finiteness test rather than a truthiness one.
+ *
+ * The caller must still clamp this against the audio's real duration before using it — a region
+ * saved against an earlier version of the track can outlive the audio it was drawn on.
+ */
+export declare function resolveLoopRangeSecFromTrackData(trackData?: TrackDataLike | null): {
+    startSec: number;
+    endSec: number;
+} | null;

package/dist/clock/track-metadata.js

@@ -20,6 +20,22 @@ function firstResolvedValue(candidates, parser) {
     }
     return null;
 }
+/**
+ * The first candidate that is an actual boolean, or null when none of them is.
+ *
+ * Deliberately separate from `firstResolvedValue`: that one folds "absent" and "invalid" together
+ * and returns a number, which is exactly the wrong shape here. A warp preference has THREE states —
+ * on, off, and nobody-said — and `false` is the middle one, not the last. Any `||`, any truthiness
+ * test, any `?? ` against a default collapses off into nobody-said and loses the user's choice.
+ */
+function firstBoolean(candidates) {
+    for (const candidate of candidates) {
+        if (typeof candidate === 'boolean') {
+            return candidate;
+        }
+    }
+    return null;
+}
 /**
  * Resolve the effective track BPM. Precedence (first finite, > 0 wins):
  * owner `trackBpm` → owner `effectiveSettings.sync.trackBpm` → per-user `trackUserSettings.sync.trackBpm`
@@ -64,3 +80,71 @@ export function resolvePrimaryGridMarkerTimeSecFromTrackData(trackData = null) {
         trackData?.metadata?.wrap?.gridStartTimeSec,
     ], toNonNegativeNumber);
 }
+/**
+ * The shared walk behind the boolean preferences below.
+ *
+ * The server already applied the real precedence — the viewer's own saved setting, then the owner's,
+ * then (for warp) a smart default — and publishes the answer at `effectiveSettings.sync`. So that is
+ * read FIRST: it is the resolved value, not a competing opinion. The per-user path below it covers
+ * the shapes where the server has not resolved anything (a raw `trackUserSettings` fetch that has not
+ * been merged into a track payload yet).
+ *
+ * One walk, not one per field: warp and loop differ in what they MEAN, never in where they are found,
+ * and two hand-maintained copies of this list would drift the moment a payload shape changed.
+ */
+function resolveSyncFlagFromTrackData(trackData, field) {
+    return firstBoolean([
+        trackData?.track?.metadata?.effectiveSettings?.sync?.[field],
+        trackData?.release?.metadata?.effectiveSettings?.sync?.[field],
+        trackData?.metadata?.effectiveSettings?.sync?.[field],
+        trackData?.effectiveSettings?.sync?.[field],
+        trackData?.trackUserSettings?.sync?.[field],
+    ]);
+}
+/**
+ * Resolve whether this track should warp (time-stretch onto the grid) for the viewer.
+ *
+ * Returns null when nothing anywhere expressed a preference. Null means "no opinion", NOT "off" —
+ * the caller supplies its own default, because only the caller knows its runtime constraints (in
+ * orbiters, a deck with no tempo cannot warp at all, whatever was saved).
+ */
+export function resolveWarpEnabledFromTrackData(trackData = null) {
+    return resolveSyncFlagFromTrackData(trackData, 'warpEnabled');
+}
+/**
+ * Resolve whether this track should play looped for the viewer.
+ *
+ * Same three states as warp — on, off, nobody-said — but no smart default anywhere behind it: the
+ * server stops at the owner's setting, so null here is genuinely common and simply means the caller
+ * keeps whatever looping default it already had.
+ */
+export function resolveLoopEnabledFromTrackData(trackData = null) {
+    return resolveSyncFlagFromTrackData(trackData, 'loopEnabled');
+}
+/**
+ * Resolve the saved loop region, in seconds, or null when no layer holds a complete one.
+ *
+ * Resolved as a PAIR, never edge by edge: a start borrowed from one layer and an end from another
+ * describes a loop nobody set, and can invert. `start` of 0 is a real value, so the guard is a
+ * finiteness test rather than a truthiness one.
+ *
+ * The caller must still clamp this against the audio's real duration before using it — a region
+ * saved against an earlier version of the track can outlive the audio it was drawn on.
+ */
+export function resolveLoopRangeSecFromTrackData(trackData = null) {
+    const candidates = [
+        trackData?.track?.metadata?.effectiveSettings?.sync,
+        trackData?.release?.metadata?.effectiveSettings?.sync,
+        trackData?.metadata?.effectiveSettings?.sync,
+        trackData?.effectiveSettings?.sync,
+        trackData?.trackUserSettings?.sync,
+    ];
+    for (const candidate of candidates) {
+        const startSec = toNonNegativeNumber(candidate?.loopStartSec);
+        const endSec = toNonNegativeNumber(candidate?.loopEndSec);
+        if (startSec !== null && endSec !== null && endSec > startSec) {
+            return { startSec, endSec };
+        }
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",
@@ -8,7 +8,6 @@
   "exports": {
     ".": "./src/index.js",
     "./world": "./src/world/index.js",
-    "./minimal": "./src/minimal/index.js",
     "./moons": "./src/moons/index.js",
     "./loaders": "./src/loaders/index.js",
     "./render": "./src/render/index.js",
@@ -92,8 +91,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:clock": "node --test --import tsx src/clock/*.test.ts",
     "test:render": "node --test src/render/*.test.js",
-    "test:minimal": "node --test src/minimal/*.test.js",
-    "test": "npm run test:clock && npm run test:render && npm run test:minimal && npm run test:moons",
+    "test": "npm run test:clock && npm run test:render && npm run test:moons",
     "test:moons": "node --test src/moons/*.test.js"
   }
 }

package/src/clock/track-metadata.ts

@@ -18,6 +18,16 @@ export interface SyncSettingsLike {
   primaryGridMarkerTimeSec?: unknown;
   gridMarkers?: ReadonlyArray<{ sourceTimeSec?: unknown } | null | undefined> | null;
   gridStartTimeSec?: unknown;
+  /** Whether this track time-stretches onto the grid. A BOOLEAN, so `false` is an answer rather than
+   *  an absence — see `resolveWarpEnabledFromTrackData`. */
+  warpEnabled?: unknown;
+  /** Whether this track plays looped. Same boolean rule as `warpEnabled`, and the same three states:
+   *  on, off, and nobody-said — see `resolveLoopEnabledFromTrackData`. */
+  loopEnabled?: unknown;
+  /** The loop region in SECONDS (storage's time unit; the audio engine works in ms and converts at
+   *  its edge). Only ever meaningful as a pair — see `resolveLoopRangeSecFromTrackData`. */
+  loopStartSec?: unknown;
+  loopEndSec?: unknown;
 }
 
 export interface TrackMetadataLike {
@@ -72,6 +82,23 @@ function firstResolvedValue(
   return null;
 }
 
+/**
+ * The first candidate that is an actual boolean, or null when none of them is.
+ *
+ * Deliberately separate from `firstResolvedValue`: that one folds "absent" and "invalid" together
+ * and returns a number, which is exactly the wrong shape here. A warp preference has THREE states —
+ * on, off, and nobody-said — and `false` is the middle one, not the last. Any `||`, any truthiness
+ * test, any `?? ` against a default collapses off into nobody-said and loses the user's choice.
+ */
+function firstBoolean(candidates: ReadonlyArray<unknown>): boolean | null {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'boolean') {
+      return candidate;
+    }
+  }
+  return null;
+}
+
 /**
  * Resolve the effective track BPM. Precedence (first finite, > 0 wins):
  * owner `trackBpm` → owner `effectiveSettings.sync.trackBpm` → per-user `trackUserSettings.sync.trackBpm`
@@ -125,3 +152,85 @@ export function resolvePrimaryGridMarkerTimeSecFromTrackData(
     toNonNegativeNumber,
   );
 }
+
+/**
+ * The shared walk behind the boolean preferences below.
+ *
+ * The server already applied the real precedence — the viewer's own saved setting, then the owner's,
+ * then (for warp) a smart default — and publishes the answer at `effectiveSettings.sync`. So that is
+ * read FIRST: it is the resolved value, not a competing opinion. The per-user path below it covers
+ * the shapes where the server has not resolved anything (a raw `trackUserSettings` fetch that has not
+ * been merged into a track payload yet).
+ *
+ * One walk, not one per field: warp and loop differ in what they MEAN, never in where they are found,
+ * and two hand-maintained copies of this list would drift the moment a payload shape changed.
+ */
+function resolveSyncFlagFromTrackData(
+  trackData: TrackDataLike | null,
+  field: 'warpEnabled' | 'loopEnabled',
+): boolean | null {
+  return firstBoolean([
+    trackData?.track?.metadata?.effectiveSettings?.sync?.[field],
+    trackData?.release?.metadata?.effectiveSettings?.sync?.[field],
+    trackData?.metadata?.effectiveSettings?.sync?.[field],
+    trackData?.effectiveSettings?.sync?.[field],
+    trackData?.trackUserSettings?.sync?.[field],
+  ]);
+}
+
+/**
+ * Resolve whether this track should warp (time-stretch onto the grid) for the viewer.
+ *
+ * Returns null when nothing anywhere expressed a preference. Null means "no opinion", NOT "off" —
+ * the caller supplies its own default, because only the caller knows its runtime constraints (in
+ * orbiters, a deck with no tempo cannot warp at all, whatever was saved).
+ */
+export function resolveWarpEnabledFromTrackData(
+  trackData: TrackDataLike | null = null,
+): boolean | null {
+  return resolveSyncFlagFromTrackData(trackData, 'warpEnabled');
+}
+
+/**
+ * Resolve whether this track should play looped for the viewer.
+ *
+ * Same three states as warp — on, off, nobody-said — but no smart default anywhere behind it: the
+ * server stops at the owner's setting, so null here is genuinely common and simply means the caller
+ * keeps whatever looping default it already had.
+ */
+export function resolveLoopEnabledFromTrackData(
+  trackData: TrackDataLike | null = null,
+): boolean | null {
+  return resolveSyncFlagFromTrackData(trackData, 'loopEnabled');
+}
+
+/**
+ * Resolve the saved loop region, in seconds, or null when no layer holds a complete one.
+ *
+ * Resolved as a PAIR, never edge by edge: a start borrowed from one layer and an end from another
+ * describes a loop nobody set, and can invert. `start` of 0 is a real value, so the guard is a
+ * finiteness test rather than a truthiness one.
+ *
+ * The caller must still clamp this against the audio's real duration before using it — a region
+ * saved against an earlier version of the track can outlive the audio it was drawn on.
+ */
+export function resolveLoopRangeSecFromTrackData(
+  trackData: TrackDataLike | null = null,
+): { startSec: number; endSec: number } | null {
+  const candidates: Array<SyncSettingsLike | null | undefined> = [
+    trackData?.track?.metadata?.effectiveSettings?.sync,
+    trackData?.release?.metadata?.effectiveSettings?.sync,
+    trackData?.metadata?.effectiveSettings?.sync,
+    trackData?.effectiveSettings?.sync,
+    trackData?.trackUserSettings?.sync,
+  ];
+
+  for (const candidate of candidates) {
+    const startSec = toNonNegativeNumber(candidate?.loopStartSec);
+    const endSec = toNonNegativeNumber(candidate?.loopEndSec);
+    if (startSec !== null && endSec !== null && endSec > startSec) {
+      return { startSec, endSec };
+    }
+  }
+  return null;
+}

package/src/minimal/index.js

@@ -1,26 +0,0 @@
-/**
- * The minimal ("performance mode") look: one cheap lit sphere, one key light, a weak ambient fill,
- * and nothing else — no texture, no halo, no cloud shell, no skybox.
- *
- * Its own entry point rather than a few more names on `./world`, because both consumers want exactly
- * this and nothing around it: the Orbiters renderer and the Entangled Worlds editor's performance
- * preview. Keeping it separate means importing the look never drags in the texture/GLB/cloud loaders
- * that the look exists to avoid.
- */
-export {
-  createMinimalWorld,
-  resolvePlanetColor,
-  MINIMAL_WORLD_MODE,
-  MINIMAL_MATERIAL_KINDS,
-  MINIMAL_PLANET_COLOR_HEX,
-} from './minimalWorld.js';
-
-export {
-  applyMinimalLighting,
-  removeMinimalLighting,
-  updateMinimalKeyLight,
-  takeSceneLights,
-  DEFAULT_LIGHT_NAMES,
-  MINIMAL_LIGHT_NAME,
-  MINIMAL_FILL_NAME,
-} from './minimalLighting.js';

package/src/minimal/minimalLighting.js

@@ -1,137 +0,0 @@
-/**
- * @file src/minimal/minimalLighting.js
- * @description The one light the minimal look keeps.
- *
- * Shared for the same reason as `minimalWorld.js`, and more sharply: lighting is what makes two
- * renders of the same world look like the same world. The editor's performance preview and the
- * Orbiters render MUST take their key light, their fill and their restore behaviour from this one
- * module, or an author would tune a world against lighting the public never sees.
- *
- * Minimal is not an unlit scene. The moons are a lit material, so a scene with no lights renders them
- * as black discs, and the planet needs a light for its shape to be legible at all. What it does not
- * need is the world's usual pair — a hemisphere and an ambient, both white-on-white at full strength,
- * which light every surface identically and are themselves part of why a sphere reads as a flat disc.
- *
- * So: exactly one directional light, no shadows. Its colour and direction come from the world's own
- * authored lighting where the world provides them, which is how a minimal scene still carries some of
- * the world's identity without loading anything.
- */
-import * as THREE from 'three';
-
-/** The shared default lights, by the names the shared package gives them. */
-export const DEFAULT_LIGHT_NAMES = Object.freeze(['ew_HemisphereLight', 'ew_AmbientLight']);
-/** The single light the minimal look keeps. */
-export const MINIMAL_LIGHT_NAME = 'orb_MinimalKeyLight';
-/** The weak ambient that keeps the unlit side from going pure black. */
-export const MINIMAL_FILL_NAME = 'orb_MinimalFillLight';
-
-const DEFAULT_INTENSITY = 1.8;
-const DEFAULT_DIRECTION = Object.freeze({ x: 1, y: 0.6, z: 1 });
-/**
- * The fill. A single directional light alone puts the unlit side at pure black, which cuts the
- * silhouette in half instead of rounding it — the terminator reads as a hard edge rather than a
- * curve. A weak ambient lifts that side just enough for the shape to close.
- *
- * Ambient is the cheapest light there is: a constant added per fragment, no direction, no attenuation,
- * no extra pass, and no shadow map. It is the right way to soften this and the only one worth its cost.
- */
-const FILL_INTENSITY = 0.55;
-
-function removeLightByName(scene, name) {
-  const light = scene.getObjectByName(name);
-  if (!light) return;
-  scene.remove(light);
-  // Lights hold no geometry or texture, but they do hold a shadow map + camera once shadows have
-  // been on, and `dispose` is what releases it.
-  light.dispose?.();
-}
-
-/**
- * Detach the world's default lights and hand them back — WITHOUT disposing them.
- *
- * They carry the world's authored colour, direction and intensities, and nothing re-applies those
- * when the mode is switched off inside Studio. Keeping the objects means leaving minimal restores
- * exactly what the world had, rather than a generic pair at 1.0/1.0.
- *
- * @param {THREE.Scene} scene
- * @returns {THREE.Light[]} the detached lights, in the order they were found
- */
-export function takeSceneLights(scene) {
-  if (!scene) return [];
-  const taken = [];
-  DEFAULT_LIGHT_NAMES.forEach((name) => {
-    const light = scene.getObjectByName(name);
-    if (!light) return;
-    scene.remove(light);
-    taken.push(light);
-  });
-  return taken;
-}
-
-/**
- * Add the key light plus a weak ambient fill. Idempotent. Two lights, both of the cheapest kinds,
- * and neither casting a shadow.
- *
- * The world's own lights are NOT removed here — that is `takeSceneLights`, so the caller decides
- * whether it is keeping them to put back.
- */
-export function applyMinimalLighting(scene) {
-  if (!scene) return null;
-
-  if (!scene.getObjectByName(MINIMAL_FILL_NAME)) {
-    const fill = new THREE.AmbientLight(0xffffff, FILL_INTENSITY);
-    fill.name = MINIMAL_FILL_NAME;
-    scene.add(fill);
-  }
-
-  const existing = scene.getObjectByName(MINIMAL_LIGHT_NAME);
-  if (existing) return existing;
-  const key = new THREE.DirectionalLight(0xffffff, DEFAULT_INTENSITY);
-  key.position.set(DEFAULT_DIRECTION.x, DEFAULT_DIRECTION.y, DEFAULT_DIRECTION.z);
-  key.castShadow = false;
-  key.name = MINIMAL_LIGHT_NAME;
-  scene.add(key);
-  return key;
-}
-
-export function removeMinimalLighting(scene) {
-  if (!scene) return;
-  removeLightByName(scene, MINIMAL_LIGHT_NAME);
-  removeLightByName(scene, MINIMAL_FILL_NAME);
-}
-
-/**
- * Point the key light the way the world says its light points.
- *
- * DIRECTION only — the world's light COLOUR is deliberately not applied. Minimal is a monochrome
- * look, and a world that authored a strongly tinted light would drag the whole scene into that hue
- * and break the consistency the mode is for. Direction gives the shape somewhere to be lit from,
- * which is what actually varies usefully between worlds.
- *
- * A no-op when the key light is not in the scene, so a full-profile world load never has to check
- * which mode it is in.
- *
- * @param {THREE.Scene} scene
- * @param {{ lightDirection?: object, direction?: object,
- *           diffuseIntensity?: number, diffuse?: number }} lighting
- */
-export function updateMinimalKeyLight(scene, lighting = {}) {
-  const key = scene?.getObjectByName(MINIMAL_LIGHT_NAME);
-  if (!key) return;
-
-  const direction = lighting.lightDirection ?? lighting.direction;
-  if (direction && typeof direction === 'object') {
-    const x = Number.isFinite(direction.x) ? direction.x : DEFAULT_DIRECTION.x;
-    const y = Number.isFinite(direction.y) ? direction.y : DEFAULT_DIRECTION.y;
-    const z = Number.isFinite(direction.z) ? direction.z : DEFAULT_DIRECTION.z;
-    // A direction of all zeros would put the light inside the planet and black the scene out.
-    if (x !== 0 || y !== 0 || z !== 0) key.position.set(x, y, z);
-  }
-
-  const intensity = lighting.diffuseIntensity ?? lighting.diffuse;
-  if (Number.isFinite(intensity) && intensity > 0) {
-    // The world's intensities are authored against TWO lights at full strength; this is one, so it
-    // keeps the default as a floor rather than dimming the only light in the scene.
-    key.intensity = Math.max(DEFAULT_INTENSITY, intensity);
-  }
-}

package/src/minimal/minimalWorld.js

@@ -1,179 +0,0 @@
-/**
- * @file src/minimal/minimalWorld.js
- * @description The planet as performance mode draws it: one sphere, one cheap lit material, no
- * texture, no halo, no cloud shell.
- *
- * Shared, not Orbiters-local, because TWO surfaces draw this look: Orbiters renders it in
- * performance mode, and the Entangled Worlds editor previews it so an author can see what they are
- * authoring. If each kept its own copy the preview would drift from the render and start lying about
- * what the public will see — the one failure this module exists to prevent.
- *
- * Why this exists rather than reusing the shared normal-material sphere: `MeshNormalMaterial` colours
- * each pixel by the direction the surface faces, which is a gradient, not shading. It cannot respond
- * to a light at all — so however many lights the scene has, the planet reads as a flat disc while the
- * moons beside it (a lit material) read as spheres. A lit material is what makes the shape legible.
- *
- * The cost of that is close to nothing. Lambert is one dot product per fragment against a single
- * directional light — no specular, no roughness, no environment lookup, no texture fetch. What it
- * costs over the normal material is far less than what a texture, a halo or a cloud shell cost, all
- * of which this mode drops.
- *
- * `kind` exists so the options can be compared on real hardware without a rebuild
- * (`?minimalMaterial=lambert|phong|normal`), and so the choice is one line if a cheaper one wins.
- */
-import * as THREE from 'three';
-
-export const MINIMAL_WORLD_MODE = 90;
-
-/**
- * The minimal planet's colour when the world names none.
- *
- * Deliberately neutral, and deliberately NOT read from the `--color*` theme variables: those are the
- * app chrome's palette (white, black, the UI accent), not the world's, so reading them would paint
- * every planet the same interface colour. A world that DOES name a colour is honoured — see
- * `resolvePlanetColor` — and what carries the identity of one that does not is its own authored
- * light (`minimalLighting.js`).
- */
-const DEFAULT_PLANET_COLOR = 0xb8c2cc;
-
-/**
- * The same neutral as a CSS hex, for surfaces that have to SHOW it rather than render it — the
- * editor's colour swatch displays this when a world has authored nothing, so the control never
- * claims a colour the renderer is not actually using. Exported so there is one constant, not an
- * editor copy that has to be kept equal to this one.
- */
-export const MINIMAL_PLANET_COLOR_HEX = `#${DEFAULT_PLANET_COLOR.toString(16).padStart(6, '0')}`;
-
-/**
- * The floor an authored colour is lifted to, as HSL lightness in the sRGB the author picked in.
- *
- * Minimal drops the skybox, so the planet is drawn against black (`SceneSpace` sets the background to
- * BLACK when there is no cubemap). The scene's whole light budget is one key at 1.8 plus a 0.55
- * ambient fill, so a near-black body reflects almost nothing and disappears into that background
- * entirely — not a dark planet, no planet. Lifting the lightness while keeping hue and saturation
- * means a world that authored near-black still reads as its own hue, just at the darkest level that
- * is still a visible sphere.
- *
- * 0.10 sits below anything an author would recognise as a colour rather than as black: `#101030`, a
- * genuinely dark navy, measures 0.125 and passes through untouched.
- */
-const MIN_PLANET_LIGHTNESS = 0.1;
-
-export const MINIMAL_MATERIAL_KINDS = Object.freeze(['lambert', 'phong', 'normal']);
-
-/**
- * Segment counts used only when the world names none.
- *
- * The world's OWN resolution is never overridden, including when it is very low. A low-segment world
- * is a faceted world on purpose — that faceting is the world's shape, not a defect to be smoothed
- * away — and performance mode changes what is DRAWN, never the world's configuration.
- */
-const FALLBACK_WIDTH_SEGMENTS = 48;
-const FALLBACK_HEIGHT_SEGMENTS = 32;
-
-function resolveSegments(value, fallback) {
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric) || numeric <= 0) return fallback;
-  return Math.round(numeric);
-}
-
-/**
- * Parse a colour, or report that it could not be parsed.
- *
- * `new THREE.Color(x)` does NOT throw on a value it cannot read: `Color.set` ignores anything that is
- * not a Color, a number or a string, and `setStyle` warns and leaves the colour untouched. Either way
- * the object keeps whatever it was constructed with, so a `try/catch` around it catches nothing and
- * the caller silently gets that starting value — white, by default.
- *
- * That matters here because the colour arrives from world metadata, which is `Schema.Types.Mixed` and
- * validated nowhere: any non-empty string persists, so `'blueish'` would paint a WHITE planet rather
- * than falling back to the neutral one.
- *
- * So: probe from black. If the result is black the value was either genuinely black or not read at
- * all — probe again from white to tell those apart. The common case parses on the first probe and
- * costs one object.
- *
- * @returns {THREE.Color|null} null when the value could not be read as a colour
- */
-function parseColor(value) {
-  const fromBlack = new THREE.Color(0x000000).set(value);
-  if (fromBlack.getHex() !== 0x000000) return fromBlack;
-  const fromWhite = new THREE.Color(0xffffff).set(value);
-  return fromWhite.getHex() === 0x000000 ? fromBlack : null;
-}
-
-/**
- * The planet colour to use, given the colour the world authored (if any).
- *
- * The only thing done to an authored colour is the legibility floor above. Hue and saturation are
- * never touched: the point of the control is that the world picks its own colour, so anything that
- * moved it toward a house palette would defeat it.
- *
- * @param {THREE.Color|number|string|null|undefined} override
- * @returns {THREE.Color}
- */
-export function resolvePlanetColor(override) {
-  if (override === undefined || override === null) return new THREE.Color(DEFAULT_PLANET_COLOR);
-  // An unreadable colour is never worth failing a world load over — the world just keeps the neutral.
-  const color = parseColor(override);
-  if (!color) return new THREE.Color(DEFAULT_PLANET_COLOR);
-  // Read and write HSL in sRGB — the space the author picked the colour in. The working space is
-  // linear, where the same swatch measures several times darker, so a floor applied there would
-  // lift colours the author would not call dark at all.
-  const hsl = { h: 0, s: 0, l: 0 };
-  color.getHSL(hsl, THREE.SRGBColorSpace);
-  if (hsl.l < MIN_PLANET_LIGHTNESS) {
-    color.setHSL(hsl.h, hsl.s, MIN_PLANET_LIGHTNESS, THREE.SRGBColorSpace);
-  }
-  return color;
-}
-
-function createMaterial(kind, color) {
-  switch (kind) {
-    case 'normal':
-      // The previous look, kept so it can be compared directly rather than from memory.
-      return new THREE.MeshNormalMaterial();
-    case 'phong':
-      // One specular highlight on top of Lambert. Reads glossier; costs a little more.
-      return new THREE.MeshPhongMaterial({ color, shininess: 12, specular: 0x222222 });
-    default:
-      return new THREE.MeshLambertMaterial({ color });
-  }
-}
-
-/**
- * Build the minimal planet. Signature matches what `WorldManager.setMode` hands a custom creator.
- *
- * @param {{
- *   sphereRadius?: number,
- *   sphereWidthSegments?: number,
- *   sphereHeightSegments?: number,
- *   materialKind?: 'lambert'|'phong'|'normal',
- *   planetColor?: THREE.Color|number|string,
- * }} args
- * @returns {Promise<THREE.Mesh>}
- */
-export async function createMinimalWorld({
-  sphereRadius = 1,
-  sphereWidthSegments,
-  sphereHeightSegments,
-  materialKind = 'lambert',
-  planetColor,
-} = {}) {
-  const kind = MINIMAL_MATERIAL_KINDS.includes(materialKind) ? materialKind : 'lambert';
-  const color = resolvePlanetColor(planetColor);
-
-  // The world's own radius and segment counts, as authored. Same shape as the full look — this mode
-  // changes the material and what surrounds the planet, never the geometry the world describes.
-  const geometry = new THREE.SphereGeometry(
-    sphereRadius,
-    resolveSegments(sphereWidthSegments, FALLBACK_WIDTH_SEGMENTS),
-    resolveSegments(sphereHeightSegments, FALLBACK_HEIGHT_SEGMENTS),
-  );
-  const material = createMaterial(kind, color);
-  const mesh = new THREE.Mesh(geometry, material);
-  mesh.name = 'orb_MinimalWorld';
-  mesh.castShadow = false;
-  mesh.receiveShadow = false;
-  return mesh;
-}