@solidrt/core 0.0.44 → 0.0.46

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.46",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -27,11 +27,11 @@
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.44"
+    "@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).
@@ -71,25 +74,34 @@ 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
 // (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,13 +114,27 @@ 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.
 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 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); 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).
+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
@@ -181,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,
@@ -191,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
 }
 
@@ -201,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.
  */
@@ -212,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
 }
 
@@ -225,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.
@@ -235,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.
  *
@@ -258,26 +285,31 @@ 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 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 `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)`
@@ -286,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,
@@ -297,15 +328,66 @@ 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 {
   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
+}
+
+/**
+ * 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`.
+ *
+ * `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 `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, params, opts)
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
 
@@ -344,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),
@@ -381,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
@@ -428,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
@@ -439,11 +521,18 @@ 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
- * 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(
@@ -456,19 +545,22 @@ 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 {
   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
 }
 
@@ -477,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"