paperlab 0.6.0 → 0.7.0

package/dist/fx.d.cts

@@ -0,0 +1,1796 @@
+import { D as DamageSource } from './damageContract-DPF1YFLZ.cjs';
+export { a as DAMAGE_CHANNELS, b as DAMAGE_LOOK_DEFAULTS, c as DamageLook } from './damageContract-DPF1YFLZ.cjs';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as THREE from 'three';
+
+/**
+ * The damage field: what has happened to this sheet, as four numbers per
+ * texel, over the sheet's own UV.
+ *
+ * One primitive rather than one subsystem per effect. Fire is heat diffusing
+ * into char and char eating presence; water is saturation diffusing along the
+ * fibre; a tear is presence zeroed along a path. They share a grid, a step
+ * and a set of paint operations, which is the whole reason the second effect
+ * costs a chunk and a preset instead of a new system.
+ *
+ *   R  char        scorch colour, the brown halo, shrinkage and curl, smoke density
+ *   G  saturation  wet darkening, roughness, translucency, added mass, sag
+ *   B  heat        the glowing ignition line
+ *   A  presence    alpha erosion — burn-away, tear-away, punched holes
+ *
+ * **It runs on the CPU because of who reads it.** Three of the four layers an
+ * effect has to land on consume the field on the CPU: the physics coupling
+ * needs stiffness and mass per vertex, the emitters spawn ash where presence
+ * reaches zero and drips from the lowest wet vertex, and the sound is driven
+ * by the length of the burn front every frame. A GPU field would have fed all
+ * three through a `readPixels` per frame — a pipeline stall that tile-based
+ * phone GPUs pay the most for. Only the shading reads the field on the GPU,
+ * and it gets an 8-bit texture uploaded from here. Testability without a
+ * renderer comes free with that, and it is how every property below is known.
+ *
+ * It stays on the main thread. A worker would need `SharedArrayBuffer` to
+ * avoid copying the field every frame, and that needs COOP/COEP headers that
+ * GitHub Pages cannot send. The main thread is affordable only because the
+ * field costs nothing when nothing is happening to it — see `step`.
+ *
+ * **It is not tiered.** Every device runs the same grid at the same timestep
+ * and produces the same fire. With explicit diffusion, halving the cell size
+ * quadruples both the cells and the steps stability needs, so the same fire
+ * costs N⁴: a 128 grid is sixteen times a 64 one. The first version tiered
+ * grid size and substeps as though they were independent, and the measured
+ * result was a fire whose speed depended on the device. Presentation is what
+ * tiers now — see `fx/quality.ts`.
+ */
+
+/**
+ * Channel offsets into a texel — the contract's, not this file's. The sheet
+ * defines what the four bytes mean because the sheet is what draws them;
+ * the field is one thing that writes them.
+ */
+declare const CHAR: 0;
+declare const SATURATION: 1;
+declare const HEAT: 2;
+declare const PRESENCE: 3;
+/**
+ * The grid, in texels along each edge. One number for every device.
+ *
+ * 64 until a real phone says otherwise — the P1 gate is where this gets
+ * settled for good, by rendering a burn at 64 and 96 and looking. What the
+ * field carries are soft quantities with soft edges; the RAGGED edge a burn
+ * reads as comes from the anisotropy and the grain, which survive a coarse
+ * grid, and from per-fragment detail in the shader, which does not need one.
+ */
+declare const FIELD_SIZE = 64;
+/**
+ * The simulation's own clock, independent of the frame rate.
+ *
+ * The first version ran a fixed number of substeps per FRAME, so a slow frame
+ * meant a longer substep, the stability clamp scaled the diffusion down to
+ * compensate, and the same simulated second burned half as far at 30 fps as
+ * at 144. Measured on the high tier: 0.202, 0.290 and 0.439 UV of burn radius
+ * at 30, 60 and 144 fps. A fire that burns slower when the phone is busy is a
+ * fire that behaves differently on every device and every run.
+ *
+ * `ClothSim` already solved this with the same accumulator and the same
+ * number, and the field now matches it. The rates are chosen so that the
+ * stability bound is never reached at 1/120 — the clamp in `stencil` is a
+ * safety net for extreme options, not something defaults lean on, and a test
+ * says so.
+ */
+declare const FIXED_DT: number;
+interface DamageFieldOptions {
+    /**
+     * Which way the paper's fibres run, in radians over the sheet's UV, where
+     * 0 points along +u.
+     *
+     * Paper is not isotropic and this is the single number that makes it look
+     * like paper rather than like a fluid. Fibres are laid down along the
+     * machine direction when the sheet is made; liquid wicks along them far
+     * faster than across them, and a flame follows them for the same reason.
+     * A wet front with anisotropy at 1 is a circle, which reads as a stain on
+     * cloth; with it raised, the front is an ellipse along this angle, which
+     * reads as paper. Any angle — see `diffusionTensor`.
+     */
+    fibre?: number;
+    /** How much faster things travel along the fibre than across it. */
+    anisotropy?: number;
+    /** Heat spread, in UV² per second, averaged over direction. */
+    heatDiffusion?: number;
+    /** Liquid wicking, in UV² per second, averaged over direction. */
+    wicking?: number;
+    /** How fast heat turns paper to char. */
+    charRate?: number;
+    /** How fast char consumes presence — the burn-away. */
+    consumeRate?: number;
+    /** How much heat burning gives back. Above ~1 the front sustains itself. */
+    combustion?: number;
+    /** Heat lost to the room each second, as a fraction. */
+    cooling?: number;
+    /** How much heat it costs to boil a wet cell dry before it can char. */
+    wetResistance?: number;
+    /** How fast standing water leaves the sheet, as a fraction per second. */
+    drying?: number;
+    /**
+     * Per-texel variation in how readily the paper takes light, 0..1.
+     *
+     * Real paper is not uniform, and a burn front on a uniform sheet advances
+     * as a perfect circle — the single most synthetic-looking thing this
+     * simulation could do. This is what makes the edge ragged, and it is fixed
+     * per field rather than per frame, because a sheet's grain does not change
+     * while you hold it.
+     */
+    grain?: number;
+    /** Seed for the grain, so a field is reproducible. */
+    seed?: number;
+}
+/** What the field did this step. The numbers the sound and the emitters read. */
+interface FieldStats {
+    /**
+     * How much sheet is actively burning right now, 0..1.
+     *
+     * The fraction of texels part-way through charring AND still hot.
+     * Resolution-independent by construction. Both halves matter: combustion
+     * pumps heat into everything it has already burnt, so "hot" alone lights
+     * up the whole interior; and a fire that went out leaves partly charred
+     * cells behind, so "part-charred" alone would report a burn that is over as
+     * one still going.
+     *
+     * This is the number fire's audio is driven by, and it is the right one:
+     * a fire gets louder as the front gets LONGER, not as the burnt area gets
+     * bigger. A sheet nearly consumed is quiet again, which is true, and which
+     * a level driven by char would get exactly backwards.
+     */
+    front: number;
+    /** Texels that crossed into char this step. Drives crackle rate and smoke. */
+    charred: number;
+    /** Texels whose presence reached zero this step. Drives ash, and burn-through. */
+    consumed: number;
+    /** Texels that became wetter this step. Drives the water bed's level. */
+    wetted: number;
+    /** Mean saturation over the sheet, 0..1. Drives added mass in the coupling. */
+    saturation: number;
+    /** Fraction of the sheet still present, 1 at the start. */
+    remaining: number;
+}
+declare class DamageField implements DamageSource {
+    readonly size = 64;
+    /** RGBA per texel in float, row-major from v = 0. The simulation's own state. */
+    readonly data: Float32Array;
+    /** The same, at 8 bits, for upload. Kept in step with `data` over what changed. */
+    readonly pixels: Uint8Array;
+    /**
+     * How ragged the sheet DRAWS this field's edges, 0..1 — see
+     * `DamageSource.detail`. Not a simulation option, because it changes
+     * nothing the field computes: set it from `fxQualityFor(tier).detail`, and
+     * again whenever the tier moves.
+     */
+    detail: number;
+    private revision;
+    private readonly next;
+    /** Per-texel ignition threshold, fixed for the life of the sheet. */
+    private readonly tinder;
+    private readonly o;
+    private readonly heat;
+    private readonly water;
+    private accumulator;
+    /** Fixed steps run since the field was made — its own clock. See {@link time}. */
+    private steps;
+    /** Cells that might change on the next step. Everything outside is at rest. */
+    private active;
+    /** Cells written since the last pack into `pixels`. */
+    private touched;
+    private visited;
+    /** Running totals, so the stats never have to walk the whole grid. */
+    private present;
+    private wetTotal;
+    private stats;
+    /**
+     * Texels whose presence reached zero during the last `step`, in the first
+     * {@link consumedCount} slots — where ash leaves from.
+     *
+     * WHERE, not just how many. The stats were enough for the sound, which
+     * wants a level; an emitter wants a place. Fixed buffers the size of the
+     * grid and written in place: a burning sheet must not allocate a list a
+     * step, and a texel is consumed once, so a step can never fill it twice.
+     */
+    readonly consumedCells: Int32Array<ArrayBuffer>;
+    /** The burn front as of the last step that ran, in the first {@link frontCount} slots — where embers and smoke leave from. */
+    readonly frontCells: Int32Array<ArrayBuffer>;
+    private consumedLength;
+    private frontLength;
+    constructor(options?: DamageFieldOptions);
+    /** Bumped whenever `pixels` changes. */
+    get version(): number;
+    /**
+     * Simulated seconds this field has burned for — whole fixed steps, never
+     * wall time.
+     *
+     * What anything DRAWN from the field animates on: the ember line's beads
+     * flicker and crawl, flames puff, and all of it has to be the same at the
+     * same moment of the same burn, or a replay flickers differently from the
+     * original and a capture can never be taken twice. Stops while the field
+     * sleeps, which is right — a sheet at rest has nothing hot left to move.
+     */
+    get time(): number;
+    /** Nothing is happening to this sheet, and stepping it costs nothing. */
+    get asleep(): boolean;
+    /**
+     * Cells the last `step` visited.
+     *
+     * The cost of the field, stated in the one unit that means the same thing on
+     * every machine. Milliseconds would make a test of it a test of whoever ran
+     * it — which is how the hands harness spent weeks passing on one laptop.
+     */
+    get cellsVisited(): number;
+    /** What the last `step` produced. */
+    get lastStats(): FieldStats;
+    /** How many of {@link consumedCells} the last `step` wrote. Always `lastStats.consumed`. */
+    get consumedCount(): number;
+    /**
+     * How many of {@link frontCells} are current. `lastStats.front` times the
+     * texel count — and held, like it, across a frame too short to step.
+     */
+    get frontCount(): number;
+    /** Texel index for a UV, clamped to the sheet. */
+    private at;
+    /** The four channels at a UV, for anything that needs to ask a question of a point. */
+    sample(u: number, v: number): [number, number, number, number];
+    /**
+     * Add to one channel in a soft disc.
+     *
+     * Every paint operation is this with a different channel, which is the
+     * point of having one primitive: `ignite` and `wet` are not two systems
+     * that happen to look alike, they are the same write.
+     *
+     * `plateau` is the fraction of the radius that takes the full amount
+     * before the falloff starts. Zero for anything added, so the deposit has a
+     * soft peak — a flame held near paper does not deposit a stamped disc of
+     * heat, and a too-perfect edge is the first thing that reads as fake.
+     * Raised for anything removed, because a pure smoothstep never quite
+     * reaches zero even at its centre, and "almost all the way through" is not
+     * a hole.
+     */
+    paint(channel: number, u: number, v: number, radius: number, amount: number, plateau?: number): void;
+    /** Hold a flame near the sheet. Heat, not char — the burning is the field's job. */
+    ignite(u: number, v: number, radius?: number, amount?: number): void;
+    /** Wet the sheet. Saturation wicks along the fibre from wherever it lands. */
+    wet(u: number, v: number, radius?: number, amount?: number): void;
+    /**
+     * Take the paper away along a path: a tear, a cut, a punched hole.
+     *
+     * Presence only ever decreases. A sheet does not grow back, and a paint op
+     * that could raise it would make every burn reversible by accident.
+     */
+    cut(u0: number, v0: number, u1: number, v1: number, width?: number): void;
+    /** Punch a hole. The middle of the sheet, which a fixed-topology mesh cannot do. */
+    punch(u: number, v: number, radius?: number): void;
+    /**
+     * Advance the field by a frame's worth of real time.
+     *
+     * Fixed steps from an accumulator, so the same simulated second is the same
+     * fire at any frame rate. A sheet nothing is happening to returns at once
+     * and visits no cells at all — which is the condition for keeping this on
+     * the main thread, and the thing the first version could not do: an
+     * untouched sheet cost exactly what a burning one did.
+     */
+    step(delta: number): FieldStats;
+    /**
+     * One fixed step of diffusion and reaction, over the active region only.
+     *
+     * The region is the box around every cell that could change, grown by one
+     * cell because diffusion reaches exactly one neighbour per step. Cells
+     * outside it are at rest and read-only here — their neighbours may read
+     * them, and nothing writes them.
+     *
+     * Written into `next` and copied back over the same region, rather than
+     * swapping the two buffers. A swap needs both buffers to agree everywhere
+     * the step did not write, and a region that SHRINKS breaks that: a cell the
+     * last step wrote into one buffer still holds an older value in the other.
+     * Copying the region back keeps them identical outside it, for the cost of
+     * the region itself — which is the cost that matters, since it is zero on
+     * a sheet at rest rather than a whole grid every step.
+     */
+    private substep;
+    /** Quantise everything touched since the last pack, and mark it uploadable. */
+    private pack;
+}
+
+/**
+ * Particles: one pool, and presets that are only parameter sets.
+ *
+ * Embers, smoke and ash are not three systems. They are the same particle —
+ * a position, a velocity, an age — told different things about how long it
+ * lives, which way the air takes it and what it looks like. So there is one
+ * pool, and a preset is a row of numbers; the next effect's droplet or dust is
+ * another row, not another file. That is the P3 gate stated early: each effect
+ * after the second should cost a preset, not a subsystem.
+ *
+ * **Simulated on the CPU,** for the same reason the damage field is: what
+ * spawns them is read on the CPU. Ash leaves the texel that just burnt
+ * through, and that texel is in a `Float32Array`, not a texture. A GPU
+ * particle system would have to be told every spawn through an upload anyway,
+ * and the counts here — hundreds, not hundreds of thousands — are ones a CPU
+ * steps in a fraction of a millisecond.
+ *
+ * **A fixed capacity, from the tier,** allocated once and never grown. When
+ * it is full, the particle closest to the end of its life gives up its slot:
+ * dropping the NEW one instead would starve the burn of embers the moment the
+ * room filled with old smoke, which is exactly backwards — the newest
+ * particle is the one leaving the fire you are looking at.
+ *
+ * Drawing is `FxParticles`. Nothing in this file touches three.
+ */
+interface ParticlePreset {
+    /** Seconds a particle lives, drawn uniformly between the two. */
+    readonly life: readonly [number, number];
+    /** Launch speed in world units a second, drawn between the two. */
+    readonly speed: readonly [number, number];
+    /** Launch direction before spread, in world space. */
+    readonly direction: readonly [number, number, number];
+    /** 0 launches along `direction` exactly; 1 anywhere in the hemisphere around it. */
+    readonly spread: number;
+    /** Acceleration straight up, world units a second squared. Hot air rises; ash is heavier than it. */
+    readonly lift: number;
+    /** How fast the air brings a particle to its own speed, per second. */
+    readonly drag: number;
+    /** A random acceleration, world units a second squared, drawn afresh every step — the flutter. */
+    readonly jitter: number;
+    /** How much of the wind's velocity it takes on, 0..1. */
+    readonly windCatch: number;
+    /** Diameter in world units, at birth and at death. */
+    readonly size: readonly [number, number];
+    /** Linear RGB at birth and at death. Above 1 for anything that is light rather than matter. */
+    readonly color: readonly [readonly [number, number, number], readonly [number, number, number]];
+    /** Opacity at birth and at death. Every particle also fades IN over the first tenth of its life. */
+    readonly alpha: readonly [number, number];
+    /** Spin in radians a second, drawn either way up to this. */
+    readonly spin: number;
+    /** Added to what is behind it — light — or drawn over it — matter. */
+    readonly blend: 'additive' | 'normal';
+    /** A soft disc, or a jagged flake. */
+    readonly shape: 'soft' | 'flake';
+    /** Brightness wobble, 0..1: an ember flickers, a puff of smoke does not. */
+    readonly flicker: number;
+}
+/**
+ * The fire's three. World units are the sheet's: a default sheet is one unit
+ * across, about the width of A4, so 0.01 is two millimetres.
+ */
+declare const particlePresets: {
+    /**
+     * A spark off the burning line. Short-lived, shrinking as it cools, carried
+     * up and sideways by the heat.
+     *
+     * Authored through `emission.ts`, in multiples of paper white, which is what
+     * caught the bug in the version before this one. That version said "the hot
+     * end is now ~5.6, well over the bloom threshold" — and 5.6 was an ABSOLUTE
+     * luminance, while paper white under `window` is 1.6. So the hottest spark
+     * in the frame was **3.5× paper, under the spec's own 4× floor**, and its
+     * own comment said otherwise. A number that cannot be compared to anything
+     * is a number nobody can check.
+     *
+     * It was also too red. `[12, 4.2, 0.9]` is a saturated red at high
+     * intensity, and the tone curve takes a bright red-dominant colour to
+     * SALMON — which is `Never_this.png`. The hue is now a blackbody's: a spark
+     * leaving the fire is yellow-orange, about 2200 K, and cools to a deep
+     * orange-red as it dies. Hue and brightness are separate arguments now, and
+     * `emit` keeps them that way.
+     */
+    readonly ember: {
+        readonly life: readonly [0.5, 1.4];
+        readonly speed: readonly [0.15, 0.5];
+        readonly direction: readonly [0, 1, 0];
+        readonly spread: 0.6;
+        readonly lift: 0.6;
+        readonly drag: 0.8;
+        readonly jitter: 1.5;
+        readonly windCatch: 0.8;
+        readonly size: readonly [0.0035, 0.0012];
+        readonly color: readonly [[number, number, number], [number, number, number]];
+        readonly alpha: readonly [1, 0];
+        readonly spin: 0;
+        readonly blend: "additive";
+        readonly shape: "soft";
+        readonly flicker: 0.35;
+    };
+    /**
+     * What a paper fire mostly makes. Thin, slow, growing as it rises and
+     * spreads, and gone well before it could read as a volume — no fluid
+     * simulation, on purpose; see the fx plan.
+     */
+    readonly smoke: {
+        readonly life: readonly [1.8, 3.5];
+        readonly speed: readonly [0.05, 0.15];
+        readonly direction: readonly [0, 1, 0];
+        readonly spread: 0.3;
+        readonly lift: 0.25;
+        readonly drag: 0.9;
+        readonly jitter: 0.3;
+        readonly windCatch: 1;
+        readonly size: readonly [0.05, 0.35];
+        readonly color: readonly [readonly [0.147, 0.13, 0.117], readonly [0.2, 0.19, 0.18]];
+        readonly alpha: readonly [0.08, 0];
+        readonly spin: 0.4;
+        readonly blend: "normal";
+        readonly shape: "soft";
+        readonly flicker: 0;
+    };
+    /**
+     * Burnt-through paper, leaving. Lifted a little by the heat it came from,
+     * then heavier than the air: it tumbles, flutters and falls — the part of a
+     * burn that proves paper was there.
+     */
+    readonly ash: {
+        readonly life: readonly [2.5, 5];
+        readonly speed: readonly [0.14, 0.3];
+        readonly direction: readonly [0, 1, 0];
+        readonly spread: 0.55;
+        readonly lift: -0.22;
+        readonly drag: 1.6;
+        readonly jitter: 1.2;
+        readonly windCatch: 1;
+        readonly size: readonly [0.03, 0.026];
+        readonly color: readonly [readonly [0.07, 0.065, 0.06], readonly [0.12, 0.115, 0.11]];
+        readonly alpha: readonly [0.95, 0];
+        readonly spin: 4;
+        readonly blend: "normal";
+        readonly shape: "flake";
+        readonly flicker: 0;
+    };
+};
+type ParticlePresetName = keyof typeof particlePresets;
+/**
+ * Where `write` puts one blend mode's particles, as flat arrays sized for the
+ * pool's capacity: xyz, rgba, and four extras — size, spin angle, shape (0
+ * soft, 1 flake) and a per-particle seed the sprite uses for its outline.
+ */
+interface ParticleTarget {
+    readonly position: Float32Array;
+    readonly color: Float32Array;
+    readonly extra: Float32Array;
+    /** Velocity, xyz, if the target wants it — an ember is drawn stretched along its own. */
+    readonly velocity?: Float32Array;
+}
+declare class ParticlePool {
+    readonly capacity: number;
+    /**
+     * The air's own velocity, world units a second. A blow on `/hands` is a
+     * wind, and smoke that ignores it is smoke painted on the glass.
+     */
+    readonly wind: [number, number, number];
+    private readonly kind;
+    private readonly position;
+    private readonly velocity;
+    private readonly age;
+    private readonly life;
+    private readonly angle;
+    private readonly spin;
+    private readonly seed;
+    private live;
+    /** Live particles of each preset, kept as they come and go, so a cap costs nothing to check. */
+    private readonly perKind;
+    /** Embers that popped in the air since the last `takePops` — the sound follows the picture. */
+    private pops;
+    private readonly random;
+    constructor(capacity: number, seed?: number);
+    /** Particles in the air. */
+    get count(): number;
+    /** How many live particles are of one preset. For tests and for a HUD. */
+    countOf(name: ParticlePresetName): number;
+    /** Launch one particle from a point. Never allocates; at capacity it takes the most-spent slot. */
+    spawn(name: ParticlePresetName, x: number, y: number, z: number): void;
+    /** Advance every particle by `dt` seconds; the dead leave the pool. */
+    step(dt: number): void;
+    /**
+     * Write every live particle into the target for its blend mode. Returns how
+     * many went into each — the draw ranges.
+     */
+    write(additive: ParticleTarget, normal: ParticleTarget, 
+    /**
+     * Where flakes go, if they are to be drawn apart from the smoke — ash is
+     * a tumbling plane and smoke is a soft sprite, and one blend mode is not
+     * one way of drawing. Omitted, flakes go with `normal` as they always did.
+     */
+    flakes?: ParticleTarget): {
+        additive: number;
+        normal: number;
+        flakes: number;
+    };
+    /**
+     * How many embers popped in the air since the last call, and reset — one
+     * `FireSound.pop()` each keeps the sound on the frame the flash is on.
+     */
+    takePops(): number;
+    /** Empty the air — a fresh sheet. */
+    clear(): void;
+    /** Swap the last live particle into slot `i`. Order does not matter; density does. */
+    private remove;
+}
+
+/**
+ * Where a point of the sheet is in the world, given its UV — `v = 0` at the
+ * bottom edge, as the damage grid has it. Null when it cannot say (the sheet
+ * has not mounted yet).
+ *
+ * On `<Paper>` this is `(u, v) => handle.surfacePoint(u, v, scratch)`: the
+ * drawn surface this frame, after the cloth and the deformers. A callback and
+ * not the handle, because `paperlab/fx` cannot name a type from the main
+ * entry without reaching into it — see `fx/boundary.test.ts`.
+ */
+type SurfaceLocator = (u: number, v: number) => {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+} | null;
+interface FireEmitterOptions {
+    /** Embers a second for every texel on the burn front. */
+    embers?: number;
+    /** Puffs of smoke a second for every texel on the burn front. */
+    smoke?: number;
+    /** The chance a texel that burns through leaves a flake of ash. */
+    ash?: number;
+    /** Seed for which cells are chosen, so a replayed burn throws the same sparks. */
+    seed?: number;
+    /** The most of each kind in the air at once — `fxQualityFor(tier).caps`. Uncapped if omitted. */
+    caps?: {
+        ember?: number;
+        smoke?: number;
+        ash?: number;
+    };
+}
+/**
+ * How much each kind leaves the front, per texel per second.
+ *
+ * `smoke` is 0 on purpose. There were three smoke systems running at once —
+ * the fire simulator's own, these sprite puffs at 8% alpha, and the smoulder
+ * wisp — and the review's note was that only one of them should exist. The
+ * simulator's is the one that belongs to a burning sheet: it is the same
+ * fluid the flames are made of, so it rises with them instead of beside them.
+ * `FxWisps` still carries the thread after the flames are out, which is the
+ * one moment the simulator has nothing left to make. The preset stays: it is
+ * a parameter set, and anything may still ask the pool for smoke.
+ *
+ * Embers and ash are both down. Ash at 0.86 a texel was a flake for nearly
+ * every one that burnt through — a dust shower. Fewer and larger is the note.
+ */
+declare const fireEmitterDefaults: Required<FireEmitterOptions>;
+/**
+ * What a burn throws into the air, read off the field that is burning.
+ *
+ * Nothing here decides where a fire IS — the field does. Embers and smoke
+ * leave the front, at a rate set by how long the front is (a fire gets
+ * busier as its edge gets longer, the same number its sound follows). Ash
+ * leaves exactly the texels that burnt through this frame, so a hole opening
+ * is a hole shedding. On a sheet nothing is happening to, `update` reads two
+ * zeros and returns.
+ */
+declare class FireEmitter {
+    private readonly field;
+    private readonly pool;
+    private readonly locate;
+    private readonly o;
+    private emberDebt;
+    private smokeDebt;
+    private state;
+    constructor(field: DamageField, pool: ParticlePool, locate: SurfaceLocator, options?: FireEmitterOptions);
+    /** Call once a frame, after the field has stepped. */
+    update(dt: number): void;
+    private emit;
+    /** xorshift32 — its own stream, so the pool's randomness cannot shift which cells are picked. */
+    private next;
+}
+
+/**
+ * The pool, drawn — three kinds, three ways, because the spec's three
+ * particles are three different things (paperlab-fx-fire-spec.md §8).
+ *
+ * - **Embers** are light, moving fast: quads STRETCHED along their own
+ *   screen-space velocity into streaks, a bright head and a fading tail,
+ *   additive and HDR so they bloom. A spark is never a static dot.
+ * - **Smoke** is soft sprites broken up by noise — thin, grey-brown, widening
+ *   as it rises. Camera-facing points: one vertex each is still the right
+ *   price for something this soft.
+ * - **Ash** is paper: thin curled planes that tumble in three dimensions,
+ *   double-sided, char-dark with pale ash edges, lit by where they face
+ *   rather than glowing — a few keep a hot edge for their first second.
+ *
+ * This only draws. The page owns the order — field, then emitters, then the
+ * pool's own step — because only the page knows which field belongs to which
+ * sheet.
+ */
+interface FxParticlesProps {
+    pool: ParticlePool;
+}
+declare function FxParticles({ pool }: FxParticlesProps): react.JSX.Element;
+
+/**
+ * What an effect is allowed to cost to SHOW, per device class.
+ *
+ * Presentation only, deliberately. The simulation is not tiered: every device
+ * runs the same damage field on the same grid at the same timestep, so every
+ * device gets the same fire — which is also the only way a burn can be shared
+ * or replayed and come out the same. See the note at the top of
+ * `fx/field.ts`.
+ *
+ * That is a correction. The first version of this table tiered the field's
+ * grid size and its substep count as two independent knobs, and they are not
+ * independent: with explicit diffusion, halving the cell size quadruples the
+ * cells AND the steps stability needs, so the same fire costs N⁴ — the 128
+ * grid was sixteen times the 64 one. What the table actually produced was a
+ * fire whose SPEED depended on the device. It is the same shape of mistake as
+ * the `stage/quality.ts` knob this file's first preamble warned about, made
+ * one file over.
+ *
+ * What remains here is what a weaker device can genuinely show less of
+ * without the effect meaning something different: how many particles are in
+ * the air, how many sounds play at once, and how finely a burnt edge is drawn.
+ * A knob belongs here only when something reads it.
+ */
+declare const fxQualityNames: readonly ["auto", "low", "medium", "high"];
+type FxQualityName = (typeof fxQualityNames)[number];
+type FxQualityTier = Exclude<FxQualityName, 'auto'>;
+interface FxQualitySettings {
+    /**
+     * Hard ceiling on live particles across every emitter at once.
+     *
+     * Allocated at this size and never grown, so it is a size rather than a
+     * suggestion. Read by the emitters, which arrive with fire.
+     */
+    particles: number;
+    /**
+     * Simultaneous synthesised voices.
+     *
+     * A phone running MediaPipe and WebGL has no headroom for an unbounded
+     * grain cloud, and a grain cloud is exactly what fire and crumple both
+     * want to be. The ceiling is the whole design, not a safety net. Read by
+     * `FxAudio`.
+     */
+    voices: number;
+    /**
+     * How ragged a burnt edge is drawn, 0..1 — per-fragment noise that frays
+     * the edge finer than the damage grid can. Handed to the sheet as the
+     * field's `detail`. The one part of drawing damage that costs per PIXEL,
+     * so the part a fill-rate-bound phone gives up first; at 0 the shader
+     * skips the noise outright.
+     */
+    detail: number;
+    /**
+     * The resolution bloom is drawn at, as a fraction of the frame.
+     *
+     * Bloom is a blur, and a blur at half resolution is a quarter of the
+     * fill-rate for a glow that is soft anyway — the cheapest thing a phone
+     * can give up that still leaves every zone and every flame on screen
+     * (spec §12: tiers thin post quality, never what is shown). Read by
+     * `FxPost`.
+     */
+    bloomScale: number;
+    /**
+     * The most flames standing at once. The spec's §12 said 8 / 16 / 32; a ring
+     * of fire that is dense in clusters and broken by gaps needs more tongues
+     * than that, and Noor's direction (a living, uneven ring, never a crown)
+     * came later and wins — 16 / 36 / 64. Every tier has real flames; a phone
+     * gets fewer tongues, never the cheap version.
+     * Read by `FxFlames`.
+     */
+    flames: number;
+    /**
+     * The most of each particle kind in the air at once (spec §12), inside the
+     * `particles` budget. Read by `FireEmitter` through its `caps` option.
+     */
+    caps: {
+        ember: number;
+        smoke: number;
+        ash: number;
+    };
+    /**
+     * Heat haze strength in pixels at 1080p; 0 turns it off. Read by `FxPost`.
+     *
+     * High tier only, and half what it was. It was 3.8 px on two tiers against
+     * §10's 1–3, and invisible in every capture at either — a few pixels of
+     * wobble reads as nothing while the fluid beside it is moving. It is also
+     * still driven from `flameAnchors`, which is where the SPRITE flames stand,
+     * not where the fluid actually burns; until it reads the fluid's own heat
+     * texture it is the last polish item rather than a look, so it is off
+     * everywhere it cannot be afforded to be good.
+     */
+    haze: number;
+    /**
+     * The fire simulator's grids (`FxFireFluid`): a velocity grid, a finer one
+     * for what is drawn, and the pressure solve's iterations. Every tier
+     * simulates a real fire; a phone solves a coarser one.
+     *
+     * The velocity grid is half the dye's resolution, not a quarter as it was.
+     * At a quarter its cells were 4.4 mm and a tongue was one to five cells
+     * wide, so everything that makes a flame flicker happened inside a cell and
+     * the solve never saw it — sharper advection of the dye could only draw the
+     * edges of a motion that was itself butter. The pressure solve is the cheap
+     * part (a quarter of the dye grid's texels); the iterations rise with it
+     * because Jacobi needs more of them to converge over more cells.
+     */
+    fluid: {
+        velocity: readonly [number, number];
+        dye: readonly [number, number];
+        iterations: number;
+    };
+}
+declare const fxQualityTiers: Record<FxQualityTier, FxQualitySettings>;
+/** Where `auto` starts before anything has been measured. */
+declare const FX_INITIAL_TIER: FxQualityTier;
+declare const FX_TIER_ORDER: FxQualityTier[];
+declare function fxQualityFor(name: FxQualityName): FxQualitySettings;
+
+/** The rig's film. Mirrors `FilmName` — which fx cannot import; see `boundary.test.ts`. */
+type FxFilm = 'agx' | 'neutral' | 'filmic';
+interface FxPostProps {
+    /**
+     * The film the scene's lighting uses. The composer takes the tone curve off
+     * the renderer, so the pass has to be told which one to put back. Every
+     * built-in preset uses `neutral`.
+     */
+    film?: FxFilm;
+    /** How much the pass may cost — bloom is drawn at half resolution on `low`. */
+    quality?: FxQualityTier;
+    /** Bloom strength; 0 keeps the tone curve and drops the bloom. */
+    bloom?: number;
+    /** Bloom threshold in scene luminance. Must stay above paper white. */
+    threshold?: number;
+    /**
+     * The burning field, and where its sheet is — for the heat haze above its
+     * flames and the frame's warm grade as it grows (§7). Leave both out and
+     * the pass is bloom and the tone curve alone.
+     */
+    field?: DamageField;
+    locate?: SurfaceLocator;
+    /** Heat haze in pixels at 1080p, overriding the tier's; 0 turns it off. */
+    haze?: number;
+}
+/**
+ * `fallback={null}`: the scene behind it is already drawn. One frame without
+ * the pass, then one with it.
+ */
+declare function FxPost(props: FxPostProps): react.JSX.Element;
+
+/**
+ * The scene luminance of the brightest paper any built-in preset lights.
+ *
+ * **Measured, not chosen.** A clean sheet was photographed under every preset
+ * with bloom on and bloom off, stepping the threshold until the two pictures
+ * were identical: most presets are safe from 0.8–0.9, `studio` from 1.1, and
+ * `window` — the brightest — only from 1.6. The brightest preset has to set
+ * this, because a threshold that lets paper bloom under any preset brings back
+ * the painted-glow failure of §0.
+ *
+ * Re-measure it with `pnpm test:fire-look` if a preset's lighting changes.
+ */
+declare const PAPER_WHITE = 1.6;
+/**
+ * The bloom threshold, in scene luminance before the tone curve.
+ *
+ * Paper white plus headroom for a highlight at a grazing angle that the test
+ * camera does not happen to see. Stated as a multiple so that the reason for
+ * the number survives: it is not "3.6", it is "clear of the brightest paper".
+ *
+ * **Do not lower it to make fire bloom.** That is the wrong end of the
+ * problem, and the review that found the fluid's flames under it said so:
+ * `window`'s paper blooms from 1.6, so lowering the threshold blooms paper,
+ * which is the painted glow again. Raise what the fire EMITS.
+ */
+declare const FX_BLOOM_THRESHOLD: number;
+/**
+ * What the spec asks a glowing part of a fire to reach, in multiples of paper
+ * white (§4.3). The band `emission.test.ts` holds every emitter to.
+ */
+declare const FIRE_GLOW: readonly [4, 8];
+/** One sRGB channel (0..1) to linear. The transfer function, not a gamma. */
+declare function srgbToLinear(c: number): number;
+/** Rec. 709 luminance of a linear colour. */
+declare function luminance(c: readonly [number, number, number]): number;
+/** How many times paper white a linear colour is — the inverse of {@link emit}. */
+declare function timesPaperWhite(c: readonly [number, number, number]): number;
+/**
+ * An emissive colour, authored as a hue and a brightness.
+ *
+ * `srgb` is the colour it should LOOK — the ordinary 0..1 sRGB you would pick
+ * in a colour picker — and `times` is how many times paper white it should
+ * BE. The two are independent on purpose: hue is a judgement about fire, and
+ * brightness is a number the spec fixes and a test can check. Authoring them
+ * together in one linear triple is what let `[12, 4.2, 0.9]` sit at 3.5×
+ * paper white under a comment claiming it cleared 4×.
+ *
+ * The returned triple has exactly `times * PAPER_WHITE` luminance, so it can
+ * be handed straight to a shader.
+ */
+declare function emit(srgb: readonly [number, number, number], times: number): [number, number, number];
+/** `emit` from a `#rrggbb` string, for colours sampled off a reference still. */
+declare function emitHex(hex: string, times: number): [number, number, number];
+/**
+ * The FLAME HEAT that counts as the hottest gas in a flame — the heat burning
+ * made (see `REACT`), which is what a flame's colour is drawn from.
+ *
+ * It has no natural ceiling, so the render pass needs a reference before
+ * "hot" can mean anything. Every band in `RENDER_FRAGMENT`
+ * is a fraction of this, which is what gives a flame a core, a body and a
+ * tip instead of one saturated colour.
+ *
+ * It is NOT independent of the solver's `cooling` and heat terms: this is a
+ * reference temperature, and they decide how much gas ever reaches it.
+ * `pnpm test:fire-budget` is what holds the pair honest.
+ *
+ * 0.65, measured: inside a flame (where its soot is visible) flame heat runs
+ * 0.17 / 0.27 / 0.40 / 0.48 at the 10th / 50th / 90th / 99th percentile.
+ * At 0.4 most of the flame sat past the core's threshold and was 36%
+ * near-white; at 0.8 all of it sat in the tip's band and was 93% orange.
+ * 0.65 puts the median in the body and only the top few percent in the core.
+ */
+declare const FIRE_HEAT_SCALE = 0.65;
+/**
+ * The soot density that counts as a full flame.
+ *
+ * Soot is what the render pass draws a flame FROM — its outline, its opacity,
+ * how much light it can give — while temperature only picks the colour (see
+ * `RENDER_FRAGMENT`). Like the heat, the solver's soot has no natural unit,
+ * so this is the reference: `tip.from` is a fraction of it. At 1 the soot's
+ * 90th percentile (~1.4) was already past it, so every tongue was solid to
+ * its edge with a hard outline; 3 leaves the thin parts room to fade.
+ */
+declare const FIRE_SOOT_SCALE = 3;
+/**
+ * How strongly light past {@link FX_BLOOM_THRESHOLD} spreads.
+ *
+ * It lives beside the threshold because the two are one setting: bloom is a
+ * multiplier on whatever clears the threshold, so its right value depends
+ * entirely on how much fire is authored above it. 1.55 was tuned when the
+ * flames were UNDER the threshold and bloom had almost nothing to work on —
+ * measured, 0.07% of the frame. Once the flames cleared it, that same 1.55
+ * tinted the entire black stage olive. Swept at 0.25, 0.6 and 1.2 against the
+ * peak frame; past about 0.4 the stage stops being black.
+ */
+declare const FX_BLOOM = 0.55;
+/**
+ * A flame, in four zones — drawn the way the sheet's burn is (ember line, ash
+ * lip, char, scorch): each part named for what it is, with its own controls.
+ * Base to tip, as a flame spreading over a sheet actually is:
+ *
+ *   root  the blue leading edge where fresh gas meets the air at the paper.
+ *         Its light comes from excited molecules, not soot, so it is faint
+ *         and blue — and it starts OFF, because blue light added over cream
+ *         paper reads lavender.
+ *   core  the hottest gas, where soot forms densest and glows pale. The only
+ *         zone allowed to over-expose past the bloom threshold, and so the
+ *         one that blooms.
+ *   body  the luminous bulk: soot glowing yellow-orange as it rises.
+ *   tip   where soot cools and burns off at the outer edge — orange-red,
+ *         dimmer, tearing into tongues. What survives escapes as smoke.
+ *
+ * Colour and brightness are separate in every zone, the way professional
+ * fire shading keeps an intensity ramp apart from a colour ramp. The DEFAULTS
+ * keep the order a hot body glows in — each zone brighter and yellower than
+ * the one outside it — because breaking it is how dim yellow turns olive;
+ * `emission.test.ts` holds them to that.
+ *
+ * WHERE the flame is comes from its soot: it begins at `tip.from`, a fraction
+ * of FIRE_SOOT_SCALE, over `tip.softness`. WHAT COLOUR it is comes from its
+ * temperature (a fraction of FIRE_HEAT_SCALE): the tip gives way to the body
+ * around `tip.to`, and the core begins at `core.from`. Brightness is in
+ * multiples of paper white; colours are sRGB, the way a colour picker gives
+ * them.
+ *
+ * The body is ABOVE paper white. It was once held below it, because under a
+ * bright preset paper sits at the top of the tone curve and anything brighter
+ * loses its colour — and a flame dimmer than the paper behind it, drawn
+ * opaque, is a yellow decal on the sheet, not light. Fire photographed in a
+ * bright room DOES wash out; that is the lighting's to answer (the lab shoots
+ * under `noir`, as the references were), not the flame's.
+ */
+interface FireZones {
+    root: {
+        color: string;
+        amount: number;
+        reach: number;
+    };
+    core: {
+        color: string;
+        glow: number;
+        from: number;
+    };
+    body: {
+        color: string;
+        glow: number;
+    };
+    tip: {
+        color: string;
+        glow: number;
+        from: number;
+        to: number;
+        softness: number;
+        tearing: number;
+    };
+}
+/** Any part of any zone, over the defaults. */
+type FireZonesInput = {
+    [Z in keyof FireZones]?: Partial<FireZones[Z]>;
+};
+/**
+ * The defaults reproduce the look arrived at by measurement against
+ * Flame_base.png (yellow ~30%, orange ~40%, pale ~18% of a flame's pixels),
+ * now expressed zone by zone. Each colour is the linear emission the previous
+ * ramp used in that band, written as the sRGB a picker would show.
+ */
+declare const FIRE_ZONES: FireZones;
+/** The defaults with `input` laid over them, zone by zone. */
+declare function fireZones(input?: FireZonesInput): FireZones;
+/** A `#rrggbb` colour as linear RGB — what a shader multiplies light by. */
+declare function hexToLinear(hex: string): [number, number, number];
+
+interface AfterglowOptions {
+    /**
+     * How long a bead keeps glowing after the heat under it has gone, in
+     * seconds — a range, each cell drawn its own life from it by a seeded hash.
+     */
+    hold?: readonly [number, number];
+    /** Seed for which bead outlives which. */
+    seed?: number;
+}
+/**
+ * The embers a burn leaves behind, drawn over the field it came from.
+ *
+ * `paperlab-fx-fire-spec.md` §9, "Smoulder": after the flames, glowing spots
+ * crawl along the edge, flare on a breath, and go out one by one over
+ * seconds (§4.10). The field cannot do this, and it is not a tuning problem:
+ * a burn blown out loses its heat in a fraction of a second — below ignition
+ * everywhere or it recovers — so its own heat channel has nothing left to
+ * smoulder with.
+ *
+ * So this is presentation, and holds no simulation state. It wraps a field as
+ * a `DamageSource`: every channel is the field's, except HEAT, which is the
+ * field's heat or what each cell remembers of it, whichever is more. When the
+ * heat under a cell goes, the cell keeps a smoulder's worth of it and lets it
+ * go at its own pace — each cell's pace drawn once from a seeded hash, so
+ * beads go out one at a time, and the same burn goes out the same way. A
+ * breath flares what is left.
+ *
+ * Only the sheet reads it. Flames and the fire light read the FIELD, so the
+ * flames die with the gas (§4.1) while the edge keeps glowing; the physics
+ * reads char, saturation and presence, which pass through untouched.
+ */
+declare class Afterglow implements DamageSource {
+    readonly size = 64;
+    readonly pixels: Uint8Array<ArrayBuffer>;
+    private readonly field;
+    private readonly glow;
+    private readonly rate;
+    private revision;
+    private clock;
+    private flare;
+    private lastField;
+    private lit;
+    constructor(field: DamageField, options?: AfterglowOptions);
+    get version(): number;
+    get detail(): number | undefined;
+    /** Its own clock: the beads keep flickering after the field has gone to sleep. */
+    get time(): number;
+    /** Whether anything is still glowing that the field no longer is. */
+    get smouldering(): boolean;
+    /**
+     * Advance by `dt`, after the field has stepped. `blow` is the breath on the
+     * sheet, 0..1: it flares what is left (§10.6, "on smoulder: beads flare,
+     * then fade").
+     */
+    step(dt: number, blow?: number): void;
+    /** Copy the field in, and lay the remembered heat over its heat channel. */
+    private sync;
+}
+
+interface FxFlamesProps {
+    /** The burning field. Flames stand on its hot rim — see `flameAnchors`. */
+    field: DamageField;
+    /** Where a point of the sheet is in the world — `(u, v) => handle.surfacePoint(u, v, scratch)`. */
+    locate: SurfaceLocator;
+    /** How many flames may stand at once: 8 / 16 / 32 on low / medium / high. */
+    quality?: FxQualityTier;
+    /**
+     * The air, world units a second — pass the particle pool's `wind`, which is
+     * read every frame. Flames lean away from it and shorten (§10.6).
+     */
+    wind?: readonly [number, number, number];
+}
+/**
+ * The flames of a burn: separate tongues of burning gas, standing just off
+ * the char, rising straight up whatever the sheet is doing.
+ *
+ * `paperlab-fx-fire-spec.md` §6. Each tongue is a quad that turns to face the
+ * camera about WORLD up — never the sheet's normal (§13.9) — so a flame on a
+ * sheet held flat still rises to the ceiling. The shader is upward-scrolling,
+ * domain-warped noise inside a teardrop, coloured on the flame's own
+ * blackbody ramp: a dim indigo root, a yellow-white core, orange edges and
+ * tips, and a torn top that sheds wisps. Every flame puffs on its own noise
+ * at 10–15 Hz, so no two ever move in step and nothing is a sine.
+ *
+ * Additive and HDR: the core is several times paper white, so `FxPost`
+ * blooms it; it writes no depth, so the flames never occlude each other or
+ * flicker as they sort. It animates on the FIELD's clock, so a replayed burn
+ * burns with the same flames.
+ */
+declare function FxFlames({ field, locate, quality, wind }: FxFlamesProps): react.JSX.Element;
+
+interface FxWispsProps {
+    /** What the sheet draws: where the smouldering beads are. */
+    glow: Afterglow;
+    /** The field under it — a wisp rises where the glow outlives the heat. */
+    field: DamageField;
+    locate: SurfaceLocator;
+    /** The air, read every frame — pass the pool's `wind`. */
+    wind?: readonly [number, number, number];
+}
+/**
+ * The smoulder wisp: the shot people screenshot (`Stage_5__cold.png`).
+ *
+ * Not smoke sprites. A thin, pale thread — a trail of connected points drawn
+ * as a ribbon — rising from a glowing bead once the flames are gone, curving
+ * in a slow S as it climbs, and lingering a few seconds after the last bead
+ * has gone out. One or two at a time.
+ *
+ * Every point's position is a pure function of where and when it left its
+ * bead, on the afterglow's clock, so a scripted burn draws the same wisp
+ * every time and nothing here integrates anything that could drift.
+ */
+declare function FxWisps({ glow, field, locate, wind }: FxWispsProps): react.JSX.Element;
+
+/**
+ * The fire simulator's controls — by the names, and at the defaults, of the
+ * fluid-fire tool Noor pointed at (Emission, Combustion, Fuel & air, Motion
+ * & turbulence), so the lab's panel reads like the one she knows.
+ *
+ * The numbers are the panel's, not the solver's. `solverUniforms` is the one
+ * place they are turned into this solver's units — world units (a default
+ * sheet is one unit, 210 mm, across) and seconds — so a value can be copied
+ * between the two tools and mean roughly the same thing, and so tuning the
+ * look never means renaming a control.
+ *
+ * What the chemistry terms mean here, since no tool documents its own:
+ *
+ *   fuel              gas released at the burning rim, per second.
+ *   premixed oxygen   the share of that gas that arrives already mixed with
+ *                     oxygen — it can burn the moment it leaves the paper.
+ *   ambient oxygen    oxygen in the surrounding air, which fuel burns with as
+ *                     it mixes in. At 0 only the premixed share ever burns,
+ *                     so flames stay close to the rim.
+ *   heat              temperature released with the gas — paper's gas leaves
+ *                     it hot, and that heat is what lets its soot form and
+ *                     glow before it has burnt (swept to 1, most of the flame
+ *                     went out).
+ *   flame persistence how long glowing soot lasts in open air before it
+ *                     burns away — the soot a flame's light comes from.
+ *   air mixing        how fast air works into the fuel, and so how far up a
+ *                     tongue's fuel core survives.
+ */
+interface FireFluidParams {
+    fuel: number;
+    premixedOxygen: number;
+    heat: number;
+    smoke: number;
+    radialImpulse: number;
+    initialVelocity: readonly [number, number, number];
+    burnRate: number;
+    gasExpansion: number;
+    buoyancy: number;
+    cooling: number;
+    smokeProduction: number;
+    ambientOxygen: number;
+    flamePersistence: number;
+    /**
+     * How fast air works its way into the fuel, 0..1. Ours, not the panel's.
+     * Low and the fuel core survives a long way up — tall tongues with long
+     * tips; high and the fuel burns out close to the paper — short licks.
+     */
+    airMixing: number;
+    turbulence: number;
+    turbulenceScale: number;
+    vorticity: number;
+    wind: number;
+    /** How long smoke lingers, in seconds — long enough and it hangs as a haze. Ours, not the panel's. */
+    smokeFade: number;
+    /**
+     * How long a spot of the rim goes on smoking once its flame is out, in
+     * seconds. Ours, not the panel's. Paper does not stop smoking when it stops
+     * burning: the char is still hot, and a thin thread goes on rising from it.
+     */
+    smokeAfter: number;
+}
+/**
+ * The defaults — the panel's names, at the values Noor tuned in the lab on
+ * 2026-09-12. No turbulence of its own: the motion comes from vorticity,
+ * the radial impulse and the uneven rim that feeds it.
+ */
+declare const fireFluidDefaults: FireFluidParams;
+/** Slider ranges for the lab, grouped the way the panel groups them. */
+declare const fireFluidControls: readonly {
+    group: string;
+    key: Exclude<keyof FireFluidParams, 'initialVelocity'>;
+    label: string;
+    min: number;
+    max: number;
+    step: number;
+}[];
+/** What the solver's passes read, in its own units. */
+interface SolverUniforms {
+    fuel: number;
+    premixed: number;
+    heat: number;
+    smoke: number;
+    radial: number;
+    initialVelocity: [number, number];
+    burnRate: number;
+    heatRelease: number;
+    expansion: number;
+    buoyancy: number;
+    cooling: number;
+    smokeProduction: number;
+    smokeFade: number;
+    ambient: number;
+    persistence: number;
+    /** Share of the neighbours' oxygen mixed in per step, in the plane. */
+    mixing: number;
+    /** Per second: air drawn in from in front of and behind the slice. */
+    entrain: number;
+    /** Fuel density at which entrainment is down to 1/e — dense fuel keeps air out. */
+    fuelBlock: number;
+    /** Soot formed per unit of hot fuel a second. */
+    sootYield: number;
+    /** The temperature soot needs to form and glow at. */
+    sootHeat: number;
+    /** Units of air a unit of fuel burns with. */
+    stoich: number;
+    /** Smoke a second, per unit of smouldering strength, where a flame has gone out. */
+    smoulderSmoke: number;
+    /** Heat with it — enough that the smoke rises, not enough to glow. */
+    smoulderHeat: number;
+    turbulence: number;
+    turbulenceScale: number;
+    /** Noise units a second the turbulence changes by, on top of rising with the gas. */
+    turbulenceEvolve: number;
+    vorticity: number;
+    wind: number;
+}
+/**
+ * The panel's numbers, in the solver's units. Every scale here is a tuning
+ * decision made by eye against the references, stated once so it is never
+ * smeared across shaders.
+ */
+declare function solverUniforms(p: FireFluidParams): SolverUniforms;
+
+interface FxFireFluidProps {
+    field: DamageField;
+    locate: SurfaceLocator;
+    quality?: FxQualityTier;
+    /** The simulator's controls; anything left out takes the panel's default. */
+    params?: Partial<FireFluidParams>;
+    /** False freezes the fire where it is — a paused lab. */
+    running?: boolean;
+    /**
+     * Change it to start the fire over: the air is emptied and the fire is
+     * warmed up from the rim as it stands now, so a burn that was just seeked
+     * to a moment shows that moment's flames rather than empty air.
+     */
+    resetKey?: unknown;
+    /** How bright the fire glows, against paper white. */
+    glow?: number;
+    /**
+     * The flame's four zones — root, core, body and tip — each part laid over
+     * `FIRE_ZONES`. See `FireZones` for what each zone is and why it looks the
+     * way it does.
+     */
+    zones?: FireZonesInput;
+    /** The solver temperature that counts as a flame's hottest gas. */
+    heatScale?: number;
+    /** The soot density that counts as a full flame — see `FIRE_SOOT_SCALE`. */
+    sootScale?: number;
+    /** Gamma on the flame's temperature — above 1 darkens the body against the core. */
+    contrast?: number;
+    /** How opaque the densest flame gas is; 0 is purely additive fire. */
+    opacity?: number;
+    /** How opaque gas must be to glow fully; see `FIRE_THIN`. */
+    thin?: number;
+    /**
+     * Seconds of fire run, unseen, whenever it starts over (see `resetKey`).
+     * A plume started from still air rolls its leading edge into a mushroom cap
+     * — the starting vortex — and a fire that has burned for seconds has long
+     * since shed it. Too short and a seeked-to frame shows that cap.
+     */
+    warm?: number;
+    /**
+     * Error-compensated (MacCormack) advection for what is drawn. Defaults to
+     * on everywhere but the `low` tier, where the two extra passes a step are
+     * the first thing a throttled phone should give back.
+     */
+    sharp?: boolean;
+    /**
+     * What to draw where the simulator cannot run (no half-float render
+     * targets) — typically `<FxFlames>`. Drawn INSTEAD, never as well.
+     */
+    fallback?: ReactNode;
+}
+/**
+ * Fire, simulated — the flames and the smoke of a burning sheet as a fluid:
+ * gas released along the hot rim, burning where it has oxygen, rising on its
+ * own heat, torn by turbulence, cooling out of sight, leaving smoke.
+ *
+ * The damage field still decides everything about the PAPER; this is only
+ * what the air above it does. The rim is read on the CPU as emission points —
+ * the same irregular clusters `flameAnchors` stands the sprite flames on, so
+ * the fire still gathers in tall tongues above a hole and short licks below
+ * it — and nothing is ever read back from the GPU.
+ *
+ * It lives in a vertical plane through the sheet, facing the camera, so the
+ * flames rise straight up whatever the sheet is doing. Needs half-float
+ * render targets; where there are none it renders nothing, and the caller
+ * falls back to `FxFlames` (see `FireFluid.supported`).
+ */
+declare function FxFireFluid({ field, locate, quality, params, running, resetKey, glow, zones, heatScale, sootScale, contrast, opacity, thin, warm, sharp, fallback, }: FxFireFluidProps): react.JSX.Element;
+
+/** Grid sizes for one tier. Both grids share the domain's aspect, so cells are square. */
+interface FluidGrid {
+    /** Velocity and pressure — coarse, because they are smooth. */
+    velocity: readonly [number, number];
+    /** Fuel, heat, smoke, flame and air — fine, because that is what is drawn. */
+    dye: readonly [number, number];
+    /** Jacobi iterations for the pressure solve. */
+    iterations: number;
+}
+/** A pair of targets, read one and write the other, swapped after each pass. */
+declare class Pair {
+    read: THREE.WebGLRenderTarget;
+    write: THREE.WebGLRenderTarget;
+    constructor(w: number, h: number);
+    swap(): void;
+    dispose(): void;
+}
+/**
+ * A fire, simulated on the GPU: a 2D grid fluid with combustion.
+ *
+ * Owns its render targets and the passes over them, and nothing about where
+ * the fire is drawn — `FxFireFluid` places it. Every step reads the burning
+ * rim as a list of emission points (position, radius, strength) the caller
+ * works out on the CPU from the damage field, so nothing is ever read back
+ * from the GPU.
+ */
+declare class FireFluid {
+    private readonly renderer;
+    readonly grid: FluidGrid;
+    /** The domain's size in world units — width, height. */
+    readonly domain: {
+        width: number;
+        height: number;
+    };
+    /** (fuel, heat, smoke, soot) on the fine grid — what is drawn. */
+    readonly scalars: Pair;
+    /** (premixed oxygen, ambient oxygen, burn rate, flame heat) on the fine grid. */
+    readonly air: Pair;
+    readonly velocity: Pair;
+    readonly pressure: Pair;
+    /** The rim's emission this step, on the fine grid — see EMIT. */
+    private readonly emit;
+    private readonly divergence;
+    private readonly curl;
+    /** The two intermediate advections the MacCormack step compares. */
+    private readonly forward;
+    private readonly backward;
+    /**
+     * Error-compensated advection for the drawn fields. On by default; off is
+     * a single semi-Lagrangian step, which is two passes a step cheaper and
+     * visibly softer — a knob for the lowest tier, and for an A/B.
+     */
+    sharp: boolean;
+    private readonly scene;
+    private readonly camera;
+    private readonly mesh;
+    private readonly m;
+    private readonly sources;
+    private readonly across;
+    /** Whether this renderer can draw into half-float targets at all. */
+    static supported(renderer: THREE.WebGLRenderer): boolean;
+    constructor(renderer: THREE.WebGLRenderer, grid: FluidGrid, 
+    /** The domain's size in world units — width, height. */
+    domain: {
+        width: number;
+        height: number;
+    });
+    /** Empty air, at the given ambient oxygen. */
+    reset(ambient: number): void;
+    /**
+     * One step of `dt` seconds. `sources` is (u, v, half-length, strength) per
+     * rim segment and `across` is (toward-paper x, y, half-width, offset onto
+     * the paper) — see EMIT — `count` of each; `time` drives the turbulence.
+     */
+    step(dt: number, u: SolverUniforms, sources: Float32Array, across: Float32Array, count: number, time: number): void;
+    dispose(): void;
+    private run;
+    /** Passes change the renderer's target and clearing; put both back. */
+    private withRenderer;
+}
+
+interface FxFireLightProps {
+    field: DamageField;
+    locate: SurfaceLocator;
+    /** How bright the fire is per unit of burning front. Tuned against Hero.png. */
+    gain?: number;
+}
+/**
+ * Fire is a light source (§4.8, §7). A fire that changes nothing around it
+ * looks pasted on.
+ *
+ * A warm point light — about 1900 K — at the middle of the burning rim,
+ * raised by half a flame, as bright as the front is long and flickering on
+ * the very noise the flames puff on, so light and flame agree. It reaches the
+ * whole sheet: `decay` is held below the physical 2, because a sheet is a
+ * small thing next to a fire and Hero.png warms it to the top edge.
+ *
+ * And a dimmer twin on the FAR side of the sheet, for translucency: paper is
+ * thin, and a fire in front of it glows through to the back, warm and
+ * diffused (§7). A second light is the whole trick — the sheet's own
+ * material already lights its back face from whatever is behind it.
+ */
+declare function FxFireLight({ field, locate, gain }: FxFireLightProps): react.JSX.Element;
+
+/** What the page says about the match this frame. Written in place — never a prop change. */
+interface MatchFlameState {
+    /** Where the flame's root is, in world space; null when there is no match. */
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    /** Arming is the dwell before a pinch becomes a match; lit is a match. */
+    state: 'none' | 'arming' | 'lit';
+    /** How hard the viewer is blowing, 0..1. */
+    blow: number;
+    /** Whether the flame is held against the sheet. */
+    touching: boolean;
+    /**
+     * A clock to animate on, in seconds, instead of the frame clock — and
+     * `litAt`, when on that clock the match was struck.
+     *
+     * For a scripted burn (`/fx-lab`) that has to photograph the same match
+     * twice: given both, the flare is a function of time rather than of which
+     * frame saw the strike, and no random sparks or puffs are thrown. A live
+     * hand leaves both out.
+     */
+    time?: number;
+    litAt?: number;
+}
+interface FxMatchFlameProps {
+    /** Read every frame. A ref, so a hand moving the match re-renders nothing. */
+    match: {
+        readonly current: MatchFlameState;
+    };
+}
+/**
+ * A match, held: `paperlab-fx-fire-spec.md` §10, the parts that are the
+ * flame's to draw.
+ *
+ * - **Arming.** Friction building: a few tiny sparks and a warm point that
+ *   grows at the pinch. A pinch released early (a flick) fizzles — nothing
+ *   lights, because the page never says `lit`.
+ * - **Strike.** A one-frame flash of light, a burst of sparks, a puff, and
+ *   the flame flares to about twice its height for under half a second and
+ *   settles — a real match head flares as it burns off.
+ * - **Held.** A 20 mm teardrop that flickers, leans away from where the hand
+ *   is going with a lag, and stretches thin and burns blue and dim when moved
+ *   fast. Against the paper it flattens and spills upward.
+ * - **Blown.** It leans away and flickers hard; when the page says it has
+ *   gone out, it leaves a soft puff behind.
+ * - **Light.** It lights the sheet warm before anything scorches — bringing
+ *   the flame near the paper is the first thing people notice (§10.4).
+ *
+ * It owns its own clock and its own handful of particles: nothing here is
+ * part of a burn anyone replays.
+ */
+declare function FxMatchFlame({ match }: FxMatchFlameProps): react.JSX.Element;
+
+/**
+ * Where a burn's flames stand, read off the field.
+ *
+ * `paperlab-fx-fire-spec.md` §4.1: paper does not burn, the gas does. Heat
+ * cooks the cellulose into gas, which burns just ABOVE the surface, rooted
+ * over the char right behind the ember line — so a flame belongs on the edge
+ * of the hole, where it is hot, and nowhere else. Where the heat has gone
+ * there is no gas left and no flame, even if the edge still glows.
+ *
+ * Pure and deterministic, because flames are part of the picture a capture
+ * compares: the same burn at the same step stands the same flames in the
+ * same places. Anchors are spread along the rim by binning the grid — the
+ * hottest edge cell in each bin — rather than taken in scan order, which
+ * would put all of them on the first rows of the hole.
+ */
+/** One flame: where it stands, how big it is, and who it is. */
+interface FlameAnchor {
+    /** Root, in world space. */
+    x: number;
+    y: number;
+    z: number;
+    /** World units. 10–40 mm at A4 (§6), scaled by heat and by which rim it is on. */
+    height: number;
+    width: number;
+    /** Stable while the cell burns, so a flame keeps its own flicker frame to frame. */
+    seed: number;
+    /** 0..1 — how hot the paper under it is. */
+    heat: number;
+    /** -1 on the lower rim of a hole, +1 on the upper. */
+    upper: number;
+    /**
+     * Which way the paper lies from the root, as a world-space unit vector —
+     * across the rim, into the sheet. Zero where it could not be found. The
+     * simulator lays its gas along the rim with this, rather than in a disc.
+     */
+    nx: number;
+    ny: number;
+    nz: number;
+}
+/** 10 and 40 mm, in world units: a default sheet is one unit (210 mm) across. */
+declare const FLAME_HEIGHT: readonly [number, number];
+/**
+ * Fill `out` with up to `max` flames for the field as it stands at `time`.
+ * Returns how many. `out` is reused and grown, never shrunk.
+ *
+ * Not one flame per stretch of rim — that was a crown. A living, uneven
+ * ring: a noise field around the rim, drifting in time, decides where the
+ * fire gathers. Where it is strong there are clusters of tall tongues with
+ * short ones packed beside them; where it is weak, short licks and gaps.
+ * Which cells carry a flame is redrawn every fraction of a second, and each
+ * flame has its own life that fades it in and out, so clusters break apart
+ * and re-form rather than standing still. All of it is a pure function of
+ * the field and the time: the same burn stands the same flames.
+ */
+declare function flameAnchors(field: DamageField, locate: SurfaceLocator, max: number, out: FlameAnchor[], time?: number): number;
+/**
+ * How much a flame has puffed up at a moment — the same function the flame
+ * shader runs, so the fire light flickers WITH the flames rather than beside
+ * them (§7). Value noise, 10–15 Hz, seeded per flame: neighbours never move
+ * in step, and nothing is a sine.
+ */
+declare function flamePuff(seed: number, time: number): number;
+
+/**
+ * The audio graph: a context, a ceiling, and somewhere for a sound to go.
+ *
+ * There was no audio anywhere in this library or its three apps before this —
+ * not an `AudioContext`, not a clip. Sound was not under-built, it was
+ * absent, and that is most of why the wind reads as weightless: a sheet
+ * moving in silence is a picture of a sheet moving.
+ *
+ * Two decisions are baked in here rather than left to each effect.
+ *
+ * **Synthesis, not samples.** A triggered crumple clip is the same crumple
+ * every time, it does not know how fast you crushed it, and two overlapping
+ * copies turn to mush. Paper sounds are broadband noise shaped by an
+ * envelope, which is the cheapest thing a synthesiser does and the thing
+ * sample playback is worst at. It also means no licensing question at all, in
+ * a repo that has already had to reason carefully about the licence on the
+ * hand-tracking weights.
+ *
+ * **A hard ceiling, from the tier.** Fire and crumple both want to be grain
+ * clouds — dozens of short bursts a second — and a grain cloud with no
+ * ceiling is an unbounded number of live nodes on a phone that is already
+ * running a camera, a hand tracker and a cloth simulation. So voices come
+ * from a fixed pool sized by `fx/quality.ts`, and asking for one past the
+ * ceiling steals the least audible voice rather than allocating. Dropping the
+ * NEW sound would be the obvious alternative and it is wrong: the newest
+ * sound is the one the viewer just caused, and silence in response to an
+ * action reads as a broken page.
+ *
+ * **What is testable, and what is not.** Everything above is policy — pool
+ * size, stealing, the unlock state machine, gain arithmetic — and none of it
+ * needs a browser. The DSP is a handful of node connections that only a
+ * browser can make. So the context is injected rather than constructed, the
+ * policy is tested against a stub, and what ships to the browser is the same
+ * code path with a real `AudioContext` in it.
+ */
+/**
+ * The part of the Web Audio API this uses.
+ *
+ * Written out rather than referring to `AudioContext` so that the policy can
+ * be tested without a DOM, and so that the surface this depends on is small
+ * enough to read. Anything added here is a new thing to stub.
+ */
+interface AudioLike {
+    readonly currentTime: number;
+    readonly state: 'suspended' | 'running' | 'closed';
+    readonly destination: AudioNodeLike;
+    createGain(): GainLike;
+    createBufferSource(): BufferSourceLike;
+    /**
+     * Every paper sound is noise with the wrong frequencies taken out of it —
+     * a fire is a low rumble under a bright crackle, a tear is the same noise
+     * with the bottom removed. Without a filter there is one sound in the whole
+     * library: white noise at different volumes.
+     */
+    createBiquadFilter(): BiquadFilterLike;
+    /**
+     * Where the sound is. A sheet you are holding at arm's length, burning at
+     * one corner, is not a sound in the middle of your head.
+     */
+    createPanner(): PannerLike;
+    createBuffer(channels: number, length: number, sampleRate: number): AudioBufferLike;
+    readonly sampleRate: number;
+    resume(): Promise<void>;
+    close(): Promise<void>;
+}
+interface AudioNodeLike {
+    connect(destination: AudioNodeLike): void;
+    disconnect(): void;
+}
+interface AudioParamLike {
+    value: number;
+    setValueAtTime(value: number, when: number): void;
+    linearRampToValueAtTime(value: number, when: number): void;
+    cancelScheduledValues(when: number): void;
+}
+interface GainLike extends AudioNodeLike {
+    readonly gain: AudioParamLike;
+}
+interface BiquadFilterLike extends AudioNodeLike {
+    type: 'lowpass' | 'highpass' | 'bandpass' | 'notch' | 'peaking' | 'lowshelf' | 'highshelf' | 'allpass';
+    readonly frequency: AudioParamLike;
+    readonly Q: AudioParamLike;
+}
+interface PannerLike extends AudioNodeLike {
+    panningModel: 'equalpower' | 'HRTF';
+    distanceModel: 'linear' | 'inverse' | 'exponential';
+    refDistance: number;
+    maxDistance: number;
+    rolloffFactor: number;
+    readonly positionX: AudioParamLike;
+    readonly positionY: AudioParamLike;
+    readonly positionZ: AudioParamLike;
+}
+interface AudioBufferLike {
+    getChannelData(channel: number): Float32Array;
+    readonly length: number;
+}
+interface BufferSourceLike extends AudioNodeLike {
+    buffer: AudioBufferLike | null;
+    loop: boolean;
+    /**
+     * `offset` and `duration` are what make one shared second of noise into
+     * every crackle in a fire: a different slice each time, ending itself
+     * without anything having to schedule a stop.
+     */
+    start(when?: number, offset?: number, duration?: number): void;
+    stop(when?: number): void;
+    onended: (() => void) | null;
+}
+interface FxAudioOptions {
+    quality?: FxQualityName | FxQualitySettings;
+    /**
+     * The context to use. Required, and never made for you: constructing an
+     * `AudioContext` is a side effect with a user-visible cost (a browser tab
+     * shows an audio indicator), and a class that made one on construction
+     * would take that from a page that never asked. Get a browser one from
+     * `createAudioContext()`, inside the gesture that should start the sound.
+     */
+    context: AudioLike;
+    /** Master level, 0..1. */
+    volume?: number;
+}
+/** A sound in flight. Handed back so a caller can shape or stop it. */
+interface Voice {
+    readonly id: number;
+    /** What this voice is for. Only used to explain who got stolen. */
+    readonly kind: string;
+    /**
+     * How much this voice deserves to survive, 0..1.
+     *
+     * The ONLY input to stealing, and it is not loudness. A near-silent tail of
+     * a crackle is worth less than a quiet new ignition, because one is ending
+     * and the other is something the viewer just did. Effects set this and the
+     * pool obeys it.
+     */
+    priority: number;
+    readonly gain: GainLike;
+    readonly startedAt: number;
+    /**
+     * Hand a source to this voice, so it lives and dies with it.
+     *
+     * Every source that plays through a voice must be given to it, because the
+     * voice is the only thing that knows when to stop it. A voice that did not
+     * own its sources could only fade its gain when stolen — and a looping bed
+     * behind a silent gain keeps running, and keeps its nodes, for the life of
+     * the page.
+     *
+     * A one-shot that ends on its own ends the voice with it; a voice already
+     * released stops the source at once rather than letting it play unheard.
+     */
+    own(source: BufferSourceLike): void;
+    /**
+     * Hand a NODE to this voice, so it is disconnected with it.
+     *
+     * The same rule as {@link own}, for the filters and panners a sound is
+     * shaped by. A crackle makes its own filter — a few dozen a second in a
+     * good burn — and a filter left connected to a freed gain is the same leak
+     * the sources used to have, in a part of the graph nothing was watching.
+     */
+    use(node: AudioNodeLike): void;
+    /** Stop and return this voice to the pool. */
+    stop(): void;
+}
+declare class FxAudio {
+    readonly quality: FxQualitySettings;
+    private readonly ctx;
+    private readonly master;
+    private readonly live;
+    /**
+     * What each voice owns, until the last of it has actually stopped.
+     *
+     * Outlives the voice's place in `live` on purpose: a stolen voice leaves the
+     * pool at once, so the new sound can have its slot, but its sources are
+     * still fading for a few milliseconds and its gain is still connected. The
+     * nodes are freed when the last source reports `ended`, not before — cut
+     * sooner and the fade that stops stealing from clicking is cut with it.
+     */
+    private readonly slots;
+    private nextId;
+    private unlocked;
+    private noise;
+    constructor(options: FxAudioOptions);
+    get context(): AudioLike;
+    /** Live voices right now. Never more than the tier's ceiling. */
+    get voices(): readonly Voice[];
+    get isUnlocked(): boolean;
+    get volume(): number;
+    set volume(value: number);
+    /**
+     * Let sound happen, from inside a user gesture.
+     *
+     * Every browser starts an `AudioContext` suspended until a real interaction
+     * resumes it, and a page that calls this from anywhere else is a page whose
+     * audio silently never starts. Here the cost is zero: `/hands` already has
+     * a button that turns the camera on, and nothing can be heard before the
+     * camera is on anyway.
+     *
+     * Safe to call more than once — it is a latch, not a toggle.
+     */
+    unlock(): Promise<void>;
+    /**
+     * One second of white noise, made once and shared.
+     *
+     * Nearly every paper sound is filtered noise — a crumple is a cloud of
+     * short bursts of it, a fire is a bed of it, a tear is a fast train of it —
+     * so this is the single most reused object in the graph. Generating it per
+     * voice would allocate a second of audio per crackle.
+     */
+    noiseBuffer(): AudioBufferLike;
+    /**
+     * Take a voice, stealing the least deserving one if the pool is full.
+     *
+     * Returns null only when the ceiling is zero or the caller's priority is
+     * below everything already playing — the one case where refusing is right,
+     * because the alternative is cutting off something more important to play
+     * something less.
+     */
+    take(kind: string, priority?: number): Voice | null;
+    private own;
+    private useNode;
+    private ended;
+    /** Disconnect a voice's gain. Only once nothing that feeds it is still running. */
+    private free;
+    /**
+     * Return a voice to the pool, fading it out first.
+     *
+     * The fade is the whole reason this is not just a splice. Cutting a
+     * waveform mid-cycle produces a step, and a step is a click — audible,
+     * cheap-sounding, and most likely to happen exactly when the most is going
+     * on, since that is when voices get stolen.
+     */
+    private release;
+    /** Stop everything. The panic button, and what unmounting calls. */
+    stopAll(): void;
+    /**
+     * A short tone, to prove the chain end to end.
+     *
+     * Deliberately part of the shipped surface rather than a test fixture:
+     * "is the audio graph actually connected" is a question that comes up on
+     * every device, and the honest answer is a sound you can hear. It uses the
+     * same path everything else does — a voice from the pool, the noise buffer,
+     * the master gain — so if this is audible the path works.
+     */
+    test(duration?: number): Voice | null;
+    /** Release the context. Nothing survives this. */
+    dispose(): Promise<void>;
+}
+/**
+ * Make a real browser context.
+ *
+ * Separate from the constructor so that importing this module never starts an
+ * audio context — a browser shows an indicator for one, and a library that
+ * lights it up on import is a library that has taken something that was not
+ * offered.
+ */
+declare function createAudioContext(): AudioLike;
+
+/**
+ * What a burning sheet sounds like, driven by the numbers that make it burn.
+ *
+ * Two layers, and the split is the whole design.
+ *
+ * A **bed**: one looping band of filtered noise whose level follows the
+ * LENGTH of the burn front. Not the burnt area — a fire gets louder as its
+ * edge gets longer, and a nearly-consumed sheet is quiet again, which a level
+ * driven by char would get exactly backwards. It brightens as it grows too:
+ * a big fire is not a small fire turned up.
+ *
+ * A **crackle**: one short burst of bright noise for every few texels that
+ * char, so the rate is the rate the paper is actually catching. Each is a
+ * different slice of the shared second of noise through its own bandpass, so
+ * no two are the same sound; each ends itself.
+ *
+ * Both read `FieldStats` and nothing else. Sound and picture therefore cannot
+ * drift apart: the number that raises the flame's glow is the number that
+ * raises its voice. A seed makes a replayed burn crackle the same way, which
+ * is the same property the untiered simulation exists to give.
+ */
+interface FireSoundOptions {
+    /** Loudest the bed gets, 0..1. */
+    volume?: number;
+    /**
+     * The front length that counts as a fire at full blast, as the fraction of
+     * the sheet's texels on it. Four percent of a 64² grid is about 160 cells,
+     * which is a sheet burning across its whole width.
+     */
+    fullFront?: number;
+    /** Crackles per texel that chars. */
+    crackle?: number;
+    /** So the same burn sounds the same twice. */
+    seed?: number;
+}
+/** A place in the world, as little of one as this needs. */
+interface SoundAt {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+declare class FireSound {
+    private readonly audio;
+    private readonly o;
+    private bed;
+    private level;
+    private debt;
+    private state;
+    constructor(audio: FxAudio, options?: FireSoundOptions);
+    /** True while the bed is playing. */
+    get burning(): boolean;
+    /**
+     * Call once a frame with what the field just did, and where the sheet is.
+     *
+     * `at` is optional: without it the fire is not placed in the room, which is
+     * right for a sheet filling the frame and wrong for one held at arm's
+     * length.
+     */
+    update(dt: number, stats: FieldStats, at?: SoundAt | null): void;
+    /**
+     * A match struck: the scratch of the head across the box, then the hiss of
+     * it flaring as the head burns off (spec §10.2). Two bursts of the shared
+     * noise, one bright and short, one breathier and longer.
+     */
+    strike(): void;
+    /** Blown out: a soft, low breath of noise (spec §10.6). */
+    puff(): void;
+    /** One ember popping in the air — a tiny click on the frame it flashes (spec §8.1). */
+    pop(): void;
+    /** Silence, now — the flame blown out, or the page going away. */
+    stop(): void;
+    private startBed;
+    private driveBed;
+    private stopBed;
+    private crackle;
+    /**
+     * One shaped burst of the shared noise through one filter — what strike,
+     * puff and pop are made of. `delay` starts it a moment late, which is how
+     * the flare follows the scratch.
+     */
+    private burst;
+    /** xorshift32 — its own stream, so nothing else can shift the crackle. */
+    private next;
+}
+
+export { Afterglow, type AfterglowOptions, type AudioLike, type BiquadFilterLike, CHAR, DamageField, type DamageFieldOptions, DamageSource, FIELD_SIZE, FIRE_GLOW, FIRE_HEAT_SCALE, FIRE_SOOT_SCALE, FIRE_ZONES, FIXED_DT, FLAME_HEIGHT, FX_BLOOM, FX_BLOOM_THRESHOLD, FX_INITIAL_TIER, FX_TIER_ORDER, type FieldStats, FireEmitter, type FireEmitterOptions, FireFluid, type FireFluidParams, FireSound, type FireSoundOptions, type FireZones, type FireZonesInput, type FlameAnchor, type FluidGrid, FxAudio, type FxAudioOptions, type FxFilm, FxFireFluid, type FxFireFluidProps, FxFireLight, type FxFireLightProps, FxFlames, type FxFlamesProps, FxMatchFlame, type FxMatchFlameProps, FxParticles, type FxParticlesProps, FxPost, type FxPostProps, type FxQualityName, type FxQualitySettings, type FxQualityTier, FxWisps, type FxWispsProps, HEAT, type MatchFlameState, PAPER_WHITE, PRESENCE, type PannerLike, ParticlePool, type ParticlePreset, type ParticlePresetName, type ParticleTarget, SATURATION, type SolverUniforms, type SoundAt, type SurfaceLocator, type Voice, createAudioContext, emit, emitHex, fireEmitterDefaults, fireFluidControls, fireFluidDefaults, fireZones, flameAnchors, flamePuff, fxQualityFor, fxQualityNames, fxQualityTiers, hexToLinear, luminance, particlePresets, solverUniforms, srgbToLinear, timesPaperWhite };