@solidrt/2d 0.0.55 → 0.0.56

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.tsx
+// 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.
 //
@@ -30,33 +32,63 @@ import {
   setTargetSize,
 } from "@solidrt/core/gpu"
 import type { BufferId, TextureId } from "@solidrt/core/gpu"
+import { checkCamera, projectCamera, unprojectCamera } from "./camera.ts"
 import { FULL_FRAME, writeFrame } from "./frames.ts"
-import { readFrame, spriteDispatch } from "./layer.ts"
-import type { LayerBase, Sprite, SpriteHandlers, SpriteLayerOptions, SpriteOptions } from "./layer.ts"
+import { spriteDispatch } from "./dispatch.ts"
+import { checkTint, readFrame } from "./layer.ts"
+import type { LayerBase, LayerPointerListener, Sprite, SpriteHandlers, SpriteLayerOptions, SpriteOptions, SpriteState } from "./layer.ts"
 import { pointInSprite } from "./pick.ts"
-import { checkOversample } from "./oversample.ts"
+import { checkOversample, thrashSentinel } from "./oversample.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
 
+// 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[]
 }
 
 /**
@@ -69,7 +101,7 @@ export function createRecordLayer(
   width: number,
   height: number,
   atlas: TextureId,
-  opts?: SpriteLayerOptions,
+  opts?: RecordLayerOptions,
 ): RecordLayer {
   let capacity = opts?.capacity ?? 1024
   if (!(capacity > 0 && Number.isInteger(capacity))) {
@@ -87,12 +119,22 @@ export function createRecordLayer(
   })
   let oversample = opts?.oversample ?? 1
   checkOversample("createRecordLayer", oversample, width, height)
+  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 thrash = thrashSentinel(`record layer "${label}"`)
   let texture = createPipelineTexture(
     VERTEX,
     FRAGMENT,
     width * oversample,
     height * oversample,
-    { uViewport: [width, height], uCamera: [0, 0, 1, 1] },
+    { uViewport: [width, height], uCamera: [0, 0, 1, 1], uCameraRot: [1, 0, 0, 0], uTint: tint },
     {
       label,
       topology: "triangle-strip",
@@ -101,6 +143,7 @@ export function createRecordLayer(
       buffer: quad,
       instanceAttributes: INSTANCE_ATTRIBUTES,
       instanceBuffer: records,
+      instanceOrder,
       instanceCount: 0,
       blend: "alpha",
       textures: { uAtlas: atlas },
@@ -113,6 +156,9 @@ export function createRecordLayer(
   let camX = 0
   let camY = 0
   let camZoom = 1
+  let camRot = 0
+  let camPivotX = 0
+  let camPivotY = 0
   let disposed = false
   let dirty = false
   let scheduled = false
@@ -140,6 +186,16 @@ export function createRecordLayer(
     endBufferWrite(target, count * FLOATS_PER_SPRITE * 4)
     if (grown !== null) {
       setDraw(texture, { instanceBuffer: grown, instanceCount: 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
@@ -150,7 +206,13 @@ export function createRecordLayer(
   }
 
   // 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,11 +239,7 @@ export function createRecordLayer(
     }
   }
 
-  let dispatch = spriteDispatch({
-    size: () => [width, height],
-    camera: () => [camX, camY, camZoom],
-    pick: (x, y) => layer.pick(x, y),
-  })
+  let listeners = new Set<LayerPointerListener>()
 
   let layer: RecordLayer = {
     texture,
@@ -189,6 +247,12 @@ export function createRecordLayer(
     get count() {
       return layer._order.length
     },
+    get width() {
+      return width
+    },
+    get height() {
+      return height
+    },
     setSize(w, h) {
       if (disposed || (w === width && h === height)) return
       checkOversample("setSize", oversample, w, h)
@@ -197,35 +261,61 @@ export function createRecordLayer(
       setTargetSize(texture, w * oversample, h * oversample)
       setTargetParams(texture, { uViewport: [w, h] })
     },
+    listen(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
     get oversample() {
       return oversample
     },
     setOversample(n) {
       if (disposed || n === oversample) return
       checkOversample("setOversample", n, width, height)
+      thrash()
       oversample = n
       setTargetSize(texture, width * n, height * n)
     },
     setCamera(update) {
       if (disposed) return
+      checkCamera(update)
       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] })
+      if (update.zoom !== undefined) camZoom = update.zoom
+      if (update.rotation !== undefined) camRot = update.rotation
+      if (update.pivotX !== undefined) camPivotX = update.pivotX
+      if (update.pivotY !== undefined) camPivotY = update.pivotY
+      setTargetParams(texture, {
+        uCamera: [camX, camY, camZoom, camZoom],
+        uCameraRot: [Math.cos(camRot), Math.sin(camRot), camPivotX, camPivotY],
+      })
+    },
+    camera() {
+      return { x: camX, y: camY, zoom: camZoom, rotation: camRot, pivotX: camPivotX, pivotY: camPivotY }
+    },
+    project(x, y) {
+      return projectCamera(layer.camera(), x, y)
+    },
+    unproject(x, y) {
+      return unprojectCamera(layer.camera(), x, y)
+    },
+    setTint(next) {
+      if (disposed) return
+      checkTint("setTint", next)
+      setTargetParams(texture, { uTint: next })
     },
     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
+      return out
     },
     handlersFor(layout) {
       return dispatch(layout)
@@ -233,6 +323,7 @@ export function createRecordLayer(
     dispose() {
       if (disposed) return
       disposed = true
+      listeners.clear()
       for (let sprite of layer._order) sprite.layer = null
       layer._order.length = 0
       destroyTexture(texture)
@@ -249,7 +340,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 +372,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,11 +397,21 @@ export function createRecordLayer(
       RESOLVED.then(flush)
     },
     records: new Float32Array(capacity * FLOATS_PER_SPRITE),
+    withRecords(fn) {
+      return fn(layer.records)
+    },
     touch() {
       layer._schedule()
     },
     _order: [],
   }
+  let dispatch = spriteDispatch({
+    size: () => [width, height],
+    camera: () => layer.camera(),
+    pick: (x, y) => layer.pick(x, y),
+    root: layer,
+    listeners,
+  })
   layer.handlers = dispatch(null)
 
   if (opts?.autoFree !== false && getOwner()) onCleanup(() => layer.dispose())

package/src/shaders.ts

@@ -1,18 +1,25 @@
 // 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.
+//   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 { glsl } from "@solidrt/core/gpu"
 import type { InstanceAttribute, VertexAttribute } from "@solidrt/core/gpu"
 
@@ -27,12 +34,14 @@ export let VERTEX = glsl`
   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);
@@ -40,13 +49,17 @@ export let VERTEX = glsl`
   }
 `
 
+// 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).
 export let FRAGMENT = glsl`
   in vec2 vUv;
   in vec4 vTint;
   uniform sampler2D uAtlas;
+  uniform vec4 uTint;
 
   void main() {
-    fragColor = texture(uAtlas, vUv) * vTint;
+    fragColor = texture(uAtlas, vUv) * vTint * uTint;
   }
 `
 
@@ -70,12 +83,14 @@ export let VERTEX_SPLIT = glsl`
   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);
@@ -83,11 +98,13 @@ export let VERTEX_SPLIT = glsl`
   }
 `
 
-/** 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 },
 ]