@solidrt/core 0.0.39 → 0.0.41

package/src/gpu.ts

@@ -7,6 +7,40 @@
 // to hold a params prop, e.g. a shader that only feeds another shader as a
 // sampler2D input. The imperative primitives (uploadTexture, setShaderParams,
 // destroyTexture, ...) live in the `flux:gpu` module.
+//
+// Sampling is a per-texture property declared at creation: `filter`
+// ("linear" default | "nearest") and `wrap` ("clamp" default | "repeat") on
+// every create* helper. One state for every consumer - `<texture>` display
+// and shader sampling both follow it - so a nearest texture upscales with
+// hard pixels everywhere (the retro/pixel-art path: render small, display
+// big). No mipmaps exist.
+//
+// Combining several passes is a render-tree job, not a shader one: stack
+// `<texture>` elements and set their `blendMode` (e.g. `blendMode="plus"` for
+// an additive pass over a base pass) instead of writing a pass that samples
+// both. WITHIN one pipeline draw, `blend: "add"` accumulates overlapping
+// geometry additively (order-independent, no sorting); anything else draws
+// with GL blending disabled and overwrites.
+//
+// The pixel contract. Three facts hold for every texture and target:
+//
+// - Clip space is y-down. `gl_Position` y = -1 is the top of the target, +1
+//   the bottom (GL's row 0 is clip y = -1, and Impeller samples row 0 as the
+//   top). A vertex stage carrying camera-up geometry must negate y, or fold
+//   the flip into its projection, or it draws upside down: Vulkan's
+//   convention, not desktop GL's. The fragment path absorbs the same flip
+//   already, so `vUV` is 0..1 with top-left origin and a fragment-only shader
+//   never sees it.
+// - Color is premultiplied alpha. A target's RGB is expected already
+//   multiplied by its A - `vec4(rgb * a, a)`, not `vec4(rgb, a)`, which
+//   composites as opaque. That is what Impeller composites and what
+//   `<texture blendMode>` blends; `clearColor` is premultiplied too, so the
+//   default transparent black needs no thought.
+// - Values are non-linear RGBA8, with no color-space concept. Every texture
+//   and target holds 8-bit RGBA UNORM exactly as written; nothing converts to
+//   or from linear light. `filter: "linear"` averages and `blend: "add"`
+//   accumulates non-linear values - the usual approximation, stated so
+//   shaders written today stay correct if a format vocabulary arrives.
 
 import { createEffect, createSignal, getOwner, onCleanup, untrack } from "@solidjs/signals"
 import * as gpu from "flux:gpu"
@@ -16,7 +50,21 @@ import * as gpu from "flux:gpu"
 // 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.
-export type CreateOptions = { manual?: boolean }
+// `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 }
+
+// Sampling options every texture-producing create* helper accepts, applied at
+// creation as a property of the texture id (there is no set-sampler-later).
+export type SamplerOptions = { filter?: gpu.FilterMode; wrap?: gpu.WrapMode }
+export type { FilterMode, WrapMode } from "flux:gpu"
+
+// The branded id types, one per id space (see flux:gpu): plain numbers at
+// 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"
 
 // Re-exported so callers that depend on @solidrt/core -- like @solidrt/components
 // -- need not import flux directly: destroyTexture for the manual-cleanup path
@@ -38,23 +86,70 @@ export {
   uploadTexture,
 } from "flux:gpu"
 
-// Pipeline plumbing re-exported raw: setDrawCount re-renders a pipeline after
-// its buffer gained or lost dynamic geometry; destroyBuffer is the manual
-// cleanup path for buffers created outside a reactive scope.
-export { destroyBuffer, setDrawCount } from "flux:gpu"
-export type { Topology, VertexAttribute } from "flux:gpu"
+// Pipeline plumbing re-exported raw: setDraw re-renders a pipeline with an
+// updated draw range (vertexCount after its buffer gained or lost dynamic
+// geometry, firstVertex for a different window of a shared buffer,
+// instanceCount for an instanced population; absent keys keep their current
+// value, like params); destroyBuffer is the manual
+// cleanup path for buffers created outside a reactive scope. renderTarget is
+// 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.)
+// 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"
+
+// The device ceilings (max texture/target size, sampler inputs per pass,
+// vertex attributes per pipeline), queried once at startup. Creates and binds
+// validate against them and throw naming the limit; read these to size within
+// the device instead (e.g. clamp a supersampled target to maxTextureSize).
+export { limits } from "flux:gpu"
 
 // The raw shading layer, re-exported as-is - no reactive wrapper, the app
 // owns these lifetimes. compileShader compiles one stage from complete GLSL
 // ES (or with the standard header via { header: true }); linkProgram links a
-// vertex and a fragment stage into a program handle that backs any number of
-// createShaderTarget calls (and compiles nothing per target); destroyShader /
-// destroyProgram free by id space, either order safe against live targets.
-// createShader/createPipeline remain the fused conveniences on top.
-export { compileShader, destroyProgram, destroyShader, linkProgram } from "flux:gpu"
+// vertex and a fragment stage into a program handle; createRenderPipeline
+// pairs a program with draw state (vertex layout, topology, blend, depth -
+// how it draws) into a pipeline handle that backs any number of
+// createShaderTarget calls (and compiles nothing per pipeline or target);
+// destroyShader / destroyProgram / destroyRenderPipeline free by id space,
+// any order safe against live users. createShaderTexture/createPipelineTexture
+// remain the fused conveniences on top.
+export {
+  compileShader,
+  createRenderPipeline,
+  destroyProgram,
+  destroyRenderPipeline,
+  destroyShader,
+  linkProgram,
+} from "flux:gpu"
+
+/**
+ * Tags an inline GLSL source, returning it unchanged. Shaders small enough to
+ * belong beside the code that uses them stay in the file; the tag is what makes
+ * them legible there, because editors highlight GLSL inside a template literal
+ * only when a known tag marks it (the name matters - `glsl` is the one the
+ * grammars look for).
+ *
+ * Interpolated values are stringified verbatim, with no GLSL-aware formatting:
+ * `${2}` splices in the int literal `2`, which will not assign to a float. Pass
+ * anything that varies as a uniform instead of building it into the source.
+ *
+ * Raw semantics, so backslashes reach the compiler as written: the GLSL
+ * preprocessor continues a line with a trailing `\`, which a cooked template
+ * would reject as an invalid escape and silently pass through as `undefined`.
+ */
+export let glsl = String.raw
 
 // captureSnapshot renders a node to a texture and readTexture reads any
-// texture's bytes back. Re-exported raw (no reactive auto-cleanup wrapper):
+// texture's bytes back. A laid-out node captures its layout box; a `d-*` node
+// captures its painted box - its own w/h when set, else the nearest laid-out
+// ancestor's box, its x/y offset mapped to the texture origin. Re-exported raw
+// (no reactive auto-cleanup wrapper):
 // captureSnapshot resolves asynchronously, by which point the reactive owner is
 // no longer current, so the caller owns the returned id and frees it with
 // destroyTexture (as with any texture created after an await).
@@ -81,8 +176,13 @@ export { captureSnapshot, readTexture } from "flux:gpu"
  * yourself. Pass `{ manual: true }` to skip the auto-free and own the
  * disposal yourself even inside a reactive scope.
  */
-export function createTexture(data: Uint8Array, width: number, height: number, opts?: CreateOptions): number {
-  let id = gpu.createTexture(data, width, height)
+export function createTexture(
+  data: Uint8Array,
+  width: number,
+  height: number,
+  opts?: CreateOptions & SamplerOptions,
+): gpu.TextureId {
+  let id = gpu.createTexture(data, width, height, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
@@ -96,8 +196,13 @@ export function createTexture(data: Uint8Array, width: number, height: number, o
  * outside a reactive scope you must call `destroyTexture` (from flux:gpu)
  * yourself.
  */
-export function createMutableTexture(data: Uint8Array, width: number, height: number, opts?: CreateOptions): number {
-  let id = gpu.createMutableTexture(data, width, height)
+export function createMutableTexture(
+  data: Uint8Array,
+  width: number,
+  height: number,
+  opts?: CreateOptions & SamplerOptions,
+): gpu.TextureId {
+  let id = gpu.createMutableTexture(data, width, height, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
@@ -105,78 +210,122 @@ export function createMutableTexture(data: Uint8Array, width: number, height: nu
 /**
  * Compiles a GLSL ES 3.00 fragment shader and renders it into a texture,
  * returning the texture id (usable anywhere a normal texture id is, e.g.
- * `<texture src>`). The fragment body may reference `vUV` (0..1, top-left
- * origin), `iResolution`, `iTime`, and any `uniform float` it declares; drive
- * their values with `<texture src={id} params={{...}} />` (preferred) or, when
- * there is no `<texture>` element for it, imperatively with `setShaderParams`.
- * `textures` binds each declared `uniform sampler2D` to an existing texture id
- * (e.g. a camera or decoded image) so the shader can read it; those inputs are
- * re-sampled on every params update, so live sources stay current. Frees the
+ * `<texture src>`) - hence the name: what comes back is a texture, not a
+ * shader object. The fragment body may reference `vUV` (0..1, top-left
+ * origin), `iResolution`, and any uniform it declares (`float`/`int`
+ * scalars from a number, `vec2`/`vec3`/`vec4`/`mat4` from a flat number
+ * array); drive their values with `<texture src={id} params={{...}} />`
+ * (preferred) or, when there is no `<texture>` element for it, imperatively
+ * with `setShaderParams`. `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.
+ * `opts.textures` binds each declared `uniform sampler2D` to an existing texture id
+ * (e.g. a camera or decoded image, or another shader/pipeline target) so the
+ * shader can read it; bound inputs are live dependencies, so the shader
+ * re-renders whenever a source changes - including a sampled target
+ * re-rendering, transitively through chains. Frees the
  * texture and shader program when the reactive owner is disposed (opt out
  * with `{ manual: true }`); create outside any reactive scope for
  * app-lifetime shaders. For a shader whose source or inputs change
- * reactively, use {@link createShaderMemo} instead.
+ * reactively, use {@link createShaderTextureMemo} instead.
+ *
+ * That preamble (`#version 300 es`, precision, `vUV`, `iResolution`,
+ * `fragColor`) is injected only into sources that do not declare their own
+ * `#version` line, and declares exactly what the runtime provides - nothing
+ * app-driven. A source starting with `#version 300 es` compiles exactly
+ * as written, so a shader carrying its own uniform names - one ported from
+ * elsewhere - runs unchanged here without dropping to compileShader /
+ * linkProgram. The built-in vertex stage still supplies `vUV`; declare
+ * `in vec2 vUV;` yourself to read it.
  */
-export function createShader(
+export function createShaderTexture(
   fragmentSrc: string,
   width: number,
   height: number,
-  params?: Record<string, number>,
-  textures?: Record<string, number>,
-  opts?: CreateOptions,
-): number {
-  let id = gpu.createShader(fragmentSrc, width, height, params, textures)
+  params?: gpu.ShaderParams | null,
+  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))
   return id
 }
 
 /**
- * Creates a render target over a program from `linkProgram` 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 share one
- * program, and creating a target compiles nothing. The mesh options mirror
- * `createPipeline`: a raw-linked program carries its own vertex stage, so a
- * fullscreen pass is `{ vertexCount: 3 }` over a covering-triangle vertex
- * stage. Frees the target when the reactive owner is disposed (opt out with
- * `opts.manual`); the program is yours and outlives it.
+ * 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
+ * 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.
+ *
+ * `render: "manual"` makes it a manual target: the runtime never renders it
+ * (it starts cleared to `clearColor`), only an explicit `renderTarget(id)`
+ * does, in call order - which is what legalizes feedback state stepped by
+ * the app. `loadOp: "load"` (manual-only, throws otherwise) keeps the
+ * 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.
  */
 export function createShaderTarget(
-  program: number,
+  pipeline: gpu.RenderPipelineId,
   width: number,
   height: number,
+  params?: gpu.ShaderParams | null,
   opts?: {
-    params?: Record<string, number>
-    textures?: Record<string, number>
-    attributes?: gpu.VertexAttribute[]
-    buffer?: number
-    topology?: gpu.Topology
-    vertexCount?: number
-    depth?: boolean
+    textures?: Record<string, gpu.TextureId>
+    buffer?: gpu.BufferId
     clearColor?: [number, number, number, number]
-  } & CreateOptions,
-): number {
-  let id = gpu.createShaderTarget(program, width, height, opts)
+    render?: "auto" | "manual"
+    loadOp?: "clear" | "load"
+  } & gpu.DrawRange &
+    CreateOptions &
+    SamplerOptions,
+): gpu.TextureId {
+  let id = gpu.createShaderTarget(pipeline, width, height, params, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
 
-/** The reactive shader description `createShaderMemo` builds from. */
+/** 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. */
 export type ShaderSpec = {
   fragmentSrc: string
   width: number
   height: number
-  params?: Record<string, number>
-  textures?: Record<string, number>
+  params?: gpu.ShaderParams
+  textures?: Record<string, gpu.TextureId>
+} & SamplerOptions
+
+// Shallow name->value equality for params/textures records; treats undefined
+// as the empty record. A param value may be a number or a flat number array
+// (typed uniforms), so arrays compare elementwise.
+function sameValue(a: number | number[] | undefined, b: number | number[] | undefined): boolean {
+  if (a === b) return true
+  if (!Array.isArray(a) || !Array.isArray(b)) return false
+  return a.length === b.length && a.every((v, i) => v === b[i])
 }
 
-// Shallow name->number equality for params/textures records; treats undefined
-// as the empty record.
-function sameRecord(a: Record<string, number> | undefined, b: Record<string, number> | undefined): boolean {
+function sameRecord(
+  a: Record<string, number | number[]> | undefined,
+  b: Record<string, number | number[]> | undefined,
+): boolean {
   if (a === b) return true
   let ka = a ? Object.keys(a) : []
   let kb = b ? Object.keys(b) : []
-  return ka.length === kb.length && ka.every(k => a![k] === b![k])
+  return ka.length === kb.length && ka.every(k => sameValue(a![k], b![k]))
 }
 
 /**
@@ -191,28 +340,57 @@ function sameRecord(a: Record<string, number> | undefined, b: Record<string, num
  * so the swap never paints a blank frame. The current id is freed when the
  * owning scope is disposed. Data textures need no analog: `uploadTexture` and
  * `resizeTexture` already cover their reactive changes id-stably.
+ *
+ * `onError` makes a failed rebuild survivable. Without it a shader that does
+ * not compile throws from inside the effect, where no caller can catch it;
+ * with it the error is handed to you and the last shader that DID compile
+ * stays current - id, size, params and accessor all unchanged - so the app
+ * keeps drawing the previous frame's shader instead of tearing down. That is
+ * the normal case whenever the source is not known-good: a shader editor, live
+ * coding, or a dialect ported from elsewhere. The initial compile is not
+ * covered: it throws at the call site, where an ordinary try/catch works and
+ * there is no previous shader to fall back to.
  */
-export function createShaderMemo(spec: () => ShaderSpec): () => number {
+export function createShaderTextureMemo(
+  spec: () => ShaderSpec,
+  opts?: { onError?: (error: unknown) => void },
+): () => gpu.TextureId {
+  let make = (s: ShaderSpec) =>
+    gpu.createShaderTexture(s.fragmentSrc, s.width, s.height, s.params, { textures: s.textures, filter: s.filter, wrap: s.wrap })
   let current = untrack(spec)
-  let currentId = gpu.createShader(current.fragmentSrc, current.width, current.height, current.params, current.textures)
+  let currentId = make(current)
   let [id, setId] = createSignal(currentId)
   createEffect(spec, next => {
-    if (next.fragmentSrc === current.fragmentSrc && sameRecord(next.textures, current.textures)) {
-      // Program and inputs unchanged: mutate in place, the id stays stable.
-      if (next.width !== current.width || next.height !== current.height) {
-        gpu.setShaderSize(currentId, next.width, next.height)
-      }
-      if (!sameRecord(next.params, current.params) && next.params) {
-        gpu.setShaderParams(currentId, next.params)
+    try {
+      if (
+        next.fragmentSrc === current.fragmentSrc &&
+        sameRecord(next.textures, current.textures) &&
+        next.filter === current.filter &&
+        next.wrap === current.wrap
+      ) {
+        // Program and inputs unchanged: mutate in place, the id stays stable.
+        if (next.width !== current.width || next.height !== current.height) {
+          gpu.setShaderSize(currentId, next.width, next.height)
+        }
+        if (!sameRecord(next.params, current.params) && next.params) {
+          gpu.setShaderParams(currentId, next.params)
+        }
+        current = next
+        return
       }
+      // Compile before touching any state: a throw here must leave `current`,
+      // `currentId` and the accessor all still pointing at the last shader
+      // that worked, which is what makes onError's keep-last-good real.
+      let rebuilt = make(next)
+      let old = currentId
       current = next
-      return
+      currentId = rebuilt
+      setId(rebuilt)
+      gpu.destroyTexture(old)
+    } catch (error) {
+      if (!opts?.onError) throw error
+      opts.onError(error)
     }
-    let old = currentId
-    current = next
-    currentId = gpu.createShader(next.fragmentSrc, next.width, next.height, next.params, next.textures)
-    setId(currentId)
-    gpu.destroyTexture(old)
   })
   if (getOwner()) onCleanup(() => gpu.destroyTexture(currentId))
   return id
@@ -229,35 +407,56 @@ function toUint8(data: ArrayBuffer | ArrayBufferView): Uint8Array {
 /**
  * Compiles a GLSL ES 3.00 vertex+fragment pipeline and renders it into a
  * texture, returning the texture id (usable anywhere a normal texture id is,
- * e.g. `<texture src>`). Unlike `createShader` the vertex stage is yours:
+ * e.g. `<texture src>`) - named, like `createShaderTexture`, for what comes
+ * back. Unlike `createShaderTexture` the vertex stage is yours:
  * declare `in` attributes matching `opts.attributes` (one interleaved vertex
  * in `opts.buffer`, a {@link createBuffer} id) and your own varyings toward
- * the fragment stage. Both sources may reference `iResolution`/`iTime` and any
- * `uniform float` they declare; drive values with `<texture src={id}
- * params={{...}} />` or `setShaderParams`, exactly like a fragment shader.
+ * the fragment stage. Clip space is y-down: `gl_Position` y = -1 is the top
+ * row of the target and +1 the bottom, so camera-up geometry must negate y
+ * (or fold the flip into its projection) to display up. Both sources may
+ * 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.
  * `opts.depth` attaches a private depth buffer (cleared + tested per render);
- * `opts.vertexCount` defaults to the whole buffer and can be changed later
- * with `setDrawCount`. Frees the texture and GL program when the reactive
+ * `opts.depthWrite: false` (requires depth) keeps the test but stops the
+ * draw from writing depth. `opts.blend: "add"` makes the draw accumulate
+ * overlapping geometry additively (order-independent, no sorting) instead of
+ * overwriting; a depth-tested additive pass is `{ depth: true, blend: "add",
+ * depthWrite: false }` - each option only does what it says, neither implies
+ * the other. The draw range (`firstVertex`, `vertexCount`, `instanceCount` -
+ * 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
+ * `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
  * scope for app-lifetime pipelines.
  */
-export function createPipeline(
+export function createPipelineTexture(
   vertexSrc: string,
   fragmentSrc: string,
   width: number,
   height: number,
+  params?: gpu.ShaderParams | null,
   opts?: {
-    params?: Record<string, number>
-    textures?: Record<string, number>
+    textures?: Record<string, gpu.TextureId>
     attributes?: gpu.VertexAttribute[]
-    buffer?: number
+    buffer?: gpu.BufferId
     topology?: gpu.Topology
-    vertexCount?: number
     depth?: boolean
+    depthWrite?: boolean
+    blend?: gpu.BlendMode
     clearColor?: [number, number, number, number]
-  } & CreateOptions,
-): number {
-  let id = gpu.createPipeline(vertexSrc, fragmentSrc, width, height, opts)
+    render?: "auto" | "manual"
+    loadOp?: "clear" | "load"
+  } & gpu.DrawRange &
+    CreateOptions &
+    SamplerOptions,
+): gpu.TextureId {
+  let id = gpu.createPipelineTexture(vertexSrc, fragmentSrc, width, height, params, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
@@ -269,10 +468,10 @@ export function createPipeline(
  * creation, so reserve room up front for dynamic geometry. Freed automatically
  * when the reactive owner is disposed (opt out with `{ manual: true }`);
  * created outside a reactive scope you must call `destroyBuffer` yourself.
- * Destroy pipelines before their buffer.
+ * (Destruction order relative to pipelines does not matter.)
  */
-export function createBuffer(data: ArrayBuffer | ArrayBufferView, opts?: CreateOptions): number {
-  let id = gpu.createBuffer(toUint8(data))
+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))
   return id
 }
@@ -282,6 +481,6 @@ export function createBuffer(data: ArrayBuffer | ArrayBufferView, opts?: CreateO
  * pipeline drawing from the buffer re-renders with its last-applied params,
  * so geometry-only changes reach the screen without a params update.
  */
-export function writeBuffer(id: number, data: ArrayBuffer | ArrayBufferView, byteOffset?: number): void {
+export function writeBuffer(id: gpu.BufferId, data: ArrayBuffer | ArrayBufferView, byteOffset?: number): void {
   gpu.writeBuffer(id, toUint8(data), byteOffset)
 }

package/src/image.ts

@@ -1,10 +1,11 @@
 // 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/createShader have to flux:gpu.
+// changes - the same relationship createTexture/createShaderTexture have to
+// flux:gpu.
 
 import { createMemo, onCleanup } from "@solidjs/signals"
-import { createTexture, destroyTexture } from "./gpu"
+import { createTexture, destroyTexture, type TextureId } from "./gpu"
 
 export type DecodedImage = {
   data: Uint8Array
@@ -32,13 +33,13 @@ export type ImageSource = string | Uint8Array
 // Uint8Array sources bypass all of this: no key, per-mount texture.
 type ImageEntry = {
   refs: number
-  texture: number
-  promise: Promise<number>
+  texture: TextureId | undefined
+  promise: Promise<TextureId>
 }
 
 let imageCache = new Map<string, ImageEntry>()
 
-async function loadImage(url: string): Promise<number> {
+async function loadImage(url: string): Promise<TextureId> {
   // Images are assets: cache to disk, no freshness. Use a versioned URL (or
   // fetch + decodeImage manually) when a URL's content must be re-checked.
   let res = await fetch(url, { cache: "force-cache" })
@@ -56,7 +57,7 @@ async function loadImage(url: string): Promise<number> {
 function acquireImage(url: string): ImageEntry {
   let entry = imageCache.get(url)
   if (!entry) {
-    let e: ImageEntry = { refs: 0, texture: -1, promise: undefined as never }
+    let e: ImageEntry = { refs: 0, texture: undefined, promise: undefined as never }
     e.promise = loadImage(url).then(
       id => {
         // Everyone released while the load was in flight: nothing owns the
@@ -91,7 +92,7 @@ function releaseImage(url: string): void {
   if (!entry) return
   entry.refs--
   if (entry.refs > 0) return
-  if (entry.texture >= 0) {
+  if (entry.texture !== undefined) {
     destroyTexture(entry.texture)
     imageCache.delete(url)
   }
@@ -122,10 +123,10 @@ function releaseImage(url: string): void {
  * `createImage` earns its async only for a fetched string URL or a reactive
  * source.
  */
-export function createImage(src: ImageSource | (() => ImageSource)): () => number {
+export function createImage(src: ImageSource | (() => ImageSource)): () => TextureId {
   let getSrc = typeof src === "function" ? src : () => src
 
-  return createMemo<number>(async () => {
+  return createMemo<TextureId>(async () => {
     let source = getSrc()
 
     if (typeof source === "string") {
@@ -138,9 +139,9 @@ export function createImage(src: ImageSource | (() => ImageSource)): () => numbe
     }
 
     // Byte sources decode and upload synchronously; this run owns the texture.
-    let holder = { id: -1 }
+    let holder: { id: TextureId | undefined } = { id: undefined }
     onCleanup(() => {
-      if (holder.id >= 0) destroyTexture(holder.id)
+      if (holder.id !== undefined) destroyTexture(holder.id)
     })
     let decoded: DecodedImage
     try {

package/src/index.ts

@@ -13,8 +13,11 @@ export type { GamepadState } from "./gamepad"
 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 type { DecodedImage, ImageSource } from "./image"
+export { parseSvg, svg } from "./svg"
+export type { SvgDocument, SvgDraw } from "./svg"
 export { createScroll } from "./scroll"
 export type { Scroll, ScrollAxis, ScrollOffset, ScrollOptions } from "./scroll"
 export type {

package/src/renderer.ts

@@ -129,21 +129,22 @@ export function scanForOrphans(now: number): void {
 }
 
 // A property the native tree rejected must not take down the reactive system:
-// a typo'd or not-yet-implemented prop poisons only itself. Warn once per
-// element kind + property with a stack (the dev server remaps its frames to
-// the .tsx source), then ignore further writes of the same pair.
-let warnedUnknownProps = new Set<string>()
+// a typo'd, not-yet-implemented, or detached-only prop poisons only itself.
+// Warn once per element kind + property with a stack (the dev server remaps
+// its frames to the .tsx source), then ignore further writes of the same pair.
+let warnedRejectedProps = new Set<string>()
 
 function setTreeProperty(node: ProxyNode, name: string, value: unknown): void {
   try {
     tree.setProperty(node.id, name, value)
   } catch (e) {
-    if (!String(e).includes("unknown property")) throw e
+    let message = String(e)
+    if (!message.includes("unknown property") && !message.includes("detached-only")) throw e
     let key = node.elementType + "." + name
-    if (warnedUnknownProps.has(key)) return
-    warnedUnknownProps.add(key)
+    if (warnedRejectedProps.has(key)) return
+    warnedRejectedProps.add(key)
     let stack = new Error().stack ?? ""
-    console.warn(`Ignoring unknown property '${name}' on <${node.elementType}>\n${stack}`)
+    console.warn(`Ignoring property '${name}' on <${node.elementType}>: ${message}\n${stack}`)
   }
 }