@solidrt/2d 0.0.55 → 0.0.57

package/src/oversample-math.ts

@@ -0,0 +1,73 @@
+// The pure oversample math: arithmetic on plain numbers, no GPU or window
+// imports, so the headless check (checks/oversample-check.ts) drives it
+// directly. oversample.ts wraps it with the device limits; components/
+// adds the measured inputs (window box, display scale, camera).
+
+/** Tolerance under a whole number when rounding a display scale up, so a
+ * scale that is 3 up to float noise picks 3, not 4. */
+const FIT_EPSILON = 1e-6
+
+/** How far below the current factor's lower boundary the scale must fall
+ * before an auto-picked oversample shrinks. Growth is immediate (an
+ * undersampled layer is visibly soft); the margin keeps a scale
+ * oscillating around an integer (a breathing ancestor transform, float
+ * noise in a measured box) from re-baking the layer on every swing. */
+const SHRINK_MARGIN = 0.25
+
+/** fitOversample against an explicit device size ceiling (see
+ * fitOversample in oversample.ts, which supplies limits.maxTextureSize). */
+export function fitOversampleWithin(scale: number, targetW: number, targetH: number, budget: number, maxSize: number): number {
+  // The budget bounds the scale, not the rounded factor: the ceiling may
+  // still round a fit that fills the window up by one (a 320 x 200 design
+  // on a 2560 x 1440 panel fits at 7.2 and needs 8).
+  let byBudget = Math.sqrt(budget / (targetW * targetH))
+  let n = Math.max(1, Math.ceil(Math.min(scale, byBudget) - FIT_EPSILON))
+  let byDevice = Math.floor(maxSize / Math.max(targetW, targetH))
+  return Math.max(1, Math.min(n, byDevice))
+}
+
+/**
+ * The auto-pick decision: the oversample a layer at `current` should move
+ * to for a measured `scale`, or null for "keep current" (already there, or
+ * the shrink hysteresis holding). `cap` is the maxOversample prop,
+ * validated here (throws - the dev policy).
+ */
+export function pickOversample(
+  current: number,
+  scale: number,
+  targetW: number,
+  targetH: number,
+  budget: number,
+  maxSize: number,
+  cap: number | undefined,
+): number | null {
+  if (cap !== undefined && !(Number.isInteger(cap) && cap >= 1)) {
+    throw new Error(`maxOversample must be a positive integer, got ${cap}`)
+  }
+  let n = fitOversampleWithin(scale, targetW, targetH, budget, maxSize)
+  // The cap overrides the shrink hysteresis: lowering maxOversample below
+  // the current factor is an explicit ask, not measurement noise.
+  let capped = false
+  if (cap !== undefined && n > cap) {
+    n = cap
+    capped = true
+  }
+  if (!capped && n < current && scale > current - 1 - SHRINK_MARGIN) return null
+  return n === current ? null : n
+}
+
+/**
+ * The device-pixels-per-world-pixel factor of a tile world measured through
+ * a rotated camera, before the display scale: the measured box is the AABB
+ * of the ROTATED world view, which swells by up to sqrt(2) as the camera
+ * turns, but texels per world pixel do not change with rotation - so the
+ * swell is divided back out for the known rotation, leaving the camera zoom
+ * and any ancestor fit.
+ */
+export function tileWorldScale(boxW: number, boxH: number, worldW: number, worldH: number, rotation: number): number {
+  let cos = Math.abs(Math.cos(rotation))
+  let sin = Math.abs(Math.sin(rotation))
+  let rotW = worldW * cos + worldH * sin
+  let rotH = worldW * sin + worldH * cos
+  return Math.max(boxW / rotW, boxH / rotH)
+}

package/src/oversample.ts

@@ -4,11 +4,10 @@
 // atlas is still sampled nearest inside (texels stay square blocks), the
 // composite samples linear (each block edge softens over one device pixel
 // instead of snapping to uneven widths). okf/backlog/2d-layer-display-scale.md.
+// The pure math lives in oversample-math.ts (checkable headless); this
+// module binds it to the device limits and adds the thrash sentinel.
 import { limits } from "@solidrt/core/gpu"
-
-/** Tolerance under a whole number when rounding a display scale up, so a
- * scale that is 3 up to float noise picks 3, not 4. */
-const FIT_EPSILON = 1e-6
+import { fitOversampleWithin } from "./oversample-math.ts"
 
 /** Validate an oversample against the target it scales; throws (dev policy). */
 export function checkOversample(verb: string, n: number, width: number, height: number): void {
@@ -30,11 +29,40 @@ export function checkOversample(verb: string, n: number, width: number, height:
  * not ask for one) and by what the target can grow to on this device.
  */
 export function fitOversample(scale: number, targetW: number, targetH: number, budget: number): number {
-  // The budget bounds the scale, not the rounded factor: the ceiling may
-  // still round a fit that fills the window up by one (a 320 x 200 design
-  // on a 2560 x 1440 panel fits at 7.2 and needs 8).
-  let byBudget = Math.sqrt(budget / (targetW * targetH))
-  let n = Math.max(1, Math.ceil(Math.min(scale, byBudget) - FIT_EPSILON))
-  let byDevice = Math.floor(limits.maxTextureSize / Math.max(targetW, targetH))
-  return Math.max(1, Math.min(n, byDevice))
+  return fitOversampleWithin(scale, targetW, targetH, budget, limits.maxTextureSize)
+}
+
+/** Oversample changes inside the window before the thrash warning fires. A
+ * healthy layer settles in a change or two (mount, then the post-resize
+ * scale); reaching this count means something re-picks every frame. */
+const THRASH_CHANGES = 4
+/** The window those changes must land in, ms. */
+const THRASH_WINDOW_MS = 1000
+
+/**
+ * The thrash sentinel: each layer calls the returned hook on every ACTUAL
+ * oversample change, and bunched changes warn once per layer. Every change
+ * resizes and redraws the layer's targets (a tile layer re-bakes every
+ * resident chunk), so a scale sweeping an integer boundary every frame is
+ * this package's most expensive silent mistake - worth a console line the
+ * moment it happens rather than a profiling session later.
+ */
+export function thrashSentinel(what: string): () => void {
+  let stamps: number[] = []
+  let warned = false
+  return () => {
+    if (warned) return
+    let now = performance.now()
+    stamps.push(now)
+    while (stamps.length > 0 && now - stamps[0]! > THRASH_WINDOW_MS) stamps.shift()
+    if (stamps.length < THRASH_CHANGES) return
+    warned = true
+    console.warn(
+      `Oversample thrash: ${what} changed oversample ${THRASH_CHANGES} times within a second. ` +
+        `Every change resizes and redraws the layer's targets (a tile layer re-bakes every ` +
+        `resident chunk). The usual cause is an animated transform or camera sweeping the ` +
+        `measured scale across integer boundaries; pin \`oversample\`, or bound the sweep ` +
+        `with \`maxOversample\`. Warned once per layer.`,
+    )
+  }
 }

package/src/records.ts

@@ -2,8 +2,10 @@
 // (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.
+// algorithm, later over earlier; `orderBy` swaps that for a core-produced
+// key order at publish, records untouched); 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.
 //
@@ -18,101 +20,92 @@
 // (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 { beginBufferWrite, createBuffer, destroyBuffer, endBufferWrite } from "@solidrt/core/gpu"
 import type { BufferId, TextureId } from "@solidrt/core/gpu"
 import { FULL_FRAME, writeFrame } from "./frames.ts"
-import { readFrame, spriteDispatch } from "./layer.ts"
-import type { LayerBase, Sprite, SpriteHandlers, SpriteLayerOptions, SpriteOptions } from "./layer.ts"
+import { checkTint, readFrame } from "./layer.ts"
+import type { LayerBase, Sprite, SpriteLayerOptions, SpriteOptions, SpriteState } from "./layer.ts"
 import { pointInSprite } from "./pick.ts"
-import { checkOversample } from "./oversample.ts"
-import { FRAGMENT, INSTANCE_ATTRIBUTES, VERTEX } from "./shaders.ts"
+import { createSpritePipeline, INSTANCE_ATTRIBUTES, VERTEX } from "./shaders.ts"
+import { createViews } from "./views.ts"
 
 // Floats per instance record:
 // [cx, cy, w, h, u0, v0, u1, v1, rot, tintR, tintG, tintB, tintA]
 export const FLOATS_PER_SPRITE = 13
 
+// Float offset of cy in a record - what `orderBy: "y"` keys on.
+const Y_FIELD_OFFSET = 1
+
 const RESOLVED = Promise.resolve()
 
+export type RecordLayerOptions = Omit<SpriteLayerOptions, "orderBy"> & {
+  /**
+   * Draw records in KEY order instead of record order, produced by core at
+   * each publish (the gpu `instanceOrder` primitive - the flush's lease
+   * copy arrives gathered, no per-record JS anywhere): `"y"` keys on the
+   * record's cy, so a perspective crowd paints back to front (smaller y =
+   * further up the screen = drawn first); or an explicit `{ field,
+   * descending? }` float offset into the record for a custom sort key.
+   * Record slots stay stable - record i keeps meaning sprite i, and
+   * removeSprite still shifts - only the draw order changes. Ties keep
+   * record order, so an unset key draws exactly as before. Known
+   * limitation: pick() resolves overlapping sprites by record order, not
+   * visual order, when a key is set.
+   */
+  orderBy?: "y" | { field: number; descending?: boolean }
+}
+
 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.
+   * tintG, tintB, tintA], record i at i * FLOATS_PER_SPRITE. Record order
+   * is draw order - unless the layer was created with `orderBy`, which
+   * draws in key order while record i keeps meaning sprite i. 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
+  /**
+   * Run `fn` with the CURRENT record array and return its result - the
+   * hoist-proof form of `records`. A cached array reference silently
+   * becomes a dead copy after growth (writes publish nothing); reading
+   * through withRecords at use time always hits the live array.
+   */
+  withRecords<T>(fn: (records: Float32Array) => T): T
   /** Mark the records dirty and schedule the publish (the raw-path commit). */
   touch(): void
-  _order: Sprite[]
+  _order: SpriteState[]
 }
 
 /**
- * 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 }`).
+ * Create a records layer over one atlas texture (the atlas is NOT owned).
+ * Like createSpriteLayer it renders nothing by itself: `createView` is
+ * where it shows. Disposed automatically with the owning reactive scope
+ * (opt out with `{ autoFree: false }`).
  */
-export function createRecordLayer(
-  width: number,
-  height: number,
-  atlas: TextureId,
-  opts?: SpriteLayerOptions,
-): RecordLayer {
+export function createRecordLayer(atlas: TextureId, opts?: RecordLayerOptions): 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 oversample = opts?.oversample ?? 1
-  checkOversample("createRecordLayer", oversample, width, height)
-  let texture = createPipelineTexture(
-    VERTEX,
-    FRAGMENT,
-    width * oversample,
-    height * oversample,
-    { 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,
-    },
-  )
+  let tint = opts?.tint ?? [1, 1, 1, 1]
+  checkTint("createRecordLayer", tint)
+  let orderBy = opts?.orderBy
+  let instanceOrder =
+    orderBy === undefined
+      ? undefined
+      : orderBy === "y"
+        ? { field: Y_FIELD_OFFSET }
+        : { field: orderBy.field, descending: orderBy.descending }
+  let gpu = createSpritePipeline(label, VERTEX, INSTANCE_ATTRIBUTES)
 
-  // 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
@@ -121,7 +114,7 @@ export function createRecordLayer(
   // 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
+  // entries hold the old buffer alive until the swaps land, so the destroy
   // is safe to issue right after.
   let gpuCapacity = capacity
   let flush = () => {
@@ -139,18 +132,35 @@ export function createRecordLayer(
     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 })
+      views.setBuffers({ instanceBuffer: grown })
+      views.setCount(count)
+      if (instanceOrder !== undefined) {
+        // The growth publish above landed BEFORE the swap (the entry must
+        // never point at an unwritten buffer), so the order had not yet
+        // followed to the grown buffer and that publish went out ungathered.
+        // One more publish, now under the swapped-in order, restores key
+        // order - growth frames only.
+        let again = beginBufferWrite(grown)
+        again.set(layer.records.subarray(0, count * FLOATS_PER_SPRITE))
+        endBufferWrite(grown, count * FLOATS_PER_SPRITE * 4)
+      }
       destroyBuffer(records)
       records = grown
       published = count
     } else if (count !== published) {
-      setDraw(texture, { instanceCount: count })
+      views.setCount(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 writeRecord = (sprite: SpriteState, opts: SpriteOptions) => {
+    if (opts.renderOrder !== undefined) {
+      throw new Error("setSprite: record layers have no renderOrder field; order by a record field with orderBy { field }")
+    }
+    if (opts.visible !== undefined) {
+      throw new Error("setSprite: record sprites have no visibility; hide by zeroing w or h")
+    }
     let at = sprite._slot * FLOATS_PER_SPRITE
     let r = layer.records
     if (opts.x !== undefined) r[at] = opts.x
@@ -177,67 +187,52 @@ export function createRecordLayer(
     }
   }
 
-  let dispatch = spriteDispatch({
-    size: () => [width, height],
-    camera: () => [camX, camY, camZoom],
+  let views = createViews({
+    label,
+    pipeline: gpu.pipeline,
+    quad: gpu.quad,
+    atlas,
+    buffers: () => ({ instanceBuffer: records }),
+    count: () => published,
+    tint: () => tint,
     pick: (x, y) => layer.pick(x, y),
+    order: instanceOrder,
   })
 
   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
-      checkOversample("setSize", oversample, w, h)
-      width = w
-      height = h
-      setTargetSize(texture, w * oversample, h * oversample)
-      setTargetParams(texture, { uViewport: [w, h] })
-    },
-    get oversample() {
-      return oversample
-    },
-    setOversample(n) {
-      if (disposed || n === oversample) return
-      checkOversample("setOversample", n, width, height)
-      oversample = n
-      setTargetSize(texture, width * n, height * n)
-    },
-    setCamera(update) {
+    setTint(next) {
       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] })
+      checkTint("setTint", next)
+      tint = next
+      views.setTint(next)
+    },
+    createView(vopts) {
+      if (disposed) throw new Error("createView: layer is disposed")
+      return views.create(vopts)
     },
     pick(x, y) {
       // Topmost first: reverse draw order, exact rotated-rect containment.
+      let out: Sprite[] = []
       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]!
+          out.push(layer._order[i]!)
         }
       }
-      return null
-    },
-    handlersFor(layout) {
-      return dispatch(layout)
+      return out
     },
     dispose() {
       if (disposed) return
       disposed = true
       for (let sprite of layer._order) sprite.layer = null
       layer._order.length = 0
-      destroyTexture(texture)
+      views.dispose()
       destroyBuffer(records)
-      destroyBuffer(quad)
+      gpu.dispose()
     },
     _add(opts) {
       if (opts?.parent) {
@@ -249,7 +244,7 @@ export function createRecordLayer(
         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, _flipX: false, _flipY: false }
+      let sprite: SpriteState = { layer, node: null, _slot: index, _x: 0, _y: 0, _w: 0, _h: 0, _rot: 0, _flipX: false, _flipY: false, _visible: true, _parent: null }
       layer._order.push(sprite)
       writeRecord(sprite, {
         x: 0,
@@ -281,6 +276,10 @@ export function createRecordLayer(
         flipY: sprite._flipY,
         rotation: r[at + 8]!,
         tint: [r[at + 9]!, r[at + 10]!, r[at + 11]!, r[at + 12]!],
+        // Record sprites have no key field and no visibility (see
+        // writeRecord's throws).
+        renderOrder: 0,
+        visible: true,
       }
     },
     _remove(sprite) {
@@ -302,13 +301,14 @@ export function createRecordLayer(
       RESOLVED.then(flush)
     },
     records: new Float32Array(capacity * FLOATS_PER_SPRITE),
+    withRecords(fn) {
+      return fn(layer.records)
+    },
     touch() {
       layer._schedule()
     },
     _order: [],
   }
-  layer.handlers = dispatch(null)
-
   if (opts?.autoFree !== false && getOwner()) onCleanup(() => layer.dispose())
   return layer
 }

package/src/shaders.ts

@@ -1,20 +1,27 @@
 // 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:
+// world -> clip through uCamera (offset + zoom), uCameraRot ([cos, sin,
+// pivotX, pivotY]: the camera rotation about the pivot, identity
+// [1, 0, 0, 0]) and uViewport - the projectCamera mapping (camera.ts)
+// spelled in GLSL; the two must agree. 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"
+//   JS-written style record [u0, v0, u1, v1, tintR, tintG, tintB, tintA,
+//   renderOrder]. The shader never reads iRenderOrder - it exists for the
+//   core's instanceOrder (orderBy: "renderOrder"); declared attributes without an
+//   active program attribute are skipped, their bytes pad the stride.
+// The rotations here (clockwise, y-down) and their JS partners must
+// agree: iRot with pointInSprite in pick.ts, uCameraRot with
+// projectCamera in camera.ts. The differential checks guard the JS side
+// against oracles but NOT against these shaders - if you touch one
+// rotation, touch all.
+import { compileShader, createBuffer, createRenderPipeline, destroyBuffer, destroyProgram, destroyRenderPipeline, destroyShader, glsl, linkProgram } from "@solidrt/core/gpu"
+import type { BufferId, InstanceAttribute, RenderPipelineId, VertexAttribute } from "@solidrt/core/gpu"
 
 export let VERTEX = glsl`
   in vec2 aPos;
@@ -24,29 +31,54 @@ export let VERTEX = glsl`
   in float iRot;
   in vec4 iTint;
   out vec2 vUv;
+  flat out vec4 vFrame;
   out vec4 vTint;
   uniform vec2 uViewport;
   uniform vec4 uCamera;
+  uniform vec4 uCameraRot;
 
   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;
+    vec2 view = (world - uCamera.xy) * uCamera.zw;
+    vec2 screen = uCameraRot.zw + vec2(view.x * uCameraRot.x - view.y * uCameraRot.y, view.x * uCameraRot.y + view.y * uCameraRot.x);
     // 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);
+    vFrame = iUv;
     vTint = iTint;
   }
 `
 
+// uTint is the LAYER tint, multiplied over the per-instance vTint (identity
+// [1, 1, 1, 1] - GLSL uniforms default to ZERO, so every pipeline creation
+// must pin it explicitly or everything renders transparent black).
+//
+// The sample is clamped to its frame, pulled in by half a texel: a quad at
+// a fractional position lands edge samples so close to the frame's edge
+// that a linear tap (and float interpolation under nearest) reaches the
+// cell next door, painting a one-texel line of the neighbour along the
+// sprite's edge. The clamp keeps the quad's texel mapping 1:1 and only
+// moves those edge samples onto the edge texel, so touching cells do not
+// bleed and no gutter or inset is needed at mip level 0. It cannot help a
+// mip chain, whose texels straddle the cell edge before sampling - that is
+// okf/backlog/2d-atlas-extrude.md. min/max because a flipped frame stores
+// its UVs swapped, and the inner min/max because a sub-texel frame would
+// otherwise hand clamp() a lower bound above its upper one.
 export let FRAGMENT = glsl`
   in vec2 vUv;
+  flat in vec4 vFrame;
   in vec4 vTint;
   uniform sampler2D uAtlas;
+  uniform vec4 uTint;
 
   void main() {
-    fragColor = texture(uAtlas, vUv) * vTint;
+    vec2 halfTexel = 0.5 / vec2(textureSize(uAtlas, 0));
+    vec2 lo = min(vFrame.xy, vFrame.zw) + halfTexel;
+    vec2 hi = max(vFrame.xy, vFrame.zw) - halfTexel;
+    vec2 uv = clamp(vUv, min(lo, hi), max(lo, hi));
+    fragColor = texture(uAtlas, uv) * vTint * uTint;
   }
 `
 
@@ -67,27 +99,74 @@ export let VERTEX_SPLIT = glsl`
   in vec4 iUv;
   in vec4 iTint;
   out vec2 vUv;
+  flat out vec4 vFrame;
   out vec4 vTint;
   uniform vec2 uViewport;
   uniform vec4 uCamera;
+  uniform vec4 uCameraRot;
 
   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;
+    vec2 view = (world - uCamera.xy) * uCamera.zw;
+    vec2 screen = uCameraRot.zw + vec2(view.x * uCameraRot.x - view.y * uCameraRot.y, view.x * uCameraRot.y + view.y * uCameraRot.x);
     // 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);
+    vFrame = iUv;
     vTint = iTint;
   }
 `
 
-/** The split layout: slot 0 the Pose2D record, slot 1 the style record. */
+/** The split layout: slot 0 the Pose2D record, slot 1 the style record
+ * (iRenderOrder is layout-only - see the header note). */
 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 },
+  { name: "iRenderOrder", format: "f32", slot: 1 },
 ]
+
+/** What a layer's targets draw with: the unit quad every instance reuses
+ * and the pipeline over one of the two layouts above. */
+export type SpritePipeline = { quad: BufferId; pipeline: RenderPipelineId; dispose(): void }
+
+/**
+ * Compile one sprite pipeline: `vertex` with its matching attribute list
+ * (VERTEX + INSTANCE_ATTRIBUTES, or the split pair) over the shared
+ * fragment stage, alpha-blended triangle strips. Spelled out (not the
+ * fused createPipelineTexture) so a layer's targets - its own and every
+ * view - add entries over the one pipeline. The program lives as long as
+ * the pipeline; `dispose` frees both and the quad.
+ */
+export function createSpritePipeline(label: string, vertex: string, instanceAttributes: InstanceAttribute[]): SpritePipeline {
+  // 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 vs = compileShader("vertex", vertex, { header: true })
+  let fs = compileShader("fragment", FRAGMENT, { header: true })
+  let program = linkProgram(vs, fs, { label })
+  destroyShader(vs)
+  destroyShader(fs)
+  let pipeline = createRenderPipeline(program, {
+    label,
+    topology: "triangle-strip",
+    attributes: [{ name: "aPos", format: "vec2" }],
+    instanceAttributes,
+    blend: "alpha",
+  })
+  return {
+    quad,
+    pipeline,
+    dispose() {
+      destroyRenderPipeline(pipeline)
+      destroyProgram(program)
+      destroyBuffer(quad)
+    },
+  }
+}