@johnmorrisdotca/chikyu-earth 0.4.0 → 0.7.0

package/dist/space/element.d.ts

@@ -0,0 +1,134 @@
+import type { GeoPoint } from "../types.ts";
+import { setThreeLoader } from "../realistic/shared.ts";
+import { type ScaleMode } from "./scale.ts";
+import { BODY_NAMES, type BodyName, type BodyPainter } from "./scene.ts";
+export { BODY_NAMES, type BodyName };
+/**
+ * Change how the Sun and the planets are drawn (before the first element connects): the space view keeps their places, sizes, light, names and orbits and asks
+ * the painter only for what to draw at each place (see `BodyPainter`). Left alone, they are plain spheres in the right colours.
+ *
+ * @param next - The painter to use, or `undefined` for the plain one.
+ *
+ * @example
+ * ```ts no-run
+ * import { plainPainter } from "@johnmorrisdotca/chikyu-earth/space";
+ * import { setBodyPainter } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * setBodyPainter({ make: (three, name) => plainPainter.make(three, name) });
+ * ```
+ */
+export declare function setBodyPainter(next: BodyPainter | undefined): void;
+/**
+ * What a page can tell a reader about a body now.
+ *
+ * @example
+ * ```ts no-run
+ * import type { BodyInfo } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * const info: BodyInfo = { name: "Mars", radiusKm: 3389.5, distanceKm: 225_000_000 };
+ * console.log(`${info.name}: ${info.radiusKm} km`);
+ * ```
+ */
+export interface BodyInfo {
+    name: BodyName;
+    /** Mean radius, kilometres. */
+    radiusKm: number;
+    /** Distance from the Earth's centre now, kilometres (0 for the Earth). */
+    distanceKm: number;
+}
+export { setThreeLoader };
+/**
+ * What the space view is doing: `loading`, `live`, `unavailable` (no WebGL), `lost` (the GPU took the context; it comes back by itself) or `idle` (another view has the page's one context).
+ *
+ * @example
+ * ```ts no-run
+ * import type { ChikyuSpace, SpaceState } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * const stateOf = (space: ChikyuSpace): SpaceState => space.stats.state;
+ * console.log(typeof stateOf);
+ * ```
+ */
+export type SpaceState = "loading" | "live" | "unavailable" | "lost" | "idle";
+/**
+ * A named distance for `zoomFor`: the Earth, the Moon, the Sun, the inner planets or the whole solar system.
+ *
+ * @example
+ * ```ts no-run
+ * import type { ChikyuSpace, SpacePreset } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * const zoomTo = (space: ChikyuSpace, preset: SpacePreset): number => space.zoomFor(preset);
+ * console.log(typeof zoomTo);
+ * ```
+ */
+export type SpacePreset = "earth" | "moon" | "sun" | "inner" | "solar-system";
+/**
+ * The `<chikyu-space>` custom element: the Earth, the Moon, the Sun and the planets where they are at a date and time, drawn with three.js through the shared renderer. It takes `center`, `time` (`now` or an ISO date), `speed` (1 is real time, 0 holds, 86400 is a day a second, negative runs backwards), `scale` (`compressed` or `true`), `labels` and `orbits` (`off` hides them); positions are computed in the browser by astronomy-engine, an optional peer dependency. It draws only when something changes, and nothing while it is out of sight.
+ *
+ * @example
+ * ```ts no-run
+ * import type { ChikyuSpace } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * const space = document.createElement("chikyu-space") as ChikyuSpace;
+ * space.setAttribute("time", "2026-11-02T12:00Z");
+ * space.setAttribute("speed", "0");
+ * document.body.append(space);
+ * ```
+ */
+export declare class ChikyuSpace extends HTMLElement {
+    #private;
+    static observedAttributes: string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    get centre(): GeoPoint;
+    set centre(value: GeoPoint);
+    /** The moment shown: milliseconds since the epoch, or "now" to follow the clock. Setting it points the camera at the same place on the ground again. */
+    get time(): number;
+    set time(value: number | Date | "now");
+    /** Seconds of game time per second: 1 is real time, 0 holds still, negative runs backwards. */
+    get speed(): number;
+    set speed(value: number);
+    get scale(): ScaleMode;
+    set scale(value: ScaleMode);
+    get labels(): boolean;
+    set labels(value: boolean);
+    get orbits(): boolean;
+    set orbits(value: boolean);
+    /** The shared controls' camera: yaw and tilt turn the view, zoom brings the camera in (1 shows the Earth, less shows the sky round it). Pan is not used. */
+    setView(view: {
+        yaw: number;
+        tilt: number;
+        zoom: number;
+    }): void;
+    /** The body the camera looks at: at zoom 1 it fills the view; the yaw and tilt turn the camera round it. */
+    get body(): BodyName;
+    set body(name: BodyName);
+    /** The radius and the distance from the Earth of a body now, for a page's own caption. */
+    bodyInfo(name: BodyName): BodyInfo;
+    /** The zoom that shows a part of the sky: the Earth alone, the Moon's orbit, the Sun, the planets out to Mars, or all of them, at this scale and moment. */
+    zoomFor(preset: SpacePreset): number;
+    /** What the element is doing, for a page or a test. */
+    get stats(): {
+        state: SpaceState;
+        draws: number;
+        contexts: number;
+        canvas: {
+            width: number;
+            height: number;
+            pixels: number;
+        };
+        tiers: Record<string, number>;
+        distance: number;
+        assets: {
+            entries: number;
+            refs: number;
+        };
+        time: number;
+        lookups: number;
+    };
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "chikyu-space": ChikyuSpace;
+    }
+}

package/dist/space/element.js

@@ -0,0 +1,394 @@
+import { createGate, frameCap } from "../realistic/gate.js";
+import { setThreeLoader, takeRenderer } from "../realistic/shared.js";
+import { MAX_TEXTURE } from "../realistic/tiers.js";
+import { AU_IN_EARTH_RADII, EARTH_RADIUS_KM, frameAt } from "./ephemeris.js";
+import { placeAround, placeMoon, placeSun } from "./scale.js";
+import { BODY_NAMES, createSpaceItem, FIT_DISTANCE, newSpaceModel } from "./scene.js";
+export { BODY_NAMES };
+let painter;
+/**
+ * Change how the Sun and the planets are drawn (before the first element connects): the space view keeps their places, sizes, light, names and orbits and asks
+ * the painter only for what to draw at each place (see `BodyPainter`). Left alone, they are plain spheres in the right colours.
+ *
+ * @param next - The painter to use, or `undefined` for the plain one.
+ *
+ * @example
+ * ```ts no-run
+ * import { plainPainter } from "@johnmorrisdotca/chikyu-earth/space";
+ * import { setBodyPainter } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * setBodyPainter({ make: (three, name) => plainPainter.make(three, name) });
+ * ```
+ */
+export function setBodyPainter(next) {
+    painter = next;
+}
+/** Mean radii in kilometres (IAU), for what a click tells. */
+const RADIUS_KM = { Sun: 695_700, Mercury: 2439.7, Venus: 6051.8, Earth: 6371, Moon: 1737.4, Mars: 3389.5, Jupiter: 69_911, Saturn: 58_232, Uranus: 25_362, Neptune: 24_622 };
+export { setThreeLoader };
+const RAD = Math.PI / 180;
+/** The Earth's own turn, degrees a second. */
+const EARTH_RATE = 360 / 86_164.0905;
+const REAL_TIME_TICK_MS = 60_000;
+const readCentre = (value) => {
+    if (!value)
+        return null;
+    const [lon, lat] = value.split(",").map((part) => Number(part.trim()));
+    if (!Number.isFinite(lon) || !Number.isFinite(lat) || Math.abs(lon) > 180 || Math.abs(lat) > 90)
+        return null;
+    return { lon: lon, lat: lat };
+};
+const readTime = (value) => {
+    if (value === null || value === "" || value === "now")
+        return "now";
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? ms : "now";
+};
+/**
+ * The `<chikyu-space>` custom element: the Earth, the Moon, the Sun and the planets where they are at a date and time, drawn with three.js through the shared renderer. It takes `center`, `time` (`now` or an ISO date), `speed` (1 is real time, 0 holds, 86400 is a day a second, negative runs backwards), `scale` (`compressed` or `true`), `labels` and `orbits` (`off` hides them); positions are computed in the browser by astronomy-engine, an optional peer dependency. It draws only when something changes, and nothing while it is out of sight.
+ *
+ * @example
+ * ```ts no-run
+ * import type { ChikyuSpace } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * const space = document.createElement("chikyu-space") as ChikyuSpace;
+ * space.setAttribute("time", "2026-11-02T12:00Z");
+ * space.setAttribute("speed", "0");
+ * document.body.append(space);
+ * ```
+ */
+export class ChikyuSpace extends HTMLElement {
+    static observedAttributes = ["center", "time", "speed", "scale", "labels", "orbits"];
+    #model = newSpaceModel();
+    #mode = "now";
+    #speed = 1;
+    #view;
+    #gate;
+    #taken;
+    #stage;
+    #labelBox;
+    #state = "loading";
+    #timer;
+    #last = 0;
+    #pool = new Map();
+    #places;
+    #tiers = {};
+    connectedCallback() {
+        this.#model.centre = readCentre(this.getAttribute("center")) ?? this.#model.centre;
+        this.#mode = readTime(this.getAttribute("time"));
+        this.#model.time = this.#mode === "now" ? Date.now() : this.#mode;
+        this.#speed = this.#readSpeed();
+        this.#model.mode = this.getAttribute("scale") === "true" ? "true" : "compressed";
+        this.#model.labels = this.getAttribute("labels") !== "off";
+        this.#model.orbits = this.getAttribute("orbits") !== "off";
+        this.#model.stepMs = Math.max(1000, Math.abs(this.#speed) * 1000);
+        if (!this.hasAttribute("role"))
+            this.setAttribute("role", "img");
+        if (!this.hasAttribute("aria-label"))
+            this.setAttribute("aria-label", "The Earth, the Moon, the Sun and the planets in their places for the date shown");
+        const root = this.shadowRoot ?? this.attachShadow({ mode: "open" });
+        root.innerHTML = `<style>:host{display:block;aspect-ratio:1/1;position:relative;overflow:hidden}#stage,#labels{position:absolute;inset:0}#labels{pointer-events:none;overflow:hidden}.sp-label{position:absolute;left:0;top:0;margin:0;padding:0;border:0;background:none;font:12px/16px system-ui,-apple-system,sans-serif;color:#fff;white-space:nowrap;text-shadow:0 0 3px #000,0 0 3px #000;will-change:transform;pointer-events:none}.sp-label:focus-visible{outline:2px solid #6cd0ff;outline-offset:2px;border-radius:4px}.sp-label::before{content:"";display:inline-block;width:5px;height:5px;margin:0 5px 1px -2px;border-radius:50%;background:#fff}.sp-label[hidden]{display:none}</style><div id="stage"></div><div id="labels" aria-hidden="true"></div>`;
+        this.#stage = root.getElementById("stage");
+        this.#labelBox = root.getElementById("labels");
+        this.#pool.clear();
+        const nav = navigator;
+        this.#gate = createGate(1000 / frameCap(30, { deviceMemory: nav.deviceMemory, hardwareConcurrency: nav.hardwareConcurrency }), () => this.#view?.invalidate());
+        this.#stage.addEventListener("webglcontextlost", this.#lost, true);
+        this.#stage.addEventListener("webglcontextrestored", this.#restored, true);
+        const taken = takeRenderer((state) => {
+            if (state === "unavailable")
+                this.#fail("WebGL is not available");
+        });
+        this.#taken = taken;
+        const item = createSpaceItem(this.#model, {
+            assets: taken.renderer.assets,
+            textureBase: () => this.#textureBase(),
+            cap: () => this.#textureCap(),
+            invalidate: () => this.#gate?.request(),
+            onError: (error) => this.#fail(error instanceof Error ? error.message : String(error)),
+            onTier: (layer, width) => {
+                this.#tiers[layer] = width;
+            },
+            onLabels: (places) => this.#placeLabels(places),
+            ...(painter ? { painter } : {}),
+        });
+        this.#view = taken.renderer.view(this.#stage, item, { still: null });
+        this.#set("loading");
+        void this.#view.focus().then((live) => {
+            if (live) {
+                this.#set("live");
+                this.dispatchEvent(new CustomEvent("chikyu-ready"));
+            }
+            else if (this.#state === "loading")
+                this.#set("unavailable");
+        });
+        this.#last = performance.now();
+        this.#schedule();
+        this.addEventListener("pointerdown", this.#down);
+        this.#labelBox.addEventListener("click", this.#labelClick);
+        this.#labelBox.addEventListener("focusin", this.#labelFocus);
+    }
+    disconnectedCallback() {
+        this.removeEventListener("pointerdown", this.#down);
+        window.removeEventListener("pointerup", this.#up, true);
+        clearTimeout(this.#timer);
+        this.#timer = undefined;
+        this.#gate?.cancel();
+        this.#view?.dispose();
+        this.#view = undefined;
+        this.#taken?.release();
+        this.#taken = undefined;
+    }
+    attributeChangedCallback(name, _old, value) {
+        if (name === "center")
+            this.centre = readCentre(value) ?? { lon: 0, lat: 0 };
+        else if (name === "time")
+            this.time = readTime(value);
+        else if (name === "speed")
+            this.speed = this.#readSpeed();
+        else if (name === "scale")
+            this.scale = value === "true" ? "true" : "compressed";
+        else if (name === "labels")
+            this.labels = value !== "off";
+        else if (name === "orbits")
+            this.orbits = value !== "off";
+    }
+    get centre() {
+        return { ...this.#model.centre };
+    }
+    set centre(value) {
+        this.#model.centre = { ...value };
+        this.#gate?.request();
+    }
+    /** The moment shown: milliseconds since the epoch, or "now" to follow the clock. Setting it points the camera at the same place on the ground again. */
+    get time() {
+        return this.#model.time;
+    }
+    set time(value) {
+        this.#mode = value instanceof Date ? value.getTime() : value;
+        this.#model.time = this.#mode === "now" ? Date.now() : this.#mode;
+        this.#model.cameraSpin = null;
+        this.#last = performance.now();
+        this.#schedule();
+        this.#gate?.request();
+    }
+    /** Seconds of game time per second: 1 is real time, 0 holds still, negative runs backwards. */
+    get speed() {
+        return this.#speed;
+    }
+    set speed(value) {
+        this.#speed = Number.isFinite(value) ? value : 1;
+        this.#model.stepMs = Math.max(1000, Math.abs(this.#speed) * 1000);
+        this.#last = performance.now();
+        this.#schedule();
+        this.#gate?.request();
+    }
+    get scale() {
+        return this.#model.mode;
+    }
+    set scale(value) {
+        this.#model.mode = value;
+        this.#gate?.request();
+    }
+    get labels() {
+        return this.#model.labels;
+    }
+    set labels(value) {
+        this.#model.labels = value;
+        if (!value)
+            for (const label of this.#pool.values())
+                label.hidden = true;
+        this.#gate?.request();
+    }
+    get orbits() {
+        return this.#model.orbits;
+    }
+    set orbits(value) {
+        this.#model.orbits = value;
+        this.#gate?.request();
+    }
+    /** The shared controls' camera: yaw and tilt turn the view, zoom brings the camera in (1 shows the Earth, less shows the sky round it). Pan is not used. */
+    setView(view) {
+        const now = this.#model.view;
+        if (view.yaw === now.yaw && view.tilt === now.tilt && view.zoom === now.zoom)
+            return;
+        this.#model.view = { yaw: view.yaw, tilt: view.tilt, zoom: view.zoom };
+        this.#gate?.request();
+    }
+    /** The body the camera looks at: at zoom 1 it fills the view; the yaw and tilt turn the camera round it. */
+    get body() {
+        return this.#model.focus;
+    }
+    set body(name) {
+        if (!BODY_NAMES.includes(name))
+            return;
+        this.#model.focus = name;
+        this.#gate?.request();
+    }
+    /** The radius and the distance from the Earth of a body now, for a page's own caption. */
+    bodyInfo(name) {
+        const frame = this.#model.drawn?.frame ?? frameAt(this.#model.time);
+        const geo = name === "Earth" ? [0, 0, 0] : name === "Sun" ? frame.sun : name === "Moon" ? frame.moon : frame.planets[name];
+        return { name, radiusKm: RADIUS_KM[name], distanceKm: Math.hypot(geo[0], geo[1], geo[2]) * (AU_IN_EARTH_RADII * EARTH_RADIUS_KM) };
+    }
+    /** The zoom that shows a part of the sky: the Earth alone, the Moon's orbit, the Sun, the planets out to Mars, or all of them, at this scale and moment. */
+    zoomFor(preset) {
+        const frame = this.#model.drawn?.frame ?? frameAt(this.#model.time);
+        const mode = this.#model.mode;
+        const sun = placeSun(mode, frame.sun);
+        const around = (name) => Math.hypot(...placeAround(mode, sun, [frame.planets[name][0] - frame.sun[0], frame.planets[name][1] - frame.sun[1], frame.planets[name][2] - frame.sun[2]]));
+        const reach = {
+            earth: 0,
+            moon: Math.hypot(...placeMoon(mode, frame.moon)),
+            sun: Math.hypot(...sun),
+            inner: Math.max(around("Mercury"), around("Venus"), around("Mars"), Math.hypot(...sun)),
+            "solar-system": Math.max(...Object.keys(frame.planets).map(around), Math.hypot(...sun)),
+        }[preset];
+        return preset === "earth" ? 1 : FIT_DISTANCE / Math.max(FIT_DISTANCE, reach * 3.4);
+    }
+    /** What the element is doing, for a page or a test. */
+    get stats() {
+        const stats = this.#taken?.renderer.stats;
+        return {
+            state: this.#state,
+            draws: stats?.draws ?? 0,
+            contexts: stats?.contexts ?? 0,
+            canvas: stats?.canvas ?? { width: 0, height: 0, pixels: 0 },
+            tiers: { ...this.#tiers },
+            distance: this.#model.drawn?.distance ?? 0,
+            assets: { entries: stats?.assets.entries ?? 0, refs: stats?.assets.refs ?? 0 },
+            time: this.#model.time,
+            lookups: this.#model.lookups,
+        };
+    }
+    // --- the game clock ----------------------------------------------------------------------------------------------------------------------------
+    #readSpeed() {
+        const raw = this.getAttribute("speed");
+        const value = raw === null || raw === "" ? 1 : Number(raw);
+        return Number.isFinite(value) ? value : 1;
+    }
+    /** While time runs, draw as often as it shows: real time once a minute; faster time as often as the Earth's turn moves a pixel (1 to 30 times a second). */
+    #schedule() {
+        clearTimeout(this.#timer);
+        this.#timer = undefined;
+        if (!this.isConnected || this.#speed === 0)
+            return;
+        const realTime = this.#speed === 1 && this.#mode === "now";
+        const radius = this.#model.drawn?.radiusPx ?? 200;
+        const pixelsPerSecond = EARTH_RATE * RAD * Math.abs(this.#speed) * radius;
+        const perSecond = Math.min(30, Math.max(1, pixelsPerSecond));
+        const wait = realTime || this.#speed === 1 ? REAL_TIME_TICK_MS : 1000 / perSecond;
+        this.#timer = setTimeout(this.#tick, wait);
+    }
+    #tick = () => {
+        const now = performance.now();
+        if (this.#speed === 1 && this.#mode === "now")
+            this.#model.time = Date.now();
+        else
+            this.#model.time += (now - this.#last) * this.#speed;
+        this.#last = now;
+        this.#gate?.request();
+        this.#schedule();
+        this.dispatchEvent(new CustomEvent("chikyu-time", { detail: { time: this.#model.time } }));
+    };
+    // --- labels --------------------------------------------------------------------------------------------------------------------------------------
+    #placeLabels(places) {
+        this.#places = places;
+        const box = this.#labelBox;
+        if (!box)
+            return;
+        for (const name of BODY_NAMES) {
+            let label = this.#pool.get(name);
+            const at = places[name];
+            if (!label) {
+                if (!at)
+                    continue;
+                const button = box.ownerDocument.createElement("button");
+                button.type = "button";
+                button.className = "sp-label";
+                button.dataset["body"] = name;
+                button.textContent = name;
+                button.setAttribute("aria-label", `${name}: choose to look at it`);
+                box.append(button);
+                this.#pool.set(name, button);
+                label = button;
+            }
+            if (!at) {
+                if (!label.hidden)
+                    label.hidden = true;
+                continue;
+            }
+            if (label.hidden)
+                label.hidden = false;
+            label.style.transform = `translate(${Math.round(at.x + Math.max(4, Math.min(at.r, 40)))}px,${Math.round(at.y - 8)}px)`;
+        }
+    }
+    // A body is chosen by pressing on it or on its name (and by Tab and Enter on the name); a drag that turns the view is not a choice.
+    #downX = 0;
+    #downY = 0;
+    #down = (event) => {
+        if (event.button !== 0)
+            return;
+        this.#downX = event.clientX;
+        this.#downY = event.clientY;
+        window.addEventListener("pointerup", this.#up, { capture: true, once: true });
+    };
+    #up = (event) => {
+        if (Math.hypot(event.clientX - this.#downX, event.clientY - this.#downY) > 6 || !this.#places)
+            return;
+        const rect = this.getBoundingClientRect();
+        const x = event.clientX - rect.left;
+        const y = event.clientY - rect.top;
+        let best;
+        let bestD = Infinity;
+        for (const name of BODY_NAMES) {
+            const at = this.#places[name];
+            if (!at)
+                continue;
+            const d = Math.hypot(x - at.x, y - at.y);
+            if (d <= Math.max(at.r, 14) && d < bestD) {
+                best = name;
+                bestD = d;
+            }
+        }
+        if (best)
+            this.dispatchEvent(new CustomEvent("chikyu-body-click", { detail: this.bodyInfo(best), bubbles: true, composed: true }));
+    };
+    #labelClick = (event) => {
+        const name = event.target?.dataset?.["body"];
+        if (name)
+            this.dispatchEvent(new CustomEvent("chikyu-body-click", { detail: this.bodyInfo(name), bubbles: true, composed: true }));
+    };
+    #labelFocus = (event) => {
+        const name = event.target?.dataset?.["body"];
+        if (name)
+            this.dispatchEvent(new CustomEvent("chikyu-body-focus", { detail: this.bodyInfo(name), bubbles: true, composed: true }));
+    };
+    // --- the rest --------------------------------------------------------------------------------------------------------------------------------------
+    #textureBase() {
+        const given = this.getAttribute("texture-base");
+        const base = given ?? new URL("../textures/", import.meta.url).href;
+        return base.endsWith("/") ? base : `${base}/`;
+    }
+    #textureCap() {
+        const given = Number(this.getAttribute("max-texture"));
+        const memory = navigator.deviceMemory;
+        const cap = Number.isFinite(given) && given > 0 ? Math.min(given, MAX_TEXTURE) : MAX_TEXTURE;
+        return memory !== undefined && memory <= 2 ? Math.min(cap, 2048) : cap;
+    }
+    #lost = () => this.#set("lost");
+    #restored = () => this.#set("live");
+    #set(state) {
+        if (this.#state === state)
+            return;
+        this.#state = state;
+        this.dataset["state"] = state;
+    }
+    #fail(reason) {
+        this.#set("unavailable");
+        this.dispatchEvent(new CustomEvent("chikyu-unavailable", { detail: { reason } }));
+    }
+}
+if (typeof customElements !== "undefined" && !customElements.get("chikyu-space")) {
+    customElements.define("chikyu-space", ChikyuSpace);
+}

package/dist/space/ephemeris.d.ts

@@ -0,0 +1,151 @@
+/**
+ * A position or direction as `[x, y, z]`, in the scene's axes (x toward the vernal equinox, y north).
+ *
+ * @example
+ * ```ts
+ * import type { Vec3 } from "@johnmorrisdotca/chikyu-earth/space";
+ *
+ * const origin: Vec3 = [0, 0, 0];
+ * console.log(origin);
+ * ```
+ */
+export type Vec3 = [number, number, number];
+/**
+ * The planets drawn, nearest the Sun first.
+ *
+ * @example
+ * ```ts
+ * import { PLANETS } from "@johnmorrisdotca/chikyu-earth/space";
+ *
+ * console.log(PLANETS.join(", "));
+ * ```
+ */
+export declare const PLANETS: readonly ["Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune"];
+/**
+ * One of the seven planets drawn, by name.
+ *
+ * @example
+ * ```ts
+ * import { orbitPath, type PlanetName } from "@johnmorrisdotca/chikyu-earth/space";
+ *
+ * const planet: PlanetName = "Mars";
+ * console.log(orbitPath(planet, Date.UTC(2026, 10, 2), 8).length);
+ * ```
+ */
+export type PlanetName = (typeof PLANETS)[number];
+/**
+ * Where everything is at one moment: positions in astronomical units from the Earth's centre, in scene axes (x to the vernal equinox, y north, z toward -y of the equator).
+ *
+ * @example
+ * ```ts
+ * import { frameAt, type Frame } from "@johnmorrisdotca/chikyu-earth/space";
+ *
+ * const frame: Frame = frameAt(Date.UTC(2026, 10, 2, 12));
+ * console.log(Object.keys(frame.planets).length, frame.spin.toFixed(0));
+ * ```
+ */
+export interface Frame {
+    ms: number;
+    sun: Vec3;
+    moon: Vec3;
+    planets: Record<PlanetName, Vec3>;
+    /** Greenwich sidereal time, in degrees: how far the Earth has turned against the stars. */
+    spin: number;
+}
+/**
+ * The Earth's radius in kilometres, the unit of the scene's distances.
+ *
+ * @example
+ * ```ts
+ * import { EARTH_RADIUS_KM } from "@johnmorrisdotca/chikyu-earth/space";
+ *
+ * console.log(EARTH_RADIUS_KM);
+ * ```
+ */
+export declare const EARTH_RADIUS_KM = 6371;
+/**
+ * Earth radii in one astronomical unit.
+ *
+ * @example
+ * ```ts
+ * import { AU_IN_EARTH_RADII } from "@johnmorrisdotca/chikyu-earth/space";
+ *
+ * console.log(Math.round(AU_IN_EARTH_RADII));
+ * ```
+ */
+export declare const AU_IN_EARTH_RADII: number;
+/**
+ * The state of the sky at `ms`: nine vectors and an angle, in a few tenths of a millisecond. It needs astronomy-engine (an optional peer dependency).
+ *
+ * @param ms - A moment, in milliseconds since the Unix epoch.
+ * @returns The Sun, the Moon and the planets as seen from the Earth's centre, and how far the Earth has turned.
+ *
+ * @example
+ * ```ts
+ * import { frameAt } from "@johnmorrisdotca/chikyu-earth/space";
+ *
+ * const frame = frameAt(Date.UTC(2026, 10, 2, 12));
+ * console.log(frame.moon.map((n) => n.toFixed(4)));
+ * ```
+ */
+export declare function frameAt(ms: number): Frame;
+/**
+ * A frame between two others, `t` from 0 to 1. The spin goes the short way round, so a step under half a turn is right.
+ *
+ * @param a - The earlier frame.
+ * @param b - The later frame.
+ * @param t - How far from `a` to `b`, from 0 to 1.
+ * @returns The frame at that fraction.
+ *
+ * @example
+ * ```ts
+ * import { blend, frameAt } from "@johnmorrisdotca/chikyu-earth/space";
+ *
+ * const start = Date.UTC(2026, 10, 2);
+ * const middle = blend(frameAt(start), frameAt(start + 1000), 0.5);
+ * console.log(middle.ms - start);
+ * ```
+ */
+export declare function blend(a: Frame, b: Frame, t: number): Frame;
+/**
+ * Answers for any moment from two real ones: `at(ms)` asks astronomy-engine only when `ms` leaves the span the last two answers cover, and then looks
+ * `stepMs` ahead, so playing time at a steady rate costs one pair of lookups every `stepMs` and every draw in between is arithmetic.
+ *
+ * @param initialStepMs - How far ahead the second answer looks, in milliseconds.
+ * @returns A track: `at(ms)` for a frame, `lookups` for how many times the ephemeris was asked, `reset()` and `setStep(ms)`.
+ *
+ * @example
+ * ```ts
+ * import { createTrack } from "@johnmorrisdotca/chikyu-earth/space";
+ *
+ * const track = createTrack(1000);
+ * const start = Date.UTC(2026, 10, 2);
+ * for (let step = 0; step < 10; step += 1) track.at(start + step * 50);
+ * console.log(track.lookups);
+ * ```
+ */
+export declare function createTrack(initialStepMs?: number): {
+    at(ms: number): Frame;
+    /** How many times astronomy-engine has been asked for a frame. */
+    readonly lookups: number;
+    reset(): void;
+    /** Look further ahead (a faster game clock): the next lookup uses it. */
+    setStep(ms: number): void;
+};
+/** The path a planet takes round the Sun, as `count` points around the orbit that starts where the planet is at `ms`, relative to the Sun (scene axes, AU).
+ *
+ * @param name - The planet.
+ * @param ms - The moment the orbit starts at, in milliseconds since the Unix epoch.
+ * @param count - How many segments to cut the orbit into.
+ * @returns `count + 1` points, the last on the first.
+ *
+ * @example
+ * ```ts
+ * import { orbitPath } from "@johnmorrisdotca/chikyu-earth/space";
+ *
+ * const points = orbitPath("Jupiter", Date.UTC(2026, 10, 2), 12);
+ * console.log(points.length);
+ * ```
+ */
+export declare function orbitPath(name: PlanetName, ms: number, count?: number): Vec3[];
+/** The Earth's own place relative to the Sun, for placing the orbits round the Sun's place in the Earth-centred scene. */