@solidrt/core 0.0.39 → 0.0.40

package/examples/README.md

@@ -35,8 +35,11 @@ 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.
 
@@ -47,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/package.json

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

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,7 +61,7 @@ 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
@@ -54,7 +73,10 @@ export type { Topology, VertexAttribute } from "flux:gpu"
 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).
@@ -81,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
 }
@@ -96,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
 }
@@ -106,26 +138,38 @@ 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)
+  let id = gpu.createShader(fragmentSrc, width, height, params, textures, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
@@ -146,37 +190,52 @@ export function createShaderTarget(
   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.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]))
 }
 
 /**
@@ -191,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
@@ -232,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.
  */
@@ -247,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/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

package/src/types.d.ts

@@ -299,8 +299,12 @@ export interface WindowProps extends LayoutProps, PointerProps {
 export interface WindowShaderProps {
   /** Linked program handle from linkProgram. */
   program: number
-  /** Float uniforms filled by name, paced to the next real repaint. */
-  params?: Record<string, 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. */
@@ -434,6 +438,9 @@ export interface TextureProps extends Position, PaintProps, 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[]>
 }