@solidrt/2d 0.0.71 → 0.0.73

package/src/layer.ts

@@ -12,19 +12,27 @@
 //
 // Two instance-buffer slots split ownership: slot 0 is the pose buffer,
 // written ONLY by the core (one coalesced write per flush however many
-// nodes moved); slot 1 is the style buffer [u0, v0, u1, v1, tint rgba,
-// renderOrder, minScreenPx, maxScreenPx, atlas], JS-owned and published
-// through the zero-copy write lease. Never write the pose buffer from JS -
-// the core's staging mirror is the owner and will overwrite. For motion
-// only JS can compute at large populations, the records layer (records.ts)
+// nodes moved); slot 1 is the SPRITE record [u0, v0, u1, v1, tint rgba,
+// renderOrder, minScreenPx, maxScreenPx, atlas, outline], JS-owned
+// through the sprite verbs and published through the zero-copy write
+// lease. After them come the MATERIAL's style streams (style.ts), one
+// per instance buffer its material declares: app-owned per-sprite data
+// in any vertex format, written with setInstanceStyle, instanceAttribute
+// or records(layer, stream). Never write the pose buffer from JS - the
+// core's staging mirror is the owner and will overwrite. For motion only
+// JS can compute at large populations, the records layer (records.ts)
 // is the escape hatch.
 //
 // A layer draws from the ATLASES it declares at creation, bound together
-// as one draw: every frame carries its texture, the style record stores
-// that texture's index in the list, and the generated fragment stage
-// (shaders.ts) picks the sampler per instance - so sprites from several
-// sheets interleave freely in one draw, key order included, and a frame
-// from a sheet the layer did not declare throws at the write.
+// as one draw: every frame carries its texture, the sprite record stores
+// that texture's index in the list, and the fragment set generated for
+// the list (glsl.ts) picks the sampler per instance - so sprites from
+// several sheets interleave freely in one draw, key order included, and
+// a frame from a sheet the layer did not declare throws at the write.
+// What the pixels look like is the layer's MATERIAL (material.ts): the
+// stock `unlit()` unless the options name one, which owns the pipeline
+// (its blend, its program over the layer's set) and whose params and
+// textures every view seeds.
 //
 // Sprites hold FIXED instance slots (freed slots recycle): draw order is
 // slot order, so removal never shifts records and pose sinks never rebind.
@@ -36,7 +44,7 @@
 import { getOwner, onBeforeRender, onCleanup, runWithOwner } from "@solidrt/core"
 import type { PointerEvent as ElementPointerEvent, WheelEvent as ElementWheelEvent } from "@solidrt/core"
 import { checkScreenSize, createBuffer, createRecordStream, destroyBuffer, screenSizeScale } from "@solidrt/core/gpu"
-import type { BlendMode, BufferId, RecordStream, TextureId } from "@solidrt/core/gpu"
+import type { BufferId, RecordStream, ShaderParams, TextureId } from "@solidrt/core/gpu"
 import * as spatial from "flux:spatial"
 import type {
   Impact as CoreImpact,
@@ -56,7 +64,11 @@ import type { Frame } from "./frames.ts"
 import { fullFrame, isFrame, writeFrame } from "./frames.ts"
 import type { RecordLayer } from "./records.ts"
 import { floorReach, pointInSprite } from "./pick.ts"
-import { createSpritePipeline, INSTANCE_LAYOUTS_SPLIT, VERTEX_SPLIT } from "./shaders.ts"
+import { atlasBindings, POSE_ATTRIBUTES, SPRITE_ATTRIBUTES } from "./glsl.ts"
+import { materialSamplers, unlit } from "./material.ts"
+import type { Material } from "./material.ts"
+import { blankStyle, createStyleStreams, growStyle } from "./style.ts"
+import type { StyleStream } from "./style.ts"
 import { createViews } from "./views.ts"
 import type { ViewHandle, ViewOptions } from "./views.ts"
 
@@ -65,24 +77,24 @@ export const POSE_FLOATS = 5
 
 // Float offset of world y in a pose record - what `orderBy: "y"` keys on.
 const POSE_Y_FIELD = 1
-/** Floats per style record:
+/** Floats per sprite record (the node layer's slot 1, SPRITE_ATTRIBUTES):
  * [u0, v0, u1, v1, tintR, tintG, tintB, tintA, renderOrder, minScreenPx,
  * maxScreenPx, atlas, outlineR, outlineG, outlineB, outlineWidth]. */
-export const STYLE_FLOATS = 16
+export const SPRITE_FLOATS = 16
 
-// Float offset of renderOrder in a style record - what `orderBy: "renderOrder"`
+// Float offset of renderOrder in a sprite record - what `orderBy: "renderOrder"`
 // keys on.
-const STYLE_KEY_FIELD = 8
-// Float offsets of the screen-size clamp in a style record.
-const STYLE_MIN_PX_FIELD = 9
-const STYLE_MAX_PX_FIELD = 10
+const SPRITE_KEY_FIELD = 8
+// Float offsets of the screen-size clamp in a sprite record.
+const SPRITE_MIN_PX_FIELD = 9
+const SPRITE_MAX_PX_FIELD = 10
 // Float offset of the outline (rgb plus width in world pixels) a
 // distance-field atlas draws under the sprite; text runs write it, a
 // colour atlas ignores it.
-const STYLE_OUTLINE_FIELD = 12
+const SPRITE_OUTLINE_FIELD = 12
 // Float offset of the atlas sampler index (the frame's texture's position
 // in the layer's atlas list).
-const STYLE_ATLAS_FIELD = 11
+const SPRITE_ATLAS_FIELD = 11
 
 const RESOLVED = Promise.resolve()
 
@@ -287,7 +299,7 @@ export type SpriteOptions = {
   /**
    * Show or hide the sprite (default true), @solidrt/3d's setVisible in
    * the setSprite bag: hidden, its pose slot zeroes (nothing drawn) and
-   * pick/pickRect skip it; the handle, slot, style records and any
+   * pick/pickRect skip it; the handle, slot, sprite records and any
    * running transition state stay, so showing again restores the sprite
    * as it was. Node layer only - a record sprite has no node (hide it by
    * zeroing w or h); setting this there throws.
@@ -320,6 +332,9 @@ export type LayerEventBase = {
   predicted: boolean
   pointerId: number
   pointerType: string
+  /** The pressed button on a down, up or tap (0 = primary, 2 = secondary;
+   * touch is always 0), as the element event carries it; absent on a
+   * move, cancel or wheel. */
   button?: number
   shiftKey: boolean
   ctrlKey: boolean
@@ -378,10 +393,10 @@ type TapFields = {
 export type SpriteWheelEvent = SpritePointerEvent & WheelFields
 export type LayerWheelEvent = LayerPointerEvent & WheelFields
 /**
- * A press that released on the target it pressed without travelling past
- * the slop, the only pointer down for its whole press (a pinch never taps).
- * Dispatched after the up, bubbling the same way; `x`/`y` are the release
- * point.
+ * A primary-button press (DOM click: a right click never taps) that
+ * released on the target it pressed without travelling past the slop, the
+ * only pointer down for its whole press (a pinch never taps). Dispatched
+ * after the up, bubbling the same way; `x`/`y` are the release point.
  */
 export type SpriteTapEvent = SpritePointerEvent & TapFields
 export type LayerTapEvent = LayerPointerEvent & TapFields
@@ -415,6 +430,17 @@ export function checkTint(verb: string, tint: [number, number, number, number]):
   }
 }
 
+/** Validate a params record (throws - the dev validation policy): a
+ * plain object of finite numbers or number lists. Internal - every
+ * layer kind's setParams calls it. */
+export function checkParams(verb: string, params: ShaderParams): void {
+  if (typeof params !== "object" || params === null || Array.isArray(params)) throw new Error(`${verb}: params must be an object of uniform values, got ${JSON.stringify(params)}`)
+  for (let [name, value] of Object.entries(params)) {
+    let ok = typeof value === "number" ? Number.isFinite(value) : Array.isArray(value) && value.length > 0 && value.every(Number.isFinite)
+    if (!ok) throw new Error(`${verb}: ${name} must be a finite number or a list of them, got ${JSON.stringify(value)}`)
+  }
+}
+
 export type SpriteLayerOptions = {
   /**
    * Initial slot reservation; default 1024. The layer grows past it on
@@ -427,13 +453,25 @@ export type SpriteLayerOptions = {
    * setTint. */
   tint?: [number, number, number, number]
   /**
-   * How the sprites blend into the layer's targets, core gpu's BlendMode;
-   * default "alpha" (premultiplied source-over in draw order). "add" for
-   * glows, explosions and additive particles, "multiply" to darken, "none"
-   * to overwrite. Pipeline state, fixed at creation: an additive layer is
-   * a second layer over the same atlas.
+   * What the sprites look like: the layer's material (material.ts),
+   * fixed at creation - its pipeline (the blend mode, its program over
+   * the layer's atlases), its params and its textures on every view,
+   * its instance buffers as per-sprite style streams after the layer's
+   * own records. Default `unlit()`: the atlas texel times the tints,
+   * alpha-blended in draw order. An additive glow layer is
+   * `material: unlit({ blend: "add" })` over the same atlases; a look is
+   * `unlit({ prelude, surface })` or a shaderMaterialClass instance. The
+   * material sits on the LAYER because the layer is the batch - two
+   * looks are two layers, which is also how you order them.
    */
-  blend?: BlendMode
+  material?: Material
+  /**
+   * Uniform values seeded on every view of the layer over the
+   * material's own (a prelude's uniforms: a flash amount, a palette
+   * row, a clock); see setParams. Names the program does not declare
+   * are skipped.
+   */
+  params?: ShaderParams
   /** Names the GPU resources (buffers, pipeline; views default to
    * `<label>-view`); default "sprites". */
   label?: string
@@ -443,17 +481,21 @@ export type SpriteLayerOptions = {
    * group's `stagger` (a group declaring its own wins for what is under
    * it). See setStagger. */
   stagger?: number
+  /** The rate the layer's native motion runs at (setTimeScale at
+   * creation): 0 freezes every sprite and group transition, 1 is app
+   * time; a group declaring its own wins for what is under it. */
+  timeScale?: number
   /** Skip the owner-scoped auto-dispose (see createSpriteLayer). */
   autoFree?: boolean
   /**
    * Draw sprites in KEY order instead of slot order, produced by core at
-   * every publish (the gpu `instanceOrder` primitive across the pose/style
+   * every publish (the gpu `instanceOrder` primitive across the pose/sprite
    * buffer pair - no per-sprite JS anywhere): `"y"` keys on the sprite's
    * WORLD y, the pose the core itself writes, so a perspective crowd
    * paints back to front (smaller y = further up the screen = drawn
    * first) - and because the key is core-owned, sprites moved by native
    * transitions or any other core producer re-sort with zero JS per
-   * frame. Slots stay fixed - handles, picking and the style records are
+   * frame. Slots stay fixed - handles, picking and the sprite records are
    * untouched, only the draw order changes - and ties keep slot order, so
    * sprites at equal y draw exactly as without it.
    *
@@ -551,6 +593,9 @@ export type LayerBase = {
    * in draw order.
    */
   readonly atlases: readonly Atlas[]
+  /** The material the layer draws with, as declared at creation (the
+   * stock `unlit()` when none was). */
+  readonly material: Material
   /** Live sprite count. */
   readonly count: number
   /**
@@ -562,6 +607,16 @@ export type LayerBase = {
    * kinds.
    */
   setTint(tint: [number, number, number, number]): void
+  /**
+   * Write uniform values to every view of the layer (one shared-params
+   * write per view, cheap to animate): the material's prelude uniforms
+   * - a flash amount, a palette row, a scroll offset, a clock - over the
+   * material's own `params`; @solidrt/3d's setMeshParams one dimension
+   * down, the layer being the draw entry. Absent names keep their
+   * values; a name the program does not declare is skipped. Views
+   * created later seed from the merged record.
+   */
+  setParams(params: ShaderParams): void
   /** Every shown sprite whose rotated rect contains the layer-pixel point
    * (a hidden sprite or subtree is never hit), topmost first - the
    * all-hits shape of @solidrt/3d's pick; `pick(x, y)[0]` is the topmost.
@@ -592,12 +647,16 @@ export type LayerBase = {
   _destroy(sprite: SpriteState): void
   _schedule(): void
   /** The layer's JS-owned record stream, what records()/updateRecords
-   * read and mark: a records layer's whole records, a node layer's style
-   * records (its poses are the core's). Internal. */
+   * read and mark: a records layer's whole records, a node layer's
+   * sprite records (its poses are the core's). Internal. */
   _stream: RecordStream
   /** The stream's mirror as floats, re-pointed by growth; records() hands
    * it out. Internal. */
   _records: Float32Array
+  /** The material's style streams, one per instance buffer it declares,
+   * in its order; what setInstanceStyle, instanceAttribute, records(layer,
+   * stream) and updateRecords reach. Internal. */
+  _styles: StyleStream[]
 }
 
 /** A query volume for overlap/sweep/moveAndSlide, in layer pixels: a
@@ -726,6 +785,20 @@ export type SpriteLayer = LayerBase & {
    * straight under the layer that begin in one frame (SpriteLayerOptions
    * `stagger`). */
   setStagger(ms: number | null): void
+  /** Set (or with null clear) the time scale on the layer's root: the
+   * rate every sprite and group transition in the layer runs at, with
+   * their delays, enters, exits and stagger slots - 0 a pause that leaves
+   * the app's UI moving, 1 app time, other values slow or fast motion
+   * (SpriteLayerOptions `timeScale`). The nearest declaring node wins:
+   * a group or sprite with its own (setGroupTimeScale,
+   * setSpriteTimeScale) keeps its rate inside a frozen layer. A frozen
+   * layer asks for no frames; this write brings the one that resumes it.
+   * Not covered: frame animations (createAnimation), which are JS clocks
+   * on app time unless given this layer as their `clock`, and the app's
+   * own onFrame logic, which multiplies its step by `timeRate()`. */
+  setTimeScale(scale: number | null): void
+  /** The rate the layer's root runs at (setTimeScale); 1 after dispose. */
+  timeRate(): number
   /** The core node every sprite and group of the layer sits under: what
    * scopes the layer's queries in the arena shared with 3d scenes. */
   _root: NodeId
@@ -833,14 +906,22 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
   let label = opts?.label ?? "sprites"
   let tint = opts?.tint ?? [1, 1, 1, 1]
   checkTint("createSpriteLayer", tint)
+  let material = opts?.material ?? unlit()
+  checkAtlases("createSpriteLayer", atlases, materialSamplers(material))
+  // The params every view seeds: the material's, the layer's over them,
+  // merged as setParams writes land so a later view starts current.
+  let params: ShaderParams = { ...material.params, ...opts?.params }
   let pose: BufferId = createBuffer(capacity * POSE_FLOATS * 4, { label: `${label}-pose`, autoFree: false })
-  // The style records: JS-written through the sprite verbs (writeStyle),
+  // The sprite records: JS-written through the sprite verbs (writeSprite),
   // records()/updateRecords for a bulk restyle, published by the flush as
   // the dirty slot range, or the used prefix whole under an order (the
-  // core gathers both buffers under the one permutation).
-  let style = createRecordStream(STYLE_FLOATS * 4, capacity, { label: `${label}-style`, autoFree: false })
+  // core gathers every instance buffer under the one permutation).
+  let sprites = createRecordStream(SPRITE_FLOATS * 4, capacity, { label: `${label}-sprites`, autoFree: false })
+  // The material's style streams, after the layer's own: the same
+  // publish, the same growth.
+  let styles = createStyleStreams(material, capacity, label)
   let ordered = opts?.orderBy !== undefined
-  let gpu = createSpritePipeline(label, VERTEX_SPLIT, INSTANCE_LAYOUTS_SPLIT, opts?.blend ?? "alpha", atlases)
+  let gpu = material.pipeline(atlases, [POSE_ATTRIBUTES, SPRITE_ATTRIBUTES], label)
   // The sprites with a screen-size clamp (either bound on), and the
   // furthest any of them reaches from its center at its floor (floorReach,
   // view pixels): the candidate box a pick searches around the pointer. A
@@ -859,8 +940,8 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
   // ceiling set alone must not drop below the floor already there.
   let checkClamp = (verb: string, sprite: SpriteState, opts: SpriteOptions): void => {
     if (opts.minScreenPx === undefined && opts.maxScreenPx === undefined) return
-    let at = sprite._slot * STYLE_FLOATS
-    checkScreenSize(verb, opts.minScreenPx ?? styleData[at + STYLE_MIN_PX_FIELD]!, opts.maxScreenPx ?? styleData[at + STYLE_MAX_PX_FIELD]!)
+    let at = sprite._slot * SPRITE_FLOATS
+    checkScreenSize(verb, opts.minScreenPx ?? spriteData[at + SPRITE_MIN_PX_FIELD]!, opts.maxScreenPx ?? spriteData[at + SPRITE_MAX_PX_FIELD]!)
   }
 
   let disposed = false
@@ -889,7 +970,7 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
   // slot stays taken until the core says it is gone; dispose frees them.
   let leaving = new Set<NodeId>()
   let gpuCapacity = capacity
-  let styleData = new Float32Array(style.bytes.buffer)
+  let spriteData = new Float32Array(sprites.bytes.buffer)
   let byNode = new Map<NodeId, SpriteState>()
   // The layer's root node (identity): parentless sprites and groups hang
   // off it, so a query scoped to it sees exactly this layer.
@@ -897,6 +978,7 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
   let root = spatial.createNode(TRANSFORM, true)
   let filter: QueryFilter = { root }
   if (opts?.stagger !== undefined) spatial.setTransition(root, { stagger: opts.stagger })
+  if (opts?.timeScale !== undefined) spatial.setTimeScale(root, opts.timeScale)
   // Refill the layer's one filter for a query: the root always, the
   // include-list as the sprites' nodes when given.
   let queryFilter = (opts: QueryOptions | undefined, site: string): void => {
@@ -920,7 +1002,8 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
   let flush = () => {
     scheduled = false
     if (disposed) return
-    if (style.dirty) style.publish(ordered, highWater)
+    if (sprites.dirty) sprites.publish(ordered, highWater)
+    for (let s of styles) if (s.stream.dirty) s.stream.publish(ordered, highWater)
     if (published !== highWater) {
       views.setCount(highWater)
       published = highWater
@@ -930,20 +1013,25 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
     spatial.flush()
   }
 
-  // Grow both instance buffers to `next` slots: the pose sinks move in one
+  // The instance buffers in pipeline order after the quad: the pose, the
+  // sprite records, the material's style streams.
+  let buffers = (): BufferId[] => [pose, sprites.buffer, ...styles.map(s => s.stream.buffer)]
+  // Grow every instance buffer to `next` slots: the pose sinks move in one
   // retargetRecords call (the whole used range republishes at the next
-  // flush), the style stream grows into a replacement marked whole, which
+  // flush), the record streams grow into replacements marked whole, which
   // the next flush publishes. The entries hold the old buffers alive until
   // the swaps land, so the destroys are safe to issue right after.
   let grow = (next: number) => {
-    let newPose = createBuffer(next * POSE_FLOATS * 4, { label: `${label}-pose`, autoFree: false })
-    spatial.retargetRecords(pose, newPose)
-    let oldStyle = style.grow(next)
-    styleData = new Float32Array(style.bytes.buffer)
-    views.setBuffers([newPose, style.buffer])
-    destroyBuffer(pose)
-    destroyBuffer(oldStyle)
-    pose = newPose
+    let oldPose = pose
+    pose = createBuffer(next * POSE_FLOATS * 4, { label: `${label}-pose`, autoFree: false })
+    spatial.retargetRecords(oldPose, pose)
+    let oldSprites = sprites.grow(next)
+    spriteData = new Float32Array(sprites.bytes.buffer)
+    let oldStyles = styles.map(s => growStyle(s, next))
+    views.setBuffers(buffers())
+    destroyBuffer(oldPose)
+    destroyBuffer(oldSprites)
+    for (let old of oldStyles) destroyBuffer(old)
     gpuCapacity = next
   }
 
@@ -956,8 +1044,8 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
     return frameIndex(verb, atlasIndex, opts.frame)
   }
 
-  let writeStyle = (sprite: SpriteState, opts: SpriteOptions, atlas: number) => {
-    let at = sprite._slot * STYLE_FLOATS
+  let writeSprite = (sprite: SpriteState, opts: SpriteOptions, atlas: number) => {
+    let at = sprite._slot * SPRITE_FLOATS
     let changed = false
     let flipX = opts.flipX !== undefined && opts.flipX !== sprite._flipX
     let flipY = opts.flipY !== undefined && opts.flipY !== sprite._flipY
@@ -965,36 +1053,36 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
     if (flipY) sprite._flipY = !sprite._flipY
     if (opts.frame !== undefined) {
       let f = opts.frame
-      writeFrame(styleData, at, f.u0, f.v0, f.u1, f.v1, sprite._flipX, sprite._flipY)
-      styleData[at + STYLE_ATLAS_FIELD] = atlas
+      writeFrame(spriteData, at, f.u0, f.v0, f.u1, f.v1, sprite._flipX, sprite._flipY)
+      spriteData[at + SPRITE_ATLAS_FIELD] = atlas
       changed = true
     } else if (flipX || flipY) {
       // No new frame: toggle the changed axes on the stored UVs.
-      writeFrame(styleData, at, styleData[at]!, styleData[at + 1]!, styleData[at + 2]!, styleData[at + 3]!, flipX, flipY)
+      writeFrame(spriteData, at, spriteData[at]!, spriteData[at + 1]!, spriteData[at + 2]!, spriteData[at + 3]!, flipX, flipY)
       changed = true
     }
     if (opts.tint !== undefined) {
-      styleData[at + 4] = opts.tint[0]
-      styleData[at + 5] = opts.tint[1]
-      styleData[at + 6] = opts.tint[2]
-      styleData[at + 7] = opts.tint[3]
+      spriteData[at + 4] = opts.tint[0]
+      spriteData[at + 5] = opts.tint[1]
+      spriteData[at + 6] = opts.tint[2]
+      spriteData[at + 7] = opts.tint[3]
       changed = true
     }
     if (opts.renderOrder !== undefined) {
-      styleData[at + STYLE_KEY_FIELD] = opts.renderOrder
+      spriteData[at + SPRITE_KEY_FIELD] = opts.renderOrder
       changed = true
     }
     if (opts.minScreenPx !== undefined) {
-      styleData[at + STYLE_MIN_PX_FIELD] = opts.minScreenPx
+      spriteData[at + SPRITE_MIN_PX_FIELD] = opts.minScreenPx
       changed = true
     }
     if (opts.maxScreenPx !== undefined) {
-      styleData[at + STYLE_MAX_PX_FIELD] = opts.maxScreenPx
+      spriteData[at + SPRITE_MAX_PX_FIELD] = opts.maxScreenPx
       changed = true
     }
-    if (changed) style.mark(sprite._slot, sprite._slot + 1)
-    let min = styleData[at + STYLE_MIN_PX_FIELD]!
-    if (min > 0 || styleData[at + STYLE_MAX_PX_FIELD]! > 0) {
+    if (changed) sprites.mark(sprite._slot, sprite._slot + 1)
+    let min = spriteData[at + SPRITE_MIN_PX_FIELD]!
+    if (min > 0 || spriteData[at + SPRITE_MAX_PX_FIELD]! > 0) {
       clamped.add(sprite)
       let r = floorReach(sprite._w, sprite._h, min)
       if (r >= reach) reach = r
@@ -1008,13 +1096,14 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
     label,
     pipeline: gpu.pipeline,
     quad: gpu.quad,
-    atlases: atlases.map(a => a.texture),
-    buffers: () => [pose, style.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),
     // The order key one view entry declares: "y" on world y in the pose
-    // record (slot 0), "renderOrder" on the app-owned key in the style
+    // record (slot 0), "renderOrder" on the app-owned key in the sprite
     // record (slot 1); either way the core gathers BOTH buffers under the
     // one permutation at every publish and republishes the sibling itself
     // when the key buffer re-orders.
@@ -1022,12 +1111,13 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
       opts?.orderBy === "y"
         ? { field: POSE_Y_FIELD }
         : opts?.orderBy === "renderOrder"
-          ? { field: STYLE_KEY_FIELD, buffer: 2 }
+          ? { field: SPRITE_KEY_FIELD, buffer: 2 }
           : undefined,
   })
 
   let layer: SpriteLayer = {
     atlases,
+    material,
     get count() {
       return byNode.size
     },
@@ -1037,6 +1127,12 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
       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)
@@ -1072,7 +1168,7 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
         // the vertex stage draws.
         if (reachDirty) {
           reach = 0
-          for (let s of clamped) reach = Math.max(reach, floorReach(s._w, s._h, styleData[s._slot * STYLE_FLOATS + STYLE_MIN_PX_FIELD]!))
+          for (let s of clamped) reach = Math.max(reach, floorReach(s._w, s._h, spriteData[s._slot * SPRITE_FLOATS + SPRITE_MIN_PX_FIELD]!))
           reachDirty = false
         }
         let candidates = new Set<NodeId>()
@@ -1088,8 +1184,8 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
           spatial.worldMatrix(sprite.node!, WORLD)
           let w = Math.hypot(WORLD[0]!, WORLD[1]!)
           let h = Math.hypot(WORLD[4]!, WORLD[5]!)
-          let at = sprite._slot * STYLE_FLOATS
-          let scale = screenSizeScale(w, h, zoom, styleData[at + STYLE_MIN_PX_FIELD]!, styleData[at + STYLE_MAX_PX_FIELD]!)
+          let at = sprite._slot * SPRITE_FLOATS
+          let scale = screenSizeScale(w, h, zoom, spriteData[at + SPRITE_MIN_PX_FIELD]!, spriteData[at + SPRITE_MAX_PX_FIELD]!)
           if (pointInSprite(x, y, WORLD[12]!, WORLD[13]!, w * scale, h * scale, Math.atan2(WORLD[1]!, WORLD[0]!))) out.push(sprite)
         }
       }
@@ -1199,18 +1295,18 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
       spatial.flush()
       views.dispose()
       destroyBuffer(pose)
-      style.destroy()
-      gpu.dispose()
+      sprites.destroy()
+      for (let s of styles) s.stream.destroy()
     },
     _add(opts) {
       if (disposed) throw new Error("addSprite: layer is disposed")
-      // The style bag with its defaults - renderOrder and the clamp at 0
+      // The fields bag with its defaults - renderOrder and the clamp at 0
       // explicitly, since a recycled slot holds the previous occupant's
       // values otherwise - resolved before a slot or node is taken, so a
       // bad frame allocates nothing. An absent key and an explicit
       // undefined both take the default (the options convention
       // everywhere; a plain spread would let undefined win).
-      let style: SpriteOptions = {
+      let fields: SpriteOptions = {
         ...opts,
         frame: opts?.frame ?? fullFrame(atlases[0]!),
         tint: opts?.tint ?? [1, 1, 1, 1],
@@ -1218,7 +1314,7 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
         minScreenPx: opts?.minScreenPx ?? 0,
         maxScreenPx: opts?.maxScreenPx ?? 0,
       }
-      let atlas = frameAtlas("addSprite", style)
+      let atlas = frameAtlas("addSprite", fields)
       if (opts?.parent && opts.parent.layer !== layer) throw new Error("addSprite: parent group belongs to another layer")
       let slot = freeSlots.pop() ?? highWater++
       if (slot >= gpuCapacity) grow(gpuCapacity * 2)
@@ -1248,20 +1344,22 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
       spatial.setBounds(node, COLUMN_BOUNDS)
       spatial.bindPoseRecord(node, pose, slot)
       byNode.set(node, sprite)
-      writeStyle(sprite, style, atlas)
+      writeSprite(sprite, fields, atlas)
       // No outline until a text run sets one: a recycled slot would
-      // otherwise leak the previous occupant's.
-      styleData.fill(0, slot * STYLE_FLOATS + STYLE_OUTLINE_FIELD, slot * STYLE_FLOATS + STYLE_OUTLINE_FIELD + 4)
+      // otherwise leak the previous occupant's. The material's sprites
+      // slots start over for the same reason.
+      spriteData.fill(0, slot * SPRITE_FLOATS + SPRITE_OUTLINE_FIELD, slot * SPRITE_FLOATS + SPRITE_OUTLINE_FIELD + 4)
+      for (let style of styles) blankStyle(style, slot)
       layer._schedule()
       return sprite
     },
     _outline(sprite, r, g, b, width) {
-      let at = sprite._slot * STYLE_FLOATS + STYLE_OUTLINE_FIELD
-      styleData[at] = r
-      styleData[at + 1] = g
-      styleData[at + 2] = b
-      styleData[at + 3] = width
-      style.mark(sprite._slot, sprite._slot + 1)
+      let at = sprite._slot * SPRITE_FLOATS + SPRITE_OUTLINE_FIELD
+      spriteData[at] = r
+      spriteData[at + 1] = g
+      spriteData[at + 2] = b
+      spriteData[at + 3] = width
+      sprites.mark(sprite._slot, sprite._slot + 1)
       layer._schedule()
     },
     _write(sprite, opts) {
@@ -1289,25 +1387,25 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
         opts.maxScreenPx !== undefined ||
         (moved && clamped.has(sprite))
       ) {
-        writeStyle(sprite, opts, atlas)
+        writeSprite(sprite, opts, atlas)
       }
-      if (moved || style.dirty) layer._schedule()
+      if (moved || sprites.dirty) layer._schedule()
     },
     _read(sprite) {
-      let at = sprite._slot * STYLE_FLOATS
+      let at = sprite._slot * SPRITE_FLOATS
       return {
         x: sprite._x,
         y: sprite._y,
         w: sprite._w,
         h: sprite._h,
-        frame: readFrame(styleData, at, sprite, atlases[styleData[at + STYLE_ATLAS_FIELD]!]!.texture),
+        frame: readFrame(spriteData, at, sprite, atlases[spriteData[at + SPRITE_ATLAS_FIELD]!]!.texture),
         flipX: sprite._flipX,
         flipY: sprite._flipY,
         rotation: sprite._rot,
-        tint: [styleData[at + 4]!, styleData[at + 5]!, styleData[at + 6]!, styleData[at + 7]!],
-        minScreenPx: styleData[at + STYLE_MIN_PX_FIELD]!,
-        maxScreenPx: styleData[at + STYLE_MAX_PX_FIELD]!,
-        renderOrder: styleData[at + STYLE_KEY_FIELD]!,
+        tint: [spriteData[at + 4]!, spriteData[at + 5]!, spriteData[at + 6]!, spriteData[at + 7]!],
+        minScreenPx: spriteData[at + SPRITE_MIN_PX_FIELD]!,
+        maxScreenPx: spriteData[at + SPRITE_MAX_PX_FIELD]!,
+        renderOrder: spriteData[at + SPRITE_KEY_FIELD]!,
         visible: sprite._visible,
       }
     },
@@ -1351,6 +1449,13 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
       if (disposed) return
       spatial.setTransition(root, ms === null ? null : { stagger: ms })
     },
+    setTimeScale(scale) {
+      if (disposed) return
+      spatial.setTimeScale(root, scale)
+    },
+    timeRate() {
+      return disposed ? 1 : spatial.timeRate(root)
+    },
     _schedule() {
       if (disposed || scheduled) return
       scheduled = true
@@ -1358,10 +1463,11 @@ export function createSpriteLayer(atlases: Atlas[], opts?: SpriteLayerOptions):
     },
     _groups: new Set(),
     _root: root,
-    _stream: style,
+    _stream: sprites,
     get _records() {
-      return styleData
+      return spriteData
     },
+    _styles: styles,
   }
   if (opts?.autoFree !== false && getOwner()) onCleanup(() => layer.dispose())
   return layer
@@ -1425,7 +1531,8 @@ export function destroySprite(sprite: Sprite): void {
  * through every enclosing group (@solidrt/3d's worldPosition, Three's
  * getWorldPosition), read from the core's world matrix as the tree stands
  * now, pending writes included. Under a transition this is the
- * mid-flight pose - what picking and the screen show - where the handle's
+ * mid-flight pose of THIS frame (native motion steps before any of the
+ * frame's JS) - what picking and the screen show - where the handle's
  * own fields hold the target. A record layer's sprite has no groups, so
  * its world position is its own, read as getSprite reads it (the records
  * array). A fresh pair per call; null once the handle is inert.
@@ -1588,6 +1695,38 @@ export function setGroupTransition(group: SpriteGroup, transition: SpriteTransit
   declareTransition(group.node, group, node)
 }
 
+/**
+ * Declare (null clears) the rate the sprite's own native motion runs at
+ * (its transitions, with their delays, enter and exit): 0 freezes it, 1
+ * is app time, other values slow or fast motion. Overrides the layer's
+ * and the enclosing groups' rate for this sprite alone (the nearest
+ * declaring node wins); see SpriteLayer.setTimeScale. Node layer only.
+ */
+export function setSpriteTimeScale(sprite: Sprite, scale: number | null): void {
+  if (sprite.layer === null) return
+  if (sprite.node === null) throw new Error("setSpriteTimeScale: record sprites have no native motion")
+  spatial.setTimeScale(sprite.node, scale)
+}
+
+/** The group counterpart of setSpriteTimeScale: the rate everything under
+ * the group runs at, down to the next group or sprite declaring its own
+ * - a frozen world with one live group inside it. */
+export function setGroupTimeScale(group: SpriteGroup, scale: number | null): void {
+  if (group.layer === null) return
+  spatial.setTimeScale(group.node, scale)
+}
+
+/**
+ * The rate a sprite's or group's motion runs at: its own time scale, else
+ * the nearest declaring group's, else the layer's, else 1. What JS-driven
+ * motion of the handle multiplies its own frame step by. Null for a
+ * destroyed handle or a record layer's sprite (no native motion).
+ */
+export function timeRate(target: Sprite | SpriteGroup): number | null {
+  if (target.layer === null || target.node === null) return null
+  return spatial.timeRate(target.node)
+}
+
 /** Add a transform group (see SpriteGroup). */
 export function addGroup(layer: SpriteLayer, opts?: GroupOptions): SpriteGroup {
   let group = {