@driftengine/texture 4.0.0

package/src/decodeCpu.ts

@@ -0,0 +1,308 @@
+/**
+ * The reference decoder: what the shader has to agree with.
+ *
+ * **A second implementation is not duplication here, it is the specification.** A shader cannot be
+ * unit-tested at speed, and a decoder that is subtly wrong is a picture that is subtly wrong
+ * everywhere — the hardest defect in this whole design to notice and the easiest to ship. So the
+ * arithmetic is written once in TypeScript, where it can be asserted in milliseconds, and the
+ * device copy is checked against it over generated input.
+ *
+ * The repository already takes this position: `splats` authors its shader once and generates the
+ * second backend from it. This is the same discipline where the second copy cannot be generated.
+ *
+ * **Deterministic by construction.** No clock, no random, and `t` is the caller's. Decoding the
+ * same inputs twice is bit-identical, which is what the fingerprint test rests on.
+ */
+import {
+  ADDRESS_MODE,
+  DECODE_OP,
+  MAX_REGISTERS,
+  nodeA,
+  nodeB,
+  nodeOp,
+  nodeOut,
+} from './decodeGraph.ts';
+import type { DecodeGraph } from './decodeGraph.ts';
+import { evalNetwork } from './inference.ts';
+import type { NetworkShape } from './inference.ts';
+import { CHANNEL_SEMANTICS, normaliseSample } from './semantics.ts';
+import type { ChannelSemantic } from './semantics.ts';
+import { flipbookFrame } from './timeNodes.ts';
+
+/** One level of a latent's chain. Components are the image's own. */
+export interface LatentLevel {
+  data: Float32Array;
+  width: number;
+  height: number;
+}
+
+export interface LatentImage {
+  data: Float32Array;
+  width: number;
+  height: number;
+  /** Components per texel, up to four. */
+  channels: number;
+  /**
+   * Levels 1 onward, each half the one before. `mips[k]` is level `k + 1`.
+   *
+   * Absent is a single level, which is every image written before 2026-09-17 — and at `lod` 0 the
+   * chain is never read, so those callers decode exactly what they did.
+   */
+  mips?: readonly LatentLevel[];
+}
+
+export interface DecodeResources {
+  latents: readonly LatentImage[];
+  blocks: readonly LatentImage[];
+  networks: readonly { shape: NetworkShape; weights: Float32Array }[];
+  /**
+   * Four floats per slot, for `CONSTANT`.
+   *
+   * Optional, so every caller written before Wave 4C still type-checks and still runs — a graph
+   * with no constant in it never reads this.
+   */
+  constants?: Float32Array;
+}
+
+/**
+ * The order `REMAP_CHANNEL` packs a semantic in, which is `CHANNEL_SEMANTICS` and not a copy of it.
+ *
+ * **It was a copy until 2026-09-20**, written out again here — the same eleven names in the same
+ * order in two files, with nothing holding them together. That is a list a file's channels are
+ * *numbered* by: the two drifting apart means every material written by one and read by the other
+ * decodes its channels as something else, and a normal map read as roughness inverts every
+ * highlight in a scene. The name is kept because `terrainTexture.ts`, the WGSL interpreter's test
+ * and this file all say `REMAP_SEMANTICS` when they mean the packing.
+ */
+export const REMAP_SEMANTICS: readonly ChannelSemantic[] = CHANNEL_SEMANTICS;
+
+/** Lattice addressing only: where a coordinate lands before it is scaled across the lattice. */
+function address(value: number, mode: number): number {
+  if (mode === ADDRESS_MODE.LATTICE_WRAP) return value - Math.floor(value);
+  return Math.min(1, Math.max(0, value));
+}
+
+/** A texel index inside the image: wrapped for centre wrap, clamped for everything else. */
+function texelIndex(value: number, size: number, mode: number): number {
+  if (mode === ADDRESS_MODE.CENTRE_WRAP) return ((value % size) + size) % size;
+  return Math.min(size - 1, Math.max(0, value));
+}
+
+/**
+ * Bilinear on one level, with the graph's address mode applied first.
+ *
+ * **For the lattice modes this is byte-identical to what it replaced**: `su` is inside
+ * `[0, width - 1]`, so clamping `floor(su)` and `floor(su) + 1` is exactly the `min` it was.
+ */
+function sampleLevel(
+  level: LatentLevel,
+  channels: number,
+  u: number,
+  v: number,
+  mode: number,
+  out: Float32Array,
+): void {
+  const centre = mode === ADDRESS_MODE.CENTRE_CLAMP || mode === ADDRESS_MODE.CENTRE_WRAP;
+  const su = centre ? u * level.width - 0.5 : address(u, mode) * (level.width - 1);
+  const sv = centre ? v * level.height - 0.5 : address(v, mode) * (level.height - 1);
+  const baseX = Math.floor(su);
+  const baseY = Math.floor(sv);
+  const fx = su - baseX;
+  const fy = sv - baseY;
+  const x0 = texelIndex(baseX, level.width, mode);
+  const x1 = texelIndex(baseX + 1, level.width, mode);
+  const y0 = texelIndex(baseY, level.height, mode);
+  const y1 = texelIndex(baseY + 1, level.height, mode);
+  for (let c = 0; c < 4; c += 1) {
+    if (c >= channels) {
+      out[c] = c === 3 ? 1 : 0;
+      continue;
+    }
+    const at = (x: number, y: number) => level.data[(y * level.width + x) * channels + c] as number;
+    const top = at(x0, y0) * (1 - fx) + at(x1, y0) * fx;
+    const bottom = at(x0, y1) * (1 - fx) + at(x1, y1) * fx;
+    out[c] = top * (1 - fy) + bottom * fy;
+  }
+}
+
+const SECOND = new Float32Array(4);
+
+/**
+ * Trilinear: bilinear on the two levels either side of `lod`, mixed by its fraction.
+ *
+ * **At a whole level only that level is read**, so an integer `lod` — and 0 above all — costs and
+ * returns exactly one bilinear sample.
+ */
+function sampleImage(
+  image: LatentImage,
+  u: number,
+  v: number,
+  mode: number,
+  lod: number,
+  out: Float32Array,
+): void {
+  const top = image.mips?.length ?? 0;
+  const level = lod > 0 ? Math.min(lod, top) : 0;
+  const lower = Math.floor(level);
+  const blend = level - lower;
+  const levelOf = (k: number): LatentLevel =>
+    k === 0 ? image : (image.mips?.[k - 1] as LatentLevel);
+  sampleLevel(levelOf(lower), image.channels, u, v, mode, out);
+  if (blend === 0) return;
+  sampleLevel(levelOf(Math.min(lower + 1, top)), image.channels, u, v, mode, SECOND);
+  for (let c = 0; c < 4; c += 1) {
+    out[c] = (out[c] as number) * (1 - blend) + (SECOND[c] as number) * blend;
+  }
+}
+
+/** A deterministic integer hash, so the procedural node reproduces across runs and platforms. */
+function hash2(x: number, y: number, seed: number): number {
+  let h =
+    Math.imul(x | 0, 0x27d4eb2d) ^ Math.imul(y | 0, 0x165667b1) ^ Math.imul(seed | 0, 0x9e3779b1);
+  h = Math.imul(h ^ (h >>> 15), 0x2c1b3c6d);
+  h = Math.imul(h ^ (h >>> 12), 0x297a2d39);
+  return ((h ^ (h >>> 15)) >>> 0) / 0xffffffff;
+}
+
+function valueNoise(u: number, v: number, seed: number): number {
+  const x0 = Math.floor(u);
+  const y0 = Math.floor(v);
+  const fx = u - x0;
+  const fy = v - y0;
+  const sx = fx * fx * (3 - 2 * fx);
+  const sy = fy * fy * (3 - 2 * fy);
+  const a = hash2(x0, y0, seed);
+  const b = hash2(x0 + 1, y0, seed);
+  const c = hash2(x0, y0 + 1, seed);
+  const d = hash2(x0 + 1, y0 + 1, seed);
+  return (a * (1 - sx) + b * sx) * (1 - sy) + (c * (1 - sx) + d * sx) * sy;
+}
+
+const SCRATCH = new Float32Array(256);
+const SAMPLE = new Float32Array(4);
+const NET_IN = new Float32Array(64);
+const NET_OUT = new Float32Array(64);
+
+/**
+ * Run the graph at one texture coordinate and one time, writing four components into `out`.
+ *
+ * `registers` is the caller's, `MAX_REGISTERS * 4` floats, reused so this allocates nothing.
+ * `lod` picks the level a latent is sampled at; 0, and anything that is not a positive number, is
+ * level 0.
+ */
+export function decodeCpu(
+  graph: DecodeGraph,
+  resources: DecodeResources,
+  u: number,
+  v: number,
+  t: number,
+  out: Float32Array,
+  registers: Float32Array,
+  lod = 0,
+): void {
+  for (let i = 0; i < graph.count; i += 1) {
+    const op = nodeOp(graph, i);
+    const a = nodeA(graph, i);
+    const b = nodeB(graph, i);
+    const dst = nodeOut(graph, i) * 4;
+
+    switch (op) {
+      case DECODE_OP.CONSTANT: {
+        const constants = resources.constants;
+        const base = a * 4;
+        for (let c = 0; c < 4; c += 1) registers[dst + c] = constants?.[base + c] ?? 0;
+        break;
+      }
+      case DECODE_OP.SAMPLE_LATENT: {
+        const image = resources.latents[a];
+        if (image === undefined) break;
+        sampleImage(image, u, v, graph.addressMode, lod, SAMPLE);
+        registers.set(SAMPLE, dst);
+        break;
+      }
+      case DECODE_OP.SAMPLE_BLOCK: {
+        const image = resources.blocks[a];
+        if (image === undefined) break;
+        sampleImage(image, u, v, graph.addressMode, lod, SAMPLE);
+        registers.set(SAMPLE, dst);
+        break;
+      }
+      case DECODE_OP.PROCEDURAL_FBM: {
+        let sum = 0;
+        let amplitude = 0.5;
+        let frequency = 1;
+        const octaves = Math.max(1, b);
+        for (let o = 0; o < octaves; o += 1) {
+          sum += valueNoise(u * frequency * 8, v * frequency * 8, a) * amplitude;
+          amplitude *= 0.5;
+          frequency *= 2;
+        }
+        registers[dst] = sum;
+        registers[dst + 1] = sum;
+        registers[dst + 2] = sum;
+        registers[dst + 3] = 1;
+        break;
+      }
+      case DECODE_OP.FLIPBOOK_INDEX: {
+        registers[dst] = flipbookFrame(t, a, b, true);
+        registers[dst + 1] = 0;
+        registers[dst + 2] = 0;
+        registers[dst + 3] = 1;
+        break;
+      }
+      case DECODE_OP.LATENT_LERP: {
+        const mix = t - Math.floor(t);
+        const src0 = a * 4;
+        const src1 = b * 4;
+        for (let c = 0; c < 4; c += 1) {
+          registers[dst + c] =
+            (registers[src0 + c] as number) * (1 - mix) + (registers[src1 + c] as number) * mix;
+        }
+        break;
+      }
+      case DECODE_OP.REMAP_CHANNEL: {
+        const src = a * 4;
+        for (let c = 0; c < 4; c += 1) registers[dst + c] = registers[src + c] as number;
+        const semantic = REMAP_SEMANTICS[b >>> 4] ?? 'mask-linear';
+        const component = b & 0xf;
+        SAMPLE.set(registers.subarray(dst, dst + 4));
+        normaliseSample(SAMPLE, { semantic, component }, registers[src + component] as number);
+        registers.set(SAMPLE, dst);
+        break;
+      }
+      case DECODE_OP.COMPOSITE: {
+        const src0 = a * 4;
+        const src1 = b * 4;
+        const alpha = registers[src0 + 3] as number;
+        for (let c = 0; c < 3; c += 1) {
+          registers[dst + c] =
+            (registers[src0 + c] as number) * alpha + (registers[src1 + c] as number) * (1 - alpha);
+        }
+        registers[dst + 3] = alpha + (registers[src1 + 3] as number) * (1 - alpha);
+        break;
+      }
+      case DECODE_OP.EVAL_NETWORK: {
+        const net = resources.networks[b];
+        if (net === undefined) break;
+        const src = a * 4;
+        for (let c = 0; c < net.shape.inputs; c += 1) {
+          NET_IN[c] = c < 4 ? (registers[src + c] as number) : 0;
+        }
+        evalNetwork(net.shape, net.weights, NET_IN, NET_OUT, SCRATCH);
+        for (let c = 0; c < 4; c += 1) {
+          registers[dst + c] = c < net.shape.outputs ? (NET_OUT[c] as number) : 0;
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  const result = graph.result * 4;
+  for (let c = 0; c < 4; c += 1) out[c] = registers[result + c] as number;
+}
+
+/** A registers array of the right size, for a caller that holds one across calls. */
+export function createDecodeRegisters(): Float32Array {
+  return new Float32Array(MAX_REGISTERS * 4);
+}

package/src/decodeGraph.ts

@@ -0,0 +1,214 @@
+/**
+ * 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,
+} as const;
+
+export type DecodeOp = (typeof DECODE_OP)[keyof typeof DECODE_OP];
+
+/** Whether each operation's `a` and `b` name registers. One table, three readers. */
+const OP_ARGS: Readonly<Record<number, { a: boolean; b: boolean }>> = {
+  [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,
+} as const;
+
+/** 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 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 function createDecodeGraph(capacity: number): DecodeGraph {
+  return { nodes: new Uint32Array(capacity * NODE_STRIDE), count: 0, result: 0, addressMode: 0 };
+}
+
+export function addDecodeNode(
+  graph: DecodeGraph,
+  op: number,
+  a: number,
+  b: number,
+  out: number,
+): number {
+  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: DecodeGraph, index: number): number {
+  return graph.nodes[index * NODE_STRIDE] as number;
+}
+export function nodeA(graph: DecodeGraph, index: number): number {
+  return graph.nodes[index * NODE_STRIDE + 1] as number;
+}
+export function nodeB(graph: DecodeGraph, index: number): number {
+  return graph.nodes[index * NODE_STRIDE + 2] as number;
+}
+export function nodeOut(graph: DecodeGraph, index: number): number {
+  return graph.nodes[index * NODE_STRIDE + 3] as number;
+}
+
+/** The highest register the graph writes, plus one. */
+export function graphRegisterCount(graph: DecodeGraph): number {
+  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: DecodeGraph): string | null {
+  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<number>();
+  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: DecodeGraph): Uint8Array {
+  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: Uint8Array): DecodeGraph {
+  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/src/half.ts

@@ -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: number): number {
+  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: number): number {
+  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: number): number {
+  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: number): number {
+  return fromHalfBits(toHalfBits(value));
+}
+
+/** A whole weight array as half-precision bits, each weight rounded on its own. */
+export function halfWeights(weights: Float32Array): Uint16Array {
+  const out = new Uint16Array(weights.length);
+  for (let i = 0; i < weights.length; i += 1) out[i] = toHalfBits(weights[i] as number);
+  return out;
+}