@driftengine/script 3.61.0

package/dist/bindings/animation.js

@@ -0,0 +1,177 @@
+/**
+ * `drift/animation` — Track A, complete, and the one binding with a trap to disarm.
+ *
+ * **`BlendTree` allocates its own scratch poses, and without a bind pose they start at zero
+ * translation.** `sampleClip` leaves a channel no track mentions exactly as it found it, so a
+ * rotation-only clip — which is most of them — preserves whatever translations the pose already
+ * held. `blendPoses` cannot do that: it interpolates *every* channel of two poses. So a tree or a
+ * state machine built without a bind pose collapses every joint onto its parent's origin, and the
+ * symptom is a figure folded in on itself rather than an error.
+ *
+ * The TypeScript constructor makes `bind` optional, and that is right there: its caller is holding
+ * the skeleton and knows what a rest pose is. **A script never meets that argument**, because a
+ * script does not build a tree — it drives one its host built and handed it, which is what
+ * `blendSet` and `blendAt` are for and what the block above them explains. `reach` is this file's
+ * worked example of the rule that used to live here: its pole hint is required at the boundary
+ * because a chain that is already straight has no plane to bend in, and a script author meets that
+ * trap first.
+ *
+ * **`blendPoses` does not take one and must not be given one**, which the paraphrase this binding
+ * was first written from got wrong. It writes into a caller-owned `out`, so the caller already
+ * controls what the untouched channels start as; adding a bind-pose parameter here would be
+ * inventing an argument the engine does not have. The rule belongs to the thing that allocates.
+ */
+import { Skeleton, blendPoses, createPose, createRootMotion, extractRootMotion, restPose, sampleClip, solveTwoBone, stripRootMotion, } from '@driftengine/animation';
+import { defineCapability } from 'driftscript';
+export const ANIMATION_MODULE = 'drift/animation';
+export const ANIMATION_TYPES = [
+    {
+        module: ANIMATION_MODULE,
+        name: 'Skeleton',
+        doc: 'A joint hierarchy, parents before children.',
+    },
+    { module: ANIMATION_MODULE, name: 'Pose', doc: 'One set of joint transforms.' },
+    { module: ANIMATION_MODULE, name: 'Clip', doc: 'Keyframed tracks over time.' },
+    { module: ANIMATION_MODULE, name: 'Blend', doc: 'A blend tree over clips.' },
+    { module: ANIMATION_MODULE, name: 'Motion', doc: "A root's displacement over an interval." },
+];
+const define = (name, params, returns, effects, deterministic, doc) => defineCapability({
+    module: ANIMATION_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects,
+    deterministic,
+    doc,
+    implementation: `${ANIMATION_MODULE}.${name}`,
+});
+export const ANIMATION_CAPABILITIES = [
+    define('pose', [{ name: 'jointCount', type: 'u32' }], 'Pose', ['pure'], true, 'A new pose at rest. This is where a bind pose comes from; take one and keep it.'),
+    define('toRest', [
+        { name: 'pose', type: 'Pose' },
+        { name: 'jointCount', type: 'u32' },
+    ], 'void', ['animation.write'], false, 'Return a pose to rest without allocating another, which is what a state machine does on re-entry.'),
+    define('sample', [
+        { name: 'clip', type: 'Clip' },
+        { name: 'at', type: 'f32' },
+        { name: 'into', type: 'Pose' },
+    ], 'void', ['animation.write'], false, 'Sample a clip at a time. A channel no track mentions is left as it was, so a rotation-only clip preserves the rest of the pose.'),
+    define('blend', [
+        { name: 'a', type: 'Pose' },
+        { name: 'b', type: 'Pose' },
+        { name: 'amount', type: 'f32' },
+        { name: 'into', type: 'Pose' },
+    ], 'void', ['animation.write'], false, 'Blend two poses into a third, clamped at the ends. Safe when `into` is also `a` or `b`. It interpolates every channel, so `into` decides what an untouched joint blends from.'),
+    /*
+     * **A script drives a tree; it does not build one. And `blendTree` used to say otherwise.**
+     *
+     * That capability took a `Skeleton` and handed it to `new BlendTree(skeleton as never, …)`,
+     * whose first parameter is the *root node* of the graph. Run, it threw `Cannot read properties
+     * of undefined (reading 'length')` — measured 2026-08-28, not reasoned about — because `prepare`
+     * asked a skeleton for its children. Nothing caught it: `host.test.ts` asserted that the
+     * *compiler* required three arguments, which it did, and no test ever called the implementation.
+     * A capability nobody could use, with a message naming nothing a script author could act on.
+     *
+     * **Why building one is a design and not an oversight.** A tree is a graph of nodes, and a
+     * script has no node value: it would need a `clip` node, a `lerp`, a set with a list of stops
+     * and a weight per stop, and then a name for the whole shape. That is a surface to design, and
+     * `docs/IMPROVEMENTS.md` carries it with what it needs.
+     *
+     * **What works today is the shape DriftScript 1.8.1 opened.** A host builds the tree in
+     * TypeScript, where the skeleton and the clips already are, and hands it to a system through
+     * `uses`; the script then sets its parameters and evaluates it. So these two are the whole
+     * script-side surface of a blend tree, and they are enough for the case the language was given
+     * `uses` for.
+     */
+    define('blendSet', [
+        { name: 'tree', type: 'Blend' },
+        { name: 'parameter', type: 'String' },
+        { name: 'value', type: 'f32' },
+    ], 'void', ['animation.write'], false, "Set one of a tree's parameters. A name no node in that tree declares is refused by name, because a typo that silently did nothing would present as an animation that will not respond. Both kinds of parameter are set this way: a blend weight, and a clock — the time a `clip` node named for its own sampling."),
+    define('blendAt', [
+        { name: 'tree', type: 'Blend' },
+        { name: 'at', type: 'f32' },
+        { name: 'into', type: 'Pose' },
+    ], 'void', ['animation.write'], false, 'Evaluate a whole tree into a pose. `at` is the clock for every node that did not name one of its own, so a tree of ordinary clips is sampled at one time and a node with a clock reads that parameter instead.'),
+    define('reach', [
+        { name: 'skeleton', type: 'Skeleton' },
+        { name: 'pose', type: 'Pose' },
+        { name: 'root', type: 'u32' },
+        { name: 'mid', type: 'u32' },
+        { name: 'tip', type: 'u32' },
+        { name: 'targetX', type: 'f32' },
+        { name: 'targetY', type: 'f32' },
+        { name: 'targetZ', type: 'f32' },
+        /*
+         * The pole hint decides the one thing a target cannot: which way the joint bends. Required
+         * for the same reason as the bind pose — a chain that is already straight has no plane to
+         * bend in, and without a hint the elbow flips unpredictably as a character turns. The engine
+         * requires it too; it is listed here so a reader of the signature knows what it is for.
+         */
+        { name: 'poleX', type: 'f32' },
+        { name: 'poleY', type: 'f32' },
+        { name: 'poleZ', type: 'f32' },
+    ], 'bool', ['animation.write'], false, 'Bend a two-bone chain so its tip reaches a target. Answers whether it was reachable; an unreachable target straightens the chain toward it rather than giving up.'),
+    /*
+     * **Root motion is two calls and it is a mistake to make only one of them.** `rootMotion` hands
+     * the caller the displacement and `stripRoot` takes it out of the pose; a script that extracts
+     * without stripping moves its character twice, at exactly double speed, with nothing failing.
+     * Both descriptions say so, because a script author has no signature to read.
+     *
+     * The displacement is read back through separate accessors, the shape `hitX` and `input.axisX`
+     * already use — a script has no way to receive an engine record. Here the accessors take the
+     * `Motion` rather than reading a scratch the last call wrote, so two characters extracted in one
+     * frame do not clobber each other; the raycast surface keys its scratch on the world for the
+     * same reason, and animation has no equivalent handle to key on.
+     */
+    define('motion', [], 'Motion', ['pure'], true, 'A new root displacement, at zero. Take one and keep it; nothing here allocates per frame.'),
+    define('rootMotion', [
+        { name: 'clip', type: 'Clip' },
+        { name: 'joint', type: 'u32' },
+        { name: 'from', type: 'f32' },
+        { name: 'to', type: 'f32' },
+        { name: 'into', type: 'Motion' },
+    ], 'void', ['animation.write'], false, 'How far the root travelled between two times, in its own frame at `from`. Loops are accumulated, so a clip that wraps between the two times still answers a step forward. Pair every call with `stripRoot` or the character moves twice.'),
+    define('stripRoot', [
+        { name: 'clip', type: 'Clip' },
+        { name: 'joint', type: 'u32' },
+        { name: 'pose', type: 'Pose' },
+    ], 'void', ['animation.write'], false, "Pin a sampled pose's root to the clip's value at time zero, so the displacement `rootMotion` handed you is not also in the pose. Every other joint is left as it was."),
+    define('motionX', [{ name: 'motion', type: 'Motion' }], 'f32', ['pure'], true, "The displacement along the root's own x axis at the earlier time."),
+    define('motionY', [{ name: 'motion', type: 'Motion' }], 'f32', ['pure'], true, "The displacement along the root's own y axis at the earlier time."),
+    define('motionZ', [{ name: 'motion', type: 'Motion' }], 'f32', ['pure'], true, "The displacement along the root's own z axis at the earlier time."),
+    define('motionTurnX', [{ name: 'motion', type: 'Motion' }], 'f32', ['pure'], true, 'The x part of the rotation the root turned through, as a quaternion.'),
+    define('motionTurnY', [{ name: 'motion', type: 'Motion' }], 'f32', ['pure'], true, 'The y part of the rotation the root turned through, as a quaternion.'),
+    define('motionTurnZ', [{ name: 'motion', type: 'Motion' }], 'f32', ['pure'], true, 'The z part of the rotation the root turned through, as a quaternion.'),
+    define('motionTurnW', [{ name: 'motion', type: 'Motion' }], 'f32', ['pure'], true, 'The w part of the rotation the root turned through, as a quaternion. One means it did not turn.'),
+];
+/**
+ * The implementations.
+ *
+ * `blendTree` passes the bind pose straight through to the engine's optional parameter — the
+ * requirement lives entirely in the *description*, which is exactly where a capability boundary
+ * should hold a rule. The engine's own callers keep their option; script authors get the safe
+ * behaviour without the engine changing.
+ */
+export function animationImplementation() {
+    return {
+        pose: (jointCount) => createPose(jointCount),
+        toRest: (pose, jointCount) => restPose(jointCount, pose),
+        sample: (clip, at, into) => sampleClip(clip, at, into),
+        blend: (a, b, amount, into) => blendPoses(a, b, amount, into),
+        blendSet: (tree, parameter, value) => tree.set(parameter, value),
+        blendAt: (tree, at, into) => tree.evaluate(at, into),
+        motion: () => createRootMotion(),
+        rootMotion: (clip, joint, from, to, into) => extractRootMotion(clip, joint, from, to, into),
+        stripRoot: (clip, joint, pose) => stripRootMotion(clip, joint, pose),
+        motionX: (motion) => motion.translation[0],
+        motionY: (motion) => motion.translation[1],
+        motionZ: (motion) => motion.translation[2],
+        motionTurnX: (motion) => motion.rotation[0],
+        motionTurnY: (motion) => motion.rotation[1],
+        motionTurnZ: (motion) => motion.rotation[2],
+        motionTurnW: (motion) => motion.rotation[3],
+        reach: (skeleton, pose, root, mid, tip, targetX, targetY, targetZ, poleX, poleY, poleZ) => solveTwoBone(skeleton, pose, root, mid, tip, [targetX, targetY, targetZ], [poleX, poleY, poleZ]),
+    };
+}

package/dist/bindings/audio.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `drift/audio` — what this engine lets a script do to sound.
+ *
+ * **Five capabilities: a slot, two ways to play it, and the two cheap positional helpers.** This
+ * header read "playback, placement, the mix, and the rhythm the music is doing" until 2026-08-27,
+ * and three of those four were never here — there is no mix verb, no rhythm verb, no HRTF-panned
+ * source, no listener and no reverb zone. The sentence was written from *Track G's* deliverables
+ * rather than from the list beneath it, which is the same failure `drift/physics` had one file
+ * over, and the same one the first `drift/camera` binding had: a comment describing what a
+ * subsystem ought to expose rather than what this array does.
+ *
+ * It is still the right first binding and still the thing that shows what a binding *is* — registry
+ * entries describing capabilities the engine already has, plus a map of implementations the host
+ * supplies at link time. **No new engine code.**
+ *
+ * **What is missing, and why it is not guessed at here.** `MixConsole`, `AudioListenerGraph`,
+ * `SpatialSource` and `ReverbZone` are four stateful objects with lifetimes, and a script-side
+ * surface for them is a design about handles and ownership rather than a table entry — who disposes
+ * a source, what happens to its probe slot, whether a zone outlives the script that made it.
+ * `docs/CAPABILITIES.md` §4 records it. Taking that badly would put a leak in front of every script
+ * author, which is worse than a surface they can see is absent.
+ *
+ * Three constraints this surface inherits, none of them negotiable:
+ *
+ * - **`audio.write` is outside the determinism boundary.** `ARCHITECTURE.md` places audio there, so
+ *   a `@deterministic` function may not call any of it. A simulation decides *that* a door opened
+ *   and emits an event; something outside the fixed step decides what it sounds like. The compiler
+ *   is only making a line that already exists visible.
+ * - **`audio.play` in a `@hot` function is a diagnostic**, for the reason the engine's own rules
+ *   forbid allocation there.
+ * - **A sound slot may be absent, so `sound` returns an option.** The registry probes several
+ *   format candidates per slot and the file often is not there. A script that ignores that plays
+ *   silence and reports success, which is the failure the language's no-implicit-null rule exists
+ *   to prevent — and this is the first place in the engine where that rule earns its keep.
+ */
+import { AudioGraph, SoundRegistry } from '@driftengine/audio';
+import { type CapabilityDefinition, type OpaqueType } from 'driftscript';
+export declare const AUDIO_MODULE = "drift/audio";
+/**
+ * A decoded sound, held by a script and passed back to the engine.
+ *
+ * Opaque on purpose: it is an `AudioBuffer`, and a script that could read its fields would be a
+ * script depending on a representation the engine cannot then change. The design calls these safe
+ * handles, and this is one.
+ */
+export declare const AUDIO_TYPES: readonly OpaqueType[];
+export declare const AUDIO_CAPABILITIES: readonly CapabilityDefinition[];
+/**
+ * The implementations, which the host hands to a module's `__bind`.
+ *
+ * A plain object rather than anything the registry holds — R2: the registry describes and never
+ * becomes the call path, so this is a separate thing that happens to have matching keys. The
+ * registry's `implementation` strings name these; nothing enforces that mechanically, which is why
+ * a test asserts every definition has an implementation here.
+ */
+export declare function audioImplementation(graph: AudioGraph, registry: SoundRegistry): Record<string, unknown>;

package/dist/bindings/audio.js

@@ -0,0 +1,126 @@
+/**
+ * `drift/audio` — what this engine lets a script do to sound.
+ *
+ * **Five capabilities: a slot, two ways to play it, and the two cheap positional helpers.** This
+ * header read "playback, placement, the mix, and the rhythm the music is doing" until 2026-08-27,
+ * and three of those four were never here — there is no mix verb, no rhythm verb, no HRTF-panned
+ * source, no listener and no reverb zone. The sentence was written from *Track G's* deliverables
+ * rather than from the list beneath it, which is the same failure `drift/physics` had one file
+ * over, and the same one the first `drift/camera` binding had: a comment describing what a
+ * subsystem ought to expose rather than what this array does.
+ *
+ * It is still the right first binding and still the thing that shows what a binding *is* — registry
+ * entries describing capabilities the engine already has, plus a map of implementations the host
+ * supplies at link time. **No new engine code.**
+ *
+ * **What is missing, and why it is not guessed at here.** `MixConsole`, `AudioListenerGraph`,
+ * `SpatialSource` and `ReverbZone` are four stateful objects with lifetimes, and a script-side
+ * surface for them is a design about handles and ownership rather than a table entry — who disposes
+ * a source, what happens to its probe slot, whether a zone outlives the script that made it.
+ * `docs/CAPABILITIES.md` §4 records it. Taking that badly would put a leak in front of every script
+ * author, which is worse than a surface they can see is absent.
+ *
+ * Three constraints this surface inherits, none of them negotiable:
+ *
+ * - **`audio.write` is outside the determinism boundary.** `ARCHITECTURE.md` places audio there, so
+ *   a `@deterministic` function may not call any of it. A simulation decides *that* a door opened
+ *   and emits an event; something outside the fixed step decides what it sounds like. The compiler
+ *   is only making a line that already exists visible.
+ * - **`audio.play` in a `@hot` function is a diagnostic**, for the reason the engine's own rules
+ *   forbid allocation there.
+ * - **A sound slot may be absent, so `sound` returns an option.** The registry probes several
+ *   format candidates per slot and the file often is not there. A script that ignores that plays
+ *   silence and reports success, which is the failure the language's no-implicit-null rule exists
+ *   to prevent — and this is the first place in the engine where that rule earns its keep.
+ */
+import { AudioGraph, SoundRegistry, distanceGain, stereoPan } from '@driftengine/audio';
+import { defineCapability } from 'driftscript';
+export const AUDIO_MODULE = 'drift/audio';
+/**
+ * A decoded sound, held by a script and passed back to the engine.
+ *
+ * Opaque on purpose: it is an `AudioBuffer`, and a script that could read its fields would be a
+ * script depending on a representation the engine cannot then change. The design calls these safe
+ * handles, and this is one.
+ */
+export const AUDIO_TYPES = [
+    {
+        module: AUDIO_MODULE,
+        name: 'Sound',
+        doc: 'A decoded sound, resolved from a slot. Held and passed back; never read into.',
+    },
+];
+const define = (name, params, returns, effects, deterministic, doc, implementation) => defineCapability({
+    module: AUDIO_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects,
+    deterministic,
+    doc,
+    implementation,
+});
+export const AUDIO_CAPABILITIES = [
+    define('sound', [{ name: 'slot', type: 'String' }], 
+    /*
+     * `Sound?`, and the `?` is the whole point.
+     *
+     * The registry resolves a slot by probing format candidates, and a missing file is ordinary
+     * rather than exceptional. Returning a bare `Sound` would make every script that forgot to
+     * check play silence and report success.
+     */
+    'Sound?', ['pure'], true, 'Resolve a sound slot. Absent when nothing was registered or nothing decoded.', 'SoundRegistry.get'),
+    define('play', [
+        { name: 'sound', type: 'Sound' },
+        { name: 'gain', type: 'f32' },
+    ], 'void', ['audio.write'], false, 'Play a resolved sound through the mix.', 'AudioGraph.play'),
+    define('playPanned', [
+        { name: 'sound', type: 'Sound' },
+        { name: 'gain', type: 'f32' },
+        { name: 'pan', type: 'f32' },
+    ], 'void', ['audio.write'], false, 'Play a resolved sound at a stereo position, -1 left to 1 right.', 'AudioGraph.play'),
+    define('distanceGain', [
+        { name: 'distance', type: 'f32' },
+        { name: 'radius', type: 'f32' },
+    ], 'f32', 
+    /*
+     * `pure`, and therefore callable from a `@deterministic` function.
+     *
+     * It is arithmetic over two numbers — the cheap positional function, not the HRTF path. That a
+     * capability in an otherwise effectful module is deterministic is the reason effects are
+     * declared per capability rather than per module.
+     */
+    ['pure'], true, 'How loud something is at a distance, falling off to nothing at the radius.', 'audio.distanceGain'),
+    define('stereoPan', [
+        { name: 'dx', type: 'f32' },
+        { name: 'dz', type: 'f32' },
+        { name: 'yaw', type: 'f32' },
+    ], 'f32', ['pure'], true, 'Where something sits in the stereo field, relative to a listener facing yaw.', 'audio.stereoPan'),
+];
+const some = (value) => ({ tag: 'some', value });
+const none = { tag: 'none' };
+/**
+ * The implementations, which the host hands to a module's `__bind`.
+ *
+ * A plain object rather than anything the registry holds — R2: the registry describes and never
+ * becomes the call path, so this is a separate thing that happens to have matching keys. The
+ * registry's `implementation` strings name these; nothing enforces that mechanically, which is why
+ * a test asserts every definition has an implementation here.
+ */
+export function audioImplementation(graph, registry) {
+    return {
+        sound(slot) {
+            const buffer = registry.get(slot);
+            return buffer === undefined ? none : some(buffer);
+        },
+        play(sound, gain) {
+            graph.play(sound, gain);
+        },
+        playPanned(sound, gain, pan) {
+            graph.play(sound, gain, pan);
+        },
+        distanceGain,
+        stereoPan,
+    };
+}

package/dist/bindings/behavior.d.ts

@@ -0,0 +1,36 @@
+import { BehaviorRunner } from '@driftengine/core';
+import { type CapabilityDefinition, type OpaqueType } from 'driftscript';
+export declare const BEHAVIOR_MODULE = "drift/behavior";
+/**
+ * `drift/behavior` — driving and watching a behaviour tree from a script.
+ *
+ * **A script drives a tree; it does not author one.** A tree is nested data with a name on every
+ * node, and the useful thing to have in a script is not a builder for it but the two verbs a
+ * hand-written routine cannot offer: advance it, and ask what it is doing. Authoring stays in
+ * TypeScript beside the actions the tree calls, which is where the consumer's own verbs already
+ * are.
+ *
+ * **`doing` is the capability worth pointing at.** It answers whether the agent is currently inside
+ * a node of a given name, which is what turns a tree from something that runs into something a
+ * script can react to — play a sound while an agent is sheltering, show an icon while it is walking
+ * home, refuse to talk to it mid-errand — without the tree and the script keeping a second copy of
+ * the same state in step.
+ *
+ * The same effect seam as `drift/navigation` and for the same reason: `behavior.read` is in the
+ * language's deterministic set and `behavior.write` is not, so a `@deterministic` system may watch
+ * a tree and not tick one. See `bindings/navigation.ts`, where the argument and its reversal
+ * condition are written out.
+ */
+export declare const BEHAVIOR_TYPES: readonly OpaqueType[];
+export declare const BEHAVIOR_CAPABILITIES: readonly CapabilityDefinition[];
+/** What a consumer hands the host so scripts can drive their agents' routines. */
+export interface BehaviorServices {
+    /**
+     * What a character's tick is handed: a world, an entity, whatever the tree's own actions read.
+     *
+     * A function of the character rather than one context for all of them, because a routine is per
+     * agent and the thing its actions act on almost always is too.
+     */
+    context(character: BehaviorRunner<unknown>): unknown;
+}
+export declare function behaviorImplementation(services: BehaviorServices): Record<string, unknown>;

package/dist/bindings/behavior.js

@@ -0,0 +1,101 @@
+import { BehaviorRunner } from '@driftengine/core';
+import { defineCapability } from 'driftscript';
+export const BEHAVIOR_MODULE = 'drift/behavior';
+/**
+ * `drift/behavior` — driving and watching a behaviour tree from a script.
+ *
+ * **A script drives a tree; it does not author one.** A tree is nested data with a name on every
+ * node, and the useful thing to have in a script is not a builder for it but the two verbs a
+ * hand-written routine cannot offer: advance it, and ask what it is doing. Authoring stays in
+ * TypeScript beside the actions the tree calls, which is where the consumer's own verbs already
+ * are.
+ *
+ * **`doing` is the capability worth pointing at.** It answers whether the agent is currently inside
+ * a node of a given name, which is what turns a tree from something that runs into something a
+ * script can react to — play a sound while an agent is sheltering, show an icon while it is walking
+ * home, refuse to talk to it mid-errand — without the tree and the script keeping a second copy of
+ * the same state in step.
+ *
+ * The same effect seam as `drift/navigation` and for the same reason: `behavior.read` is in the
+ * language's deterministic set and `behavior.write` is not, so a `@deterministic` system may watch
+ * a tree and not tick one. See `bindings/navigation.ts`, where the argument and its reversal
+ * condition are written out.
+ */
+export const BEHAVIOR_TYPES = [
+    {
+        module: BEHAVIOR_MODULE,
+        name: 'Behavior',
+        doc: 'One agent running one behaviour tree: where it is in its routine.',
+    },
+];
+const define = (name, params, returns, effects, doc, deterministic = true) => defineCapability({
+    module: BEHAVIOR_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects: effects,
+    deterministic,
+    doc,
+    implementation: `${BEHAVIOR_MODULE}.${name}`,
+});
+export const BEHAVIOR_CAPABILITIES = [
+    define('tick', [{ name: 'behavior', type: 'Behavior' }], 'i32', ['behavior.write'], 'Advance the routine one tick. Answers 0 failed, 1 finished, 2 still going. Does nothing while paused.', false),
+    define('step', [{ name: 'behavior', type: 'Behavior' }], 'i32', ['behavior.write'], 'Advance one tick even while paused, which is what a step button is.', false),
+    define('restart', [{ name: 'behavior', type: 'Behavior' }], 'void', ['behavior.write'], 'Forget where the routine had got to, so the next tick starts it from the top.', false),
+    define('setPaused', [
+        { name: 'behavior', type: 'Behavior' },
+        { name: 'paused', type: 'bool' },
+    ], 'void', ['behavior.write'], 'Hold this one agent while the world carries on.', false),
+    define('paused', [{ name: 'behavior', type: 'Behavior' }], 'bool', ['behavior.read'], 'Whether it is being held.'),
+    define('status', [{ name: 'behavior', type: 'Behavior' }], 'i32', ['behavior.read'], 'What the last tick answered, without ticking again.'),
+    /*
+     * **The reason a tree beats a loop, from a script's side.** A hand-written routine keeps its
+     * state where nothing else can see it, so a script that wants to react to what an agent is doing
+     * keeps a second copy and the two drift. This reads the tree's own answer.
+     */
+    define('doing', [
+        { name: 'behavior', type: 'Behavior' },
+        { name: 'node', type: 'String' },
+    ], 'bool', ['behavior.read'], "Whether the agent is currently inside a node of this name — the routine's own answer, not a copy of it."),
+    define('depth', [{ name: 'behavior', type: 'Behavior' }], 'i32', ['behavior.read'], 'How deep in the tree the last tick reached. For a debug readout.'),
+];
+export function behaviorImplementation(services) {
+    /* Reused across every `doing` call: the path is at most the tree's depth and this is read every
+       tick by anything watching an agent. */
+    let scratch = new Uint32Array(32);
+    return {
+        tick: (character) => character.tick(services.context(character)),
+        step: (character) => character.stepOnce(services.context(character)),
+        restart: (character) => character.reset(),
+        setPaused: (character, paused) => {
+            character.paused = paused;
+        },
+        paused: (character) => character.paused,
+        status: (character) => character.status,
+        depth(character) {
+            scratch = fit(scratch, character);
+            return character.activePath(scratch);
+        },
+        doing(character, node) {
+            scratch = fit(scratch, character);
+            const depth = character.activePath(scratch);
+            for (let i = 0; i < depth; i++) {
+                if (character.nameOf(scratch[i] ?? 0) === node)
+                    return true;
+            }
+            return false;
+        },
+    };
+}
+/**
+ * Grow the scratch to hold this tree's deepest possible path.
+ *
+ * A path cannot be longer than the tree has nodes, so this settles after the first call per tree
+ * and never runs again — which is what keeps a per-tick read allocation-free in the steady state
+ * without asking a consumer to declare a depth they would have to keep correct.
+ */
+function fit(scratch, character) {
+    const needed = character.tree.nodeCount;
+    return scratch.length >= needed ? scratch : new Uint32Array(needed);
+}

package/dist/bindings/chemistry.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `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 { type ComponentType } from '@driftengine/entities';
+import { type CapabilityDefinition, type OpaqueType } from 'driftscript';
+export declare const CHEMISTRY_MODULE = "drift/chemistry";
+/**
+ * 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 declare const CHEMISTRY_TYPES: readonly OpaqueType[];
+export declare const CHEMISTRY_CAPABILITIES: readonly CapabilityDefinition[];
+/**
+ * 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 declare const CHEMISTRY_COMPONENT: ComponentType;
+/** What a consumer supplies to make `drift/chemistry` reachable. */
+export interface ChemistryServices {
+    readonly world: ChemistryWorld;
+    readonly parcels: ParcelStore;
+    readonly air: AtmosphereField;
+    readonly substances: SubstanceRegistry;
+    readonly species: SpeciesRegistry;
+}
+export declare function chemistryImplementation(services: ChemistryServices): Record<string, unknown>;