@solidrt/core 0.0.44 → 0.0.45

package/examples/README.md

@@ -8,6 +8,7 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 ## Host elements and layout
 - `window-root.tsx` - the minimal app; the root must be `<window>`.
 - `view-layout.tsx` - `<view>` as a flex container; containers do not paint.
+- `view-viewbox.tsx` - `viewBox` on a `<view>`: author a scene once in fixed design units and let the view uniformly scale-and-center (letterbox) that space into its box. A pure fit transform - it never sizes the element (layout still does); children live in design space (the box they inherit IS the design size, so a bare `d-rect` fills it); pointer `localX`/`localY` arrive in design units. The fixed-aspect alternative to `windowSizeClass` reflow for diagrams, slides, dashboards, game boards.
 - `background-rect.tsx` - a `d-rect` filling its parent as a background.
 - `detached-positioning.tsx` - the `d-` prefix: x/y placement, no reflow, detached-only children.
 - `text-paint-styling.tsx` - the uniform `color` prop; `drawStyle="stroke"` vs fill.
@@ -27,7 +28,7 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 
 ## Window state
 - `window-signals.tsx` - reactive `windowSize()` / `safeArea()` accessors (prefer over `onResize`).
-- `responsive-grid.tsx` - one app across phone/tablet/desktop: `capabilities.windowSizeClass` (Material 3 breakpoints, a reactive getter) drives the column count and `windowSize()` sizes each card; reflows on resize.
+- `responsive-grid.tsx` - one app across phone/tablet/desktop: `capabilities.windowSizeClass` (Material 3 breakpoints, a reactive getter) drives the column count and `windowSize()` sizes each card; reflows on resize. The reflow answer; for fixed-aspect content use `view-viewbox.tsx` instead.
 
 ## Overlays
 - `portal.tsx` - `createPortal` relocating content to the window root to escape clipping.

package/examples/gpu-draw-list.tsx

@@ -0,0 +1,110 @@
+// A draw target: one render target holding an ordered, mutable LIST of
+// draws - two orbiting triangles from two different programs sharing one
+// depth buffer (they occlude each other correctly as they cross), plus a
+// third entry added and removed on a timer. One render of the target is one
+// GPU pass no matter how many entries it holds, and per-entry params
+// (setDrawParams) are the per-object channel: each triangle carries its own
+// angle uniform, the model-matrix pattern at toy scale.
+//
+// The depth split to notice: the TARGET owns the storage (depth: true on
+// createDrawTarget - what makes cross-entry occlusion work), each PIPELINE
+// owns the behavior (depth: true on createRenderPipeline - this draw tests
+// and writes). A depth-testing pipeline added to a depthless draw target
+// throws at addDraw.
+import { render, onFrame } from "@solidrt/core"
+import {
+  addDraw,
+  compileShader,
+  createBuffer,
+  createDrawTarget,
+  createRenderPipeline,
+  glsl,
+  linkProgram,
+  removeDraw,
+  setDrawParams,
+} from "@solidrt/core/gpu"
+import type { DrawId } from "@solidrt/core/gpu"
+
+let VERTEX = glsl`
+  in vec2 aPos;
+  uniform float uAngle;
+
+  void main() {
+    // Orbit in x, swing through depth in z: the two entries cross each
+    // other, and the shared depth buffer decides who is in front.
+    float c = cos(uAngle), s = sin(uAngle);
+    vec2 p = aPos * 0.55 + vec2(0.55 * c, 0.0);
+    gl_Position = vec4(p, 0.5 * s, 1.0);
+  }
+`
+
+let FRAGMENT_WARM = glsl`
+  void main() {
+    fragColor = vec4(0.95, 0.45, 0.2, 1.0);
+  }
+`
+
+let FRAGMENT_COOL = glsl`
+  void main() {
+    fragColor = vec4(0.25, 0.55, 0.95, 1.0);
+  }
+`
+
+let FRAGMENT_PULSE = glsl`
+  uniform float uPhase;
+  void main() {
+    fragColor = vec4(vec3(0.6 + 0.4 * sin(uPhase)), 1.0);
+  }
+`
+
+function App() {
+  let triangle = createBuffer(new Float32Array([0, 0.6, -0.5, -0.4, 0.5, -0.4]), { label: "tri" })
+  let vs = compileShader("vertex", VERTEX, { header: true })
+  let attrs = [{ name: "aPos", format: "vec2" as const }]
+  let warm = createRenderPipeline(linkProgram(vs, compileShader("fragment", FRAGMENT_WARM, { header: true })), {
+    attributes: attrs,
+    depth: true,
+  })
+  let cool = createRenderPipeline(linkProgram(vs, compileShader("fragment", FRAGMENT_COOL, { header: true })), {
+    attributes: attrs,
+    depth: true,
+  })
+  let pulse = createRenderPipeline(linkProgram(vs, compileShader("fragment", FRAGMENT_PULSE, { header: true })), {
+    attributes: attrs,
+  })
+
+  let target = createDrawTarget(512, 512, { depth: true, clearColor: [0.04, 0.04, 0.08, 1], label: "orbits" })
+  let warmDraw = addDraw(target, warm, { uAngle: 0 }, { buffer: triangle })
+  let coolDraw = addDraw(target, cool, { uAngle: Math.PI }, { buffer: triangle })
+
+  // A third entry blinks in and out every second: add/remove are ordinary
+  // per-frame-affordable writes, and a removed DrawId simply retires. Its
+  // pipeline declares no depth, so it neither tests nor writes: list order
+  // alone places it, and inserting it BEFORE the warm triangle
+  // (before: warmDraw) keeps the flash beneath both orbits - appended
+  // instead, it would cover them. setDrawOrder is the wholesale form when a
+  // scene sorts its whole list.
+  let pulseDraw: DrawId | null = null
+  onFrame((tick) => {
+    let t = tick / 1000
+    setDrawParams(target, warmDraw, { uAngle: t })
+    setDrawParams(target, coolDraw, { uAngle: t + Math.PI })
+    let wantPulse = Math.floor(t) % 2 === 0
+    if (wantPulse && pulseDraw === null) {
+      pulseDraw = addDraw(target, pulse, { uAngle: t * 0.3, uPhase: t * 5 }, { buffer: triangle, before: warmDraw })
+    } else if (!wantPulse && pulseDraw !== null) {
+      removeDraw(target, pulseDraw)
+      pulseDraw = null
+    } else if (pulseDraw !== null) {
+      setDrawParams(target, pulseDraw, { uAngle: t * 0.3, uPhase: t * 5 })
+    }
+  })
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <texture src={target} width={420} height={420} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/gpu-instancing.tsx

@@ -1,15 +1,18 @@
-// 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.
+// Instanced drawing with per-instance attributes: one 3-vertex triangle in
+// the vertex buffer, drawn hundreds of times, each copy reading its own
+// record from an instance buffer (instanceAttributes on the pipeline +
+// instanceBuffer on the target, vertex divisor 1 underneath). Here each
+// record is one petal of a phyllotaxis spiral - its angle, radius, size, and
+// tint, computed once in JS - so the vertex stage just reads state instead
+// of re-deriving it from gl_InstanceID every frame, and 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).
+// vertexCount keep their values (the whole buffer). With an instance buffer
+// bound, an omitted instanceCount would default to one instance per record
+// (the whole population); the explicit 1 here starts the bloom closed, and
+// the count is bounds-checked against the records either way.
 import { render, onFrame, createSignal } from "@solidrt/core"
 import { createBuffer, createPipelineTexture, glsl, setDraw } from "@solidrt/core/gpu"
 
@@ -17,21 +20,20 @@ let MAX_PETALS = 324
 
 let VERTEX = glsl`
   in vec2 aPos;
+  in float iAngle;
+  in float iRadius;
+  in float iScale;
+  in vec3 iTint;
   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);
+    // The record places the petal; time only spins the whole flower.
+    float angle = iAngle + uTime * 0.3;
     float c = cos(angle), s = sin(angle);
-    vec2 p = radius * vec2(c, s) + mat2(c, s, -s, c) * (aPos * scale);
+    vec2 p = iRadius * vec2(c, s) + mat2(c, s, -s, c) * (aPos * iScale);
     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));
+    vTint = iTint;
   }
 `
 
@@ -43,13 +45,40 @@ let FRAGMENT = glsl`
   }
 `
 
+// One record per petal (matching instanceAttributes: 6 floats): radius grows
+// with sqrt(index), the angle steps by the golden angle (~2.39996 rad) - the
+// sunflower layout - petals shrink toward the rim, and the tint walks a
+// cosine palette.
+function petalRecords() {
+  let records = new Float32Array(MAX_PETALS * 6)
+  for (let i = 0; i < MAX_PETALS; i++) {
+    let at = i * 6
+    let t = Math.sqrt(i) / 18
+    records[at] = i * 2.39996
+    records[at + 1] = 0.045 * Math.sqrt(i)
+    records[at + 2] = 0.05 * (1 - t) + 0.016 * t
+    for (let k = 0; k < 3; k++) {
+      records[at + 3 + k] = 0.5 + 0.5 * Math.cos(6.2832 * (i / 96) + k * 2.1)
+    }
+  }
+  return records
+}
+
 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 instanceId = createBuffer(petalRecords(), { label: "petal-records" })
   let id = createPipelineTexture(VERTEX, FRAGMENT, 512, 512, { uTime: 0 }, {
     label: "petals",
     attributes: [{ name: "aPos", format: "vec2" }],
     buffer: bufferId,
+    instanceAttributes: [
+      { name: "iAngle", format: "f32" },
+      { name: "iRadius", format: "f32" },
+      { name: "iScale", format: "f32" },
+      { name: "iTint", format: "vec3" },
+    ],
+    instanceBuffer: instanceId,
     instanceCount: 1,
     clearColor: [0.03, 0.03, 0.06, 1],
   })

package/examples/gpu-pipeline.tsx

@@ -6,7 +6,11 @@
 // 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"
+// The cube draws indexed (indexBuffer + indexFormat: 24 shared vertices
+// stitched by 36 uint16 indices instead of 36 unshared vertices) with its
+// back faces culled (cull: "back") - a closed mesh never shows them, so
+// rastering them is pure waste.
+import { render, onFrame, createSignal, pct } from "@solidrt/core"
 import { createBuffer, createPipelineTexture, glsl } from "@solidrt/core/gpu"
 
 let VERTEX = glsl`
@@ -21,15 +25,19 @@ let VERTEX = glsl`
     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;
+    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.
+    // Standard right-handed camera at the origin looking down -z, perspective
+    // 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. With this textbook rig the CCW-outward mesh
+    // winds counter-clockwise AS DISPLAYED on its camera-facing faces -
+    // exactly the front-face rule cull: "back" tests against.
+    float w = -p.z;
     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);
+    gl_Position = vec4(p.x * f, -p.y * f, w * a + b, w);
     vColor = aColor;
   }
 `
@@ -41,12 +49,16 @@ let FRAGMENT = glsl`
   }
 `
 
-// Interleaved [pos vec3, color vec3], 6 faces x 2 triangles, one color per face.
-function cube(): Float32Array {
+// Interleaved [pos vec3, color vec3]: 24 vertices, 4 per face with that
+// face's color - each corner stored once and stitched into 2 triangles by
+// the index buffer below, the sharing real meshes are made of. Every face
+// winds counter-clockwise seen from outside, so with the projection's y
+// negation the cube culls correctly with cull: "back".
+function cubeVertices(): Float32Array {
   type Vec3 = [number, number, number]
   let verts: number[] = []
   let quad = (a: Vec3, b: Vec3, c: Vec3, d: Vec3, color: Vec3) => {
-    for (let p of [a, b, c, a, c, d]) verts.push(p[0], p[1], p[2], color[0], color[1], color[2])
+    for (let p of [a, b, c, d]) verts.push(p[0], p[1], p[2], color[0], color[1], color[2])
   }
   let s = 0.5
   quad([-s, -s, s], [s, -s, s], [s, s, s], [-s, s, s], [0.9, 0.3, 0.3]) // front
@@ -58,26 +70,44 @@ function cube(): Float32Array {
   return new Float32Array(verts)
 }
 
+// Two triangles per face over its 4 shared vertices: 36 uint16 indices.
+function cubeIndices(): Uint16Array {
+  let indices: number[] = []
+  for (let face = 0; face < 6; face++) {
+    let v = face * 4
+    indices.push(v, v + 1, v + 2, v, v + 2, v + 3)
+  }
+  return new Uint16Array(indices)
+}
+
 function App() {
-  // Labels name the buffer and target in the dev tooling's GPU inventory
+  // Labels name the buffers 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 }, {
+  let bufferId = createBuffer(cubeVertices(), { label: "cube-verts" })
+  let indexId = createBuffer(cubeIndices(), { label: "cube-indices" })
+  let id = createPipelineTexture(VERTEX, FRAGMENT, 1024, 1024, { uTime: 0 }, {
     label: "cube",
     attributes: [
       { name: "aPos", format: "vec3" },
       { name: "aColor", format: "vec3" },
     ],
     buffer: bufferId,
+    indexBuffer: indexId,
+    indexFormat: "uint16",
     depth: true,
+    cull: "back",
     clearColor: [0.08, 0.08, 0.12, 1],
   })
   let [time, setTime] = createSignal(0)
   onFrame((tick) => setTime(tick / 1000))
 
+  // Fill the window: the viewBox fits and centers the square content into
+  // the full-window view, so the projection is never stretched.
   return (
-    <window alignItems="center" justifyContent="center">
-      <texture src={id} params={{ uTime: time() }} width={400} height={400} />
+    <window>
+      <view width={pct(100)} height={pct(100)} viewBox={[1024, 1024]}>
+        <texture src={id} params={{ uTime: time() }} width={1024} height={1024} />
+      </view>
     </window>
   )
 }

package/examples/responsive-grid.tsx

@@ -8,6 +8,11 @@
 // functions - read `capabilities.windowSizeClass` (no call). Reading it inside
 // JSX tracks, so the memo below re-runs on every resize. `windowSize()` IS a
 // function (call it) - we read its width to size each card exactly.
+//
+// This is the REFLOW answer, for layouts that genuinely rearrange across form
+// factors. For content with fixed internal geometry (diagrams, slides,
+// dashboards, game boards) do not branch on window size at all: author one
+// design space and let `viewBox` scale it to fit - see view-viewbox.tsx.
 import { render, capabilities, windowSize, createMemo, For } from "@solidrt/core"
 
 const GAP = 16

package/examples/view-shader-history.tsx

@@ -0,0 +1,85 @@
+// Source history on a boundary shader: previous: true retains the prior
+// rasterization of the subtree as uPrevious, rotated when the content
+// actually changes - not per frame. That makes it transition material: on
+// each content change uPrevious holds the old look and uSource the new, and
+// uMix sweeps a cross-dissolve between them. For a static panel uPrevious
+// equals uSource (the previous rasterization IS the same content), so
+// feedback/accumulation is not what this is for - that stays with manual
+// targets.
+//
+// Click the panel to cycle its colors: the old palette dissolves into the
+// new one instead of snapping.
+import { render, onFrame, createSignal } from "@solidrt/core"
+import { compileShader, destroyShader, glsl, linkProgram } from "@solidrt/core/gpu"
+
+let VERTEX = glsl`
+  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);
+  }
+`
+
+let DISSOLVE = glsl`
+  uniform sampler2D uSource;
+  uniform sampler2D uPrevious;
+  uniform float uMix;
+  in vec2 vUV;
+  void main() {
+    fragColor = mix(texture(uPrevious, vUV), texture(uSource, vUV), uMix);
+  }
+`
+
+const PALETTES = [
+  ["#0077ff", "#ff6a00", "#00c46a"],
+  ["#e63946", "#ffb703", "#8338ec"],
+  ["#00b4d8", "#ef476f", "#ffd166"],
+] as const
+
+function App() {
+  let vs = compileShader("vertex", VERTEX, { header: true })
+  let fs = compileShader("fragment", DISSOLVE, { header: true })
+  let dissolve = linkProgram(vs, fs, { label: "dissolve" })
+  destroyShader(vs)
+  destroyShader(fs)
+
+  let [palette, setPalette] = createSignal(0)
+  let colors = () => PALETTES[palette() % PALETTES.length]!
+  let [mixv, setMix] = createSignal(1)
+  // Sweep uMix back to 1 after each change (~250ms). At 1 the signal stops
+  // changing, so the pass stops re-running.
+  onFrame((_tick, _frame, rate) => setMix(m => Math.min(1, m + 4 / rate)))
+
+  let cycle = () => {
+    setPalette(p => (p + 1) % PALETTES.length)
+    setMix(0)
+  }
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <view
+        repaintBoundary="snapshot"
+        shader={{ program: dissolve, params: { uMix: mixv() }, previous: true }}
+        onPointerDown={cycle}
+        flexDirection="column"
+        gap={12}
+        alignItems="center"
+        justifyContent="center"
+        width={360}
+        height={240}
+      >
+        <rect position="absolute" width="100%" height="100%" radius={16} color="#dde3ec" />
+        <text fontSize={24} color="#222">Boundary history</text>
+        <view flexDirection="row" gap={12}>
+          <rect width={70} height={70} radius={12} color={colors()[0]} />
+          <rect width={70} height={70} radius={12} color={colors()[1]} />
+          <rect width={70} height={70} radius={12} color={colors()[2]} />
+        </view>
+        <text fontSize={13} color="#666">Click: colors cross-dissolve</text>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/view-shader.tsx

@@ -0,0 +1,81 @@
+// A boundary shader: a view with repaintBoundary="snapshot" runs its
+// rasterized subtree through a linked program and composites the result in
+// its place. The program contract matches shader targets, not the window
+// pass: uSource is the subtree's rasterization (top-left origin, so vUV
+// needs no flip), iResolution is the boundary in physical pixels. The pass
+// is split from content invalidation: animating params here re-runs only
+// the pass - the panel's content is rasterized once and stays cached.
+//
+// outset adds a transparent margin the effect may write into: without it the
+// wave clips at the layout box, with it the crests escape the box edge.
+//
+// Click the panel to toggle the warp between 0 and 1: at 0 the program is an
+// identity pass, which must be indistinguishable from the plain snapshot.
+import { render, onFrame, createSignal } from "@solidrt/core"
+import { compileShader, destroyShader, glsl, linkProgram } from "@solidrt/core/gpu"
+
+// { header: true } supplies #version and precision; the varyings are the
+// program's own. Unlike the window pass there is no flip here: a target
+// pass's vUV origin already matches the sampled texture's top-left.
+let VERTEX = glsl`
+  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);
+  }
+`
+
+let WARP = glsl`
+  uniform sampler2D uSource;
+  uniform float uAmount;
+  uniform float uTime;
+  in vec2 vUV;
+  void main() {
+    vec2 uv = vUV;
+    uv.x += sin(uv.y * 24.0 + uTime * 3.0) * 0.03 * uAmount;
+    uv.y += sin(uv.x * 18.0 - uTime * 2.0) * 0.03 * uAmount;
+    fragColor = texture(uSource, uv);
+  }
+`
+
+function App() {
+  let vs = compileShader("vertex", VERTEX, { header: true })
+  let fs = compileShader("fragment", WARP, { header: true })
+  let warp = linkProgram(vs, fs, { label: "panel-warp" })
+  destroyShader(vs)
+  destroyShader(fs)
+
+  let [time, setTime] = createSignal(0)
+  let [amount, setAmount] = createSignal(1)
+  onFrame(tick => setTime(tick / 1000))
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <view
+        repaintBoundary="snapshot"
+        shader={{ program: warp, params: { uTime: time(), uAmount: amount() }, outset: 16 }}
+        onPointerDown={() => setAmount(a => (a > 0 ? 0 : 1))}
+        flexDirection="column"
+        gap={12}
+        alignItems="center"
+        justifyContent="center"
+        width={360}
+        height={240}
+      >
+        {/* Fills the boundary, so the box edge is a content edge: the warp
+            visibly ripples it out into the outset margin. */}
+        <rect position="absolute" width="100%" height="100%" radius={16} color="#dde3ec" />
+        <text fontSize={24} color="#222">Boundary shader</text>
+        <view flexDirection="row" gap={12}>
+          <rect width={70} height={70} radius={12} color="#0077ff" />
+          <rect width={70} height={70} radius={12} color="#ff6a00" />
+          <rect width={70} height={70} radius={12} color="#00c46a" />
+        </view>
+        <text fontSize={13} color="#666">Click to toggle warp (identity at 0)</text>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/view-viewbox.tsx

@@ -0,0 +1,86 @@
+// `viewBox` on a <view> is the fixed-aspect answer to "many screen sizes": you
+// author the whole scene once, in your own made-up design units, and the view
+// scales that space to fit its box. It is SVG's viewBox generalized to any
+// subtree, not an SVG-only thing.
+//
+// Four facts, each demonstrated below:
+// 1. It NEVER sizes the element. `viewBox` is a pure fit transform; the box
+//    still takes its size from layout (here `flex={1}`). A view with only a
+//    viewBox and no layout size is zero-sized and paints nothing.
+// 2. It fits UNIFORMLY and centers - one scale for both axes, SVG's default
+//    preserveAspectRatio. Content never stretches; the leftover on the loose
+//    axis is letterbox, showing the window background through it.
+// 3. Children live in DESIGN space. Their x/y, w/h, fontSize, stroke widths -
+//    everything resolves against the design size, not the box. The box a child
+//    inherits IS the design size, so a bare `d-rect` fills the design space
+//    and detached text wraps at its width.
+// 4. Pointer coordinates arrive in design space too. localX/localY on the
+//    viewBox view (and on anything under it) read in design units, so no
+//    scale factor is threaded through the app's hit math.
+//
+// The payoff: no `windowSizeClass` branching, no per-breakpoint sizes, no
+// scale factor anywhere. The same code runs unchanged from a desktop window to
+// a phone. Reach for reflow (responsive-grid.tsx) only when the layout
+// genuinely rearranges across form factors; for content with fixed internal
+// geometry - diagrams, slides, dashboards, game boards, emulator screens - fit
+// one design space instead.
+//
+// Resize the window and watch: the scene keeps its aspect ratio, everything
+// including text scales together, and the readout reports the same design
+// coordinates for the same spot on the scene at any window size.
+import { render, createSignal, Show } from "@solidrt/core"
+
+// The design space. Every number below is in these units - invent whatever
+// suits the content and stay in it. 640x400 is 16:10.
+const DESIGN_W = 640
+const DESIGN_H = 400
+
+function App() {
+  let [at, setAt] = createSignal<{ x: number; y: number } | null>(null)
+  let round = (v: number) => Math.round(v)
+
+  return (
+    // The window background is what shows through the letterbox bars.
+    <window>
+      <d-rect color="#0b0f17" />
+
+      {/* flex={1} sizes the box; viewBox only maps content into it (fact 1). */}
+      <view
+        flex={1}
+        viewBox={[DESIGN_W, DESIGN_H]}
+        onPointerMove={(e) => setAt({ x: e.localX, y: e.localY })}
+        onPointerLeave={() => setAt(null)}
+      >
+        {/* No w/h, so it fills the box it inherits - which under a viewBox is
+            the design space (fact 3). Its edges are the letterbox edges. */}
+        <d-rect color="#151b28" />
+
+        {/* A scene at literal design coordinates. No breakpoints, no
+            windowSize() reads, no scale factor: authored once, at this size. */}
+        <d-rect x={40} y={40} w={240} h={140} radius={12} color="#1f6feb" />
+        <d-rect x={300} y={40} w={300} h={140} radius={12} color="#3fb950" />
+        <d-oval x={40} y={220} w={140} h={140} color="#a371f7" />
+        <d-line x1={200} y1={300} x2={600} y2={300} color="#e3b341" strokeWidth={6} />
+        <d-text x={64} y={95} fontSize={28} color="#e6e6e6">
+          fixed design space
+        </d-text>
+        <d-text x={324} y={95} fontSize={28} color="#0b0f17">
+          {DESIGN_W} x {DESIGN_H}
+        </d-text>
+
+        {/* Pointer position in design units (fact 4), drawn in design units.
+            Non-keyed Show keeps the marker node mounted across moves (a
+            ternary on at() would recreate it every event); the accessor
+            reads update its props fine-grained. */}
+        <d-text x={200} y={330} fontSize={22} color="#8b949e">
+          {at() ? `design x ${round(at()!.x)}, y ${round(at()!.y)}` : "move the pointer over the scene"}
+        </d-text>
+        <Show when={at()}>
+          {(a) => <d-oval x={a().x - 8} y={a().y - 8} w={16} h={16} color="#f85149" />}
+        </Show>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

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

package/src/gpu.ts

@@ -71,7 +71,7 @@ export type { TextureFormat } from "flux:gpu"
 // runtime, distinct types to the checker, so a cross-space slip like
 // destroyBuffer(textureId) fails to compile. Exported so apps can annotate
 // storage (`let ids: TextureId[]`).
-export type { BufferId, ProgramId, RenderPipelineId, ShaderStageId, TextureId } from "flux:gpu"
+export type { BufferId, DrawId, ProgramId, RenderPipelineId, ShaderStageId, TextureId } 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
@@ -108,7 +108,20 @@ export {
 // GPU-side (exact, same size): seed a loadOp "load" accumulator, snapshot a
 // ping-pong buffer, reset state to a known image.
 export { copyTexture, destroyBuffer, renderTarget, setDraw } from "flux:gpu"
-export type { BlendMode, DrawRange, ShaderParams, Topology, VertexAttribute } from "flux:gpu"
+export type { BlendMode, CullMode, DrawRange, IndexBinding, IndexFormat, IndexRange, ShaderParams, Topology, VertexAttribute } from "flux:gpu"
+
+// The draw-list verbs, re-exported raw: entries live and die with their draw
+// target (see createDrawTarget below), so there is no per-entry lifetime to
+// wrap. addDraw adds an entry (appended, or inserted via opts.before) and
+// returns its stable DrawId; removeDraw drops one; setDrawParams /
+// setDrawTextures / setDrawRange are the per-entry forms of setShaderParams /
+// setShaderTextures / setDraw, taking (target, draw, value) with identical
+// merge and validation semantics. The per-object hot path is setDrawParams (a
+// moved mesh = one call with its new matrix). setDrawOrder replaces the whole
+// list order with a full permutation of the live ids - the sorting verb
+// (opaque front-to-back, transparent back-to-front, re-issued when the
+// camera moves).
+export { addDraw, removeDraw, setDrawOrder, setDrawParams, setDrawRange, setDrawTextures } from "flux:gpu"
 
 // The device ceilings (max texture/target size, sampler inputs per pass,
 // vertex attributes per pipeline), queried once at startup. Creates and binds
@@ -269,15 +282,20 @@ export function createShaderTexture(
  * uniforms with `<texture params>` or `setShaderParams`). Many targets may
  * share one pipeline, and creating a target compiles nothing. The target
  * brings the per-target half: size, the concrete vertex `buffer` the
- * pipeline's attribute layout describes, the draw range (`vertexCount`
- * defaults to the rest of the buffer from `firstVertex` on, `instanceCount`
- * repeats it as instances told apart by `gl_InstanceID`; a fullscreen pass
- * over an attributeless pipeline is `{ vertexCount: 3 }` with a
- * covering-triangle vertex stage), uniforms, and
- * `clearColor`. Draw state (`attributes`, `topology`, `blend`, `depth`,
- * `depthWrite`) lives on the pipeline and throws here. Frees the target when
- * the reactive owner is disposed (opt out with `opts.manual`); the pipeline
- * is yours and outlives it.
+ * pipeline's attribute layout describes, the `instanceBuffer` its
+ * `instanceAttributes` describe (required exactly when it declares any),
+ * the draw range (`vertexCount` defaults to the rest of the buffer from
+ * `firstVertex` on, `instanceCount` repeats it as instances told apart by
+ * `gl_InstanceID` and defaults to one per instance-buffer record; a
+ * fullscreen pass over an attributeless pipeline is `{ vertexCount: 3 }`
+ * with a covering-triangle vertex stage), uniforms, and
+ * `clearColor`. An `indexBuffer` + `indexFormat` pair makes the draw indexed
+ * (shared vertices stored once), with the range in `firstIndex`/`indexCount`
+ * spelling - see IndexBinding/IndexRange. Draw state (`attributes`,
+ * `instanceAttributes`, `topology`, `blend`, `cull`, `depth`, `depthWrite`)
+ * lives on the pipeline
+ * and throws here. Frees the target when the reactive owner is disposed (opt
+ * out with `opts.manual`); the pipeline is yours and outlives it.
  *
  * `render: "manual"` makes it a manual target: the runtime never renders it
  * (it starts cleared to `clearColor`), only an explicit `renderTarget(id)`
@@ -297,10 +315,11 @@ export function createShaderTarget(
   opts?: {
     textures?: Record<string, gpu.TextureId>
     buffer?: gpu.BufferId
+    instanceBuffer?: gpu.BufferId
     clearColor?: [number, number, number, number]
     render?: "auto" | "manual"
     loadOp?: "clear" | "load"
-  } & gpu.DrawRange &
+  } & (gpu.DrawRange | (gpu.IndexBinding & gpu.IndexRange)) &
     CreateOptions &
     SamplerOptions,
 ): gpu.TextureId {
@@ -309,6 +328,42 @@ export function createShaderTarget(
   return id
 }
 
+/**
+ * Creates a draw target: a render target holding an ordered, MUTABLE list of
+ * draws, rendered as one pass - clear once (color, and depth when declared),
+ * then every entry in list order into the same storage. This is the
+ * multi-pass primitive (N meshes x N pipelines sharing one depth buffer -
+ * what every 3D API calls a render pass), retained: build the list with
+ * `addDraw`, prune it with `removeDraw`, and drive per-entry state with
+ * `setDrawParams` / `setDrawTextures` / `setDrawRange`. `depth: true` gives
+ * the target the depth storage all entries share (cross-entry occlusion);
+ * whether an entry tests/writes it stays pipeline state, and a depth-testing
+ * pipeline into a depthless target throws at `addDraw`.
+ *
+ * The render contract is unchanged: the list is input data, so an ordinary
+ * (`render: "auto"`) draw target re-renders exactly when its entries or
+ * their inputs change - a static scene costs zero passes, and one render is
+ * one pass regardless of entry count. `render: "manual"` and `loadOp` work
+ * as on `createShaderTarget`. Returns the texture id; frees on owner
+ * disposal (opt out with `opts.manual`), taking its entries with it - the
+ * entries' pipelines and buffers are yours and outlive it.
+ */
+export function createDrawTarget(
+  width: number,
+  height: number,
+  opts?: {
+    depth?: boolean
+    clearColor?: [number, number, number, number]
+    render?: "auto" | "manual"
+    loadOp?: "clear" | "load"
+  } & CreateOptions &
+    SamplerOptions,
+): gpu.TextureId {
+  let id = gpu.createDrawTarget(width, height, opts)
+  if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
+  return id
+}
+
 /** The reactive shader description `createShaderTextureMemo` 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. */
@@ -439,7 +494,14 @@ function toUint8(data: ArrayBuffer | ArrayBufferView): Uint8Array {
  * see DrawRange) defaults to the whole buffer drawn once and can be changed
  * later with `setDraw`; `instanceCount` is the standard answer to particles
  * and repeated meshes, N copies of the range told apart by `gl_InstanceID`
- * in the vertex stage. `opts.render: "manual"` and
+ * in the vertex stage. `opts.instanceAttributes` + `opts.instanceBuffer`
+ * (declare both or neither) give each instance its own interleaved record -
+ * real per-instance state instead of `gl_InstanceID` arithmetic - and
+ * `instanceCount` then defaults to one instance per record. An
+ * `indexBuffer` + `indexFormat` pair makes the draw
+ * indexed (shared vertices stored once), with the range in
+ * `firstIndex`/`indexCount` spelling; `opts.cull` discards one face set by
+ * winding (counter-clockwise as displayed = front). `opts.render: "manual"` and
  * `opts.loadOp` behave exactly as on {@link createShaderTarget}: step the
  * target with `renderTarget(id)`, and `loadOp: "load"` (manual-only) keeps
  * the previous contents under each draw. Frees the texture and GL program when the reactive
@@ -456,14 +518,17 @@ export function createPipelineTexture(
     textures?: Record<string, gpu.TextureId>
     attributes?: gpu.VertexAttribute[]
     buffer?: gpu.BufferId
+    instanceAttributes?: gpu.VertexAttribute[]
+    instanceBuffer?: gpu.BufferId
     topology?: gpu.Topology
     depth?: boolean
     depthWrite?: boolean
     blend?: gpu.BlendMode
+    cull?: gpu.CullMode
     clearColor?: [number, number, number, number]
     render?: "auto" | "manual"
     loadOp?: "clear" | "load"
-  } & gpu.DrawRange &
+  } & (gpu.DrawRange | (gpu.IndexBinding & gpu.IndexRange)) &
     CreateOptions &
     SamplerOptions,
 ): gpu.TextureId {

package/src/types.d.ts

@@ -447,6 +447,67 @@ export interface ViewOwnProps extends TransformProps, PointerProps {
    * axis-aligned rects look identical, so prefer it for plain UI panels.
    */
   repaintBoundary?: boolean | "snapshot" | "snapshot-no-aa"
+  /**
+   * Run this view's rasterized subtree through a GPU program and composite
+   * the result in its place. Requires repaintBoundary="snapshot" (the cost
+   * is snapshot semantics, kept explicit; declared without it the shader is
+   * ignored with a warning). The pass is region-sized and split from content
+   * invalidation: a params-only change re-runs just the pass against the
+   * cached snapshot, so animating an effect over a static subtree never
+   * re-rasterizes it.
+   *
+   * The effect samples only the subtree's own pixels - grading, warping or
+   * dissolving the panel works; anything needing what is behind it does not.
+   * Sampling outside the content clamps to the edge, and the output is
+   * cropped to the layout box like any snapshot. Hit-testing stays on layout
+   * geometry: a distortion moves pixels, not hit targets. The view's own
+   * transform and opacity apply after the effect, so the program sees
+   * unrotated, opaque content.
+   */
+  shader?: ViewShaderProps | null
+}
+
+/**
+ * A boundary shader declaration. The program contract matches shader targets,
+ * not the window pass: the subtree's rasterization binds as
+ * `uniform sampler2D uSource` (top-left origin, like every sampled texture)
+ * and the pass draws the covering triangle attributeless. `iResolution`,
+ * filled by name, is the boundary in physical pixels.
+ */
+export interface ViewShaderProps {
+  /** Linked program handle from linkProgram. */
+  program: ProgramId
+  /**
+   * 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, TextureId>
+  /**
+   * Transparent margin in logical px on every side of the layout box, for
+   * the effect to write into - glow, drop shadow, blur that bleeds past the
+   * edge. Grows the rasterized canvas and the composited quad; the subtree's
+   * own paint stays clipped to the layout box either way. The pass sees only
+   * the bigger iResolution - declare an app uniform if the program needs the
+   * margin size. Default 0.
+   */
+  outset?: number
+  /**
+   * Retain the prior rasterization of the subtree as
+   * `uniform sampler2D uPrevious`. Source history, not output history: it
+   * rotates when the content actually re-rasterizes, not per frame - on a
+   * content change uPrevious holds exactly the old look (transition
+   * material: cross-dissolve old into new), while for a static subtree with
+   * animated params uPrevious equals uSource. Feedback/accumulation is not
+   * this; that stays with manual targets. Costs one extra canvas-sized
+   * texture while declared; transparent until the first rotation, and reset
+   * to transparent by a size or scale change. 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 ViewOwnProps, LayoutProps {}