@solidrt/core 0.0.45 → 0.0.46

package/AGENTS.md

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

package/examples/README.md

@@ -42,6 +42,8 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 - `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.
+- `gpu-draw-list.tsx` - `createDrawTarget`: one render target holding an ordered, mutable LIST of draws - two orbiting triangles from different programs sharing one depth buffer (the target owns the depth storage, each pipeline the test/write behavior), a third entry added and removed live via its stable `DrawId`, and `setDrawParams` as the per-object channel.
+- `gpu-shared-params.tsx` - shared target state on a draw target: `setTargetParams`/`setTargetTextures` write values every entry reads - a ring of quads spins and color-cycles from ONE write per frame, and the shared sampler source swaps for the whole target at once. The spin is imperative (`setTargetParams` in `onFrame`) while the tint rides the `<texture params>` prop - the declarative channel, which on a draw target writes the same shared record. The two entries that seeded their own uTint/uMap show the precedence rule (an entry's own value beats the shared one), and mixed programs show partial coverage (a program that does not declare a shared name skips it). `createDrawTarget`'s positional `params` and `opts.textures` seed both channels before any entry exists.
 - `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.
 

package/examples/gpu-draw-list.tsx

@@ -73,7 +73,7 @@ function App() {
     attributes: attrs,
   })
 
-  let target = createDrawTarget(512, 512, { depth: true, clearColor: [0.04, 0.04, 0.08, 1], label: "orbits" })
+  let target = createDrawTarget(512, 512, null, { 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 })
 

package/examples/gpu-shared-params.tsx

@@ -0,0 +1,135 @@
+// Shared target state on a draw target: values every entry reads, written
+// ONCE per target instead of once per entry. A ring of quads spins under a
+// single "camera" uniform (uView) and color-cycles under a shared tint
+// (uTint) - one target-level write per frame however many entries the
+// list holds, where per-entry setDrawParams would cost one call and one
+// value's worth of JS arithmetic per quad (the cost profile @solidrt/3d's
+// camera rides on). setTargetTextures is the sampler analog: the patterned
+// quads read one shared uMap source, swapped for the whole target every
+// two seconds.
+//
+// The rules to notice: an entry's OWN value beats the shared one - the
+// amber quad seeds uTint at addDraw and ignores the color cycle, the
+// striped quad binds its own uMap and ignores the swap - and coverage may
+// be partial: the tint program never declares uMap and the patterned
+// program never declares uTint, so each shared write simply skips entries
+// whose program does not declare the name. Shared state is target state:
+// createDrawTarget seeds it (positional params + opts.textures) before any
+// entry exists, and entry add/remove/rebuild cannot lose it.
+//
+// Two channels drive the same shared params. uView goes imperatively
+// (setTargetParams in onFrame), uTint goes declaratively: the `<texture
+// params>` prop means "the target's params" on every target kind, so on a
+// draw target it writes the shared record - a signal into the prop is all
+// the wiring a shared value needs.
+import { render, onFrame, createSignal } from "@solidrt/core"
+import {
+  addDraw,
+  compileShader,
+  createBuffer,
+  createDrawTarget,
+  createRenderPipeline,
+  createTexture,
+  glsl,
+  linkProgram,
+  setTargetParams,
+  setTargetTextures,
+} from "@solidrt/core/gpu"
+
+let VERTEX = glsl`
+  in vec2 aPos;
+  uniform float uView;
+  uniform vec2 uCenter;
+
+  void main() {
+    vec2 p = uCenter + aPos * 0.13;
+    float c = cos(uView), s = sin(uView);
+    gl_Position = vec4(c * p.x - s * p.y, s * p.x + c * p.y, 0.0, 1.0);
+  }
+`
+
+let FRAGMENT_TINT = glsl`
+  uniform vec4 uTint;
+  void main() {
+    fragColor = uTint;
+  }
+`
+
+let FRAGMENT_MAP = glsl`
+  uniform sampler2D uMap;
+  void main() {
+    fragColor = texture(uMap, gl_FragCoord.xy / 32.0);
+  }
+`
+
+function App() {
+  let quad = createBuffer(new Float32Array([-1, -1, 1, -1, 1, 1, -1, -1, 1, 1, -1, 1]), { label: "quad" })
+  let vs = compileShader("vertex", VERTEX, { header: true })
+  let attrs = [{ name: "aPos", format: "vec2" as const }]
+  let tint = createRenderPipeline(linkProgram(vs, compileShader("fragment", FRAGMENT_TINT, { header: true })), {
+    attributes: attrs,
+  })
+  let mapped = createRenderPipeline(linkProgram(vs, compileShader("fragment", FRAGMENT_MAP, { header: true })), {
+    attributes: attrs,
+  })
+
+  // 2x2 patterns, nearest + repeat, so gl_FragCoord tiling shows hard cells.
+  let pattern = (a: number[], b: number[]) =>
+    createTexture(new Uint8Array([...a, ...b, ...b, ...a]), 2, 2, { filter: "nearest", wrap: "repeat" })
+  let checker = pattern([15, 15, 20, 255], [235, 235, 235, 255])
+  let ember = pattern([250, 160, 30, 255], [45, 10, 60, 255])
+  let stripes = createTexture(new Uint8Array([220, 40, 60, 255, 245, 245, 245, 255]), 2, 1, {
+    filter: "nearest",
+    wrap: "repeat",
+  })
+
+  // The positional params argument and opts.textures seed the shared state
+  // before any entry exists; the entries added below pick it up.
+  let target = createDrawTarget(
+    512,
+    512,
+    { uView: 0, uTint: [0.3, 0.8, 0.9, 1] },
+    { textures: { uMap: checker }, clearColor: [0.05, 0.05, 0.09, 1], label: "shared-ring" },
+  )
+
+  const RING = 8
+  for (let i = 0; i < RING; i++) {
+    let a = (i / RING) * Math.PI * 2
+    let uCenter = [0.62 * Math.cos(a), 0.62 * Math.sin(a)]
+    if (i === 1 || i === 5) {
+      // Patterned entries read the shared uMap; the one at i === 5 brings
+      // its own binding and keeps its stripes through every shared swap.
+      addDraw(target, mapped, { uCenter }, i === 5 ? { buffer: quad, textures: { uMap: stripes } } : { buffer: quad })
+    } else if (i === 3) {
+      // The override quad: its own uTint beats the shared color cycle.
+      addDraw(target, tint, { uCenter, uTint: [1, 0.62, 0.1, 1] }, { buffer: quad })
+    } else {
+      addDraw(target, tint, { uCenter }, { buffer: quad })
+    }
+  }
+
+  let [sharedTint, setSharedTint] = createSignal([0.3, 0.8, 0.9, 1])
+  let mapFlip = -1
+  onFrame(tick => {
+    let t = tick / 1000
+    // The whole ring, one write: uView spins every entry. uTint takes the
+    // declarative channel instead - the signal feeds the params prop below.
+    setTargetParams(target, { uView: t * 0.5 })
+    setSharedTint([0.45 + 0.45 * Math.sin(t), 0.45 + 0.45 * Math.sin(t + 2.1), 0.45 + 0.45 * Math.sin(t + 4.2), 1])
+    // The shared sampler source swaps every two seconds; only the entry
+    // with its own uMap keeps its pattern.
+    let flip = Math.floor(t / 2) % 2
+    if (flip !== mapFlip) {
+      mapFlip = flip
+      setTargetTextures(target, { uMap: flip === 0 ? checker : ember })
+    }
+  })
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <texture src={target} width={420} height={420} params={{ uTint: sharedTint() }} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

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

package/src/gpu.ts

@@ -1,12 +1,14 @@
 // GPU textures and shaders, reactive (SolidJS) layer: the create* helpers free
 // their texture automatically when the reactive owner is disposed. Drive a
-// shader's uniforms declaratively with `<texture src={id} params={{...}} />`
+// target's uniforms declaratively with `<texture src={id} params={{...}} />`
 // (see TextureProps) - the preferred way, deferred to the next real repaint so
-// a fast-changing signal stays paced to actual frames. setShaderParams is the
-// imperative exception: reach for it only when there is no `<texture>` element
-// 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.
+// a fast-changing signal stays paced to actual frames; the prop means "the
+// target's params" on every kind (on a draw target, its shared params).
+// setTargetParams is the imperative exception: reach for it only when there
+// is no `<texture>` element to hold a params prop, e.g. a target that only
+// feeds another shader as a sampler2D input. The imperative primitives
+// (uploadTexture, setTargetParams, 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
@@ -45,15 +47,16 @@
 import { createEffect, createSignal, getOwner, onCleanup, untrack } from "@solidjs/signals"
 import * as gpu from "flux:gpu"
 
-// The create* helpers accept { manual: true } to opt out of the owner-scoped
-// auto-free, for resources whose lifetime is managed by hand (rebuilt on
-// signal changes inside a long-lived component, handed across owners, ...).
-// Without it, each rebuild would stack another onCleanup on the component
-// owner: a leak until unmount, then a double-free against manual destroys.
+// The create* helpers accept { autoFree: false } to opt out of the
+// owner-scoped auto-free, for resources whose lifetime is managed by hand
+// (rebuilt on signal changes inside a long-lived component, handed across
+// owners, ...). Without the opt-out, each rebuild would stack another
+// onCleanup on the component owner: a leak until unmount, then a double-free
+// against the by-hand destroys.
 // `label` is a free-form debug name (WebGPU's label): surfaced by the dev
 // tooling's GPU inventory and engine log messages, never interpreted, kept
 // across id-stable resizes.
-export type CreateOptions = { manual?: boolean; label?: string }
+export type CreateOptions = { autoFree?: boolean; label?: string }
 
 // Sampling options every texture-producing create* helper accepts, applied at
 // creation as a property of the texture id (there is no set-sampler-later).
@@ -77,19 +80,28 @@ export type { BufferId, DrawId, ProgramId, RenderPipelineId, ShaderStageId, Text
 // -- need not import flux directly: destroyTexture for the manual-cleanup path
 // (textures made outside a reactive scope, e.g. after an await, are not
 // auto-freed), uploadTexture to push new pixels into a mutable texture, and
-// setShaderParams as the non-reactive exception described above - prefer
-// `<texture params={...}>` when a `<texture>` element is already in the tree.
-// resizeTexture and setShaderSize resize in place at a stable id (so
-// `<texture src>` and sampler bindings stay valid); because the id survives,
-// the owner-scoped auto-free registered at creation keeps working and no
-// re-registration is needed. setShaderTextures is the sampler analog of
-// setShaderParams: retarget a shader's sampler2D inputs without recompiling.
+// the target-level verbs. setTargetParams writes a target's params on ANY
+// target kind - the non-reactive exception described above, so prefer
+// `<texture params={...}>` when a `<texture>` element is already in the
+// tree. On a single-program target (fragment texture, pipeline target) the
+// names validate strictly against its one program; on a draw target they are
+// the SHARED params every entry reads (a camera's view-projection: one write
+// per camera move instead of one per mesh), applied before each entry's own
+// params so an entry naming the same uniform overrides the shared value, and
+// a name only some entries' programs declare applies where declared.
+// setTargetTextures is its sampler analog: retarget sampler2D inputs without
+// recompiling (on a draw target, shared sources every entry reads - an
+// environment map, a LUT - bound where an entry's program declares the name
+// and its own bindings do not override it). resizeTexture and setTargetSize
+// resize in place at a stable id (so `<texture src>` and sampler bindings
+// stay valid); because the id survives, the owner-scoped auto-free
+// registered at creation keeps working and no re-registration is needed.
 export {
   destroyTexture,
   resizeTexture,
-  setShaderParams,
-  setShaderSize,
-  setShaderTextures,
+  setTargetParams,
+  setTargetSize,
+  setTargetTextures,
   uploadTexture,
 } from "flux:gpu"
 
@@ -102,8 +114,7 @@ export {
 // the explicit render verb for `render: "manual"` targets - targets whose
 // pass is state (accumulation, feedback) rather than a pure function of its
 // inputs, which the runtime therefore never renders on its own; the app
-// steps them, usually from onFrame. (`render: "manual"` is the render mode;
-// the unrelated `manual: true` create option is the lifetime opt-out above.)
+// steps them, usually from onFrame.
 // copyTexture overwrites a manual target with another texture's pixels
 // GPU-side (exact, same size): seed a loadOp "load" accumulator, snapshot a
 // ping-pong buffer, reset state to a known image.
@@ -114,10 +125,12 @@ export type { BlendMode, CullMode, DrawRange, IndexBinding, IndexFormat, IndexRa
 // 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
+// setDrawTextures / setDrawRange are the per-entry forms of setTargetParams /
+// setTargetTextures / 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
+// moved mesh = one call with its new matrix); the per-target one is
+// setTargetParams (exported above), which on a draw target writes the SHARED
+// params every entry reads. 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).
@@ -194,8 +207,9 @@ export { captureSnapshot, readTexture } from "flux:gpu"
  * reactive scope the texture is freed automatically once that owner is
  * disposed; when called outside one (e.g. after an `await`, where the owner
  * is no longer current) nothing is registered and you must call
- * `destroyTexture` (from flux:gpu) yourself. Pass `{ manual: true }` to skip
- * the auto-free and own the disposal yourself even inside a reactive scope.
+ * `destroyTexture` (from flux:gpu) yourself. Pass `{ autoFree: false }` to
+ * skip the auto-free and own the disposal yourself even inside a reactive
+ * scope.
  */
 export function createTexture(
   data: Uint8Array,
@@ -204,7 +218,7 @@ export function createTexture(
   opts?: CreateOptions & SamplerOptions & TextureFormatOptions,
 ): gpu.TextureId {
   let id = gpu.createTexture(data, width, height, opts)
-  if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
 
@@ -214,7 +228,7 @@ export function createTexture(
  * `data` must hold at least `width * height` pixels at the declared format's
  * size (`* 4` bytes for the default "rgba8", `* 1` for "r8"; it may hold
  * several frames). Like `createTexture`, the texture is freed automatically
- * when the reactive owner is disposed (opt out with `{ manual: true }`);
+ * when the reactive owner is disposed (opt out with `{ autoFree: false }`);
  * created outside a reactive scope you must call `destroyTexture` (from
  * flux:gpu) yourself.
  */
@@ -225,7 +239,7 @@ export function createMutableTexture(
   opts?: CreateOptions & SamplerOptions & TextureFormatOptions,
 ): gpu.TextureId {
   let id = gpu.createMutableTexture(data, width, height, opts)
-  if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
 
@@ -238,7 +252,7 @@ export function createMutableTexture(
  * 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`. `params` is its own argument - it seeds the same
+ * with `setTargetParams`. `params` is its own argument - it seeds the same
  * live channel those two drive - and takes `null` (or nothing) for a shader
  * without uniforms. A time-driven shader declares its own time uniform
  * (`uniform float uTime;`) and the app drives it like any other value.
@@ -248,7 +262,7 @@ export function createMutableTexture(
  * 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
+ * with `{ autoFree: false }`); create outside any reactive scope for
  * app-lifetime shaders. For a shader whose source or inputs change
  * reactively, use {@link createShaderTextureMemo} instead.
  *
@@ -271,15 +285,15 @@ export function createShaderTexture(
   opts?: CreateOptions & SamplerOptions & { textures?: Record<string, gpu.TextureId> },
 ): gpu.TextureId {
   let id = gpu.createShaderTexture(fragmentSrc, width, height, params, opts)
-  if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
 
 /**
  * Creates a render target over a pipeline from `createRenderPipeline` and
  * renders it once, returning the texture id (usable anywhere a normal
- * texture id is, e.g. `<texture src>`; resize with `setShaderSize`, drive
- * uniforms with `<texture params>` or `setShaderParams`). Many targets may
+ * texture id is, e.g. `<texture src>`; resize with `setTargetSize`, drive
+ * uniforms with `<texture params>` or `setTargetParams`). 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 `instanceBuffer` its
@@ -295,7 +309,7 @@ export function createShaderTexture(
  * `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.
+ * out with `autoFree: false`); 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)`
@@ -304,8 +318,7 @@ export function createShaderTexture(
  * previous contents under each draw - single-target accumulation - while
  * the default `"clear"` clears to `clearColor` per render; state that must
  * read its own pixels (decay, blur, simulation) still ping-pongs across two
- * manual targets, and `copyTexture` seeds either shape. Distinct from the
- * `manual` lifetime option: `render` is who renders, `manual` is who frees.
+ * manual targets, and `copyTexture` seeds either shape.
  */
 export function createShaderTarget(
   pipeline: gpu.RenderPipelineId,
@@ -324,7 +337,7 @@ export function createShaderTarget(
     SamplerOptions,
 ): gpu.TextureId {
   let id = gpu.createShaderTarget(pipeline, width, height, params, opts)
-  if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
 
@@ -340,27 +353,41 @@ export function createShaderTarget(
  * whether an entry tests/writes it stays pipeline state, and a depth-testing
  * pipeline into a depthless target throws at `addDraw`.
  *
+ * `params` seeds the target's SHARED params - values every entry reads,
+ * written once per target instead of once per entry (a camera's
+ * view-projection is the motivating case: one `setTargetParams` per camera
+ * move instead of one `setDrawParams` per mesh). Shared values apply before
+ * each entry's own params, so an entry naming the same uniform overrides
+ * the shared value; a name only some entries' programs declare is applied
+ * where declared and skipped elsewhere. They are target state: entry
+ * add/remove/rebuild cannot lose them. `opts.textures` is the sampler
+ * analog - shared sources every entry reads (an environment map, a LUT),
+ * driven later with `setTargetTextures`, same precedence and coverage
+ * rules.
+ *
  * 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
+ * disposal (opt out with `autoFree: false`), taking its entries with it - the
  * entries' pipelines and buffers are yours and outlive it.
  */
 export function createDrawTarget(
   width: number,
   height: number,
+  params?: gpu.ShaderParams | null,
   opts?: {
     depth?: boolean
+    textures?: Record<string, gpu.TextureId>
     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))
+  let id = gpu.createDrawTarget(width, height, params, opts)
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
 
@@ -399,7 +426,7 @@ function sameRecord(
  * current texture id (use it as `<texture src={id()} />`) and keeps the GPU
  * resource in step with `spec` from then on. Changes that keep the compiled
  * program valid mutate in place at a stable id - a size change routes to
- * `setShaderSize`, a params change to `setShaderParams` - while a change to
+ * `setTargetSize`, a params change to `setTargetParams` - while a change to
  * the fragment source or the sampler bindings rebuilds at a fresh id, updates
  * the accessor, and destroys the old id. That destroy is frame-safe (the
  * runtime reclaims an id only once the render tree no longer references it),
@@ -436,10 +463,10 @@ export function createShaderTextureMemo(
       ) {
         // 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)
+          gpu.setTargetSize(currentId, next.width, next.height)
         }
         if (!sameRecord(next.params, current.params) && next.params) {
-          gpu.setShaderParams(currentId, next.params)
+          gpu.setTargetParams(currentId, next.params)
         }
         current = next
         return
@@ -483,7 +510,7 @@ function toUint8(data: ArrayBuffer | ArrayBufferView): Uint8Array {
  * reference `iResolution` 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.
+ * `setTargetParams`, exactly like a fragment shader.
  * `opts.depth` attaches a private depth buffer (cleared + tested per render);
  * `opts.depthWrite: false` (requires depth) keeps the test but stops the
  * draw from writing depth. `opts.blend: "add"` makes the draw accumulate
@@ -505,7 +532,7 @@ function toUint8(data: ArrayBuffer | ArrayBufferView): Uint8Array {
  * `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
- * owner is disposed (opt out with `opts.manual`); create outside any reactive
+ * owner is disposed (opt out with `autoFree: false`); create outside any reactive
  * scope for app-lifetime pipelines.
  */
 export function createPipelineTexture(
@@ -533,7 +560,7 @@ export function createPipelineTexture(
     SamplerOptions,
 ): gpu.TextureId {
   let id = gpu.createPipelineTexture(vertexSrc, fragmentSrc, width, height, params, opts)
-  if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
 
@@ -542,13 +569,13 @@ export function createPipelineTexture(
  * Float32Array laid out to match the pipeline's interleaved attribute list).
  * Update it later with {@link writeBuffer}; the buffer's byte size is fixed at
  * creation, so reserve room up front for dynamic geometry. Freed automatically
- * when the reactive owner is disposed (opt out with `{ manual: true }`);
+ * when the reactive owner is disposed (opt out with `{ autoFree: false }`);
  * created outside a reactive scope you must call `destroyBuffer` yourself.
  * (Destruction order relative to pipelines does not matter.)
  */
 export function createBuffer(data: ArrayBuffer | ArrayBufferView, opts?: CreateOptions): gpu.BufferId {
   let id = gpu.createBuffer(toUint8(data), opts)
-  if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyBuffer(id))
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => gpu.destroyBuffer(id))
   return id
 }
 

package/src/image.ts

@@ -1,27 +1,15 @@
-// CPU image codec plus the reactive load-and-upload convenience. decodeImage is
-// the raw primitive (no GPU involved); createImage is the owner-aware layer on
-// top that fetches/decodes/uploads for you and swaps the texture when the source
-// changes - the same relationship createTexture/createShaderTexture have to
-// flux:gpu.
+// CPU image codec plus the reactive load-and-upload convenience. The codec is
+// flux:image, re-exported here (like the flux:gpu re-exports in gpu.ts) so
+// applications import everything image-shaped from one place; createImage is
+// the owner-aware layer on top that fetches/decodes/uploads for you and swaps
+// the texture when the source changes.
 
 import { createMemo, onCleanup } from "@solidjs/signals"
+import { decodeImage, type DecodedImage } from "flux:image"
 import { createTexture, destroyTexture, type TextureId } from "./gpu"
 
-export type DecodedImage = {
-  data: Uint8Array
-  width: number
-  height: number
-}
-
-/**
- * Decodes encoded image bytes (PNG, JPEG, and the other formats the runtime's
- * image decoder supports) into raw, tightly-packed RGBA8 pixels plus the
- * decoded dimensions. Feed the result straight into `createTexture`. Use this
- * when you want manual control; for the common case reach for `createImage`.
- */
-export function decodeImage(bytes: Uint8Array): DecodedImage {
-  return image.decodeImage(bytes)
-}
+export { decodeImage, encodeImage } from "flux:image"
+export type { DecodedImage } from "flux:image"
 
 export type ImageSource = string | Uint8Array
 

package/src/index.ts

@@ -14,7 +14,7 @@ export { capabilities } from "./capabilities"
 export type { Capabilities, WindowSizeClass } from "./capabilities"
 export { createTexture } from "./gpu"
 export type { TextureId } from "./gpu"
-export { createImage, decodeImage } from "./image"
+export { createImage, decodeImage, encodeImage } from "./image"
 export type { DecodedImage, ImageSource } from "./image"
 export { parseSvg, svg } from "./svg"
 export type { SvgDocument, SvgDraw } from "./svg"

package/src/types.d.ts

@@ -23,10 +23,6 @@ declare global {
     readonly env: { readonly DEV: boolean }
   }
 
-  let image: {
-    decodeImage(bytes: Uint8Array): { data: Uint8Array, width: number, height: number }
-  }
-
   let speech: {
     start(options: {
       model: Uint8Array, vadModel: Uint8Array, lang?: string, microphone?: number,