@solidrt/2d 0.0.70 → 0.0.72

package/src/records.ts

@@ -5,20 +5,25 @@
 // algorithm, later over earlier; `orderBy` swaps that for a core-produced
 // key order at publish, records untouched); mutations batch, and the flush
 // (ahead of the frame's paint, or at a microtask outside a frame)
-// publishes what changed: the dirty record range as one buffer write, or
-// under `orderBy` the drawn prefix whole through the zero-copy write lease
-// (the core gathers it into key order during the copy, and a byte range
-// has no stable position under a permutation). A moved sprite is 20 float
-// stores plus its share of one memcpy per dirty frame; a static layer
-// publishes nothing and therefore costs nothing.
+// publishes what changed through the core's record stream
+// (`createRecordStream` in @solidrt/core/gpu, the publish model every
+// JS-stepped population shares): the dirty record range as one buffer
+// write, or under `orderBy` the drawn prefix whole through the zero-copy
+// write lease (the core gathers it into key order during the copy, and a
+// byte range has no stable position under a permutation). A moved sprite
+// is 20 float stores plus its share of one memcpy per dirty frame; a
+// static layer publishes nothing and therefore costs nothing.
 //
 // The record vocabulary is @solidrt/3d's record mesh's, one dimension
-// down: `records(layer)` is the mirror, `updateRecords(layer, { first?,
-// count? })` publishes a range, `setRecordCount(layer, n)` dials the drawn
-// prefix. The POPULATION differs by kind and keeps its own verbs - a
-// record mesh's records are opaque data (setRecords), a record layer's
-// are sprites (addSprite/destroySprite) - so the copy-in here is
-// `records(layer).set(src)` followed by updateRecords.
+// down: `records(layer, stream?)` is the mirror (stream 0 the layer's
+// own record, 1.. the material's style streams), `updateRecords(layer, {
+// stream?, first?, count? })` publishes a range, `setRecordCount(layer,
+// n)` dials the drawn prefix, `setInstanceStyle(layer, sprite, values)`
+// and `instanceAttribute(layer, name)` write the material's per-sprite
+// style record (style.ts). The POPULATION differs by kind and keeps its
+// own verbs - a record mesh's records are opaque data (setRecords), a
+// record layer's are sprites (addSprite/destroySprite) - so the copy-in
+// here is `records(layer).set(src)` followed by updateRecords.
 //
 // 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
@@ -32,15 +37,18 @@
 // (addSprite/setSprite/...) are shared with the node layer; picking here is
 // the JS reverse walk (pointInSprite), since records have no nodes.
 import { getOwner, onBeforeRender, onCleanup, runWithOwner } from "@solidrt/core"
-import { beginBufferWrite, checkScreenSize, createBuffer, destroyBuffer, endBufferWrite, screenSizeScale, writeBuffer } from "@solidrt/core/gpu"
+import { checkScreenSize, createRecordStream, destroyBuffer, screenSizeScale } from "@solidrt/core/gpu"
 import type { BufferId } from "@solidrt/core/gpu"
+import type { AttributeAccess, ShaderParams } from "@solidrt/core/gpu"
 import { checkAtlases, frameIndex } from "./atlas.ts"
 import type { Atlas } from "./atlas.ts"
 import { fullFrame, isFrame, writeFrame } from "./frames.ts"
-import { checkTint, readFrame } from "./layer.ts"
-import type { LayerBase, Sprite, SpriteLayerOptions, SpriteOptions, SpriteState } from "./layer.ts"
+import { atlasBindings, RECORD_ATTRIBUTES } from "./glsl.ts"
+import { checkParams, checkTint, readFrame } from "./layer.ts"
+import type { LayerBase, Sprite, SpriteLayer, SpriteLayerOptions, SpriteOptions, SpriteState } from "./layer.ts"
+import { materialSamplers, unlit } from "./material.ts"
 import { pointInSprite } from "./pick.ts"
-import { createSpritePipeline, INSTANCE_ATTRIBUTES, VERTEX } from "./shaders.ts"
+import { blankStyle, createStyleStreams, growStyle, shiftStyle, writeStyle } from "./style.ts"
 import { createViews } from "./views.ts"
 
 // Floats per instance record:
@@ -83,10 +91,6 @@ export type RecordLayerOptions = Omit<SpriteLayerOptions, "orderBy"> & {
 }
 
 export type RecordLayer = LayerBase & {
-  /** The record mirror; read it through records(). Replaced by growth. */
-  _records: Float32Array
-  /** The record range [lo, hi) written since the last publish, or null. */
-  _dirty: [number, number] | null
   /** The count dial (setRecordCount): how many leading sprites draw and
    * pick; Infinity (the identity of the min against the live count)
    * until a dial is set. */
@@ -94,48 +98,129 @@ export type RecordLayer = LayerBase & {
   _order: SpriteState[]
 }
 
-/** Options of `updateRecords`: the record range (default the whole
- * mirror, capacity wide). */
-export type UpdateRecordsOptions = { first?: number; count?: number }
+/** Options of `updateRecords`: the stream (default 0, the layer's own
+ * record; 1.. the material's style streams in its instanceBuffers
+ * order) and the record range (default the whole mirror, capacity
+ * wide). */
+export type UpdateRecordsOptions = { stream?: number; first?: number; count?: number }
 
 /**
- * The layer's record mirror - the raw power path. Layout per sprite is
- * INSTANCE_FLOATS floats: [cx, cy, w, h, u0, v0, u1, v1, rot, tintR,
- * tintG, tintB, tintA, minScreenPx, maxScreenPx, atlas, outlineR,
- * outlineG, outlineB, outlineWidth], record i at i * INSTANCE_FLOATS;
- * `atlas` is the frame's texture as its index in the layer's `atlases`
- * list, and the outline is read only by a distance-field atlas (see
- * `Atlas.sdf`): rgb in 0..1 and a width in world pixels, zero for none. Record order is draw order - unless the
+ * The layer's record mirror - the raw power path. Stream 0 (the default)
+ * is the layer's own record; stream 1.. are the material's style
+ * streams in its `instanceBuffers` order, each a Float32Array over an
+ * all-float layout and bytes otherwise (write those through
+ * instanceAttribute's codecs, or a typed view of your own over the
+ * format), slot-indexed like the layer's own, blank (the material's
+ * instanceStyle) until written. On a records layer the
+ * layout per sprite is INSTANCE_FLOATS floats: [cx, cy, w, h, u0, v0, u1,
+ * v1, rot, tintR, tintG, tintB, tintA, minScreenPx, maxScreenPx, atlas,
+ * outlineR, outlineG, outlineB, outlineWidth], record i at i *
+ * INSTANCE_FLOATS; `atlas` is the frame's texture as its index in the
+ * layer's `atlases` list, and the outline is read only by a
+ * distance-field atlas (see `Atlas.sdf`): rgb in 0..1 and a width in
+ * world pixels, zero for none. 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 updateRecords the range. Read it AT USE TIME: addSprite
- * past capacity replaces the array, and a hoisted reference becomes a dead
- * copy whose writes publish nothing. Do not cache indices across
- * destroySprite - records shift. @solidrt/3d's records(mesh).
+ * i keeps meaning sprite i. Do not cache indices across destroySprite -
+ * records shift.
+ *
+ * On a node layer (createSpriteLayer) the records are its STYLE records,
+ * SPRITE_FLOATS floats per sprite slot: [u0, v0, u1, v1, tintR, tintG,
+ * tintB, tintA, renderOrder, minScreenPx, maxScreenPx, atlas, outlineR,
+ * outlineG, outlineB, outlineWidth], slot i at i * SPRITE_FLOATS (a
+ * sprite's slot is fixed for its life; a freed slot recycles) - the pose
+ * lives in the core and is written through setSprite. The 3d
+ * `records(instancedMesh)`, one dimension down: a bulk restyle (a palette
+ * cycle over thousands of sprites) is one loop over this and one
+ * updateRecords.
+ *
+ * Write fields directly for large per-frame populations, then
+ * updateRecords the range. Read it AT USE TIME: an add past capacity
+ * replaces the array, and a hoisted reference becomes a dead copy whose
+ * writes publish nothing. @solidrt/3d's records(mesh).
  */
-export function records(layer: RecordLayer): Float32Array {
-  return layer._records
+export function records(layer: RecordLayer | SpriteLayer): Float32Array
+export function records(layer: RecordLayer | SpriteLayer, stream: number): ArrayBufferView
+export function records(layer: RecordLayer | SpriteLayer, stream = 0): ArrayBufferView {
+  if (stream === 0) return layer._records
+  return styleStream("records", layer, stream).data
+}
+
+// The material style stream at index `stream` (1-based after the layer's
+// own record), or a throw naming the range.
+function styleStream(verb: string, layer: RecordLayer | SpriteLayer, stream: number) {
+  let s = layer._styles[stream - 1]
+  if (!Number.isInteger(stream) || stream < 1 || s === undefined) {
+    throw new Error(`${verb}: stream ${stream} is out of range; the layer has record streams 0..${layer._styles.length} (0 its own record, then the material's instance buffers)`)
+  }
+  return s
 }
 
 /**
- * Publish records [first, first + count) of the mirror at the layer's
+ * Write a sprite's style record - the material's per-sprite data, its
+ * FIRST instance buffer (any format; `values` one per component, in
+ * attribute order, as the shader sees them: a unorm8x4 tint as 0..1) -
+ * marking the slot for the next flush; a frame-rate path like
+ * setSprite, any number of sprites restyled between two frames
+ * costing one coalesced buffer write. Throws on a material without an
+ * instance buffer or a record of the wrong length; a no-op on a
+ * destroyed sprite. instanceAttribute + updateRecords is the same
+ * write by attribute name, and the only way into a second stream.
+ * @solidrt/3d's setInstanceStyle(instance, values).
+ */
+export function setInstanceStyle(layer: RecordLayer | SpriteLayer, sprite: Sprite, values: ArrayLike<number>): void {
+  if (sprite.layer !== layer) {
+    if (sprite.layer === null) return
+    throw new Error("setInstanceStyle: the sprite belongs to another layer")
+  }
+  let style = layer._styles[0]
+  if (style === undefined) throw new Error("setInstanceStyle: the layer's material declares no instance buffer (no style record)")
+  writeStyle(style, sprite._slot, values, "setInstanceStyle")
+  layer._schedule()
+}
+
+/**
+ * The accessor for the material's per-sprite attribute `name` over the
+ * layer's style streams: slot in (a sprite's `_slot`), component values
+ * as the shader sees them (a unorm8x4 reads and writes as 0..1),
+ * encoded through the format's codec. Write through it, then
+ * updateRecords the range of that stream; the accessor stays valid
+ * across growth. Null when no stream carries the name (the layer's own
+ * record fields are records(layer)'s, not reachable here).
+ * @solidrt/3d's instanceAttribute(mesh, name).
+ */
+export function instanceAttribute(layer: RecordLayer | SpriteLayer, name: string): AttributeAccess | null {
+  for (let s of layer._styles) {
+    let i = s.layout.findIndex(a => a.name === name)
+    if (i >= 0) return s.fields[i]!
+  }
+  return null
+}
+
+/**
+ * Publish records [first, first + count) of a mirror (`stream` 0 the
+ * layer's own record, 1.. the material's style streams) at the layer's
  * next flush - the partial rewrite a population stepped in JS wants (ten
  * moved records of ten thousand cost ten); the whole mirror by default.
  * Write the mirror first, through records(), then call this. The range
  * is against the mirror's capacity, not the live sprites: a record past
- * the last live sprite is accepted and never drawn. Under `orderBy` any
- * range republishes the drawn prefix whole - the core gathers it into
- * key order, and a byte range has no stable position under a
- * permutation. @solidrt/3d's updateRecords(mesh).
+ * the last live sprite (on a node layer, past the highest slot in use)
+ * is accepted and never drawn. Under `orderBy` any range republishes the
+ * drawn prefix whole - the core gathers it into key order, and a byte
+ * range has no stable position under a permutation. @solidrt/3d's
+ * updateRecords(mesh).
  */
-export function updateRecords(layer: RecordLayer, options: UpdateRecordsOptions = {}): void {
-  let capacity = layer._records.length / INSTANCE_FLOATS
+export function updateRecords(layer: RecordLayer | SpriteLayer, options: UpdateRecordsOptions = {}): void {
+  let index = options.stream ?? 0
+  let stream = index === 0 ? layer._stream : styleStream("updateRecords", layer, index).stream
+  let capacity = stream.capacity
   let first = options.first ?? 0
   let count = options.count ?? capacity - first
   if (!Number.isInteger(first) || !Number.isInteger(count) || first < 0 || count < 0 || first + count > capacity) {
     throw new Error("updateRecords: range [" + first + ", " + (first + count) + ") is outside the layer's " + capacity + " records")
   }
-  if (count > 0) markRecords(layer, first, first + count)
+  if (count === 0) return
+  stream.mark(first, first + count)
+  layer._schedule()
 }
 
 /**
@@ -154,14 +239,10 @@ export function setRecordCount(layer: RecordLayer, count: number): void {
   layer._schedule()
 }
 
-// Extend the layer's dirty range over records [lo, hi) and schedule the
-// flush that publishes it.
-function markRecords(layer: RecordLayer, lo: number, hi: number): void {
-  if (layer._dirty === null) layer._dirty = [lo, hi]
-  else {
-    if (lo < layer._dirty[0]) layer._dirty[0] = lo
-    if (hi > layer._dirty[1]) layer._dirty[1] = hi
-  }
+// Mark records [lo, hi) of the layer's stream and schedule the flush that
+// publishes them.
+function markRecords(layer: RecordLayer | SpriteLayer, lo: number, hi: number): void {
+  layer._stream.mark(lo, hi)
   layer._schedule()
 }
 
@@ -179,12 +260,15 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
     throw new Error(`createRecordLayer: capacity must be a positive integer, got ${capacity}`)
   }
   let label = opts?.label ?? "sprites"
-  let buffer: BufferId = createBuffer(capacity * RECORD_BYTES, {
-    label: `${label}-records`,
-    autoFree: false,
-  })
+  let stream = createRecordStream(RECORD_BYTES, capacity, { label: `${label}-records`, autoFree: false })
   let tint = opts?.tint ?? [1, 1, 1, 1]
   checkTint("createRecordLayer", tint)
+  let material = opts?.material ?? unlit()
+  checkAtlases("createRecordLayer", atlases, materialSamplers(material))
+  let params: ShaderParams = { ...material.params, ...opts?.params }
+  // The material's style streams, after the layer's own record: the
+  // same publish, the same growth, the same shift on destroy.
+  let styles = createStyleStreams(material, capacity, label)
   let orderBy = opts?.orderBy
   let instanceOrder =
     orderBy === undefined
@@ -193,7 +277,9 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
         ? { field: Y_FIELD_OFFSET }
         : { field: orderBy.field, descending: orderBy.descending }
   let ordered = instanceOrder !== undefined
-  let gpu = createSpritePipeline(label, VERTEX, [INSTANCE_ATTRIBUTES], opts?.blend ?? "alpha", atlases)
+  let gpu = material.pipeline(atlases, [RECORD_ATTRIBUTES], label)
+  // The instance buffers in pipeline order after the quad.
+  let buffers = () => [stream.buffer, ...styles.map(s => s.stream.buffer)]
 
   let disposed = false
   let scheduled = false
@@ -215,60 +301,53 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
 
   // How many leading sprites draw: the dial against the live count.
   let drawn = () => Math.min(layer._dial, layer._order.length)
-  // Publish the first `n` records whole through the write lease: a
-  // replacement buffer's first fill (its contents are unspecified), and
-  // every publish of an ordered layer (the gather runs in the copy).
-  let publishWhole = (target: BufferId, n: number) => {
-    let out = beginBufferWrite(target)
-    out.set(layer._records.subarray(0, n * INSTANCE_FLOATS))
-    endBufferWrite(target, n * RECORD_BYTES)
-  }
 
-  // The GPU buffer's record capacity; the mirror grows ahead of it
-  // (addSprite) and the flush catches the buffer up: a larger buffer is
-  // created, written in full, swapped in, and the old one destroyed. The
-  // entries hold the old buffer alive until the swaps land, so the destroy
-  // is safe to issue right after.
-  let gpuCapacity = capacity
+  // The buffers growth replaced since the last flush (addSprite grows the
+  // stream at once; the views still draw from the first of these until the
+  // flush swaps the replacement in). The entries hold a swapped-out buffer
+  // alive until the swap lands, so the destroys are safe to issue right
+  // after.
+  let grownFrom: BufferId[] = []
   let flush = () => {
     scheduled = false
     if (disposed) return
-    let dirty = layer._dirty
-    layer._dirty = null
-    let mirror = layer._records
     let live = layer._order.length
     let count = drawn()
-    if (mirror.length > gpuCapacity * INSTANCE_FLOATS) {
-      gpuCapacity = mirror.length / INSTANCE_FLOATS
-      let grown = createBuffer(mirror.length * Float32Array.BYTES_PER_ELEMENT, { label: `${label}-records`, autoFree: false })
-      // The replacement is filled whole before the swap (the entry must
+    if (grownFrom.length > 0) {
+      // The replacements are filled whole before the swap (the entry must
       // never point at an unwritten buffer): the live prefix, or under
       // orderBy the drawn one, which is all the gather may see.
-      publishWhole(grown, ordered ? count : live)
-      views.setBuffers([grown])
+      stream.publish(true, ordered ? count : live)
+      for (let s of styles) s.stream.publish(true, ordered ? count : live)
+      views.setBuffers(buffers())
       views.setCount(count)
       if (ordered) {
         // That publish landed BEFORE the swap, so the order had not yet
-        // followed to the grown buffer and it went out ungathered. One
+        // followed to the grown buffers and it went out ungathered. One
         // more publish, now under the swapped-in order, restores key
         // order - growth frames only.
-        publishWhole(grown, count)
+        stream.publish(true, count)
+        for (let s of styles) s.stream.publish(true, count)
       }
-      destroyBuffer(buffer)
-      buffer = grown
+      for (let old of grownFrom) destroyBuffer(old)
+      grownFrom.length = 0
       published = count
       return
     }
     if (ordered) {
       // The gathered set IS the drawn prefix: a dirty record or a moved
-      // dial republishes it whole.
-      if (dirty !== null || count !== published) publishWhole(buffer, count)
-    } else if (dirty !== null) {
+      // dial republishes it whole, every stream alike (the core gathers
+      // them under one permutation).
+      if (stream.dirty || count !== published) {
+        stream.publish(true, count)
+        for (let s of styles) s.stream.publish(true, count)
+      }
+    } else {
       // The dirty range, clipped to the live sprites (a record past them
-      // is never drawn): one partial write at its byte offset.
-      let lo = dirty[0]
-      let hi = Math.min(dirty[1], live)
-      if (hi > lo) writeBuffer(buffer, mirror.subarray(lo * INSTANCE_FLOATS, hi * INSTANCE_FLOATS), lo * RECORD_BYTES)
+      // is never drawn): one partial write at its byte offset, per
+      // dirty stream.
+      stream.publish(false, live)
+      for (let s of styles) s.stream.publish(false, live)
     }
     if (count !== published) {
       views.setCount(count)
@@ -334,16 +413,18 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
     label,
     pipeline: gpu.pipeline,
     quad: gpu.quad,
-    atlases: atlases.map(a => a.texture),
-    buffers: () => [buffer],
+    textures: { ...atlasBindings(atlases.map(a => a.texture)), ...material.textures },
+    buffers,
     count: () => published,
     tint: () => tint,
+    params: () => params,
     pick: (x, y, zoom) => layer.pick(x, y, zoom),
     order: instanceOrder,
   })
 
   let layer: RecordLayer = {
     atlases,
+    material,
     get count() {
       return layer._order.length
     },
@@ -353,6 +434,12 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
       tint = next
       views.setTint(next)
     },
+    setParams(next) {
+      if (disposed) return
+      checkParams("setParams", next)
+      Object.assign(params, next)
+      views.setParams(next)
+    },
     createView(vopts) {
       if (disposed) throw new Error("createView: layer is disposed")
       return views.create(vopts)
@@ -383,8 +470,10 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
       for (let sprite of layer._order) sprite.layer = null
       layer._order.length = 0
       views.dispose()
-      destroyBuffer(buffer)
-      gpu.dispose()
+      for (let old of grownFrom) destroyBuffer(old)
+      grownFrom.length = 0
+      stream.destroy()
+      for (let s of styles) s.stream.destroy()
     },
     _add(opts) {
       if (opts?.parent) {
@@ -407,12 +496,13 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
       }
       let atlas = checkWrite("addSprite", record)
       let index = layer._order.length
-      if ((index + 1) * INSTANCE_FLOATS > layer._records.length) {
-        // Growth replaces the mirror (doubling); the flush catches the GPU
-        // buffer up with a whole publish.
-        let next = new Float32Array(layer._records.length * 2)
-        next.set(layer._records)
-        layer._records = next
+      if (index + 1 > stream.capacity) {
+        // Growth replaces the mirrors and the buffers (doubling); the
+        // flush fills the replacements whole and swaps them in.
+        let next = stream.capacity * 2
+        grownFrom.push(stream.grow(next))
+        for (let s of styles) grownFrom.push(growStyle(s, next))
+        layer._records = new Float32Array(stream.bytes.buffer)
       }
       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)
@@ -420,6 +510,8 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
       // No outline until a raw writer sets one: the slot may hold a
       // shifted-out sprite's record otherwise.
       layer._records.fill(0, index * INSTANCE_FLOATS + OUTLINE_FIELD_OFFSET, index * INSTANCE_FLOATS + OUTLINE_FIELD_OFFSET + 4)
+      // The material's style slot starts blank for the same reason.
+      for (let s of styles) blankStyle(s, index)
       markRecords(layer, index, index + 1)
       return sprite
     },
@@ -459,6 +551,7 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
       let r = layer._records
       let last = order.length - 1
       r.copyWithin(index * INSTANCE_FLOATS, (index + 1) * INSTANCE_FLOATS, order.length * INSTANCE_FLOATS)
+      if (index < last) for (let s of styles) shiftStyle(s, index + 1, order.length)
       order.splice(index, 1)
       for (let i = index; i < order.length; i++) order[i]!._slot = i
       if (index < last) markRecords(layer, index, last)
@@ -469,8 +562,9 @@ export function createRecordLayer(atlases: Atlas[], opts?: RecordLayerOptions):
       scheduled = true
       RESOLVED.then(flush)
     },
-    _records: new Float32Array(capacity * INSTANCE_FLOATS),
-    _dirty: null,
+    _stream: stream,
+    _records: new Float32Array(stream.bytes.buffer),
+    _styles: styles,
     _dial: Infinity,
     _order: [],
   }

package/src/style.ts

@@ -0,0 +1,98 @@
+// A material's style streams on a layer: one core record stream per
+// instance buffer the material declares (createRecordStream: the GPU
+// buffer, the byte mirror, the dirty range and the range-or-whole
+// publish), bound after the layer's own records, each slot starting as
+// the material's blank record. The node layer and the records layer
+// hold them beside their own stream and publish them in the same flush
+// (the tile layer bakes per chunk and keeps plain arrays, tiles.ts);
+// the shared verbs (setInstanceStyle, instanceAttribute, records,
+// updateRecords in records.ts) write through the accessors here. The
+// codecs are core's (vertex.ts), the same ones @solidrt/3d's instance
+// streams encode through.
+import { createRecordStream, isFloatLayout, layoutFields, layoutStride, layoutView, writeRecord } from "@solidrt/core/gpu"
+import type { AttributeAccess, BufferId, RecordStream, VertexAttribute } from "@solidrt/core/gpu"
+import { materialBlank } from "./material.ts"
+import type { Material } from "./material.ts"
+
+/** One style stream: the layout, the core stream behind it, the blank a
+ * fresh slot copies, the accessors (valid across growth), and the
+ * mirror's view as the layout wants it (re-derived by growth: read it
+ * at use time). */
+export type StyleStream = {
+  layout: VertexAttribute[]
+  stream: RecordStream
+  blank: Uint8Array
+  fields: AttributeAccess[]
+  /** A Float32Array over an all-float layout, bytes otherwise. */
+  data: ArrayBufferView
+  /** The float view writeRecord stores through on an all-float layout,
+   * null otherwise. */
+  _floats: Float32Array | null
+  _view: DataView
+}
+
+/** The material's style streams for a layer of `capacity` slots: empty
+ * without instance buffers. */
+export function createStyleStreams(material: Material, capacity: number, label: string): StyleStream[] {
+  let out: StyleStream[] = []
+  material.instanceBuffers?.forEach((buffer, i) => {
+    let layout = buffer.attributes
+    let stream = createRecordStream(layoutStride(layout), capacity, { label: `${label}-style${i}`, autoFree: false })
+    let style: StyleStream = {
+      layout,
+      stream,
+      blank: materialBlank(material, i),
+      fields: [],
+      data: new Uint8Array(0),
+      _floats: null,
+      _view: new DataView(new ArrayBuffer(0)),
+    }
+    viewStyle(style)
+    style.fields = layoutFields(layout, () => style._view)
+    // Every slot starts blank: a material's instanceStyle is what an
+    // unwritten sprite shows, not zeros.
+    for (let slot = 0; slot < capacity; slot++) stream.bytes.set(style.blank, slot * stream.stride)
+    out.push(style)
+  })
+  return out
+}
+
+// Point the views at the stream's current mirror.
+function viewStyle(style: StyleStream): void {
+  let buffer = style.stream.bytes.buffer
+  style.data = layoutView(style.layout, buffer)
+  style._floats = isFloatLayout(style.layout) ? (style.data as Float32Array) : null
+  style._view = new DataView(buffer)
+}
+
+/** Grow a style stream to `next` slots (the new slots blank) and return
+ * the old buffer for the caller to destroy once its draws point at the
+ * new one. */
+export function growStyle(style: StyleStream, next: number): BufferId {
+  let previous = style.stream.capacity
+  let old = style.stream.grow(next)
+  for (let slot = previous; slot < next; slot++) style.stream.bytes.set(style.blank, slot * style.stream.stride)
+  viewStyle(style)
+  return old
+}
+
+/** Reset slot `slot` to the blank record and mark it. */
+export function blankStyle(style: StyleStream, slot: number): void {
+  style.stream.bytes.set(style.blank, slot * style.stream.stride)
+  style.stream.mark(slot, slot + 1)
+}
+
+/** Encode `values` (one per component, in layout order, as the shader
+ * sees them) into slot `slot` and mark it. */
+export function writeStyle(style: StyleStream, slot: number, values: ArrayLike<number>, site: string): void {
+  writeRecord(style.layout, style.fields, style._floats, slot, values, site)
+  style.stream.mark(slot, slot + 1)
+}
+
+/** Shift slots [from, to) down to `from - 1` (a records layer's destroy)
+ * and mark the moved range. */
+export function shiftStyle(style: StyleStream, from: number, to: number): void {
+  let stride = style.stream.stride
+  style.stream.bytes.copyWithin((from - 1) * stride, from * stride, to * stride)
+  style.stream.mark(from - 1, to - 1)
+}