@driftengine/chemistry 3.61.0

package/dist/parcel/tier.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Four levels of detail, and every one of them conserves.
+ *
+ * **`§14`'s table.** A parcel far away or barely doing anything does not need sixteen shells and a
+ * tick of its own; a burning log in the player's hand does. The tiers are the two axes that matter:
+ * how finely the depth is resolved, and how often the chemistry runs.
+ *
+ * | Tier | Shells | Chemistry | Substeps |
+ * |---|---|---|---|
+ * | `Hero` | as declared | every tick | 32 |
+ * | `Near` | 4 | every tick | 8 |
+ * | `Far` | 2 | every 4th tick, 4× step | 4 |
+ * | `Distant` | 1 | every 16th tick, 16× step | 2 |
+ *
+ * **A tier only ever reduces resolution.** `Hero` is what the substance's author asked for, and a
+ * tier that invented shells would be inventing a depth profile nobody measured.
+ *
+ * **`Far` and `Distant` integrate the same `dt`, just less often**, with the accumulated step handed
+ * over when their turn comes. That is what makes a cadence conserving for free: the same seconds are
+ * integrated either way, at a coarser resolution in time.
+ */
+export declare const TIER_HERO = 0;
+export declare const TIER_NEAR = 1;
+export declare const TIER_FAR = 2;
+export declare const TIER_DISTANT = 3;
+export type Tier = typeof TIER_HERO | typeof TIER_NEAR | typeof TIER_FAR | typeof TIER_DISTANT;
+export declare const TIER_COUNT = 4;
+/** Shells each tier resolves to, capped by what the substance declared. */
+export declare const TIER_SHELLS: readonly number[];
+/** Ticks between updates. A parcel skipped for three ticks is stepped with four ticks of `dt`. */
+export declare const TIER_CADENCE: readonly number[];
+/** The most sub-steps a reaction solve will take at this tier. */
+export declare const TIER_SUBSTEPS: readonly number[];
+/**
+ * Which shells of an `n`-shell parcel make up target shell `j` of `m`, as a half-open range in
+ * **fractional** shell coordinates.
+ *
+ * The fold is a proportional redistribution: target `j` takes `[j·n/m, (j+1)·n/m)`, splitting a
+ * source shell where the ratio is not an integer. Every target ends with exactly `n/m` shells' worth
+ * of mass, which is what keeps the result equal-mass — and equal mass is the invariant conduction
+ * rests on, so this is not a detail.
+ */
+export declare function foldSpan(from: number, to: number, target: number): {
+    start: number;
+    end: number;
+};
+/** How much of source shell `i` belongs to a target spanning `[start, end)`. 0 to 1. */
+export declare function foldShare(i: number, start: number, end: number): number;

package/dist/parcel/tier.js

@@ -0,0 +1,51 @@
+/**
+ * Four levels of detail, and every one of them conserves.
+ *
+ * **`§14`'s table.** A parcel far away or barely doing anything does not need sixteen shells and a
+ * tick of its own; a burning log in the player's hand does. The tiers are the two axes that matter:
+ * how finely the depth is resolved, and how often the chemistry runs.
+ *
+ * | Tier | Shells | Chemistry | Substeps |
+ * |---|---|---|---|
+ * | `Hero` | as declared | every tick | 32 |
+ * | `Near` | 4 | every tick | 8 |
+ * | `Far` | 2 | every 4th tick, 4× step | 4 |
+ * | `Distant` | 1 | every 16th tick, 16× step | 2 |
+ *
+ * **A tier only ever reduces resolution.** `Hero` is what the substance's author asked for, and a
+ * tier that invented shells would be inventing a depth profile nobody measured.
+ *
+ * **`Far` and `Distant` integrate the same `dt`, just less often**, with the accumulated step handed
+ * over when their turn comes. That is what makes a cadence conserving for free: the same seconds are
+ * integrated either way, at a coarser resolution in time.
+ */
+export const TIER_HERO = 0;
+export const TIER_NEAR = 1;
+export const TIER_FAR = 2;
+export const TIER_DISTANT = 3;
+export const TIER_COUNT = 4;
+/** Shells each tier resolves to, capped by what the substance declared. */
+export const TIER_SHELLS = [16, 4, 2, 1];
+/** Ticks between updates. A parcel skipped for three ticks is stepped with four ticks of `dt`. */
+export const TIER_CADENCE = [1, 1, 4, 16];
+/** The most sub-steps a reaction solve will take at this tier. */
+export const TIER_SUBSTEPS = [32, 8, 4, 2];
+/**
+ * Which shells of an `n`-shell parcel make up target shell `j` of `m`, as a half-open range in
+ * **fractional** shell coordinates.
+ *
+ * The fold is a proportional redistribution: target `j` takes `[j·n/m, (j+1)·n/m)`, splitting a
+ * source shell where the ratio is not an integer. Every target ends with exactly `n/m` shells' worth
+ * of mass, which is what keeps the result equal-mass — and equal mass is the invariant conduction
+ * rests on, so this is not a detail.
+ */
+export function foldSpan(from, to, target) {
+    const width = from / to;
+    return { start: target * width, end: (target + 1) * width };
+}
+/** How much of source shell `i` belongs to a target spanning `[start, end)`. 0 to 1. */
+export function foldShare(i, start, end) {
+    const low = i > start ? i : start;
+    const high = i + 1 < end ? i + 1 : end;
+    return high > low ? high - low : 0;
+}

package/dist/present/audio.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A fire as three numbers, and **this package never touches `@driftengine/audio`**.
+ *
+ * `§17` is deliberate about that: what a fire sounds like is a consumer's decision made with
+ * quantities the model already has, and a chemistry package that reached for a mix bus would have
+ * imported an engine package for the first time to play a sound.
+ *
+ * All three are *rates and levels* rather than volumes. A consumer maps them to whatever their mix
+ * wants; nothing here knows what a decibel is worth in their game.
+ */
+/**
+ * How fast it crackles, from the volatile release rate and the area releasing them.
+ *
+ * **Crackling is pockets of gas bursting out of the wood**, so it tracks pyrolysis rather than a
+ * flag — which means it starts before the flame does, peaks while the log is gasifying hardest, and
+ * fades on its own as the volatiles run out. A loop played while `burning` is true does none of that.
+ *
+ * @param fuelFlux kg/(m²·s) of combustible gas leaving the surface.
+ * @param area m² of that surface.
+ */
+export declare function crackleRate(fuelFlux: number, area: number): number;
+/**
+ * How hard it hisses, from the steam leaving rather than the fuel.
+ *
+ * The difference between the two fluxes is the whole reason both are stored: a green log hisses and
+ * does not crackle, a seasoned one crackles and does not hiss, and a log part-way through does both
+ * in the proportion its own drying front is at.
+ *
+ * @param steamFlux kg/(m²·s) of water vapour leaving the surface.
+ */
+export declare function hissRate(steamFlux: number, area: number): number;
+/**
+ * How loud it roars, from the air it entrains.
+ *
+ * A fire's roar is the sound of air being pulled into the plume, so it goes with the plume's own
+ * velocity — and as the **square** of it, because acoustic power does. That is why a large fire is
+ * disproportionately louder rather than proportionally louder.
+ *
+ * @param entrainedSpeed m/s of gas rising in the plume, which the field reports as `riseAt`.
+ */
+export declare function roarLevel(entrainedSpeed: number): number;

package/dist/present/audio.js

@@ -0,0 +1,50 @@
+/**
+ * A fire as three numbers, and **this package never touches `@driftengine/audio`**.
+ *
+ * `§17` is deliberate about that: what a fire sounds like is a consumer's decision made with
+ * quantities the model already has, and a chemistry package that reached for a mix bus would have
+ * imported an engine package for the first time to play a sound.
+ *
+ * All three are *rates and levels* rather than volumes. A consumer maps them to whatever their mix
+ * wants; nothing here knows what a decibel is worth in their game.
+ */
+/** Bursts per second per unit rate, at one square metre. A gain, and the only one in this file. */
+const CRACKLE_GAIN = 900;
+const HISS_GAIN = 40;
+/**
+ * How fast it crackles, from the volatile release rate and the area releasing them.
+ *
+ * **Crackling is pockets of gas bursting out of the wood**, so it tracks pyrolysis rather than a
+ * flag — which means it starts before the flame does, peaks while the log is gasifying hardest, and
+ * fades on its own as the volatiles run out. A loop played while `burning` is true does none of that.
+ *
+ * @param fuelFlux kg/(m²·s) of combustible gas leaving the surface.
+ * @param area m² of that surface.
+ */
+export function crackleRate(fuelFlux, area) {
+    return fuelFlux > 0 ? fuelFlux * area * CRACKLE_GAIN : 0;
+}
+/**
+ * How hard it hisses, from the steam leaving rather than the fuel.
+ *
+ * The difference between the two fluxes is the whole reason both are stored: a green log hisses and
+ * does not crackle, a seasoned one crackles and does not hiss, and a log part-way through does both
+ * in the proportion its own drying front is at.
+ *
+ * @param steamFlux kg/(m²·s) of water vapour leaving the surface.
+ */
+export function hissRate(steamFlux, area) {
+    return steamFlux > 0 ? steamFlux * area * HISS_GAIN : 0;
+}
+/**
+ * How loud it roars, from the air it entrains.
+ *
+ * A fire's roar is the sound of air being pulled into the plume, so it goes with the plume's own
+ * velocity — and as the **square** of it, because acoustic power does. That is why a large fire is
+ * disproportionately louder rather than proportionally louder.
+ *
+ * @param entrainedSpeed m/s of gas rising in the plume, which the field reports as `riseAt`.
+ */
+export function roarLevel(entrainedSpeed) {
+    return entrainedSpeed > 0 ? entrainedSpeed * entrainedSpeed : 0;
+}

package/dist/present/blackbody.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A hot surface's colour, from Planck's law rather than from a gradient somebody liked.
+ *
+ * **`§8.5` and `§17` both lean on this.** A char surface at 1,000 K is a dull red and at 1,300 K is
+ * orange, and the reason is not a decision: at 1,000 K a blackbody puts nineteen times more power
+ * at 600 nm than at 450, and by 3,000 K the two are within a factor of three. Sampling the same law
+ * at three wavelengths reproduces that progression exactly, and an ember therefore has the right
+ * colour without anybody having chosen one.
+ *
+ * **Tabulated, because `exp` may not run on a frame any more than on a tick.** 256 knots over
+ * 600-4,000 K, which is every temperature a fire reaches; the ratios between channels vary smoothly
+ * enough over that range that linear interpolation is invisible.
+ *
+ * ---
+ *
+ * ## What this is not, stated rather than left to be discovered
+ *
+ * **It samples Planck at three wavelengths; it does not integrate against the CIE colour-matching
+ * functions.** A proper conversion integrates the spectrum against three overlapping curves and
+ * lands in XYZ, and the chromaticity that comes out is not quite the chromaticity of three point
+ * samples. What is right here is the **hue progression** — red, orange, yellow, white, in the order
+ * and roughly at the temperatures a real one does it. What is approximate is the exact chromaticity.
+ *
+ * **Reversal:** integrate against the CIE curves, tabulated the same way, if a consumer ever needs a
+ * blackbody to match a reference photograph. It is a bigger table and the same interface.
+ */
+/**
+ * K below which nothing is emitted at all.
+ *
+ * **Not a fade from room temperature**, which is the tempting shape and the wrong one: a surface at
+ * 400 K radiates plenty and none of it is visible, so an emissive term that faded smoothly would
+ * make every warm object in a scene glow faintly in the dark. 600 K is roughly where a real surface
+ * becomes visible as a dull red in an unlit room, which is the threshold this models.
+ */
+export declare const GLOW_MIN_TEMPERATURE = 600;
+/**
+ * Linear RGB for a surface at `temperature`, normalised so the brightest channel is one.
+ *
+ * **A hue, not a brightness.** Separating them is what lets a consumer tone-map: at Stefan-Boltzmann
+ * scaling a 3,000 K flame is over eighty times a 1,000 K ember, and a colour channel carrying that
+ * range has nothing left for the colour. `glowIntensity` is the other half.
+ *
+ * Writes into `out` and allocates nothing, because this runs per parcel per frame.
+ */
+export declare function blackbodyRGB(temperature: number, out: Float32Array): void;
+/**
+ * How brightly it glows, relative to 1,000 K.
+ *
+ * `(T/1000)⁴` — Stefan-Boltzmann, and one multiply chain rather than a `pow`. Doubling the
+ * temperature is sixteen times the power, which is why an ember beside a flame is not nearly as much
+ * cooler as it looks.
+ *
+ * Zero below `GLOW_MIN_TEMPERATURE`, for the reason that constant gives.
+ */
+export declare function glowIntensity(temperature: number): number;

package/dist/present/blackbody.js

@@ -0,0 +1,112 @@
+/**
+ * A hot surface's colour, from Planck's law rather than from a gradient somebody liked.
+ *
+ * **`§8.5` and `§17` both lean on this.** A char surface at 1,000 K is a dull red and at 1,300 K is
+ * orange, and the reason is not a decision: at 1,000 K a blackbody puts nineteen times more power
+ * at 600 nm than at 450, and by 3,000 K the two are within a factor of three. Sampling the same law
+ * at three wavelengths reproduces that progression exactly, and an ember therefore has the right
+ * colour without anybody having chosen one.
+ *
+ * **Tabulated, because `exp` may not run on a frame any more than on a tick.** 256 knots over
+ * 600-4,000 K, which is every temperature a fire reaches; the ratios between channels vary smoothly
+ * enough over that range that linear interpolation is invisible.
+ *
+ * ---
+ *
+ * ## What this is not, stated rather than left to be discovered
+ *
+ * **It samples Planck at three wavelengths; it does not integrate against the CIE colour-matching
+ * functions.** A proper conversion integrates the spectrum against three overlapping curves and
+ * lands in XYZ, and the chromaticity that comes out is not quite the chromaticity of three point
+ * samples. What is right here is the **hue progression** — red, orange, yellow, white, in the order
+ * and roughly at the temperatures a real one does it. What is approximate is the exact chromaticity.
+ *
+ * **Reversal:** integrate against the CIE curves, tabulated the same way, if a consumer ever needs a
+ * blackbody to match a reference photograph. It is a bigger table and the same interface.
+ */
+/**
+ * K below which nothing is emitted at all.
+ *
+ * **Not a fade from room temperature**, which is the tempting shape and the wrong one: a surface at
+ * 400 K radiates plenty and none of it is visible, so an emissive term that faded smoothly would
+ * make every warm object in a scene glow faintly in the dark. 600 K is roughly where a real surface
+ * becomes visible as a dull red in an unlit room, which is the threshold this models.
+ */
+export const GLOW_MIN_TEMPERATURE = 600;
+const TABLE_MIN = GLOW_MIN_TEMPERATURE;
+const TABLE_MAX = 4000;
+const KNOTS = 256;
+/**
+ * The three wavelengths sampled, in metres: 600, 550 and 450 nm.
+ *
+ * Roughly where the human red, green and blue responses peak. Point samples rather than curves —
+ * see the header on what that costs.
+ */
+const WAVELENGTHS = [600e-9, 550e-9, 450e-9];
+/** Planck's second radiation constant, `h·c/k`, in metre-kelvin. */
+const C2 = 1.438776877e-2;
+/**
+ * Spectral radiance at a wavelength and temperature, up to constants that cancel on normalisation.
+ *
+ * `λ⁻⁵ / (exp(hc/λkT) − 1)`, and the leading `2hc²` is dropped because every channel carries it and
+ * the result is divided by its own maximum.
+ */
+function planck(wavelength, temperature) {
+    const x = C2 / (wavelength * temperature);
+    /* `expm1` rather than `exp(x) - 1`: at low temperature `x` is large and the subtraction is fine,
+       but at high temperature it approaches zero from above and the naive form loses every digit. */
+    // determinism: build-time — presentation: Planck into a glow colour, never simulation state
+    return 1 / (wavelength ** 5 * Math.expm1(x));
+}
+/** Three channels per knot, normalised so the brightest is one. */
+const TABLE = (() => {
+    const table = new Float32Array(KNOTS * 3);
+    for (let i = 0; i < KNOTS; i++) {
+        const temperature = TABLE_MIN + ((TABLE_MAX - TABLE_MIN) * i) / (KNOTS - 1);
+        let peak = 0;
+        for (let c = 0; c < 3; c++) {
+            const value = planck(WAVELENGTHS[c], temperature);
+            table[i * 3 + c] = value;
+            if (value > peak)
+                peak = value;
+        }
+        for (let c = 0; c < 3; c++)
+            table[i * 3 + c] = table[i * 3 + c] / peak;
+    }
+    return table;
+})();
+/**
+ * Linear RGB for a surface at `temperature`, normalised so the brightest channel is one.
+ *
+ * **A hue, not a brightness.** Separating them is what lets a consumer tone-map: at Stefan-Boltzmann
+ * scaling a 3,000 K flame is over eighty times a 1,000 K ember, and a colour channel carrying that
+ * range has nothing left for the colour. `glowIntensity` is the other half.
+ *
+ * Writes into `out` and allocates nothing, because this runs per parcel per frame.
+ */
+export function blackbodyRGB(temperature, out) {
+    const clamped = temperature <= TABLE_MIN ? TABLE_MIN : temperature >= TABLE_MAX ? TABLE_MAX : temperature;
+    const position = ((clamped - TABLE_MIN) / (TABLE_MAX - TABLE_MIN)) * (KNOTS - 1);
+    const low = Math.floor(position);
+    const high = low + 1 >= KNOTS ? low : low + 1;
+    const at = position - low;
+    for (let c = 0; c < 3; c++) {
+        out[c] = TABLE[low * 3 + c] * (1 - at) + TABLE[high * 3 + c] * at;
+    }
+}
+/**
+ * How brightly it glows, relative to 1,000 K.
+ *
+ * `(T/1000)⁴` — Stefan-Boltzmann, and one multiply chain rather than a `pow`. Doubling the
+ * temperature is sixteen times the power, which is why an ember beside a flame is not nearly as much
+ * cooler as it looks.
+ *
+ * Zero below `GLOW_MIN_TEMPERATURE`, for the reason that constant gives.
+ */
+export function glowIntensity(temperature) {
+    if (temperature < GLOW_MIN_TEMPERATURE)
+        return 0;
+    const t = temperature / 1000;
+    const square = t * t;
+    return square * square;
+}

package/dist/present/flame.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Metres of visible flame over a fire of `kilowatts` on a base `diameter` metres across.
+ *
+ * **Heskestad's correlation, `L = 0.235·Q^(2/5) − 1.02·D`**, which is the standard flame-height
+ * relation in fire engineering and is here verbatim. A 100 kW campfire over a 0.3 m base stands
+ * 1.18 m; a megawatt over a metre stands 2.71.
+ *
+ * **The two-fifths power is the interesting part**: ten times the fire is two and a half times the
+ * flame, which is why a large fire looks less impressive than its output suggests and why the
+ * flames over a room fire are shorter than people draw them.
+ *
+ * Clamped at zero, and a negative result is physics rather than a domain error: a few kilowatts
+ * spread over a metre is a smouldering surface with no standing flame over it at all.
+ */
+export declare function flameHeight(kilowatts: number, diameter: number): number;
+/**
+ * How luminous the soot makes a flame, 0 to 1, from the equivalence ratio.
+ *
+ * Zero for a lean flame — there is no soot in one, which is why a gas ring is nearly invisible in
+ * daylight — climbing through the band where soot forms. Above `SOOT_FULL` the flame is too rich to
+ * burn at all and what leaves is smoke, which `§8.4` says and the field's own chemistry produces;
+ * this stays at one rather than pretending to model that.
+ */
+export declare function sootLuminosity(equivalenceRatio: number): number;
+/**
+ * A flame's linear RGB: incandescent soot mixed with chemiluminescence by the equivalence ratio.
+ *
+ * `§8.4` again — the model computes φ and the soot mass, and this maps them. The result is that
+ * **nobody chose a flame colour**: a methanol flame is nearly invisible, a candle is orange, a
+ * bunsen burner with its collar open is blue, and all three come out of one ratio.
+ *
+ * Writes into `out`, allocates nothing.
+ */
+export declare function flameColour(equivalenceRatio: number, temperature: number, out: Float32Array): void;

package/dist/present/flame.js

@@ -0,0 +1,103 @@
+/**
+ * What a flame looks like, from what it is doing.
+ *
+ * **Nothing here is an art direction.** Its height is the published plume correlation over its own
+ * heat release; its colour is `§8.4`'s argument that a luminous flame is orange because it contains
+ * incandescent soot and a clean one is blue because it does not. A gas ring is short and blue and a
+ * bonfire is tall and orange for the reasons they actually are.
+ */
+import { blackbodyRGB } from './blackbody.js';
+/**
+ * `Q^(2/5)`, tabulated, because `pow` is a transcendental and this runs per fire per frame.
+ *
+ * Knots uniform in `Q^(1/2)` rather than in `Q`, which puts them where the curve bends: the
+ * two-fifths power changes fastest near zero, and uniform-in-Q knots would spend three hundred of
+ * them on the flat end and none on the part where a fire grows from nothing.
+ */
+const POWER_MIN = 0;
+const POWER_MAX = 20000;
+const POWER_KNOTS = 512;
+const POWER_TABLE = (() => {
+    const table = new Float64Array(POWER_KNOTS);
+    const rootMax = Math.sqrt(POWER_MAX);
+    for (let i = 0; i < POWER_KNOTS; i++) {
+        const root = (rootMax * i) / (POWER_KNOTS - 1);
+        // determinism: build-time — presentation: a flame-height lookup table, built once
+        table[i] = (root * root) ** 0.4;
+    }
+    return table;
+})();
+function twoFifths(kilowatts) {
+    if (!(kilowatts > POWER_MIN))
+        return 0;
+    if (kilowatts >= POWER_MAX)
+        return POWER_TABLE[POWER_KNOTS - 1];
+    const position = (Math.sqrt(kilowatts) / Math.sqrt(POWER_MAX)) * (POWER_KNOTS - 1);
+    const low = Math.floor(position);
+    const at = position - low;
+    return POWER_TABLE[low] * (1 - at) + POWER_TABLE[low + 1] * at;
+}
+/**
+ * Metres of visible flame over a fire of `kilowatts` on a base `diameter` metres across.
+ *
+ * **Heskestad's correlation, `L = 0.235·Q^(2/5) − 1.02·D`**, which is the standard flame-height
+ * relation in fire engineering and is here verbatim. A 100 kW campfire over a 0.3 m base stands
+ * 1.18 m; a megawatt over a metre stands 2.71.
+ *
+ * **The two-fifths power is the interesting part**: ten times the fire is two and a half times the
+ * flame, which is why a large fire looks less impressive than its output suggests and why the
+ * flames over a room fire are shorter than people draw them.
+ *
+ * Clamped at zero, and a negative result is physics rather than a domain error: a few kilowatts
+ * spread over a metre is a smouldering surface with no standing flame over it at all.
+ */
+export function flameHeight(kilowatts, diameter) {
+    const height = 0.235 * twoFifths(kilowatts) - 1.02 * diameter;
+    return height > 0 ? height : 0;
+}
+/**
+ * Where soot starts forming, as an equivalence ratio.
+ *
+ * `§8.4`'s table: below stoichiometric there is enough oxygen to burn everything and the flame is
+ * clean; between 1.5 and 3 it is the classic luminous orange. One below the other is the onset.
+ */
+const SOOT_ONSET = 1.0;
+const SOOT_FULL = 3.0;
+/**
+ * How luminous the soot makes a flame, 0 to 1, from the equivalence ratio.
+ *
+ * Zero for a lean flame — there is no soot in one, which is why a gas ring is nearly invisible in
+ * daylight — climbing through the band where soot forms. Above `SOOT_FULL` the flame is too rich to
+ * burn at all and what leaves is smoke, which `§8.4` says and the field's own chemistry produces;
+ * this stays at one rather than pretending to model that.
+ */
+export function sootLuminosity(equivalenceRatio) {
+    if (!(equivalenceRatio > SOOT_ONSET))
+        return 0;
+    const share = (equivalenceRatio - SOOT_ONSET) / (SOOT_FULL - SOOT_ONSET);
+    return share > 1 ? 1 : share;
+}
+/**
+ * Linear RGB of the CH* and C₂* chemiluminescence a clean flame is seen by.
+ *
+ * 431 nm and 516 nm, which is genuinely blue-green, and it is what you are looking at when you look
+ * at a gas ring. A fixed colour rather than a curve because it is two emission *lines* rather than a
+ * continuum — that is the whole difference between it and the blackbody term.
+ */
+const CHEMILUMINESCENCE = [0.12, 0.45, 1.0];
+/**
+ * A flame's linear RGB: incandescent soot mixed with chemiluminescence by the equivalence ratio.
+ *
+ * `§8.4` again — the model computes φ and the soot mass, and this maps them. The result is that
+ * **nobody chose a flame colour**: a methanol flame is nearly invisible, a candle is orange, a
+ * bunsen burner with its collar open is blue, and all three come out of one ratio.
+ *
+ * Writes into `out`, allocates nothing.
+ */
+export function flameColour(equivalenceRatio, temperature, out) {
+    const soot = sootLuminosity(equivalenceRatio);
+    blackbodyRGB(temperature, out);
+    for (let c = 0; c < 3; c++) {
+        out[c] = out[c] * soot + CHEMILUMINESCENCE[c] * (1 - soot);
+    }
+}

package/dist/present/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `@driftengine/chemistry/present` — the numbers a renderer draws a fire from, and the installer.
+ *
+ * **Nothing here imports an engine package or names a core type.** Every target is described
+ * structurally by what it must have, which is the `ragdollFromBones` arrangement: core's
+ * `ParticleInstances` satisfies `SmokeTarget` exactly and neither package knows the other exists.
+ * That matters more here than it did there, because this package imports **no** engine package at
+ * all and `present/` is the module most tempted to break it.
+ *
+ * **Both backends, checked rather than assumed.** `ARCHITECTURE.md` §5 asks every visual feature to
+ * ship on WebGL2 and WebGPU or to refuse one in writing. Nothing in this directory is a shader, a
+ * pipeline or a bind group — it is arithmetic that writes into typed arrays a consumer already owns
+ * — so there is no backend-specific path to be missing. The one thing a consumer must know is not
+ * about backends at all and is written at `writeSurface`: **emissive in this engine is gated on
+ * `nightFactor`**, so embers written here look right at dusk and dead at noon.
+ */
+export { GLOW_MIN_TEMPERATURE, blackbodyRGB, glowIntensity } from './blackbody.ts';
+export { flameColour, flameHeight, sootLuminosity } from './flame.ts';
+export type { SmokeOptions, SmokeTarget } from './smoke.ts';
+export { emitSmoke, smokeColour } from './smoke.ts';
+export type { SurfaceTarget } from './surface.ts';
+export { writeSurface } from './surface.ts';
+export { crackleRate, hissRate, roarLevel } from './audio.ts';
+export type { ChemistryOptions, InstalledChemistry, MatchReport, ParcelBox } from './install.ts';
+export { installChemistry, parcelFromBounds } from './install.ts';

package/dist/present/index.js

@@ -0,0 +1,22 @@
+/**
+ * `@driftengine/chemistry/present` — the numbers a renderer draws a fire from, and the installer.
+ *
+ * **Nothing here imports an engine package or names a core type.** Every target is described
+ * structurally by what it must have, which is the `ragdollFromBones` arrangement: core's
+ * `ParticleInstances` satisfies `SmokeTarget` exactly and neither package knows the other exists.
+ * That matters more here than it did there, because this package imports **no** engine package at
+ * all and `present/` is the module most tempted to break it.
+ *
+ * **Both backends, checked rather than assumed.** `ARCHITECTURE.md` §5 asks every visual feature to
+ * ship on WebGL2 and WebGPU or to refuse one in writing. Nothing in this directory is a shader, a
+ * pipeline or a bind group — it is arithmetic that writes into typed arrays a consumer already owns
+ * — so there is no backend-specific path to be missing. The one thing a consumer must know is not
+ * about backends at all and is written at `writeSurface`: **emissive in this engine is gated on
+ * `nightFactor`**, so embers written here look right at dusk and dead at noon.
+ */
+export { GLOW_MIN_TEMPERATURE, blackbodyRGB, glowIntensity } from './blackbody.js';
+export { flameColour, flameHeight, sootLuminosity } from './flame.js';
+export { emitSmoke, smokeColour } from './smoke.js';
+export { writeSurface } from './surface.js';
+export { crackleRate, hissRate, roarLevel } from './audio.js';
+export { installChemistry, parcelFromBounds } from './install.js';

package/dist/present/install.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `installChemistry` — three lines, and a consumer's oak is oak.
+ *
+ * **`§16` is honest about what "free" means and this file is where it lands.** Free of *authoring*:
+ * a consumer never writes a reaction, never tunes an ignition temperature, never writes a state
+ * machine for fire. Not free of *importing*: core does not depend on chemistry and a game with no
+ * fire in it pays zero bytes, which is `ARCHITECTURE.md` §5's payload rule and this track does not
+ * get an exception to it.
+ *
+ * So the work goes into making the wiring free, and this is it.
+ */
+import { ReactionRegistry } from '../reaction/registry.ts';
+import { SpeciesRegistry } from '../species/registry.ts';
+import { SubstanceRegistry } from '../substance/registry.ts';
+import { ParcelStore } from '../parcel/store.ts';
+import { AtmosphereField } from '../field/atmosphere.ts';
+import { type AmbientState } from '../field/ambient.ts';
+import { ChemistryWorld } from '../transport/world.ts';
+import { type SubstanceLibrary } from '../library/library.ts';
+export interface ChemistryOptions {
+    /** The families this game uses. Everything else is optional. */
+    readonly libraries: readonly SubstanceLibrary[];
+    /** Metres per gas cell. One by default, which is a room-scale fire. */
+    readonly cellSize?: number;
+    readonly ambient?: AmbientState;
+    /** How many 8³ chunks of air may be live at once. */
+    readonly maxChunks?: number;
+}
+/** What a material name resolved to, and what did not resolve at all. */
+export interface MatchReport {
+    /** One index per name asked about, in order. `-1` where nothing matched. */
+    readonly substances: readonly number[];
+    readonly matched: number;
+    /** Every name that matched nothing, in the order given. */
+    readonly unmatched: readonly string[];
+}
+export interface InstalledChemistry {
+    readonly species: SpeciesRegistry;
+    readonly reactions: ReactionRegistry;
+    readonly substances: SubstanceRegistry;
+    readonly parcels: ParcelStore;
+    readonly air: AtmosphereField;
+    readonly world: ChemistryWorld;
+    /** The gas-phase steps the installed families brought, which the air is already running. */
+    readonly gasReactions: readonly string[];
+    /**
+     * Resolve material names to substances, **exactly**.
+     *
+     * **There is no synonym table and there will not be one.** `AGENTS.md` records the decision for
+     * retargeting — matching is exact and there is no name database, because a table of synonyms rots
+     * silently and its failure is a limb that does not move. The failure here is worse: a
+     * `pine_bark_02` quietly matching `pine` is a material with the wrong ignition temperature, and
+     * nobody will ever notice.
+     *
+     * So unmatched names come back in a list with a count, and the consumer decides.
+     */
+    match(names: readonly string[]): MatchReport;
+}
+/**
+ * A world with the given families in it, and everything wired to everything else.
+ *
+ * **Every option after `libraries` removes a capability when omitted rather than breaking.** No
+ * ambient: standard air. No cell size: one metre. That is `§16`'s arrangement, and the reason none
+ * of them is required is that a consumer who has not decided yet should still get a fire.
+ *
+ * **The gas-phase reactions come from the libraries rather than from the caller.** A family knows
+ * what its own volatiles are, and a consumer who forgot to pass `burn-tar` would have a fire that
+ * made smoke and no flame — which is a silent wrong answer rather than an error.
+ */
+export declare function installChemistry(options: ChemistryOptions): InstalledChemistry;
+/** Mass, volume, area and characteristic thickness, from a box. */
+export interface ParcelBox {
+    readonly mass: number;
+    readonly volume: number;
+    readonly area: number;
+    /** Volume over area, which is the depth conduction divides into shells. */
+    readonly thickness: number;
+}
+/**
+ * Sensible parcel numbers from a bounding box and a density.
+ *
+ * **`§16`'s third mechanism**: a consumer with meshes gets parcels without measuring anything, and a
+ * consumer who cares supplies real numbers instead. The area is all six faces, which is right for
+ * something in the open and generous for something lying on a hearth — and being generous is the
+ * safe direction, because it makes things heat slightly faster rather than mysteriously refusing to.
+ */
+export declare function parcelFromBounds(width: number, height: number, depth: number, density: number): ParcelBox;