@driftengine/script 3.61.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Drift Technologies
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+DriftEngine
+Copyright 2026 Drift Technologies
+
+This product includes software developed at Drift Technologies
+(https://github.com/drftrun/driftengine).
+
+Licensed under the Apache License, Version 2.0. Section 4(d) of that licence
+requires this NOTICE to be reproduced in any derivative work you distribute,
+in the source, the documentation, or a display generated by the work.

package/README.md

@@ -0,0 +1,81 @@
+# @driftengine/script
+
+The `drift/*` capability bindings: what this engine provides to DriftScript, and **the only place the
+two are coupled**.
+
+**Cost: 36.7 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it
+drifts more than 3% — the number is derived from the same floors that gate asserts, so a README
+quoting a stale one is a red suite rather than a thing somebody notices.
+
+## What it is
+
+[`driftscript`](https://www.npmjs.com/package/driftscript) is a language and knows nothing about this engine: no
+scene, no mesh, no mix bus. This package is the other half — it describes each engine subsystem as
+capabilities a script may call, and supplies the implementations at link time.
+
+Twelve modules are bound: `drift/animation`, `audio`, `camera`, `ecs`, `events`, `input`,
+`persistence`, `physics`, `prefab`, `random`, `scene` and `time`. **`drift/core` is deliberately
+unbound**, because its provider is `startLoop`, which drives a script rather than being called by
+one.
+
+**Four of `drift/ecs`'s capabilities are ones nobody writes by hand.** `query`, `next`, `view` and
+`without` are what a `for … in query<…>()` loop compiles to, so their documentation describes the
+shape of generated code rather than how to call them. They are capabilities rather than a second
+bind hook, so generated code reaches them exactly as it reaches everything else.
+
+`registerEntityModule` turns a compiled module's declarations into the engine's own objects — a
+`ComponentType` per component, a `Prefab` per prefab, a `SystemDefinition` per system — and
+`assertHostShapes` checks every `component X from host` against what this host registered.
+
+## Reaching this package from a bundler config — you cannot, and do not need to
+
+**`import { engineRegistry } from '@driftengine/script'` fails inside a `vite.config.ts`**, with
+`ERR_MODULE_NOT_FOUND` on a path like `@driftengine/audio/src/registry`. A bundler config is loaded
+by Node; engine packages use extensionless relative imports that only a bundler resolves. That is
+this engine's module layout and not a bug in the config.
+
+Pass the **data** instead. This package ships it:
+
+```ts
+import { fileURLToPath } from 'node:url';
+import { driftScript } from 'driftscript/vite';
+
+driftScript({
+  capabilities: fileURLToPath(import.meta.resolve('@driftengine/script/capabilities.json')),
+  manifest: { name: 'my-game', provides: ['drift/ecs', 'drift/audio'] },
+});
+```
+
+`capabilities.json` is regenerated by `npm run capabilities` and gated by `npm run
+capabilities:check`, so it cannot drift from the bindings above it. The DriftScript language server
+reads the same file for the same reason — see the next section for why a registry can cross a
+process boundary at all.
+
+## The registry describes and never invokes
+
+A definition names its implementation as a **string**. The host supplies the functions when a module
+links. That is what keeps the language package host-neutral, and it is also what lets the language
+server read `capabilities.json` in a process that cannot import this engine at all.
+
+## Adding a binding
+
+The five steps are at the top of [`src/host.ts`](src/host.ts), beside the code that does them. Two of
+them are the ones that get missed:
+
+**A capability that lands unbound is one DriftScript cannot reach, and nothing fails to say so.** The
+linker refuses an unbound module by naming the track it waits on — so a script author hits a refusal
+that reads exactly like a track that has not shipped, and concludes it has not. The capability
+exists, is finished, is tested, and is unreachable.
+
+**Check whether an optional parameter must become required at the language boundary.** A TypeScript
+signature may make one optional because its caller has the context to know when to pass it. A script
+author is further from the subsystem, meets the trap first, and gets a wrong _result_ rather than an
+error. `src/bindings/animation.ts` is the worked example.
+
+**Write a binding from the source, never from a description of it.** Two were written from a
+paraphrase and both were wrong — one named two methods the class does not have, reached through an
+optional-call cast, so a script calling it compiled, linked, ran and did nothing. `src/host.test.ts`
+now refuses `?.(` and `as unknown as` anywhere under `bindings/`.
+
+Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)
+for how the packages divide, and why some features are compiled into core on demand instead.

package/dist/bindings/ai.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `drift/ai` — what this engine lets a script ask of an agent.
+ *
+ * **Deliberately small, and deliberately not a way to call a model.** A script wakes an
+ * agent, asks it to consider, and reads what it is doing. It never awaits a provider,
+ * because a script that could would be a script that can stall a fixed step for five
+ * seconds — and the whole of Track O is the argument that nothing should.
+ *
+ * Three constraints this surface inherits:
+ *
+ * - **`ai` is outside the determinism boundary.** A `@deterministic` function may not
+ *   call any of it. The floor is deterministic and runs inside the simulation; asking a
+ *   provider is not, and the compiler is making a line that already exists visible.
+ * - **Nothing here returns a model's answer.** `wake` and `consider` are requests that
+ *   an agent think, and they return immediately. What the agent decided arrives as the
+ *   intent its session hands the consumer on a later tick.
+ * - **Reading is cheap and stays inside the boundary.** `intentId` and `degraded` are
+ *   `@deterministic`-safe: the current intent is state the simulation already owns,
+ *   because a deterministic floor put it there and a replay recomputes it.
+ */
+import { type CapabilityDefinition, type OpaqueType } from 'driftscript';
+import type { AgentSession, NavigateArgs, NavigateResult, ToolDefinition } from '@driftengine/ai';
+import type { NavPath } from '@driftengine/core';
+export declare const AI_MODULE = "drift/ai";
+/**
+ * A live agent session, held by a script and passed back to the engine.
+ *
+ * Opaque, for the reason `Sound` is: a script that could read its fields would be a
+ * script depending on a representation this package cannot then change.
+ */
+export declare const AI_TYPES: readonly OpaqueType[];
+export declare const AI_CAPABILITIES: readonly CapabilityDefinition[];
+/**
+ * A consumer's agents, by the id a script may name them with.
+ *
+ * The registry is the consumer's, exactly as `SoundRegistry` is: this package owns the
+ * loop and the floor, and which agents exist in a scene is not something an engine can
+ * know.
+ */
+export interface AgentRegistry {
+    get(id: string): AgentSession | undefined;
+}
+/**
+ * What the navigation bridge needs from the host to answer for an agent.
+ *
+ * The world and the tools are the consumer's: `navigationBridge` is a factory over their adapter,
+ * and this is where the result of that factory meets a script.
+ */
+export interface AgentNavigation<W = unknown> {
+    readonly world: W;
+    readonly tools: readonly ToolDefinition<NavigateArgs, NavigateResult, W>[];
+    pathOf(agentId: string): NavPath | undefined;
+}
+/** Which agents this peer decides for. One method, because that is the whole script-visible fact. */
+export interface AgentAuthority {
+    deciding(agentId: string): boolean;
+}
+export interface AiServices<W = unknown> {
+    readonly agents: AgentRegistry;
+    /** Absent means `reachable`, `navigate` and `path` fail at the call saying what to provide. */
+    readonly navigation?: AgentNavigation<W>;
+    /** Absent means `deciding` fails at the call. */
+    readonly authority?: AgentAuthority;
+}
+/** The implementations the host supplies at link time, keyed by capability name. */
+export declare function aiImplementation(services: AiServices): Readonly<Record<string, unknown>>;

package/dist/bindings/ai.js

@@ -0,0 +1,173 @@
+/**
+ * `drift/ai` — what this engine lets a script ask of an agent.
+ *
+ * **Deliberately small, and deliberately not a way to call a model.** A script wakes an
+ * agent, asks it to consider, and reads what it is doing. It never awaits a provider,
+ * because a script that could would be a script that can stall a fixed step for five
+ * seconds — and the whole of Track O is the argument that nothing should.
+ *
+ * Three constraints this surface inherits:
+ *
+ * - **`ai` is outside the determinism boundary.** A `@deterministic` function may not
+ *   call any of it. The floor is deterministic and runs inside the simulation; asking a
+ *   provider is not, and the compiler is making a line that already exists visible.
+ * - **Nothing here returns a model's answer.** `wake` and `consider` are requests that
+ *   an agent think, and they return immediately. What the agent decided arrives as the
+ *   intent its session hands the consumer on a later tick.
+ * - **Reading is cheap and stays inside the boundary.** `intentId` and `degraded` are
+ *   `@deterministic`-safe: the current intent is state the simulation already owns,
+ *   because a deterministic floor put it there and a replay recomputes it.
+ */
+import { defineCapability } from 'driftscript';
+export const AI_MODULE = 'drift/ai';
+/**
+ * A live agent session, held by a script and passed back to the engine.
+ *
+ * Opaque, for the reason `Sound` is: a script that could read its fields would be a
+ * script depending on a representation this package cannot then change.
+ */
+export const AI_TYPES = [
+    {
+        module: AI_MODULE,
+        name: 'Agent',
+        doc: 'A live agent session. Held and passed back; never read into.',
+    },
+];
+const define = (name, params, returns, effects, deterministic, doc, implementation) => defineCapability({
+    module: AI_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects,
+    deterministic,
+    doc,
+    implementation,
+});
+export const AI_CAPABILITIES = [
+    define('agent', [{ name: 'id', type: 'String' }], 
+    /*
+     * `Agent?`, and the `?` is the point, exactly as it is for `audio.sound`.
+     *
+     * A consumer registers the agents a script may talk to, and a script naming one
+     * that was not registered is ordinary rather than exceptional — a scene loaded
+     * without its agents, a name that moved. Returning a bare `Agent` would make every
+     * script that forgot to check talk to nothing and report success.
+     */
+    'Agent?', ['pure'], true, 'Resolve an agent by the id the consumer registered it under. Absent when there is none.', 'AgentRegistry.get'),
+    define('wake', [
+        { name: 'agent', type: 'Agent' },
+        { name: 'reason', type: 'String' },
+        { name: 'priority', type: 'i32' },
+    ], 'void', ['ai'], false, 'Tell an agent something happened. Returns immediately; the agent acts at its next tick.', 'AgentSession.observe'),
+    define('consider', [{ name: 'agent', type: 'Agent' }], 'void', ['ai'], false, 'Ask an agent to think, at ordinary priority. Returns immediately.', 'AgentSession.consider'),
+    define('intentId', [{ name: 'agent', type: 'Agent' }], 'String', ['pure'], 
+    /*
+     * Readable from a `@deterministic` function, unlike everything else here.
+     *
+     * The current intent is state the simulation already owns — the floor put it there
+     * and a replay recomputes it — so reading it is reading the simulation rather than
+     * reaching outside it. Asking a provider is the part that is nondeterministic, and
+     * that is what `wake` and `consider` carry `ai` for.
+     */
+    true, 'What the agent is doing now. Empty before its first tick.', 'AgentSession.intentId'),
+    define('degraded', [{ name: 'agent', type: 'Agent' }], 'bool', ['pure'], true, 'Whether the agent is over budget and running on its policy floor alone.', 'AgentSession.degraded'),
+    /*
+     * The two bridges, and every effect below is inherited rather than invented.
+     *
+     * **None of these duplicates `drift/navigation`.** That module binds twelve capabilities and
+     * every one takes a `NavPath` or a `NavGraph`; what a script could not do is aim any of them at
+     * an `Agent`, which is a session keyed by an id the consumer registered. `path` is the join, so
+     * one capability makes all twelve work on an agent instead of any being bound a second time.
+     */
+    define('reachable', [
+        { name: 'agent', type: 'Agent' },
+        { name: 'x', type: 'float' },
+        { name: 'y', type: 'float' },
+        { name: 'z', type: 'float' },
+    ], 'bool', ['navigation.read'], 
+    /*
+     * Deterministic, and it is the admission guard as a question. `navigation.route` computes *and
+     * writes*, so a script wanting to score a destination before committing to it had to route and
+     * then undo — which is a write a `@deterministic` system would have had to make and take back.
+     */
+    true, 'Whether a route exists from where this agent is to a point, without writing one.', 'navigationBridge.admits'),
+    define('navigate', [
+        { name: 'agent', type: 'Agent' },
+        { name: 'x', type: 'float' },
+        { name: 'y', type: 'float' },
+        { name: 'z', type: 'float' },
+    ], 'bool', ['navigation.write'], 
+    /*
+     * **Deterministic, and safe on every peer, which only looks like it contradicts `deciding`.**
+     * The authority rule is about *model*-authored intents: a provider is nondeterministic, slow
+     * and metered, so two peers running one diverge. A script's own command is a function of the
+     * simulation — DriftScript 1.12.0 admitted `navigation.write` to `DETERMINISTIC_EFFECTS` on
+     * exactly that argument, since a route is a function of the graph and two endpoints and
+     * `navSearch` breaks ties on the node index — so every peer computes the same route and it
+     * replicates itself by being re-run.
+     */
+    true, 'Route this agent to a point. False when no route exists, and then it clears the old one.', 'navigationBridge.execute'),
+    define('path', [{ name: 'agent', type: 'Agent' }], 
+    /*
+     * `NavPath?`, from `drift/navigation`. Cross-module opaque types are ordinary here:
+     * `drift/editor.rebuildTree` takes a `drift/scene.Node` and `drift/ui.draw` takes a
+     * `drift/2d.SpriteBatch`.
+     *
+     * Optional because an agent the consumer never gave a route object to is ordinary rather than
+     * exceptional, and a bare `NavPath` would hand every script that forgot to check a handle to
+     * nothing.
+     */
+    'NavPath?', ['navigation.read'], true, 'The route object this agent follows, for `drift/navigation` to read or steer along.', 'AgentNavigation.pathOf'),
+    define('deciding', [{ name: 'agent', type: 'Agent' }], 'bool', 
+    /*
+     * `network.read`, and inside `DETERMINISTIC_EFFECTS`, on the same narrowing
+     * `drift/network.authority` already uses: which participant this is, and whether it is the
+     * authority, are facts that cannot vary with packet timing. This is that fact per agent.
+     */
+    ['network.read'], true, 'Whether this peer decides this agent’s model intents. Elsewhere they arrive already taken.', 'AuthoritativeAgent.deciding'),
+];
+/**
+ * Missing wiring fails at the call, naming what is absent.
+ *
+ * **Not a falsy default**, for the reason `HostServices` already gives about `drift/behavior`: a
+ * stub makes an agent whose routine never runs look exactly like one standing about with nothing to
+ * do. `navigate` returning `false` because nobody wired a bridge is indistinguishable from `false`
+ * because there is no route, and the second is a thing a script is meant to handle.
+ */
+function required(value, what) {
+    if (value === undefined) {
+        throw new Error(`drift/ai: this host provides no ${what}, so that capability cannot answer. Pass it in ` +
+            `\`services.ai\` — see \`navigationBridge\` in @driftengine/ai.`);
+    }
+    return value;
+}
+/** The implementations the host supplies at link time, keyed by capability name. */
+export function aiImplementation(services) {
+    const { agents } = services;
+    const navigate = (agent, x, y, z, act) => {
+        const nav = required(services.navigation, 'navigation bridge');
+        const tool = nav.tools.find((candidate) => candidate.id === 'navigate@1');
+        if (tool === undefined)
+            return false;
+        const args = { agentId: agent.agentId, x, y, z };
+        /* `admits` is the guard and `execute` is the act, and `reachable` is deliberately the first
+           without the second — the whole point of exposing it is not having to route and undo. */
+        return act ? tool.execute(args, nav.world).found : tool.admits(args, nav.world);
+    };
+    return {
+        agent: (id) => agents.get(id),
+        wake: (agent, reason, priority) => {
+            agent.observe({ id: reason, priority, text: reason });
+        },
+        consider: (agent) => {
+            agent.observe({ id: 'consider', priority: 0, text: 'consider' });
+        },
+        intentId: (agent) => agent.current?.id ?? '',
+        degraded: (agent) => agent.degraded,
+        reachable: (agent, x, y, z) => navigate(agent, x, y, z, false),
+        navigate: (agent, x, y, z) => navigate(agent, x, y, z, true),
+        path: (agent) => required(services.navigation, 'navigation bridge').pathOf(agent.agentId),
+        deciding: (agent) => required(services.authority, 'authority bridge').deciding(agent.agentId),
+    };
+}

package/dist/bindings/animation.d.ts

@@ -0,0 +1,13 @@
+import { type CapabilityDefinition, type OpaqueType } from 'driftscript';
+export declare const ANIMATION_MODULE = "drift/animation";
+export declare const ANIMATION_TYPES: readonly OpaqueType[];
+export declare const ANIMATION_CAPABILITIES: readonly CapabilityDefinition[];
+/**
+ * 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 declare function animationImplementation(): Record<string, unknown>;