@driftengine/core 3.61.0

package/dist/core/rng.js

@@ -0,0 +1,72 @@
+/**
+ * Seeded PRNG (mulberry32). The only randomness source allowed in simulation
+ * and world generation — `Math.random()` is banned there (see AGENTS.md).
+ * Same seed ⇒ same sequence on every platform.
+ */
+/**
+ * Deterministically choose one item from a list.
+ *
+ * The seed is hashed before the modulo rather than used raw. `seed % length`
+ * walks the list in order, so consecutive seeds — day numbers, level indices —
+ * produce a visible cycle; multiplying by the golden-ratio constant first
+ * scatters them, which is the difference between "today's track" feeling picked
+ * and feeling like a rota.
+ */
+export function pickBySeed(seed, items) {
+    if (items.length === 0)
+        return null;
+    const scrambled = Math.abs(Math.imul(seed | 0, 0x9e3779b1)) % items.length;
+    return items[scrambled] ?? null;
+}
+/**
+ * A single well-mixed value in `[0, 1)` from one integer seed.
+ *
+ * `mulberry32`'s mixer without the stream: the same avalanche, applied once, for the
+ * very common case of "one deterministic value per index" — a per-particle jitter, a
+ * per-node displacement — where allocating a generator per lookup is absurd.
+ *
+ * It exists because the obvious alternative is wrong in a way that is hard to see.
+ * `fract(sin(x) * 43758.5453)` is the reflex GPU hash and it degrades badly on the CPU
+ * for large `x`: `sin` of a number in the millions has lost most of its precision to
+ * argument reduction, so nearby seeds correlate and *whole families of values collapse
+ * onto each other*. That is what an effect seeded from a tick count hands it. Measured
+ * as lightning whose every bolt came out the same shape however much variation the
+ * caller thought it was asking for: still visibly deterministic where the caller
+ * expected a fresh shape on every strike.
+ *
+ * Integer mixing has no such failure: every bit of the input reaches every bit of the
+ * output, at any magnitude, and it is bit-identical on every platform, which the
+ * replay contract requires.
+ */
+export function hashToUnit(seed) {
+    let t = (seed | 0) + 0x6d2b79f5;
+    t = Math.imul(t ^ (t >>> 15), 1 | t);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+}
+export function mulberry32(seed) {
+    let state = seed | 0;
+    return () => {
+        state = (state + 0x6d2b79f5) | 0;
+        let t = Math.imul(state ^ (state >>> 15), 1 | state);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+export function savableMulberry32(seed) {
+    let state = seed | 0;
+    return {
+        next() {
+            state = (state + 0x6d2b79f5) | 0;
+            let t = Math.imul(state ^ (state >>> 15), 1 | state);
+            t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+            return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+        },
+        save() {
+            return state;
+        },
+        restore(next) {
+            state = next | 0;
+        },
+    };
+}

package/dist/core/stepBudget.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Spending a slice of a frame on work that can stop, without spending more than the slice.
+ *
+ * A **budgeted step pump**: the caller has some job — building a square of world, uploading a
+ * mesh, decoding a model — that can be broken into indivisible units, and wants to advance it
+ * a little every frame without the frame noticing. This holds the clock and the arithmetic;
+ * the caller holds the work and decides what to do next.
+ *
+ * **What it guarantees, in the honest words:** a call costs the larger of the budget and one
+ * uninterrupted stop. Not the budget. A stop cannot be interrupted from outside, so the only
+ * way to bound a call by the budget alone would be to bound every stop, which is the caller's
+ * job and not this one's — see `worstIn`, which exists to say which of the caller's units is
+ * the one over the line.
+ *
+ * **Why this rather than a count of units.** A count bounds the cheap term and leaves the
+ * expensive one free. `assets/uploadBudget.ts` records the measurement that established it:
+ * the parts of a model cost between 6 and 254 ms each, so three per frame was three of
+ * whatever they happened to be. The clock is exact, needs no per-asset tuning, and is as
+ * right on a phone as on a workstation.
+ *
+ * Nothing here touches a renderer or a device, on purpose: the property worth testing is a
+ * whole number of stops, and a test that needed a GPU could not assert it.
+ */
+export interface StepBudgetOptions {
+    /**
+     * The clock, in milliseconds.
+     *
+     * Injected so a test can move time by hand. Every property this class has is a whole number
+     * of milliseconds and a whole number of stops; measuring them against a real clock would be
+     * measuring the machine the suite ran on.
+     */
+    readonly now?: () => number;
+    /**
+     * How fast the worst-stop estimate forgets, as a factor applied once per call.
+     *
+     * One per cent by default, and the number is load-bearing. Five per cent was tried by a
+     * consumer and is wrong: the estimate falls below the real cost inside a single crossing of
+     * a town, the guard lets a second stop start with no room for it, and a call costs the
+     * budget *plus* a stop rather than the larger of the two — which is the whole thing the
+     * guard exists to prevent.
+     */
+    readonly forget?: number;
+}
+export declare class StepBudget<Label = string> {
+    private readonly clock;
+    private readonly forget;
+    /**
+     * What one more stop is assumed to cost, and therefore whether there is room for it.
+     *
+     * The largest stop seen so far, decayed a little each call. It starts at zero, which means
+     * the first call of a program's life overshoots by one stop and learns from it — the price
+     * of not asking a caller to declare a number it cannot know.
+     */
+    private guard;
+    private worstEver;
+    private worstEverIn;
+    constructor(options?: StepBudgetOptions);
+    /** What one more stop is currently assumed to cost. Decays; see `StepBudgetOptions.forget`. */
+    get estimate(): number;
+    /** The longest single stop ever taken. Does not decay: this is the report, not the guard. */
+    get worst(): number;
+    /**
+     * The label the caller gave the longest stop.
+     *
+     * **A budget being blown is useless information without the name of the unit that blew it.**
+     * That is the whole reason `next` returns a label rather than a boolean: "the worst stop was
+     * 57 ms" sends a reader nowhere, and "the worst stop was 57 ms, in upload" sends them to one
+     * file.
+     */
+    get worstIn(): Label | null;
+    /**
+     * Advance the caller's work for up to `budgetMs`, and say how many stops that took.
+     *
+     * `next` performs exactly one indivisible unit and returns a label naming what it did, or
+     * `null` when there is nothing left to do — which ends the call without counting a stop.
+     *
+     * **Return the label of the work just done, not of the work about to be done.** The two are
+     * easy to confuse where a job names its own next phase, and the report that results sends a
+     * reader to the wrong builder every time the phase changes.
+     *
+     * The two rules the loop is made of, both arrived at by getting them wrong first:
+     *
+     * - *Do not start what you cannot finish.* A driver that keeps going while any budget
+     *   remains overshoots by a whole stop. Measured by a consumer at 30 Hz: 8.3 ms of budget
+     *   plus an 8.6 ms stop against a frame of 16.7.
+     * - *But always do one.* Without the unconditional first stop, a unit costing more than the
+     *   whole budget means nothing ever advances at all, and a world that never loads is worse
+     *   than a frame that runs long.
+     */
+    spend(budgetMs: number, next: () => Label | null): number;
+}

package/dist/core/stepBudget.js

@@ -0,0 +1,105 @@
+/**
+ * Spending a slice of a frame on work that can stop, without spending more than the slice.
+ *
+ * A **budgeted step pump**: the caller has some job — building a square of world, uploading a
+ * mesh, decoding a model — that can be broken into indivisible units, and wants to advance it
+ * a little every frame without the frame noticing. This holds the clock and the arithmetic;
+ * the caller holds the work and decides what to do next.
+ *
+ * **What it guarantees, in the honest words:** a call costs the larger of the budget and one
+ * uninterrupted stop. Not the budget. A stop cannot be interrupted from outside, so the only
+ * way to bound a call by the budget alone would be to bound every stop, which is the caller's
+ * job and not this one's — see `worstIn`, which exists to say which of the caller's units is
+ * the one over the line.
+ *
+ * **Why this rather than a count of units.** A count bounds the cheap term and leaves the
+ * expensive one free. `assets/uploadBudget.ts` records the measurement that established it:
+ * the parts of a model cost between 6 and 254 ms each, so three per frame was three of
+ * whatever they happened to be. The clock is exact, needs no per-asset tuning, and is as
+ * right on a phone as on a workstation.
+ *
+ * Nothing here touches a renderer or a device, on purpose: the property worth testing is a
+ * whole number of stops, and a test that needed a GPU could not assert it.
+ */
+/** A per-call decay of the guard: a half-life of sixty-nine calls, a little over a second at 60 Hz. */
+const DEFAULT_FORGET = 0.99;
+export class StepBudget {
+    clock;
+    forget;
+    /**
+     * What one more stop is assumed to cost, and therefore whether there is room for it.
+     *
+     * The largest stop seen so far, decayed a little each call. It starts at zero, which means
+     * the first call of a program's life overshoots by one stop and learns from it — the price
+     * of not asking a caller to declare a number it cannot know.
+     */
+    guard = 0;
+    worstEver = 0;
+    worstEverIn = null;
+    constructor(options = {}) {
+        this.clock = options.now ?? (() => performance.now());
+        this.forget = options.forget ?? DEFAULT_FORGET;
+    }
+    /** What one more stop is currently assumed to cost. Decays; see `StepBudgetOptions.forget`. */
+    get estimate() {
+        return this.guard;
+    }
+    /** The longest single stop ever taken. Does not decay: this is the report, not the guard. */
+    get worst() {
+        return this.worstEver;
+    }
+    /**
+     * The label the caller gave the longest stop.
+     *
+     * **A budget being blown is useless information without the name of the unit that blew it.**
+     * That is the whole reason `next` returns a label rather than a boolean: "the worst stop was
+     * 57 ms" sends a reader nowhere, and "the worst stop was 57 ms, in upload" sends them to one
+     * file.
+     */
+    get worstIn() {
+        return this.worstEverIn;
+    }
+    /**
+     * Advance the caller's work for up to `budgetMs`, and say how many stops that took.
+     *
+     * `next` performs exactly one indivisible unit and returns a label naming what it did, or
+     * `null` when there is nothing left to do — which ends the call without counting a stop.
+     *
+     * **Return the label of the work just done, not of the work about to be done.** The two are
+     * easy to confuse where a job names its own next phase, and the report that results sends a
+     * reader to the wrong builder every time the phase changes.
+     *
+     * The two rules the loop is made of, both arrived at by getting them wrong first:
+     *
+     * - *Do not start what you cannot finish.* A driver that keeps going while any budget
+     *   remains overshoots by a whole stop. Measured by a consumer at 30 Hz: 8.3 ms of budget
+     *   plus an 8.6 ms stop against a frame of 16.7.
+     * - *But always do one.* Without the unconditional first stop, a unit costing more than the
+     *   whole budget means nothing ever advances at all, and a world that never loads is worse
+     *   than a frame that runs long.
+     */
+    spend(budgetMs, next) {
+        const started = this.clock();
+        let stops = 0;
+        for (;;) {
+            const elapsed = this.clock() - started;
+            if (stops > 0 && elapsed + this.guard > budgetMs)
+                break;
+            const began = this.clock();
+            const did = next();
+            if (did === null)
+                break;
+            const took = this.clock() - began;
+            if (took > this.guard)
+                this.guard = took;
+            if (took > this.worstEver) {
+                this.worstEver = took;
+                this.worstEverIn = did;
+            }
+            stops += 1;
+        }
+        /* And the estimate forgets, or one bad stop holds the queue for ever. */
+        this.guard *= this.forget;
+        return stops;
+    }
+}

package/dist/core/storage.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Where persisted state goes.
+ *
+ * The engine must not assume a browser origin. A game may want its saves on a
+ * server, in a native shell's own store, in an embedder-provided sandbox, or
+ * nowhere at all — so every engine system that persists takes a
+ * `KeyValueStore` and the browser is merely the default implementation.
+ *
+ * **Synchronous by design.** Preferences, one-time flags and a chosen character
+ * are all read during boot, before the first frame, and an await there means a
+ * frame rendered with the wrong settings and then corrected — a visible flicker
+ * on every load. An asynchronous backend (a server, IndexedDB) fits by
+ * hydrating a cache first and implementing `write` as fire-and-forget; that is
+ * what `MemoryStore.hydrate` exists for.
+ *
+ * No implementation here throws. Storage failure is a normal condition — Safari
+ * private mode and several embedded webviews throw on plain access — and a
+ * preference is never worth failing a boot for.
+ */
+export interface KeyValueStore {
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+    remove(key: string): void;
+}
+/** Volatile store: the test double, and the fallback when nothing persists. */
+export declare class MemoryStore implements KeyValueStore {
+    private readonly entries;
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+    remove(key: string): void;
+    /** Seed from an asynchronous backend before anything reads. */
+    hydrate(entries: Iterable<readonly [string, string]>): void;
+}
+/**
+ * `localStorage`, with every access guarded.
+ *
+ * A blocked store degrades to memory rather than to nothing: settings then last
+ * the session instead of resetting between screens, and a first-run prompt
+ * fires once per visit instead of on every single load. Never showing it at all
+ * would be the worse failure — a player who arrived from a link would have no
+ * idea what the controls are.
+ */
+export declare class BrowserStore implements KeyValueStore {
+    private readonly fallback;
+    private readonly available;
+    constructor();
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+    remove(key: string): void;
+}
+/** The default store: the browser's when it works, memory when it does not. */
+export declare function defaultStore(): KeyValueStore;

package/dist/core/storage.js

@@ -0,0 +1,85 @@
+/** Volatile store: the test double, and the fallback when nothing persists. */
+export class MemoryStore {
+    entries = new Map();
+    read(key) {
+        return this.entries.get(key) ?? null;
+    }
+    write(key, value) {
+        this.entries.set(key, value);
+    }
+    remove(key) {
+        this.entries.delete(key);
+    }
+    /** Seed from an asynchronous backend before anything reads. */
+    hydrate(entries) {
+        for (const [key, value] of entries)
+            this.entries.set(key, value);
+    }
+}
+/**
+ * `localStorage`, with every access guarded.
+ *
+ * A blocked store degrades to memory rather than to nothing: settings then last
+ * the session instead of resetting between screens, and a first-run prompt
+ * fires once per visit instead of on every single load. Never showing it at all
+ * would be the worse failure — a player who arrived from a link would have no
+ * idea what the controls are.
+ */
+export class BrowserStore {
+    fallback = new MemoryStore();
+    available;
+    constructor() {
+        this.available = probeLocalStorage();
+    }
+    read(key) {
+        if (!this.available)
+            return this.fallback.read(key);
+        try {
+            return localStorage.getItem(key);
+        }
+        catch {
+            return this.fallback.read(key);
+        }
+    }
+    write(key, value) {
+        this.fallback.write(key, value);
+        if (!this.available)
+            return;
+        try {
+            localStorage.setItem(key, value);
+        }
+        catch {
+            // Quota exceeded or blocked mid-session; the memory copy still stands.
+        }
+    }
+    remove(key) {
+        this.fallback.remove(key);
+        if (!this.available)
+            return;
+        try {
+            localStorage.removeItem(key);
+        }
+        catch {
+            // As above.
+        }
+    }
+}
+function probeLocalStorage() {
+    try {
+        // Reading is not enough of a probe: some browsers allow the read and throw
+        // only on write, which would strand a store that reports itself healthy.
+        const probe = '__driftengine_probe__';
+        localStorage.setItem(probe, '1');
+        localStorage.removeItem(probe);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+let shared = null;
+/** The default store: the browser's when it works, memory when it does not. */
+export function defaultStore() {
+    shared ??= new BrowserStore();
+    return shared;
+}

package/dist/core/tickTrace.d.ts

@@ -0,0 +1,72 @@
+/**
+ * What a fixed-step simulation produced, tick by tick.
+ *
+ * Replaying a recorded run means re-running the simulation, which is far too
+ * expensive to do inside a frame and cannot be seeked into at all — an intent
+ * stream has no keyframes, so reaching tick 4,000 means running the four
+ * thousand before it. Running it *once*, up front, and keeping what each tick
+ * produced turns a replay from a simulation into a lookup.
+ *
+ * A flat `Float32Array` of `channels` values per tick, plus one byte of flags for
+ * the booleans that would otherwise cost four bytes each. Preallocate with
+ * `capacity` when the length is known — a caller replaying a recording always
+ * knows it — and nothing reallocates while the simulation is running.
+ */
+export interface TickTraceLike {
+    readonly length: number;
+    readonly channels: number;
+    sample(tick: number, out: Float32Array): void;
+    flagsAt(tick: number): number;
+    channelAt(tick: number, channel: number): number;
+    tickAtOrBefore(channel: number, value: number): number;
+}
+export declare class TickTrace implements TickTraceLike {
+    readonly channels: number;
+    private values;
+    private flags;
+    private count;
+    constructor(channels: number, capacity?: number);
+    get length(): number;
+    push(values: ArrayLike<number>, flags?: number): void;
+    /**
+     * The state at a tick, clamped to the range that exists.
+     *
+     * Clamped rather than refused because both ends are ordinary rather than
+     * exceptional: a caller one tick past the end is a character who has finished, and
+     * holding their last state is exactly what they should look like.
+     */
+    sample(tick: number, out: Float32Array): void;
+    channelAt(tick: number, channel: number): number;
+    flagsAt(tick: number): number;
+    /**
+     * The last tick at which a non-decreasing channel was at or below `value`.
+     *
+     * This is how two runs of the same course are compared **at the same point on
+     * the course** rather than at the same moment in time. Comparing by time drifts
+     * the instant one character takes a wider line; comparing by distance does not,
+     * which is what makes the difference a split rather than a guess.
+     *
+     * The **last** tick of a run of equal values, not the first, and that matters
+     * wherever the channel can stall: a character who stopped for half a second has a
+     * plateau, and answering its first tick would report them ahead by the whole
+     * length of the stall.
+     *
+     * The channel must be non-decreasing. Binary search over anything else returns
+     * an answer that is merely arbitrary rather than obviously wrong, so a caller
+     * whose channel can go backwards must clamp it on the way in.
+     *
+     * `-1` on an empty trace: there is no tick to name, and 0 would be a lie about
+     * a tick that does not exist.
+     */
+    tickAtOrBefore(channel: number, value: number): number;
+    private clamp;
+    /**
+     * Both arrays double together.
+     *
+     * They are parallel and they are separate allocations, which is exactly how
+     * they come apart: a values array that grew while the flags one did not would
+     * read every flag past the old boundary as zero, and zero is a legal flag
+     * rather than an error anybody would notice.
+     */
+    private grow;
+}

package/dist/core/tickTrace.js

@@ -0,0 +1,102 @@
+export class TickTrace {
+    channels;
+    values;
+    flags;
+    count = 0;
+    constructor(channels, capacity = 256) {
+        this.channels = Math.max(1, channels | 0);
+        const slots = Math.max(1, capacity | 0);
+        this.values = new Float32Array(slots * this.channels);
+        this.flags = new Uint8Array(slots);
+    }
+    get length() {
+        return this.count;
+    }
+    push(values, flags = 0) {
+        if ((this.count + 1) * this.channels > this.values.length)
+            this.grow();
+        const at = this.count * this.channels;
+        for (let i = 0; i < this.channels; i++)
+            this.values[at + i] = values[i] ?? 0;
+        this.flags[this.count] = flags & 0xff;
+        this.count++;
+    }
+    /**
+     * The state at a tick, clamped to the range that exists.
+     *
+     * Clamped rather than refused because both ends are ordinary rather than
+     * exceptional: a caller one tick past the end is a character who has finished, and
+     * holding their last state is exactly what they should look like.
+     */
+    sample(tick, out) {
+        const at = this.clamp(tick) * this.channels;
+        for (let i = 0; i < this.channels; i++)
+            out[i] = this.values[at + i] ?? 0;
+    }
+    channelAt(tick, channel) {
+        return this.values[this.clamp(tick) * this.channels + channel] ?? 0;
+    }
+    flagsAt(tick) {
+        return this.flags[this.clamp(tick)] ?? 0;
+    }
+    /**
+     * The last tick at which a non-decreasing channel was at or below `value`.
+     *
+     * This is how two runs of the same course are compared **at the same point on
+     * the course** rather than at the same moment in time. Comparing by time drifts
+     * the instant one character takes a wider line; comparing by distance does not,
+     * which is what makes the difference a split rather than a guess.
+     *
+     * The **last** tick of a run of equal values, not the first, and that matters
+     * wherever the channel can stall: a character who stopped for half a second has a
+     * plateau, and answering its first tick would report them ahead by the whole
+     * length of the stall.
+     *
+     * The channel must be non-decreasing. Binary search over anything else returns
+     * an answer that is merely arbitrary rather than obviously wrong, so a caller
+     * whose channel can go backwards must clamp it on the way in.
+     *
+     * `-1` on an empty trace: there is no tick to name, and 0 would be a lie about
+     * a tick that does not exist.
+     */
+    tickAtOrBefore(channel, value) {
+        if (this.count === 0)
+            return -1;
+        let low = 0;
+        let high = this.count - 1;
+        if (this.channelAt(low, channel) > value)
+            return 0;
+        while (low < high) {
+            // Biased upward, so `low` can actually reach `high` and the loop ends.
+            const mid = (low + high + 1) >> 1;
+            if (this.channelAt(mid, channel) <= value)
+                low = mid;
+            else
+                high = mid - 1;
+        }
+        return low;
+    }
+    clamp(tick) {
+        if (this.count === 0)
+            return 0;
+        if (tick < 0)
+            return 0;
+        return tick >= this.count ? this.count - 1 : tick | 0;
+    }
+    /**
+     * Both arrays double together.
+     *
+     * They are parallel and they are separate allocations, which is exactly how
+     * they come apart: a values array that grew while the flags one did not would
+     * read every flag past the old boundary as zero, and zero is a legal flag
+     * rather than an error anybody would notice.
+     */
+    grow() {
+        const values = new Float32Array(this.values.length * 2);
+        values.set(this.values);
+        this.values = values;
+        const flags = new Uint8Array(this.flags.length * 2);
+        flags.set(this.flags);
+        this.flags = flags;
+    }
+}

package/dist/core/timeCurve.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Re-timing a stretch of playback: how much *source* time one second of clip
+ * time is worth.
+ *
+ * A curve is a reparameterisation, not an animation. It answers exactly one
+ * question — "given `localSec` into this segment, how far has the source
+ * advanced?" — which is what lets a caller drive a fixed-timestep simulation, a
+ * recorded stream or a video from the same maths.
+ *
+ * **Every curve is speed-neutral over its own segment**: whatever it steals it
+ * pays back, so `curveSpanSec` equals `durationSec` for every kind. That is the
+ * property that keeps a re-timed clip the length it was asked for. A curve that
+ * slowed time without catching up would quietly shorten the footage a fixed
+ * clip length can cover, and the clip would stop before the thing it was cut
+ * for.
+ *
+ * Pure, closed-form and allocation-free: evaluated once per rendered frame.
+ */
+export type TimeCurveKind = 'linear' | 'hold' | 'ramp' | 'stutter' | 'reverse';
+export interface TimeCurve {
+    readonly kind: TimeCurveKind;
+    /** Length of the segment on the clip's own clock, seconds. */
+    readonly durationSec: number;
+    /**
+     * How much of the segment the effect claims, 0–1.
+     *
+     * `hold`: the fraction frozen. `ramp`: the depth of the rate swing.
+     * `stutter`: the frozen fraction of each step. `reverse`: the fraction run
+     * backwards. Zero makes every kind behave as `linear`, which is the honest
+     * neutral rather than a special case to branch on.
+     */
+    readonly amount: number;
+    /** `stutter` only: one freeze-and-catch-up cycle, seconds. */
+    readonly stepSec: number;
+    /**
+     * `reverse` only: how far back the *caller* can actually go, in source
+     * seconds.
+     *
+     * Running a re-simulated stream backwards is impossible without keeping the
+     * states to go back to, so the reversible window is a property of the
+     * consumer's buffer and has to be supplied rather than assumed. A curve never
+     * returns an offset below `-reversibleSec`; a consumer with no buffer passes
+     * zero and gets no reversal at all.
+     */
+    readonly reversibleSec: number;
+}
+export interface TimeCurveOptions {
+    readonly amount?: number;
+    readonly stepSec?: number;
+    readonly reversibleSec?: number;
+}
+/**
+ * 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 declare const MAX_TIME_CURVE_AMOUNT = 0.9;
+/**
+ * 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 declare function timeCurve(kind: TimeCurveKind, durationSec: number, options?: TimeCurveOptions): TimeCurve;
+/** A curve that does nothing, for a segment that is played straight. */
+export declare function linearCurve(durationSec: number): TimeCurve;
+/**
+ * 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 declare function curveOffsetSec(curve: TimeCurve, localSec: number): number;
+/**
+ * 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 declare function curveSpanSec(curve: TimeCurve): number;