@driftengine/script 3.61.0

package/dist/bindings/chemistry.js

@@ -0,0 +1,253 @@
+/**
+ * `drift/chemistry` — Track P's surface, and the thirteenth `drift/*` module.
+ *
+ * Like every binding here, nothing in it is new engine code: a binding is a **description and a
+ * lookup**. Where the surface needed a quantity `@driftengine/chemistry` did not have — a moisture
+ * content on a dry basis, a heat release rate, a char depth — that function was grown in the package
+ * that owns the subsystem and this describes it, per the rule in `host.ts`.
+ *
+ * ---
+ *
+ * ## Parcels are `i32`, and that is `drift/physics`'s convention followed rather than improved on
+ *
+ * A body is an `i32` there, a negative value means none, and a script author who has learned one
+ * surface has learned this one. A second convention for the same shape of thing is the kind of
+ * inconsistency nobody can defend a year later. `§20.2`.
+ *
+ * ## `chemistry.write` is inside the determinism boundary
+ *
+ * `capability.ts` wrote the rule that decides it and this track is the one entitled to apply it: a
+ * parcel's composition and enthalpy are simulated quantities in exactly the sense a component's
+ * fields are. They integrate on the fixed step and touch no clock. A rule that refused
+ * `chemistry.write` to a `@deterministic` function would refuse the canonical operation of the
+ * package.
+ *
+ * ## Two capabilities the design lists are **not** here, and neither is an oversight
+ *
+ * - **`wake`.** `§14`'s sleeping, budgets and LOD tiers were the design's CH-6 and were displaced
+ *   when the build re-scoped that phase onto the temperature reading the ignition criteria had to
+ *   read. Nothing sleeps, so a capability to wake it would be a no-op wearing a name — which is the
+ *   rule against silent no-ops, arriving through a binding. It goes in with `§14`.
+ * - **`setAmbient`.** The ambient is the far field every live chunk was filled from and every vented
+ *   kilogram was booked against. Changing it mid-run would leave the field holding air drawn from an
+ *   atmosphere that no longer exists and the conservation ledger measuring against a moved baseline —
+ *   which would make `elementTotals`, the single most valuable assertion in the track, meaningless.
+ *   A consumer who wants a different atmosphere constructs the field with one. **Reversal:**
+ *   re-baselining every live chunk and re-booking the ledger, which is a feature rather than a
+ *   setter.
+ */
+import { AtmosphereField, ChemistryWorld, ParcelStore, SpeciesRegistry, SubstanceRegistry, } from '@driftengine/chemistry';
+import { defineComponent } from '@driftengine/entities';
+import { defineCapability } from 'driftscript';
+export const CHEMISTRY_MODULE = 'drift/chemistry';
+const define = (name, params, returns, effects, doc) => defineCapability({
+    module: CHEMISTRY_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects,
+    /* Every capability in this module is deterministic — see the header. */
+    deterministic: true,
+    doc,
+    implementation: `${CHEMISTRY_MODULE}.${name}`,
+});
+/**
+ * The three opaque types `§20.2` names.
+ *
+ * `Chemistry` is the world as `PhysicsWorld` is one. A `Substance` and a `Species` are registrations,
+ * and a script holds them to pass back rather than to read into — a field on either would be a
+ * promise about a representation the engine could then never change.
+ */
+export const CHEMISTRY_TYPES = [
+    {
+        module: CHEMISTRY_MODULE,
+        name: 'Chemistry',
+        doc: 'A chemistry world: parcels, the air, and the tick that runs them.',
+    },
+    {
+        module: CHEMISTRY_MODULE,
+        name: 'Substance',
+        doc: 'A registered material: what it is made of and what it can turn into.',
+    },
+    {
+        module: CHEMISTRY_MODULE,
+        name: 'Species',
+        doc: 'A registered chemical species, such as `O2` or `cellulose`.',
+    },
+];
+const READ = ['chemistry.read'];
+const WRITE = ['chemistry.write'];
+const P = { name: 'chem', type: 'Chemistry' };
+const PARCEL = { name: 'parcel', type: 'i32' };
+const XYZ = [
+    { name: 'x', type: 'f32' },
+    { name: 'y', type: 'f32' },
+    { name: 'z', type: 'f32' },
+];
+export const CHEMISTRY_CAPABILITIES = [
+    /* Registration lookups: the two opaque handles enter a script here and nowhere else. */
+    define('substance', [P, { name: 'id', type: 'String' }], 'Substance', READ, 'A registered material by id, such as `oak`. Refuses in words naming what the world has.'),
+    define('species', [P, { name: 'id', type: 'String' }], 'Species', READ, 'A registered species by id, such as `O2`. Refuses in words if the world has no such species.'),
+    /* The read surface, §20.3. */
+    define('parcelCount', [P], 'i32', READ, 'How many parcel handles have ever been issued, live or not.'),
+    define('parcelAt', [P, { name: 'index', type: 'i32' }], 'i32', READ, 'The handle at an index, for iteration. Check `alive` before reading it.'),
+    define('alive', [P, PARCEL], 'bool', READ, 'Whether a parcel still exists.'),
+    define('substanceOf', [P, PARCEL], 'Substance', READ, 'What material a parcel is made of.'),
+    define('temperature', [P, PARCEL], 'f32', READ, 'K, averaged over the whole parcel.'),
+    define('surfaceTemperature', [P, PARCEL], 'f32', READ, 'K at the outermost shell — the one that decides whether it catches.'),
+    define('coreTemperature', [P, PARCEL], 'f32', READ, 'K at the innermost shell — the one that decides whether it is cooked.'),
+    define('mass', [P, PARCEL], 'f32', READ, 'How much of it there is, in kilograms. Falls as it burns.'),
+    define('speciesMass', [P, PARCEL, { name: 'species', type: 'Species' }], 'f32', READ, 'kg of one species held anywhere in this parcel.'),
+    define('moisture', [P, PARCEL], 'f32', READ, 'kg of water per kg of dry matter — the dry basis, which is how moisture content is quoted. Under 0.25 will burn; over 0.35 will not.'),
+    define('charFraction', [P, PARCEL], 'f32', READ, 'Share of the parcel that is now carbon, 0 to 1.'),
+    define('charDepth', [P, PARCEL], 'f32', READ, 'Metres of char measured inward from the surface.'),
+    define('wetness', [P, PARCEL], 'f32', READ, 'kg of liquid water on the surface, per square metre of it.'),
+    define('phase', [P, PARCEL], 'i32', READ, '0 solid, 1 liquid, 2 gas, 3 mixed. Mixed is a real answer: wet wood is a solid and a liquid at once.'),
+    define('burning', [P, PARCEL], 'bool', READ, 'Whether a flame stands over it.'),
+    define('smouldering', [P, PARCEL], 'bool', READ, 'Whether it is glowing with no flame. A smoulder survives air a flame cannot, which is why smothering leaves embers.'),
+    define('heatRelease', [P, PARCEL], 'f32', READ, "kW the reactions released last tick. A fire's size is its heat release rate, not its temperature. Negative while a surface is gasifying, which is correct."),
+    define('ignitionProgress', [P, PARCEL], 'f32', READ, 'How close to catching, 0 to 1: the least satisfied of the five criteria. A readout — nothing branches on it.'),
+    define('structuralIntegrity', [P, PARCEL], 'f32', READ, 'How much is still load-bearing, 1 down to 0, as char eats the thickness. This package breaks nothing; it reports.'),
+    define('massFlux', [P, PARCEL], 'f32', READ, 'kg/(m²·s) of gas leaving the surface — the smoke.'),
+    define('fuelFlux', [P, PARCEL], 'f32', READ, 'The combustible share of that, which is what ignition is measured against.'),
+    define('positionX', [P, PARCEL], 'f32', READ, 'Where the consumer said this parcel is.'),
+    define('positionY', [P, PARCEL], 'f32', READ, 'Where the consumer said this parcel is.'),
+    define('positionZ', [P, PARCEL], 'f32', READ, 'Where the consumer said this parcel is.'),
+    /* The air, sampled at a point. */
+    define('ambientTemperature', [P, ...XYZ], 'f32', READ, 'K of the air at a point.'),
+    define('oxygenFraction', [P, ...XYZ], 'f32', READ, 'Volume fraction of oxygen. Air is 0.209; a flame stops near 0.14 and a smoulder near 0.05.'),
+    define('humidity', [P, ...XYZ], 'f32', READ, 'Relative humidity, 0 to 1. Nothing dries in fog because the vapour pressure deficit is zero.'),
+    define('pressure', [P, ...XYZ], 'f32', READ, 'Pascals. Rises where the air is heated and confined, which is what an explosion event reports on.'),
+    define('concentration', [P, { name: 'species', type: 'Species' }, ...XYZ], 'f32', READ, 'Parts per million by volume. The reading a game acts on — carbon monoxide is the one that kills.'),
+    define('smokeDensity', [P, ...XYZ], 'f32', READ, 'Extinction coefficient, 1/m: what to attenuate a light along a ray by.'),
+    define('visibility', [P, ...XYZ], 'f32', READ, 'How far you can see, metres. Clamped at ten kilometres.'),
+    /* The write surface, §20.4. */
+    /*
+     * **`place`, not `spawn`, and `release`, not `emit`.** `§20.4` named both after words this
+     * language already reserves as statement heads — `spawn` starts a task and `emit` starts an event
+     * — so `chemistry.spawn(…)` does not parse at all. Renaming the capability is the narrow fix;
+     * making either a soft keyword would loosen the grammar everywhere for two names. The store's own
+     * method is still `spawn`, because TypeScript has no such collision.
+     */
+    define('place', [
+        P,
+        { name: 'substance', type: 'Substance' },
+        { name: 'kilograms', type: 'f32' },
+        { name: 'area', type: 'f32' },
+        ...XYZ,
+    ], 'i32', WRITE, 'Put a new parcel in the world. `area` is the exposed surface in m², and it is required rather than defaulted: a characteristic depth is volume over area, so a parcel with no area has no depth.'),
+    define('destroy', [P, PARCEL], 'void', WRITE, 'Remove a parcel. Its handle is never reused.'),
+    define('move', [P, PARCEL, ...XYZ], 'void', WRITE, 'Where it is. The consumer owns position; this package only reads it to work out what reaches it.'),
+    define('addHeat', [P, PARCEL, { name: 'joules', type: 'f32' }], 'void', WRITE, 'Joules into the surface shell, which is what a flux from outside does.'),
+    define('addHeatDeep', [P, PARCEL, { name: 'shell', type: 'i32' }, { name: 'joules', type: 'f32' }], 'void', WRITE, 'Joules into a named shell. The difference from `addHeat` is a microwave and an oven.'),
+    define('setTemperature', [P, PARCEL, { name: 'kelvin', type: 'f32' }], 'void', WRITE, 'Set every shell to a temperature. **For authoring and tests, not for a tick** — it discards whatever enthalpy was there rather than accounting for it.'),
+    define('wet', [P, PARCEL, { name: 'kilograms', type: 'f32' }], 'void', WRITE, 'Pour water on it: real liquid water into the surface shell, where boiling will find it. Refuses, naming the material, where that material holds no water.'),
+    define('dry', [P, PARCEL, { name: 'kilograms', type: 'f32' }], 'void', WRITE, 'Take surface water away: a cloth, a hot dry pan, or wind.'),
+    define('ignite', [P, PARCEL], 'void', WRITE, 'Supply a pilot for one tick. **This does not start a fire** — it satisfies one of five criteria, so holding a match to wet wood does nothing.'),
+    define('douse', [P, PARCEL], 'void', WRITE, 'Remove the pilot and the flame. Embers survive, which is the point of it.'),
+    define('addSpecies', [P, PARCEL, { name: 'species', type: 'Species' }, { name: 'kilograms', type: 'f32' }], 'void', WRITE, 'Salt the water, oil the pan, poison the well.'),
+    define('mix', [P, { name: 'from', type: 'i32' }, { name: 'into', type: 'i32' }], 'void', WRITE, 'Pour one parcel into another; the first is consumed. Both must be the same material — a mixture of two is a third material, authored as one.'),
+    define('release', [P, { name: 'species', type: 'Species' }, { name: 'kilograms', type: 'f32' }, ...XYZ], 'void', WRITE, 'A gas release into the air: a leak, a vent, an extinguisher.'),
+    define('addAirHeat', [P, { name: 'joules', type: 'f32' }, ...XYZ], 'void', WRITE, 'Joules into a cell of air, which is what a heater does and what a fire does to the room.'),
+    /* The event buffer, §20.5, in the shape `drift/physics`'s contact buffer established. */
+    define('eventCount', [P], 'i32', READ, 'Events this tick. Cleared at the top of every one.'),
+    define('eventKind', [P, { name: 'index', type: 'i32' }], 'i32', READ, '0 ignited, 1 extinguished, 2 smoulderStart, 3 smoulderEnd, 4 consumed, 5 charred, 6 structuralFail, 7 frozen, 8 melted, 9 boiled, 10 condensed, 11 sublimed, 12 corroded, 13 calcined, 14 dissolved, 15 denatured, 16 browned, 17 caramelised, 18 fermented, 19 decayed, 20 exploded.'),
+    define('eventParcel', [P, { name: 'index', type: 'i32' }], 'i32', READ, 'Which parcel it happened to.'),
+    define('eventSpecies', [P, { name: 'index', type: 'i32' }], 'i32', READ, 'Which species, or -1 where the kind does not name one.'),
+    define('eventValue', [P, { name: 'index', type: 'i32' }], 'f32', READ, "The kind's own quantity."),
+];
+/**
+ * A parcel handle on an entity, and `§19` says why it is declared here.
+ *
+ * Track M's design is explicit that `@driftengine/entities` declares **no components** — it is the
+ * model, not a library of them. And `@driftengine/chemistry` imports no engine package at all, so it
+ * cannot declare one either. This binding layer is the one place that already depends on core,
+ * entities and now chemistry at once, which makes it the only honest home.
+ *
+ * `standoff` is not a chemistry quantity and is here because it is the one a consumer always ends up
+ * adding: how far this was placed from the fire, which is what `1/r²` is measured over.
+ */
+export const CHEMISTRY_COMPONENT = defineComponent('Chemistry', {
+    parcel: 'i32',
+    standoff: 'f32',
+});
+export function chemistryImplementation(services) {
+    const { world, parcels, air, substances, species } = services;
+    /**
+     * Resolve an id, or refuse naming what the world has.
+     *
+     * **Not `-1` and not a no-op**, for the reason `drift/ecs` gives about a component name: a script
+     * that misspells `oak` would otherwise spawn nothing and read zeroes, which is a behaviour that
+     * runs, reports success and is wrong.
+     */
+    const substanceOf = (id) => {
+        const index = substances.indexOf(id);
+        if (index >= 0)
+            return index;
+        throw new Error(`no substance is registered as \`${id}\`. Install the library that carries it — ` +
+            '`@driftengine/chemistry/library/organic` has `oak`, `pine`, `paper`, `cotton`, `leather` ' +
+            'and `straw` — or define one.');
+    };
+    const speciesOf = (id) => {
+        const index = species.indexOf(id);
+        if (index >= 0)
+            return index;
+        throw new Error(`no species is registered as \`${id}\`. The standard table has sixty-eight.`);
+    };
+    return {
+        substance: (_, id) => substanceOf(id),
+        species: (_, id) => speciesOf(id),
+        parcelCount: () => parcels.count,
+        parcelAt: (_, index) => index,
+        alive: (_, parcel) => parcels.alive(parcel),
+        substanceOf: (_, parcel) => parcels.substanceOf(parcel),
+        temperature: (_, parcel) => parcels.temperatureOf(parcel),
+        surfaceTemperature: (_, parcel) => parcels.surfaceTemperatureOf(parcel),
+        coreTemperature: (_, parcel) => parcels.coreTemperatureOf(parcel),
+        mass: (_, parcel) => parcels.massOf(parcel),
+        speciesMass: (_, parcel, s) => parcels.parcelSpeciesMass(parcel, s),
+        moisture: (_, parcel) => parcels.moistureOf(parcel),
+        charFraction: (_, parcel) => parcels.charFractionOf(parcel),
+        charDepth: (_, parcel) => parcels.charDepthOf(parcel),
+        wetness: (_, parcel) => parcels.wetnessOf(parcel),
+        phase: (_, parcel) => parcels.parcelPhaseOf(parcel),
+        burning: (_, parcel) => parcels.burning(parcel),
+        smouldering: (_, parcel) => parcels.smouldering(parcel),
+        /* Watts inside, kilowatts out: a fire is quoted in kW everywhere a person reads one. */
+        heatRelease: (_, parcel) => parcels.heatReleaseOf(parcel) / 1000,
+        ignitionProgress: (_, parcel) => world.ignitionProgressOf(parcel),
+        structuralIntegrity: (_, parcel) => parcels.structuralIntegrityOf(parcel),
+        massFlux: (_, parcel) => parcels.massFluxOf(parcel),
+        fuelFlux: (_, parcel) => parcels.fuelFluxOf(parcel),
+        positionX: (_, parcel) => parcels.positionX(parcel),
+        positionY: (_, parcel) => parcels.positionY(parcel),
+        positionZ: (_, parcel) => parcels.positionZ(parcel),
+        ambientTemperature: (_, x, y, z) => air.temperatureAt(x, y, z),
+        oxygenFraction: (_, x, y, z) => air.oxygenFractionAt(x, y, z),
+        humidity: (_, x, y, z) => air.humidityAt(x, y, z),
+        pressure: (_, x, y, z) => air.pressureAt(x, y, z),
+        concentration: (_, s, x, y, z) => air.concentrationAt(x, y, z, s),
+        smokeDensity: (_, x, y, z) => air.smokeDensityAt(x, y, z),
+        visibility: (_, x, y, z) => air.visibilityAt(x, y, z),
+        place: (_, substance, kilograms, area, x, y, z) => parcels.spawn({ substance, mass: kilograms, temperature: 293.15, area, x, y, z }),
+        destroy: (_, parcel) => parcels.destroy(parcel),
+        move: (_, parcel, x, y, z) => parcels.move(parcel, x, y, z),
+        addHeat: (_, parcel, joules) => parcels.addSurfaceHeat(parcel, joules),
+        addHeatDeep: (_, parcel, shell, joules) => parcels.addShellHeat(parcel, shell, joules),
+        setTemperature: (_, parcel, kelvin) => parcels.setTemperature(parcel, kelvin),
+        wet: (_, parcel, kilograms) => parcels.wet(parcel, kilograms),
+        dry: (_, parcel, kilograms) => parcels.dry(parcel, kilograms),
+        ignite: (_, parcel) => parcels.ignite(parcel),
+        douse: (_, parcel) => parcels.douse(parcel),
+        addSpecies: (_, parcel, s, kilograms) => parcels.addSpeciesMass(parcel, 0, s, kilograms),
+        mix: (_, from, into) => parcels.mix(from, into),
+        release: (_, s, kilograms, x, y, z) => air.addSpecies(x, y, z, s, kilograms),
+        addAirHeat: (_, joules, x, y, z) => air.addHeat(x, y, z, joules),
+        eventCount: () => world.events.count,
+        eventKind: (_, index) => world.events.kindOf(index),
+        eventParcel: (_, index) => world.events.parcelOf(index),
+        eventSpecies: (_, index) => world.events.speciesOf(index),
+        eventValue: (_, index) => world.events.valueOf(index),
+    };
+}

package/dist/bindings/core.d.ts

@@ -0,0 +1,172 @@
+/**
+ * The wired `drift/*` surfaces other than audio, in one file because each is a table.
+ *
+ * A binding is a **description plus a lookup**. Nothing here is new engine code, and if a binding
+ * needed the engine to grow a function, that function would belong in the package owning the
+ * subsystem and this would then describe it like any other.
+ *
+ * **What is deliberately absent, and why**, because an empty module is a decision rather than an
+ * oversight:
+ *
+ * - **`drift/core`.** §11 gives its provider as `startLoop` and `LoopHooks`. A script does not call
+ *   those — they are what *drives* a script. There is nothing for a script to call, so the module
+ *   is not registered rather than registered empty, and a target does not claim it.
+ * - **`drift/xr`.** No provider: Track I is the one track nobody has taken, and the linker refuses
+ *   the module by name. **Twelve names stood in this list beside it and every one of them has since
+ *   been bound** — `render`, `ui`, `2d`, `terrain`, `ecs`, `prefab`, `navigation`, `behavior`,
+ *   `network`, `rollback`, `editor` and `ai` — and this sentence went on calling them unprovided,
+ *   because a comment listing what is missing has no guard on it and goes stale in the one
+ *   direction nothing checks.
+ */
+import { ActionMap, type KeyValueStore, MessageQueue, type QueuedMessage } from '@driftengine/core';
+import { type CapabilityDefinition, type OpaqueType } from 'driftscript';
+export declare const TIME_MODULE = "drift/time";
+export declare const RANDOM_MODULE = "drift/random";
+export declare const EVENTS_MODULE = "drift/events";
+export declare const PERSISTENCE_MODULE = "drift/persistence";
+export declare const SCENE_MODULE = "drift/scene";
+export declare const PHYSICS_MODULE = "drift/physics";
+export declare const INPUT_MODULE = "drift/input";
+export declare const CAMERA_MODULE = "drift/camera";
+/**
+ * Handles a script holds and passes back, never reads into.
+ *
+ * A field on any of these would be a promise about a representation the engine could then never
+ * change — the design's safe-handle rule. `Node` is the one a script touches most, and it is still
+ * opaque: a position is read through a capability rather than off the object.
+ */
+export declare const CORE_TYPES: readonly OpaqueType[];
+/**
+ * `drift/time` — the loop's three clocks, and the one that is deterministic is not here.
+ *
+ * All three carry `clock.read`, so **none may be called from a `@deterministic` function** — and
+ * that is right even for the fixed step. A simulation is *given* its delta as a parameter; a
+ * simulation that reached out and read one has stopped being a function of its inputs, which is
+ * what replay depends on.
+ */
+export declare const TIME_CAPABILITIES: readonly CapabilityDefinition[];
+/**
+ * `drift/random` — a seeded generator whose sequence is **frozen**.
+ *
+ * Deterministic by construction, so a `@deterministic` function may call it. That is the whole
+ * reason it is a capability rather than a `std/*` function: the sequence is a promise about *this
+ * engine's* stored replays, and a standard library that shipped its own would either break that
+ * promise or silently become the thing that defines it.
+ */
+export declare const RANDOM_CAPABILITIES: readonly CapabilityDefinition[];
+/** `drift/events` — the engine's priority queue, with dedupe over a window and a backlog ceiling. */
+export declare const EVENTS_CAPABILITIES: readonly CapabilityDefinition[];
+/** `drift/persistence` — the store the consumer supplied, which may be a browser, a server or nothing. */
+export declare const PERSISTENCE_CAPABILITIES: readonly CapabilityDefinition[];
+/**
+ * `drift/scene` — the transform hierarchy from Phase 1.1.
+ *
+ * Reads are deterministic and writes are not, which is the boundary drawn per capability rather
+ * than per module. A simulation may ask where something is; moving it is a change to the world.
+ */
+export declare const SCENE_CAPABILITIES: readonly CapabilityDefinition[];
+/**
+ * `drift/physics` — bodies, contacts, queries and forces. **Not joints, not the controller and not
+ * ragdolls**, which is what this line said until 2026-08-27 and what none of the thirty-six
+ * capabilities below has ever done.
+ *
+ * **This module was two read-only functions until 2026-08-26**, and its own comment said why: there
+ * was no solver to write into, and a capability that pretended otherwise would have been the mock
+ * the design refused. Track B built the solver, so the surface is real — but the sentence that
+ * announced it was written from the *track's* deliverables rather than from this list, which is the
+ * same failure as a binding written from memory of what a camera ought to have. A reader looking
+ * for `joint` here found a comment that promised one.
+ *
+ * **Six of the thirty-six are `nearestWithin` and its accessors, added 2026-08-28**, and they exist
+ * because a consumer reported that `anyWithin` answers *whether* and never *what*. A script could
+ * already find the nearest entity — `drift/ecs` grew `findNearest` and `nearest` for that — and
+ * could not find the nearest wall, so what is in reach of a character was decided in TypeScript.
+ *
+ * **The two `within` questions measure different volumes, and the names cannot say so on their
+ * own.** `anyWithin` tests the axis-aligned *box* around the sphere, because that is what the
+ * collider hash indexes and testing anything narrower would cost a pass it does not need for a
+ * yes-or-no. `nearestWithin` is already walking each candidate to rank it, so it measures the
+ * sphere exactly and answers false where `anyWithin` answers true — a collider that reaches only
+ * the box corners. Both say which they do, on themselves, because a reader comparing the two names
+ * would have no reason to suspect it.
+ *
+ * **It measures to a collider's bounds rather than to the shape inside them**, which is the one
+ * place this surface is coarser than the sweep beside it. `ColliderSet`'s own header draws that
+ * line: the bounds are the broad phase and the shape resolves a contact, so a proximity answer that
+ * ran the convex sweep per candidate per frame would be paying contact prices for a distance. The
+ * documentation on each accessor says bounds, so nobody reads a banked slab's box as its surface.
+ *
+ * **What is missing, and the design question that is why it is still missing**: `JointDesc` carries
+ * twenty optional fields, so a script-side constructor is either an enormous signature or a builder
+ * this language has no shape for. That is a decision somebody has to take deliberately, and taking
+ * it badly would put a wrong-by-construction surface in front of every script author. Recorded here
+ * rather than guessed at.
+ *
+ * **Two parameters are required here that TypeScript leaves optional**, which is step four of the
+ * note at the top of `host.ts`, and both are the same shape of trap — an omission that produces a
+ * *wrong result* rather than an error:
+ *
+ * - **A raycast's layer mask.** Omitted, the first thing a ray finds is very often the body it
+ *   started inside, because `raycastWorld` reports that body at fraction zero deliberately. A
+ *   TypeScript caller has the context to know when that matters; a script author meets it first and
+ *   reads it as the engine seeing through walls.
+ * - **An impulse's application point.** Omitted, the impulse goes through the centre of mass and
+ *   produces no rotation whatever. Nothing throws; a crate simply slides instead of tumbling, which
+ *   reads as a broken impulse rather than as a missing argument.
+ *
+ * **Every body and event index is `i32`, not `u32`.** `hitBody` has to be able to answer −1, and a
+ * script has no cast, so a mixed surface would make the obvious code — raycast, check the body,
+ * apply an impulse to it — impossible to write. One signed type throughout costs nothing and is
+ * what a query result already is.
+ *
+ * **A raycast's result is read back through separate accessors**, in the same shape `input.axisX`
+ * and `input.axisY` already use for a vector. A script has no way to receive an engine record, and
+ * inventing a flattened signature would drift from the real one the first time a hit gains a field —
+ * which is the reasoning `drift/camera` gives for leaving `cut` out. *What it costs* is that a hit
+ * is only valid until the next `raycast` on the same world, and the documentation says so on every
+ * accessor.
+ */
+export declare const PHYSICS_CAPABILITIES: readonly CapabilityDefinition[];
+/** `drift/input` — Track H, complete: action maps, rebinding, gamepad, pointer and touch. */
+export declare const INPUT_CAPABILITIES: readonly CapabilityDefinition[];
+/**
+ * `drift/camera` — the cinematic cameras, and **only what they actually have**.
+ *
+ * The first version of this binding described `lookAt` and `setPosition`. `CinematicCamera` has
+ * neither: it has `cut`, `snap`, `shotAgeSec` and `update`. The implementation reached them through
+ * an optional-call cast, so a script calling `camera.lookAt(…)` compiled, linked, ran, and did
+ * **nothing** — the silent no-op this repository's rules forbid, arriving by way of a binding
+ * written from memory of what a camera ought to have rather than from the class.
+ *
+ * `cut` is deliberately still absent: it takes a `ShotParams`, and a script has no way to construct
+ * an engine record yet. Binding it would mean inventing a flattened signature that drifts from the
+ * real one the first time a shot gains a field. It waits for a way to express the record.
+ */
+export declare const CAMERA_CAPABILITIES: readonly CapabilityDefinition[];
+/** What a host must supply for each module it wants to provide. */
+export interface CoreServices {
+    readonly clocks?: {
+        fixedDelta(): number;
+        frameDelta(): number;
+        wallDelta(): number;
+        elapsed(): number;
+    };
+    readonly store?: KeyValueStore;
+    readonly queue?: MessageQueue<QueuedMessage>;
+    readonly actions?: ActionMap;
+}
+export declare function timeImplementation(clocks: NonNullable<CoreServices['clocks']>): Record<string, unknown>;
+/**
+ * The seeded generator, dispatching to core's frozen sequence.
+ *
+ * `index` returns 0 for an empty collection rather than an error, because "pick from nothing" has
+ * one sane answer and a script asking is usually mid-way through a list that will have items next
+ * frame.
+ */
+export declare function randomImplementation(): Record<string, unknown>;
+export declare function eventsImplementation(): Record<string, unknown>;
+export declare function persistenceImplementation(): Record<string, unknown>;
+export declare function sceneImplementation(): Record<string, unknown>;
+export declare function physicsImplementation(): Record<string, unknown>;
+export declare function inputImplementation(): Record<string, unknown>;
+export declare function cameraImplementation(): Record<string, unknown>;