@driftengine/script 3.61.0

package/dist/bindings/navigation.js

@@ -0,0 +1,255 @@
+import { NavPath, NavSearch, createNavSteer, nearestNavNode } from '@driftengine/core';
+import { entityGeneration, entityIndex } from '@driftengine/entities';
+import { defineCapability } from 'driftscript';
+export 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 const NAVIGATION_TYPES = [
+    {
+        module: NAVIGATION_MODULE,
+        name: 'NavGraph',
+        doc: 'A network of places and the ways between them.',
+    },
+    {
+        module: NAVIGATION_MODULE,
+        name: 'NavPath',
+        doc: 'A route being walked, and how far along it the walker is. Ask it where to steer.',
+    },
+];
+const define = (name, params, returns, effects, doc, deterministic = true, allocates = false) => defineCapability({
+    module: NAVIGATION_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    ...(allocates ? { allocates: true } : {}),
+    effects: effects,
+    /*
+     * **Writing a route is deterministic too, as of DriftScript 1.12.0**, and this paragraph used
+     * to say the opposite. `navigation.read` was in `DETERMINISTIC_EFFECTS` and `navigation.write`
+     * was not, so a `@deterministic` system could steer along a route and could not compute one —
+     * an agent re-pathing inside the fixed step, because a bridge dropped or because it was pushed
+     * off the network, had to path from an ordinary system and hand the result in.
+     *
+     * **It reversed on exactly the argument this comment named**, which is the whole reason the
+     * condition was written down rather than the limitation merely stated: a route is a function of
+     * the graph and two endpoints, `navSearch.ts` breaks ties on the node index so two runs agree,
+     * and the `NavPath` written into is simulation state rather than a host's. The language's own
+     * deferral said the track that builds an effect is the one that can answer for its replay
+     * behaviour; this track shipped, so it answered.
+     *
+     * Every capability here is deterministic now, so the parameter keeps its default and the three
+     * writers stopped passing `false`.
+     */
+    deterministic,
+    doc,
+    implementation: `${NAVIGATION_MODULE}.${name}`,
+});
+export const NAVIGATION_CAPABILITIES = [
+    define('nearest', [
+        { name: 'graph', type: 'NavGraph' },
+        { name: 'x', type: 'float' },
+        { name: 'y', type: 'float' },
+        { name: 'z', type: 'float' },
+    ], 'i32', ['navigation.read'], 'The node nearest a place, or -1 where the graph has none. How an agent gets onto the network.'),
+    define('nearestWithin', [
+        { name: 'graph', type: 'NavGraph' },
+        { name: 'x', type: 'float' },
+        { name: 'y', type: 'float' },
+        { name: 'z', type: 'float' },
+        { name: 'maxDistance', type: 'float' },
+    ], 'i32', ['navigation.read'], 'The nearest node within a distance, or -1. Use it so an agent that has walked off the network is not snapped to the far side of the map.'),
+    /*
+     * **`route` takes places and not node indices**, which is the whole difference between a binding
+     * a script author can use and one they have to learn a data model for first. Getting onto a graph
+     * is `nearest` twice, and a script that had to write that would write it identically every time
+     * and get the out-of-reach case wrong once.
+     */
+    define('route', [
+        { name: 'path', type: 'NavPath' },
+        { name: 'graph', type: 'NavGraph' },
+        { name: 'fromX', type: 'float' },
+        { name: 'fromY', type: 'float' },
+        { name: 'fromZ', type: 'float' },
+        { name: 'toX', type: 'float' },
+        { name: 'toY', type: 'float' },
+        { name: 'toZ', type: 'float' },
+    ], 'bool', ['navigation.write'], 'Path from one place to another, storing the route. False where there is no way through, which is an answer and not a failure.'),
+    define('routeBetween', [
+        { name: 'path', type: 'NavPath' },
+        { name: 'graph', type: 'NavGraph' },
+        { name: 'from', type: 'i32' },
+        { name: 'to', type: 'i32' },
+    ], 'bool', ['navigation.write'], 'The same, between two nodes you already have. For a consumer with their own spatial index.'),
+    /*
+     * **A route per agent, because a script had nowhere to keep one.**
+     *
+     * Every capability above takes a `NavPath` and nothing here made one, so a consumer kept a path
+     * per agent in TypeScript and called a script function once per agent per step — which is the
+     * report DriftScript 1.8.0's `uses` clause answers half of. `uses` hands a system the *graph*, one
+     * per world; a route is one per walker, and a resource is one per type, so the other half has to
+     * arrive as a value a script can ask for by entity. This is it, and with it the loop over agents
+     * goes back into the `system` where it can be reloaded.
+     *
+     * **Kept per entity *index*, with the generation beside it.** A map keyed by the handle would grow
+     * for the life of the world — every agent that ever pathed, long after it was destroyed, with no
+     * moment at which anything could know to drop one. An index is bounded by the world's ceiling, and
+     * a reused index arriving with a different generation is a different agent, so the route is
+     * cleared rather than inherited. That is the failure worth naming: without the check a freshly
+     * spawned walker would set off along the route of whatever died in its slot.
+     *
+     * **It allocates the first time it is asked about an agent** and never again, which `allocates`
+     * says so a `@hot` function is told. There is no way around it — a route is a buffer — and the
+     * alternative, making a script pass its own, is the thing this exists to remove.
+     */
+    define('path', [{ name: 'agent', type: 'Entity' }], 'NavPath', ['navigation.read'], "The route this agent is following, kept by the host between steps. Empty until something routes it, and empty again if the agent's handle is reused.", true, true),
+    define('clear', [{ name: 'path', type: 'NavPath' }], 'void', ['navigation.write'], 'Forget the route. The walker is then arrived, wherever it is.'),
+    define('following', [{ name: 'path', type: 'NavPath' }], 'bool', ['navigation.read'], 'Whether there is a route to follow.'),
+    /*
+     * **The steer is read back through four accessors**, which is the shape `input.axisX` and
+     * `animation.hitX` already have and the reason is the same: the language has no way to return a
+     * record by value into a caller's own storage, and an opaque handle for a three-float answer
+     * would be a lifetime a script author has to think about to read a direction.
+     *
+     * The implementation answers all four from one computation — see `navigationImplementation`,
+     * where the reason it can is that the arguments say what the answer depends on.
+     */
+    define('steerX', [
+        { name: 'path', type: 'NavPath' },
+        { name: 'x', type: 'float' },
+        { name: 'y', type: 'float' },
+        { name: 'z', type: 'float' },
+    ], 'float', ['navigation.read'], 'Where a walker at this place should aim, along x. A point ahead on the path rather than the next node, so corners are cut smoothly instead of snapped at.'),
+    define('steerY', [
+        { name: 'path', type: 'NavPath' },
+        { name: 'x', type: 'float' },
+        { name: 'y', type: 'float' },
+        { name: 'z', type: 'float' },
+    ], 'float', ['navigation.read'], 'The same aim point, along y.'),
+    define('steerZ', [
+        { name: 'path', type: 'NavPath' },
+        { name: 'x', type: 'float' },
+        { name: 'y', type: 'float' },
+        { name: 'z', type: 'float' },
+    ], 'float', ['navigation.read'], 'The same aim point, along z.'),
+    define('remaining', [
+        { name: 'path', type: 'NavPath' },
+        { name: 'x', type: 'float' },
+        { name: 'y', type: 'float' },
+        { name: 'z', type: 'float' },
+    ], 'float', ['navigation.read'], 'How far is left, following the path rather than as the crow flies.'),
+    define('arrived', [
+        { name: 'path', type: 'NavPath' },
+        { name: 'x', type: 'float' },
+        { name: 'y', type: 'float' },
+        { name: 'z', type: 'float' },
+    ], 'bool', ['navigation.read'], 'Whether the walker is there. True with no route at all, so one check covers both.'),
+];
+export function navigationImplementation(services) {
+    const buffer = new Uint32Array(services.maxRouteNodes ?? 256);
+    const steer = createNavSteer();
+    /*
+     * The last place a steer was computed for, so `steerX`, `steerY`, `steerZ`, `remaining` and
+     * `arrived` at one position cost one walk of the path rather than five. Correct rather than
+     * merely fast: the answer is a function of the path and the place, and the path cannot change
+     * between two reads inside a script's own statement.
+     */
+    let cachedPath = null;
+    let cachedX = NaN;
+    let cachedY = NaN;
+    let cachedZ = NaN;
+    /*
+     * One route per agent, by entity **index**, with the generation beside it.
+     *
+     * Two sparse arrays rather than a `Map` keyed by the handle: a map grows for the life of the
+     * world, one entry per agent that ever pathed, and nothing is in a position to know when to drop
+     * one. An index is bounded by the world's ceiling. The generation is what makes a reused index
+     * safe — a slot arriving with a different one is a different agent, and its route is cleared
+     * rather than inherited, which would otherwise send a freshly spawned walker off along the route
+     * of whatever died in its place.
+     */
+    const routes = [];
+    const owners = [];
+    const at = (path, x, y, z) => {
+        if (path !== cachedPath || x !== cachedX || y !== cachedY || z !== cachedZ) {
+            path.steer(x, y, z, steer);
+            cachedPath = path;
+            cachedX = x;
+            cachedY = y;
+            cachedZ = z;
+        }
+        return steer;
+    };
+    /** Any write to a path invalidates the cache, since the answer depends on the route. */
+    const invalidate = () => {
+        cachedPath = null;
+    };
+    return {
+        path(agent) {
+            const index = entityIndex(agent);
+            const generation = entityGeneration(agent);
+            let route = routes[index];
+            if (route === undefined) {
+                route = new NavPath(services.graph, services.maxRouteNodes ?? 256);
+                routes[index] = route;
+            }
+            else if (owners[index] !== generation) {
+                /* The slot was somebody else's. Clearing rather than replacing keeps the allocation this
+                   agent is about to need and leaves nothing of the last one's route. */
+                route.clear();
+                invalidate();
+            }
+            owners[index] = generation;
+            return route;
+        },
+        nearest: (graph, x, y, z) => nearestNavNode(graph, x, y, z),
+        nearestWithin: (graph, x, y, z, maxDistance) => nearestNavNode(graph, x, y, z, maxDistance),
+        route(path, graph, fromX, fromY, fromZ, toX, toY, toZ) {
+            invalidate();
+            const from = nearestNavNode(graph, fromX, fromY, fromZ);
+            const to = nearestNavNode(graph, toX, toY, toZ);
+            if (from < 0 || to < 0) {
+                path.clear();
+                return false;
+            }
+            const count = services.search.find(from, to, buffer);
+            path.set(buffer, count);
+            return count > 1;
+        },
+        routeBetween(path, graph, from, to) {
+            invalidate();
+            void graph;
+            const count = services.search.find(from, to, buffer);
+            path.set(buffer, count);
+            return count > 1;
+        },
+        clear(path) {
+            invalidate();
+            path.clear();
+        },
+        following: (path) => path.active,
+        steerX: (path, x, y, z) => at(path, x, y, z).x,
+        steerY: (path, x, y, z) => at(path, x, y, z).y,
+        steerZ: (path, x, y, z) => at(path, x, y, z).z,
+        remaining: (path, x, y, z) => at(path, x, y, z).remainingM,
+        arrived: (path, x, y, z) => at(path, x, y, z).arrived,
+    };
+}

package/dist/bindings/network.d.ts

@@ -0,0 +1,51 @@
+import type { CapabilityDefinition, OpaqueType } from 'driftscript';
+export declare const NETWORK_MODULE = "drift/network";
+/**
+ * `drift/network` — what a script can see of a session, and the scalars it can publish.
+ *
+ * **The linker has refused this module by name since the language shipped**, saying it waits on
+ * Track J. The corpus carries `NetworkReplicatedActor.drs`, written *before* any provider existed
+ * so that "the networking semantics are written down before networking couples itself to the state
+ * and task design". Its names are honoured here — `replicate` and `authority` are both capabilities
+ * — and its one illustrative call is not: it reads `network.replicate(character.x, character.y)`, with no
+ * session, because when it was written there was no handle to take. Every capability takes the
+ * thing it is about, the way every other binding in this directory does.
+ *
+ * ---
+ *
+ * ## The effect split, which the language asked this track to make
+ *
+ * `capability.ts` puts `network.read` **inside** `DETERMINISTIC_EFFECTS` and leaves `network.write`
+ * outside, with a note that the exclusion is *"a deferral rather than a judgement: each belongs to a
+ * track that has not shipped, and the track that builds one is the one that can say whether its
+ * writes are the simulation or a consequence of it."* This is that track, so here is the answer.
+ *
+ * **`network.write` stays outside, and the rollback loop is the reason.** The tempting argument for
+ * admitting it is that publishing a value changes no simulation state, so a replay would publish
+ * the same thing and nothing would drift. That argument is exactly backwards once a rewind exists:
+ * **a `@deterministic` function is precisely the kind that gets re-run**, several times, over ticks
+ * that have already happened. A send is not idempotent — the replay would publish the same value
+ * again for a tick a peer already has, and a correction that replayed twelve ticks would put twelve
+ * duplicate messages on the wire. Deferring the effect was right and the deferral now has a reason
+ * behind it rather than an absence.
+ *
+ * **`network.read` is kept for the two things that genuinely do not vary**: which participant this
+ * is, and whether this peer is the authority. Both are fixed when the session is created, so a
+ * `@deterministic` system may branch on them and replay identically.
+ *
+ * **Everything else a session knows is `nondeterministic`, and that is not pedantry.** The confirmed
+ * watermark, the participant count and whether the session has halted all move with packet timing:
+ * a system that branched on "is tick 400 confirmed" would take one path live and the other on
+ * replay, which is the class of bug rollback netcode is famous for. `bindings/ui.ts` made the same
+ * call for `hovered` and `pressed`, and this file's version of that sentence is: an effect that
+ * type-checks can still be a lie.
+ *
+ * ## Slots rather than field names
+ *
+ * `replicate(session, slot, value)` writes into a numbered table. A name would need a string map on
+ * a per-tick path and a miss would need an optional to answer with, which the language does not
+ * have. A slot out of range does nothing on write and answers zero on read, so both are total.
+ */
+export declare const NETWORK_TYPES: readonly OpaqueType[];
+export declare const NETWORK_CAPABILITIES: readonly CapabilityDefinition[];
+export declare function networkImplementation(): Record<string, unknown>;

package/dist/bindings/network.js

@@ -0,0 +1,96 @@
+import { defineCapability } from 'driftscript';
+export const NETWORK_MODULE = 'drift/network';
+/**
+ * `drift/network` — what a script can see of a session, and the scalars it can publish.
+ *
+ * **The linker has refused this module by name since the language shipped**, saying it waits on
+ * Track J. The corpus carries `NetworkReplicatedActor.drs`, written *before* any provider existed
+ * so that "the networking semantics are written down before networking couples itself to the state
+ * and task design". Its names are honoured here — `replicate` and `authority` are both capabilities
+ * — and its one illustrative call is not: it reads `network.replicate(character.x, character.y)`, with no
+ * session, because when it was written there was no handle to take. Every capability takes the
+ * thing it is about, the way every other binding in this directory does.
+ *
+ * ---
+ *
+ * ## The effect split, which the language asked this track to make
+ *
+ * `capability.ts` puts `network.read` **inside** `DETERMINISTIC_EFFECTS` and leaves `network.write`
+ * outside, with a note that the exclusion is *"a deferral rather than a judgement: each belongs to a
+ * track that has not shipped, and the track that builds one is the one that can say whether its
+ * writes are the simulation or a consequence of it."* This is that track, so here is the answer.
+ *
+ * **`network.write` stays outside, and the rollback loop is the reason.** The tempting argument for
+ * admitting it is that publishing a value changes no simulation state, so a replay would publish
+ * the same thing and nothing would drift. That argument is exactly backwards once a rewind exists:
+ * **a `@deterministic` function is precisely the kind that gets re-run**, several times, over ticks
+ * that have already happened. A send is not idempotent — the replay would publish the same value
+ * again for a tick a peer already has, and a correction that replayed twelve ticks would put twelve
+ * duplicate messages on the wire. Deferring the effect was right and the deferral now has a reason
+ * behind it rather than an absence.
+ *
+ * **`network.read` is kept for the two things that genuinely do not vary**: which participant this
+ * is, and whether this peer is the authority. Both are fixed when the session is created, so a
+ * `@deterministic` system may branch on them and replay identically.
+ *
+ * **Everything else a session knows is `nondeterministic`, and that is not pedantry.** The confirmed
+ * watermark, the participant count and whether the session has halted all move with packet timing:
+ * a system that branched on "is tick 400 confirmed" would take one path live and the other on
+ * replay, which is the class of bug rollback netcode is famous for. `bindings/ui.ts` made the same
+ * call for `hovered` and `pressed`, and this file's version of that sentence is: an effect that
+ * type-checks can still be a lie.
+ *
+ * ## Slots rather than field names
+ *
+ * `replicate(session, slot, value)` writes into a numbered table. A name would need a string map on
+ * a per-tick path and a miss would need an optional to answer with, which the language does not
+ * have. A slot out of range does nothing on write and answers zero on read, so both are total.
+ */
+export const NETWORK_TYPES = [
+    {
+        module: NETWORK_MODULE,
+        name: 'Session',
+        doc: 'A networking session: who this peer is, what it can see of the others, and the scalars it publishes.',
+    },
+];
+const define = (name, params, returns, effects, deterministic, doc) => defineCapability({
+    module: NETWORK_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects: [...effects],
+    deterministic,
+    doc,
+    implementation: `${NETWORK_MODULE}.${name}`,
+});
+const ON = [{ name: 'session', type: 'Session' }];
+export const NETWORK_CAPABILITIES = [
+    /* The two that do not move. See the header for why only these two. */
+    define('self', ON, 'i32', ['network.read'], true, 'Which participant this peer is. Fixed for the life of the session, which is why a deterministic system may read it.'),
+    define('authority', ON, 'bool', ['network.read'], true, 'Whether this peer’s world is the authoritative one. Fixed when the session is created.'),
+    /* Everything that moves with packet timing. */
+    define('participants', ON, 'i32', ['nondeterministic'], false, 'How many participants the session holds. Nondeterministic because somebody may join or leave between two runs of the same recording.'),
+    define('confirmed', ON, 'i32', ['nondeterministic'], false, 'The highest tick every participant’s input has arrived for, or -1. Moves with packet timing, so a deterministic system may not branch on it.'),
+    define('halted', ON, 'bool', ['nondeterministic'], false, 'Whether the session has stopped, because an input arrived too late to apply or two peers computed different worlds.'),
+    define('haltReason', ON, 'String', ['nondeterministic'], false, 'Why it halted, as a sentence, or an empty string. Names the tick a divergence began at.'),
+    define('slots', ON, 'i32', ['nondeterministic'], false, 'How many replicated scalars each participant has. A consumer sizes this when the session is made.'),
+    define('replicated', [...ON, { name: 'participant', type: 'i32' }, { name: 'slot', type: 'i32' }], 'f32', ['nondeterministic'], false, 'Read a participant’s published scalar. An index out of range answers zero rather than failing, because a frame loop has nothing to do with a refusal.'),
+    /* And the one write. */
+    define('replicate', [...ON, { name: 'slot', type: 'i32' }, { name: 'value', type: 'f32' }], 'void', ['network.write'], false, 'Publish a value in one of this peer’s slots. Not callable from a deterministic system: a replay re-runs one and a send is not idempotent.'),
+];
+export function networkImplementation() {
+    return {
+        self: (session) => session.self,
+        authority: (session) => session.authority,
+        participants: (session) => session.participants,
+        confirmed: (session) => session.confirmed,
+        halted: (session) => session.halted,
+        haltReason: (session) => session.haltReason,
+        slots: (session) => session.slots,
+        replicated: (session, participant, slot) => session.replicated(participant, slot),
+        replicate: (session, slot, value) => {
+            session.replicate(slot, value);
+        },
+    };
+}

package/dist/bindings/render.d.ts

@@ -0,0 +1,71 @@
+import { type CapabilityDefinition, type OpaqueType } from 'driftscript';
+export declare const RENDER_MODULE = "drift/render";
+/**
+ * `drift/render` — how the finished image is presented, for the frame about to be drawn.
+ *
+ * **The linker refused this module by name from the day the language shipped until now**, and the
+ * roadmap slot it was waiting on was Track D. Track D completed on 2026-09-03 with refraction, so
+ * the wait ended five releases before anything noticed — `docs/CAPABILITIES.md` still mapped this
+ * module to a track that had closed, while `host.test.ts` had already been corrected to say it
+ * waits on a row of its own. Two documents, one right.
+ *
+ * ## What this module is, which is a smaller thing than "the renderer"
+ *
+ * `RenderQuality` has fifty fields and **none of them are here.** The engine already draws
+ * the line this module needs, in `renderQuality.ts`'s own words about depth of field:
+ *
+ * > A ceiling rather than the effect [...] this says how far a defocused point may spread and
+ * > therefore what the pass may cost, and `setDepthOfField` says where this frame's lens is focused
+ * > and how much of the ceiling it takes. A camera focuses on a subject; a quality profile decides
+ * > how expensive that is allowed to be.
+ *
+ * **A quality profile is the application's and a dial is the game's.** A profile is chosen once,
+ * from what the device can afford, and is clamped by `capabilityClamp` against what the adapter
+ * actually reports; a script that wrote to one would be overruling a decision made about hardware
+ * it cannot see, and two machines running the same script would draw different pictures for
+ * reasons the script did not choose. So this module binds the seven dials and none of the ceilings.
+ *
+ * ## Writes only, and the reason is the same one
+ *
+ * There is no `render.bloomOf` here, and nothing reads a dial back. Every one of these is **clamped
+ * against the ceiling the host set** — `setBloom` does nothing at all when `bloom` is 0, because
+ * the chain is never built — so what a read would answer is a fact about the machine wearing the
+ * costume of a fact about the frame. The language wrote this argument once already, for
+ * `network.read` and a confirmed-input watermark: a host registering a machine-dependent number
+ * under a deterministic effect hands a `@deterministic` system a value that differs between a run
+ * and its replay. A script sets a dial; what the device did with it is the device's business.
+ *
+ * ## The effect, which needed no language release
+ *
+ * **`scene.write`, and it is a description rather than a borrowing.** `capability.ts` puts
+ * `scene.write` outside `DETERMINISTIC_EFFECTS` and says exactly why: *"a `SceneNode` is what
+ * draws, and `ARCHITECTURE.md` forbids render code mutating simulation state, so moving a node is
+ * a change to the view."* Every capability here is a change to the view and nothing else — the
+ * renderers' own comments call these *"a renderer parameter rather than a scene one: it describes
+ * how the finished image is presented, not anything in the world, which is why nothing about the
+ * world has to know it exists."* Two files arriving at the same sentence from opposite ends is the
+ * argument.
+ *
+ * So no capability here is deterministic, and that is the property rather than a limitation: a
+ * `@deterministic` system may not dim the screen. Presentation belongs outside the fixed step,
+ * where the frame is.
+ */
+export declare const RENDER_TYPES: readonly OpaqueType[];
+export declare const RENDER_CAPABILITIES: readonly CapabilityDefinition[];
+/**
+ * Unconditional, like `drift/terrain` and `drift/editor`: every capability takes the renderer it
+ * acts on, which reaches a script through `uses`, so there is nothing for an absent service to
+ * make fail.
+ *
+ * **`medium` takes every argument the engine defaults**, unlike `setGlobalMedium`, and for the
+ * reason `focus` gives about its own `scale`: a script author is further from the cost than a
+ * TypeScript caller, and a defaulted albedo is a number somebody has to go and look up before they
+ * can tell what their fog will look like. Four numbers is one line either way.
+ *
+ *  * **`speedBlur` is the one name here that is not the engine's own.** The method is `setSpeedRush`,
+ * and a rush is a thing that happens in somebody's game rather than a description of an image
+ * operation — binding that spelling would have written one consumer's noun into the language's
+ * surface, where it could not later be taken back. A binding is a lookup and this is what a lookup
+ * is for.
+ */
+export declare function renderImplementation(): Record<string, unknown>;

package/dist/bindings/render.js

@@ -0,0 +1,143 @@
+import { defineCapability } from 'driftscript';
+export const RENDER_MODULE = 'drift/render';
+/**
+ * `drift/render` — how the finished image is presented, for the frame about to be drawn.
+ *
+ * **The linker refused this module by name from the day the language shipped until now**, and the
+ * roadmap slot it was waiting on was Track D. Track D completed on 2026-09-03 with refraction, so
+ * the wait ended five releases before anything noticed — `docs/CAPABILITIES.md` still mapped this
+ * module to a track that had closed, while `host.test.ts` had already been corrected to say it
+ * waits on a row of its own. Two documents, one right.
+ *
+ * ## What this module is, which is a smaller thing than "the renderer"
+ *
+ * `RenderQuality` has fifty fields and **none of them are here.** The engine already draws
+ * the line this module needs, in `renderQuality.ts`'s own words about depth of field:
+ *
+ * > A ceiling rather than the effect [...] this says how far a defocused point may spread and
+ * > therefore what the pass may cost, and `setDepthOfField` says where this frame's lens is focused
+ * > and how much of the ceiling it takes. A camera focuses on a subject; a quality profile decides
+ * > how expensive that is allowed to be.
+ *
+ * **A quality profile is the application's and a dial is the game's.** A profile is chosen once,
+ * from what the device can afford, and is clamped by `capabilityClamp` against what the adapter
+ * actually reports; a script that wrote to one would be overruling a decision made about hardware
+ * it cannot see, and two machines running the same script would draw different pictures for
+ * reasons the script did not choose. So this module binds the seven dials and none of the ceilings.
+ *
+ * ## Writes only, and the reason is the same one
+ *
+ * There is no `render.bloomOf` here, and nothing reads a dial back. Every one of these is **clamped
+ * against the ceiling the host set** — `setBloom` does nothing at all when `bloom` is 0, because
+ * the chain is never built — so what a read would answer is a fact about the machine wearing the
+ * costume of a fact about the frame. The language wrote this argument once already, for
+ * `network.read` and a confirmed-input watermark: a host registering a machine-dependent number
+ * under a deterministic effect hands a `@deterministic` system a value that differs between a run
+ * and its replay. A script sets a dial; what the device did with it is the device's business.
+ *
+ * ## The effect, which needed no language release
+ *
+ * **`scene.write`, and it is a description rather than a borrowing.** `capability.ts` puts
+ * `scene.write` outside `DETERMINISTIC_EFFECTS` and says exactly why: *"a `SceneNode` is what
+ * draws, and `ARCHITECTURE.md` forbids render code mutating simulation state, so moving a node is
+ * a change to the view."* Every capability here is a change to the view and nothing else — the
+ * renderers' own comments call these *"a renderer parameter rather than a scene one: it describes
+ * how the finished image is presented, not anything in the world, which is why nothing about the
+ * world has to know it exists."* Two files arriving at the same sentence from opposite ends is the
+ * argument.
+ *
+ * So no capability here is deterministic, and that is the property rather than a limitation: a
+ * `@deterministic` system may not dim the screen. Presentation belongs outside the fixed step,
+ * where the frame is.
+ */
+export const RENDER_TYPES = [
+    {
+        module: RENDER_MODULE,
+        name: 'Renderer',
+        doc: 'The renderer drawing this frame. Reaches a script through `uses`.',
+    },
+];
+const define = (name, params, doc) => defineCapability({
+    module: RENDER_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> void`,
+    params: [...params],
+    returns: 'void',
+    effects: ['scene.write'],
+    deterministic: false,
+    doc,
+    implementation: `${RENDER_MODULE}.${name}`,
+});
+const R = { name: 'renderer', type: 'Renderer' };
+export const RENDER_CAPABILITIES = [
+    define('bloom', [R, { name: 'scale', type: 'f32' }], "How much of the frame's bloom ceiling to take, 0 to 1. Held until changed. Does nothing " +
+        "when the quality profile's `bloom` is 0, because the chain is never built."),
+    define('exposure', [R, { name: 'stops', type: 'f32' }], "How far this frame is scaled into the tone curve, above 0. Replaces the profile's " +
+        '`outputExposure` for this frame onward. Adaptation is yours: a game knows it walked into a ' +
+        'cave, and the renderer could only find out a frame late. Ignored unless the output ' +
+        'transform is `aces`, since otherwise there is no curve to be exposed into.'),
+    define('motionBlur', [R, { name: 'scale', type: 'f32' }], 'How much of the camera motion blur ceiling this frame takes, 0 to 1. Held until changed. ' +
+        'Ramp it with whatever "fast" means here: blur that is always on stops being a speed cue ' +
+        'within seconds and costs eight taps a moving pixel while doing so.'),
+    define('speedBlur', [R, { name: 'strength', type: 'f32' }], 'How much speed blur the frame resolves with, 0 to 1. Held until changed, and ignored when ' +
+        'screen effects are off.'),
+    define('focus', [
+        R,
+        { name: 'distance', type: 'f32' },
+        { name: 'range', type: 'f32' },
+        { name: 'scale', type: 'f32' },
+    ], "Where this frame's lens is focused and how deep the sharp zone is, in metres, and how much " +
+        'of the depth-of-field ceiling to take, 0 to 1. Held until changed. `scale` is required ' +
+        'here though the engine defaults it to 1, because taking the whole ceiling is the expensive ' +
+        'answer and a script author is further from that cost than a TypeScript caller.'),
+    define('medium', [
+        R,
+        { name: 'density', type: 'f32' },
+        { name: 'albedo', type: 'f32' },
+        { name: 'anisotropy', type: 'f32' },
+        { name: 'maxDistance', type: 'f32' },
+    ], 'How thick the air is: a medium filling the whole frustum, rather than a beam inside a hull. ' +
+        '`density` is extinction per metre and 0 is off — nothing is allocated and nothing is drawn, ' +
+        'so a script that never raises it costs nothing. `albedo` is how much of what the air takes ' +
+        'out comes back as light rather than heat, 0 to 1; `anisotropy` is -1 back to 1 forward, and ' +
+        'is what makes haze glow toward a low sun; `maxDistance` is where the search for light to ' +
+        'scatter stops, in metres, which is not where the fog stops. Held until changed. Does ' +
+        "nothing when the quality profile's `globalMediumSteps` is 0, because no march is built."),
+    define('veil', [
+        R,
+        { name: 'red', type: 'f32' },
+        { name: 'green', type: 'f32' },
+        { name: 'blue', type: 'f32' },
+        { name: 'alpha', type: 'f32' },
+    ], 'Composite a flat colour over the finished frame, for a cut dipping to white or to black. ' +
+        '**Once per frame: a frame that does not call this draws with no veil at all**, unlike the ' +
+        'dials above, because a transition that forgets to turn itself off is worse than one that ' +
+        'forgets to turn on.'),
+];
+/**
+ * Unconditional, like `drift/terrain` and `drift/editor`: every capability takes the renderer it
+ * acts on, which reaches a script through `uses`, so there is nothing for an absent service to
+ * make fail.
+ *
+ * **`medium` takes every argument the engine defaults**, unlike `setGlobalMedium`, and for the
+ * reason `focus` gives about its own `scale`: a script author is further from the cost than a
+ * TypeScript caller, and a defaulted albedo is a number somebody has to go and look up before they
+ * can tell what their fog will look like. Four numbers is one line either way.
+ *
+ *  * **`speedBlur` is the one name here that is not the engine's own.** The method is `setSpeedRush`,
+ * and a rush is a thing that happens in somebody's game rather than a description of an image
+ * operation — binding that spelling would have written one consumer's noun into the language's
+ * surface, where it could not later be taken back. A binding is a lookup and this is what a lookup
+ * is for.
+ */
+export function renderImplementation() {
+    return {
+        bloom: (renderer, scale) => renderer.setBloom(scale),
+        exposure: (renderer, stops) => renderer.setOutputExposure(stops),
+        motionBlur: (renderer, scale) => renderer.setCameraMotionBlur(scale),
+        speedBlur: (renderer, strength) => renderer.setSpeedRush(strength),
+        focus: (renderer, distance, range, scale) => renderer.setDepthOfField(distance, range, scale),
+        medium: (renderer, density, albedo, anisotropy, maxDistance) => renderer.setGlobalMedium(density, albedo, anisotropy, maxDistance),
+        veil: (renderer, red, green, blue, alpha) => renderer.setFrameVeil(red, green, blue, alpha),
+    };
+}