@remix-gg/three 0.1.1

package/dist/ramp.d.ts

@@ -0,0 +1,39 @@
+import { type Easing, type EasingName } from './juice.js';
+/**
+ * Difficulty over time, as a clamped curve.
+ *
+ * The hand-rolled version is `speed += 0.001` in update — linear, uncapped,
+ * and unplayable by the sixty-second mark, which is exactly when a good run is
+ * getting interesting. A ramp is a *shape*: where it starts, where it tops
+ * out, how long it takes to get there, and how the difficulty is distributed
+ * along the way. The cap is built in because every endless game needs one and
+ * the hand-rolled version never has one.
+ */
+export type RampOptions = {
+    /** The value at 0 — the first ten seconds, which should be easy. */
+    from: number;
+    /** The cap. Reached at `over` and held forever after. */
+    to: number;
+    /** Seconds (or metres, or points — whatever drives it) to reach the cap. */
+    over: number;
+    /**
+     * How difficulty is distributed. 'quadIn' (the default) rises gently early
+     * and steepens late: a forgiving opening while the player finds the verb,
+     * with the pressure arriving once they have it. 'quadOut' front-loads it.
+     */
+    curve?: EasingName | Easing;
+};
+/**
+ * A pure function of progress: `speed(game.time.elapsed)`.
+ *
+ *     const speed = createRamp({ from: 8, to: 22, over: 75 })
+ *     update(game, step) {
+ *       player.position.z -= speed(game.time.elapsed) * step
+ *     }
+ *
+ * Drive it by elapsed time, distance, or score — anything monotonic. Several
+ * ramps can share one input: speed on 75s, spawn density on 90s, gap width
+ * shrinking on 60s, so the pressure arrives in layers instead of all at once.
+ */
+export declare function createRamp(options: RampOptions): (progress: number) => number;
+//# sourceMappingURL=ramp.d.ts.map

package/dist/ramp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ramp.d.ts","sourceRoot":"","sources":["../src/ramp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,UAAU,EAAW,MAAM,YAAY,CAAA;AAElE;;;;;;;;;GASG;AAEH,MAAM,MAAM,WAAW,GAAG;IACxB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAA;IACV,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAU7E"}

package/dist/ramp.js

@@ -0,0 +1,24 @@
+import { easings } from './juice.js';
+/**
+ * A pure function of progress: `speed(game.time.elapsed)`.
+ *
+ *     const speed = createRamp({ from: 8, to: 22, over: 75 })
+ *     update(game, step) {
+ *       player.position.z -= speed(game.time.elapsed) * step
+ *     }
+ *
+ * Drive it by elapsed time, distance, or score — anything monotonic. Several
+ * ramps can share one input: speed on 75s, spawn density on 90s, gap width
+ * shrinking on 60s, so the pressure arrives in layers instead of all at once.
+ */
+export function createRamp(options) {
+    if (!(options.over > 0))
+        throw new Error(`createRamp: over must be > 0, got ${options.over}`);
+    const curve = typeof options.curve === 'function' ? options.curve : easings[options.curve ?? 'quadIn'];
+    if (!curve)
+        throw new Error(`createRamp: unknown easing '${String(options.curve)}'`);
+    return (progress) => {
+        const t = Math.min(Math.max(progress / options.over, 0), 1);
+        return options.from + (options.to - options.from) * curve(t);
+    };
+}

package/dist/random.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Randomness that feels fair.
+ *
+ * `Math.random()` is stateless, and stateless rolls streak: a 25% crit chance
+ * misses eight times in a row for one player in ten thousand attacks, and that
+ * player experiences a broken game, not an unlucky one. Players expect random
+ * events to self-correct over a handful of trials — real independence does not —
+ * so a repeated player-facing roll wants a distribution that is *guaranteed*
+ * over a short cycle and merely *shuffled* within it.
+ *
+ * That is the shuffle bag (the "marble bag"): fill a bag with the outcomes in
+ * their intended ratio, draw without replacement, refill and reshuffle when it
+ * empties. A 1-in-4 crit is then exactly one crit in every four attacks, the
+ * worst possible drought is bounded by construction (2 × (cycle − 1) misses,
+ * when a crit opens one cycle and closes the next), and the ratio is still
+ * honest over any long run.
+ *
+ * This lives in the SDK rather than in prompt prose because every game that
+ * hand-rolls it gets a different one — usually with the `sort(() => r - 0.5)`
+ * shuffle, which is biased on every engine — and because an injectable RNG is
+ * what makes game logic deterministic under test and daily-challenge seeds
+ * reproducible across players.
+ */
+export type ShuffleBagEntry<T> = {
+    /** What `draw()` returns when this marble comes up. */
+    value: T;
+    /** How many of this marble go into each cycle. A positive integer. */
+    count: number;
+};
+export type ShuffleBagOptions = {
+    /**
+     * The random source, returning [0, 1) like `Math.random` — which is the
+     * default. Pass `seededRandom(seed)` when the sequence has to reproduce:
+     * unit tests, replays, a daily challenge every player should experience
+     * identically.
+     */
+    rng?: () => number;
+};
+export type ShuffleBag<T> = {
+    /** The next outcome. The bag refills and reshuffles itself when it empties. */
+    draw(): T;
+    /** Draws left before the next refill. */
+    readonly remaining: number;
+    /** Draws per full cycle: the sum of every entry's count. */
+    readonly size: number;
+    /**
+     * Discard the part-drawn cycle so the next draw starts a fresh, full bag.
+     * Call it from the run reset — a run that inherits the tail of the last
+     * run's bag starts with odds the player never saw the front of.
+     */
+    reset(): void;
+};
+/**
+ * A pool of outcomes drawn without replacement, refilled when empty.
+ *
+ * Values are generic, so bags nest: a bag whose values are themselves bags
+ * first decides the category, then the category's own bag decides the item —
+ * which is how "rare letters are not only rare but spaced out" is built.
+ *
+ * Use it for every repeated player-facing roll: crits, drops, obstacle types.
+ * One-off cosmetic jitter keeps using the plain RNG; nobody counts particles.
+ */
+export declare function createShuffleBag<T>(entries: readonly ShuffleBagEntry<T>[], options?: ShuffleBagOptions): ShuffleBag<T>;
+export type PityTimerOptions = {
+    /** The per-roll probability, 0..1. */
+    chance: number;
+    /** The ceiling: roll number `guaranteedBy` hits if none before it did. */
+    guaranteedBy: number;
+    /** The random source, returning [0, 1). Defaults to `Math.random`. */
+    rng?: () => number;
+};
+export type PityTimer = {
+    /** One attempt. A hit — rolled or guaranteed — resets the counter. */
+    roll(): boolean;
+    /** Misses since the last hit. */
+    readonly misses: number;
+    /** Forget the streak. Call from the run reset if pity is per-run. */
+    reset(): void;
+};
+/**
+ * A rare event with a guaranteed ceiling: independent rolls, but the Nth
+ * attempt after a hit always hits.
+ *
+ * The shuffle bag is the wrong tool for the genuinely rare — a 1-in-50 drop
+ * means a 50-item bag, and the guarantee it offers ("exactly one per 50") is
+ * more rigid than a drop wants to feel. The pity timer keeps every roll
+ * independent and honest, and only intervenes at the tail: the player who
+ * would have gone 80 drops dry is the one player it touches, and that player
+ * was about to quit.
+ */
+export declare function createPityTimer(options: PityTimerOptions): PityTimer;
+export type EscalatingChanceOptions = {
+    /** The probability of the first attempt after a hit, 0..1. */
+    start: number;
+    /** Added to the probability after each miss. Clamped at 1. */
+    step: number;
+    /** The random source, returning [0, 1). Defaults to `Math.random`. */
+    rng?: () => number;
+};
+export type EscalatingChance = {
+    /** One attempt. A hit resets the probability to `start`. */
+    roll(): boolean;
+    /** The probability the NEXT roll will be made at. */
+    readonly chance: number;
+    /** Back to `start`. Call from the run reset. */
+    reset(): void;
+};
+/**
+ * A probability that climbs with every miss and resets on a hit — the
+ * pseudo-random distribution behind "25%" crits in Dota and Warcraft 3.
+ *
+ * Softer than the pity timer: there is no hard ceiling, just pressure toward
+ * the mean from both sides. Streaks of misses get rapidly less likely, and
+ * back-to-back hits do too, because a hit drops the odds back to `start`.
+ * `start: 0.05, step: 0.1` feels like roughly a fifth and never insults the
+ * player with an eight-miss run.
+ */
+export declare function createEscalatingChance(options: EscalatingChanceOptions): EscalatingChance;
+/**
+ * mulberry32: a seeded drop-in for `Math.random`, returning [0, 1).
+ *
+ * Not cryptographic and not meant to be — it exists so a sequence can be
+ * replayed. Same seed, same sequence, on every engine, which is what makes a
+ * shuffle bag assertable in a unit test and a daily challenge identical for
+ * every player who types the same date.
+ */
+export declare function seededRandom(seed: number): () => number;
+//# sourceMappingURL=random.d.ts.map

package/dist/random.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.d.ts","sourceRoot":"","sources":["../src/random.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI;IAC/B,uDAAuD;IACvD,KAAK,EAAE,CAAC,CAAA;IACR,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;IAC1B,+EAA+E;IAC/E,IAAI,IAAI,CAAC,CAAA;IACT,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAAA;CACd,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,OAAO,EAAE,SAAS,eAAe,CAAC,CAAC,CAAC,EAAE,EACtC,OAAO,GAAE,iBAAsB,GAC9B,UAAU,CAAC,CAAC,CAAC,CAwCf;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,sEAAsE;IACtE,IAAI,IAAI,OAAO,CAAA;IACf,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,qEAAqE;IACrE,KAAK,IAAI,IAAI,CAAA;CACd,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAuBpE;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,4DAA4D;IAC5D,IAAI,IAAI,OAAO,CAAA;IACf,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,gDAAgD;IAChD,KAAK,IAAI,IAAI,CAAA;CACd,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CAqBzF;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,MAAM,CASvD"}

package/dist/random.js

@@ -0,0 +1,160 @@
+/**
+ * Randomness that feels fair.
+ *
+ * `Math.random()` is stateless, and stateless rolls streak: a 25% crit chance
+ * misses eight times in a row for one player in ten thousand attacks, and that
+ * player experiences a broken game, not an unlucky one. Players expect random
+ * events to self-correct over a handful of trials — real independence does not —
+ * so a repeated player-facing roll wants a distribution that is *guaranteed*
+ * over a short cycle and merely *shuffled* within it.
+ *
+ * That is the shuffle bag (the "marble bag"): fill a bag with the outcomes in
+ * their intended ratio, draw without replacement, refill and reshuffle when it
+ * empties. A 1-in-4 crit is then exactly one crit in every four attacks, the
+ * worst possible drought is bounded by construction (2 × (cycle − 1) misses,
+ * when a crit opens one cycle and closes the next), and the ratio is still
+ * honest over any long run.
+ *
+ * This lives in the SDK rather than in prompt prose because every game that
+ * hand-rolls it gets a different one — usually with the `sort(() => r - 0.5)`
+ * shuffle, which is biased on every engine — and because an injectable RNG is
+ * what makes game logic deterministic under test and daily-challenge seeds
+ * reproducible across players.
+ */
+/**
+ * A pool of outcomes drawn without replacement, refilled when empty.
+ *
+ * Values are generic, so bags nest: a bag whose values are themselves bags
+ * first decides the category, then the category's own bag decides the item —
+ * which is how "rare letters are not only rare but spaced out" is built.
+ *
+ * Use it for every repeated player-facing roll: crits, drops, obstacle types.
+ * One-off cosmetic jitter keeps using the plain RNG; nobody counts particles.
+ */
+export function createShuffleBag(entries, options = {}) {
+    const rng = options.rng ?? Math.random;
+    const cycle = [];
+    for (const entry of entries) {
+        if (!Number.isInteger(entry.count) || entry.count <= 0) {
+            throw new Error(`createShuffleBag: count must be a positive integer, got ${entry.count}`);
+        }
+        for (let i = 0; i < entry.count; i++)
+            cycle.push(entry.value);
+    }
+    if (cycle.length === 0)
+        throw new Error('createShuffleBag: entries must not be empty');
+    const bag = [];
+    const refill = () => {
+        bag.length = 0;
+        bag.push(...cycle);
+        // Fisher–Yates. `sort(() => rng() - 0.5)` — the shuffle an LLM reaches for
+        // first — is measurably biased under every engine's sort, which quietly
+        // un-randomises exactly the distribution the bag exists to guarantee.
+        for (let i = bag.length - 1; i > 0; i--) {
+            const j = Math.floor(rng() * (i + 1));
+            const swap = bag[i];
+            bag[i] = bag[j];
+            bag[j] = swap;
+        }
+    };
+    return {
+        draw() {
+            if (bag.length === 0)
+                refill();
+            return bag.pop();
+        },
+        get remaining() {
+            return bag.length;
+        },
+        size: cycle.length,
+        reset() {
+            bag.length = 0;
+        },
+    };
+}
+/**
+ * A rare event with a guaranteed ceiling: independent rolls, but the Nth
+ * attempt after a hit always hits.
+ *
+ * The shuffle bag is the wrong tool for the genuinely rare — a 1-in-50 drop
+ * means a 50-item bag, and the guarantee it offers ("exactly one per 50") is
+ * more rigid than a drop wants to feel. The pity timer keeps every roll
+ * independent and honest, and only intervenes at the tail: the player who
+ * would have gone 80 drops dry is the one player it touches, and that player
+ * was about to quit.
+ */
+export function createPityTimer(options) {
+    const { chance, guaranteedBy } = options;
+    const rng = options.rng ?? Math.random;
+    if (!(chance >= 0 && chance <= 1)) {
+        throw new Error(`createPityTimer: chance must be in 0..1, got ${chance}`);
+    }
+    if (!Number.isInteger(guaranteedBy) || guaranteedBy <= 0) {
+        throw new Error(`createPityTimer: guaranteedBy must be a positive integer, got ${guaranteedBy}`);
+    }
+    let misses = 0;
+    return {
+        roll() {
+            const hit = misses + 1 >= guaranteedBy || rng() < chance;
+            misses = hit ? 0 : misses + 1;
+            return hit;
+        },
+        get misses() {
+            return misses;
+        },
+        reset() {
+            misses = 0;
+        },
+    };
+}
+/**
+ * A probability that climbs with every miss and resets on a hit — the
+ * pseudo-random distribution behind "25%" crits in Dota and Warcraft 3.
+ *
+ * Softer than the pity timer: there is no hard ceiling, just pressure toward
+ * the mean from both sides. Streaks of misses get rapidly less likely, and
+ * back-to-back hits do too, because a hit drops the odds back to `start`.
+ * `start: 0.05, step: 0.1` feels like roughly a fifth and never insults the
+ * player with an eight-miss run.
+ */
+export function createEscalatingChance(options) {
+    const { start, step } = options;
+    const rng = options.rng ?? Math.random;
+    if (!(start >= 0 && start <= 1)) {
+        throw new Error(`createEscalatingChance: start must be in 0..1, got ${start}`);
+    }
+    if (!(step > 0))
+        throw new Error(`createEscalatingChance: step must be > 0, got ${step}`);
+    let chance = start;
+    return {
+        roll() {
+            const hit = rng() < chance;
+            chance = hit ? start : Math.min(chance + step, 1);
+            return hit;
+        },
+        get chance() {
+            return chance;
+        },
+        reset() {
+            chance = start;
+        },
+    };
+}
+/**
+ * mulberry32: a seeded drop-in for `Math.random`, returning [0, 1).
+ *
+ * Not cryptographic and not meant to be — it exists so a sequence can be
+ * replayed. Same seed, same sequence, on every engine, which is what makes a
+ * shuffle bag assertable in a unit test and a daily challenge identical for
+ * every player who types the same date.
+ */
+export function seededRandom(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}

package/dist/scene/dispose.d.ts

@@ -0,0 +1,46 @@
+import type { Object3D } from 'three';
+/**
+ * The Three.js leak, solved once.
+ *
+ * `scene.remove(mesh)` frees nothing: geometries, materials and textures are
+ * GPU resources that only `renderer.info.memory` ever sees, and they survive
+ * until someone calls `.dispose()`. A game that rebuilds its level on every
+ * restart and never disposes will climb until the WebView is killed — and
+ * because it climbs on the GPU, JS heap profiling shows nothing.
+ */
+export type Disposable = {
+    dispose(): void;
+};
+/** Anything that must outlive a restart: cached assets, shared materials. */
+export type DisposeOptions = {
+    skip?: ReadonlySet<unknown>;
+};
+/**
+ * Recursively disposes every geometry, material and texture under `object`.
+ *
+ * Shared resources are visited once, and anything in `skip` (pass
+ * `assets.owned`) is left alone — cached assets live for the whole session and
+ * disposing one would blank every other object that clones it.
+ */
+export declare function disposeObject(object: Object3D, options?: DisposeOptions): void;
+/** Detach from the scene graph and dispose. The normal way to remove a thing. */
+export declare function destroy(object: Object3D, options?: DisposeOptions): void;
+/**
+ * A bag of things to free together.
+ *
+ * `game.transient` is a scope cleared on every `restart()`, which is why a game
+ * only has to remember rule 8 — register what you create after setup — instead
+ * of tracking individual resources.
+ */
+export declare class DisposalScope {
+    private readonly items;
+    private skip;
+    /** @param skip resources this scope must never dispose (`assets.owned`). */
+    constructor(skip?: ReadonlySet<unknown>);
+    add<T extends Object3D | Disposable>(item: T): T;
+    /** Removes without disposing — for an object that was handed off elsewhere. */
+    forget(item: unknown): void;
+    get size(): number;
+    dispose(): void;
+}
+//# sourceMappingURL=dispose.d.ts.map

package/dist/scene/dispose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispose.d.ts","sourceRoot":"","sources":["../../src/scene/dispose.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,QAAQ,EAAW,MAAM,OAAO,CAAA;AAExE;;;;;;;;GAQG;AAEH,MAAM,MAAM,UAAU,GAAG;IAAE,OAAO,IAAI,IAAI,CAAA;CAAE,CAAA;AAE5C,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;CAAE,CAAA;AA4C5D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAE,cAAmB,GAAG,IAAI,CAelF;AAED,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAE,cAAmB,GAAG,IAAI,CAG5E;AAED;;;;;;GAMG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,IAAI,CAA8B;IAE1C,4EAA4E;gBAChE,IAAI,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC;IAIvC,GAAG,CAAC,CAAC,SAAS,QAAQ,GAAG,UAAU,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC;IAKhD,+EAA+E;IAC/E,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAK3B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,OAAO,IAAI,IAAI;CAUhB"}

package/dist/scene/dispose.js

@@ -0,0 +1,108 @@
+const EMPTY = new Set();
+function isTexture(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.isTexture === true);
+}
+function disposeMaterial(material, skip, seen) {
+    if (skip.has(material) || seen.has(material))
+        return;
+    seen.add(material);
+    // Enumerate rather than list the slots: three has ~20 map properties and
+    // MeshPhysicalMaterial keeps adding them, so a hardcoded list is a slow leak
+    // waiting for the next release.
+    for (const value of Object.values(material)) {
+        if (!isTexture(value) || skip.has(value) || seen.has(value))
+            continue;
+        seen.add(value);
+        value.dispose();
+    }
+    material.dispose();
+}
+function disposeGeometry(geometry, skip, seen) {
+    if (skip.has(geometry) || seen.has(geometry))
+        return;
+    seen.add(geometry);
+    geometry.dispose();
+}
+/**
+ * Recursively disposes every geometry, material and texture under `object`.
+ *
+ * Shared resources are visited once, and anything in `skip` (pass
+ * `assets.owned`) is left alone — cached assets live for the whole session and
+ * disposing one would blank every other object that clones it.
+ */
+export function disposeObject(object, options = {}) {
+    const skip = options.skip ?? EMPTY;
+    const seen = new Set();
+    object.traverse((node) => {
+        const renderable = node;
+        if (renderable.geometry)
+            disposeGeometry(renderable.geometry, skip, seen);
+        const material = renderable.material;
+        if (!material)
+            return;
+        if (Array.isArray(material)) {
+            for (const entry of material)
+                disposeMaterial(entry, skip, seen);
+        }
+        else {
+            disposeMaterial(material, skip, seen);
+        }
+    });
+}
+/** Detach from the scene graph and dispose. The normal way to remove a thing. */
+export function destroy(object, options = {}) {
+    object.removeFromParent();
+    disposeObject(object, options);
+}
+/**
+ * A bag of things to free together.
+ *
+ * `game.transient` is a scope cleared on every `restart()`, which is why a game
+ * only has to remember rule 8 — register what you create after setup — instead
+ * of tracking individual resources.
+ */
+export class DisposalScope {
+    items = [];
+    skip = EMPTY;
+    /** @param skip resources this scope must never dispose (`assets.owned`). */
+    constructor(skip) {
+        if (skip)
+            this.skip = skip;
+    }
+    add(item) {
+        this.items.push(item);
+        return item;
+    }
+    /** Removes without disposing — for an object that was handed off elsewhere. */
+    forget(item) {
+        const index = this.items.indexOf(item);
+        if (index >= 0)
+            this.items.splice(index, 1);
+    }
+    get size() {
+        return this.items.length;
+    }
+    dispose() {
+        // Reverse order so a child registered after its parent is freed first.
+        for (let i = this.items.length - 1; i >= 0; i--) {
+            const item = this.items[i];
+            if (this.skip.has(item))
+                continue;
+            if (isObject3D(item))
+                destroy(item, { skip: this.skip });
+            else if (isDisposable(item))
+                item.dispose();
+        }
+        this.items.length = 0;
+    }
+}
+function isObject3D(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.isObject3D === true);
+}
+function isDisposable(value) {
+    return typeof value?.dispose === 'function';
+}

package/dist/scene/lighting.d.ts

@@ -0,0 +1,42 @@
+import { type Box3, DirectionalLight, HemisphereLight, Mesh, type Object3D, type Scene, type WebGLRenderer } from 'three';
+/**
+ * Three phone-tuned presets. There is deliberately no EffectComposer here: at
+ * 720x1080 with DPR capped at 2 the real framebuffer is 1440x2160, and a bloom
+ * chain costs 4-6 ms of a 16.6 ms frame on a mid-range Android WebView. ACES
+ * tone mapping (set by `createGame`) plus emissive materials gets most of the
+ * look for free.
+ */
+export type LightingPreset = 'studio' | 'sunset' | 'night';
+export type LightingOptions = {
+    /** Real shadow maps are opt-in — they cost a second scene pass. */
+    shadows?: boolean;
+    /** Ortho frustum for the shadow camera. Without it shadows look chunky. */
+    shadowBounds?: Box3;
+    renderer?: WebGLRenderer;
+};
+export type Lighting = {
+    key: DirectionalLight;
+    fill: HemisphereLight;
+    dispose(): void;
+};
+export declare function applyLighting(scene: Scene, preset: LightingPreset, options?: LightingOptions): Lighting;
+export type BlobShadowOptions = {
+    radius?: number;
+    opacity?: number;
+    /** World Y the blob sits on. */
+    groundY?: number;
+};
+export type BlobShadow = {
+    mesh: Mesh;
+    update(): void;
+    dispose(): void;
+};
+/**
+ * A flat translucent disc that tracks an object's ground position.
+ *
+ * On a small screen this reads better than a real shadow map and costs one
+ * draw call instead of a depth pass — the same trick the Remix avatar already
+ * uses in `packages/ui/src/lib/avatar-three.ts`.
+ */
+export declare function blobShadow(target: Object3D, options?: BlobShadowOptions): BlobShadow;
+//# sourceMappingURL=lighting.d.ts.map

package/dist/scene/lighting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lighting.d.ts","sourceRoot":"","sources":["../../src/scene/lighting.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,IAAI,EAGT,gBAAgB,EAEhB,eAAe,EACf,IAAI,EAEJ,KAAK,QAAQ,EAEb,KAAK,KAAK,EAEV,KAAK,aAAa,EACnB,MAAM,OAAO,CAAA;AAEd;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAA;AA8C1D,MAAM,MAAM,eAAe,GAAG;IAC5B,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,EAAE,aAAa,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,gBAAgB,CAAA;IACrB,IAAI,EAAE,eAAe,CAAA;IACrB,OAAO,IAAI,IAAI,CAAA;CAChB,CAAA;AAED,wBAAgB,aAAa,CAC3B,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,eAAoB,GAC5B,QAAQ,CAiDV;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,IAAI,IAAI,CAAA;IACd,OAAO,IAAI,IAAI,CAAA;CAChB,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAE,iBAAsB,GAAG,UAAU,CAiCxF"}