@solidrt/core 0.0.39 → 0.0.41

package/AGENTS.md

@@ -55,8 +55,9 @@ you need the raw fact (e.g. `env.displayScale` for asset sizing below).
 Because the drawn size is fluid and the display DPI varies, asset format is a
 real design decision, not an afterthought:
 
-- Prefer VECTORS (`<svg>`, `<d-path>`) whenever the render size is fluid or DPI
-  varies - they stay crisp at any size x `displayScale()`.
+- Prefer VECTORS (`parseSvg` draws mapped to `<d-path>` in a `viewBox` view)
+  whenever the render size is fluid or DPI varies - they stay crisp at any
+  size x `displayScale()`.
 - RASTER (`<texture>` / `createImage`) needs source resolution >= displayed size
   x `env.displayScale`, or it softens on hi-DPI. Author raster at 2-3x the
   largest size you will ever draw it. A 256px PNG blown up large on a hi-DPI

package/README.md

@@ -2,7 +2,7 @@
 
 A low-level toolkit for creating cross-platform applications.
 
-_SolidRT is in pre-alpha stage. Anything can and will be changed._
+_SolidRT is in alpha: useful today, but APIs are still stabilizing._
 
 > LLM agents: see [AGENTS.md](./AGENTS.md) for a dense, self-contained quickstart.
 

package/examples/README.md

@@ -35,8 +35,12 @@ 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-raw-program.tsx` - the raw shading layer: compileShader/linkProgram/createShaderTarget, one vertex stage shared by two programs, with and without the standard header.
+- `gpu-shader.tsx` - a GLSL fragment shader rendered to a texture via `createShaderTexture`, animated by driving its own `uTime` uniform declaratively through the `<texture params={{...}}>` prop. Shows both source dialects side by side: without a `#version` line the runtime injects the `vUV`/`iResolution`/`fragColor` preamble (exactly what the runtime provides - app-driven uniforms are the source's own declarations), 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/createRenderPipeline/createShaderTarget, one vertex stage shared by two programs, with and without the standard header.
+- `gpu-pipeline.tsx` - `createPipelineTexture`: 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.
+- `gpu-instancing.tsx` - instanced drawing: one 3-vertex triangle drawn hundreds of times via `instanceCount`, each instance placed and tinted on a phyllotaxis spiral from `gl_InstanceID` alone. `setDraw(id, { instanceCount })` merges into the draw range per frame (absent keys keep their values, like params), so the population breathes without touching the buffer.
 - `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.
 
@@ -44,7 +48,8 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 - `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.
 
 ## Vector graphics
-- `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`.
+- `parse-svg.tsx` - `parseSvg` turns a whole SVG *document string* (not HTML/JSX children) into plain draw data mapped to `<d-path>` inside a `viewBox`-fitted view; per-shape hover highlighting shows the payoff (exact-outline hit testing, recolor without re-parse), plus a `currentColor` icon recolored via the `color` option. This is how to use existing icon libraries (Lucide, Heroicons, etc.) - hand their SVG source to `parseSvg`.
 
 ## 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-instancing.tsx

@@ -0,0 +1,70 @@
+// Instanced drawing: one 3-vertex triangle in the buffer, drawn hundreds of
+// times with instanceCount (glDrawArraysInstanced, native ES 3.0). The vertex
+// stage tells copies apart by gl_InstanceID - here each instance becomes one
+// petal on a phyllotaxis spiral, placed and tinted from its index alone, so
+// the geometry buffer stays 6 floats no matter the population.
+//
+// The draw range is data: setDraw merges partial updates like params, so the
+// per-frame write below changes only instanceCount while firstVertex and
+// vertexCount keep their values (the whole buffer). instanceCount 0 would
+// draw nothing - the population legitimately breathes down to a single
+// petal and could go dark the same way. gl_InstanceID always counts from 0
+// (ES 3.0 has no base instance).
+import { render, onFrame, createSignal } from "@solidrt/core"
+import { createBuffer, createPipelineTexture, glsl, setDraw } from "@solidrt/core/gpu"
+
+let MAX_PETALS = 324
+
+let VERTEX = glsl`
+  in vec2 aPos;
+  out vec3 vTint;
+  uniform float uTime;
+
+  void main() {
+    // One instance = one petal: radius grows with sqrt(index) and the angle
+    // steps by the golden angle (~2.39996 rad) - the sunflower layout.
+    float i = float(gl_InstanceID);
+    float angle = i * 2.39996 + uTime * 0.3;
+    float radius = 0.045 * sqrt(i);
+    // Petals shrink toward the rim and point outward along the spiral.
+    float scale = mix(0.05, 0.016, sqrt(i) / 18.0);
+    float c = cos(angle), s = sin(angle);
+    vec2 p = radius * vec2(c, s) + mat2(c, s, -s, c) * (aPos * scale);
+    gl_Position = vec4(p, 0.0, 1.0);
+    vTint = 0.5 + 0.5 * cos(6.2832 * (i / 96.0) + vec3(0.0, 2.1, 4.2));
+  }
+`
+
+let FRAGMENT = glsl`
+  in vec3 vTint;
+
+  void main() {
+    fragColor = vec4(vTint, 1.0);
+  }
+`
+
+function App() {
+  // The whole mesh: one triangle, reused by every instance.
+  let bufferId = createBuffer(new Float32Array([0, 1.3, -1, -0.75, 1, -0.75]), { label: "petal-tri" })
+  let id = createPipelineTexture(VERTEX, FRAGMENT, 512, 512, { uTime: 0 }, {
+    label: "petals",
+    attributes: [{ name: "aPos", format: "vec2" }],
+    buffer: bufferId,
+    instanceCount: 1,
+    clearColor: [0.03, 0.03, 0.06, 1],
+  })
+  let [time, setTime] = createSignal(0)
+  onFrame((tick) => {
+    let t = tick / 1000
+    setTime(t)
+    setDraw(id, { instanceCount: Math.round(MAX_PETALS / 2 + (MAX_PETALS / 2 - 1) * Math.sin(t * 0.7)) })
+  })
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <texture src={id} params={{ uTime: time() }} width={420} height={420} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/gpu-particles.tsx

@@ -0,0 +1,96 @@
+// An additive particle field: createPipelineTexture 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, createPipelineTexture, glsl } from "@solidrt/core/gpu"
+
+let VERTEX = glsl`
+  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 = glsl`
+  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), { label: "particle-verts" })
+  let id = createPipelineTexture(VERTEX, FRAGMENT, 512, 512, { uTime: 0, uTintA: [1.0, 0.45, 0.15], uTintB: [0.25, 0.5, 1.0] }, {
+    label: "particles",
+    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-pipeline.tsx

@@ -1,43 +1,44 @@
-// createPipeline compiles a custom GLSL ES 3.00 vertex+fragment pair that draws
-// an interleaved vertex buffer into a texture, here a spinning cube with depth
-// testing. The vertex shader declares `in` attributes matching the pipeline's
-// attribute list (locations are resolved by name) and its own varyings; the
-// fragment preamble provides fragColor/iResolution/iTime but no vUV. Uniforms
-// are driven exactly like createShader: declaratively via the <texture> params
-// prop, applied at the next repaint.
+// createPipelineTexture compiles a custom GLSL ES 3.00 vertex+fragment pair
+// that draws an interleaved vertex buffer into a texture, here a spinning
+// cube with depth testing. The vertex shader declares `in` attributes
+// matching the pipeline's attribute list (locations are resolved by name)
+// and its own varyings; the fragment preamble provides fragColor/iResolution
+// but no vUV, and app-driven uniforms (uTime below) are the source's own
+// declarations. Uniforms are driven exactly like createShaderTexture:
+// declaratively via the <texture> params prop, applied at the next repaint.
 import { render, onFrame, createSignal } from "@solidrt/core"
-import { createBuffer, createPipeline } from "@solidrt/core/gpu"
+import { createBuffer, createPipelineTexture, glsl } from "@solidrt/core/gpu"
 
-let VERTEX = `
-in vec3 aPos;
-in vec3 aColor;
-out vec3 vColor;
-uniform float uTime;
+let VERTEX = glsl`
+  in vec3 aPos;
+  in vec3 aColor;
+  out vec3 vColor;
+  uniform float uTime;
 
-void main() {
-  float cy = cos(uTime), sy = sin(uTime);
-  float cx = cos(uTime * 0.7), sx = sin(uTime * 0.7);
-  mat3 rotY = mat3(cy, 0.0, -sy, 0.0, 1.0, 0.0, sy, 0.0, cy);
-  mat3 rotX = mat3(1.0, 0.0, 0.0, 0.0, cx, sx, 0.0, -sx, cx);
-  vec3 p = rotX * (rotY * aPos);
-  p.z += 2.5;
+  void main() {
+    float cy = cos(uTime), sy = sin(uTime);
+    float cx = cos(uTime * 0.7), sx = sin(uTime * 0.7);
+    mat3 rotY = mat3(cy, 0.0, -sy, 0.0, 1.0, 0.0, sy, 0.0, cy);
+    mat3 rotX = mat3(1.0, 0.0, 0.0, 0.0, cx, sx, 0.0, -sx, cx);
+    vec3 p = rotX * (rotY * aPos);
+    p.z += 2.5;
 
-  // Perspective projection (near 1, far 10). Clip y is negated: the target's
-  // memory row 0 is clip y = -1, and Impeller samples row 0 as the top, so
-  // camera-up needs the flip to be displayed up.
-  float f = 2.0;
-  float a = 11.0 / 9.0;
-  float b = -20.0 / 9.0;
-  gl_Position = vec4(p.x * f, -p.y * f, p.z * a + b, p.z);
-  vColor = aColor;
-}
+    // Perspective projection (near 1, far 10). Clip y is negated: the target's
+    // memory row 0 is clip y = -1, and Impeller samples row 0 as the top, so
+    // camera-up needs the flip to be displayed up.
+    float f = 2.0;
+    float a = 11.0 / 9.0;
+    float b = -20.0 / 9.0;
+    gl_Position = vec4(p.x * f, -p.y * f, p.z * a + b, p.z);
+    vColor = aColor;
+  }
 `
 
-let FRAGMENT = `
-in vec3 vColor;
-void main() {
-  fragColor = vec4(vColor, 1.0);
-}
+let FRAGMENT = glsl`
+  in vec3 vColor;
+  void main() {
+    fragColor = vec4(vColor, 1.0);
+  }
 `
 
 // Interleaved [pos vec3, color vec3], 6 faces x 2 triangles, one color per face.
@@ -58,9 +59,11 @@ function cube(): Float32Array {
 }
 
 function App() {
-  let bufferId = createBuffer(cube())
-  let id = createPipeline(VERTEX, FRAGMENT, 512, 512, {
-    params: { uTime: 0 },
+  // Labels name the buffer and target in the dev tooling's GPU inventory
+  // (and in engine log messages) - free-form, purely diagnostic.
+  let bufferId = createBuffer(cube(), { label: "cube-verts" })
+  let id = createPipelineTexture(VERTEX, FRAGMENT, 512, 512, { uTime: 0 }, {
+    label: "cube",
     attributes: [
       { name: "aPos", format: "vec3" },
       { name: "aColor", format: "vec3" },

package/examples/gpu-raw-program.tsx

@@ -0,0 +1,95 @@
+// 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, createRenderPipeline pairs the program with draw state
+// (none here: attributeless triangles are the defaults), and
+// createShaderTarget builds a render target over the pipeline. One program
+// can back many pipelines, one pipeline many targets, and only the compile
+// step compiles, 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 createShaderTexture does all of this in
+// one call with an injected preamble.
+import { render, onFrame, createSignal } from "@solidrt/core"
+import {
+  compileShader,
+  createRenderPipeline,
+  createShaderTarget,
+  destroyShader,
+  glsl,
+  linkProgram,
+} from "@solidrt/core/gpu"
+
+let VERTEX = glsl`#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 = glsl`#version 300 es
+  precision highp float;
+  in vec2 vUV;
+  out vec4 fragColor;
+  uniform float uTime;
+  void main() {
+    float t = uTime * 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 and fragColor, so this source only adds its own inputs -
+// including the app-driven time uniform.
+let RINGS = glsl`
+  in vec2 vUV;
+  uniform float uTime;
+  void main() {
+    float d = length(vUV - 0.5);
+    float r = 0.5 + 0.5 * sin(d * 40.0 - uTime * 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 })
+  // Labels name each object in the dev tooling's GPU inventory, which is
+  // what keeps a chain of programs, pipelines, and targets readable. They
+  // are free-form and need not be unique - one name per chain works, since
+  // the inventory already groups by kind.
+  let waves = linkProgram(vs, wavesFs, { label: "waves" })
+  let rings = linkProgram(vs, ringsFs, { label: "rings" })
+  destroyShader(vs)
+  destroyShader(wavesFs)
+  destroyShader(ringsFs)
+
+  let wavesPipeline = createRenderPipeline(waves, { label: "waves" })
+  let ringsPipeline = createRenderPipeline(rings, { label: "rings" })
+
+  let wavesId = createShaderTarget(wavesPipeline, 512, 512, { uTime: 0 }, { vertexCount: 3, label: "waves" })
+  let ringsId = createShaderTarget(ringsPipeline, 512, 512, { uTime: 0 }, { vertexCount: 3, label: "rings" })
+
+  let [time, setTime] = createSignal(0)
+  onFrame(tick => setTime(tick / 1000))
+
+  return (
+    <window flexDirection="row" gap={16} alignItems="center" justifyContent="center">
+      <texture src={wavesId} params={{ uTime: time() }} width={360} height={360} />
+      <texture src={ringsId} params={{ uTime: time() }} width={360} height={360} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/gpu-shader.tsx

@@ -1,38 +1,80 @@
-// 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.
+// createShaderTexture 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 name says what comes back). The texture is freed automatically when
+// the reactive owner is disposed.
 //
-// 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.
+// 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, 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.
+//
+// The preamble declares exactly what the runtime provides; anything the app
+// drives is the shader's own declaration in both dialects - `uniform float
+// uTime;` below - fed declaratively via the <texture> element's params prop.
+// A param applies at the next repaint, so a signal updated every frame stays
+// paced to actual frames. 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"
+import { createShaderTexture, glsl } from "@solidrt/core/gpu"
 
-let FRAGMENT = `
-void main() {
-  vec2 uv = vUV;
-  float t = iTime * 2.0;
-  float a = 0.5 + 0.5 * sin(uv.x * 10.0 + t);
-  float b = 0.5 + 0.5 * sin(uv.y * 10.0 - t * 1.3);
-  float c = 0.5 + 0.5 * sin((uv.x + uv.y) * 8.0 + t * 0.7);
-  fragColor = vec4(a, b, c, 1.0);
-}
+// Injected-preamble dialect: no #version, no main() plumbing; uniforms the
+// app drives are declared here, like any other.
+let FRAGMENT = glsl`
+  uniform float uTime;
+  void main() {
+    vec2 uv = vUV;
+    float t = uTime * 2.0;
+    float a = 0.5 + 0.5 * sin(uv.x * 10.0 + t);
+    float b = 0.5 + 0.5 * sin(uv.y * 10.0 - t * 1.3);
+    float c = 0.5 + 0.5 * sin((uv.x + uv.y) * 8.0 + t * 0.7);
+    fragColor = vec4(a, b, c, 1.0);
+  }
+`
+
+// Complete-source dialect: declares its own version, precision, varying and
+// output, and calls its time uniform uSpin. uTint is a typed (vec3) uniform,
+// filled from a 3-number array param.
+let RAW_FRAGMENT = glsl`#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 })
+  // The label names the target in the dev tooling's GPU inventory and in
+  // engine log messages - free-form, purely diagnostic, worth the habit.
+  let id = createShaderTexture(FRAGMENT, 512, 512, { uTime: 0 }, { label: "waves" })
+  let rawId = createShaderTexture(RAW_FRAGMENT, 512, 512, { uSpin: 0, uTint: [0.9, 0.4, 0.6] }, { label: "spiral" })
   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={{ uTime: 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,79 @@
+// 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 { createShaderTexture, glsl } 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 = glsl`
+  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 = glsl`
+  uniform float uTime;
+  void main() {
+    vec2 uv = vUV;
+    float r = length(uv - 0.5);
+    float radius = 0.28 + 0.04 * sin(uTime * 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 = createShaderTexture(BASE, SIZE, SIZE, null, { label: "base" })
+  let glowId = createShaderTexture(GLOW, SIZE, SIZE, { uTime: 0 }, { label: "glow" })
+  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={{ uTime: time() }}
+        />
+      </view>
+      <text fontSize={14} color="#888">blendMode "{mode()}" - click to toggle</text>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/inline-image.tsx

@@ -15,7 +15,7 @@ import bytes from "./logo.png" with { type: "binary" }
 
 function App() {
   let { data, width, height } = decodeImage(bytes)
-  let id = createTexture(data, width, height)
+  let id = createTexture(data, width, height, { label: "logo" })
 
   return (
     <window alignItems="center" justifyContent="center">