@solidrt/2d 0.0.71 → 0.0.72

package/AGENTS.md

@@ -17,7 +17,8 @@ Contents:
   - [Three faces](#three-faces)
   - [A layer renders through its views](#a-layer-renders-through-its-views)
   - [Atlases and frames](#atlases-and-frames)
-  - [Pose and style slots](#pose-and-style-slots)
+  - [Materials](#materials)
+  - [Pose, sprite and style slots](#pose-sprite-and-style-slots)
   - [Fixed instance slots](#fixed-instance-slots)
   - [Growth](#growth)
   - [Picking](#picking)
@@ -48,6 +49,7 @@ Contents:
   - [Pointer events](#pointer-events)
 - [Traps](#traps)
   - [Atlases and sampling](#atlases-and-sampling)
+  - [Materials](#materials-1)
   - [Slots, capacity and order](#slots-capacity-and-order)
   - [Nodes, transitions and queries](#nodes-transitions-and-queries)
   - [Cameras and rotation](#cameras-and-rotation)
@@ -94,10 +96,12 @@ included, and a tile world bakes from several tilesets in one pass. A
 Unity's Sprite and Godot's AtlasTexture pair the texture with the rect
 the same way), the record stores that texture's index in the layer's
 list (`layer.atlases`, what a raw record writer stores), and the
-fragment stage is GENERATED per layer with one sampler per atlas, the
-flat per-instance index picking it: derivatives are taken from the
-unclamped uv before the branch and the tap is `textureGrad`, so mip
-selection is the quad's own and well defined inside the branch. A frame
+fragment SET is GENERATED per layer with one sampler per atlas, the
+flat per-instance index picking it (`spriteSource` in `@solidrt/2d/glsl`,
+prepended to whatever fragment the layer's material carries):
+derivatives are taken from the unclamped uv before the branch and the
+tap is `textureGrad`, so mip selection is the quad's own and well
+defined inside the branch. A frame
 whose texture the layer did not declare THROWS at the write (the
 wrong-sheet bug, caught instead of drawn); the frame left out of
 `addSprite` is the whole FIRST atlas. An atlas declared `sdf: { range }`
@@ -107,19 +111,114 @@ the edge, anti-aliased over one screen pixel at whatever zoom, the true
 field in alpha grows a per-sprite outline (text runs set it; a colour
 atlas ignores the field). Fixed at creation like the list itself.
 
-### Pose and style slots
-
-Node layer ownership split, two instance-buffer slots on one pipeline
-(the layer's, blended with its `blend` option, "alpha" unless it says
-"add", "multiply" or "none" at creation - two blend modes are two
-layers): slot 0 is the POSE buffer `[x, y, angle, sx, sy]` written ONLY
-by the core (each sprite node's Pose2D record sink; one coalesced buffer
-write per flush however many nodes moved), slot 1 the STYLE buffer
-`[u0, v0, u1, v1, tint rgba, renderOrder, minScreenPx, maxScreenPx,
-atlas, outline rgb, outlineWidth]` (16 floats), JS-owned, published
-through the zero-copy write lease. NEVER
-write the pose buffer from JS - the core's staging mirror owns it and
-will overwrite.
+### Materials
+
+What a layer's pixels look like is its MATERIAL (material.ts), one per
+layer, fixed at creation (`createSpriteLayer(atlases, { material })`,
+the records and tile layers alike, `<SpriteLayer material>` /
+`<TileLayer material>`): the material sits on the thing that is one
+draw entry - the layer is the batch - as @solidrt/3d's sits on the
+mesh, so two looks are two layers, which is also how you order them
+(the additive glow layer draws over the scene layer). The same model
+and the same words as 3d, deliberately: `unlit()` is the stock
+material, `prelude`/`surface` its tier-2 slot, `shaderMaterialClass`
+/ `shaderMaterial` the class form over the layer's GLSL set,
+`instanceBuffers` / `instanceStyle` / `setInstanceStyle` /
+`instanceAttribute` the per-sprite style record (the comparison and
+the decisions: okf/plans/materials-one-model.md; Godot's
+`CanvasItem.material` with a `canvas_item` shader is the nearest
+engine shape, PixiJS and Phaser the batch-per-look precedent). The one
+deliberate asymmetry: a 3d `blend` implies `transparent` and the
+scene's back-to-front sort; a layer has no depth and draws in record
+order, so nothing sorts.
+
+- `unlit({ blend?, prelude?, surface?, params?, textures?,
+  instanceBuffers?, instanceStyle?, label? })` - the atlas texel times
+  the sprite's tint (a distance-field atlas decoded to its fill and
+  outline), times the layer tint, blended with `blend` ("alpha" by
+  default, "add" for glows and additive particles, "multiply" to
+  darken, "none" to overwrite; pipeline state, so per layer). Every
+  layer draws with `unlit()` unless told otherwise. The TIER-2 slot:
+  `surface` declares `void surface(inout Sprite s)`, called with the
+  struct filled and before the layer tint - `color` (the stock result,
+  premultiplied: texel times tint, or the decoded field), `uv`,
+  `frame`, `tint`, `atlas` - rewrite `s.color` or `discard`;
+  `prelude` is file scope after the set (uniforms, each a LAYER PARAM;
+  helpers); `spriteSample(uv)` resamples the fragment's own atlas at
+  another uv (the pick, the frame clamp, the field decode, the tint),
+  so a scroll is `spriteSample(mix(s.frame.xy, s.frame.zw,
+  fract(t)))` - the clamp into the frame still applies, so a wrap is
+  `fract` in FRAME space. One program per distinct source, cached for
+  the app's lifetime like 3d's.
+- PER-SPRITE DATA: `instanceBuffers: [{ attributes: [{ name, format }]
+  }]` on either form declares the material's STYLE record(s), one
+  stream per buffer bound after the layer's own records, any vertex
+  format (a palette index is a `uint8x4` at four bytes, a dissolve
+  amount a `float16x2`), every slot starting as `instanceStyle` (the
+  identity of what the look does with it). On `unlit` the stock
+  vertex stage forwards each attribute unchanged as a flat varying -
+  `iPalette` reaches the prelude and the surface as `vPalette`
+  (`forwardedName`; names follow the layer's own `i` + capital
+  convention) - so a palette swap is one attribute, one surface line
+  and a `setInstanceStyle(layer, sprite, [row])` per sprite. Writes:
+  `setInstanceStyle(layer, sprite, values)` (the first buffer, one
+  value per component as the shader sees them; marks the slot like
+  setSprite), `instanceAttribute(layer, name)` (the accessor: slot in,
+  component values out and in through the format's codec; valid
+  across growth) plus `updateRecords(layer, { stream, first, count
+  })`, or `records(layer, stream)` in bulk (stream 1.. the material's
+  buffers in order; a Float32Array over an all-float layout, bytes
+  otherwise), `<Sprite style>` in the component face, `setTile(...,
+  { style })` on a tile layer. A recycled slot (and a records layer's
+  shifted one) starts blank again.
+- LAYER PARAMS: `layer.setParams({ uFlash: 0.5 })` writes a prelude's
+  uniforms to every view (and every resident chunk of a tile layer,
+  which RE-BAKES on each write like its tint) over the material's own
+  `params`; the `params` option and prop seed them, a view created
+  later inherits the merged record. @solidrt/3d's setMeshParams one
+  dimension down. Material `textures` (a palette LUT, a noise texture)
+  bind beside the atlases and count against the same
+  `limits.maxTextureUnits` budget, checked at layer creation.
+- The class form, `shaderMaterialClass({ vertex, fragment,
+  instanceBuffers?, instanceStyle?, blend?, label? })` with
+  `instance({ params?, textures? })` and `dispose()` on the class
+  (`shaderMaterial(opts)` is a class with one instance): TIER 1 pairs
+  a vertex stage of your own with `unlitFragment(options)` from
+  `@solidrt/2d/glsl` - compose `SPRITE_VARYINGS`, core's
+  `SCREEN_SIZE_GLSL`, your placement into `corner`/`center`/`rot`/
+  `clampScale`, then `SPRITE_VERTEX_BODY`; `SPRITE_VERTEX` is the
+  stock stage, `unlitVertex(forwards)` the stock stage forwarding
+  attributes - and TIER 3 writes a `main` of its own over the layer's
+  SET, which the layer prepends (the varyings, `uAtlasN`, `uTint`, the
+  `Sprite` struct, `spriteOf()`, `spriteSample(uv)`: declare none of
+  them, start with `Sprite s = spriteOf();` since the derivatives
+  every tap uses are taken there, and write premultiplied). One
+  program per ATLAS LIST met (the set is generated per list), one
+  pipeline per instance-layout list met on top - the records and tile
+  layers bind one record buffer, the node layer a pose and a sprite
+  buffer, with the same attribute NAMES on both (iPos, iRot, iScale,
+  iUv, iTint, iScreenPx, iAtlas, iOutline), so one vertex stage
+  serves every layer kind. A vertex stage must declare and use
+  `uCamera`, `uCameraRot` and `uViewport` (checked at creation), an
+  instance attribute may not reuse a layer name
+  (`LAYER_ATTRIBUTE_NAMES`), a texture may not take an atlas sampler's
+  (`uAtlasN`). `tests/materials.test.tsx` pins all three tiers, the
+  style streams through growth and shift, the params, the resample,
+  the tile bake and the throws.
+
+### Pose, sprite and style slots
+
+Node layer ownership split, instance-buffer slots on one pipeline (the
+material's; two materials are two layers): slot 0 is the POSE buffer
+`[x, y, angle, sx, sy]` written ONLY by the core (each sprite node's
+Pose2D record sink; one coalesced buffer write per flush however many
+nodes moved), slot 1 the SPRITE record `[u0, v0, u1, v1, tint rgba,
+renderOrder, minScreenPx, maxScreenPx, atlas, outline rgb,
+outlineWidth]` (`SPRITE_FLOATS`, 16), JS-owned through the sprite verbs
+and published through the zero-copy write lease, and after them the
+material's STYLE streams, one per instance buffer it declares (app-owned
+per-sprite data, Materials above). NEVER write the pose buffer from JS -
+the core's staging mirror owns it and will overwrite.
 
 ### Fixed instance slots
 
@@ -212,7 +311,9 @@ detach here (3d's `remove`), and a sprite that should come back is
 hidden (`visible: false`).
 A handle's x/y are local to its group; `worldPosition(sprite | group)`
 reads the layer-pixel position composed through every enclosing group
-from the core's world matrix (@solidrt/3d's worldPosition).
+from the core's world matrix (@solidrt/3d's worldPosition) - under a
+transition the pose of this frame, since native motion steps before the
+frame's JS.
 
 ### Visibility
 
@@ -273,14 +374,18 @@ publish itself is the core's record stream (`createRecordStream` in
 the range-or-whole publish, growth into a replacement), the one model
 the 3d instance streams run on too; this file only decides what to
 mark and when to flush. The node layer speaks the same two verbs over
-its STYLE records: `records(spriteLayer)` is the style mirror
-(`STYLE_FLOATS` floats per slot: `[u0, v0, u1, v1, tint rgba,
+its SPRITE records: `records(spriteLayer)` is the sprite mirror
+(`SPRITE_FLOATS` floats per slot: `[u0, v0, u1, v1, tint rgba,
 renderOrder, minScreenPx, maxScreenPx, atlas, outline rgb,
 outlineWidth]`, slot-indexed, poses stay the core's) and
 `updateRecords(spriteLayer, { first?, count? })` publishes the slot
 range, so a bulk restyle (a palette cycle over thousands of sprites) is
 one loop and one range write instead of a setSprite each - the 3d
-`records(instancedMesh)` pairing, one dimension down. It is the
+`records(instancedMesh)` pairing, one dimension down. Both layer
+kinds take a `stream` beyond 0 on the same verbs for the material's
+style streams (`records(layer, 1)`, `updateRecords(layer, { stream: 1
+})`), which grow, publish and (on a records layer) shift with the
+layer's own record. It is the
 escape hatch for motion only JS can compute at scale (measured 30k
 sprites: 12.9ms raw records vs 30.8ms via setSprite; both figures are
 the WRITE path only - whatever computes the motion is excluded and is
@@ -478,7 +583,9 @@ kinds): one `uTint` shared-params write multiplied over every sprite's
 own tint - day/night, a dimmed parallax plane, a fade-in. Cheap to
 animate (no record touches), unlike TileLayer's, which re-renders
 resident chunks. The same contract as TileLayer.setTint, so one signal
-drives a whole scene across layer kinds.
+drives a whole scene across layer kinds. The general form is
+`setParams` (Materials above): the tint is the one param every material
+takes.
 
 ### Views
 
@@ -562,6 +669,25 @@ never on a cancel, snap or exit; the raw "spatialTransitionEnd" engine
 event (sol:events, node = sprite.node) stays for flux:spatial consumers.
 See examples/springs.tsx (tap a sprite: it leaves through its `exit`).
 
+PAUSE and time scale are declarations on the same nodes:
+`layer.setTimeScale(scale)` / `<SpriteLayer timeScale>` sets 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, 0.5 slow motion; `setGroupTimeScale` /
+`<Group timeScale>` and `setSpriteTimeScale` / `<Sprite timeScale>`
+declare it for a subtree or one sprite. The NEAREST declaring node wins,
+never a product (Godot's process_mode shape): a frozen layer with a
+`<Group timeScale={1}>` inside keeps that group running. A frozen layer
+asks for no frames (the write that resumes it brings the frame), writes
+while frozen retarget and wait, a destroyed sprite with an `exit` stays
+a ghost until its time moves again (the layer's `dispose` still cuts it
+short), and a sprite added frozen sits at its `from`. The scale covers
+the CORE's motion: frame animations follow it only when given a `clock`
+(see Frame animation), and your own `onFrame` logic, timers and audio
+stay on app time - multiply your step by `layer.timeRate()` /
+`timeRate(sprite)`, the effective rate read. The dev clock
+(`/clock?scale=`) scales app time underneath all of this.
+
 ### Frame-rate motion
 
 Frame-rate motion only JS can compute (physics, flocking) bypasses the
@@ -588,7 +714,12 @@ most one animation (add detaches the previous); removed sprites prune
 lazily on the next step. Works on both layer kinds; with `<Sprite>`,
 attach via `ref` and leave the `frame` prop off - the clip owns that
 field (the prop effect passes absent props as undefined, which setSprite
-keeps, so other props stay reactive).
+keeps, so other props stay reactive). A clip is a JS clock, so a layer's
+`setTimeScale` does not reach it by itself: `createAnimation(frames, fps,
+{ clock: layer })` (a group or a sprite works too) runs the clip at that
+handle's `timeRate`, read every frame, so the one pause that freezes the
+world's transitions holds its walk cycles as well, and a slow-motion
+group slows the flipbooks in it.
 
 ### Text runs
 
@@ -640,8 +771,10 @@ Static 2D bulk as a few quads: on tiled GPUs the budget is primitive count
 quads per frame. `createTileLayer(cols, rows, tileW, tileH, atlases)`
 bakes the world into CHUNKED `render: "manual"` targets (default ~512px
 of tiles per chunk, `chunkTiles` to tune), each chunk a manual target
-over the layer's ONE sprite pipeline (shaders.ts, compiled once per
-layer for its atlases) with FIXED record slots - an empty tile is a
+over the layer's ONE pipeline (its material's, resolved once per layer
+for its atlases; a cell's style record is `setTile`'s `style`, its
+params re-bake every resident chunk on each write) with FIXED record
+slots - an empty tile is a
 zero-size quad, instance count is constant per chunk. Records hold WORLD
 pixel coordinates; each chunk target's `uCamera` is its pixel origin, so
 the shared vertex stage does the chunk-local mapping. Chunks allocate on
@@ -700,8 +833,11 @@ the whole layer through the shared `uTint` uniform, multiplied over the
 per-cell tints - day/night, a dimmed parallax plane. A layer-tint write
 is not a record write (chunks re-render GPU-side, nothing re-uploads),
 but it does re-render every resident chunk: drive it from slow state,
-not per frame. Not built yet: camera-driven residency (bake far chunks
-on approach, evict) - okf/backlog/2d-baked-layers.md.
+not per frame. `setParams` (a material prelude's uniforms) and a cell's
+`style` (the material's per-cell record, `setTile`/`setTiles` `{ style
+}`) are the same two levels for a custom look, Materials above. Not
+built yet: camera-driven residency (bake far chunks on approach, evict)
+- okf/backlog/2d-baked-layers.md.
 
 ## Components
 
@@ -709,12 +845,12 @@ on approach, evict) - okf/backlog/2d-baked-layers.md.
 
 | Component | Props |
 |---|---|
-| `SpriteLayer` | atlases (Atlas[], the sheets bound as one draw; mount-fixed) or layer (an existing createSpriteLayer handle to adopt: the component shows and populates it, keeps only the view and the leaf as its own and leaves the layer's lifetime to its maker, so `<Sprite>`/`<Text2d>` sit over an imperative layer; the creation props atlases/capacity/blend/orderBy then throw), capacity?, blend? (core gpu BlendMode, "alpha" default, "add" for glows; mount-fixed), tint? ([r,g,b,a] 0..1, over the whole layer in every view), orderBy?, stagger? (ms, the layer root's enter/exit spacing), label?, ref?(layer) - the layer; plus its OWN VIEW, unless `output={false}`: width?, height? (view pixels - both, or neither = FILL: the leaf lays out at 100% of its sized parent and the view follows its box, so view pixels are the leaf's own coordinates; mount-fixed, a function `output` requires explicit sizes, matching `<Scene>` in @solidrt/3d), clearColor?, camera?, oversample?, maxOversample?, viewRef?(view), output? (a function composes the leaf from the texture id; `false` = no own view, the layer shows only through `<View2d>` children and the view props throw), events?, pointer? (a createPointerFeed fed from the view's root, what a map over this view binds; `useSpriteLayer().pointer` inside), onPointer{Down,Move,Up}?, onWheel?, onTap? (the view's root: `event.sprite` is the hit sprite or null over empty space) |
-| `Sprite` | x, y (center; local to the enclosing `<Group>`), w, h, frame?, rotation? (radians, clockwise), tint? ([r,g,b,a] 0..1), minScreenPx?, maxScreenPx? (the screen-size clamp on the smaller axis, view pixels; 0 = off; equal = constant size), visible?, transition?, onPointer{Down,Move,Up,Enter,Leave}?, onWheel?, onTap?, ref? |
+| `SpriteLayer` | atlases (Atlas[], the sheets bound as one draw; mount-fixed) or layer (an existing createSpriteLayer handle to adopt: the component shows and populates it, keeps only the view and the leaf as its own and leaves the layer's lifetime to its maker, so `<Sprite>`/`<Text2d>` sit over an imperative layer; the creation props atlases/capacity/material/orderBy then throw), capacity?, material? (the layer's material, `unlit()` default, `unlit({ blend: "add" })` for glows; mount-fixed), params? (layer.setParams as a prop, over the material's own; live, merge semantics), tint? ([r,g,b,a] 0..1, over the whole layer in every view), orderBy?, stagger? (ms, the layer root's enter/exit spacing), label?, ref?(layer) - the layer; plus its OWN VIEW, unless `output={false}`: width?, height? (view pixels - both, or neither = FILL: the leaf lays out at 100% of its sized parent and the view follows its box, so view pixels are the leaf's own coordinates; mount-fixed, a function `output` requires explicit sizes, matching `<Scene>` in @solidrt/3d), clearColor?, camera?, oversample?, maxOversample?, viewRef?(view), output? (a function composes the leaf from the texture id; `false` = no own view, the layer shows only through `<View2d>` children and the view props throw), events?, pointer? (a createPointerFeed fed from the view's root, what a map over this view binds; `useSpriteLayer().pointer` inside), onPointer{Down,Move,Up}?, onWheel?, onTap? (the view's root: `event.sprite` is the hit sprite or null over empty space) |
+| `Sprite` | x, y (center; local to the enclosing `<Group>`), w, h, frame?, rotation? (radians, clockwise), tint? ([r,g,b,a] 0..1), minScreenPx?, maxScreenPx? (the screen-size clamp on the smaller axis, view pixels; 0 = off; equal = constant size), style? (the sprite's style record under the layer's material, one value per component of its first instance buffer; live), visible?, transition?, onPointer{Down,Move,Up,Enter,Leave}?, onWheel?, onTap?, ref? |
 | `Group` | x?, y?, rotation?, scale? (uniform, scales the subtree), visible? (the whole subtree), transition?, onPointer{Down,Move,Up}?, onWheel?, onTap? (bubbled from hit child sprites), ref? |
 | `Camera2d` | createCamera2d's options (world?, min/maxZoom?, pivot?, follow?, offset?, panSpeed?, zoomSpeed?, rollSpeed?, damping?, inertia?, x?, y?, zoom?, rotation?), input? (the input map driving its `pan`/`zoom`/`roll` axes; live), actions? (action names per axis when the map's differ), ref? - a `<SpriteLayer>` child driving the nearest view's camera (the `<SpriteLayer>`'s own, or inside a `<View2d>` that view; its `size()` the viewport) from the map, nothing else; read at mount; throws under `output={false}` outside a `<View2d>` |
 | `View2d` | a `<SpriteLayer>` child: one more view of the layer from a camera of its own (layer.createView as a component): width, height (view pixels, live; fixed-size only for now), camera? (partial CameraUpdate on the view's camera, live; the same state a `<Camera2d>` child writes), oversample?, maxOversample? (the auto-pick, as SpriteLayer's), clearColor?, label? (createView's, fixed), ref?(view), output?(texture) (else a built-in `<texture>` leaf at the view size carrying the view's handlers), events?, pointer? (this view's feed, fed from its root), onPointer{Down,Move,Up}?, onWheel?, onTap? (the view's root: `event.sprite` null over empty space); a `<Camera2d>` child drives the VIEW from its map (inside, `useSpriteLayer()` reports the view as `viewport` and the feed as `pointer`); `<Sprite>`/`<Group>` children mount to the layer as outside |
-| `TileLayer` | cols, rows, tileW, tileH, atlases (Atlas[], the tilesets bound as one bake; mount-fixed), frames? (the tileset `setTiles` indices name), chunkClearColor?, blend? (the bake's blend mode, "alpha" default; mount-fixed), filter?, chunkTiles?, tint? ([r,g,b,a] 0..1, over the whole layer), oversample?, maxOversample?, camera? (TileCamera: x, y, zoom, rotation, pivotX, pivotY), label?, ref? |
+| `TileLayer` | cols, rows, tileW, tileH, atlases (Atlas[], the tilesets bound as one bake; mount-fixed), frames? (the tileset `setTiles` indices name), chunkClearColor?, material? (the bake's material, `unlit()` default; mount-fixed), params? (layer.setParams as a prop; live, each change re-bakes), filter?, chunkTiles?, tint? ([r,g,b,a] 0..1, over the whole layer), oversample?, maxOversample?, camera? (TileCamera: x, y, zoom, rotation, pivotX, pivotY), label?, ref? |
 
 ### SpriteLayer and useSpriteLayer
 
@@ -772,12 +908,15 @@ space keeps delivering to the root as it crosses sprites; a drag from a
 sprite keeps naming it with live coordinates). Enter/leave fire on the
 sprite alone - a group never receives them - while the root sees every
 move, so "hovering empty space" is a root move with `sprite` null. Taps
-are synthesized by the dispatch (DOM click, Unity's click handler):
-`onTap` fires after the up when the press released on the target it
-pressed within the slop (8 window px, core's recognizer slop, so a press
-is never both a tap and a pan), was the only pointer down for its whole
-press (a pinch never taps), with `tapCount` counting repeats within 300
-ms and 20 px on the same target (a double tap is `tapCount === 2`).
+are synthesized by the dispatch, as DOM click (Unity's click handler
+fires for every button; ours, like DOM's, for the primary alone): `onTap`
+fires after the up when a PRIMARY-button press (a right click walks its
+down and up with `button` 2 but never taps, like core's press; read
+`button` on the down to act on it) released on the target it pressed
+within the slop (8 window px, core's recognizer slop, so a press is never
+both a tap and a pan), was the only pointer down for its whole press (a
+pinch never taps), with `tapCount` counting repeats within 300 ms and 20
+px on the same target (a double tap is `tapCount === 2`).
 Wheel walks like a move with `deltaX/deltaY`. Every event carries
 `timeStamp` and `predicted` as the element event has them (time input
 with the first; a `predicted` move is one to draw with, not to measure
@@ -844,11 +983,12 @@ hover, wheel and tap rules headless.
   shading: the same tint triple is a different brightness in the two
   packages, so a palette shared across them needs its own conversion.
 - Tint multiplies the sampled texel (`texture * tint`) and the pipeline
-  blends with the layer's `blend` in record order - "alpha" by default,
-  the premultiplied composite; "add" accumulates (glows, sparks, light
-  cones: two half-alpha whites make opaque white), "multiply" darkens,
-  "none" overwrites. Pipeline state, so it is per layer and fixed at
-  creation; an additive effect layer draws over the scene layer.
+  blends with the material's `blend` in record order - "alpha" by
+  default, the premultiplied composite; "add" accumulates (glows,
+  sparks, light cones: two half-alpha whites make opaque white),
+  "multiply" darkens, "none" overwrites. Pipeline state, so it is per
+  layer (`material: unlit({ blend: "add" })`) and fixed at creation; an
+  additive effect layer draws over the scene layer.
   The atlas is premultiplied because `decodeImage` premultiplies by default;
   an atlas uploaded from straight-alpha pixels (`decodeImage(bytes, { alpha:
   "straight" })` into `createAtlas`) draws color under transparent texels
@@ -884,6 +1024,35 @@ hover, wheel and tap rules headless.
   snapping the fit to an integer: the scene should fill its box at any
   ratio.
 
+### Materials
+
+- A `surface` reads the struct, never a local of the generated program:
+  `s.color` is premultiplied and BEFORE the layer tint (`uTint`
+  multiplies after the slot), so a rewrite to an opaque colour is
+  `vec4(rgb, 1.0) * s.color.a` to keep the sprite's coverage.
+- A custom `main` (tier 3) starts with `Sprite s = spriteOf();`: the uv
+  derivatives every tap uses are taken there, in uniform control flow.
+  A `spriteSample` before it reads zero derivatives and picks the
+  sharpest mip everywhere.
+- `spriteSample(uv)` clamps into the FRAME like the stock tap: a uv
+  past the frame's edge lands on the edge texel, never on the next
+  cell. Wrap in frame space (`fract`) before mixing into the frame rect.
+- The stock stage forwards a material's instance attributes as FLAT
+  varyings named `v` + the name without its `i` - `iPalette` is
+  `vPalette` in the surface; a name not spelled `i` + capital throws at
+  `unlit()`. A custom vertex stage forwards what it likes.
+- A material's `textures` and the atlases share one sampler budget
+  (`limits.maxTextureUnits`, 16): a LUT and a noise texture leave room
+  for fourteen sheets, and the layer creation throws past it.
+- A tile layer BAKES: `setParams` on it re-renders every resident chunk,
+  like `setTint`. Animated uniforms belong on a sprite layer, whose
+  params are one shared write per view.
+- The stock material classes are cached for the app's lifetime (one per
+  blend x prelude x surface x layouts, like 3d's unlit); a
+  `shaderMaterialClass` is yours to `dispose()`, and its programs are
+  compiled per atlas LIST met - two layers over the same atlases share
+  the program, two over different lists compile twice.
+
 ### Slots, capacity and order
 
 - `capacity` is a reservation, not a limit, on both layer kinds; reserve

package/README.md

@@ -39,7 +39,7 @@ transitions, groups, picking and the collision queries reach it with no
 per-frame JS: a sprite write is a target the core animates toward, and
 the core writes the pose buffer itself. For motion only JS can compute at
 scale (a flock, a particle sim), the records layer is the escape hatch:
-sixteen JS-owned floats per sprite in one `Float32Array`, published by
+twenty JS-owned floats per sprite in one `Float32Array`, published by
 dirty range with the same `records`/`updateRecords`/`setRecordCount`
 verbs as `@solidrt/3d`'s record mesh - ten thousand float stores and one
 buffer write, not twenty thousand FFI calls.
@@ -54,8 +54,12 @@ hit-test exact rotated rects, topmost first, with pointer capture.
 
 In the package: atlas creation, slicing and extrusion (`createAtlas`,
 `grid`, `namedFrames`, `fullFrame`, `extrudeGrid`, `extrudeRects`), the
-sprite layer with its views and cameras, sprite pointer events, the baked
-tile layer, frame animation, key ordering, world-space text (a sprite
+sprite layer with its views and cameras, materials (the stock `unlit`
+with its blend and a `surface` slot over the sprite, `shaderMaterial`
+over the layer's GLSL set, per-sprite style records in any vertex format
+- the same three tiers and the same words as `@solidrt/3d`, the material
+on the layer because the layer is the batch), sprite pointer events, the
+baked tile layer, frame animation, key ordering, world-space text (a sprite
 font over the runtime's glyph engine is one more atlas, a run of text a
 group of glyph sprites: `createSpriteFont`, `addText`, `<Text2d>`), and
 the component face. Staged

package/examples/README.md

@@ -67,7 +67,7 @@ copy one and adapt it.
   `maxScreenPx`), a label bar that never grows past 24 px (`maxScreenPx`)
   and a selection ring that never shrinks under 48 px (`minScreenPx`,
   gliding to the tapped sprite through a position transition), the glow
-  layer the same atlas on `blend: "add"` with haloes that add up to white
+  layer the same atlas on `unlit({ blend: "add" })` with haloes that add up to white
   where they overlap. Picking follows the drawn size. Debug commands
   `zoom`, `select` and `pick` drive it headless.
 - `split-screen.tsx` - one `<SpriteLayer output={false}>` (sprites, no

package/examples/camera-probe.tsx

@@ -1,6 +1,6 @@
 // Camera-mapping probe: the live guard that the three spellings of the
-// camera mapping agree - projectCamera (camera.ts), the vertex stages'
-// uCameraRot (shaders.ts), and pointer dispatch's unprojectCamera
+// camera mapping agree - projectCamera (camera.ts), the vertex stage's
+// uCameraRot (glsl.ts), and pointer dispatch's unprojectCamera
 // (layer.ts). The headless check (tests/camera.test.ts) ties
 // projectCamera to the <view>-prop oracle but cannot see the shader; this
 // probe closes that gap on a real client. Self-asserting: watch the logs
@@ -11,8 +11,8 @@
 // What it checks, all under one rotated + pivoted camera:
 // 1. The shader implements projectCamera: a probe sprite samples opaque
 //    at its PROJECTED pixel and background at the unrotated position.
-// 2. VERTEX (records) and VERTEX_SPLIT (nodes) agree: pixel parity
-//    between the two layer kinds.
+// 2. The one vertex stage over the two record layouts (records, nodes)
+//    agrees with itself: pixel parity between the two layer kinds.
 // 3. Pointer dispatch round-trips: a pointer at the projected screen
 //    point hits the sprite and reports its world coordinates.
 // 4. Tile chunks bake with the pinned identity camera rotation.

package/examples/markers.tsx

@@ -7,7 +7,7 @@
 // px however far in you zoom (maxScreenPx alone), and the selection RING
 // that never shrinks under 48 px however far out (minScreenPx alone), so
 // the selected sprite stays findable at the overview. The glow layer is
-// the same atlas on a `blend: "add"` pipeline: half-lit haloes that
+// the same atlas on an additive material: half-lit haloes that
 // accumulate to white where they overlap, over the transparent clear.
 // Wheel or pinch to zoom, drag empty space to pan, tap a sprite to
 // select it (the ring glides along), tap empty space to deselect.
@@ -21,7 +21,7 @@
 // pixels) and the ring's; `pick` ({ x, y }) returns
 // what the world view hits at those VIEW pixels, as marker kinds.
 import { createEffect, createInputMap, createPointerFeed, decodeImage, displayScale, onFrame, render, windowSize } from "@solidrt/core"
-import { addSprite, camera2dActions, camera2dBindings, createAtlas, createCamera2d, createSpriteLayer, feedPointer, fitOversample, grid, setSprite, setSpriteTransition } from "@solidrt/2d"
+import { addSprite, camera2dActions, camera2dBindings, createAtlas, createCamera2d, createSpriteLayer, feedPointer, fitOversample, grid, setSprite, setSpriteTransition, unlit } from "@solidrt/2d"
 import type { Camera2dHandle, SpriteHandle, ViewHandle } from "@solidrt/2d"
 import { registerDebug } from "sol:dev"
 import logoBytes from "./logo.png" with { type: "binary" }
@@ -80,7 +80,7 @@ function App() {
   let frames = grid(atlas, 2, 2)
   let win = { width: 1, height: 1 }
   let layer = createSpriteLayer([atlas], { capacity: 128, label: "markers" })
-  let glow = createSpriteLayer([atlas], { capacity: 64, blend: "add", label: "glow" })
+  let glow = createSpriteLayer([atlas], { capacity: 64, material: unlit({ blend: "add" }), label: "glow" })
   world = layer.createView({ width: win.width, height: win.height, clearColor: [0.05, 0.05, 0.09, 1], label: "world" })
   let glowView = glow.createView({ width: win.width, height: win.height, clearColor: [0, 0, 0, 0], label: "glow" })
 

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@solidrt/2d",
-  "version": "0.0.71",
+  "version": "0.0.72",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
   "type": "module",
   "main": "src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./glsl": "./src/glsl.ts"
   },
   "files": [
     "src/",
@@ -15,10 +16,10 @@
     "AGENTS.md"
   ],
   "devDependencies": {
-    "@solidrt/test": "0.0.71"
+    "@solidrt/test": "0.0.72"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.13",
-    "@solidrt/core": "0.0.71"
+    "@solidrt/core": "0.0.72"
   }
 }

package/src/animation.ts

@@ -6,23 +6,42 @@
 // nothing - the demand-gate story unchanged. The clock is the app's frame
 // time: the clip freezes and resumes with the dev tools' clock, plays at
 // its own speed under `sol render`, and a step lands on the frame it is
-// due in. The clip
+// due in; with a `clock` it runs at that layer's, group's or sprite's
+// time rate instead, so one setTimeScale pauses the walk cycles with the
+// world. The clip
 // does not own its sprites (destroySprite prunes lazily on the next step),
 // and a sprite belongs to at most one animation. Plain JS over setSprite,
 // so it works on both layer kinds and composes with <Sprite> via ref (leave
 // the frame prop off - the clip owns that field).
 import { getOwner, onCleanup, onFrame, runWithOwner } from "@solidrt/core"
 import type { Frame } from "./frames.ts"
-import type { Sprite } from "./layer.ts"
-import { setSprite } from "./layer.ts"
+import type { Sprite, SpriteGroup, SpriteLayer } from "./layer.ts"
+import { setSprite, timeRate } from "./layer.ts"
 
 export type AnimationOptions = {
   /** Wrap around (default) or play once and hold the last frame. */
   loop?: boolean
+  /**
+   * Run on this layer's, group's or sprite's time (its `timeRate`, read
+   * every frame) instead of plain app time: the clip's step is the frame
+   * step times the rate, so a layer paused with `setTimeScale(0)` holds
+   * the walk cycles too, and a slow-motion group slows the flipbooks in
+   * it. One clock per clip, since every attached sprite shows the same
+   * frame; a destroyed clock reads as app time.
+   */
+  clock?: SpriteLayer | SpriteGroup | Sprite
   /** Skip the owner-scoped auto-dispose (the core resource contract). */
   autoFree?: boolean
 }
 
+/** The rate a clip's clock runs at now: the handle's own, or 1 without a
+ * clock or for one that is gone (a destroyed sprite, a record sprite). */
+function rateOf(clock: SpriteLayer | SpriteGroup | Sprite | undefined): number {
+  if (clock === undefined) return 1
+  if ("_root" in clock) return clock.timeRate()
+  return timeRate(clock) ?? 1
+}
+
 export type SpriteAnimation = {
   /** Current frame index into the clip. */
   frame(): number
@@ -66,6 +85,7 @@ export function createAnimation(frames: Frame[], fps: number, opts?: AnimationOp
     throw new Error(`createAnimation: fps must be positive, got ${fps}`)
   }
   let loop = opts?.loop !== false
+  let clock = opts?.clock
   let sprites = new Set<Sprite>()
   let current = 0
   let playing = true
@@ -116,8 +136,9 @@ export function createAnimation(frames: Frame[], fps: number, opts?: AnimationOp
   }
 
   function tick(now: number): void {
-    // Never backward: across a hot reload the frame time restarts.
-    if (lastTick !== null) elapsed += Math.max(0, now - lastTick)
+    // Never backward: across a hot reload the frame time restarts. The
+    // step is the frame step on the clock's time (rateOf: 1 without one).
+    if (lastTick !== null) elapsed += Math.max(0, now - lastTick) * rateOf(clock)
     lastTick = now
     let raw = Math.floor((elapsed * fps) / 1000)
     if (!loop && raw >= frames.length) {

package/src/atlas.ts

@@ -82,16 +82,20 @@ export function isAtlas(a: unknown): a is Atlas {
  * Validate a layer's `atlases` list (throws - the dev validation policy):
  * a non-empty array of distinct atlas records, no more than the device
  * binds in one pass (`limits.maxTextureUnits`, 16 on every GLES 3.0
- * device). Returns the texture -> sampler index map the layer resolves
+ * device) once the material's own `samplers` (its textures: a palette
+ * LUT, a noise texture) are counted in - the two lists bind on the same
+ * targets. Returns the texture -> sampler index map the layer resolves
  * frames through; the index is the atlas's position in the list.
  * Internal - every layer kind calls it.
  */
-export function checkAtlases(verb: string, atlases: readonly Atlas[]): Map<TextureId, number> {
+export function checkAtlases(verb: string, atlases: readonly Atlas[], samplers = 0): Map<TextureId, number> {
   if (!Array.isArray(atlases) || atlases.length === 0) {
     throw new Error(`${verb}: atlases must be a non-empty array of atlas records (createAtlas, or { texture, width, height })`)
   }
-  if (atlases.length > limits.maxTextureUnits) {
-    throw new Error(`${verb}: ${atlases.length} atlases exceed the ${limits.maxTextureUnits} sampler inputs one pass may bind (limits.maxTextureUnits); pack sheets together`)
+  if (atlases.length + samplers > limits.maxTextureUnits) {
+    throw new Error(
+      `${verb}: ${atlases.length} atlases${samplers > 0 ? ` plus the material's ${samplers} textures` : ""} exceed the ${limits.maxTextureUnits} sampler inputs one pass may bind (limits.maxTextureUnits); pack sheets together`,
+    )
   }
   let index = new Map<TextureId, number>()
   atlases.forEach((atlas, i) => {

package/src/camera.ts

@@ -3,7 +3,7 @@
 // imports, so its test (tests/camera.test.ts) exercises this
 // module headless on the flux binary. Three consumers implement or undo
 // exactly this mapping and must agree with it: the vertex stages
-// (shaders.ts, uCamera + uCameraRot), the tile layer's composite
+// (glsl.ts, uCamera + uCameraRot), the tile layer's composite
 // transform (the <view> props in components/tile-layer.tsx) and the pointer inverse
 // (spriteDispatch in layer.ts, which calls unprojectCamera directly). The
 // check keeps the spellings from drifting.
@@ -101,7 +101,7 @@ export function applyCamera(camera: CameraState, update: CameraUpdate): void {
   if (update.pivotY !== undefined) camera.pivotY = update.pivotY
 }
 
-/** The shared params the vertex stages (shaders.ts) read for a camera:
+/** The shared params the vertex stage (glsl.ts) reads for a camera:
  * uCamera [x, y, zoom, zoom] and uCameraRot [cos, sin, pivotX, pivotY]. */
 export function cameraParams(camera: CameraState): { uCamera: [number, number, number, number]; uCameraRot: [number, number, number, number] } {
   return {

package/src/components/camera2d.tsx

@@ -1,4 +1,4 @@
-import { createEffect, merge, onFrame, untrack } from "@solidrt/core"
+import { callRef, createEffect, merge, onFrame, untrack } from "@solidrt/core"
 import type { InputMap, VoidComponent } from "@solidrt/core"
 import { createCamera2d } from "../camera2d.ts"
 import type { Camera2d as Camera2dHandle, Camera2dAxes, Camera2dOptions } from "../camera2d.ts"
@@ -72,6 +72,6 @@ export let Camera2d: VoidComponent<Camera2dProps> = props => {
     () => untrack(() => cam.set({})),
     { defer: true },
   )
-  untrack(() => props.ref)?.(cam)
+  callRef(() => props.ref, cam)
   return null
 }