@driftengine/ui2d 3.61.0

package/dist/uiNode.js

@@ -0,0 +1,79 @@
+/** A node of the retained interface tree: what it is, where it wants to be, and what it draws. */
+function rgba(source) {
+    if (source === null || source === undefined)
+        return null;
+    const out = new Float32Array(4);
+    out[0] = source[0];
+    out[1] = source[1];
+    out[2] = source[2];
+    out[3] = (source[3] ?? 1);
+    return out;
+}
+export function createUiNode(options = {}) {
+    const padding = options.padding ?? 0;
+    return {
+        children: [],
+        parent: null,
+        direction: options.direction ?? 'column',
+        width: options.width ?? 'fit',
+        height: options.height ?? 'fit',
+        paddingLeft: padding,
+        paddingTop: padding,
+        paddingRight: padding,
+        paddingBottom: padding,
+        gap: options.gap ?? 0,
+        align: options.align ?? 'start',
+        justify: options.justify ?? 'start',
+        absolute: options.absolute ?? false,
+        x: options.x ?? 0,
+        y: options.y ?? 0,
+        contentWidth: options.contentWidth ?? 0,
+        contentHeight: options.contentHeight ?? 0,
+        hidden: options.hidden ?? false,
+        rect: { x: 0, y: 0, w: 0, h: 0 },
+        measuredWidth: 0,
+        measuredHeight: 0,
+        background: rgba(options.background),
+        texture: options.texture ?? -1,
+        frame: options.frame ?? null,
+        tint: rgba(options.tint),
+        text: options.text ?? '',
+        interactive: options.interactive ?? false,
+        focusable: options.focusable ?? false,
+        hovered: false,
+        pressed: false,
+        name: options.name ?? '',
+    };
+}
+/** Put `child` at the end of `parent`'s children, detaching it from wherever it was. */
+export function addUiChild(parent, child) {
+    if (child.parent !== null)
+        removeUiChild(child.parent, child);
+    child.parent = parent;
+    parent.children.push(child);
+    return child;
+}
+/** Take `child` out of `parent`. A child that is not there is left alone. */
+export function removeUiChild(parent, child) {
+    const at = parent.children.indexOf(child);
+    if (at < 0)
+        return;
+    parent.children.splice(at, 1);
+    child.parent = null;
+}
+/** The node named, depth-first from `root`, or `null`. For a caller finding its own tree again. */
+export function uiNodeNamed(root, name) {
+    if (root.name === name)
+        return root;
+    for (const child of root.children) {
+        const hit = uiNodeNamed(child, name);
+        if (hit !== null)
+            return hit;
+    }
+    return null;
+}
+/** Whether a point is inside a node's resolved box. */
+export function uiRectHolds(node, x, y) {
+    const r = node.rect;
+    return x >= r.x && x < r.x + r.w && y >= r.y && y < r.y + r.h;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@driftengine/ui2d",
+  "version": "3.61.0",
+  "description": "The 2D layer: batched sprites, sheets, tilemaps, and a retained interface tree over them",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "drift-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.mjs",
+    "!src/**/__snapshots__",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@driftengine/core": "3.61.0"
+  },
+  "author": "Drift Technologies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drftrun/driftengine.git",
+    "directory": "packages/ui2d"
+  },
+  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "bugs": "https://github.com/drftrun/driftengine/issues",
+  "keywords": [
+    "driftengine",
+    "3d",
+    "webgl",
+    "webgpu",
+    "typescript",
+    "sprites",
+    "tilemap",
+    "user-interface",
+    "layout"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/camera2d.ts

@@ -0,0 +1,88 @@
+/** The affine that takes a point in a 2D world, or a CSS pixel, to normalised device coordinates. */
+
+/**
+ * Six numbers, laid out the way a 2D graphics API has laid them out for thirty years:
+ *
+ * ```
+ * ndc.x = m[0] * x + m[2] * y + m[4]
+ * ndc.y = m[1] * x + m[3] * y + m[5]
+ * ```
+ *
+ * A `Float32Array` rather than six fields because it is uploaded as two `vec4`s and read by the
+ * vertex stage every frame; an object would be repacked on the way.
+ */
+export type Affine2D = Float32Array;
+
+export function createAffine2D(): Affine2D {
+  return new Float32Array(6);
+}
+
+/** A 2D camera: where it is, how far in, and which way up. */
+export interface Camera2D {
+  /** World units. The point that lands on the middle of the viewport. */
+  readonly x: number;
+  readonly y: number;
+  /**
+   * Pixels per world unit, and it is the same on both axes on purpose.
+   *
+   * A separate x and y zoom is a non-uniform scale, which turns a circle into an ellipse and a
+   * square tile into a rectangle — the caller who wants that has asked for a stretched picture and
+   * can say so in the sprite's own size, where it is visible.
+   */
+  readonly zoom: number;
+  /** Radians, anticlockwise. The world turns the other way; see `worldToNdc`. */
+  readonly rotation?: number;
+}
+
+/**
+ * The affine for a 2D world seen through a camera.
+ *
+ * **y counts upward**, which is the opposite of `screenToNdc` below and is deliberate: a 2D world is
+ * a world, and a caller placing a platform above a floor should not have to subtract. A screen-space
+ * overlay is the other convention because that is the one every layout system already uses, and the
+ * two are different enough that sharing one would make each caller wrong half the time.
+ *
+ * Rotation turns the *camera*, so the world turns the other way: at `rotation = +π/2` the camera has
+ * tilted its head anticlockwise and what was to its right is now above it.
+ */
+export function worldToNdc(
+  camera: Camera2D,
+  viewportWidth: number,
+  viewportHeight: number,
+  out: Affine2D,
+): Affine2D {
+  const rotation = camera.rotation ?? 0;
+  const cos = Math.cos(rotation);
+  const sin = Math.sin(rotation);
+  const perPixelX = 2 / viewportWidth;
+  const perPixelY = 2 / viewportHeight;
+  const a = camera.zoom * cos * perPixelX;
+  const c = camera.zoom * sin * perPixelX;
+  const b = -camera.zoom * sin * perPixelY;
+  const d = camera.zoom * cos * perPixelY;
+  out[0] = a;
+  out[1] = b;
+  out[2] = c;
+  out[3] = d;
+  out[4] = -(a * camera.x + c * camera.y);
+  out[5] = -(b * camera.x + d * camera.y);
+  return out;
+}
+
+/**
+ * The affine for CSS pixels with a top-left origin — the convention `InsetRect` and `fillPanel`
+ * already use, and the one a caller laying out an overlay already has.
+ */
+export function screenToNdc(
+  viewportWidth: number,
+  viewportHeight: number,
+  out: Affine2D,
+): Affine2D {
+  out[0] = 2 / viewportWidth;
+  out[1] = 0;
+  out[2] = 0;
+  out[3] = -2 / viewportHeight;
+  out[4] = -1;
+  out[5] = 1;
+  return out;
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * `@driftengine/ui2d` — the 2D layer.
+ *
+ * A quad is the whole of 2D, so this package is one batch and one pass over it: sprites, the
+ * sheets they are cut from, the tilemaps that place thousands of them, and the interface tree that
+ * lays a screen out. It draws through `registerPass` rather than through a verb on the renderer,
+ * which is what lets it be a package at all — see `pass.ts` in core, which names this package as
+ * one of the three that mechanism exists for.
+ */
+
+export { createAffine2D, screenToNdc, worldToNdc } from './camera2d.ts';
+export type { Affine2D, Camera2D } from './camera2d.ts';
+
+export {
+  SPRITE_FLOATS,
+  createSpriteBatch,
+  drawSprite,
+  resetSpriteBatch,
+  spriteRun,
+} from './spriteBatch.ts';
+export type { SpriteBatch, SpritePlacement, SpriteRun, UvRect } from './spriteBatch.ts';
+
+export { DEFAULT_SPRITE_CAPACITY, DEFAULT_SPRITE_SLOTS, createSpritePass } from './spritePass.ts';
+export type { SpritePass, SpritePassOptions } from './spritePass.ts';
+
+export { DEFAULT_SPRITE_TEXTURE_OPTIONS } from './spriteTexture.ts';
+export type { SpriteImage, SpriteTextureOptions } from './spriteTexture.ts';
+
+export {
+  createSpriteFrame,
+  frameOf,
+  gridSheet,
+  namedSheet,
+  sheetFrame,
+  sheetFrameHeight,
+  sheetFrameWidth,
+} from './spriteSheet.ts';
+export type { SheetEntry, SpriteFrame, SpriteSheet } from './spriteSheet.ts';
+
+export { TILE_EMPTY, createTilemap, drawTilemap, setTile, tileAt } from './tilemap.ts';
+export type { Tilemap, ViewRect } from './tilemap.ts';
+
+export { addUiChild, createUiNode, removeUiChild, uiNodeNamed, uiRectHolds } from './uiNode.ts';
+export type { UiAlign, UiJustify, UiNode, UiNodeOptions, UiRect, UiSize } from './uiNode.ts';
+
+export { layoutUiTree } from './uiLayout.ts';
+
+export { drawUiTree } from './uiDraw.ts';
+export type { UiContentSink } from './uiDraw.ts';
+
+export { uiFocusNext, uiFocusOrder, uiFocusPrevious, uiHitTest } from './uiFocus.ts';
+
+export { createUiInput, resetUiInput, routeUiKey, routeUiPointer, setUiFocus } from './uiInput.ts';
+export type { UiInput } from './uiInput.ts';

package/src/shaders/generated/sprite.wgsl.ts

@@ -0,0 +1,63 @@
+/*
+ * Generated from ../sprite.ts by `npm run wgsl`. Do not edit.
+ *
+ * The GLSL beside this file is the source of truth. A hand edit here is discarded by
+ * the next generation, and `npm run wgsl:check` fails the build when this is stale.
+ */
+
+export const SPRITE_FRAG_WGSL = "struct Uniforms {\n    uOutputTransform: i32,\n    uOutputExposure: f32,\n}\n\n@group(0) @binding(1) \nvar<uniform> unnamed: Uniforms;\n@group(0) @binding(32) \nvar uSpriteTexture_t: texture_2d<f32>;\n@group(0) @binding(33) \nvar uSpriteTexture_s: sampler;\nvar<private> vUv_1: vec2<f32>;\nvar<private> vTint_1: vec4<f32>;\nvar<private> fragColor: vec4<f32>;\n\nfn linearToSrgb_u0028_vf3_u003b(c: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var low: vec3<f32>;\n    var high: vec3<f32>;\n\n    let _e55 = (*c);\n    low = (_e55 * 12.92f);\n    let _e57 = (*c);\n    high = ((pow(max(_e57, vec3<f32>(0f, 0f, 0f)), vec3<f32>(0.41666666f, 0.41666666f, 0.41666666f)) * 1.055f) - vec3(0.055f));\n    let _e63 = high;\n    let _e64 = low;\n    let _e65 = (*c);\n    return mix(_e63, _e64, step(_e65, vec3<f32>(0.0031308f, 0.0031308f, 0.0031308f)));\n}\n\nfn rrtAndOdtFit_u0028_vf3_u003b(v: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var a: vec3<f32>;\n    var b: vec3<f32>;\n\n    let _e55 = (*v);\n    let _e56 = (*v);\n    a = ((_e55 * (_e56 + vec3(0.0245786f))) - vec3(0.000090537f));\n    let _e62 = (*v);\n    let _e63 = (*v);\n    b = ((_e62 * ((_e63 * 0.983729f) + vec3(0.432951f))) + vec3(0.238081f));\n    let _e70 = a;\n    let _e71 = b;\n    return (_e70 / _e71);\n}\n\nfn acesFilmic_u0028_vf3_u003b(x: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var param: vec3<f32>;\n\n    let _e55 = unnamed.uOutputExposure;\n    let _e56 = (*x);\n    (*x) = (_e56 * _e55);\n    let _e58 = (*x);\n    param = (mat3x3<f32>(vec3<f32>(0.59719f, 0.076f, 0.0284f), vec3<f32>(0.35458f, 0.90834f, 0.13383f), vec3<f32>(0.04823f, 0.01566f, 0.83777f)) * _e58);\n    let _e60 = rrtAndOdtFit_u0028_vf3_u003b((&param));\n    return clamp((mat3x3<f32>(vec3<f32>(1.60475f, -0.10208f, -0.00327f), vec3<f32>(-0.53108f, 1.10813f, -0.07276f), vec3<f32>(-0.07367f, -0.00605f, 1.07602f)) * _e60), vec3(0f), vec3(1f));\n}\n\nfn applyOutputTransform_u0028_vf3_u003b(c_1: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var param_1: vec3<f32>;\n    var param_2: vec3<f32>;\n\n    let _e56 = unnamed.uOutputTransform;\n    if (_e56 == 0i) {\n        let _e58 = (*c_1);\n        return _e58;\n    }\n    let _e60 = unnamed.uOutputTransform;\n    if (_e60 == 2i) {\n        let _e62 = (*c_1);\n        param_1 = _e62;\n        let _e63 = acesFilmic_u0028_vf3_u003b((&param_1));\n        (*c_1) = _e63;\n    }\n    let _e64 = (*c_1);\n    param_2 = _e64;\n    let _e65 = linearToSrgb_u0028_vf3_u003b((&param_2));\n    return _e65;\n}\n\nfn main_1() {\n    var texel: vec4<f32>;\n    var colour: vec4<f32>;\n    var param_3: vec3<f32>;\n\n    let _e55 = vUv_1;\n    let _e56 = textureSample(uSpriteTexture_t, uSpriteTexture_s, _e55);\n    texel = _e56;\n    let _e57 = texel;\n    let _e58 = vTint_1;\n    colour = (_e57 * _e58);\n    let _e61 = colour[3u];\n    if (_e61 < 0.00392157f) {\n        discard;\n    }\n    let _e63 = colour;\n    param_3 = _e63.xyz;\n    let _e65 = applyOutputTransform_u0028_vf3_u003b((&param_3));\n    let _e66 = colour;\n    colour = vec4<f32>(_e65.x, _e65.y, _e65.z, _e66.w);\n    let _e72 = colour;\n    let _e75 = colour[3u];\n    let _e76 = (_e72.xyz * _e75);\n    let _e78 = colour[3u];\n    fragColor = vec4<f32>(_e76.x, _e76.y, _e76.z, _e78);\n    return;\n}\n\n@fragment \nfn main(@location(0) vUv: vec2<f32>, @location(1) vTint: vec4<f32>) -> @location(0) vec4<f32> {\n    vUv_1 = vUv;\n    vTint_1 = vTint;\n    main_1();\n    let _e5 = fragColor;\n    return _e5;\n}\n";
+
+export const SPRITE_VERT_WGSL = "struct Uniforms {\n    uToNdc0_: vec4<f32>,\n    uToNdc1_: vec4<f32>,\n    uClipCorrection: mat4x4<f32>,\n}\n\nstruct gl_PerVertex {\n    @builtin(position) gl_Position: vec4<f32>,\n    gl_PointSize: f32,\n}\n\nstruct VertexOutput {\n    @location(0) member: vec2<f32>,\n    @location(1) member_1: vec4<f32>,\n    @builtin(position) gl_Position: vec4<f32>,\n}\n\nvar<private> gl_VertexIndex_1: i32;\nvar<private> aOrigin_1: vec2<f32>;\nvar<private> aEdges_1: vec4<f32>;\n@group(0) @binding(0) \nvar<uniform> unnamed: Uniforms;\nvar<private> vUv: vec2<f32>;\nvar<private> aUv_1: vec4<f32>;\nvar<private> vTint: vec4<f32>;\nvar<private> aTint_1: vec4<f32>;\nvar<private> unnamed_1: gl_PerVertex = gl_PerVertex(vec4<f32>(0f, 0f, 0f, 1f), 1f);\n\nfn main_1() {\n    var corner: vec2<f32>;\n    var indexable: array<vec2<f32>, 6>;\n    var p: vec2<f32>;\n    var ndc: vec2<f32>;\n\n    let _e28 = gl_VertexIndex_1;\n    indexable = array<vec2<f32>, 6>(vec2<f32>(0f, 0f), vec2<f32>(1f, 0f), vec2<f32>(0f, 1f), vec2<f32>(0f, 1f), vec2<f32>(1f, 0f), vec2<f32>(1f, 1f));\n    let _e30 = indexable[_e28];\n    corner = _e30;\n    let _e31 = aOrigin_1;\n    let _e32 = aEdges_1;\n    let _e35 = corner[0u];\n    let _e38 = aEdges_1;\n    let _e41 = corner[1u];\n    p = ((_e31 + (_e32.xy * _e35)) + (_e38.zw * _e41));\n    let _e46 = unnamed.uToNdc0_[0u];\n    let _e48 = p[0u];\n    let _e52 = unnamed.uToNdc0_[2u];\n    let _e54 = p[1u];\n    let _e59 = unnamed.uToNdc1_[0u];\n    let _e63 = unnamed.uToNdc0_[1u];\n    let _e65 = p[0u];\n    let _e69 = unnamed.uToNdc0_[3u];\n    let _e71 = p[1u];\n    let _e76 = unnamed.uToNdc1_[1u];\n    ndc = vec2<f32>((((_e46 * _e48) + (_e52 * _e54)) + _e59), (((_e63 * _e65) + (_e69 * _e71)) + _e76));\n    let _e79 = aUv_1;\n    let _e81 = aUv_1;\n    let _e83 = corner;\n    vUv = mix(_e79.xy, _e81.zw, _e83);\n    let _e85 = aTint_1;\n    vTint = _e85;\n    let _e87 = unnamed.uClipCorrection;\n    let _e88 = ndc;\n    unnamed_1.gl_Position = (_e87 * vec4<f32>(_e88.x, _e88.y, 0f, 1f));\n    return;\n}\n\n@vertex \nfn main(@builtin(vertex_index) gl_VertexIndex: u32, @location(3) aOrigin: vec2<f32>, @location(0) aEdges: vec4<f32>, @location(1) aUv: vec4<f32>, @location(2) aTint: vec4<f32>) -> VertexOutput {\n    gl_VertexIndex_1 = i32(gl_VertexIndex);\n    aOrigin_1 = aOrigin;\n    aEdges_1 = aEdges;\n    aUv_1 = aUv;\n    aTint_1 = aTint;\n    main_1();\n    let _e16 = unnamed_1.gl_Position.y;\n    unnamed_1.gl_Position.y = -(_e16);\n    let _e18 = vUv;\n    let _e19 = vTint;\n    let _e20 = unnamed_1.gl_Position;\n    return VertexOutput(_e18, _e19, _e20);\n}\n";
+
+/**
+ * What the transform assigned, so the renderer binds the same numbers.
+ *
+ * A permuted shader has one entry per variant, keyed as `FLAT_FRAG_WGSL` is.
+ */
+export const SPRITE_BINDINGS = {
+  "SPRITE_FRAG": {
+    "uniforms": 1,
+    "uniformSize": 16,
+    "fields": {
+      "uOutputTransform": {
+        "offset": 0,
+        "size": 4,
+        "type": "int"
+      },
+      "uOutputExposure": {
+        "offset": 4,
+        "size": 4,
+        "type": "float"
+      }
+    },
+    "textures": {
+      "uSpriteTexture": {
+        "texture": 32,
+        "sampler": 33,
+        "type": "sampler2D"
+      }
+    }
+  },
+  "SPRITE_VERT": {
+    "uniforms": 0,
+    "uniformSize": 96,
+    "fields": {
+      "uToNdc0": {
+        "offset": 0,
+        "size": 16,
+        "type": "vec4"
+      },
+      "uToNdc1": {
+        "offset": 16,
+        "size": 16,
+        "type": "vec4"
+      },
+      "uClipCorrection": {
+        "offset": 32,
+        "size": 64,
+        "type": "mat4"
+      }
+    },
+    "textures": {}
+  }
+} as const;

package/src/shaders/sprite.ts

@@ -0,0 +1,102 @@
+/** The sprite program: one textured, tinted quad per instance, blended in submission order. */
+
+import { OUTPUT_TRANSFORM_GLSL } from '@driftengine/core';
+
+/**
+ * Below this the fragment is thrown away rather than blended.
+ *
+ * Half of one eight-bit step. A sprite sheet's transparent margin is exactly zero and costs
+ * nothing to reject; what this buys is the *soft* edge of an antialiased glyph or a feathered
+ * particle, whose outermost ring blends a texture fetch and a blend for a contribution no frame
+ * can show. It is a fill saving and not a correctness rule, which is why it is this low: a cutout
+ * threshold that shaved visible alpha would put a hard edge on every soft one.
+ */
+const ALPHA_FLOOR = 1.0 / 255.0;
+
+export const SPRITE_VERT = `#version 300 es
+
+/**
+ * The two edge vectors of the quad, in the space the affine below maps from.
+ *
+ * Edge vectors rather than a size and an angle: the rotation is resolved on the CPU once per
+ * sprite, where it costs one sine, and the vertex stage does two multiplies and an add. A sprite
+ * batch is vertex-bound at four thousand quads and this is the whole of its vertex work.
+ */
+layout(location = 0) in vec4 aEdges;
+/** The frame this sprite reads, as (u0, v0) and (u1, v1). */
+layout(location = 1) in vec4 aUv;
+/** Straight, not premultiplied. The fragment stage premultiplies after the texture fetch. */
+layout(location = 2) in vec4 aTint;
+/** The corner the two edges grow from. */
+layout(location = 3) in vec2 aOrigin;
+
+/**
+ * The affine to normalised device coordinates, as (a, b, c, d) and (e, f).
+ *
+ * Two \`vec4\`s rather than a \`mat3\`, because a \`mat3\` in a uniform block is three
+ * sixteen-byte rows for nine useful floats and this is read once per vertex.
+ */
+uniform vec4 uToNdc0;
+uniform vec4 uToNdc1;
+/**
+ * Clip space, as the backend drawing this defines it. Identity on WebGL2.
+ *
+ * The same correction \`panel.ts\` carries and for the same reason: this stage builds its own clip
+ * position and never multiplies by a camera, so the generated vertex shader's Y negation would
+ * stand uncancelled and the whole 2D layer would land mirrored about the middle of the frame.
+ */
+uniform mat4 uClipCorrection;
+
+out vec2 vUv;
+out vec4 vTint;
+
+/**
+ * Two triangles, wound so that either winding draws: this pass culls nothing.
+ *
+ * A sprite is flipped by giving it a negative width, which reverses the winding — so a cull mode
+ * would silently drop every mirrored sprite, which is what a character facing left is.
+ */
+const vec2 CORNERS[6] = vec2[6](
+  vec2(0.0, 0.0), vec2(1.0, 0.0), vec2(0.0, 1.0),
+  vec2(0.0, 1.0), vec2(1.0, 0.0), vec2(1.0, 1.0)
+);
+
+void main() {
+  vec2 corner = CORNERS[gl_VertexID];
+  vec2 p = aOrigin + aEdges.xy * corner.x + aEdges.zw * corner.y;
+  vec2 ndc = vec2(
+    uToNdc0.x * p.x + uToNdc0.z * p.y + uToNdc1.x,
+    uToNdc0.y * p.x + uToNdc0.w * p.y + uToNdc1.y
+  );
+  vUv = mix(aUv.xy, aUv.zw, corner);
+  vTint = aTint;
+  /* z is 0 and nothing depth-tests here: the order sprites were submitted in is the layering. */
+  gl_Position = uClipCorrection * vec4(ndc, 0.0, 1.0);
+}
+`;
+
+export const SPRITE_FRAG = `#version 300 es
+precision highp float;
+
+uniform sampler2D uSpriteTexture;
+
+in vec2 vUv;
+in vec4 vTint;
+out vec4 fragColor;
+
+${OUTPUT_TRANSFORM_GLSL}
+
+void main() {
+  /*
+   * No branch reaches this fetch, so the implicit derivative is taken in uniform control flow and
+   * a sheet may be mipmapped. The 2026-08-07 rule is about a sample under a branch and there is
+   * none here; adding one later would mean a \`textureLod\`.
+   */
+  vec4 texel = texture(uSpriteTexture, vUv);
+  vec4 colour = texel * vTint;
+  if (colour.a < ${ALPHA_FLOOR.toFixed(8)}) discard;
+  colour.rgb = applyOutputTransform(colour.rgb);
+  /* Premultiplied out, because the blend is (ONE, ONE_MINUS_SRC_ALPHA). */
+  fragColor = vec4(colour.rgb * colour.a, colour.a);
+}
+`;

package/src/spriteBatch.ts

@@ -0,0 +1,169 @@
+/** The CPU side of a sprite draw: quads packed into one instance buffer, in submission order. */
+
+/**
+ * Floats per instance: two edge vectors, a UV rectangle, a tint, and an origin.
+ *
+ * Fourteen rather than a rounder sixteen because a vertex buffer's stride only has to be a multiple
+ * of four bytes, and two floats a sprite is 8 KB at a four-thousand-sprite batch.
+ */
+export const SPRITE_FLOATS = 14;
+
+/** Where a sprite goes, in whatever space the batch is being drawn in. */
+export interface SpritePlacement {
+  /**
+   * The corner the sprite grows from, and *which* corner depends on the affine.
+   *
+   * In screen space y counts down, so this is the top-left; in a 2D world y counts up, so it is
+   * the bottom-left. The batch does not know which it is in and does not need to: it is the same
+   * arithmetic either way, and `camera2d.ts` is where the two conventions are written down.
+   */
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+  /**
+   * Radians, anticlockwise in the mathematical sense — which reads as clockwise on screen, where y
+   * counts down. Defaults to none.
+   */
+  readonly rotation?: number;
+  /** The point rotation turns about, as a fraction of the sprite. Defaults to its centre. */
+  readonly pivotX?: number;
+  readonly pivotY?: number;
+}
+
+/** A rectangle of a texture, in the 0..1 the sampler reads. See `spriteSheet.ts`. */
+export interface UvRect {
+  readonly u0: number;
+  readonly v0: number;
+  readonly u1: number;
+  readonly v1: number;
+}
+
+/**
+ * A run of consecutive instances that share a texture.
+ *
+ * Runs exist because the number to hold down is material changes rather than draws: a tilemap over
+ * one sheet is one run however many thousand tiles it is, and a run boundary is the only place the
+ * pass has to touch the GPU between them.
+ */
+export interface SpriteRun {
+  readonly texture: number;
+  readonly first: number;
+  readonly count: number;
+}
+
+/**
+ * One frame's worth of sprites.
+ *
+ * Fixed capacity, filled from the front, reset each frame. It grows for nobody: a batch that
+ * reallocated mid-frame would allocate in the hot path, and the failure it is protecting against —
+ * a caller drawing more than it planned for — is one that wants counting rather than absorbing.
+ */
+export interface SpriteBatch {
+  /** `capacity * SPRITE_FLOATS`, filled to `count * SPRITE_FLOATS`. */
+  readonly instances: Float32Array;
+  readonly capacity: number;
+  count: number;
+  /** Three entries a run: texture, first instance, length. */
+  readonly runs: Int32Array;
+  runCount: number;
+  /** Sprites this frame refused for want of room. Zero is the only good value. */
+  dropped: number;
+}
+
+export function createSpriteBatch(capacity: number): SpriteBatch {
+  return {
+    instances: new Float32Array(capacity * SPRITE_FLOATS),
+    capacity,
+    count: 0,
+    /*
+     * One run per sprite is the worst case — a caller alternating textures every draw — and
+     * allocating for it costs twelve bytes a sprite against the fifty-six the sprite itself costs.
+     * The alternative is a second capacity to overflow, on a path where overflowing means dropping
+     * a draw the caller can see.
+     */
+    runs: new Int32Array(capacity * 3),
+    runCount: 0,
+    dropped: 0,
+  };
+}
+
+export function resetSpriteBatch(batch: SpriteBatch): void {
+  batch.count = 0;
+  batch.runCount = 0;
+  batch.dropped = 0;
+}
+
+/** Read a run back. For tests and diagnostics; the pass reads `runs` directly. */
+export function spriteRun(batch: SpriteBatch, index: number): SpriteRun {
+  const at = index * 3;
+  return {
+    texture: batch.runs[at] as number,
+    first: batch.runs[at + 1] as number,
+    count: batch.runs[at + 2] as number,
+  };
+}
+
+/**
+ * Push one quad. Allocates nothing.
+ *
+ * `source` of `null` is the whole texture and `tint` of `null` is opaque white, because those are
+ * what a caller drawing a plain image wants and neither should cost an object per draw.
+ */
+export function drawSprite(
+  batch: SpriteBatch,
+  texture: number,
+  placement: SpritePlacement,
+  source: UvRect | null,
+  tint: ArrayLike<number> | null,
+): void {
+  if (batch.count >= batch.capacity) {
+    batch.dropped += 1;
+    return;
+  }
+
+  const rotation = placement.rotation ?? 0;
+  const cos = rotation === 0 ? 1 : Math.cos(rotation);
+  const sin = rotation === 0 ? 0 : Math.sin(rotation);
+  const w = placement.w;
+  const h = placement.h;
+  // The two edge vectors of the quad, turned.
+  const ax = w * cos;
+  const ay = w * sin;
+  const bx = -h * sin;
+  const by = h * cos;
+  const pivotX = placement.pivotX ?? 0.5;
+  const pivotY = placement.pivotY ?? 0.5;
+  // The pivot does not move, so the origin is wherever it has to be for that to hold.
+  const originX = placement.x + w * pivotX - (ax * pivotX + bx * pivotY);
+  const originY = placement.y + h * pivotY - (ay * pivotX + by * pivotY);
+
+  const at = batch.count * SPRITE_FLOATS;
+  const f = batch.instances;
+  f[at] = ax;
+  f[at + 1] = ay;
+  f[at + 2] = bx;
+  f[at + 3] = by;
+  f[at + 4] = source === null ? 0 : source.u0;
+  f[at + 5] = source === null ? 0 : source.v0;
+  f[at + 6] = source === null ? 1 : source.u1;
+  f[at + 7] = source === null ? 1 : source.v1;
+  f[at + 8] = tint === null ? 1 : (tint[0] as number);
+  f[at + 9] = tint === null ? 1 : (tint[1] as number);
+  f[at + 10] = tint === null ? 1 : (tint[2] as number);
+  f[at + 11] = tint === null ? 1 : (tint[3] as number);
+  f[at + 12] = originX;
+  f[at + 13] = originY;
+
+  const lastRun = (batch.runCount - 1) * 3;
+  if (batch.runCount > 0 && batch.runs[lastRun] === texture) {
+    batch.runs[lastRun + 2] = (batch.runs[lastRun + 2] as number) + 1;
+  } else {
+    const run = batch.runCount * 3;
+    batch.runs[run] = texture;
+    batch.runs[run + 1] = batch.count;
+    batch.runs[run + 2] = 1;
+    batch.runCount += 1;
+  }
+  batch.count += 1;
+}