@solidrt/2d 0.0.52

package/src/pick.ts

@@ -0,0 +1,22 @@
+// Picking narrowphase, pure: no GPU or GUI imports, so the checks rig
+// (checks/pick-check.ts) exercises this module headless on the flux binary.
+// layer.ts walks its draw order calling this per sprite (topmost first).
+
+/** Exact containment test against a rotated rect (center, size, rotation). */
+export function pointInSprite(
+  px: number,
+  py: number,
+  cx: number,
+  cy: number,
+  w: number,
+  h: number,
+  rotation: number,
+): boolean {
+  let dx = px - cx
+  let dy = py - cy
+  let c = Math.cos(-rotation)
+  let s = Math.sin(-rotation)
+  let lx = dx * c - dy * s
+  let ly = dx * s + dy * c
+  return Math.abs(lx) <= w / 2 && Math.abs(ly) <= h / 2
+}

package/src/records.ts

@@ -0,0 +1,294 @@
+// The records layer: the raw escape hatch for motion only JS can compute
+// (bespoke flocking, per-frame gameplay logic over every entity at large
+// populations). Sprites are 13 JS-owned floats in one canonical
+// Float32Array ordered by draw order (insertion order - painter's
+// algorithm, later over earlier); mutations batch to a microtask whose
+// flush publishes the live prefix through the zero-copy buffer write lease.
+// A moved sprite is 13 float stores plus one bulk memcpy per dirty frame; a
+// static layer publishes nothing and therefore costs nothing.
+//
+// This is NOT the default live layer - that is layer.ts, where sprites are
+// spatial arena nodes core producers can reach. Use this when a JS loop
+// writes every record every frame anyway: `layer.records` + `touch()` is
+// ~2.4x faster than setSprite at 30k sprites (measured 12.9ms raw vs
+// 30.8ms via setSprite, purely call overhead). It shrinks as producers
+// land; it is the where-motion-is-computed axis, not a "game tier".
+//
+// Layer space, camera, pointer dispatch and the sprite functions
+// (addSprite/setSprite/...) are shared with the node layer; picking here is
+// the JS reverse walk (pointInSprite), since records have no nodes.
+import { getOwner, onCleanup } from "@solidrt/core"
+import {
+  beginBufferWrite,
+  createBuffer,
+  createPipelineTexture,
+  destroyBuffer,
+  destroyTexture,
+  endBufferWrite,
+  setDraw,
+  setTargetParams,
+  setTargetSize,
+} from "@solidrt/core/gpu"
+import type { BufferId, TextureId } from "@solidrt/core/gpu"
+import { FULL_FRAME } from "./frames.ts"
+import { spriteDispatch } from "./layer.ts"
+import type { LayerBase, Sprite, SpriteHandlers, SpriteLayerOptions, SpriteOptions } from "./layer.ts"
+import { pointInSprite } from "./pick.ts"
+import { FRAGMENT, INSTANCE_ATTRIBUTES, VERTEX } from "./shaders.ts"
+
+// Floats per instance record:
+// [cx, cy, w, h, u0, v0, u1, v1, rot, tintR, tintG, tintB, tintA]
+export const FLOATS_PER_SPRITE = 13
+
+const RESOLVED = Promise.resolve()
+
+export type RecordLayer = LayerBase & {
+  /**
+   * The canonical record array - the raw power path. Layout per sprite is
+   * FLOATS_PER_SPRITE floats: [cx, cy, w, h, u0, v0, u1, v1, rot, tintR,
+   * tintG, tintB, tintA], record i at i * FLOATS_PER_SPRITE in draw order.
+   * Write fields directly for large per-frame populations, then call
+   * touch() once. Do not cache indices across removeSprite - records
+   * shift - and do not cache the array across addSprite - growth replaces
+   * it.
+   */
+  records: Float32Array
+  /** Mark the records dirty and schedule the publish (the raw-path commit). */
+  touch(): void
+  _order: Sprite[]
+}
+
+/**
+ * Create a records layer rendering into a `width` x `height` texture from
+ * one atlas texture (same target shape as createSpriteLayer; the atlas is
+ * NOT owned). Disposed automatically with the owning reactive scope (opt
+ * out with `{ autoFree: false }`).
+ */
+export function createRecordLayer(
+  width: number,
+  height: number,
+  atlas: TextureId,
+  opts?: SpriteLayerOptions,
+): RecordLayer {
+  let capacity = opts?.capacity ?? 1024
+  if (!(capacity > 0 && Number.isInteger(capacity))) {
+    throw new Error(`createRecordLayer: capacity must be a positive integer, got ${capacity}`)
+  }
+  let label = opts?.label ?? "sprites"
+  // One unit quad (triangle strip), reused by every instance.
+  let quad = createBuffer(new Float32Array([-0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, 0.5]), {
+    label: `${label}-quad`,
+    autoFree: false,
+  })
+  let records: BufferId = createBuffer(capacity * FLOATS_PER_SPRITE * 4, {
+    label: `${label}-records`,
+    autoFree: false,
+  })
+  let texture = createPipelineTexture(
+    VERTEX,
+    FRAGMENT,
+    width,
+    height,
+    { uViewport: [width, height], uCamera: [0, 0, 1, 1] },
+    {
+      label,
+      topology: "triangle-strip",
+      vertexCount: 4,
+      attributes: [{ name: "aPos", format: "vec2" }],
+      buffer: quad,
+      instanceAttributes: INSTANCE_ATTRIBUTES,
+      instanceBuffer: records,
+      instanceCount: 0,
+      blend: "alpha",
+      textures: { uAtlas: atlas },
+      clearColor: opts?.clearColor ?? [0, 0, 0, 0],
+      autoFree: false,
+    },
+  )
+
+  // Camera state, mirrored for picking (the inverse mapping).
+  let camX = 0
+  let camY = 0
+  let camZoom = 1
+  let disposed = false
+  let dirty = false
+  let scheduled = false
+  let published = 0
+
+  // The GPU buffer's record capacity; the canonical array grows ahead of it
+  // (addSprite) and the publish catches the buffer up: a larger buffer is
+  // created, written in full, swapped in, and the old one destroyed. The
+  // entry holds the old buffer alive until the swap lands, so the destroy
+  // is safe to issue right after.
+  let gpuCapacity = capacity
+  let flush = () => {
+    scheduled = false
+    if (disposed || !dirty) return
+    dirty = false
+    let count = layer._order.length
+    let grown: BufferId | null = null
+    if (layer.records.length > gpuCapacity * FLOATS_PER_SPRITE) {
+      gpuCapacity = layer.records.length / FLOATS_PER_SPRITE
+      grown = createBuffer(layer.records.length * 4, { label: `${label}-records`, autoFree: false })
+    }
+    let target = grown ?? records
+    let out = beginBufferWrite(target)
+    out.set(layer.records.subarray(0, count * FLOATS_PER_SPRITE))
+    endBufferWrite(target, count * FLOATS_PER_SPRITE * 4)
+    if (grown !== null) {
+      setDraw(texture, { instanceBuffer: grown, instanceCount: count })
+      destroyBuffer(records)
+      records = grown
+      published = count
+    } else if (count !== published) {
+      setDraw(texture, { instanceCount: count })
+      published = count
+    }
+  }
+
+  // Record layout: [cx, cy, w, h, u0, v0, u1, v1, rot, tintR, tintG, tintB, tintA]
+  let writeRecord = (sprite: Sprite, opts: SpriteOptions) => {
+    let at = sprite._slot * FLOATS_PER_SPRITE
+    let r = layer.records
+    if (opts.x !== undefined) r[at] = opts.x
+    if (opts.y !== undefined) r[at + 1] = opts.y
+    if (opts.w !== undefined) r[at + 2] = opts.w
+    if (opts.h !== undefined) r[at + 3] = opts.h
+    if (opts.frame !== undefined) {
+      r[at + 4] = opts.frame.u0
+      r[at + 5] = opts.frame.v0
+      r[at + 6] = opts.frame.u1
+      r[at + 7] = opts.frame.v1
+    }
+    if (opts.rotation !== undefined) r[at + 8] = opts.rotation
+    if (opts.tint !== undefined) {
+      r[at + 9] = opts.tint[0]
+      r[at + 10] = opts.tint[1]
+      r[at + 11] = opts.tint[2]
+      r[at + 12] = opts.tint[3]
+    }
+  }
+
+  let dispatch = spriteDispatch({
+    size: () => [width, height],
+    camera: () => [camX, camY, camZoom],
+    pick: (x, y) => layer.pick(x, y),
+  })
+
+  let layer: RecordLayer = {
+    texture,
+    handlers: undefined as unknown as SpriteHandlers,
+    get count() {
+      return layer._order.length
+    },
+    setSize(w, h) {
+      if (disposed || (w === width && h === height)) return
+      width = w
+      height = h
+      setTargetSize(texture, w, h)
+      setTargetParams(texture, { uViewport: [w, h] })
+    },
+    setCamera(update) {
+      if (disposed) return
+      if (update.x !== undefined) camX = update.x
+      if (update.y !== undefined) camY = update.y
+      if (update.zoom !== undefined) {
+        if (!(update.zoom > 0)) throw new Error(`setCamera: zoom must be positive, got ${update.zoom}`)
+        camZoom = update.zoom
+      }
+      setTargetParams(texture, { uCamera: [camX, camY, camZoom, camZoom] })
+    },
+    pick(x, y) {
+      // Topmost first: reverse draw order, exact rotated-rect containment.
+      let r = layer.records
+      for (let i = layer._order.length - 1; i >= 0; i--) {
+        let at = i * FLOATS_PER_SPRITE
+        if (pointInSprite(x, y, r[at]!, r[at + 1]!, r[at + 2]!, r[at + 3]!, r[at + 8]!)) {
+          return layer._order[i]!
+        }
+      }
+      return null
+    },
+    handlersFor(layout) {
+      return dispatch(layout)
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      for (let sprite of layer._order) sprite.layer = null
+      layer._order.length = 0
+      destroyTexture(texture)
+      destroyBuffer(records)
+      destroyBuffer(quad)
+    },
+    _add(opts) {
+      if (opts?.parent) {
+        throw new Error("addSprite: record layers have no groups (parent is the node layer's)")
+      }
+      let index = layer._order.length
+      if ((index + 1) * FLOATS_PER_SPRITE > layer.records.length) {
+        let next = new Float32Array(layer.records.length * 2)
+        next.set(layer.records)
+        layer.records = next
+      }
+      let sprite: Sprite = { layer, node: null, _slot: index, _x: 0, _y: 0, _w: 0, _h: 0, _rot: 0 }
+      layer._order.push(sprite)
+      writeRecord(sprite, {
+        x: 0,
+        y: 0,
+        w: 0,
+        h: 0,
+        frame: FULL_FRAME,
+        rotation: 0,
+        tint: [1, 1, 1, 1],
+        ...opts,
+      })
+      layer._schedule()
+      return sprite
+    },
+    _write(sprite, opts) {
+      writeRecord(sprite, opts)
+      layer._schedule()
+    },
+    _read(sprite) {
+      let at = sprite._slot * FLOATS_PER_SPRITE
+      let r = layer.records
+      return {
+        x: r[at]!,
+        y: r[at + 1]!,
+        w: r[at + 2]!,
+        h: r[at + 3]!,
+        frame: { u0: r[at + 4]!, v0: r[at + 5]!, u1: r[at + 6]!, v1: r[at + 7]! },
+        rotation: r[at + 8]!,
+        tint: [r[at + 9]!, r[at + 10]!, r[at + 11]!, r[at + 12]!],
+      }
+    },
+    _remove(sprite) {
+      // Later sprites shift down one draw slot (order preserved).
+      sprite.layer = null
+      let index = sprite._slot
+      let order = layer._order
+      let r = layer.records
+      r.copyWithin(index * FLOATS_PER_SPRITE, (index + 1) * FLOATS_PER_SPRITE, order.length * FLOATS_PER_SPRITE)
+      order.splice(index, 1)
+      for (let i = index; i < order.length; i++) order[i]!._slot = i
+      layer._schedule()
+    },
+    _schedule() {
+      if (disposed) return
+      dirty = true
+      if (scheduled) return
+      scheduled = true
+      RESOLVED.then(flush)
+    },
+    records: new Float32Array(capacity * FLOATS_PER_SPRITE),
+    touch() {
+      layer._schedule()
+    },
+    _order: [],
+  }
+  layer.handlers = dispatch(null)
+
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => layer.dispose())
+  return layer
+}

package/src/shaders.ts

@@ -0,0 +1,93 @@
+// The sprite pipelines: a unit quad instanced over one atlas, mapped
+// world -> clip through uCamera (offset + zoom) and uViewport. World and
+// clip space are both y-down (core gpu.ts pixel contract), so the mapping
+// carries NO flip anywhere - do not add one. Two record layouts share the
+// fragment stage:
+// - VERTEX + INSTANCE_ATTRIBUTES: the 13-float interleaved record
+//   [cx, cy, w, h, u0, v0, u1, v1, rot, tintR, tintG, tintB, tintA],
+//   used by the records layer (records.ts) and the tile layer (tiles.ts).
+// - VERTEX_SPLIT + INSTANCE_ATTRIBUTES_SPLIT: the node-backed live layer
+//   (layer.ts), pose and style in separate instance-buffer slots - slot 0
+//   is the core-written Pose2D record [x, y, angle, sx, sy], slot 1 the
+//   JS-written style record [u0, v0, u1, v1, tintR, tintG, tintB, tintA].
+// The rotation here (clockwise, y-down) and pointInSprite in pick.ts must
+// agree; the differential check guards pick.ts against an oracle but NOT
+// against these shaders - if you touch one rotation, touch all.
+import { glsl } from "@solidrt/core/gpu"
+import type { InstanceAttribute, VertexAttribute } from "@solidrt/core/gpu"
+
+export let VERTEX = glsl`
+  in vec2 aPos;
+  in vec2 iCenter;
+  in vec2 iSize;
+  in vec4 iUv;
+  in float iRot;
+  in vec4 iTint;
+  out vec2 vUv;
+  out vec4 vTint;
+  uniform vec2 uViewport;
+  uniform vec4 uCamera;
+
+  void main() {
+    vec2 corner = aPos * iSize;
+    float c = cos(iRot), s = sin(iRot);
+    vec2 world = iCenter + vec2(corner.x * c - corner.y * s, corner.x * s + corner.y * c);
+    vec2 screen = (world - uCamera.xy) * uCamera.zw;
+    // World and clip are both y-down, so the mapping carries no flip.
+    gl_Position = vec4(screen / uViewport * 2.0 - 1.0, 0.0, 1.0);
+    vUv = mix(iUv.xy, iUv.zw, aPos + 0.5);
+    vTint = iTint;
+  }
+`
+
+export let FRAGMENT = glsl`
+  in vec2 vUv;
+  in vec4 vTint;
+  uniform sampler2D uAtlas;
+
+  void main() {
+    fragColor = texture(uAtlas, vUv) * vTint;
+  }
+`
+
+/** The instance attribute list matching the 13-float record layout. */
+export const INSTANCE_ATTRIBUTES: VertexAttribute[] = [
+  { name: "iCenter", format: "vec2" },
+  { name: "iSize", format: "vec2" },
+  { name: "iUv", format: "vec4" },
+  { name: "iRot", format: "f32" },
+  { name: "iTint", format: "vec4" },
+]
+
+export let VERTEX_SPLIT = glsl`
+  in vec2 aPos;
+  in vec2 iPos;
+  in float iRot;
+  in vec2 iScale;
+  in vec4 iUv;
+  in vec4 iTint;
+  out vec2 vUv;
+  out vec4 vTint;
+  uniform vec2 uViewport;
+  uniform vec4 uCamera;
+
+  void main() {
+    vec2 corner = aPos * iScale;
+    float c = cos(iRot), s = sin(iRot);
+    vec2 world = iPos + vec2(corner.x * c - corner.y * s, corner.x * s + corner.y * c);
+    vec2 screen = (world - uCamera.xy) * uCamera.zw;
+    // World and clip are both y-down, so the mapping carries no flip.
+    gl_Position = vec4(screen / uViewport * 2.0 - 1.0, 0.0, 1.0);
+    vUv = mix(iUv.xy, iUv.zw, aPos + 0.5);
+    vTint = iTint;
+  }
+`
+
+/** The split layout: slot 0 the Pose2D record, slot 1 the style record. */
+export const INSTANCE_ATTRIBUTES_SPLIT: InstanceAttribute[] = [
+  { name: "iPos", format: "vec2" },
+  { name: "iRot", format: "f32" },
+  { name: "iScale", format: "vec2" },
+  { name: "iUv", format: "vec4", slot: 1 },
+  { name: "iTint", format: "vec4", slot: 1 },
+]

package/src/tiles.ts

@@ -0,0 +1,281 @@
+// The baked tile layer: a cols x rows grid of atlas frames rendered into
+// CHUNKED `render: "manual"` targets and composited as a handful of quads -
+// never a quad per tile. On tiled GPUs the budget is primitive count, so a
+// 100x100 world must not be 10,000 quads per frame; baked, it is a few
+// chunk textures, and scrolling is a transform on the composited world
+// (see <TileLayer> in components.tsx), never a repaint.
+//
+// Each chunk is a small copy of the sprite pipeline (shaders.ts) with fixed
+// record slots - record localRow * chunkTiles + localCol IS that tile, an
+// empty tile is a zero-size quad, instance count is constant per chunk.
+// Records hold WORLD pixel coordinates; the chunk target's uCamera is its
+// pixel origin, so the shared vertex stage does the chunk-local mapping
+// (the same mechanism a camera pass uses, pointed at a chunk rect).
+//
+// Chunks allocate lazily on the first setTile that gives them content: an
+// empty chunk costs nothing - no records, no buffer, no texture - so a
+// sparse world is bounded by its content, and world size is bounded by
+// memory, not maxTextureSize. setTile batches to a microtask; the flush
+// publishes and re-bakes ONLY dirty chunks. A layer nobody edits publishes
+// nothing, renders nothing, and costs nothing per frame. Camera-driven
+// residency (bake far chunks on approach, evict them) is deliberately not
+// here yet - see okf/backlog/2d-baked-layers.md.
+import { getOwner, onCleanup } from "@solidrt/core"
+import {
+  beginBufferWrite,
+  createBuffer,
+  createPipelineTexture,
+  destroyBuffer,
+  destroyTexture,
+  endBufferWrite,
+  limits,
+  renderTarget,
+} from "@solidrt/core/gpu"
+import type { BufferId, FilterMode, TextureId } from "@solidrt/core/gpu"
+import type { Frame } from "./frames.ts"
+import { FLOATS_PER_SPRITE } from "./records.ts"
+import { FRAGMENT, INSTANCE_ATTRIBUTES, VERTEX } from "./shaders.ts"
+
+const RESOLVED = Promise.resolve()
+
+// Default chunk edge in pixels; the tile count per chunk derives from it.
+const CHUNK_TARGET_PX = 512
+
+export type TileLayerOptions = {
+  /** Per-chunk clear color; empty (never-written) chunks render nothing. */
+  clearColor?: [number, number, number, number]
+  /**
+   * Sampler filter for the baked chunk textures (what the camera zoom
+   * scales at composite time); default "linear". Pixel art wants "nearest"
+   * - hard pixels under integer upscales.
+   */
+  filter?: FilterMode
+  /**
+   * Chunk edge in TILES; default sized so a chunk is ~512px. The tuning
+   * knob between re-bake granularity (smaller = finer dirty regions) and
+   * chunk count (larger = fewer textures and leaves).
+   */
+  chunkTiles?: number
+  label?: string
+  /** Skip the owner-scoped auto-dispose (see createTileLayer). */
+  autoFree?: boolean
+}
+
+/** One resident chunk: a baked texture at a world-pixel rect. */
+export type TileChunk = {
+  texture: TextureId
+  /** World-pixel origin and size of the chunk's rect. */
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export type TileLayer = {
+  /** Grid shape, fixed at creation. */
+  cols: number
+  rows: number
+  tileW: number
+  tileH: number
+  /** World size in pixels: cols * tileW x rows * tileH. */
+  width: number
+  height: number
+  /**
+   * The resident chunks, in allocation order - the layer's output.
+   * Composite each as a texture leaf at its world rect (`<TileLayer>` does
+   * this). The array grows as content reaches new chunks; entries never
+   * move or leave (no eviction yet). Do not mutate.
+   */
+  chunks: TileChunk[]
+  /** Called after a chunk allocates - the composition hook. Assignable. */
+  onChunk?: (chunk: TileChunk) => void
+  /**
+   * Set one cell: a frame draws it, null clears it. Batched; the microtask
+   * flush publishes and re-bakes ONLY the chunks that changed, however
+   * many tiles did.
+   */
+  setTile(col: number, row: number, frame: Frame | null): void
+  /** The frame at a cell, or null when empty. */
+  getTile(col: number, row: number): Frame | null
+  dispose(): void
+}
+
+type Chunk = TileChunk & {
+  records: Float32Array
+  buffer: BufferId
+  dirty: boolean
+}
+
+/**
+ * Create a baked tile layer: `cols` x `rows` cells of `tileW` x `tileH`
+ * pixels, every tile drawing one atlas frame, baked into lazily-allocated
+ * chunk textures and composited as a few quads. The grid shape is fixed at
+ * creation - recreate the layer to resize. Disposed automatically with the
+ * owning reactive scope (opt out with `{ autoFree: false }`); the atlas is
+ * NOT owned - dispose it yourself.
+ */
+export function createTileLayer(
+  cols: number,
+  rows: number,
+  tileW: number,
+  tileH: number,
+  atlas: TextureId,
+  opts?: TileLayerOptions,
+): TileLayer {
+  if (!(cols > 0 && rows > 0 && Number.isInteger(cols) && Number.isInteger(rows))) {
+    throw new Error(`createTileLayer: cols and rows must be positive integers, got ${cols} x ${rows}`)
+  }
+  if (!(tileW > 0 && tileH > 0)) {
+    throw new Error(`createTileLayer: tile size must be positive, got ${tileW} x ${tileH}`)
+  }
+  let chunkTiles = opts?.chunkTiles ?? Math.max(1, Math.floor(CHUNK_TARGET_PX / Math.max(tileW, tileH)))
+  if (!(chunkTiles > 0 && Number.isInteger(chunkTiles))) {
+    throw new Error(`createTileLayer: chunkTiles must be a positive integer, got ${chunkTiles}`)
+  }
+  let chunkW = chunkTiles * tileW
+  let chunkH = chunkTiles * tileH
+  if (chunkW > limits.maxTextureSize || chunkH > limits.maxTextureSize) {
+    throw new Error(
+      `createTileLayer: chunk size ${chunkW} x ${chunkH} exceeds maxTextureSize ${limits.maxTextureSize}; lower chunkTiles`,
+    )
+  }
+  let label = opts?.label ?? "tiles"
+  let chunkCols = Math.ceil(cols / chunkTiles)
+  let perChunk = chunkTiles * chunkTiles
+  // One unit quad (triangle strip), shared by every chunk's pipeline.
+  let quad = createBuffer(new Float32Array([-0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, 0.5]), {
+    label: `${label}-quad`,
+    autoFree: false,
+  })
+
+  let disposed = false
+  let scheduled = false
+  // Chunk index (chunkRow * chunkCols + chunkCol) -> resident chunk.
+  let resident = new Map<number, Chunk>()
+  let dirtyChunks: Chunk[] = []
+
+  let flush = () => {
+    scheduled = false
+    if (disposed) return
+    let baked = dirtyChunks
+    dirtyChunks = []
+    for (let chunk of baked) {
+      if (!chunk.dirty) continue
+      chunk.dirty = false
+      let out = beginBufferWrite(chunk.buffer)
+      out.set(chunk.records)
+      endBufferWrite(chunk.buffer, chunk.records.byteLength)
+      renderTarget(chunk.texture)
+    }
+  }
+  let touch = (chunk: Chunk) => {
+    if (chunk.dirty) return
+    chunk.dirty = true
+    dirtyChunks.push(chunk)
+    if (scheduled) return
+    scheduled = true
+    RESOLVED.then(flush)
+  }
+
+  let allocate = (index: number): Chunk => {
+    let x = (index % chunkCols) * chunkW
+    let y = Math.floor(index / chunkCols) * chunkH
+    let records = new Float32Array(perChunk * FLOATS_PER_SPRITE)
+    let buffer = createBuffer(records.byteLength, { label: `${label}-chunk-records`, autoFree: false })
+    let texture = createPipelineTexture(
+      VERTEX,
+      FRAGMENT,
+      chunkW,
+      chunkH,
+      { uViewport: [chunkW, chunkH], uCamera: [x, y, 1, 1] },
+      {
+        label: `${label}-chunk`,
+        topology: "triangle-strip",
+        vertexCount: 4,
+        attributes: [{ name: "aPos", format: "vec2" }],
+        buffer: quad,
+        instanceAttributes: INSTANCE_ATTRIBUTES,
+        instanceBuffer: buffer,
+        instanceCount: perChunk,
+        blend: "alpha",
+        textures: { uAtlas: atlas },
+        clearColor: opts?.clearColor ?? [0, 0, 0, 0],
+        filter: opts?.filter,
+        render: "manual",
+        autoFree: false,
+      },
+    )
+    let chunk: Chunk = { texture, x, y, width: chunkW, height: chunkH, records, buffer, dirty: false }
+    resident.set(index, chunk)
+    layer.chunks.push(chunk)
+    layer.onChunk?.(chunk)
+    return chunk
+  }
+
+  let locate = (col: number, row: number, verb: string): [number, number] => {
+    if (!(Number.isInteger(col) && Number.isInteger(row) && col >= 0 && col < cols && row >= 0 && row < rows)) {
+      throw new Error(`${verb}: cell ${col}, ${row} outside the ${cols} x ${rows} grid`)
+    }
+    let index = Math.floor(row / chunkTiles) * chunkCols + Math.floor(col / chunkTiles)
+    let at = ((row % chunkTiles) * chunkTiles + (col % chunkTiles)) * FLOATS_PER_SPRITE
+    return [index, at]
+  }
+
+  let layer: TileLayer = {
+    cols,
+    rows,
+    tileW,
+    tileH,
+    width: cols * tileW,
+    height: rows * tileH,
+    chunks: [],
+    setTile(col, row, frame) {
+      if (disposed) return
+      let [index, at] = locate(col, row, "setTile")
+      let chunk = resident.get(index)
+      if (frame === null) {
+        // Clearing a cell no chunk holds is a no-op, not an allocation.
+        if (!chunk) return
+        chunk.records[at + 2] = 0
+        chunk.records[at + 3] = 0
+      } else {
+        chunk ??= allocate(index)
+        let r = chunk.records
+        r[at] = (col + 0.5) * tileW
+        r[at + 1] = (row + 0.5) * tileH
+        r[at + 2] = tileW
+        r[at + 3] = tileH
+        r[at + 4] = frame.u0
+        r[at + 5] = frame.v0
+        r[at + 6] = frame.u1
+        r[at + 7] = frame.v1
+        r[at + 9] = 1
+        r[at + 10] = 1
+        r[at + 11] = 1
+        r[at + 12] = 1
+      }
+      touch(chunk)
+    },
+    getTile(col, row) {
+      let [index, at] = locate(col, row, "getTile")
+      let chunk = resident.get(index)
+      if (!chunk || chunk.records[at + 2] === 0) return null
+      let r = chunk.records
+      return { u0: r[at + 4]!, v0: r[at + 5]!, u1: r[at + 6]!, v1: r[at + 7]! }
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      for (let chunk of resident.values()) {
+        destroyTexture(chunk.texture)
+        destroyBuffer(chunk.buffer)
+      }
+      resident.clear()
+      layer.chunks.length = 0
+      destroyBuffer(quad)
+    },
+  }
+
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => layer.dispose())
+  return layer
+}