@driftengine/core 3.61.0

package/dist/core/timeCurve.js

@@ -0,0 +1,107 @@
+import { TAU, clamp } from '../math/scalar.js';
+/**
+ * Ceiling on `amount`.
+ *
+ * Every kind pays its debt back by running the rest of the segment at
+ * `1 / (1 - amount)`, so an amount at 1 asks for infinite speed in zero time.
+ * Capped rather than merely documented: this is the kind of value a tuning pass
+ * pushes to its limit.
+ */
+export const MAX_TIME_CURVE_AMOUNT = 0.9;
+const LINEAR_STEP_SEC = 1;
+/**
+ * Build a curve, validating at construction.
+ *
+ * Fail-fast here rather than per-frame in `curveOffsetSec`: a curve is built
+ * once when a clip is planned, and a plan is a fine place to throw.
+ */
+export function timeCurve(kind, durationSec, options = {}) {
+    if (!Number.isFinite(durationSec) || durationSec <= 0) {
+        throw new Error(`A time curve needs a positive duration, got ${durationSec}`);
+    }
+    const amount = clamp(options.amount ?? 0, 0, MAX_TIME_CURVE_AMOUNT);
+    const requested = options.stepSec ?? LINEAR_STEP_SEC;
+    if (!Number.isFinite(requested) || requested <= 0) {
+        throw new Error(`A stutter step must be positive, got ${requested}`);
+    }
+    /*
+     * Snap the stutter step so a whole number of cycles fits the segment. A
+     * trailing part-cycle would leave the curve mid-freeze at its own end, which
+     * breaks neutrality by exactly the frozen remainder — small, and therefore
+     * the sort of drift that accumulates over a dozen shots without ever looking
+     * like a bug.
+     */
+    const cycles = Math.max(1, Math.round(durationSec / requested));
+    return {
+        kind,
+        durationSec,
+        amount,
+        stepSec: kind === 'stutter' ? durationSec / cycles : requested,
+        reversibleSec: Math.max(0, options.reversibleSec ?? 0),
+    };
+}
+/** A curve that does nothing, for a segment that is played straight. */
+export function linearCurve(durationSec) {
+    return timeCurve('linear', durationSec);
+}
+/**
+ * Source seconds elapsed by `localSec` into the curve.
+ *
+ * Monotonically non-decreasing for every kind except `reverse`, continuous
+ * everywhere, and clamped to the segment — outside it, the neighbouring
+ * segments own the clock.
+ */
+export function curveOffsetSec(curve, localSec) {
+    const duration = curve.durationSec;
+    const local = clamp(localSec, 0, duration);
+    const amount = curve.amount;
+    if (amount === 0)
+        return local;
+    switch (curve.kind) {
+        case 'linear':
+            return local;
+        case 'hold': {
+            // Freeze on the cut, then run fast enough to arrive on time.
+            const frozen = amount * duration;
+            return local <= frozen ? 0 : (local - frozen) / (1 - amount);
+        }
+        case 'ramp': {
+            /*
+             * Slow, fast, slow — an "ease-in-out-in". The rate is
+             * `1 - amount * cos(TAU * t / duration)`, whose integral closes the loop
+             * exactly at the segment's end because a whole cosine period integrates
+             * to zero. Chosen over a hand-tuned easing precisely for that: neutrality
+             * is a consequence of the shape rather than something to correct for.
+             */
+            // determinism: build-time — presentation: remaps a cinematic's playback time, not a tick
+            return local - ((amount * duration) / TAU) * Math.sin((TAU * local) / duration);
+        }
+        case 'stutter': {
+            const step = curve.stepSec;
+            const cycles = Math.floor(local / step);
+            const into = local - cycles * step;
+            const frozen = amount * step;
+            const moving = into <= frozen ? 0 : (into - frozen) / (1 - amount);
+            return cycles * step + moving;
+        }
+        case 'reverse': {
+            // Only as far back as the caller kept states for. With no buffer this is
+            // zero and the segment plays straight.
+            const back = Math.min(amount * duration, curve.reversibleSec);
+            if (back <= 0)
+                return local;
+            if (local <= back)
+                return -local;
+            // Then recover the ground given up *and* the segment itself.
+            return -back + ((local - back) * (duration + back)) / (duration - back);
+        }
+    }
+}
+/**
+ * Source seconds a whole segment consumes — `durationSec` for every kind, and
+ * worth asking for rather than assuming: a caller composing segments needs the
+ * answer the curve actually gives, not the one it promises.
+ */
+export function curveSpanSec(curve) {
+    return curveOffsetSec(curve, curve.durationSec);
+}

package/dist/core/withDefaults.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Fill a defaults object from a partial one, ignoring keys whose value is `undefined`.
+ *
+ * **`{ ...DEFAULTS, ...given }` is the obvious spelling and it destroys the default it was
+ * written to preserve.** A spread copies every own key, including one explicitly set to
+ * `undefined` — so a caller writing `{ retractLambda: settings.lambda }`, where `settings.lambda`
+ * is `number | undefined`, does not fall back to the default. It overwrites it with `undefined`,
+ * and what comes out of the arithmetic downstream is `NaN`.
+ *
+ * That is not a hypothetical: measured on `Boom`, a timing of `{ retractLambda: undefined }` takes
+ * the arm's fraction from 0.96 to `NaN` on the first step, which is a camera that never recovers.
+ * And it is invisible to TypeScript here, because this repository does not run
+ * `exactOptionalPropertyTypes` — the flag that separates "absent" from "present and undefined".
+ * Under it, forty call sites in this tree pass an optional straight into an optional slot; the
+ * pattern is ordinary and the hazard is only in what receives it.
+ *
+ * So the merge is a function rather than a spread, and every `Partial<T>` over a `T` of defaults
+ * goes through it. One implementation, for the reason `Boom`'s own header gives about the arm it
+ * smooths: a third caller must not be able to get this wrong again.
+ */
+export declare function withDefaults<T extends object>(defaults: T, given: Partial<T>): T;

package/dist/core/withDefaults.js

@@ -0,0 +1,29 @@
+/**
+ * Fill a defaults object from a partial one, ignoring keys whose value is `undefined`.
+ *
+ * **`{ ...DEFAULTS, ...given }` is the obvious spelling and it destroys the default it was
+ * written to preserve.** A spread copies every own key, including one explicitly set to
+ * `undefined` — so a caller writing `{ retractLambda: settings.lambda }`, where `settings.lambda`
+ * is `number | undefined`, does not fall back to the default. It overwrites it with `undefined`,
+ * and what comes out of the arithmetic downstream is `NaN`.
+ *
+ * That is not a hypothetical: measured on `Boom`, a timing of `{ retractLambda: undefined }` takes
+ * the arm's fraction from 0.96 to `NaN` on the first step, which is a camera that never recovers.
+ * And it is invisible to TypeScript here, because this repository does not run
+ * `exactOptionalPropertyTypes` — the flag that separates "absent" from "present and undefined".
+ * Under it, forty call sites in this tree pass an optional straight into an optional slot; the
+ * pattern is ordinary and the hazard is only in what receives it.
+ *
+ * So the merge is a function rather than a spread, and every `Partial<T>` over a `T` of defaults
+ * goes through it. One implementation, for the reason `Boom`'s own header gives about the arm it
+ * smooths: a third caller must not be able to get this wrong again.
+ */
+export function withDefaults(defaults, given) {
+    const merged = { ...defaults };
+    for (const key of Object.keys(given)) {
+        const value = given[key];
+        if (value !== undefined)
+            merged[key] = value;
+    }
+    return merged;
+}

package/dist/dev/contactProbe.d.ts

@@ -0,0 +1,41 @@
+import type { Aabb } from '@driftengine/physics';
+import type { ColliderSet } from '@driftengine/physics';
+/**
+ * What is around a box, in numbers a person can check.
+ *
+ * A development tool, not a physics path: `collide.ts` already resolves contacts and
+ * is tuned to do it without allocating. This answers a different question — *which
+ * colliders are here, and by how much* — for a diagnostic that runs when somebody
+ * presses a key, so it favours being readable over being fast.
+ *
+ * Signed depth per axis rather than a single distance, because the two failures worth
+ * telling apart look identical otherwise: a body 5 cm inside a deck and a body 5 cm
+ * above one are both "5 cm from a collider".
+ */
+export interface ContactReport {
+    index: number;
+    /** True where the collider is a hull; its box is then the broad phase only. */
+    hull: boolean;
+    minX: number;
+    minY: number;
+    minZ: number;
+    maxX: number;
+    maxY: number;
+    maxZ: number;
+    /** Overlap along the axis. Positive is penetration, negative is the gap. */
+    depthX: number;
+    depthY: number;
+    depthZ: number;
+    /** Straight line between the boxes. Zero exactly when all three axes overlap. */
+    distanceM: number;
+}
+export declare const CONTACT_LIMIT = 32;
+export declare function createContactReports(count?: number): ContactReport[];
+/**
+ * Describe every collider overlapping `box` or within `radius` of it.
+ *
+ * Returns how many entries of `out` were written. Reports are in query order, which is
+ * spatial-hash order and therefore arbitrary: sort by `distanceM` at the point of
+ * display if order matters, rather than paying for it here.
+ */
+export declare function describeContacts(colliders: ColliderSet, box: Aabb, radius: number, scratch: Int32Array, out: ContactReport[]): number;

package/dist/dev/contactProbe.js

@@ -0,0 +1,58 @@
+export const CONTACT_LIMIT = 32;
+export function createContactReports(count = CONTACT_LIMIT) {
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        out.push({
+            index: -1,
+            hull: false,
+            minX: 0,
+            minY: 0,
+            minZ: 0,
+            maxX: 0,
+            maxY: 0,
+            maxZ: 0,
+            depthX: 0,
+            depthY: 0,
+            depthZ: 0,
+            distanceM: 0,
+        });
+    }
+    return out;
+}
+const SCRATCH_BOUNDS = { minX: 0, minY: 0, minZ: 0, maxX: 0, maxY: 0, maxZ: 0 };
+/**
+ * Describe every collider overlapping `box` or within `radius` of it.
+ *
+ * Returns how many entries of `out` were written. Reports are in query order, which is
+ * spatial-hash order and therefore arbitrary: sort by `distanceM` at the point of
+ * display if order matters, rather than paying for it here.
+ */
+export function describeContacts(colliders, box, radius, scratch, out) {
+    const found = colliders.query(box.minX - radius, box.minY - radius, box.minZ - radius, box.maxX + radius, box.maxY + radius, box.maxZ + radius, scratch);
+    let written = 0;
+    for (let k = 0; k < found && written < out.length; k++) {
+        const index = scratch[k];
+        colliders.bounds(index, SCRATCH_BOUNDS);
+        const depthX = Math.min(box.maxX, SCRATCH_BOUNDS.maxX) - Math.max(box.minX, SCRATCH_BOUNDS.minX);
+        const depthY = Math.min(box.maxY, SCRATCH_BOUNDS.maxY) - Math.max(box.minY, SCRATCH_BOUNDS.minY);
+        const depthZ = Math.min(box.maxZ, SCRATCH_BOUNDS.maxZ) - Math.max(box.minZ, SCRATCH_BOUNDS.minZ);
+        const gapX = Math.max(0, -depthX);
+        const gapY = Math.max(0, -depthY);
+        const gapZ = Math.max(0, -depthZ);
+        const report = out[written];
+        report.index = index;
+        report.hull = colliders.shapeAt(index) !== undefined;
+        report.minX = SCRATCH_BOUNDS.minX;
+        report.minY = SCRATCH_BOUNDS.minY;
+        report.minZ = SCRATCH_BOUNDS.minZ;
+        report.maxX = SCRATCH_BOUNDS.maxX;
+        report.maxY = SCRATCH_BOUNDS.maxY;
+        report.maxZ = SCRATCH_BOUNDS.maxZ;
+        report.depthX = depthX;
+        report.depthY = depthY;
+        report.depthZ = depthZ;
+        report.distanceM = Math.hypot(gapX, gapY, gapZ);
+        written++;
+    }
+    return written;
+}

package/dist/dev/fpsMeter.d.ts

@@ -0,0 +1,45 @@
+/** Throttled DOM frame profiler for development builds. */
+export interface FpsMeterOptions {
+    parent?: HTMLElement;
+    id?: string;
+    updateIntervalMs?: number;
+    sampleWindow?: number;
+    frameBudgetMs?: number;
+    overBudgetClass?: string;
+}
+export declare class FpsMeter {
+    private readonly element;
+    private readonly samples;
+    private readonly updateIntervalMs;
+    private readonly frameBudgetMs;
+    private readonly overBudgetClass;
+    private index;
+    private filled;
+    private lastUpdate;
+    private lastText;
+    private lastFps;
+    private lastMeanMs;
+    private lastWorstMs;
+    constructor(options?: FpsMeterOptions);
+    /**
+     * The rate this meter last computed, for a caller that wants the number as well as the panel.
+     *
+     * **Reported from outside**, by a consumer that had to keep its own average beside this one to
+     * say "the preview is below rate, the export is unaffected". A class that owns an element and
+     * refuses to say what it wrote in it makes every caller measure the same thing twice.
+     *
+     * These are what was last *displayed*, so they move at `updateIntervalMs` rather than per frame,
+     * which is the point: a figure that changes sixty times a second is not one a person reads, and
+     * a caller comparing against a budget wants the same smoothed number the panel shows.
+     *
+     * Zero until the first update, which is a real state and not a rate.
+     */
+    get fps(): number;
+    /** Mean frame time in milliseconds over the window, as last displayed. See `fps`. */
+    get meanMs(): number;
+    /** The slowest frame in the window in milliseconds, as last displayed. See `fps`. */
+    get worstMs(): number;
+    /** Call once per rendered frame with duration in seconds. */
+    sample(frameDt: number, nowMs: number): void;
+    dispose(): void;
+}

package/dist/dev/fpsMeter.js

@@ -0,0 +1,86 @@
+/** Throttled DOM frame profiler for development builds. */
+export class FpsMeter {
+    element;
+    samples;
+    updateIntervalMs;
+    frameBudgetMs;
+    overBudgetClass;
+    index = 0;
+    filled = 0;
+    lastUpdate = 0;
+    lastText = '';
+    lastFps = 0;
+    lastMeanMs = 0;
+    lastWorstMs = 0;
+    constructor(options = {}) {
+        const sampleWindow = options.sampleWindow ?? 60;
+        if (!Number.isInteger(sampleWindow) || sampleWindow <= 0) {
+            throw new Error(`FpsMeter.sampleWindow must be a positive integer, got ${sampleWindow}`);
+        }
+        this.samples = new Float32Array(sampleWindow);
+        this.updateIntervalMs = options.updateIntervalMs ?? 250;
+        this.frameBudgetMs = options.frameBudgetMs ?? 16.7;
+        this.overBudgetClass = options.overBudgetClass ?? 'over-budget';
+        const element = document.createElement('div');
+        element.id = options.id ?? 'fps-meter';
+        (options.parent ?? document.body).append(element);
+        this.element = element;
+    }
+    /**
+     * The rate this meter last computed, for a caller that wants the number as well as the panel.
+     *
+     * **Reported from outside**, by a consumer that had to keep its own average beside this one to
+     * say "the preview is below rate, the export is unaffected". A class that owns an element and
+     * refuses to say what it wrote in it makes every caller measure the same thing twice.
+     *
+     * These are what was last *displayed*, so they move at `updateIntervalMs` rather than per frame,
+     * which is the point: a figure that changes sixty times a second is not one a person reads, and
+     * a caller comparing against a budget wants the same smoothed number the panel shows.
+     *
+     * Zero until the first update, which is a real state and not a rate.
+     */
+    get fps() {
+        return this.lastFps;
+    }
+    /** Mean frame time in milliseconds over the window, as last displayed. See `fps`. */
+    get meanMs() {
+        return this.lastMeanMs;
+    }
+    /** The slowest frame in the window in milliseconds, as last displayed. See `fps`. */
+    get worstMs() {
+        return this.lastWorstMs;
+    }
+    /** Call once per rendered frame with duration in seconds. */
+    sample(frameDt, nowMs) {
+        this.samples[this.index] = frameDt * 1000;
+        this.index = (this.index + 1) % this.samples.length;
+        if (this.filled < this.samples.length)
+            this.filled++;
+        if (nowMs - this.lastUpdate < this.updateIntervalMs)
+            return;
+        this.lastUpdate = nowMs;
+        let total = 0;
+        let worst = 0;
+        for (let sample = 0; sample < this.filled; sample++) {
+            const ms = this.samples[sample] ?? 0;
+            total += ms;
+            if (ms > worst)
+                worst = ms;
+        }
+        const meanMs = total / Math.max(this.filled, 1);
+        const fps = meanMs > 0 ? 1000 / meanMs : 0;
+        this.lastFps = fps;
+        this.lastMeanMs = meanMs;
+        this.lastWorstMs = worst;
+        // Throttled and change-gated: the one sanctioned hot-path string/DOM write.
+        const text = `${fps.toFixed(0)} fps · ${meanMs.toFixed(1)} ms · worst ${worst.toFixed(1)} ms`;
+        if (text === this.lastText)
+            return;
+        this.lastText = text;
+        this.element.textContent = text;
+        this.element.classList.toggle(this.overBudgetClass, worst > this.frameBudgetMs * 1.5);
+    }
+    dispose() {
+        this.element.remove();
+    }
+}

package/dist/environment/celestialClock.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Allocation-free wall-clock sampling for a procedural sun, moon and clouds.
+ *
+ * **Two models, and a caller chooses by whether it names a place.** Without a `CelestialSite` this
+ * is what it has always been: a sun swung through a fixed arc, peaking at the same altitude every
+ * day of every year wherever the world is meant to be. With one, it is the standard solar-position
+ * arithmetic — a declination from the day of the year, an hour angle from the clock, and an
+ * altitude and azimuth from those and the latitude.
+ *
+ * **The simplified model is kept rather than replaced**, and that is the engine's ordinary rule
+ * rather than a soft touch: every world authored against this engine has its lighting tuned against
+ * that arc, and a model that silently moved the sun would move every shadow, every exposure and
+ * every night in every consumer at once. A caller that passes no site gets the same numbers it got
+ * before, bit for bit, which `celestialClock.test.ts` asserts against literals rather than against
+ * a second implementation.
+ *
+ * **What the simplified model gives up, said plainly, because a consumer worked it out for
+ * themselves first:** no latitude, so the sun reaches 66° at noon on the equator and at the pole
+ * alike; no season, so the arc is the same in December as in June; an azimuth that sweeps a whole
+ * turn in a day where a real one swings through rather less; and a moon pinned exactly opposite the
+ * sun, which contradicts the phase reported beside it — a crescent that rises at midnight. All four
+ * are fixed by naming a site.
+ *
+ * **A site can also name its clock, and until 2026-09-03 nothing could.** The hour was read off the
+ * timestamp through the *host machine's* time zone, so one argument put the sun in four places on
+ * four machines — solar noon at 12:00 under `TZ=UTC`, 10:00 in Rome, 16:00 in New York, 03:00 in
+ * Tokyo — and the only way to say an hour was to build a timestamp whose host offset cancelled the
+ * one being added. `longitudeDeg` and `utcOffsetHours` are the way to say it instead: either one
+ * makes the timestamp a UTC instant and the engine derives the site's own hour, so the sky is a
+ * function of the arguments alone. It was found by a player in Italy watching the sun set before
+ * six, which is what the workaround cost when the host disagreed with the world.
+ */
+import type { Vec3 } from '../math/color.ts';
+/**
+ * Where in the world, and when in the year, the sky is being sampled.
+ *
+ * **A site rather than a latitude alone**, because latitude and season are one question: the sun's
+ * altitude is a function of the declination *and* the latitude, and a model with one and not the
+ * other is wrong in a way that only shows up six months later.
+ */
+export interface CelestialSite {
+    /**
+     * Degrees north of the equator, −90 to 90. Clamped rather than refused, because a value past a
+     * pole is a caller's arithmetic overshooting rather than a request for something impossible.
+     */
+    readonly latitudeDeg: number;
+    /**
+     * Degrees east of Greenwich, −180 to 180, or absent.
+     *
+     * **Naming this or `utcOffsetHours` changes what the timestamp means**: it stops being read
+     * through the host machine's time zone and becomes a plain UTC instant, from which this site's
+     * own hour is derived. See `celestialStateAt`. Not clamped, because a longitude is an angle and
+     * a value past the antimeridian means the place a turn around says it does.
+     *
+     * Alone, it also stands in for the zone: a place is assumed to keep the time of its own
+     * meridian, which is exact solar time and differs from a real zone by up to half an hour.
+     */
+    readonly longitudeDeg?: number;
+    /**
+     * Hours this site's wall clock runs ahead of UTC — `2` for Italy in summer — or absent.
+     *
+     * The other half of the pair above, and the same switch: naming it makes the timestamp a UTC
+     * instant. It is what turns that instant into the site's *calendar day*, which is the one thing
+     * a longitude cannot do; with `longitudeDeg` beside it the sun also stops sitting at the zone's
+     * centre and moves to the place's real meridian, up to half an hour either way.
+     *
+     * **Daylight saving is the caller's**, because a zone's offset is a function of the date and of
+     * legislation, and an engine that shipped a table of it would ship a table that expires.
+     */
+    readonly utcOffsetHours?: number;
+    /**
+     * Day of the year, 1 to 365, or absent to take it from the timestamp.
+     *
+     * Present because a world may run on a calendar of its own — a game whose year is forty days
+     * still wants a season — and taking it from the timestamp would tie that to the wall clock.
+     */
+    readonly dayOfYear?: number;
+    /**
+     * The planet's axial tilt in degrees. Earth's 23.44 by default.
+     *
+     * Zero is a world with no seasons at all, where the sun's arc is the same every day and depends
+     * on latitude alone; larger values are a world with sharper ones. It is here because it costs one
+     * multiply and because a stylised world is exactly the consumer this engine has.
+     */
+    readonly obliquityDeg?: number;
+}
+export interface CelestialState {
+    sunDir: Vec3;
+    moonDir: Vec3;
+    /** 0 at night, 1 in full day. Smoothstepped across the twilight band. */
+    dayFactor: number;
+    nightFactor: number;
+    /** Wrapped scroll distance suitable for a highp shader uniform. */
+    /** 0..1 across the lunar cycle. */
+    moonPhase: number;
+}
+export declare function createCelestialState(): CelestialState;
+/** Visible fraction: new at 0/1, quarters at 0.25/0.75, full at 0.5. */
+export declare function moonIllumination(phase: number): number;
+/**
+ * Convert a timestamp and an authored azimuth into sky state.
+ *
+ * The caller decides where the timestamp comes from and must keep it out of a deterministic
+ * simulation if wall time should not affect gameplay.
+ *
+ * `sunAzimuth` is **where the world's north points**, as an angle in the xz plane from +x toward
+ * +z. It was an arbitrary offset in the model that knows no latitude and it means the same thing
+ * there; with a site it becomes load-bearing, because the sun's own azimuth is then derived and
+ * this is what relates it to the world's axes.
+ *
+ * **`site` is what turns the simplified model into the sited one**, and omitting it is not a
+ * degraded mode — it is the model every world here was authored against. See the header.
+ *
+ * **Which hour the timestamp names depends on whether the site states a zone**, and that is the
+ * one thing to get right before anything else here matters:
+ *
+ * - **A site naming `longitudeDeg` or `utcOffsetHours`** makes `whenMs` a plain **UTC instant** —
+ *   `Date.now()`, or `Date.UTC(…)` for an hour chosen outright — and the engine derives that
+ *   site's own hour from it. The answer is then a function of the arguments and of nothing else,
+ *   which is the only form that gives every machine the same sky.
+ * - **A site naming neither, or no site at all**, reads the hour off the timestamp through the
+ *   **host machine's** time zone, which is what this function has always done. Every world
+ *   authored against it is tuned that way, so it is kept exactly: the same argument gives the same
+ *   numbers, bit for bit. But the same argument on another machine gives another hour, so a caller
+ *   in this form must build the timestamp from local parts — `new Date(y, m, d, h)` — for the
+ *   host's offset to cancel rather than be added.
+ *
+ * **`moonPhase` is the reason the first form is worth taking even where the sun already looks
+ * right.** It comes from the timestamp's absolute value rather than from the hour, so the
+ * build-it-from-local-parts trick that steadies the sun leaves the moon drifting by the host's
+ * offset — a fiftieth of a lunar cycle across the world, invisible and still not a fact about the
+ * world.
+ *
+ * **The equation of time stays the caller's**, and it is the last correction left: a real sun runs
+ * up to about a quarter of an hour ahead of or behind mean time across the year, from the Earth's
+ * eccentricity and its tilt. The zone and the meridian are the engine's as soon as a site states
+ * them; this one is not, because it is a property of the planet's orbit rather than of the place,
+ * and a world with an obliquity of its own has an equation of time of its own. A caller measuring
+ * a shadow against an almanac applies it to the timestamp; a caller lighting a world does not care.
+ */
+export declare function celestialStateAt(whenMs: number, sunAzimuth: number, out: CelestialState, site?: CelestialSite): void;