@driftengine/texture 4.0.0

package/dist/decodeGraph.d.ts

@@ -0,0 +1,105 @@
+/**
+ * A texture's decoder, as data.
+ *
+ * **This is the file where the expensive mistake would be made, so the reasoning is here.** The
+ * decode program is uploaded as a uniform buffer and walked by one shader. There is no code
+ * generation, no `#define`, no shader per material and no variant — because `ARCHITECTURE.md` has
+ * already measured what the other way costs, with the number: a fifth permutation flag took the
+ * generated WGSL corpus from 914 KB to 1,906 KB and cost **196,910 gzipped bytes on every
+ * consumer**, including those who never enabled it, because deflate's window is 32 KB and
+ * near-identical permutations do not deduplicate. A decode graph as permutations would be that
+ * mistake with a far larger exponent — per material rather than per feature.
+ *
+ * As data it costs bytes, linearly, and a new operation is one more case in one switch.
+ *
+ * **A node is four words: op, a, b, out.** Which of `a` and `b` name registers rather than
+ * immediates is a property of the operation, held in `OP_ARGS` so that the validator and both
+ * interpreters read one table rather than three copies of a convention.
+ */
+export declare const DECODE_OP: {
+    /** a = latent slot. Samples it at (u, v). */
+    readonly SAMPLE_LATENT: 0;
+    /** a = register holding the input vector, b = network slot. */
+    readonly EVAL_NETWORK: 1;
+    /** a = block-compressed slot. The passthrough for content a network does not help. */
+    readonly SAMPLE_BLOCK: 2;
+    /** a = seed, b = octaves. */
+    readonly PROCEDURAL_FBM: 3;
+    /** a = frame count, b = frames per second. Writes the frame index into x. */
+    readonly FLIPBOOK_INDEX: 4;
+    /** a, b = registers. Mixes them by the fractional part of the sample time. */
+    readonly LATENT_LERP: 5;
+    /** a = register, b = packed channel spec. Applies the declared convention. */
+    readonly REMAP_CHANNEL: 6;
+    /** a, b = registers. `a` over `b`. */
+    readonly COMPOSITE: 7;
+    /**
+     * a = constant slot. Writes that four-component value.
+     *
+     * **Added for Wave 4C, and the reason is the rule rather than the node.** A material graph
+     * compiles to this vocabulary and not to a shader, so a node the vocabulary cannot express grows
+     * the vocabulary — which costs bytes linearly, because an operation is data. A colour picker is
+     * the first node anybody puts in a material graph and there was nothing here that could hold one.
+     */
+    readonly CONSTANT: 8;
+};
+export type DecodeOp = (typeof DECODE_OP)[keyof typeof DECODE_OP];
+/**
+ * Where a coordinate lands, and what happens outside the unit square.
+ *
+ * **Two conventions, because two kinds of data need them.** A *lattice* puts `u = 0` on the centre
+ * of the first texel and `u = 1` on the centre of the last, which is what a height field sampled at
+ * its own vertices wants — `terrainTexture.ts` reads `x / (width - 1)` and lands on texel `x`
+ * exactly. A *centre* mode puts `u = 0` on the first texel's edge, which is what every GPU sampler
+ * does and what a surface texture tiled across a mesh wants. Added 2026-09-17 so the device
+ * interpreter has a reference to agree with; modes 0 and 1 did not move.
+ *
+ * Lattice wrap has a seam a tiling texture shows: `u = 0.999` reads the last texel and `u = 1`
+ * the first. Centre wrap blends across it, as a repeating sampler does.
+ */
+export declare const ADDRESS_MODE: {
+    readonly LATTICE_CLAMP: 0;
+    readonly LATTICE_WRAP: 1;
+    readonly CENTRE_CLAMP: 2;
+    readonly CENTRE_WRAP: 3;
+};
+/** How many address modes there are. A graph asking for this many or more is refused. */
+export declare const ADDRESS_MODE_COUNT = 4;
+/**
+ * Registers the interpreter has, each a four-component vector.
+ *
+ * A budget rather than a limit discovered on one device: a graph that needs more is refused at
+ * encode time, where a person can see it, rather than compiling to a shader that fails on the
+ * hardware with the smallest uniform space.
+ */
+export declare const MAX_REGISTERS = 16;
+/** Words per node: op, a, b, out. */
+export declare const NODE_STRIDE = 4;
+export interface DecodeGraph {
+    /** Four words per node. */
+    nodes: Uint32Array;
+    count: number;
+    /** Which register holds the finished channel vector. */
+    result: number;
+    /** One of `ADDRESS_MODE`. */
+    addressMode: number;
+}
+export declare function createDecodeGraph(capacity: number): DecodeGraph;
+export declare function addDecodeNode(graph: DecodeGraph, op: number, a: number, b: number, out: number): number;
+export declare function nodeOp(graph: DecodeGraph, index: number): number;
+export declare function nodeA(graph: DecodeGraph, index: number): number;
+export declare function nodeB(graph: DecodeGraph, index: number): number;
+export declare function nodeOut(graph: DecodeGraph, index: number): number;
+/** The highest register the graph writes, plus one. */
+export declare function graphRegisterCount(graph: DecodeGraph): number;
+/**
+ * Whether this graph is one an interpreter can run.
+ *
+ * Returns a message rather than throwing, matching `validateGraph` in the frame package and for
+ * the same reason: whether a malformed graph is an assertion or a skipped material is the
+ * caller's decision.
+ */
+export declare function validateDecodeGraph(graph: DecodeGraph): string | null;
+/** `count`, `result`, `addressMode`, then the nodes. */
+export declare function encodeDecodeGraph(graph: DecodeGraph): Uint8Array;
+export declare function decodeDecodeGraph(bytes: Uint8Array): DecodeGraph;

package/dist/decodeGraph.js

@@ -0,0 +1,180 @@
+/**
+ * A texture's decoder, as data.
+ *
+ * **This is the file where the expensive mistake would be made, so the reasoning is here.** The
+ * decode program is uploaded as a uniform buffer and walked by one shader. There is no code
+ * generation, no `#define`, no shader per material and no variant — because `ARCHITECTURE.md` has
+ * already measured what the other way costs, with the number: a fifth permutation flag took the
+ * generated WGSL corpus from 914 KB to 1,906 KB and cost **196,910 gzipped bytes on every
+ * consumer**, including those who never enabled it, because deflate's window is 32 KB and
+ * near-identical permutations do not deduplicate. A decode graph as permutations would be that
+ * mistake with a far larger exponent — per material rather than per feature.
+ *
+ * As data it costs bytes, linearly, and a new operation is one more case in one switch.
+ *
+ * **A node is four words: op, a, b, out.** Which of `a` and `b` name registers rather than
+ * immediates is a property of the operation, held in `OP_ARGS` so that the validator and both
+ * interpreters read one table rather than three copies of a convention.
+ */
+export const DECODE_OP = {
+    /** a = latent slot. Samples it at (u, v). */
+    SAMPLE_LATENT: 0,
+    /** a = register holding the input vector, b = network slot. */
+    EVAL_NETWORK: 1,
+    /** a = block-compressed slot. The passthrough for content a network does not help. */
+    SAMPLE_BLOCK: 2,
+    /** a = seed, b = octaves. */
+    PROCEDURAL_FBM: 3,
+    /** a = frame count, b = frames per second. Writes the frame index into x. */
+    FLIPBOOK_INDEX: 4,
+    /** a, b = registers. Mixes them by the fractional part of the sample time. */
+    LATENT_LERP: 5,
+    /** a = register, b = packed channel spec. Applies the declared convention. */
+    REMAP_CHANNEL: 6,
+    /** a, b = registers. `a` over `b`. */
+    COMPOSITE: 7,
+    /**
+     * a = constant slot. Writes that four-component value.
+     *
+     * **Added for Wave 4C, and the reason is the rule rather than the node.** A material graph
+     * compiles to this vocabulary and not to a shader, so a node the vocabulary cannot express grows
+     * the vocabulary — which costs bytes linearly, because an operation is data. A colour picker is
+     * the first node anybody puts in a material graph and there was nothing here that could hold one.
+     */
+    CONSTANT: 8,
+};
+/** Whether each operation's `a` and `b` name registers. One table, three readers. */
+const OP_ARGS = {
+    [DECODE_OP.SAMPLE_LATENT]: { a: false, b: false },
+    [DECODE_OP.EVAL_NETWORK]: { a: true, b: false },
+    [DECODE_OP.SAMPLE_BLOCK]: { a: false, b: false },
+    [DECODE_OP.PROCEDURAL_FBM]: { a: false, b: false },
+    [DECODE_OP.FLIPBOOK_INDEX]: { a: false, b: false },
+    [DECODE_OP.LATENT_LERP]: { a: true, b: true },
+    [DECODE_OP.REMAP_CHANNEL]: { a: true, b: false },
+    [DECODE_OP.COMPOSITE]: { a: true, b: true },
+    [DECODE_OP.CONSTANT]: { a: false, b: false },
+};
+/**
+ * Where a coordinate lands, and what happens outside the unit square.
+ *
+ * **Two conventions, because two kinds of data need them.** A *lattice* puts `u = 0` on the centre
+ * of the first texel and `u = 1` on the centre of the last, which is what a height field sampled at
+ * its own vertices wants — `terrainTexture.ts` reads `x / (width - 1)` and lands on texel `x`
+ * exactly. A *centre* mode puts `u = 0` on the first texel's edge, which is what every GPU sampler
+ * does and what a surface texture tiled across a mesh wants. Added 2026-09-17 so the device
+ * interpreter has a reference to agree with; modes 0 and 1 did not move.
+ *
+ * Lattice wrap has a seam a tiling texture shows: `u = 0.999` reads the last texel and `u = 1`
+ * the first. Centre wrap blends across it, as a repeating sampler does.
+ */
+export const ADDRESS_MODE = {
+    LATTICE_CLAMP: 0,
+    LATTICE_WRAP: 1,
+    CENTRE_CLAMP: 2,
+    CENTRE_WRAP: 3,
+};
+/** How many address modes there are. A graph asking for this many or more is refused. */
+export const ADDRESS_MODE_COUNT = 4;
+/**
+ * Registers the interpreter has, each a four-component vector.
+ *
+ * A budget rather than a limit discovered on one device: a graph that needs more is refused at
+ * encode time, where a person can see it, rather than compiling to a shader that fails on the
+ * hardware with the smallest uniform space.
+ */
+export const MAX_REGISTERS = 16;
+/** Words per node: op, a, b, out. */
+export const NODE_STRIDE = 4;
+export function createDecodeGraph(capacity) {
+    return { nodes: new Uint32Array(capacity * NODE_STRIDE), count: 0, result: 0, addressMode: 0 };
+}
+export function addDecodeNode(graph, op, a, b, out) {
+    const at = graph.count * NODE_STRIDE;
+    graph.nodes[at] = op;
+    graph.nodes[at + 1] = a;
+    graph.nodes[at + 2] = b;
+    graph.nodes[at + 3] = out;
+    graph.count += 1;
+    return graph.count - 1;
+}
+export function nodeOp(graph, index) {
+    return graph.nodes[index * NODE_STRIDE];
+}
+export function nodeA(graph, index) {
+    return graph.nodes[index * NODE_STRIDE + 1];
+}
+export function nodeB(graph, index) {
+    return graph.nodes[index * NODE_STRIDE + 2];
+}
+export function nodeOut(graph, index) {
+    return graph.nodes[index * NODE_STRIDE + 3];
+}
+/** The highest register the graph writes, plus one. */
+export function graphRegisterCount(graph) {
+    let highest = graph.result;
+    for (let i = 0; i < graph.count; i += 1)
+        highest = Math.max(highest, nodeOut(graph, i));
+    return highest + 1;
+}
+/**
+ * Whether this graph is one an interpreter can run.
+ *
+ * Returns a message rather than throwing, matching `validateGraph` in the frame package and for
+ * the same reason: whether a malformed graph is an assertion or a skipped material is the
+ * caller's decision.
+ */
+export function validateDecodeGraph(graph) {
+    if (!Number.isInteger(graph.addressMode) ||
+        graph.addressMode < 0 ||
+        graph.addressMode >= ADDRESS_MODE_COUNT) {
+        return `address mode ${graph.addressMode} is not one of the ${ADDRESS_MODE_COUNT} the interpreter knows`;
+    }
+    const written = new Set();
+    for (let i = 0; i < graph.count; i += 1) {
+        const op = nodeOp(graph, i);
+        const args = OP_ARGS[op];
+        if (args === undefined)
+            return `node ${i} has unknown opcode ${op}`;
+        const out = nodeOut(graph, i);
+        if (out >= MAX_REGISTERS) {
+            return `node ${i} writes register ${out}, past the ${MAX_REGISTERS} the interpreter has`;
+        }
+        if (args.a && !written.has(nodeA(graph, i))) {
+            return `node ${i} reads register ${nodeA(graph, i)}, which nothing wrote`;
+        }
+        if (args.b && !written.has(nodeB(graph, i))) {
+            return `node ${i} reads register ${nodeB(graph, i)}, which nothing wrote`;
+        }
+        written.add(out);
+    }
+    if (!written.has(graph.result)) {
+        return `the result register ${graph.result} is never written`;
+    }
+    if (graphRegisterCount(graph) > MAX_REGISTERS) {
+        return `the graph needs ${graphRegisterCount(graph)} registers, past the ${MAX_REGISTERS} available`;
+    }
+    return null;
+}
+/** `count`, `result`, `addressMode`, then the nodes. */
+export function encodeDecodeGraph(graph) {
+    const bytes = new Uint8Array(12 + graph.count * NODE_STRIDE * 4);
+    const view = new DataView(bytes.buffer);
+    view.setUint32(0, graph.count, true);
+    view.setUint32(4, graph.result, true);
+    view.setUint32(8, graph.addressMode, true);
+    new Uint32Array(bytes.buffer, 12, graph.count * NODE_STRIDE).set(graph.nodes.subarray(0, graph.count * NODE_STRIDE));
+    return bytes;
+}
+export function decodeDecodeGraph(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const count = view.getUint32(0, true);
+    const graph = createDecodeGraph(Math.max(1, count));
+    graph.count = count;
+    graph.result = view.getUint32(4, true);
+    graph.addressMode = view.getUint32(8, true);
+    for (let i = 0; i < count * NODE_STRIDE; i += 1) {
+        graph.nodes[i] = view.getUint32(12 + i * 4, true);
+    }
+    return graph;
+}

package/dist/half.d.ts

@@ -0,0 +1,24 @@
+/**
+ * IEEE 754 binary16 — half precision — on a platform that has no type for it.
+ *
+ * **The half-precision network path needs a reference, and the reference needs this.** A shader
+ * declared `enable f16` computes in sixteen bits, and the only way to say what it should have
+ * produced is to round the same arithmetic to the same sixteen bits here. Node 22 has no
+ * `Float16Array` and no `Math.f16round`, so the rounding is written out: one sign bit, five exponent
+ * bits biased by fifteen, ten mantissa bits, ties to even, overflow to infinity.
+ *
+ * **What the format cannot hold is the reason the path is optional.** The largest finite value is
+ * 65,504 and the smallest normal one is 2^-14, so a network whose activations leave that range is
+ * wrong in half precision in a way no tolerance covers — `activationBound` in `inference.ts` is what
+ * a consumer asks before choosing it.
+ */
+/** The largest finite half-precision value. */
+export declare const HALF_MAX = 65504;
+/** The sixteen bits a value rounds to, as an unsigned integer. */
+export declare function toHalfBits(value: number): number;
+/** The value sixteen bits hold. */
+export declare function fromHalfBits(bits: number): number;
+/** The nearest half-precision value, as a number. */
+export declare function roundHalf(value: number): number;
+/** A whole weight array as half-precision bits, each weight rounded on its own. */
+export declare function halfWeights(weights: Float32Array): Uint16Array;

package/dist/half.js

@@ -0,0 +1,86 @@
+/**
+ * IEEE 754 binary16 — half precision — on a platform that has no type for it.
+ *
+ * **The half-precision network path needs a reference, and the reference needs this.** A shader
+ * declared `enable f16` computes in sixteen bits, and the only way to say what it should have
+ * produced is to round the same arithmetic to the same sixteen bits here. Node 22 has no
+ * `Float16Array` and no `Math.f16round`, so the rounding is written out: one sign bit, five exponent
+ * bits biased by fifteen, ten mantissa bits, ties to even, overflow to infinity.
+ *
+ * **What the format cannot hold is the reason the path is optional.** The largest finite value is
+ * 65,504 and the smallest normal one is 2^-14, so a network whose activations leave that range is
+ * wrong in half precision in a way no tolerance covers — `activationBound` in `inference.ts` is what
+ * a consumer asks before choosing it.
+ */
+/** The largest finite half-precision value. */
+export const HALF_MAX = 65504;
+/* One scratch view, so reading a double's exponent allocates nothing. */
+const BITS = new DataView(new ArrayBuffer(8));
+/*
+ * Round to the nearest integer, a tie to the even one. `Math.round` rounds a tie up, which is not
+ * what any floating-point format does and would make every tie in the tests an error of one unit.
+ */
+function roundEven(value) {
+    const floor = Math.floor(value);
+    const fraction = value - floor;
+    if (fraction > 0.5)
+        return floor + 1;
+    if (fraction < 0.5)
+        return floor;
+    return floor % 2 === 0 ? floor : floor + 1;
+}
+/** The sixteen bits a value rounds to, as an unsigned integer. */
+export function toHalfBits(value) {
+    if (Number.isNaN(value))
+        return 0x7e00;
+    const sign = value < 0 || Object.is(value, -0) ? 0x8000 : 0;
+    const magnitude = Math.abs(value);
+    if (magnitude < 2 ** -14) {
+        /*
+         * Subnormal: the value in units of 2^-24, which is the mantissa directly. A result of 1,024 is
+         * the smallest normal value, and its bits are exactly 1,024 — the carry is free.
+         */
+        return sign | roundEven(magnitude * 2 ** 24);
+    }
+    /*
+     * The exponent from the double's own bits rather than from `Math.log2`, which the language
+     * leaves approximate — exact here, because every magnitude this far down the function is a normal
+     * double.
+     */
+    BITS.setFloat64(0, magnitude);
+    let exponent = ((BITS.getUint16(0) >> 4) & 0x7ff) - 1023;
+    let mantissa = roundEven((magnitude / 2 ** exponent - 1) * 1024);
+    if (mantissa === 1024) {
+        mantissa = 0;
+        exponent += 1;
+    }
+    /*
+     * Overflow is decided here and only here. 65,520 is halfway between the largest finite value and
+     * 2^16, its mantissa rounds up to the carry above, and the exponent it lands on is 16.
+     */
+    if (exponent > 15)
+        return sign | 0x7c00;
+    return sign | ((exponent + 15) << 10) | mantissa;
+}
+/** The value sixteen bits hold. */
+export function fromHalfBits(bits) {
+    const sign = (bits & 0x8000) !== 0 ? -1 : 1;
+    const exponent = (bits >> 10) & 0x1f;
+    const mantissa = bits & 0x03ff;
+    if (exponent === 0)
+        return sign * mantissa * 2 ** -24;
+    if (exponent === 0x1f)
+        return mantissa === 0 ? sign * Infinity : Number.NaN;
+    return sign * (1 + mantissa / 1024) * 2 ** (exponent - 15);
+}
+/** The nearest half-precision value, as a number. */
+export function roundHalf(value) {
+    return fromHalfBits(toHalfBits(value));
+}
+/** A whole weight array as half-precision bits, each weight rounded on its own. */
+export function halfWeights(weights) {
+    const out = new Uint16Array(weights.length);
+    for (let i = 0; i < weights.length; i += 1)
+        out[i] = toHalfBits(weights[i]);
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * DriftTexture: a texture as a compiled, sampled field rather than an image.
+ *
+ * Every engine in the world treats a texture as a bag of texels. This one treats it as a small
+ * program sampled at `(uv, t, params)` — one object per *material* rather than per channel,
+ * carrying every channel, every level and its own decoder.
+ *
+ * Three consequences fall out of that shape and none of them is available to an image:
+ *
+ * - **Channels compress together**, because they are correlated and compressing them apart throws
+ *   that correlation away.
+ * - **Time is an argument, not a clock**, so an animated texture sampled at simulation time is
+ *   byte-exact under replay — which no other engine's animated texture can claim.
+ * - **The decoder is data walked by one shader**, never a permutation. `ARCHITECTURE.md` measured
+ *   what the other way costs at 196,910 gzipped bytes for a single flag.
+ *
+ * What ships here is the format, the reference decode, the material binding, predictive
+ * residency and the writable overlay. The device interpreter the GPU-driven pipeline samples with
+ * is `@driftengine/core`'s, checked against `decodeCpu` by `scripts/gpu-parity.mjs`.
+ */
+export { CHANNEL_SEMANTICS, isColour, linearToSrgb, needsVarianceMips, normaliseSample, semanticAt, semanticIndex, srgbToLinear, } from './semantics.ts';
+export type { ChannelSemantic, ChannelSpec } from './semantics.ts';
+export { reduceNormalMip, toksvigRoughness } from './mipNdf.ts';
+export { createTileIndex, hashTile, internTile, tileSlotCount } from './tileHash.ts';
+export type { TileIndex } from './tileHash.ts';
+export { activationBound, evalNetwork, evalNetworkHalf, halfPrecisionErrorBound, networkWeightCount, } from './inference.ts';
+export { HALF_MAX, fromHalfBits, halfWeights, roundHalf, toHalfBits } from './half.ts';
+export { addBias, erf, gelu, layerNorm, matmul, softmax } from './tensor/linear.ts';
+export { attention } from './tensor/attention.ts';
+export { resize } from './tensor/resize.ts';
+export { conv2d, convTranspose2d, maxPool2d, patchEmbed } from './tensor/spatial.ts';
+export { createGraphEvaluator, graphForDevice, graphFromStored, graphShapes, validateGraph, } from './tensor/graph.ts';
+export { CONSTANT_PREFIX, graphFromWeights } from './tensor/architecture.ts';
+export type { Architecture, GraphBuilder, WeightSource, Weights } from './tensor/architecture.ts';
+export type { GraphEvaluator, GraphNode, GraphTensor, GraphValue, NetworkGraph, StoredGraph, } from './tensor/graph.ts';
+export { OPERATORS } from './tensor/operators.ts';
+export type { AttributeValue, Attributes, Operator } from './tensor/operators.ts';
+export type { NetworkShape } from './inference.ts';
+export { flipbookFrame, latentLerpWeights } from './timeNodes.ts';
+export type { LerpWeights } from './timeNodes.ts';
+export { ADDRESS_MODE, ADDRESS_MODE_COUNT, DECODE_OP, MAX_REGISTERS, NODE_STRIDE, addDecodeNode, createDecodeGraph, decodeDecodeGraph, encodeDecodeGraph, graphRegisterCount, nodeA, nodeB, nodeOp, nodeOut, validateDecodeGraph, } from './decodeGraph.ts';
+export type { DecodeGraph, DecodeOp } from './decodeGraph.ts';
+export { REMAP_SEMANTICS, createDecodeRegisters, decodeCpu } from './decodeCpu.ts';
+export type { DecodeResources, LatentImage, LatentLevel } from './decodeCpu.ts';
+export { progressiveOrder, usableAt } from './progressive.ts';
+export { arrayDescriptor, assignLayer, createMaterialArray, layerOf } from './materialArray.ts';
+export type { MaterialArray } from './materialArray.ts';
+export { predictViews } from './residency/predict.ts';
+export type { SimulationHandle } from './residency/predict.ts';
+export { TILE_ABSENT, TILE_REQUESTED, TILE_RESIDENT, createResidencyTable, evict, leastRecentlyUsed, markRequested, markResident, residentCount, slotFor, tileState, touchTile, } from './residency/table.ts';
+export type { ResidencyTable } from './residency/table.ts';
+export { createPrefetchQueue, enqueue, queueSize, takeBatch } from './residency/queue.ts';
+export type { PrefetchQueue } from './residency/queue.ts';
+export { acquirePage, beginCacheFrame, createPageCache, decodeMode, ensurePageDecoded, occupiedPages, pageDecoded, pageSlot, releasePage, setDecodeMode, takeEvicted, } from './residency/pageCache.ts';
+export type { DecodeMode, PageCache, PageCacheOptions, PageDecode } from './residency/pageCache.ts';
+export { clearMissing, createStreamer, forgetMissing, pumpStreamer, streamerInFlight, } from './residency/stream.ts';
+export type { Streamer, StreamerOptions, TileSource } from './residency/stream.ts';
+export { ADDRESS_CLAMP, ADDRESS_WRAP, OVERLAY_CHANNELS, compositeOverlay, createOverlay, overlayTileCount, overlayTiles, sampleOverlay, writeOverlay, writtenMaskAt, } from './overlay/sparse.ts';
+export type { Overlay, OverlayOptions, OverlayTile } from './overlay/sparse.ts';
+export { JOURNAL_ENTRY_BYTES, JOURNAL_MAGIC, JOURNAL_VERSION, applyOverlayJournal, clearOverlay, createOverlayJournal, decodeOverlayJournal, emptyLike, encodeOverlayJournal, journalLength, recordOverlayWrite, rewindOverlay, truncateJournalFrom, } from './overlay/journal.ts';
+export type { OverlayJournal } from './overlay/journal.ts';
+export { runPrediction } from './residency/predictor.ts';
+export { LEVEL_MARGIN, latentTileGrid, tilesForView } from './residency/viewTiles.ts';
+export type { InstanceTileInfo, MaterialTileGrid } from './residency/viewTiles.ts';
+export type { Predictor } from './residency/predictor.ts';

package/dist/index.js

@@ -0,0 +1,55 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * DriftTexture: a texture as a compiled, sampled field rather than an image.
+ *
+ * Every engine in the world treats a texture as a bag of texels. This one treats it as a small
+ * program sampled at `(uv, t, params)` — one object per *material* rather than per channel,
+ * carrying every channel, every level and its own decoder.
+ *
+ * Three consequences fall out of that shape and none of them is available to an image:
+ *
+ * - **Channels compress together**, because they are correlated and compressing them apart throws
+ *   that correlation away.
+ * - **Time is an argument, not a clock**, so an animated texture sampled at simulation time is
+ *   byte-exact under replay — which no other engine's animated texture can claim.
+ * - **The decoder is data walked by one shader**, never a permutation. `ARCHITECTURE.md` measured
+ *   what the other way costs at 196,910 gzipped bytes for a single flag.
+ *
+ * What ships here is the format, the reference decode, the material binding, predictive
+ * residency and the writable overlay. The device interpreter the GPU-driven pipeline samples with
+ * is `@driftengine/core`'s, checked against `decodeCpu` by `scripts/gpu-parity.mjs`.
+ */
+export { CHANNEL_SEMANTICS, isColour, linearToSrgb, needsVarianceMips, normaliseSample, semanticAt, semanticIndex, srgbToLinear, } from './semantics.js';
+export { reduceNormalMip, toksvigRoughness } from './mipNdf.js';
+export { createTileIndex, hashTile, internTile, tileSlotCount } from './tileHash.js';
+export { activationBound, evalNetwork, evalNetworkHalf, halfPrecisionErrorBound, networkWeightCount, } from './inference.js';
+export { HALF_MAX, fromHalfBits, halfWeights, roundHalf, toHalfBits } from './half.js';
+/*
+ * The operators a small transformer is built from, as references the device kernels are held to:
+ * the second half of the one inference runtime, beside the perceptron's evaluation above.
+ */
+export { addBias, erf, gelu, layerNorm, matmul, softmax } from './tensor/linear.js';
+export { attention } from './tensor/attention.js';
+export { resize } from './tensor/resize.js';
+export { conv2d, convTranspose2d, maxPool2d, patchEmbed } from './tensor/spatial.js';
+export { createGraphEvaluator, graphForDevice, graphFromStored, graphShapes, validateGraph, } from './tensor/graph.js';
+export { CONSTANT_PREFIX, graphFromWeights } from './tensor/architecture.js';
+export { OPERATORS } from './tensor/operators.js';
+export { flipbookFrame, latentLerpWeights } from './timeNodes.js';
+export { ADDRESS_MODE, ADDRESS_MODE_COUNT, DECODE_OP, MAX_REGISTERS, NODE_STRIDE, addDecodeNode, createDecodeGraph, decodeDecodeGraph, encodeDecodeGraph, graphRegisterCount, nodeA, nodeB, nodeOp, nodeOut, validateDecodeGraph, } from './decodeGraph.js';
+export { REMAP_SEMANTICS, createDecodeRegisters, decodeCpu } from './decodeCpu.js';
+export { progressiveOrder, usableAt } from './progressive.js';
+export { arrayDescriptor, assignLayer, createMaterialArray, layerOf } from './materialArray.js';
+/*
+ * Predictive residency: the half that needs the simulation's save and restore rather than the
+ * renderer. See `residency/predict.ts` for why looking ahead is available here and nowhere else.
+ */
+export { predictViews } from './residency/predict.js';
+export { TILE_ABSENT, TILE_REQUESTED, TILE_RESIDENT, createResidencyTable, evict, leastRecentlyUsed, markRequested, markResident, residentCount, slotFor, tileState, touchTile, } from './residency/table.js';
+export { createPrefetchQueue, enqueue, queueSize, takeBatch } from './residency/queue.js';
+export { acquirePage, beginCacheFrame, createPageCache, decodeMode, ensurePageDecoded, occupiedPages, pageDecoded, pageSlot, releasePage, setDecodeMode, takeEvicted, } from './residency/pageCache.js';
+export { clearMissing, createStreamer, forgetMissing, pumpStreamer, streamerInFlight, } from './residency/stream.js';
+export { ADDRESS_CLAMP, ADDRESS_WRAP, OVERLAY_CHANNELS, compositeOverlay, createOverlay, overlayTileCount, overlayTiles, sampleOverlay, writeOverlay, writtenMaskAt, } from './overlay/sparse.js';
+export { JOURNAL_ENTRY_BYTES, JOURNAL_MAGIC, JOURNAL_VERSION, applyOverlayJournal, clearOverlay, createOverlayJournal, decodeOverlayJournal, emptyLike, encodeOverlayJournal, journalLength, recordOverlayWrite, rewindOverlay, truncateJournalFrom, } from './overlay/journal.js';
+export { runPrediction } from './residency/predictor.js';
+export { LEVEL_MARGIN, latentTileGrid, tilesForView } from './residency/viewTiles.js';

package/dist/inference.d.ts

@@ -0,0 +1,53 @@
+export interface NetworkShape {
+    readonly inputs: number;
+    readonly hidden: readonly number[];
+    readonly outputs: number;
+}
+/** How many weights and biases a shape needs, laid out layer by layer. */
+export declare function networkWeightCount(shape: NetworkShape): number;
+/**
+ * Evaluate the network, writing `shape.outputs` values into `out`.
+ *
+ * Weights are read in layer order: for each layer, the weight matrix row-major by output, then the
+ * biases. `scratch` must hold at least twice the widest layer and is reused across calls so this
+ * allocates nothing.
+ */
+export declare function evalNetwork(shape: NetworkShape, weights: Float32Array, input: Float32Array, out: Float32Array, scratch: Float32Array): void;
+/**
+ * How far the half-precision evaluation of this network, at this input, can sit from the
+ * single-precision one.
+ *
+ * **A bound per network rather than one tolerance for all**, because a sampled tolerance is a claim
+ * about the corpus that sampled it — 2,400 networks put the worst relative error at 0.00213, the
+ * device's own corpus reached 0.0039, and 40,000 reached 0.0066. This carries the error instead:
+ * the weights' and the input's own rounding exactly, then half a unit in the last place for every
+ * product, every partial sum and the bias, through each layer — a rectifier moves no error, since
+ * it is one-Lipschitz. **It holds whichever form a device computes**: every operation rounded, or
+ * each multiply-add contracted into a single rounding, which WGSL permits and this project's
+ * development machine does. It assumes no value overflows, which `activationBound` is for.
+ */
+export declare function halfPrecisionErrorBound(shape: NetworkShape, weights: Float32Array, input: Float32Array): number;
+/**
+ * Evaluate the network as a device with `enable f16` would, writing `shape.outputs` values into
+ * `out`.
+ *
+ * **Every multiply and every add is rounded**, because that is what a sixteen-bit adder does, and
+ * the arithmetic is in doubles so the rounding is the only approximation. The order is the
+ * device's: the weighted inputs summed in index order, then the bias, then the rectifier —
+ * `render/shaders/network.wgsl.ts` in `@driftengine/core` is written to match it.
+ *
+ * `weights` are half-precision bits, as `halfWeights` produces and an `NNET` chunk stores. Inputs
+ * are rounded to half precision on the way in. `scratch` holds at least twice the widest layer.
+ */
+export declare function evalNetworkHalf(shape: NetworkShape, weights: Uint16Array, input: Float32Array, out: Float32Array, scratch: Float64Array, contract?: boolean): void;
+/**
+ * The largest magnitude any product, partial sum or output of the network can reach over the given
+ * input box.
+ *
+ * **What a consumer asks before it chooses half precision.** Past 65,504 the format has no finite
+ * value, and a partial sum can pass that on its way to a total that does not — so this bounds each
+ * neuron by its bias plus the sum of every weight times the largest magnitude its input can take,
+ * which covers every prefix of the sum at once. Intervals are carried through the layers, and a
+ * rectifier clips them, which is what keeps the bound from growing without cause.
+ */
+export declare function activationBound(shape: NetworkShape, weights: Float32Array, low: Float32Array, high: Float32Array): number;