@driftengine/script 3.61.0

package/dist/bindings/entities.js

@@ -0,0 +1,339 @@
+/**
+ * `drift/ecs` and `drift/prefab` — the entity model as DriftScript reaches it.
+ *
+ * These are the two surfaces the linker has refused by name since Track N shipped, and this file is
+ * what kills that refusal. Like every binding here, nothing in it is new engine code: a binding is a
+ * description and a lookup.
+ *
+ * ---
+ *
+ * ## A component is named by a string, and that is forced rather than chosen
+ *
+ * A script cannot hold a `ComponentType` — it is an object with a schema, and the language's types
+ * are numbers, strings, booleans and opaque handles. So a component is addressed by name and the
+ * host resolves it. **The cost is that a typo is a runtime refusal rather than a compile error**,
+ * and the fix is DS-5's `component` declaration, which is Track N's to build now that this exists.
+ * Refusing in words naming the component and listing what the world has is what the interim owes.
+ *
+ * ## There is no query here, and that is not an omission
+ *
+ * Iterating a query needs a loop form the language does not have for it — that is DS-5 and DS-6.
+ * What a script can do today is walk a component's dense array by index, which `while` expresses
+ * perfectly. **The order is insertion modified by swap-removal**, so an entity removed during a
+ * walk moves the last one into a position already passed; a script that removes while walking
+ * should walk backwards, and the doc on `at` says so.
+ */
+import { ENTITY_INDEX_CEILING, instantiate, } from '@driftengine/entities';
+import { defineCapability } from 'driftscript';
+export const ECS_MODULE = 'drift/ecs';
+export const PREFAB_MODULE = 'drift/prefab';
+const define = (module, name, params, returns, effects, deterministic, doc) => defineCapability({
+    module,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects,
+    deterministic,
+    doc,
+    implementation: `${module}.${name}`,
+});
+export const ENTITY_TYPES = [
+    {
+        module: ECS_MODULE,
+        name: 'World',
+        doc: 'A world: its entities, their components and its systems.',
+    },
+    {
+        module: ECS_MODULE,
+        name: 'Cursor',
+        doc: "A query in progress. Borrowed from the world's pool and given back when the walk ends, so it may not outlive the loop that opened it.",
+    },
+    {
+        module: ECS_MODULE,
+        name: 'View',
+        doc: "A component's live columns. The object stays valid across a reallocation; the arrays inside it do not, so index through the view rather than holding one.",
+    },
+];
+/**
+ * An entity is `Entity`, and it took the language until DriftScript 1.6.0 to have the word.
+ *
+ * A handle carries a 26-bit index and a 27-bit generation, which is the entire 53-bit budget a
+ * double holds. A `u32` would truncate the generation — and a truncated generation is a stale
+ * handle that compares equal to a live one, which is the exact failure the generation exists to
+ * prevent. So the width was never negotiable, and until the language could name it these all said
+ * `f64` with this paragraph explaining why.
+ *
+ * **`Entity` is a type of its own there rather than an alias**, which is what makes the change worth
+ * making: a handle is assignable *to* an `f64` and not *from* one, so a number a script computed
+ * cannot arrive where a handle is wanted, and `e.Health` is legal on a handle and on nothing else.
+ * The language's own note asked for this by name — a capability that hands back a handle as an
+ * `f64` and expects it to keep working as one is what it said would make the asymmetry wrong.
+ *
+ * **`read` still answers `f64`**, and that is not an oversight: it reads a component *field*, which
+ * is a number, and typing it as a handle would be the same mistake in the other direction.
+ */
+export const ECS_CAPABILITIES = [
+    define(ECS_MODULE, 'create', [{ name: 'world', type: 'World' }], 'Entity', ['ecs.write'], false, 'A fresh entity with nothing on it. The handle is exact; do not put one in an `f32`.'),
+    define(ECS_MODULE, 'destroy', [
+        { name: 'world', type: 'World' },
+        { name: 'entity', type: 'Entity' },
+    ], 'bool', ['ecs.write'], false, 'Remove an entity and every component it had. False when the handle was already stale.'),
+    define(ECS_MODULE, 'alive', [
+        { name: 'world', type: 'World' },
+        { name: 'entity', type: 'Entity' },
+    ], 'bool', ['ecs.read'], true, 'Whether this handle still names a live entity. A handle to something destroyed is false, even after its slot is reused.'),
+    define(ECS_MODULE, 'has', [
+        { name: 'world', type: 'World' },
+        { name: 'entity', type: 'Entity' },
+        { name: 'component', type: 'String' },
+    ], 'bool', ['ecs.read'], true, 'Whether an entity carries a component.'),
+    define(ECS_MODULE, 'attach', [
+        { name: 'world', type: 'World' },
+        { name: 'entity', type: 'Entity' },
+        { name: 'component', type: 'String' },
+    ], 'void', ['ecs.write'], false, 'Give an entity a component, every field at the zero for its type. Set them with `write`.'),
+    define(ECS_MODULE, 'detach', [
+        { name: 'world', type: 'World' },
+        { name: 'entity', type: 'Entity' },
+        { name: 'component', type: 'String' },
+    ], 'bool', ['ecs.write'], false, 'Take a component away. False when it did not have one.'),
+    define(ECS_MODULE, 'read', [
+        { name: 'world', type: 'World' },
+        { name: 'entity', type: 'Entity' },
+        { name: 'component', type: 'String' },
+        { name: 'field', type: 'String' },
+    ], 'f64', ['ecs.read'], true, 'One numeric field. Reading a field of a component an entity does not have is 0.'),
+    define(ECS_MODULE, 'write', [
+        { name: 'world', type: 'World' },
+        { name: 'entity', type: 'Entity' },
+        { name: 'component', type: 'String' },
+        { name: 'field', type: 'String' },
+        { name: 'value', type: 'f64' },
+    ], 'void', ['ecs.write'], false, 'Set one numeric field.'),
+    define(ECS_MODULE, 'count', [
+        { name: 'world', type: 'World' },
+        { name: 'component', type: 'String' },
+    ], 'u32', ['ecs.read'], true, 'How many entities carry a component.'),
+    define(ECS_MODULE, 'at', [
+        { name: 'world', type: 'World' },
+        { name: 'component', type: 'String' },
+        { name: 'index', type: 'u32' },
+    ], 'Entity', ['ecs.read'], true, 'The nth entity carrying a component. **The order is insertion modified by swap-removal**, so a walk that removes should count downwards — removing moves the last entity into a position already passed.'),
+    /*
+     * **Two capabilities rather than one, and the split is what `Entity` cost.**
+     *
+     * A search that finds nothing has to say so, and once the answer is an `Entity` there is no value
+     * left to say it with: a handle is not a number a script can compare to −1, which is the whole
+     * point of it being its own type. An option would say it and allocates one object per call, on a
+     * path written to run every frame for every agent that looks around — the allocation `next`
+     * refuses one screen up.
+     *
+     * So the result is read back through a second accessor, which is exactly what `raycast` and its
+     * `hitBody` already do in this repository and for the same reason. **The cost is the same too**:
+     * the result is only valid until the next search on the same world, and that is said here and on
+     * the accessor rather than left for somebody to find out.
+     */
+    define(ECS_MODULE, 'findNearest', [
+        { name: 'world', type: 'World' },
+        { name: 'component', type: 'String' },
+        { name: 'fieldX', type: 'String' },
+        { name: 'fieldY', type: 'String' },
+        { name: 'fieldZ', type: 'String' },
+        { name: 'x', type: 'float' },
+        { name: 'y', type: 'float' },
+        { name: 'z', type: 'float' },
+        { name: 'radius', type: 'float' },
+    ], 'bool', ['ecs.read'], true, "Whether any entity carrying a component has position fields putting it within a radius, and the search `nearest` then reads. **A linear scan of that component's column, not an index** — the entity model keeps no spatial structure, so this costs one pass over everything carrying the component. Position is read from three fields you name, so nothing here knows what a transform is called."),
+    define(ECS_MODULE, 'nearest', [{ name: 'world', type: 'World' }], 'Entity', ['ecs.read'], true, 'The entity the last `findNearest` on this world found. **Valid only until the next one**, and meaningless when that answered false — the same lifetime a raycast hit has.'),
+];
+/**
+ * The four a query loop is built on.
+ *
+ * **Nobody writes these by hand.** They are what `for e in query<…>() { … }` compiles to, and a
+ * script author never names one — which is why their docs describe the shape of the generated code
+ * rather than how to call them. They are capabilities rather than a second bind hook so that
+ * generated code reaches them exactly as it reaches everything else, through `__bind($host)`.
+ */
+export const QUERY_CAPABILITIES = [
+    define(ECS_MODULE, 'query', [
+        { name: 'world', type: 'World' },
+        { name: 'a', type: 'String' },
+        { name: 'b', type: 'String' },
+        { name: 'c', type: 'String' },
+        { name: 'd', type: 'String' },
+    ], 'Cursor', ['ecs.read'], true, 'Open a walk over everything carrying these components. The cursor is borrowed from the world’s pool; ending the walk gives it back.'),
+    define(ECS_MODULE, 'without', [
+        { name: 'cursor', type: 'Cursor' },
+        { name: 'component', type: 'String' },
+    ], 'void', ['ecs.read'], true, 'Narrow an open walk to entities that do **not** carry a component.'),
+    define(ECS_MODULE, 'next', [{ name: 'cursor', type: 'Cursor' }], 'Entity', ['ecs.read'], true, 'The next entity, or a **negative** number when the walk is done — which also gives the cursor back. Negative rather than zero, because zero is a legal handle.'),
+    define(ECS_MODULE, 'view', [
+        { name: 'world', type: 'World' },
+        { name: 'component', type: 'String' },
+        { name: 'forWriting', type: 'bool' },
+    ], 'View', ['ecs.read'], true, 'A component’s live columns. `forWriting` decides which of a system’s declarations is checked — a loop that only reads takes a readable view, and asking for more than the system declared is refused.'),
+];
+export const PREFAB_CAPABILITIES = [
+    define(PREFAB_MODULE, 'spawn', [
+        { name: 'world', type: 'World' },
+        { name: 'prefab', type: 'String' },
+    ], 'Entity', ['ecs.write'], false, 'Make one, with every component the prefab names. Overrides are the host’s to apply; a script that wants a different value writes it after.'),
+];
+export function entitiesImplementation(services) {
+    const { components } = services;
+    /**
+     * Resolve a component name, or refuse naming what the world has.
+     *
+     * **Not `undefined` and not a no-op.** A script that misspells a component would otherwise read
+     * zeroes and write into nothing, which is a behaviour that runs, reports success and is wrong —
+     * the silent no-op this repository forbids, arriving through a string.
+     */
+    const resolve = (name) => {
+        const type = components.get(name);
+        if (type !== undefined)
+            return type;
+        throw new Error(`no component is registered as \`${name}\`. This host has ` +
+            `${[...components.keys()].map((k) => `\`${k}\``).join(', ')}. A script naming one that ` +
+            'does not exist would otherwise read zeroes and write into nothing.');
+    };
+    /*
+     * The last search's result, per world, held **here rather than on the world**.
+     *
+     * A script cannot receive a record, so the result is read back through an accessor — and putting
+     * the state in the binding keeps `World` free of a field that exists only because of a language
+     * limitation. A `WeakMap` rather than one shared slot, because two worlds are two questions and a
+     * shared slot would let one answer the other's. The same arrangement `physicsImplementation` makes
+     * for a raycast hit, for the same reasons.
+     */
+    const found = new WeakMap();
+    return {
+        create: (w) => w.create(),
+        destroy: (w, entity) => w.destroy(entity),
+        alive: (w, entity) => w.alive(entity),
+        has: (w, entity, component) => w.has(entity, resolve(component)),
+        attach: (w, entity, component) => w.add(entity, resolve(component)),
+        detach: (w, entity, component) => w.remove(entity, resolve(component)),
+        read: (w, entity, component, field) => {
+            const value = w.read(entity, resolve(component), field);
+            /* An entity without the component reads `undefined`, and a script's `f64` may not hold one:
+               the language has no null, so the honest zero is what a missing value is. */
+            return typeof value === 'number' ? value : 0;
+        },
+        write: (w, entity, component, field, value) => w.write(entity, resolve(component), field, value),
+        /*
+         * A query opens against whatever the caller passed as the world.
+         *
+         * **A `SystemView` and a `World` both satisfy this**, structurally, and that is the point: a
+         * loop inside a system runs against the view the schedule handed it, so every declaration
+         * check the engine makes still applies — and the same generated code runs against a bare world
+         * where there is no system to declare anything.
+         */
+        query: (w, a, b, c, d) => w.query(resolve(a), b === undefined ? undefined : resolve(b), c === undefined ? undefined : resolve(c), d === undefined ? undefined : resolve(d)),
+        without: (cursor, component) => {
+            cursor.without(resolve(component));
+        },
+        /*
+         * A negative ends the walk, and zero would not: zero is the handle of the first entity a fresh
+         * world ever allocates. Nothing is allocated to say "done" — a result record per step is the
+         * per-frame allocation the whole design refuses.
+         */
+        next: (cursor) => {
+            const step = cursor.next();
+            return step.done ? -1 : step.value;
+        },
+        view: (w, component, forWriting) => w.view(resolve(component), forWriting),
+        count: (w, component) => w.store(resolve(component)).size,
+        at: (w, component, index) => {
+            const store = w.store(resolve(component));
+            return index < store.size ? store.dense[index] : 0;
+        },
+        /*
+         * **A boolean rather than an option, and a second accessor for the handle.** `Sound?` is an
+         * option because a slot is resolved once at load; this is written to be called every frame by
+         * every agent that looks around, and `some(entity)` is one object per call — the same reasoning
+         * `next` gives one screen up. A sentinel is not available either: the result is an `Entity`, and
+         * a handle is not a number a script can compare to −1, which is the point of it having its own
+         * type. So the search answers whether it found anything and `nearest` reads what it found, the
+         * shape `raycast` and `hitBody` already have here.
+         *
+         * **Compared squared, so nothing takes a square root**, and the scan walks the dense columns
+         * directly: a store's dense position *is* its column index, so neither `sparse` nor a per-entity
+         * `read` is on this path. One pass, no allocation, no call per entity.
+         *
+         * A field this component does not have reads as absent rather than throwing, and an entity with
+         * no position contributes nothing — the honest answer for a component whose author named the
+         * wrong field is "nothing was near", reported by finding nothing, rather than a frame-loop
+         * throw that `AGENTS.md` forbids.
+         */
+        findNearest: (w, component, fieldX, fieldY, fieldZ, x, y, z, radius) => {
+            const type = resolve(component);
+            const view = w.view(type, false);
+            const columnX = view[fieldX];
+            const columnY = view[fieldY];
+            const columnZ = view[fieldZ];
+            if (columnX === undefined || columnY === undefined || columnZ === undefined) {
+                /* A component whose author named the wrong field answers "nothing was near" rather than
+                   throwing: a frame loop may not throw, and the boolean already carries that answer. */
+                found.set(w, -1);
+                return false;
+            }
+            /*
+             * **A cursor rather than the store's dense array, because `world` is not always a `World`.**
+             *
+             * Inside a system the value a script calls this with is the `SystemView` the schedule handed
+             * it, which carries `query` and `view` and no `store` — the same structural pair `query` and
+             * `view` above are typed against. A first version read `store.size` and `store.dense`, which
+             * works from a bare world and throws `w.store is not a function` the moment a system calls it.
+             * Going through the cursor is also what keeps a system's declared reads doing their job.
+             *
+             * The walk always runs to exhaustion, which is what gives the cursor back: it comes from a
+             * pool and is returned when `next` reports done, so an early exit on finding something close
+             * enough would leak one per call.
+             */
+            const cursor = w.query(type);
+            const limit = radius * radius;
+            let best = -1;
+            let bestDistance = Infinity;
+            for (;;) {
+                const step = cursor.next();
+                if (step.done === true)
+                    break;
+                const entity = step.value;
+                const at = view.sparse[entity % ENTITY_INDEX_CEILING];
+                const dx = columnX[at] - x;
+                const dy = columnY[at] - y;
+                const dz = columnZ[at] - z;
+                const distance = dx * dx + dy * dy + dz * dz;
+                if (distance > limit || distance >= bestDistance)
+                    continue;
+                bestDistance = distance;
+                best = entity;
+            }
+            found.set(w, best);
+            return best >= 0;
+        },
+        /*
+         * The handle the last search found, or zero when it found nothing.
+         *
+         * **Zero rather than a refusal**, because a frame loop may not throw and a script that read this
+         * without testing has a bug in its own logic rather than a broken host. Zero is a legal handle,
+         * so it is not a sentinel and is not documented as one — the honest test is the boolean, which
+         * is why the search answers one.
+         */
+        nearest: (w) => Math.max(0, found.get(w) ?? -1),
+    };
+}
+export function prefabImplementation(services) {
+    const prefabs = services.prefabs ?? new Map();
+    return {
+        spawn: (w, name) => {
+            const prefab = prefabs.get(name);
+            if (prefab === undefined) {
+                throw new Error(`no prefab is registered as \`${name}\`. This host has ` +
+                    `${[...prefabs.keys()].map((k) => `\`${k}\``).join(', ')}.`);
+            }
+            return instantiate(w, prefab);
+        },
+    };
+}

package/dist/bindings/interface.d.ts

@@ -0,0 +1,55 @@
+import type { CapabilityDefinition, OpaqueType } from 'driftscript';
+export declare const INTERFACE_MODULE = "drift/ui";
+/**
+ * `drift/ui` — a retained interface tree, addressed by the names its nodes were given.
+ *
+ * **The linker has refused this module by name since the language shipped**, saying it waits on
+ * Track F. It does not any more.
+ *
+ * **`drift/2d` is the other half of this track**, and it declares `SpriteBatch` — which `draw`
+ * takes. It was uncallable when it was first written: a module's namespace was the last segment of
+ * its path, so a call would have been `2d.sprite(...)`, and `2d` is a number followed by an
+ * identifier. DriftScript 1.11.0 answered it at the import, and `sprites.ts` carries the story.
+ *
+ * ## Names rather than node values, and the reason is the type system
+ *
+ * Every capability here takes the tree and a name. The alternative — a `UiNode` opaque a script
+ * holds — needs a lookup that can fail, and the language has no optional to answer with: a
+ * `uiChild` that returned the root when a name was absent would be a silent wrong answer inside a
+ * frame loop. Names are total. `has` asks whether one exists, every reader answers a defined value
+ * for a name that does not, and a script reads the way it reads: `if ui.hovered(tree, "start")`.
+ *
+ * It also matches what a tree is for. A host builds the tree, gives its nodes names, and hands the
+ * root to a script through `uses` — the way a `Terrain` and a `NavGraph` arrive. The script does not
+ * construct interfaces; it drives one.
+ *
+ * ## The effects, and the line between two of them
+ *
+ * **A layout, a draw and a change to a node are `scene.write`** — the language's own effect for a
+ * thing that draws, and outside `DETERMINISTIC_EFFECTS` for the right reason: an interface is view
+ * state, and a `@deterministic` system has no business moving it.
+ *
+ * **Reading a laid-out box is `scene.read`** and is inside the boundary, because a rect is state
+ * the layout already produced.
+ *
+ * **But `hovered`, `pressed`, `focused` and `activated` are `input.read`**, and that is the one
+ * distinction worth stopping on. Those flags live on the tree and are read like any other field —
+ * so declaring them `scene.read` would type-check and would be a lie, because what they carry is
+ * where the pointer is. `input.read` is outside `DETERMINISTIC_EFFECTS`, so a `@deterministic`
+ * system cannot ask whether the mouse is over a button, which is exactly right and is the property
+ * the annotation exists to guarantee.
+ */
+export declare const INTERFACE_TYPES: readonly OpaqueType[];
+export declare const INTERFACE_CAPABILITIES: readonly CapabilityDefinition[];
+/**
+ * **The router's state is kept here, per tree, which is the shape `drift/navigation` set.**
+ *
+ * A `UiInput` is hover, press and focus between one call and the next, and a script has nowhere to
+ * put one — the same position a script routing an agent was in before `navigation.path` started
+ * keeping a route per agent. So the host keeps one per tree, in a map keyed weakly so a tree going
+ * away takes its router with it.
+ *
+ * **No services**, for the reason `drift/terrain` gives: every capability takes the tree it acts on,
+ * so this is registered unconditionally and a script that never receives one never calls it.
+ */
+export declare function interfaceImplementation(): Record<string, unknown>;

package/dist/bindings/interface.js

@@ -0,0 +1,200 @@
+import { createUiInput, drawUiTree, layoutUiTree, routeUiKey, routeUiPointer, setUiFocus, uiNodeNamed, } from '@driftengine/ui2d';
+import { defineCapability } from 'driftscript';
+export const INTERFACE_MODULE = 'drift/ui';
+/**
+ * `drift/ui` — a retained interface tree, addressed by the names its nodes were given.
+ *
+ * **The linker has refused this module by name since the language shipped**, saying it waits on
+ * Track F. It does not any more.
+ *
+ * **`drift/2d` is the other half of this track**, and it declares `SpriteBatch` — which `draw`
+ * takes. It was uncallable when it was first written: a module's namespace was the last segment of
+ * its path, so a call would have been `2d.sprite(...)`, and `2d` is a number followed by an
+ * identifier. DriftScript 1.11.0 answered it at the import, and `sprites.ts` carries the story.
+ *
+ * ## Names rather than node values, and the reason is the type system
+ *
+ * Every capability here takes the tree and a name. The alternative — a `UiNode` opaque a script
+ * holds — needs a lookup that can fail, and the language has no optional to answer with: a
+ * `uiChild` that returned the root when a name was absent would be a silent wrong answer inside a
+ * frame loop. Names are total. `has` asks whether one exists, every reader answers a defined value
+ * for a name that does not, and a script reads the way it reads: `if ui.hovered(tree, "start")`.
+ *
+ * It also matches what a tree is for. A host builds the tree, gives its nodes names, and hands the
+ * root to a script through `uses` — the way a `Terrain` and a `NavGraph` arrive. The script does not
+ * construct interfaces; it drives one.
+ *
+ * ## The effects, and the line between two of them
+ *
+ * **A layout, a draw and a change to a node are `scene.write`** — the language's own effect for a
+ * thing that draws, and outside `DETERMINISTIC_EFFECTS` for the right reason: an interface is view
+ * state, and a `@deterministic` system has no business moving it.
+ *
+ * **Reading a laid-out box is `scene.read`** and is inside the boundary, because a rect is state
+ * the layout already produced.
+ *
+ * **But `hovered`, `pressed`, `focused` and `activated` are `input.read`**, and that is the one
+ * distinction worth stopping on. Those flags live on the tree and are read like any other field —
+ * so declaring them `scene.read` would type-check and would be a lie, because what they carry is
+ * where the pointer is. `input.read` is outside `DETERMINISTIC_EFFECTS`, so a `@deterministic`
+ * system cannot ask whether the mouse is over a button, which is exactly right and is the property
+ * the annotation exists to guarantee.
+ */
+export const INTERFACE_TYPES = [
+    {
+        module: INTERFACE_MODULE,
+        name: 'UiTree',
+        doc: 'The root of a retained interface tree. Its nodes are addressed by the names they were built with.',
+    },
+];
+const define = (name, params, returns, effects, doc) => defineCapability({
+    module: INTERFACE_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects: [...effects],
+    deterministic: effects.every((effect) => effect === 'scene.read'),
+    doc,
+    implementation: `${INTERFACE_MODULE}.${name}`,
+});
+const NAMED = [
+    { name: 'tree', type: 'UiTree' },
+    { name: 'name', type: 'String' },
+];
+export const INTERFACE_CAPABILITIES = [
+    define('layout', [
+        { name: 'tree', type: 'UiTree' },
+        { name: 'x', type: 'f32' },
+        { name: 'y', type: 'f32' },
+        { name: 'w', type: 'f32' },
+        { name: 'h', type: 'f32' },
+    ], 'void', ['scene.write'], 'Lay the tree out into a box. The box is what is available: a tree sized by its contents comes to what its contents come to.'),
+    define('draw', [
+        { name: 'tree', type: 'UiTree' },
+        { name: 'batch', type: 'SpriteBatch' },
+        { name: 'white', type: 'i32' },
+    ], 'i32', ['scene.write'], "Put the tree in a batch and answer how many quads that was. `white` is the sprite pass's own white slot, which is what a background is drawn on."),
+    define('has', NAMED, 'bool', ['scene.read'], 'Whether the tree holds a node of this name. Every reader below answers a defined value without it, so this is for a script that wants to know rather than one that would crash.'),
+    define('left', NAMED, 'f32', ['scene.read'], 'Where a node ended up, along x. Zero for a name the tree does not hold.'),
+    define('top', NAMED, 'f32', ['scene.read'], 'The same, along y.'),
+    define('width', NAMED, 'f32', ['scene.read'], 'How wide a node ended up.'),
+    define('height', NAMED, 'f32', ['scene.read'], 'How tall a node ended up.'),
+    define('visible', NAMED, 'bool', ['scene.read'], 'Whether a node is shown. A hidden node is out of the layout and out of the hit test, not merely invisible.'),
+    define('show', [...NAMED, { name: 'visible', type: 'bool' }], 'void', ['scene.write'], 'Show or hide a node and everything under it.'),
+    define('setText', [...NAMED, { name: 'text', type: 'String' }], 'void', ['scene.write'], "Change what a node says. What draws it is the caller's: this package draws quads, and core already draws two kinds of text."),
+    define('tint', [
+        ...NAMED,
+        { name: 'r', type: 'f32' },
+        { name: 'g', type: 'f32' },
+        { name: 'b', type: 'f32' },
+        { name: 'a', type: 'f32' },
+    ], 'void', ['scene.write'], "Change a node's background colour. A node with no background gets one."),
+    define('hovered', NAMED, 'bool', ['input.read'], 'Whether the pointer is over a node.'),
+    define('pressed', NAMED, 'bool', ['input.read'], 'Whether the pointer went down on a node and has not come up.'),
+    define('focused', NAMED, 'bool', ['input.read'], 'Whether a node has the keyboard.'),
+    /*
+     * **`point` answers whether anything was activated and `activated` asks which**, rather than one
+     * call returning a name. The language has no optional to answer a miss with, and a two-call shape
+     * is what `drift/behavior`'s `doing` already uses for the same reason: ask by the name you have.
+     */
+    define('point', [
+        { name: 'tree', type: 'UiTree' },
+        { name: 'x', type: 'f32' },
+        { name: 'y', type: 'f32' },
+        { name: 'down', type: 'bool' },
+    ], 'bool', ['input.read', 'scene.write'], 'Route the pointer, and answer whether this call activated anything. An activation is a press and a release on the same node, so somebody who pressed the wrong button can slide off it.'),
+    define('activated', NAMED, 'bool', ['input.read'], 'Whether the last `point` activated this node. Read it in the same step that called `point`; the next one clears it.'),
+    define('key', [
+        { name: 'tree', type: 'UiTree' },
+        { name: 'key', type: 'String' },
+        { name: 'shift', type: 'bool' },
+    ], 'bool', ['input.read', 'scene.write'], 'Route a key, and answer whether it activated what has focus. Tab moves focus, Enter and space activate, and everything else is reported unhandled so the caller can have it.'),
+    define('focus', NAMED, 'void', ['scene.write'], 'Give a node the keyboard. A name the tree does not hold focuses nothing.'),
+];
+/**
+ * **The router's state is kept here, per tree, which is the shape `drift/navigation` set.**
+ *
+ * A `UiInput` is hover, press and focus between one call and the next, and a script has nowhere to
+ * put one — the same position a script routing an agent was in before `navigation.path` started
+ * keeping a route per agent. So the host keeps one per tree, in a map keyed weakly so a tree going
+ * away takes its router with it.
+ *
+ * **No services**, for the reason `drift/terrain` gives: every capability takes the tree it acts on,
+ * so this is registered unconditionally and a script that never receives one never calls it.
+ */
+export function interfaceImplementation() {
+    const routers = new WeakMap();
+    /* What the last `point` or `key` activated, so `activated` can be asked by name. */
+    const activations = new WeakMap();
+    const routerOf = (tree) => {
+        let input = routers.get(tree);
+        if (input === undefined) {
+            input = createUiInput();
+            routers.set(tree, input);
+        }
+        return input;
+    };
+    const nodeOf = (tree, name) => uiNodeNamed(tree, name);
+    return {
+        layout: (tree, x, y, w, h) => {
+            layoutUiTree(tree, x, y, w, h);
+        },
+        draw: (tree, batch, white) => drawUiTree(batch, tree, white, null),
+        has: (tree, name) => nodeOf(tree, name) !== null,
+        left: (tree, name) => nodeOf(tree, name)?.rect.x ?? 0,
+        top: (tree, name) => nodeOf(tree, name)?.rect.y ?? 0,
+        width: (tree, name) => nodeOf(tree, name)?.rect.w ?? 0,
+        height: (tree, name) => nodeOf(tree, name)?.rect.h ?? 0,
+        visible: (tree, name) => {
+            const node = nodeOf(tree, name);
+            return node !== null && !node.hidden;
+        },
+        show: (tree, name, visible) => {
+            const node = nodeOf(tree, name);
+            if (node !== null)
+                node.hidden = !visible;
+        },
+        setText: (tree, name, text) => {
+            const node = nodeOf(tree, name);
+            if (node !== null)
+                node.text = text;
+        },
+        tint: (tree, name, r, g, b, a) => {
+            const node = nodeOf(tree, name);
+            if (node === null)
+                return;
+            /* A node with no background gets one, which is the only allocation in this module and
+               happens once per node rather than per frame. */
+            if (node.background === null)
+                node.background = new Float32Array(4);
+            node.background[0] = r;
+            node.background[1] = g;
+            node.background[2] = b;
+            node.background[3] = a;
+        },
+        hovered: (tree, name) => nodeOf(tree, name)?.hovered === true,
+        pressed: (tree, name) => nodeOf(tree, name)?.pressed === true,
+        focused: (tree, name) => {
+            const node = nodeOf(tree, name);
+            return node !== null && routerOf(tree).focused === node;
+        },
+        point: (tree, x, y, down) => {
+            const hit = routeUiPointer(routerOf(tree), tree, x, y, down);
+            activations.set(tree, hit);
+            return hit !== null;
+        },
+        activated: (tree, name) => {
+            const node = nodeOf(tree, name);
+            return node !== null && activations.get(tree) === node;
+        },
+        key: (tree, key, shift) => {
+            const hit = routeUiKey(routerOf(tree), tree, key, shift);
+            activations.set(tree, hit);
+            return hit !== null;
+        },
+        focus: (tree, name) => {
+            setUiFocus(routerOf(tree), nodeOf(tree, name));
+        },
+    };
+}

package/dist/bindings/navigation.d.ts

@@ -0,0 +1,36 @@
+import { NavSearch } from '@driftengine/core';
+import type { NavGraph } from '@driftengine/core';
+import type { CapabilityDefinition, OpaqueType } from 'driftscript';
+export declare const NAVIGATION_MODULE = "drift/navigation";
+/**
+ * `drift/navigation` — a graph, a route over it, and a point to steer at.
+ *
+ * **The linker has refused this module by name since the language shipped**, and the reason given
+ * was that nothing here paths. That was true and it was never a blocker: it was the row. A consumer
+ * reported what its absence costs them — twelve agents that walk straight at whatever they are
+ * going to and wedge against a building on the way, about once every two minutes of play — and
+ * noted that they already extract a road graph from their world, which is the half of the work that
+ * is usually the awkward half.
+ *
+ * **A graph and not a mesh**, and the header of `navGraph.ts` argues that where the decision is:
+ * these consumers arrive with a network already, and open ground crossed by two nodes is crossed in
+ * a straight line.
+ *
+ * **`navigation.read` is a deterministic effect**, which the language decided before this existed
+ * and this has to keep true: a route is a function of the graph and its two endpoints and of
+ * nothing else, ties included. `navSearch.ts` is where that is held. A `@deterministic` system may
+ * therefore path, which is the point — deciding where to walk is exactly the kind of thing that
+ * belongs inside the fixed step.
+ */
+export declare const NAVIGATION_TYPES: readonly OpaqueType[];
+export declare const NAVIGATION_CAPABILITIES: readonly CapabilityDefinition[];
+/** What a consumer hands the host so scripts can path over their world. */
+export interface NavigationServices {
+    /** The network. One graph; a consumer with several composes them into one before handing it over. */
+    readonly graph: NavGraph;
+    /** A search over that graph, reused across every agent. */
+    readonly search: NavSearch;
+    /** How many nodes a route may have. Longer routes are refused rather than truncated. */
+    readonly maxRouteNodes?: number;
+}
+export declare function navigationImplementation(services: NavigationServices): Record<string, unknown>;