@driftengine/ui2d 3.62.0 → 4.0.0

package/dist/uiScroll.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Moving a clipping node's contents underneath it.
+ *
+ * **Scrolling is an offset applied at placement, not a transform applied at draw.** `uiLayout.ts`
+ * subtracts it from the content origin, so a scrolled child's rectangle simply is where it is —
+ * and hit testing, focus and clipping keep working without any of them knowing that scrolling
+ * exists. Applied at draw, each of those would need the inverse and one of them would eventually
+ * get it wrong in one direction only.
+ *
+ * **A scroll that moves nothing says so.** Nested containers are the case: a wheel over an inner
+ * list that has reached its end should scroll the outer one rather than stopping dead, and a
+ * caller that cannot tell "consumed" from "already at the end" cannot implement that. The boolean
+ * is the whole mechanism.
+ */
+import type { UiNode } from './uiNode.ts';
+/**
+ * How far this node's contents extend past its own box, along each axis.
+ *
+ * Read from the span `layoutUiTree` measured, which is relative to the content origin and so does
+ * not change as the node scrolls. **Deriving it from placed rectangles plus the live scroll value
+ * is wrong**, and wrong in the one situation it is asked about: after a caller has moved the
+ * scroll, the rectangles still reflect the previous value and the two no longer agree.
+ */
+export declare function scrollExtent(node: UiNode): {
+    x: number;
+    y: number;
+};
+export declare function clampScroll(node: UiNode): void;
+/** Scroll, clamped. Returns whether anything actually moved — see the header for why. */
+export declare function scrollBy(node: UiNode, dx: number, dy: number): boolean;
+/**
+ * Give a wheel to the innermost container under the pointer that can use it, then outwards.
+ *
+ * Innermost first is the order a person expects and the opposite of the order the tree makes
+ * convenient, so the chain is collected on the way down and walked back up. Returns the node that
+ * consumed it, or null when nothing did — which is a caller's signal to let the page have it.
+ */
+export declare function routeScrollWheel(root: UiNode, x: number, y: number, dx: number, dy: number): UiNode | null;

package/dist/uiScroll.js

@@ -0,0 +1,65 @@
+import { uiRectHolds } from './uiNode.js';
+/**
+ * How far this node's contents extend past its own box, along each axis.
+ *
+ * Read from the span `layoutUiTree` measured, which is relative to the content origin and so does
+ * not change as the node scrolls. **Deriving it from placed rectangles plus the live scroll value
+ * is wrong**, and wrong in the one situation it is asked about: after a caller has moved the
+ * scroll, the rectangles still reflect the previous value and the two no longer agree.
+ */
+export function scrollExtent(node) {
+    const contentW = Math.max(0, node.rect.w - node.paddingLeft - node.paddingRight);
+    const contentH = Math.max(0, node.rect.h - node.paddingTop - node.paddingBottom);
+    return {
+        x: Math.max(0, node.contentSpanX - contentW),
+        y: Math.max(0, node.contentSpanY - contentH),
+    };
+}
+export function clampScroll(node) {
+    const extent = scrollExtent(node);
+    node.scrollX = Math.min(Math.max(0, node.scrollX), extent.x);
+    node.scrollY = Math.min(Math.max(0, node.scrollY), extent.y);
+}
+/** Scroll, clamped. Returns whether anything actually moved — see the header for why. */
+export function scrollBy(node, dx, dy) {
+    const beforeX = node.scrollX;
+    const beforeY = node.scrollY;
+    node.scrollX += dx;
+    node.scrollY += dy;
+    clampScroll(node);
+    return node.scrollX !== beforeX || node.scrollY !== beforeY;
+}
+/* Reused across calls: this runs per wheel event and the chain is its only allocation. */
+const CHAIN = [];
+/**
+ * Give a wheel to the innermost container under the pointer that can use it, then outwards.
+ *
+ * Innermost first is the order a person expects and the opposite of the order the tree makes
+ * convenient, so the chain is collected on the way down and walked back up. Returns the node that
+ * consumed it, or null when nothing did — which is a caller's signal to let the page have it.
+ */
+export function routeScrollWheel(root, x, y, dx, dy) {
+    let depth = 0;
+    let walk = root;
+    while (walk !== null) {
+        CHAIN[depth] = walk;
+        depth += 1;
+        let next = null;
+        for (let i = walk.children.length - 1; i >= 0; i -= 1) {
+            const child = walk.children[i];
+            if (!child.hidden && uiRectHolds(child, x, y)) {
+                next = child;
+                break;
+            }
+        }
+        walk = next;
+    }
+    for (let i = depth - 1; i >= 0; i -= 1) {
+        const node = CHAIN[i];
+        if (!node.clip)
+            continue;
+        if (scrollBy(node, dx, dy))
+            return node;
+    }
+    return null;
+}

package/dist/uiSlice.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A panel background that stretches without stretching its corners.
+ *
+ * Nine cells: the four corners keep their source size, the four edges stretch along one axis, and
+ * the middle stretches along both. Written into a caller's array as
+ * `x, y, w, h, u0, v0, u1, v1` per cell, in row-major order — top-left, top, top-right, left,
+ * middle, right, bottom-left, bottom, bottom-right — so the middle is always index 4.
+ *
+ * **A box narrower than its own insets scales them down rather than letting them overlap.**
+ * Overlapping corners draw the same alpha twice, which on a translucent panel is a visible seam
+ * exactly where the design was trying to be careful.
+ *
+ * **The source size is a parameter because `SpriteFrame` carries only texture coordinates.** The
+ * insets are in texels, so splitting the frame needs to know what the frame's texels span.
+ */
+import type { SpriteFrame } from './spriteSheet.ts';
+/** Floats per placement: x, y, w, h, u0, v0, u1, v1. */
+export declare const SLICE_STRIDE = 8;
+export interface SliceInset {
+    readonly left: number;
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+}
+export declare function sliceInto(out: Float32Array, frame: SpriteFrame, sourceWidth: number, sourceHeight: number, inset: SliceInset, x: number, y: number, w: number, h: number): number;

package/dist/uiSlice.js

@@ -0,0 +1,51 @@
+/** Floats per placement: x, y, w, h, u0, v0, u1, v1. */
+export const SLICE_STRIDE = 8;
+export function sliceInto(out, frame, sourceWidth, sourceHeight, inset, x, y, w, h) {
+    /*
+     * Scaled down together when the box cannot hold both, so the two corners meet exactly at the
+     * midpoint instead of overlapping. The texture coordinates are deliberately *not* scaled with
+     * them: the corner draws a smaller piece of the box out of the same piece of the source, which
+     * is squashing rather than seaming and is the better of the two wrong pictures available.
+     */
+    const sideX = inset.left + inset.right;
+    const kx = sideX > w && sideX > 0 ? w / sideX : 1;
+    const left = inset.left * kx;
+    const right = inset.right * kx;
+    const sideY = inset.top + inset.bottom;
+    const ky = sideY > h && sideY > 0 ? h / sideY : 1;
+    const top = inset.top * ky;
+    const bottom = inset.bottom * ky;
+    const colX = [x, x + left, x + w - right];
+    const colW = [left, Math.max(0, w - left - right), right];
+    const rowY = [y, y + top, y + h - bottom];
+    const rowH = [top, Math.max(0, h - top - bottom), bottom];
+    const du = frame.u1 - frame.u0;
+    const dv = frame.v1 - frame.v0;
+    const uAt = [
+        frame.u0,
+        frame.u0 + (inset.left / sourceWidth) * du,
+        frame.u1 - (inset.right / sourceWidth) * du,
+        frame.u1,
+    ];
+    const vAt = [
+        frame.v0,
+        frame.v0 + (inset.top / sourceHeight) * dv,
+        frame.v1 - (inset.bottom / sourceHeight) * dv,
+        frame.v1,
+    ];
+    let at = 0;
+    for (let r = 0; r < 3; r += 1) {
+        for (let c = 0; c < 3; c += 1) {
+            out[at] = colX[c];
+            out[at + 1] = rowY[r];
+            out[at + 2] = colW[c];
+            out[at + 3] = rowH[r];
+            out[at + 4] = uAt[c];
+            out[at + 5] = vAt[r];
+            out[at + 6] = uAt[c + 1];
+            out[at + 7] = vAt[r + 1];
+            at += SLICE_STRIDE;
+        }
+    }
+    return 9;
+}

package/dist/virtualList.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Which rows a scroll offset makes visible, so that a list costs a screenful rather than a list.
+ *
+ * An asset browser with ten thousand entries has to cost what a screenful costs. Without this the
+ * scene tree is unusable the first time somebody opens a real project, which is the moment nobody
+ * wants to discover it.
+ *
+ * **Overscan is applied before clamping, not after.** Applied after, a window near either end
+ * runs past the row count and a caller indexes rows that do not exist.
+ */
+export interface RowWindow {
+    first: number;
+    count: number;
+}
+/** Uniform row heights, which is arithmetic. */
+export declare function visibleRange(scrollY: number, viewHeight: number, rowHeight: number, rowCount: number, overscan: number): RowWindow;
+/**
+ * Variable row heights, through a prefix-sum table of row tops the caller owns.
+ *
+ * **The caller owns the table** because only the caller knows when a row's height changed, and
+ * recomputing it here every frame would be the cost this module exists to avoid. `offsets` holds
+ * `rowCount + 1` entries: the top of each row, then the bottom of the last.
+ */
+export declare function visibleRangeVariable(scrollY: number, viewHeight: number, offsets: Float64Array, rowCount: number, overscan: number): RowWindow;

package/dist/virtualList.js

@@ -0,0 +1,49 @@
+function clampWindow(first, lastExclusive, rowCount) {
+    const lo = Math.max(0, Math.min(rowCount, first));
+    const hi = Math.max(lo, Math.min(rowCount, lastExclusive));
+    return { first: lo, count: hi - lo };
+}
+/** Uniform row heights, which is arithmetic. */
+export function visibleRange(scrollY, viewHeight, rowHeight, rowCount, overscan) {
+    if (rowHeight <= 0 || rowCount <= 0)
+        return { first: 0, count: 0 };
+    const top = Math.max(0, scrollY);
+    const first = Math.floor(top / rowHeight) - overscan;
+    const lastExclusive = Math.ceil((top + viewHeight) / rowHeight) + overscan;
+    return clampWindow(first, lastExclusive, rowCount);
+}
+/**
+ * Variable row heights, through a prefix-sum table of row tops the caller owns.
+ *
+ * **The caller owns the table** because only the caller knows when a row's height changed, and
+ * recomputing it here every frame would be the cost this module exists to avoid. `offsets` holds
+ * `rowCount + 1` entries: the top of each row, then the bottom of the last.
+ */
+export function visibleRangeVariable(scrollY, viewHeight, offsets, rowCount, overscan) {
+    if (rowCount <= 0)
+        return { first: 0, count: 0 };
+    const top = Math.max(0, scrollY);
+    const bottom = top + viewHeight;
+    /* Largest index whose top is at or before the window's top. */
+    let lo = 0;
+    let hi = rowCount;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if ((offsets[mid] ?? 0) <= top)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    const first = lo - overscan;
+    /* Smallest index whose top is at or after the window's bottom. */
+    let a = 0;
+    let b = rowCount;
+    while (a < b) {
+        const mid = (a + b) >> 1;
+        if ((offsets[mid] ?? 0) >= bottom)
+            b = mid;
+        else
+            a = mid + 1;
+    }
+    return clampWindow(first, a + overscan, rowCount);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/ui2d",
-  "version": "3.62.0",
+  "version": "4.0.0",
   "description": "The 2D layer: batched sprites, sheets, tilemaps, and a retained interface tree over them",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,7 +27,7 @@
   ],
   "sideEffects": false,
   "peerDependencies": {
-    "@driftengine/core": "3.62.0"
+    "@driftengine/core": "4.0.0"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/a11y.ts

@@ -0,0 +1,73 @@
+/**
+ * The interface tree in the shape assistive technology needs, and the seam that publishes it.
+ *
+ * **A seam, because whether anything can receive this is the host's business.** A browser host can
+ * mirror the tree into a hidden structure that a screen reader walks. A native host may have a
+ * platform accessibility service, or may have nothing — and `createNullA11yHost` is the honest
+ * answer in that case rather than an absence nobody noticed.
+ */
+import type { UiNode } from './uiNode.ts';
+
+export interface A11yNode {
+  role: string;
+  label: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  focused: boolean;
+}
+
+export interface A11yHost {
+  publish(nodes: readonly A11yNode[], count: number): void;
+}
+
+/** A host that accepts a tree and does nothing with it. See the header. */
+export function createNullA11yHost(): A11yHost {
+  return { publish() {} };
+}
+
+/**
+ * What role this node plays, derived rather than declared.
+ *
+ * Derived, because a role a caller has to set is a role most callers will not set, and an
+ * accessibility tree that is mostly unlabelled is worse than none: it reads as though the interface
+ * has been described when it has not.
+ */
+function roleOf(node: UiNode): string {
+  if (node.focusable && node.children.length === 0) return 'button';
+  if (node.clip && (node.contentSpanX > node.rect.w || node.contentSpanY > node.rect.h)) {
+    return 'scrollable';
+  }
+  return 'text';
+}
+
+function contributes(node: UiNode): boolean {
+  return node.interactive || node.focusable || node.text.length > 0;
+}
+
+function gather(node: UiNode, out: A11yNode[], at: number): number {
+  if (node.hidden) return at;
+  let next = at;
+  if (contributes(node)) {
+    const slot = out[next] ?? { role: '', label: '', x: 0, y: 0, w: 0, h: 0, focused: false };
+    slot.role = roleOf(node);
+    slot.label = node.text;
+    slot.x = node.rect.x;
+    slot.y = node.rect.y;
+    slot.w = node.rect.w;
+    slot.h = node.rect.h;
+    slot.focused = false;
+    out[next] = slot;
+    next += 1;
+  }
+  for (const child of node.children) next = gather(child, out, next);
+  return next;
+}
+
+/** Fill `out` with every node worth describing, in tree order. Returns how many. */
+export function a11yTree(root: UiNode, out: A11yNode[]): number {
+  const count = gather(root, out, 0);
+  out.length = count;
+  return count;
+}

package/src/index.ts

@@ -53,3 +53,57 @@ export { uiFocusNext, uiFocusOrder, uiFocusPrevious, uiHitTest } from './uiFocus
 
 export { createUiInput, resetUiInput, routeUiKey, routeUiPointer, setUiFocus } from './uiInput.ts';
 export type { UiInput } from './uiInput.ts';
+
+/*
+ * The interface framework: what an editor needs from a 2D layer and a game's interface wants too.
+ *
+ * Every platform touch below is a capability the caller supplies — `TextHost` for composition and
+ * the clipboard, `A11yHost` for assistive technology — because this has to run under a host with
+ * no document object model. That is the same rule `AGENTS.md` already applies to persistence.
+ */
+export { clipRectFor, intersectClip } from './uiClip.ts';
+export { clampScroll, routeScrollWheel, scrollBy, scrollExtent } from './uiScroll.ts';
+export { layerOrder } from './uiLayer.ts';
+export { SLICE_STRIDE, sliceInto } from './uiSlice.ts';
+export type { SliceInset } from './uiSlice.ts';
+export {
+  createTextModel,
+  deleteBackward,
+  deleteForward,
+  insertText,
+  moveCaret,
+  moveToLineEdge,
+  selectAll,
+  selectedText,
+  selectionRange,
+} from './textModel.ts';
+export type { TextModel } from './textModel.ts';
+export { applyComposition, createNullTextHost } from './textHost.ts';
+export type { TextHost } from './textHost.ts';
+export { runsFor } from './richText.ts';
+export type { TextRun } from './richText.ts';
+export { visibleRange, visibleRangeVariable } from './virtualList.ts';
+export type { RowWindow } from './virtualList.ts';
+export {
+  createTheme,
+  deriveTheme,
+  themeColour,
+  themeRgba,
+  themeSize,
+  unpackRgba,
+} from './theme.ts';
+export type { Theme } from './theme.ts';
+export { clearDirty, createDirtyTracker, diffTree, dirtyBounds, markDirty } from './uiDirty.ts';
+export type { DirtyTracker } from './uiDirty.ts';
+export {
+  beginDrag,
+  capturePointer,
+  createPointerState,
+  dropTarget,
+  endDrag,
+  pointerTarget,
+  releasePointer,
+} from './uiPointer.ts';
+export type { PointerState } from './uiPointer.ts';
+export { a11yTree, createNullA11yHost } from './a11y.ts';
+export type { A11yHost, A11yNode } from './a11y.ts';

package/src/richText.ts

@@ -0,0 +1,69 @@
+/**
+ * Overlapping style runs, normalised into disjoint ones that cover every character once.
+ *
+ * **The normalisation is the whole job.** A syntax highlighter emits overlapping runs — a rule for
+ * the string, a more specific one for the escape inside it — and a renderer needs disjoint runs in
+ * order with no gaps. Every consumer that skips this step draws a character twice or not at all,
+ * and both look like a font problem.
+ *
+ * **Later wins the overlap**, because a later rule is the more specific one in every highlighter
+ * that emits them in that order.
+ */
+export interface TextRun {
+  from: number;
+  to: number;
+  colour: number;
+  bold: boolean;
+  italic: boolean;
+}
+
+/* Reused across calls: this runs per frame for a visible document. */
+const BOUNDS: number[] = [];
+
+/**
+ * Fill `out` with disjoint, ordered, gap-free runs covering `[0, text.length)`.
+ *
+ * Returns how many were written. With no input runs the answer is one run covering everything,
+ * which is what a plain string is.
+ */
+export function runsFor(text: string, runs: readonly TextRun[], out: TextRun[]): number {
+  const end = text.length;
+  if (end === 0) return 0;
+
+  BOUNDS.length = 0;
+  BOUNDS.push(0, end);
+  for (const run of runs) {
+    const from = Math.max(0, Math.min(end, run.from));
+    const to = Math.max(0, Math.min(end, run.to));
+    if (to > from) BOUNDS.push(from, to);
+  }
+  BOUNDS.sort((a, b) => a - b);
+
+  let count = 0;
+  let previous = -1;
+  for (let i = 0; i < BOUNDS.length - 1; i += 1) {
+    const from = BOUNDS[i] as number;
+    const to = BOUNDS[i + 1] as number;
+    if (from === to || from === previous) continue;
+    previous = from;
+
+    /* Last covering run wins; none covering means the default, which is what index -1 encodes. */
+    let chosen = -1;
+    for (let r = 0; r < runs.length; r += 1) {
+      const run = runs[r] as TextRun;
+      if (run.from <= from && run.to >= to) chosen = r;
+    }
+    const style = chosen === -1 ? null : (runs[chosen] as TextRun);
+
+    const slot = out[count] ?? { from: 0, to: 0, colour: 0xffffffff, bold: false, italic: false };
+    slot.from = from;
+    slot.to = to;
+    slot.colour = style?.colour ?? 0xffffffff;
+    slot.bold = style?.bold ?? false;
+    slot.italic = style?.italic ?? false;
+    out[count] = slot;
+    count += 1;
+  }
+  out.length = count;
+  return count;
+}

package/src/spriteGl.ts

@@ -129,9 +129,25 @@ export function setWebgl2SpriteTexture(
   gl.bindTexture(gl.TEXTURE_2D, texture);
   const internal = options.colorSpace === 'linear' ? gl.RGBA : gl.SRGB8_ALPHA8;
   gl.texImage2D(gl.TEXTURE_2D, 0, internal, gl.RGBA, gl.UNSIGNED_BYTE, source);
-  const filter = options.filter === 'linear' ? gl.LINEAR : gl.NEAREST;
-  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
-  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
+  const linear = options.filter === 'linear';
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, linear ? gl.LINEAR : gl.NEAREST);
+  /*
+   * **Minification is the chain's question and magnification is `filter`'s**, which is why the two
+   * are set apart here. A mipmapped sheet blends *between* levels whichever filter was asked for:
+   * that is what stops a stroke disappearing on the way down, and `filter` still decides whether
+   * the texels inside a level are blended. `SurfaceTexture` splits it the same way.
+   */
+  gl.texParameteri(
+    gl.TEXTURE_2D,
+    gl.TEXTURE_MIN_FILTER,
+    options.mipmap === true
+      ? linear
+        ? gl.LINEAR_MIPMAP_LINEAR
+        : gl.NEAREST_MIPMAP_LINEAR
+      : linear
+        ? gl.LINEAR
+        : gl.NEAREST,
+  );
   /*
    * Clamped on both axes, and it is a correctness rule rather than a default. A sheet frame's
    * edge texel is adjacent to the *next* frame's, so a repeating wrap bleeds one sprite into
@@ -139,6 +155,9 @@ export function setWebgl2SpriteTexture(
    */
   gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
   gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  /* After the upload, which is the only order that works: the chain is built from level 0, and a
+     driver that has not been given one yet builds nothing from it. */
+  if (options.mipmap === true) gl.generateMipmap(gl.TEXTURE_2D);
   gl.bindTexture(gl.TEXTURE_2D, null);
   gl.activeTexture(gl.TEXTURE0);
   sprites.textures[slot] = texture;

package/src/spriteGpu.ts

@@ -7,6 +7,16 @@ import {
 } from './shaders/generated/sprite.wgsl.ts';
 import { SPRITE_FLOATS } from './spriteBatch.ts';
 import type { SpriteBatch } from './spriteBatch.ts';
+/*
+ * **The first runtime import this package takes from the engine, and it was measured before it was
+ * taken.** Everything else here is `import type`, which erases, so `ui2d` has had no runtime edge
+ * to `core` at all — and a value import from a barrel is how a package quietly acquires the whole
+ * of another one. Bundled alone, with the import and with it stubbed out: **32,801 against 31,031
+ * raw and 11,777 against 11,163 gzipped**, so 614 gzipped bytes, which is the blit and its shader
+ * and nothing else. The alternative was a second copy of the mip blit living here, and the second
+ * copy is the one that ends up disagreeing about the colour space.
+ */
+import { generateMipChain, mipLevelCount, type MipPipelines } from '@driftengine/core';
 import type { SpriteImage, SpriteTextureOptions } from './spriteTexture.ts';
 
 const VERT = SPRITE_BINDINGS.SPRITE_VERT;
@@ -30,7 +40,14 @@ export interface GpuSprites {
   readonly vertexUniforms: GPUBuffer;
   readonly fragmentUniforms: GPUBuffer;
   readonly instances: GPUBuffer;
-  readonly samplers: { readonly nearest: GPUSampler; readonly linear: GPUSampler };
+  readonly samplers: {
+    readonly nearest: GPUSampler;
+    readonly linear: GPUSampler;
+    readonly nearestMip: GPUSampler;
+    readonly linearMip: GPUSampler;
+  };
+  /** One mip-blit pipeline per format, built on first use. See `generateMipChain`. */
+  readonly mipPipelines: MipPipelines;
   readonly slots: (GpuSpriteSlot | null)[];
   readonly vertexScratch: ArrayBuffer;
   readonly vertexFloats: Float32Array;
@@ -146,7 +163,23 @@ export function createGpuSprites(
         magFilter: 'linear',
         minFilter: 'linear',
       }),
+      /*
+       * The mipmapped pair. `mipmapFilter` is the level blend and is `linear` in both, because
+       * that is minification; `magFilter` is what `filter` was asked about. Four samplers rather
+       * than two because the questions are independent, and the same split `SurfaceTexture` makes.
+       */
+      nearestMip: device.createSampler({
+        label: `${label}.nearestMip`,
+        mipmapFilter: 'linear',
+      }),
+      linearMip: device.createSampler({
+        label: `${label}.linearMip`,
+        magFilter: 'linear',
+        minFilter: 'linear',
+        mipmapFilter: 'linear',
+      }),
     },
+    mipPipelines: mipPipelineCache(device),
     slots: new Array<null>(slots).fill(null),
     vertexScratch,
     vertexFloats: new Float32Array(vertexScratch),
@@ -156,6 +189,26 @@ export function createGpuSprites(
   };
 }
 
+/**
+ * One pipeline per format, kept on the sprite pass rather than in the renderer's cache.
+ *
+ * The renderer's `PipelineCache` is not reachable from a contributed pass, and the chain builder
+ * takes an interface for exactly that reason. A `Map` is the whole of what is needed: there are at
+ * most two formats here, and they are built once each.
+ */
+function mipPipelineCache(device: GPUDevice): MipPipelines {
+  const built = new Map<string, GPURenderPipeline>();
+  return {
+    get(key: string, describe: () => GPURenderPipelineDescriptor): GPURenderPipeline {
+      const existing = built.get(key);
+      if (existing !== undefined) return existing;
+      const pipeline = device.createRenderPipeline(describe());
+      built.set(key, pipeline);
+      return pipeline;
+    },
+  };
+}
+
 export function setGpuSpriteTexture(
   device: GPUDevice,
   sprites: GpuSprites,
@@ -165,10 +218,16 @@ export function setGpuSpriteTexture(
 ): void {
   const previous = sprites.slots[slot];
   if (previous !== null && previous !== undefined) previous.texture.destroy();
+  const format: GPUTextureFormat =
+    options.colorSpace === 'linear' ? 'rgba8unorm' : 'rgba8unorm-srgb';
+  /* One level unless a chain was asked for. `TEXTURE_USAGE` already carries RENDER_ATTACHMENT,
+     which is what the blit needs to draw into each level. */
+  const levels = options.mipmap === true ? mipLevelCount(source.width, source.height) : 1;
   const texture = device.createTexture({
     label: `ui2d.sprite.${slot}`,
     size: [source.width, source.height],
-    format: options.colorSpace === 'linear' ? 'rgba8unorm' : 'rgba8unorm-srgb',
+    format,
+    mipLevelCount: levels,
     usage: TEXTURE_USAGE,
   });
   /*
@@ -182,7 +241,18 @@ export function setGpuSpriteTexture(
     { texture },
     [source.width, source.height],
   );
-  const sampler = options.filter === 'linear' ? sprites.samplers.linear : sprites.samplers.nearest;
+  /* After the copy, which is the only order that works: every level is rendered from the one above
+     it, and level 0 has to hold the image before the chain can be built from it. */
+  generateMipChain(device, sprites.mipPipelines, texture, format, levels);
+  const linear = options.filter === 'linear';
+  const sampler =
+    levels > 1
+      ? linear
+        ? sprites.samplers.linearMip
+        : sprites.samplers.nearestMip
+      : linear
+        ? sprites.samplers.linear
+        : sprites.samplers.nearest;
   const bindGroup = device.createBindGroup({
     label: `ui2d.sprite.${slot}.bindGroup`,
     layout: sprites.layout,

package/src/spriteTexture.ts

@@ -34,9 +34,40 @@ export interface SpriteTextureOptions {
    * and saves the sharp case from a blur nobody asked for.
    */
   readonly filter?: 'nearest' | 'linear';
+  /**
+   * Whether to build a mip chain and sample it. `false` by default, which is the sheet above.
+   *
+   * **The case it exists for is type baked into an atlas.** The comment on `filter` says a sheet
+   * that is not pixel art "is normally drawn near its authored size, where the two filters differ
+   * by very little" — a glyph page is the sheet where that is not true. A consumer baking one page
+   * per weight at 96 px and drawing body copy at 11 is minifying **7x**, and `linear` reads four
+   * texels of a footprint that covers dozens: a `t` crossbar two texels tall lands on about a
+   * quarter of a pixel, and whether it survives depends on where the sample falls. Reported by a
+   * player as `Step-In Uppercut` reading `Slep-In Uppercul`, with different strokes lost per
+   * glyph and per position, so the line looks unevenly spaced as well as misread.
+   *
+   * Neither workaround available to a consumer is good: baking nearer the drawn size blurs the
+   * headings, because one atlas cannot serve an 8x range of sizes, and baking a second atlas for
+   * small text doubles the pages and the uploads and moves a sampling decision into the game where
+   * it has to be re-tuned whenever a size changes.
+   *
+   * **Off by default because the chain is wrong for pixel art**, which is what most sheets are: it
+   * is memory nothing samples, and at a distance it dissolves art whose whole point is the pixel.
+   *
+   * With `filter: 'linear'` this is trilinear — blended within a level and between levels. With
+   * `filter: 'nearest'` the levels are still blended, because that is minification and `filter` is
+   * about magnification; `SurfaceTexture` makes the same split and for the same reason.
+   *
+   * **Padding cells against bleed is the caller's problem**, and it has to be: a lower level mixes
+   * texels the atlas packer put next to each other, so a sheet whose frames touch will show its
+   * neighbours. How much padding depends on how far the chain is allowed to go, which is a fact
+   * about the sheet rather than about the sampler.
+   */
+  readonly mipmap?: boolean;
 }
 
 export const DEFAULT_SPRITE_TEXTURE_OPTIONS: SpriteTextureOptions = {
   colorSpace: 'srgb',
   filter: 'nearest',
+  mipmap: false,
 };