@solidrt/core 0.0.40 → 0.0.41

package/src/gpu.ts

@@ -21,6 +21,26 @@
 // 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"
@@ -30,13 +50,22 @@ 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
 // (textures made outside a reactive scope, e.g. after an await, are not
@@ -57,20 +86,64 @@ 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 { BlendMode, ShaderParams, 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. A laid-out node captures its layout box; a `d-*` node
@@ -108,7 +181,7 @@ export function createTexture(
   width: number,
   height: number,
   opts?: CreateOptions & SamplerOptions,
-): number {
+): gpu.TextureId {
   let id = gpu.createTexture(data, width, height, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
@@ -128,7 +201,7 @@ export function createMutableTexture(
   width: number,
   height: number,
   opts?: CreateOptions & SamplerOptions,
-): number {
+): gpu.TextureId {
   let id = gpu.createMutableTexture(data, width, height, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
@@ -137,13 +210,17 @@ export function createMutableTexture(
 /**
  * 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 it declares (`float`/`int`
+ * `<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`.
- * `textures` binds each declared `uniform sampler2D` to an existing texture id
+ * 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
@@ -151,72 +228,85 @@ export function createMutableTexture(
  * 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`, `iTime`,
+ * That preamble (`#version 300 es`, precision, `vUV`, `iResolution`,
  * `fragColor`) is injected only into sources that do not declare their own
- * `#version` line. A source starting with `#version 300 es` compiles exactly
+ * `#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?: gpu.ShaderParams,
-  textures?: Record<string, number>,
-  opts?: CreateOptions & SamplerOptions,
-): number {
-  let id = gpu.createShader(fragmentSrc, width, height, params, textures, opts)
+  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?: gpu.ShaderParams
-    textures?: Record<string, number>
-    attributes?: gpu.VertexAttribute[]
-    buffer?: number
-    topology?: gpu.Topology
-    vertexCount?: number
-    depth?: boolean
-    depthWrite?: boolean
-    blend?: gpu.BlendMode
+    textures?: Record<string, gpu.TextureId>
+    buffer?: gpu.BufferId
     clearColor?: [number, number, number, number]
-  } & CreateOptions &
+    render?: "auto" | "manual"
+    loadOp?: "clear" | "load"
+  } & gpu.DrawRange &
+    CreateOptions &
     SamplerOptions,
-): number {
-  let id = gpu.createShaderTarget(program, width, height, opts)
+): 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. Sampling
- * (`filter`/`wrap`) is creation-time state, so changing it rebuilds at a
- * fresh id, like a fragment-source or sampler-binding change. */
+/** 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?: gpu.ShaderParams
-  textures?: Record<string, number>
+  textures?: Record<string, gpu.TextureId>
 } & SamplerOptions
 
 // Shallow name->value equality for params/textures records; treats undefined
@@ -261,12 +351,12 @@ function sameRecord(
  * 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(
+export function createShaderTextureMemo(
   spec: () => ShaderSpec,
   opts?: { onError?: (error: unknown) => void },
-): () => number {
+): () => gpu.TextureId {
   let make = (s: ShaderSpec) =>
-    gpu.createShader(s.fragmentSrc, s.width, s.height, s.params, s.textures, { filter: s.filter, wrap: s.wrap })
+    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 = make(current)
   let [id, setId] = createSignal(currentId)
@@ -317,45 +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 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.
+ * 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.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. `opts.vertexCount` defaults to the whole buffer and can be
- * changed later with `setDrawCount`. Frees the texture and GL program when the reactive
+ * 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?: gpu.ShaderParams
-    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 &
+    render?: "auto" | "manual"
+    loadOp?: "clear" | "load"
+  } & gpu.DrawRange &
+    CreateOptions &
     SamplerOptions,
-): number {
-  let id = gpu.createPipeline(vertexSrc, fragmentSrc, width, height, opts)
+): gpu.TextureId {
+  let id = gpu.createPipelineTexture(vertexSrc, fragmentSrc, width, height, params, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
 }
@@ -367,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
 }
@@ -380,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}`)
   }
 }
 

package/src/runtime-modules.d.ts

@@ -105,8 +105,8 @@ declare module "srt:apps" {
    * installs nothing and leaves it alone. `size` is the version's
    * manifest-declared size (bundle plus assets) - claimed rather than walked,
    * so that listing stays cheap; `info()` reports what is actually on disk.
-   * `icon` is the manifest-declared icon's SVG source, ready for an `<svg>`
-   * src; absent when the app declares none (or the file is unreadable).
+   * `icon` is the manifest-declared icon's SVG source, ready for `parseSvg`;
+   * absent when the app declares none (or the file is unreadable).
    */
   export type InstalledApp = {
     id: string

package/src/speech-recognition.ts

@@ -3,7 +3,8 @@
 // final transcripts through onResult. With wakeWord the session starts
 // asleep behind an efficient wake word detector (livekit-wakeword) and only
 // transcribes after the wake word. startRecognition resolves once the models
-// are loaded and listening has begun; it rejects when loading fails.
+// are loaded and listening has begun; it rejects when the microphone cannot be
+// opened or the models fail to load.
 // Models are passed as bytes so any source composes: flux:fs file(), fetch
 // (incl. the dev-server file proxy), or a download cache layered on top.
 // Requires a runtime built with speech support.

package/src/svg.ts

@@ -0,0 +1,71 @@
+// SVG documents as data: parseSvg turns a document string into a flat list of
+// draws that map straight onto <d-path> elements. Vector currency is path
+// data, the same way raster currency is a texture id - there is no document
+// element that swallows the source; the app owns the parsed data and composes
+// ordinary primitives from it.
+
+import { parseSvg as fluxParseSvg } from "flux:svg"
+import { parseColor, type Gradient } from "./color"
+
+/**
+ * Tags an inline SVG source, returning it unchanged. Documents 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 markup inside a template
+ * literal only when a known tag marks it (the name matters - `svg` is one the
+ * grammars look for). Raw semantics, like `glsl`.
+ */
+export let svg = String.raw
+
+/**
+ * One resolved draw in document coordinates. The keys match `PathProps`, so a
+ * draw spreads onto a `<d-path>` unchanged: `<d-path {...draw} />`. A source
+ * path with both a fill and a stroke yields two draws (fill first).
+ */
+export type SvgDraw = {
+  d: string
+  color: string | Gradient
+  drawStyle: "fill" | "stroke"
+  fillRule?: "nonzero" | "evenodd"
+  strokeWidth?: number
+  strokeCap?: "butt" | "round" | "square"
+  strokeJoin?: "miter" | "round" | "bevel"
+}
+
+/** A parsed document: intrinsic size (viewBox/width-height) plus the flat draw list. */
+export type SvgDocument = {
+  width: number
+  height: number
+  draws: SvgDraw[]
+}
+
+/**
+ * Parses an SVG document string (an imported `.svg` asset, an icon library's
+ * string export, or a template literal) into plain draw data: geometry
+ * flattened to absolute path data with every transform baked in, paints
+ * resolved to colors or gradients. Render it by wrapping the draws in a view
+ * that fits the document's coordinate space into its box:
+ *
+ *     let doc = createMemo(() => parseSvg(src))
+ *     <view repaintBoundary viewBox={[doc().width, doc().height]} width={48} height={48}>
+ *       {doc().draws.map((draw) => <d-path {...draw} />)}
+ *     </view>
+ *
+ * The plain repaintBoundary is the recommended default: the parsed subtree is
+ * static, so it never re-records alongside changing siblings. Each `<d-path>`
+ * hit-tests its exact outline; when the document should act as ONE hit target
+ * (the usual icon case), add `pointerEvents="all"` to the wrapper - the box
+ * then matches as a whole and the per-path outline tests are skipped.
+ *
+ * `opts.color` drives `currentColor` in the document (any CSS color string),
+ * which is how monochrome icon sets (Lucide, Feather, Heroicons, ...) get
+ * recolored; explicit fills/strokes still win. Parsing is synchronous and
+ * sandboxed (no network, file, or data-URI access) and throws on an invalid
+ * document. Parse once per document under a memo, not per instance.
+ *
+ * Unsupported and skipped: clipPath, masks, filters, patterns, embedded
+ * images, and SVG text.
+ */
+export function parseSvg(src: string, opts?: { color?: string }): SvgDocument {
+  if (opts?.color != null) return fluxParseSvg(src, { color: parseColor(opts.color) })
+  return fluxParseSvg(src)
+}