@solidrt/core 0.0.38 → 0.0.40

package/AGENTS.md

@@ -84,7 +84,7 @@ tsconfig.json - the two load-bearing lines are jsx + jsxImportSource:
 ```
 
 Peer deps @solidjs/signals and @solidjs/universal must match (currently
-2.0.0-beta.20); bun resolves them from peerDependencies.
+2.0.0-beta.26); bun resolves them from peerDependencies.
 
 ## Element model (the parts that are easy to get wrong)
 

package/examples/README.md

@@ -20,7 +20,7 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 - `pointer-local-coords.tsx` - the three pointer coordinate frames (`clientX` window, `localX` the handling node's own frame, `parentX` its path-parent's frame - where the node's x/y live) and the transform-proof drag idiom: grab offset from `localX` at down, place with `parentX - offset` on moves. Exact inside rotated/scaled ancestors and when the pointer leaves the node mid-drag.
 
 ## Performance
-- `repaint-boundary.tsx` - `repaintBoundary` on a `<view>` to keep static content from rebuilding while a neighbor animates: `{true}` retains the recorded draw list, `"snapshot"` also retains the rasterized pixels as a GPU texture (for raster-expensive, screen-aligned, static subtrees).
+- `repaint-boundary.tsx` - `repaintBoundary` on a `<view>` to keep static content from rebuilding while a neighbor animates: `{true}` retains the recorded draw list, `"snapshot"` also retains the rasterized pixels as a GPU texture (for raster-expensive, screen-aligned, static subtrees). `"snapshot-no-aa"` rasterizes without anti-aliasing: cheaper, fine for text and axis-aligned rects, hard-edged on vector content.
 
 ## Scrolling
 - `scroll.tsx` - `createScroll`, the headless scroll primitive: it owns only the clamped offset (re-clamped on layout); you supply the viewport/content nodes via refs, apply the offset to `scrollX`/`scrollY`, and wire input (e.g. `onWheel`) to `scrollBy` yourself.
@@ -35,7 +35,13 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 ## Images and GPU
 - `image.tsx` - `createImage` (async value: fetch + decode + upload) read inside a `<Loading>` boundary and shown with `<texture>`.
 - `inline-image.tsx` - bytes already in memory: `decodeImage` + `createTexture` (both synchronous) show an image with no `<Loading>` boundary. The sync counterpart to `image.tsx`.
-- `gpu-shader.tsx` - a GLSL fragment shader rendered to a texture, animated by driving its `iTime` uniform declaratively through the `<texture params={{...}}>` prop.
+- `gpu-shader.tsx` - a GLSL fragment shader rendered to a texture, animated by driving its `iTime` uniform declaratively through the `<texture params={{...}}>` prop. Shows both source dialects side by side: without a `#version` line the runtime injects the `vUV`/`iResolution`/`iTime`/`fragColor` preamble, while a source starting with `#version 300 es` is compiled exactly as written and names its own uniforms - which is what lets a shader written elsewhere run unchanged.
+- `gpu-texture-blend.tsx` - compositing two shader targets as stacked `<texture>` layers with `blendMode` ("plus" additive over a base pass), the alternative to a third shader that samples both. Click toggles against `"source-over"` to show why. The tree-level counterpart to blending within one draw (`gpu-particles.tsx`); without `blend: "add"` a target's own draw runs with GL blending disabled.
+- `gpu-raw-program.tsx` - the raw shading layer: compileShader/linkProgram/createShaderTarget, one vertex stage shared by two programs, with and without the standard header.
+- `gpu-pipeline.tsx` - `createPipeline`: a custom vertex+fragment pair drawing an interleaved vertex buffer (position and color attributes resolved by name), a depth-tested spinning cube whose `uTime` uniform is driven through `<texture params>` exactly like a fragment shader's.
+- `gpu-particles.tsx` - an additive particle field: `topology: "points"` with `blend: "add"`, so overlapping gaussian splats (`gl_PointSize` from the vertex stage, `gl_PointCoord` falloff, premultiplied output) accumulate into a glowing volume instead of overwriting. The tints are typed vec3 uniforms filled from 3-number array params.
+- `window-shader.tsx` - the `shader` prop on `<window>`: the finished frame drawn through a raw-linked warp program before present, click to toggle between warp and identity.
+- `window-shader-history.tsx` - the window shader's frame history: `previous` binds last frame as uPrevious, drawn as a one-frame motion echo behind an orbiting square; click toggles the echo term.
 
 ## Sound
 - `sound.tsx` - `createSound`: decode a clip once from bytes (here a binary import), replay cheaply; `overlap` stacking vs single-voice, `playing()` signal, release on unmount. Points to `createSoundStream` for long tracks streamed from a path.
@@ -44,4 +50,5 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 - `svg.tsx` - `<svg src={...}>` draws a whole SVG *document string* (not HTML/JSX children); multi-color fills vs a `currentColor` icon recolored by the `color` prop. This is how to use existing icon libraries (Lucide, Heroicons, etc.) - hand their SVG source to `src`.
 
 ## Bundling assets
-- `binary-import.tsx` - `import bytes from "./file" with { type: "binary" }` inlines a file's bytes into the bundle as a `Uint8Array` (the bytes are in memory, so `inline-image.tsx` displays them with the synchronous `decodeImage` + `createTexture` path). `with { type: "text" }` works the same way for a string.
+- `binary-import.tsx` - `import bytes from "./file" with { type: "binary" }` inlines a file's bytes into the bundle as a `Uint8Array` (the bytes are in memory, so `inline-image.tsx` displays them with the synchronous `decodeImage` + `createTexture` path).
+- `text-import.tsx` - `with { type: "text" }`, the string counterpart: inlines a `.glsl` shader source (`wave.glsl`) into the bundle, available synchronously with no runtime read. Works on any extension; `.svg` needs no attribute and `.glsl`/`.vert`/`.frag` are declared as text modules already.

package/examples/gpu-particles.tsx

@@ -0,0 +1,96 @@
+// An additive particle field: createPipeline with topology "points" and
+// blend "add". Each vertex is one particle; the vertex stage sets
+// gl_PointSize (honored across 4..64px) and the fragment stage shapes the
+// splat from gl_PointCoord. With blend: "add" overlapping splats accumulate
+// (glBlendFunc(ONE, ONE)) - order-independent, so the buffer needs no
+// sorting - which is what turns discrete discs into a smooth glowing field.
+// Without it a target's draw overwrites, and a point cloud can only thicken
+// into scaly overlap.
+//
+// Additive output is premultiplied by construction: write vec4(color * a, a)
+// and the target stays composite-correct in the tree. No depth buffer here -
+// nothing occludes anything in a pure additive pass. A scene where opaque
+// geometry should occlude the particles would add depth: true and pair the
+// blended draw with depthWrite: false, explicitly - neither option implies
+// the other.
+//
+// The tints are typed (vec3) uniforms driven from 3-number array params.
+import { render, onFrame, createSignal } from "@solidrt/core"
+import { createBuffer, createPipeline } from "@solidrt/core/gpu"
+
+let VERTEX = `
+in vec3 aPos;
+in float aSeed;
+out float vSeed;
+uniform float uTime;
+
+void main() {
+  float cy = cos(uTime * 0.4), sy = sin(uTime * 0.4);
+  vec3 p = vec3(cy * aPos.x - sy * aPos.z, aPos.y, sy * aPos.x + cy * aPos.z);
+  // Each particle breathes on its own phase.
+  p *= 1.0 + 0.15 * sin(uTime * 1.7 + aSeed * 40.0);
+  p.z += 2.2;
+
+  // Same perspective mapping as gpu-pipeline.tsx (near 1, far 10), clip y
+  // negated so camera-up displays up.
+  float f = 2.0;
+  gl_Position = vec4(p.x * f, -p.y * f, p.z * (11.0 / 9.0) - 20.0 / 9.0, p.z);
+  gl_PointSize = mix(10.0, 26.0, aSeed) / p.z;
+  vSeed = aSeed;
+}
+`
+
+let FRAGMENT = `
+in float vSeed;
+uniform vec3 uTintA;
+uniform vec3 uTintB;
+
+void main() {
+  // Soft gaussian falloff over the point sprite; gl_PointCoord is 0..1
+  // across the splat.
+  vec2 d = gl_PointCoord - 0.5;
+  float a = exp(-dot(d, d) * 14.0) * 0.35;
+  vec3 tint = mix(uTintA, uTintB, vSeed);
+  fragColor = vec4(tint * a, a);
+}
+`
+
+// Interleaved [pos vec3, seed f32]: points on a fibonacci sphere, so the
+// field reads as a volume from every angle.
+function particles(count: number): Float32Array {
+  let verts: number[] = []
+  let golden = Math.PI * (3.0 - Math.sqrt(5.0))
+  for (let i = 0; i < count; i++) {
+    let y = 1.0 - (2.0 * (i + 0.5)) / count
+    let r = Math.sqrt(1.0 - y * y)
+    let t = golden * i
+    let seed = (i * 0.61803399) % 1.0
+    verts.push(0.7 * r * Math.cos(t), 0.7 * y, 0.7 * r * Math.sin(t), seed)
+  }
+  return new Float32Array(verts)
+}
+
+function App() {
+  let bufferId = createBuffer(particles(1500))
+  let id = createPipeline(VERTEX, FRAGMENT, 512, 512, {
+    params: { uTime: 0, uTintA: [1.0, 0.45, 0.15], uTintB: [0.25, 0.5, 1.0] },
+    attributes: [
+      { name: "aPos", format: "vec3" },
+      { name: "aSeed", format: "f32" },
+    ],
+    buffer: bufferId,
+    topology: "points",
+    blend: "add",
+    clearColor: [0.02, 0.02, 0.05, 1],
+  })
+  let [time, setTime] = createSignal(0)
+  onFrame((tick) => setTime(tick / 1000))
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <texture src={id} params={{ uTime: time() }} width={420} height={420} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/gpu-raw-program.tsx

@@ -0,0 +1,76 @@
+// The raw shading layer: compileShader compiles one stage from complete GLSL
+// ES (nothing injected - the source declares its own #version, precision,
+// varyings and uniforms), linkProgram links a vertex and a fragment stage
+// into a program, and createShaderTarget builds a render target over it. One
+// program can back many targets, and creating a target compiles nothing, so
+// swapping precompiled programs is free of compilation. Stages can be
+// destroyed right after linking; the program keeps its own compiled copies.
+//
+// A raw program carries its own vertex stage, so a fullscreen pass is a
+// covering triangle from gl_VertexID with vertexCount: 3. Compare
+// gpu-shader.tsx, where the fused createShader does all of this in one call
+// with an injected preamble.
+import { render, onFrame, createSignal } from "@solidrt/core"
+import { compileShader, createShaderTarget, destroyShader, linkProgram } from "@solidrt/core/gpu"
+
+let VERTEX = `#version 300 es
+precision highp float;
+out vec2 vUV;
+void main() {
+  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+  vUV = p;
+  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+}
+`
+
+// Two fragment stages linked against the same vertex stage: two programs,
+// one shared compile of the vertex half.
+let WAVES = `#version 300 es
+precision highp float;
+in vec2 vUV;
+out vec4 fragColor;
+uniform float iTime;
+void main() {
+  float t = iTime * 2.0;
+  float a = 0.5 + 0.5 * sin(vUV.x * 10.0 + t);
+  float b = 0.5 + 0.5 * sin(vUV.y * 10.0 - t * 1.3);
+  fragColor = vec4(a, b, 1.0 - a * b, 1.0);
+}
+`
+
+// The standard header ({ header: true }) declares #version, precision,
+// iResolution/iTime and fragColor, so this source only adds its own inputs.
+let RINGS = `
+in vec2 vUV;
+void main() {
+  float d = length(vUV - 0.5);
+  float r = 0.5 + 0.5 * sin(d * 40.0 - iTime * 3.0);
+  fragColor = vec4(r, r * 0.6, 1.0 - r, 1.0);
+}
+`
+
+function App() {
+  let vs = compileShader("vertex", VERTEX)
+  let wavesFs = compileShader("fragment", WAVES)
+  let ringsFs = compileShader("fragment", RINGS, { header: true })
+  let waves = linkProgram(vs, wavesFs)
+  let rings = linkProgram(vs, ringsFs)
+  destroyShader(vs)
+  destroyShader(wavesFs)
+  destroyShader(ringsFs)
+
+  let wavesId = createShaderTarget(waves, 512, 512, { vertexCount: 3, params: { iTime: 0 } })
+  let ringsId = createShaderTarget(rings, 512, 512, { vertexCount: 3, params: { iTime: 0 } })
+
+  let [time, setTime] = createSignal(0)
+  onFrame(tick => setTime(tick / 1000))
+
+  return (
+    <window flexDirection="row" gap={16} alignItems="center" justifyContent="center">
+      <texture src={wavesId} params={{ iTime: time() }} width={360} height={360} />
+      <texture src={ringsId} params={{ iTime: time() }} width={360} height={360} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/gpu-shader.tsx

@@ -1,17 +1,32 @@
 // createShader compiles a GLSL ES 3.00 fragment shader and renders it into a
 // texture, returning a texture id you display with <texture src={id}>. The
-// fragment body may reference vUV (0..1, top-left origin), iResolution, iTime, and
-// any `uniform float` it declares; there is no #version line - the runtime injects
-// the preamble. The texture is freed automatically when the reactive owner is
-// disposed.
+// texture is freed automatically when the reactive owner is disposed.
+//
+// There are two source dialects and the source itself picks which one applies.
+// WITHOUT a #version line the runtime injects a preamble, so the body may
+// reference vUV (0..1, top-left origin), iResolution, iTime, and any uniform
+// it declares - the left square below. A source that STARTS
+// with #version 300 es is taken as complete and compiled exactly as written:
+// nothing is injected and it names its own uniforms - the right square.
+//
+// That second dialect is what lets a shader written for somewhere else run
+// here unchanged, without dropping to the raw layer; see gpu-raw-program.tsx
+// for what compileShader/linkProgram are actually for (sharing one compile
+// across several targets). The built-in vertex stage supplies vUV either way -
+// a complete source just has to declare `in vec2 vUV;` itself - and a uniform
+// named iResolution is filled with the target size by name in both dialects.
 //
 // iResolution is filled in for you, but iTime is NOT - drive it (and any other
 // uniform) declaratively via the <texture> element's params prop; it applies at
 // the next repaint, so a signal updated every frame stays paced to actual frames.
-// The shader's size is baked in at creation.
+// A param value is a number for a scalar uniform or a flat number array for a
+// typed one (2/3/4 numbers for vec2/vec3/vec4, 16 column-major for mat4),
+// dispatched by the shader's own declaration - uTint below is a vec3 driven
+// from one array value. The shader's size is baked in at creation.
 import { render, onFrame, createSignal } from "@solidrt/core"
 import { createShader } from "@solidrt/core/gpu"
 
+// Injected-preamble dialect: no #version, no declarations, no main() plumbing.
 let FRAGMENT = `
 void main() {
   vec2 uv = vUV;
@@ -23,16 +38,36 @@ void main() {
 }
 `
 
+// Complete-source dialect: declares its own version, precision, varying and
+// output, and calls its time uniform uSpin rather than iTime. uTint is a
+// typed (vec3) uniform, filled from a 3-number array param.
+let RAW_FRAGMENT = `#version 300 es
+precision highp float;
+in vec2 vUV;
+out vec4 fragColor;
+uniform float uSpin;
+uniform vec3 uTint;
+void main() {
+  vec2 p = vUV - 0.5;
+  float a = atan(p.y, p.x) + uSpin;
+  float r = length(p);
+  float band = 0.5 + 0.5 * sin(a * 6.0 + r * 18.0);
+  fragColor = vec4(band * uTint.r, band * uTint.g, 1.0 - band * uTint.b, 1.0);
+}
+`
+
 function App() {
   let id = createShader(FRAGMENT, 512, 512, { iTime: 0 })
+  let rawId = createShader(RAW_FRAGMENT, 512, 512, { uSpin: 0, uTint: [0.9, 0.4, 0.6] })
   let [time, setTime] = createSignal(0)
   onFrame((tick) => setTime(tick / 1000))
 
   return (
-    <window alignItems="center" justifyContent="center">
-      <texture src={id} params={{ iTime: time() }} width={400} height={400} />
+    <window alignItems="center" justifyContent="center" flexDirection="row" gap={16}>
+      <texture src={id} params={{ iTime: time() }} width={260} height={260} />
+      <texture src={rawId} params={{ uSpin: time() }} width={260} height={260} />
     </window>
   )
 }
 
-render(() => <App />)
+render(() => <App />)

package/examples/gpu-texture-blend.tsx

@@ -0,0 +1,78 @@
+// Compositing two GPU passes in the element tree: stack <texture> layers and
+// give the upper one a blendMode. This is how several shader targets combine -
+// a base pass plus an additive pass - without writing a third shader that
+// samples both. The full Skia blend set is available ("plus", "screen",
+// "multiply", ...), and texture alpha is premultiplied, so additive modes need
+// no manual premultiplication.
+//
+// It is also the ONLY blending there is. A target's own draw runs with GL
+// blending disabled, so overlapping geometry inside one shader or pipeline
+// overwrites rather than accumulates; splitting the work across targets and
+// compositing them here is the way to get transparency between passes.
+//
+// Click to toggle the upper layer between "plus" and "source-over". The glow
+// pass paints opaque black outside its ring, so source-over hides the base
+// entirely while plus adds only the lit pixels - black contributes nothing.
+import { render, onFrame, createSignal } from "@solidrt/core"
+import { createShader } from "@solidrt/core/gpu"
+
+let SIZE = 360
+
+// Base pass: a static gradient with a soft vignette. Nothing drives it, so it
+// renders once at creation and then holds - shaders re-render on params writes.
+let BASE = `
+void main() {
+  vec2 uv = vUV;
+  float v = 1.0 - length(uv - 0.5) * 1.1;
+  vec3 col = mix(vec3(0.04, 0.05, 0.14), vec3(0.15, 0.10, 0.42), uv.y);
+  fragColor = vec4(col * v, 1.0);
+}
+`
+
+// Additive pass: a breathing ring, black everywhere else.
+let GLOW = `
+void main() {
+  vec2 uv = vUV;
+  float r = length(uv - 0.5);
+  float radius = 0.28 + 0.04 * sin(iTime * 2.0);
+  float ring = smoothstep(0.06, 0.0, abs(r - radius));
+  fragColor = vec4(vec3(1.0, 0.55, 0.15) * ring, 1.0);
+}
+`
+
+function App() {
+  let baseId = createShader(BASE, SIZE, SIZE)
+  let glowId = createShader(GLOW, SIZE, SIZE, { iTime: 0 })
+  let [time, setTime] = createSignal(0)
+  let [mode, setMode] = createSignal<"plus" | "source-over">("plus")
+  onFrame((tick) => setTime(tick / 1000))
+
+  return (
+    <window
+      onPointerDown={() => setMode((m) => (m === "plus" ? "source-over" : "plus"))}
+      flexDirection="column"
+      alignItems="center"
+      justifyContent="center"
+      gap={12}
+    >
+      {/* The layers resolve against this box: absolute children need an
+          ancestor with position "relative". */}
+      <view position="relative" width={SIZE} height={SIZE}>
+        <texture src={baseId} position="absolute" top={0} left={0} width={SIZE} height={SIZE} />
+        <texture
+          src={glowId}
+          position="absolute"
+          top={0}
+          left={0}
+          width={SIZE}
+          height={SIZE}
+          blendMode={mode()}
+          params={{ iTime: time() }}
+        />
+      </view>
+      <text fontSize={14} color="#888">blendMode "{mode()}" - click to toggle</text>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/text-import.tsx

@@ -0,0 +1,29 @@
+// Importing a file with `with { type: "text" }` inlines its contents into the
+// bundle as a string. Like the binary form, the text travels inside the
+// compiled bytecode, so it is available synchronously - no runtime read, works
+// offline. The attribute works on any extension; `.svg` is text-loaded without
+// one, and `.glsl`/`.vert`/`.frag` are declared as text modules so shader
+// sources typecheck with no setup.
+//
+// This example shows only the text import itself: it reports the imported
+// file's size and first line. Shader sources are the motivating case - the
+// string is exactly what gpu-shader.tsx passes to createShader, moved out of
+// the .tsx so it can be edited as GLSL. Inlining trades update granularity for
+// zero I/O, so keep big or streamable files in assets/ and read them at
+// runtime instead.
+import { render } from "@solidrt/core"
+import source from "./wave.glsl" with { type: "text" }
+
+// The file's own first line - proof the real text is inlined, not a path.
+let firstLine = source.split("\n")[0] ?? ""
+
+function App() {
+  return (
+    <window alignItems="center" justifyContent="center" gap={8}>
+      <text fontSize={18} color="#e6e6e6">{source.length} characters inlined</text>
+      <text color="#888">starts with {firstLine}</text>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/wave.glsl

@@ -0,0 +1,13 @@
+// wave.glsl - animated scanline
+//
+// A plain fragment body in the injected-preamble dialect: no #version line, so
+// createShader prepends vUV / iResolution / iTime / fragColor. Living in its
+// own file it stays editable as GLSL instead of as a template literal.
+void main() {
+  vec2 uv = vUV;
+  float wave = sin(uv.x * 12.0 + iTime * 2.0) * 0.06;
+  float d = abs(uv.y - 0.5 - wave);
+  float line = smoothstep(0.05, 0.0, d);
+  vec3 col = mix(vec3(0.05, 0.07, 0.12), vec3(0.2, 0.8, 1.0), line);
+  fragColor = vec4(col, 1.0);
+}

package/examples/window-shader-history.tsx

@@ -0,0 +1,62 @@
+// `previous: true` on the window shader retains the last resolved frame as a
+// second layer the program samples as uPrevious, rotated each frame - a
+// one-frame history. Here it draws a motion echo behind the orbiting square;
+// click to toggle the echo term off and compare with the plain frame.
+import { render, onFrame, createSignal } from "@solidrt/core"
+import { compileShader, destroyShader, linkProgram } from "@solidrt/core/gpu"
+
+let VERTEX = `#version 300 es
+precision highp float;
+out vec2 vUV;
+void main() {
+  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+  // uSource/uPrevious are top-left origin; flip v so the frame lands upright.
+  vUV = vec2(p.x, 1.0 - p.y);
+  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+}
+`
+
+let ECHO = `
+uniform sampler2D uSource;
+uniform sampler2D uPrevious;
+uniform float uEcho;
+in vec2 vUV;
+void main() {
+  vec4 cur = texture(uSource, vUV);
+  vec4 prev = texture(uPrevious, vUV);
+  // Brightest of the current frame and the decayed previous one: motion
+  // leaves a one-frame ghost trailing it.
+  fragColor = max(cur, prev * uEcho);
+}
+`
+
+function App() {
+  let vs = compileShader("vertex", VERTEX)
+  let fs = compileShader("fragment", ECHO, { header: true })
+  let echoProgram = linkProgram(vs, fs)
+  destroyShader(vs)
+  destroyShader(fs)
+
+  let [angle, setAngle] = createSignal(0)
+  let [echo, setEcho] = createSignal(0.65)
+  onFrame(tick => setAngle(tick / 350))
+
+  return (
+    <window
+      shader={{ program: echoProgram, params: { uEcho: echo() }, previous: true }}
+      onPointerDown={() => setEcho(e => (e > 0 ? 0 : 0.65))}
+      alignItems="center"
+      justifyContent="center"
+    >
+      <rect position="absolute" top={0} right={0} bottom={0} left={0} color="#101826" />
+      <view width={70} height={70} x={Math.cos(angle()) * 150} y={Math.sin(angle()) * 150}>
+        <rect width={70} height={70} radius={16} color="#7ad0ff" />
+      </view>
+      <text position="absolute" bottom={24} fontSize={14} color="#99aabb">
+        Click to toggle the uPrevious echo
+      </text>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/window-shader.tsx

@@ -0,0 +1,71 @@
+// The window shader: the finished frame renders into a runtime-owned layer
+// texture and a linked program draws over it into the window, as the last
+// step before present. The program samples the frame as uSource (top-left
+// origin - the vertex stage flips v when mapping onto the window), gets
+// iResolution in physical pixels, and draws attributeless at vertexCount
+// (default 3, the covering triangle).
+//
+// Click anywhere to toggle the warp amount between 0 and 1: at 0 the program
+// is an identity pass, which must be indistinguishable from no shader at all
+// (the orientation/half-pixel regression check from the plan).
+import { render, onFrame, createSignal } from "@solidrt/core"
+import { compileShader, destroyShader, linkProgram } from "@solidrt/core/gpu"
+
+let VERTEX = `#version 300 es
+precision highp float;
+out vec2 vUV;
+void main() {
+  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+  // uSource is top-left origin; flip v so the frame lands upright on the
+  // window (the one flip of the frame path, done here in the vertex stage).
+  vUV = vec2(p.x, 1.0 - p.y);
+  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+}
+`
+
+// { header: true } declares #version, precision, iResolution/iTime and
+// fragColor; uSource, vUV, and the app's own uniforms are declared here.
+let WARP = `
+uniform sampler2D uSource;
+uniform float uAmount;
+in vec2 vUV;
+void main() {
+  vec2 uv = vUV;
+  uv.x += sin(uv.y * 24.0 + iTime * 3.0) * 0.012 * uAmount;
+  uv.y += sin(uv.x * 18.0 - iTime * 2.0) * 0.012 * uAmount;
+  fragColor = texture(uSource, uv);
+}
+`
+
+function App() {
+  let vs = compileShader("vertex", VERTEX)
+  let fs = compileShader("fragment", WARP, { header: true })
+  let warp = linkProgram(vs, fs)
+  destroyShader(vs)
+  destroyShader(fs)
+
+  let [time, setTime] = createSignal(0)
+  let [amount, setAmount] = createSignal(1)
+  onFrame(tick => setTime(tick / 1000))
+
+  return (
+    <window
+      shader={{ program: warp, params: { iTime: time(), uAmount: amount() } }}
+      onPointerDown={() => setAmount(a => (a > 0 ? 0 : 1))}
+      flexDirection="column"
+      gap={12}
+      alignItems="center"
+      justifyContent="center"
+    >
+      <text fontSize={28} color="#222">Window shader</text>
+      <view flexDirection="row" gap={12}>
+        <rect w={90} h={90} radius={12} color="#0077ff" />
+        <rect w={90} h={90} radius={12} color="#ff6a00" />
+        <rect w={90} h={90} radius={12} color="#00c46a" />
+      </view>
+      <text fontSize={14} color="#666">Click to toggle warp (identity at 0)</text>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -27,11 +27,11 @@
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.38"
+    "@solidrt/flux-types": "0.0.40"
   },
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-beta.20",
-    "@solidjs/universal": "2.0.0-beta.20",
-    "solid-js": "2.0.0-beta.20"
+    "@solidjs/signals": "2.0.0-beta.26",
+    "@solidjs/universal": "2.0.0-beta.26",
+    "solid-js": "2.0.0-beta.26"
   }
 }

package/src/gamepad.ts

@@ -15,6 +15,12 @@ import { on } from "srt:events"
  * "back", "guide", "leftShoulder", "rightShoulder", "leftStick",
  * "rightStick"). `axes` has sticks ("leftX", "leftY", "rightX", "rightY") in
  * -1..1 and triggers ("leftTrigger", "rightTrigger") in 0..1.
+ *
+ * The snapshot is a faithful report. Note that pressing "back" (select) on a
+ * mapped pad ALSO emits the `back` event (see onBack) - it is the pad-side
+ * sibling of Android's system back, the runtime's exit-to-launcher gesture.
+ * Apps that bind "back" for their own controls should preventDefault that
+ * event.
  */
 export interface GamepadState {
   /** Runtime instance id: unique per connection, not stable across reconnects. */

package/src/gpu.ts

@@ -7,6 +7,20 @@
 // to hold a params prop, e.g. a shader that only feeds another shader as a
 // sampler2D input. The imperative primitives (uploadTexture, setShaderParams,
 // destroyTexture, ...) live in the `flux:gpu` module.
+//
+// Sampling is a per-texture property declared at creation: `filter`
+// ("linear" default | "nearest") and `wrap` ("clamp" default | "repeat") on
+// every create* helper. One state for every consumer - `<texture>` display
+// and shader sampling both follow it - so a nearest texture upscales with
+// hard pixels everywhere (the retro/pixel-art path: render small, display
+// big). No mipmaps exist.
+//
+// Combining several passes is a render-tree job, not a shader one: stack
+// `<texture>` elements and set their `blendMode` (e.g. `blendMode="plus"` for
+// an additive pass over a base pass) instead of writing a pass that samples
+// both. WITHIN one pipeline draw, `blend: "add"` accumulates overlapping
+// geometry additively (order-independent, no sorting); anything else draws
+// with GL blending disabled and overwrites.
 
 import { createEffect, createSignal, getOwner, onCleanup, untrack } from "@solidjs/signals"
 import * as gpu from "flux:gpu"
@@ -18,6 +32,11 @@ import * as gpu from "flux:gpu"
 // owner: a leak until unmount, then a double-free against manual destroys.
 export type CreateOptions = { manual?: boolean }
 
+// Sampling options every texture-producing create* helper accepts, applied at
+// creation as a property of the texture id (there is no set-sampler-later).
+export type SamplerOptions = { filter?: gpu.FilterMode; wrap?: gpu.WrapMode }
+export type { FilterMode, WrapMode } from "flux:gpu"
+
 // Re-exported so callers that depend on @solidrt/core -- like @solidrt/components
 // -- need not import flux directly: destroyTexture for the manual-cleanup path
 // (textures made outside a reactive scope, e.g. after an await, are not
@@ -42,13 +61,35 @@ export {
 // its buffer gained or lost dynamic geometry; destroyBuffer is the manual
 // cleanup path for buffers created outside a reactive scope.
 export { destroyBuffer, setDrawCount } from "flux:gpu"
-export type { Topology, VertexAttribute } from "flux:gpu"
+export type { BlendMode, ShaderParams, Topology, VertexAttribute } from "flux:gpu"
+
+// The raw shading layer, re-exported as-is - no reactive wrapper, the app
+// owns these lifetimes. compileShader compiles one stage from complete GLSL
+// ES (or with the standard header via { header: true }); linkProgram links a
+// vertex and a fragment stage into a program handle that backs any number of
+// createShaderTarget calls (and compiles nothing per target); destroyShader /
+// destroyProgram free by id space, either order safe against live targets.
+// createShader/createPipeline remain the fused conveniences on top.
+export { compileShader, destroyProgram, destroyShader, linkProgram } from "flux:gpu"
 
 // captureSnapshot renders a node to a texture and readTexture reads any
-// texture's bytes back. Re-exported raw (no reactive auto-cleanup wrapper):
+// texture's bytes back. A laid-out node captures its layout box; a `d-*` node
+// captures its painted box - its own w/h when set, else the nearest laid-out
+// ancestor's box, its x/y offset mapped to the texture origin. Re-exported raw
+// (no reactive auto-cleanup wrapper):
 // captureSnapshot resolves asynchronously, by which point the reactive owner is
 // no longer current, so the caller owns the returned id and frees it with
 // destroyTexture (as with any texture created after an await).
+//
+// Together they are the one-shot bake path: draw something only the engine can
+// produce (shaped text, an SVG, a themed view), capture it, read the pixels and
+// process them on the CPU - baking a glyph atlas is the worked example. Not a
+// rendering path: a capture rasterizes the subtree offscreen, reads it back to
+// the CPU and re-uploads it, costing a full GPU -> CPU -> GPU round trip and a
+// paint pass of latency every call. Batch captures (one paint pass services
+// many), never run them per frame, and do not use them to feed live screen
+// content into a shader - for that the source has to update in place (another
+// pipeline's target, a camera texture).
 export { captureSnapshot, readTexture } from "flux:gpu"
 
 /**
@@ -62,8 +103,13 @@ export { captureSnapshot, readTexture } from "flux:gpu"
  * yourself. Pass `{ manual: true }` to skip the auto-free and own the
  * disposal yourself even inside a reactive scope.
  */
-export function createTexture(data: Uint8Array, width: number, height: number, opts?: CreateOptions): number {
-  let id = gpu.createTexture(data, width, height)
+export function createTexture(
+  data: Uint8Array,
+  width: number,
+  height: number,
+  opts?: CreateOptions & SamplerOptions,
+): number {
+  let id = gpu.createTexture(data, width, height, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
@@ -77,8 +123,13 @@ export function createTexture(data: Uint8Array, width: number, height: number, o
  * outside a reactive scope you must call `destroyTexture` (from flux:gpu)
  * yourself.
  */
-export function createMutableTexture(data: Uint8Array, width: number, height: number, opts?: CreateOptions): number {
-  let id = gpu.createMutableTexture(data, width, height)
+export function createMutableTexture(
+  data: Uint8Array,
+  width: number,
+  height: number,
+  opts?: CreateOptions & SamplerOptions,
+): number {
+  let id = gpu.createMutableTexture(data, width, height, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
@@ -87,46 +138,104 @@ export function createMutableTexture(data: Uint8Array, width: number, height: nu
  * Compiles a GLSL ES 3.00 fragment shader and renders it into a texture,
  * returning the texture id (usable anywhere a normal texture id is, e.g.
  * `<texture src>`). The fragment body may reference `vUV` (0..1, top-left
- * origin), `iResolution`, `iTime`, and any `uniform float` it declares; drive
- * their values with `<texture src={id} params={{...}} />` (preferred) or, when
- * there is no `<texture>` element for it, imperatively with `setShaderParams`.
+ * origin), `iResolution`, `iTime`, and any uniform it declares (`float`/`int`
+ * scalars from a number, `vec2`/`vec3`/`vec4`/`mat4` from a flat number
+ * array); drive their values with `<texture src={id} params={{...}} />`
+ * (preferred) or, when there is no `<texture>` element for it, imperatively
+ * with `setShaderParams`.
  * `textures` binds each declared `uniform sampler2D` to an existing texture id
- * (e.g. a camera or decoded image) so the shader can read it; those inputs are
- * re-sampled on every params update, so live sources stay current. Frees the
+ * (e.g. a camera or decoded image, or another shader/pipeline target) so the
+ * shader can read it; bound inputs are live dependencies, so the shader
+ * re-renders whenever a source changes - including a sampled target
+ * re-rendering, transitively through chains. Frees the
  * texture and shader program when the reactive owner is disposed (opt out
  * with `{ manual: true }`); create outside any reactive scope for
  * app-lifetime shaders. For a shader whose source or inputs change
  * reactively, use {@link createShaderMemo} instead.
+ *
+ * That preamble (`#version 300 es`, precision, `vUV`, `iResolution`, `iTime`,
+ * `fragColor`) is injected only into sources that do not declare their own
+ * `#version` line. A source starting with `#version 300 es` compiles exactly
+ * as written, so a shader carrying its own uniform names - one ported from
+ * elsewhere - runs unchanged here without dropping to compileShader /
+ * linkProgram. The built-in vertex stage still supplies `vUV`; declare
+ * `in vec2 vUV;` yourself to read it.
  */
 export function createShader(
   fragmentSrc: string,
   width: number,
   height: number,
-  params?: Record<string, number>,
+  params?: gpu.ShaderParams,
   textures?: Record<string, number>,
-  opts?: CreateOptions,
+  opts?: CreateOptions & SamplerOptions,
+): number {
+  let id = gpu.createShader(fragmentSrc, width, height, params, textures, opts)
+  if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
+  return id
+}
+
+/**
+ * Creates a render target over a program from `linkProgram` and renders it
+ * once, returning the texture id (usable anywhere a normal texture id is,
+ * e.g. `<texture src>`; resize with `setShaderSize`, drive uniforms with
+ * `<texture params>` or `setShaderParams`). Many targets may share one
+ * program, and creating a target compiles nothing. The mesh options mirror
+ * `createPipeline`: a raw-linked program carries its own vertex stage, so a
+ * fullscreen pass is `{ vertexCount: 3 }` over a covering-triangle vertex
+ * stage. Frees the target when the reactive owner is disposed (opt out with
+ * `opts.manual`); the program is yours and outlives it.
+ */
+export function createShaderTarget(
+  program: number,
+  width: number,
+  height: number,
+  opts?: {
+    params?: gpu.ShaderParams
+    textures?: Record<string, number>
+    attributes?: gpu.VertexAttribute[]
+    buffer?: number
+    topology?: gpu.Topology
+    vertexCount?: number
+    depth?: boolean
+    depthWrite?: boolean
+    blend?: gpu.BlendMode
+    clearColor?: [number, number, number, number]
+  } & CreateOptions &
+    SamplerOptions,
 ): number {
-  let id = gpu.createShader(fragmentSrc, width, height, params, textures)
+  let id = gpu.createShaderTarget(program, width, height, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
 
-/** The reactive shader description `createShaderMemo` builds from. */
+/** The reactive shader description `createShaderMemo` builds from. Sampling
+ * (`filter`/`wrap`) is creation-time state, so changing it rebuilds at a
+ * fresh id, like a fragment-source or sampler-binding change. */
 export type ShaderSpec = {
   fragmentSrc: string
   width: number
   height: number
-  params?: Record<string, number>
+  params?: gpu.ShaderParams
   textures?: Record<string, number>
+} & SamplerOptions
+
+// Shallow name->value equality for params/textures records; treats undefined
+// as the empty record. A param value may be a number or a flat number array
+// (typed uniforms), so arrays compare elementwise.
+function sameValue(a: number | number[] | undefined, b: number | number[] | undefined): boolean {
+  if (a === b) return true
+  if (!Array.isArray(a) || !Array.isArray(b)) return false
+  return a.length === b.length && a.every((v, i) => v === b[i])
 }
 
-// Shallow name->number equality for params/textures records; treats undefined
-// as the empty record.
-function sameRecord(a: Record<string, number> | undefined, b: Record<string, number> | undefined): boolean {
+function sameRecord(
+  a: Record<string, number | number[]> | undefined,
+  b: Record<string, number | number[]> | undefined,
+): boolean {
   if (a === b) return true
   let ka = a ? Object.keys(a) : []
   let kb = b ? Object.keys(b) : []
-  return ka.length === kb.length && ka.every(k => a![k] === b![k])
+  return ka.length === kb.length && ka.every(k => sameValue(a![k], b![k]))
 }
 
 /**
@@ -141,28 +250,57 @@ function sameRecord(a: Record<string, number> | undefined, b: Record<string, num
  * so the swap never paints a blank frame. The current id is freed when the
  * owning scope is disposed. Data textures need no analog: `uploadTexture` and
  * `resizeTexture` already cover their reactive changes id-stably.
+ *
+ * `onError` makes a failed rebuild survivable. Without it a shader that does
+ * not compile throws from inside the effect, where no caller can catch it;
+ * with it the error is handed to you and the last shader that DID compile
+ * stays current - id, size, params and accessor all unchanged - so the app
+ * keeps drawing the previous frame's shader instead of tearing down. That is
+ * the normal case whenever the source is not known-good: a shader editor, live
+ * coding, or a dialect ported from elsewhere. The initial compile is not
+ * covered: it throws at the call site, where an ordinary try/catch works and
+ * there is no previous shader to fall back to.
  */
-export function createShaderMemo(spec: () => ShaderSpec): () => number {
+export function createShaderMemo(
+  spec: () => ShaderSpec,
+  opts?: { onError?: (error: unknown) => void },
+): () => number {
+  let make = (s: ShaderSpec) =>
+    gpu.createShader(s.fragmentSrc, s.width, s.height, s.params, s.textures, { filter: s.filter, wrap: s.wrap })
   let current = untrack(spec)
-  let currentId = gpu.createShader(current.fragmentSrc, current.width, current.height, current.params, current.textures)
+  let currentId = make(current)
   let [id, setId] = createSignal(currentId)
   createEffect(spec, next => {
-    if (next.fragmentSrc === current.fragmentSrc && sameRecord(next.textures, current.textures)) {
-      // Program and inputs unchanged: mutate in place, the id stays stable.
-      if (next.width !== current.width || next.height !== current.height) {
-        gpu.setShaderSize(currentId, next.width, next.height)
-      }
-      if (!sameRecord(next.params, current.params) && next.params) {
-        gpu.setShaderParams(currentId, next.params)
+    try {
+      if (
+        next.fragmentSrc === current.fragmentSrc &&
+        sameRecord(next.textures, current.textures) &&
+        next.filter === current.filter &&
+        next.wrap === current.wrap
+      ) {
+        // Program and inputs unchanged: mutate in place, the id stays stable.
+        if (next.width !== current.width || next.height !== current.height) {
+          gpu.setShaderSize(currentId, next.width, next.height)
+        }
+        if (!sameRecord(next.params, current.params) && next.params) {
+          gpu.setShaderParams(currentId, next.params)
+        }
+        current = next
+        return
       }
+      // Compile before touching any state: a throw here must leave `current`,
+      // `currentId` and the accessor all still pointing at the last shader
+      // that worked, which is what makes onError's keep-last-good real.
+      let rebuilt = make(next)
+      let old = currentId
       current = next
-      return
+      currentId = rebuilt
+      setId(rebuilt)
+      gpu.destroyTexture(old)
+    } catch (error) {
+      if (!opts?.onError) throw error
+      opts.onError(error)
     }
-    let old = currentId
-    current = next
-    currentId = gpu.createShader(next.fragmentSrc, next.width, next.height, next.params, next.textures)
-    setId(currentId)
-    gpu.destroyTexture(old)
   })
   if (getOwner()) onCleanup(() => gpu.destroyTexture(currentId))
   return id
@@ -182,12 +320,19 @@ function toUint8(data: ArrayBuffer | ArrayBufferView): Uint8Array {
  * e.g. `<texture src>`). Unlike `createShader` the vertex stage is yours:
  * declare `in` attributes matching `opts.attributes` (one interleaved vertex
  * in `opts.buffer`, a {@link createBuffer} id) and your own varyings toward
- * the fragment stage. Both sources may reference `iResolution`/`iTime` and any
- * `uniform float` they declare; drive values with `<texture src={id}
- * params={{...}} />` or `setShaderParams`, exactly like a fragment shader.
+ * the fragment stage. Both sources may reference `iResolution`/`iTime` and
+ * any uniform they declare (`float`/`int` scalars from a number,
+ * `vec2`/`vec3`/`vec4`/`mat4` from a flat number array); drive values with
+ * `<texture src={id} params={{...}} />` or `setShaderParams`, exactly like a
+ * fragment shader.
  * `opts.depth` attaches a private depth buffer (cleared + tested per render);
- * `opts.vertexCount` defaults to the whole buffer and can be changed later
- * with `setDrawCount`. Frees the texture and GL program when the reactive
+ * `opts.depthWrite: false` (requires depth) keeps the test but stops the
+ * draw from writing depth. `opts.blend: "add"` makes the draw accumulate
+ * overlapping geometry additively (order-independent, no sorting) instead of
+ * overwriting; a depth-tested additive pass is `{ depth: true, blend: "add",
+ * depthWrite: false }` - each option only does what it says, neither implies
+ * the other. `opts.vertexCount` defaults to the whole buffer and can be
+ * changed later with `setDrawCount`. Frees the texture and GL program when the reactive
  * owner is disposed (opt out with `opts.manual`); create outside any reactive
  * scope for app-lifetime pipelines.
  */
@@ -197,15 +342,18 @@ export function createPipeline(
   width: number,
   height: number,
   opts?: {
-    params?: Record<string, number>
+    params?: gpu.ShaderParams
     textures?: Record<string, number>
     attributes?: gpu.VertexAttribute[]
     buffer?: number
     topology?: gpu.Topology
     vertexCount?: number
     depth?: boolean
+    depthWrite?: boolean
+    blend?: gpu.BlendMode
     clearColor?: [number, number, number, number]
-  } & CreateOptions,
+  } & CreateOptions &
+    SamplerOptions,
 ): number {
   let id = gpu.createPipeline(vertexSrc, fragmentSrc, width, height, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))

package/src/index.ts

@@ -27,6 +27,7 @@ export type {
   TextEvent,
   PaintProps,
   WindowProps,
+  WindowShaderProps,
   ViewProps,
   RectProps,
   OvalProps,

package/src/runtime-modules.d.ts

@@ -8,9 +8,25 @@ declare module "*.svg" {
   export default content
 }
 
+// Text asset imports: `import src from "./effect.glsl" with { type: "text" }`.
+// The bundler inlines the file's UTF-8 contents as a string literal, so a
+// shader source travels in the bundle and needs no runtime read.
+declare module "*.glsl" {
+  const content: string
+  export default content
+}
+declare module "*.vert" {
+  const content: string
+  export default content
+}
+declare module "*.frag" {
+  const content: string
+  export default content
+}
+
 // Binary asset imports: `import data from "./pic.png" with { type: "binary" }`.
 // The bundler inlines the file's bytes as a Uint8Array (see packages/cli
-// bundler `binaryImport`); feed it straight into createImage/decodeImage.
+// bundler `inlineImport`); feed it straight into createImage/decodeImage.
 declare module "*.png" {
   const bytes: Uint8Array
   export default bytes
@@ -83,10 +99,24 @@ declare module "srt:apps" {
   export const available: boolean
   /**
    * An installed app: id, display name (the installed manifest's displayName,
-   * defaulting to the id) and current version id (manifest hash).
+   * defaulting to the id) and current version id (manifest hash). `updated` is
+   * when that version became current, in milliseconds since the epoch (0 when
+   * the store's timestamp is unreadable); a repush of an identical manifest
+   * installs nothing and leaves it alone. `size` is the version's
+   * manifest-declared size (bundle plus assets) - claimed rather than walked,
+   * so that listing stays cheap; `info()` reports what is actually on disk.
+   * `icon` is the manifest-declared icon's SVG source, ready for an `<svg>`
+   * src; absent when the app declares none (or the file is unreadable).
    */
-  export type InstalledApp = { id: string; name: string; version: string }
-  /** Installed apps, sorted by name. */
+  export type InstalledApp = {
+    id: string
+    name: string
+    icon?: string
+    version: string
+    updated: number
+    size: number
+  }
+  /** Installed apps, most recently updated first. */
   export function list(): InstalledApp[]
   /**
    * A stored version: id (manifest hash), bytes on disk, whether it is the

package/src/types.d.ts

@@ -275,6 +275,49 @@ export interface WindowProps extends LayoutProps, PointerProps {
   children?: Children
   title?: string
   fullscreen?: boolean
+  /**
+   * Run the window's finished frame through a GPU program as the last step
+   * before it reaches the screen. While declared, the frame renders into a
+   * runtime-owned layer texture the program samples; removing the prop
+   * restores the direct path and frees the layer. Everything else about the
+   * program (compiling, linking, lifetime) is the raw shading layer's:
+   * see compileShader/linkProgram.
+   */
+  shader?: WindowShaderProps | null
+}
+
+/**
+ * A window shader declaration. The program reads the frame through
+ * `uniform sampler2D uSource` (top-left origin, like every sampled texture -
+ * so a vertex stage mapping it onto the window flips the v coordinate) and
+ * is drawn attributeless as triangles, `vertexCount` vertices fetched via
+ * gl_VertexID. `iResolution`, filled by name, is the window size in physical
+ * pixels (the pass covers exactly that). The window is cleared to opaque
+ * black first, so geometry that does not cover it still presents a defined
+ * frame.
+ */
+export interface WindowShaderProps {
+  /** Linked program handle from linkProgram. */
+  program: number
+  /**
+   * Uniforms filled by name, paced to the next real repaint. A number drives
+   * a scalar (`float`/`int`); a flat number array drives the declared GLSL
+   * type: 2/3/4 for `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`.
+   */
+  params?: Record<string, number | number[]>
+  /** Extra sampler2D inputs: uniform name to texture id. */
+  textures?: Record<string, number>
+  /** Vertices drawn (attributeless triangles). Default 3, the covering triangle. */
+  vertexCount?: number
+  /**
+   * Retain the last frame as a second layer the program samples as
+   * `uniform sampler2D uPrevious` (one-frame history: motion echo, frame
+   * differencing). Costs one extra window-sized texture while declared.
+   * Until a second frame exists uPrevious samples opaque black. Only declare
+   * the uPrevious uniform together with this flag - without it the uniform
+   * stays at unit 0 and aliases uSource. Default false.
+   */
+  previous?: boolean
 }
 
 export interface ViewProps extends LayoutProps, TransformProps, PointerProps {
@@ -297,8 +340,13 @@ export interface ViewProps extends LayoutProps, TransformProps, PointerProps {
    * on layout-size or display-scale changes. Content painted outside the
    * element's layout box is cropped, and ancestor scale animations smear the
    * bitmap; best for screen-aligned, static, raster-expensive content.
+   *
+   * "snapshot-no-aa" is "snapshot" rasterized without anti-aliasing: cheaper
+   * (no multisampled scratch, one render pass), but vector content - svg
+   * paths, rounded corners, rotated edges - comes out hard-edged. Text and
+   * axis-aligned rects look identical, so prefer it for plain UI panels.
    */
-  repaintBoundary?: boolean | "snapshot"
+  repaintBoundary?: boolean | "snapshot" | "snapshot-no-aa"
 }
 
 // draw primitives
@@ -363,7 +411,16 @@ export interface TextProps extends Position, PaintProps, PointerProps {
   maxLines?: number
 }
 
-export interface TextureProps extends Position, PointerProps {
+/**
+ * A raster draw uses only part of a paint. `blendMode` applies, which is how
+ * two GPU layers composite in the tree (a solid pass plus an additive pass)
+ * without a hand-written compositing shader. `color` contributes its alpha
+ * only, as an opacity multiplier; its RGB does not tint, and a gradient does
+ * not replace the texture. `drawStyle` and the stroke props have no effect.
+ * Texture alpha is premultiplied, so additive modes need no manual
+ * premultiplication.
+ */
+export interface TextureProps extends Position, PaintProps, PointerProps {
   src?: number
   /**
    * How the texture's pixels map to the element box (CSS object-fit).
@@ -381,6 +438,9 @@ export interface TextureProps extends Position, PointerProps {
   srcH?: number
   // Shader uniform values, when src names a shader texture. Applied at the
   // next repaint (not synchronously), so a fast-changing signal stays paced
-  // to real frames rather than triggering a GL render pass per write.
-  params?: Record<string, number>
+  // to real frames rather than triggering a GL render pass per write. A
+  // number drives a scalar (`float`/`int`); a flat number array drives the
+  // declared GLSL type: 2/3/4 for `vec2`/`vec3`/`vec4`, 16 (column-major)
+  // for `mat4`.
+  params?: Record<string, number | number[]>
 }

package/src/window.ts

@@ -190,22 +190,38 @@ export function onWindowBlur(fn: () => void) {
 
 export type BackEvent = { preventDefault: () => void }
 
-// App handlers for the window-level back event, run in registration order.
-// Kept in a local registry (not per-handler bus subscriptions) so the default
-// action runs exactly once, after every handler has had its say.
-let backHandlers = new Set<(e: BackEvent) => void>()
+// App handlers for the window-level back event, as a stack: the last one
+// registered is offered the event first, and the first to prevent ends the
+// dispatch. Back is a pop, so the thing most recently put on screen has to
+// answer for it - a dialog that opens over a screen registers after it and must
+// win, and registration order tracks mount order (a parent sets up before its
+// children), so reverse order also reads as innermost-first. Kept in a local
+// registry rather than per-handler bus subscriptions so the default action runs
+// exactly once, after the handlers have had their say.
+let backHandlers: ((e: BackEvent) => void)[] = []
 
 /**
  * Calls `fn` on the user's back intent (Android back button/gesture, the
  * desktop dev chord). Call `e.preventDefault()` when back means in-app
  * navigation right now (close a modal, previous screen); unprevented, the
- * default action runs: exit(). Apps without a handler exit on back
- * everywhere, which is the correct zero-effort default.
+ * event passes to the handler registered before this one, and if none of them
+ * prevents it either, to the default action: exit(). Apps without a handler
+ * exit on back everywhere, which is the correct zero-effort default.
+ *
+ * Handlers form a stack: the most recently registered runs first and the first
+ * to prevent ends the dispatch, so each screen or overlay owns one step of the
+ * back stack and none of them needs to know what the others are doing. A
+ * handler that does not prevent must not act either - the event is still on its
+ * way to whoever will handle it.
+ *
  * Returns a cleanup function; also auto-cleans within a reactive scope.
  */
 export function onBack(fn: (e: BackEvent) => void) {
-  backHandlers.add(fn)
-  let cleanup = () => backHandlers.delete(fn)
+  backHandlers.push(fn)
+  let cleanup = () => {
+    let i = backHandlers.lastIndexOf(fn)
+    if (i >= 0) backHandlers.splice(i, 1)
+  }
   onCleanup(cleanup)
   return cleanup
 }
@@ -338,7 +354,9 @@ export function attachWindow(_nodeId: number) {
         },
       }
       // Copy first: a handler may unregister (itself or others) mid-dispatch.
-      for (let fn of [...backHandlers]) fn(e)
+      // Top of the stack down, stopping as soon as one takes the event.
+      let stack = [...backHandlers]
+      for (let i = stack.length - 1; i >= 0 && !prevented; i--) stack[i]!(e)
       if (!prevented) exit()
     })