@solidrt/flux-types 0.0.54 → 0.0.56

package/gui/gpu.d.ts

@@ -107,9 +107,12 @@ declare module "flux:gpu" {
    * A uniform that is declared but optimized out by the compiler is accepted
    * with a warning and the write is skipped, so one param object can drive
    * shader variants that do not all use every uniform.
-   * An `undefined` value is skipped, so conditional spreads stay usable.
+   * An `undefined` (or `null`) value is skipped, so conditional spreads stay
+   * usable. A `Float32Array`/`Float64Array` is accepted as a flat array. The
+   * same decoder serves the `<texture params>`, view and window shader props,
+   * so the prop and the imperative path accept and reject identically.
    */
-  export type ShaderParams = Record<string, number | number[]>
+  export type ShaderParams = Record<string, number | number[] | Float32Array | Float64Array>
   /** Magnification/minification filter; "linear" (default) or hard-pixel "nearest". */
   export type FilterMode = "linear" | "nearest"
   /** Sampling outside 0..1: "clamp" (default, extend edge pixels) or "repeat" (tile). */
@@ -129,8 +132,19 @@ declare module "flux:gpu" {
    * shader sampling minifies through the chain; the `<texture>` display
    * draw samples the full-size level. Regeneration is one GPU pass per
    * upload or render, so a per-frame texture pays it per frame.
+   *
+   * `anisotropy` (default 1 = off) is the anisotropic filtering level, Three's
+   * `texture.anisotropy`: the most taps a shader sample may take along the
+   * axis a surface is foreshortened on, so a tiled ground plane seen at a
+   * grazing angle stays sharp to the horizon instead of smearing into the
+   * mip level its long axis picks. Any number >= 1; rounded down to a power
+   * of two, capped at 16 and then at the device's `limits.maxAnisotropy`
+   * (1 on a device without the extension - the texture then samples as
+   * today, no error). Only meaningful with `mipmap: true` (it filters
+   * through the chain), ignored by the `<texture>` display draw like the
+   * chain itself. Below 1 or non-finite throws.
    */
-  export type SamplerOptions = { filter?: FilterMode; wrap?: WrapMode; mipmap?: boolean }
+  export type SamplerOptions = { filter?: FilterMode; wrap?: WrapMode; mipmap?: boolean; anisotropy?: number }
   /**
    * One `textures` binding value: a texture id, sampled with the texture's
    * own declared state, or `{ id, filter?, wrap? }` to sample that id with a
@@ -141,7 +155,14 @@ declare module "flux:gpu" {
    * not overridable - the chain either exists on the id or it does not.
    */
   export type TextureBinding = TextureId | { id: TextureId; filter?: FilterMode; wrap?: WrapMode }
-  /** Sampler2D inputs by uniform name; see {@link TextureBinding}. */
+  /**
+   * Sampler inputs by uniform name; see {@link TextureBinding}. The uniform's
+   * declared type picks what may bind: a `sampler2D` takes any 2D texture,
+   * a `samplerCube` a cube map ({@link createCubeTexture}), a
+   * `sampler2DShadow` a draw target's depth texture; a mismatch throws. An
+   * `undefined` (or `null`) binding is skipped, like a param; an id must be
+   * a non-negative integer (a negative or fractional value throws).
+   */
   export type TextureBindings = Record<string, TextureBinding>
   /**
    * A free-form debug name every create accepts (WebGPU's label): surfaced by
@@ -163,8 +184,45 @@ declare module "flux:gpu" {
    * texture as `(v, 0, 0, 1)` - read `.r`; displaying one via `<texture src>`
    * shows that same red-channel reading. Shader/pipeline targets and
    * readbacks stay RGBA8.
+   *
+   * "r32f" and "rgba32f" are the float data-texture formats, for float
+   * payloads a shader fetches - per-sector heights read in a vertex stage,
+   * bone matrices at scale, lookup tables wider than 8 bits - without
+   * fixed-point encoding into RGBA8 channels. One f32 per channel: data is a
+   * Float32Array of width*height (r32f, sampled as `(v, 0, 0, 1)`) or
+   * width*height*4 (rgba32f, a vec4 per texel). Upload-and-sample only, and
+   * nearest-only - `filter` defaults to "nearest" and "linear", `mipmap` and
+   * `anisotropy` throw (float linear filtering is not in core GLES 3.0;
+   * fetch exact texels with `texelFetch`). No readback or copy path
+   * (readTexture and copyTexture throw: float is not color-renderable in
+   * core), and displaying one via `<texture src>` is out of contract - these
+   * are shader data, not image content.
+   *
+   * "rgba16f" is the HDR image format (environment maps, panoramas): the same
+   * Float32Array payload (width*height*4), packed to half float on upload,
+   * and filterable like a byte format (RGBA16F is texture-filterable in core
+   * GLES 3.0), so `filter` defaults to "linear" and `anisotropy` applies.
+   * `mipmap: true` needs half float to be color-renderable on the device
+   * (`limits.halfFloatRenderable`; an extension almost every device has) and
+   * throws where it is not. Sample-only like the 32-bit formats (no
+   * readback, copy or display); also a draw target format where half float
+   * is renderable ({@link createDrawTarget}, {@link createCubeDrawTarget}:
+   * HDR views, probes and bakes).
+   *
+   * "rgba8-srgb" is "rgba8" whose bytes are sRGB-encoded: a shader sampling
+   * it reads linear light (the decode is done in hardware, before filtering,
+   * so `filter`, `mipmap` and `anisotropy` are all correct); alpha is not
+   * decoded. The color-map format of linear-space lighting - base color and
+   * emissive maps - while data maps (normal, roughness, metallic) stay
+   * "rgba8". Sample-only: readTexture and copyTexture throw (a readback
+   * would decode rather than return the stored bytes) and displaying one
+   * via `<texture src>` is out of contract; also a draw target format (the
+   * target encodes what a pass writes).
+   *
+   * Reserved future value of this same vocabulary: "etc2-rgba8" (compressed
+   * uploads).
    */
-  export type TextureFormat = "rgba8" | "r8"
+  export type TextureFormat = "rgba8" | "rgba8-srgb" | "r8" | "r32f" | "rgba32f" | "rgba16f"
   export type TextureFormatOption = { format?: TextureFormat }
   /**
    * This device's hard ceilings, queried once at startup: process constants.
@@ -178,6 +236,8 @@ declare module "flux:gpu" {
   export let limits: {
     /** Largest width/height of any texture or render target, in pixels (>= 2048). */
     maxTextureSize: number
+    /** Largest face edge of a cube map, in pixels (>= 2048); its own GL ceiling. */
+    maxCubeMapSize: number
     /**
      * Sampler inputs one pass may bind (>= 16): a target's `textures`
      * entries; on a window shader the runtime-filled `uSource` (and
@@ -186,26 +246,73 @@ declare module "flux:gpu" {
     maxTextureUnits: number
     /** Vertex attributes one pipeline may declare (>= 16). */
     maxVertexAttribs: number
+    /**
+     * Highest `anisotropy` level the device samples at (a power of two, 1
+     * when the device has no anisotropic filtering). A report, not a
+     * ceiling: a higher requested level is clamped to it silently, so
+     * `anisotropy: limits.maxAnisotropy` is the "as sharp as this device
+     * goes" spelling.
+     */
+    maxAnisotropy: number
+    /**
+     * vec4 uniform slots a vertex stage may declare (>= 256): a mat4 costs
+     * 4, a `mat4 u[N]` array 4N. What bounds a bone-palette array - a
+     * dynamically indexed array keeps every declared element active, so
+     * the declaration itself must fit or the program fails to link.
+     */
+    maxVertexUniformVectors: number
+    /**
+     * Whether half float is color-renderable on this device (the
+     * EXT_color_buffer_half_float extension, which almost every device
+     * has): what a generated mip chain needs, so `mipmap: true` on an
+     * "rgba16f" texture throws where this is false.
+     */
+    halfFloatRenderable: boolean
   }
   /**
-   * Create an immutable texture from a pixel buffer (exactly
-   * width*height*bytesPerPixel bytes: *4 for the default "rgba8" format, *1
-   * for "r8"). Returns the texture id.
+   * Create an immutable texture from a pixel buffer holding exactly one
+   * frame at the declared format's size. The view type must match the
+   * format: byte formats ("rgba8", "rgba8-srgb", "r8") take a Uint8Array,
+   * float formats ("r32f", "rgba32f", "rgba16f") a Float32Array. Returns
+   * the texture id.
+   */
+  export function createTexture(data: Uint8Array | Float32Array, width: number, height: number, opts?: SamplerOptions & TextureFormatOption & LabelOption): TextureId
+  /**
+   * Create a cube map from six square faces in GL order (+X, -X, +Y, -Y,
+   * +Z, -Z), each exactly one `size` x `size` frame at the declared format
+   * (view type per format as in {@link createTexture}) - or from an explicit
+   * mip chain: an array of such six-face arrays, level 0 first, sizes
+   * halving down to the 1x1 level (the FULL chain; a shorter one throws),
+   * uploaded as given instead of generated, so it carries prefiltered
+   * levels and needs no color-renderable format (an "rgba16f" chain works
+   * on every device). Explicit levels imply `mipmap: true` (`mipmap: false`
+   * with them throws). Returns an ordinary texture id that only a `uniform
+   * samplerCube` binding consumes - sampled by direction (`texture(uEnv,
+   * dir)`, `textureLod` for a level when the chain exists). Sampler-only
+   * and create-once: `<texture src>` cannot display it, and uploadTexture,
+   * resizeTexture, readTexture and copyTexture throw for it. `wrap` is
+   * accepted and has no effect (cube filtering is seamless). A cube map on a
+   * `sampler2D`, or a 2D texture on a `samplerCube`, throws at the bind.
+   * GL's convention holds: each face is what a lookup in that direction
+   * returns (the cube seen from outside), so a face set authored as seen
+   * from inside (Three's) is mirrored per image before upload.
    */
-  export function createTexture(data: Uint8Array, width: number, height: number, opts?: SamplerOptions & TextureFormatOption & LabelOption): TextureId
+  export function createCubeTexture(faces: (Uint8Array | Float32Array)[] | (Uint8Array | Float32Array)[][], size: number, opts?: SamplerOptions & TextureFormatOption & LabelOption): TextureId
   /**
    * Create a texture intended to be updated later via {@link uploadTexture}. The
-   * seed buffer must hold at least one frame (width*height bytes at the
-   * declared format's pixel size) and may hold more (uploadTexture selects a
-   * frame by offset).
+   * seed buffer must hold at least one frame at the declared format's size
+   * and may hold more (uploadTexture selects a frame by offset); like
+   * {@link createTexture}, the view type must match the format (Uint8Array
+   * for byte formats, Float32Array for float formats).
    */
-  export function createMutableTexture(data: Uint8Array, width: number, height: number, opts?: SamplerOptions & TextureFormatOption & LabelOption): TextureId
+  export function createMutableTexture(data: Uint8Array | Float32Array, width: number, height: number, opts?: SamplerOptions & TextureFormatOption & LabelOption): TextureId
   /**
-   * Replace a mutable texture's pixels; the frame size follows the format the
-   * id was created with. `data` may hold several frames; `offset` (default 0)
-   * selects which frame to upload.
+   * Replace a mutable texture's pixels; the frame size and required view
+   * type (Uint8Array for byte formats, Float32Array for float formats)
+   * follow the format the id was created with. `data` may hold several
+   * frames; `offset` (default 0) selects which frame to upload.
    */
-  export function uploadTexture(id: TextureId, data: Uint8Array, offset?: number): void
+  export function uploadTexture(id: TextureId, data: Uint8Array | Float32Array, offset?: number): void
   /**
    * Replace a texture's storage with a new size at the same id (an id-stable
    * resize): `<texture src>` references and shader sampler bindings keep
@@ -215,7 +322,7 @@ declare module "flux:gpu" {
    * state). Render target ids are rejected - resize those with
    * {@link setTargetSize}.
    */
-  export function resizeTexture(id: TextureId, data: Uint8Array, width: number, height: number): void
+  export function resizeTexture(id: TextureId, data: Uint8Array | Float32Array, width: number, height: number): void
   /**
    * Destroy a texture (immutable, mutable, or shader). Frame-safe: the id is
    * reclaimed by the runtime once the render tree no longer references it, so
@@ -277,7 +384,14 @@ declare module "flux:gpu" {
    * 300 es`, `precision highp float;`, `uniform vec2 iResolution;`, plus
    * `out vec4 fragColor;` for a fragment stage (the same text
    * {@link createPipelineTexture} injects). Do not combine `header` with your
-   * own `#version` line. Returns a shader (stage) id in its own id space;
+   * own `#version` line. The header declares those names rather than only
+   * filling them, so a source compiled with `header: true` must not declare
+   * them again: `uniform vec3 iResolution;` carried over from a ported shader
+   * is the usual mistake and fails as a redefinition (under the header
+   * iResolution is vec2; only a complete source may declare it vec3 and get
+   * `(w, h, 1.0)`). Everything else - samplers, app-driven uniforms,
+   * varyings (no `vUV` here) - is the source's own declaration.
+   * Returns a shader (stage) id in its own id space;
    * compile errors throw here, synchronously, at a call site the app chose.
    * Free with {@link destroyShader}.
    *
@@ -419,6 +533,8 @@ declare module "flux:gpu" {
       /** One buffer per instance slot of the pipeline (index = the
        * attributes' `slot`); pass this OR `instanceBuffer`, not both. */
       instanceBuffers?: BufferId[]
+      /** Draw the instance records in key order (see {@link InstanceOrder}). */
+      instanceOrder?: InstanceOrder
       clearColor?: [number, number, number, number]
       render?: "auto" | "manual"
       loadOp?: "clear" | "load"
@@ -577,6 +693,90 @@ declare module "flux:gpu" {
     instanceBuffer?: BufferId
     instanceBuffers?: BufferId[]
   } & ({} | IndexBinding)
+  /**
+   * A draw entry's instance ORDER, declared at creation via the
+   * `instanceOrder` option: the entry draws the records of its instance
+   * buffer in KEY order instead of buffer order, while the writer keeps
+   * addressing stable slots - raise and y-sort without record churn, and
+   * back-to-front over a large population without per-record JS. (This
+   * orders one entry's RECORDS; {@link setDrawOrder} orders a target's
+   * ENTRIES - different granularity, unrelated verbs.)
+   *
+   * The key, one of two modes fixed at creation, both offsets counted in
+   * FLOATS into one instance record: `field` reads the single f32 at that
+   * offset (a y coordinate, an age, an explicit sort field); `position`
+   * reads the vec3 at that offset and keys on dot(position, `direction`) -
+   * view depth along a direction you update per camera move with
+   * `orderDirection` (see {@link OrderUpdate}). Ascending by default
+   * (smallest key draws first); `descending: true` for back-to-front when
+   * larger keys are nearer. The sort is stable - equal keys keep slot
+   * order, so untouched populations draw exactly as without an order - and
+   * NaN keys sort last (ascending).
+   *
+   * The order materializes when the buffer is PUBLISHED: each
+   * {@link beginBufferWrite}/{@link endBufferWrite} publish gathers the
+   * records into key order on the way to the GPU (one extra copy of the
+   * published bytes; a single-buffer entry retains nothing). A population
+   * that republishes each frame re-orders each frame for free; a direction
+   * change alone takes effect at the next publish - unless the entry opts
+   * into `retain`, where it re-orders immediately from core's retained
+   * copy. Because the GPU-side
+   * contents are the gathered records, {@link writeBuffer} on an ordered
+   * buffer throws (a byte-offset write would land on the wrong records -
+   * publish whole record sets through the lease), {@link readBuffer} reads
+   * back gathered order, a publish must be a whole number of records, and
+   * `instanceCount` below the published record count draws the first N in
+   * key order.
+   *
+   * An entry with SEVERAL instance buffers orders them all under ONE
+   * permutation: the key reads from slot 0's records, and every other
+   * slot's publishes gather to match, so split records (a core-written
+   * pose buffer plus an app-written style buffer) always describe the same
+   * draw order. This retains a copy of each slot's records: when the key
+   * order changes - including through spatial record sinks, with no
+   * publish from the app anywhere - the sibling buffers republish
+   * themselves in the same frame. The entry's instance buffers must be
+   * pairwise distinct, each ordered by no other entry; a buffer swap
+   * ({@link BufferUpdate}) carries the order to the new buffers, every
+   * swapped slot at once - republish app-written slots after a swap, the
+   * new buffer starts empty.
+   */
+  export type InstanceOrder = ({ field: number } | { position: number; direction: [number, number, number] }) & {
+    descending?: boolean
+    /**
+     * Which instance slot's records hold the key (default 0). On a
+     * multi-buffer entry the key may live in any one slot - a core-written
+     * pose slot keyed by position, or an app-written style slot keyed by
+     * an explicit sort field - and every other slot gathers under its
+     * permutation.
+     */
+    slot?: number
+    /**
+     * The retained-copy strategy, for write-once populations (a splat
+     * cloud: records written once, only the ORDER changes per camera
+     * move). Core keeps a CPU copy of each slot's published records, and
+     * an `orderDirection` update re-sorts that copy and republishes the
+     * entry's buffers core-side, in the same call, with no publish from
+     * the app; when the re-sort leaves the order unchanged nothing
+     * uploads, so a parked camera costs nothing. The copy is the
+     * deliberate cost (the records' size in CPU memory); publishes still
+     * go through the lease and update the copy. Position keys only - a
+     * field key re-orders when its records republish, so retaining buys
+     * nothing there and throws.
+     */
+    retain?: boolean
+  }
+  /**
+   * The order half of a draw-entry update: `orderDirection` replaces the
+   * projected key's direction ({@link InstanceOrder}'s `position` mode) -
+   * the per-camera-move update. On a gather entry it stages sort state for
+   * the entry's NEXT publish and renders nothing by itself; on a retained
+   * entry (`retain: true`) it re-sorts core's copy right away and, when
+   * the order changed, republishes the entry's buffers - no publish from
+   * the app. On an entry without a position-keyed instance order it
+   * throws.
+   */
+  export type OrderUpdate = { orderDirection?: [number, number, number] }
 
   /**
    * Compile a GLSL ES vertex+fragment pipeline into an offscreen texture of
@@ -625,6 +825,8 @@ declare module "flux:gpu" {
       /** One buffer per instance slot (index = the attributes' `slot`);
        * pass this OR `instanceBuffer`, not both. */
       instanceBuffers?: BufferId[]
+      /** Draw the instance records in key order (see {@link InstanceOrder}). */
+      instanceOrder?: InstanceOrder
       topology?: Topology
       depth?: boolean
       depthWrite?: boolean
@@ -667,12 +869,18 @@ declare module "flux:gpu" {
    * closes and nothing is published. Always closes the lease, error or not;
    * throws when no write is open or `byteLength` exceeds the buffer size.
    * Pipelines drawing from the buffer re-render, like {@link writeBuffer}.
+   * On an ordered instance buffer ({@link InstanceOrder}) the publish is
+   * where the order materializes: the records reach the GPU gathered into
+   * key order, and `byteLength` must be a whole number of records.
    */
   export function endBufferWrite(id: BufferId, byteLength?: number): void
   /**
    * Overwrite part of a vertex buffer at `byteOffset` (default 0), within the
    * size it was created with. Pipelines drawing from the buffer re-render
-   * with their last-applied params.
+   * with their last-applied params. Throws on an ordered instance buffer
+   * ({@link InstanceOrder}): its GPU contents are in key order, so a
+   * byte-offset write would land on the wrong records - publish whole
+   * record sets through {@link beginBufferWrite}/{@link endBufferWrite}.
    */
   export function writeBuffer(id: BufferId, data: Uint8Array, byteOffset?: number): void
   /**
@@ -700,7 +908,7 @@ declare module "flux:gpu" {
    * buffer and extends the range into it, and a call that throws changes
    * nothing (range and buffers commit together or not at all).
    */
-  export function setDraw(id: TextureId, draw: (DrawRange | IndexRange) & BufferUpdate): void
+  export function setDraw(id: TextureId, draw: (DrawRange | IndexRange) & BufferUpdate & OrderUpdate): void
   /**
    * Create a draw target: a render target whose contents are an ordered,
    * mutable LIST of draws - one render clears once, then executes every
@@ -741,6 +949,17 @@ declare module "flux:gpu" {
    * Returns a texture id (display, resize, destroy like any target; entries
    * die with it).
    *
+   * `format` is the color storage: "rgba8" (default), "rgba8-srgb" (the
+   * target encodes what a pass writes and decodes on sample, like an
+   * uploaded sRGB texture) or "rgba16f" (half float: the range a pass
+   * writes survives - an HDR view or bake; renderable where
+   * `limits.halfFloatRenderable`, throws elsewhere). Other formats throw
+   * (not color-renderable). A target of either non-default format is
+   * SAMPLER-ONLY: bind it to a `sampler2D`; a `<texture>` leaf cannot
+   * display it, {@link readTexture} and {@link copyTexture} refuse it -
+   * render it through a pass into an rgba8 target for those. Multisampling
+   * and resize work at the format.
+   *
    * `into` makes a SUB-TARGET: a draw target that renders into the `width`
    * x `height` rectangle at `x`/`y` (top-left origin, the texture leaf's
    * `srcX`/`srcY` space; default 0) of draw target `into`'s storage instead
@@ -752,8 +971,8 @@ declare module "flux:gpu" {
    * cost one pass instead of N. The returned id is not a texture: sample,
    * display (`<d-texture src={parent} srcX srcY srcW srcH>`), read back and
    * copy the PARENT; `depthTexture(parent)` is the tile's depth too. Depth,
-   * `samples`, `render` and `loadOp` are the parent's (passing them
-   * throws), `clearColor` is the tile's own. A rectangle partly outside the
+   * `samples`, `format`, `render` and `loadOp` are the parent's (passing
+   * them throws), `clearColor` is the tile's own. A rectangle partly outside the
    * parent is clipped; {@link setTargetRect} moves it. Tiles do not nest.
    * Destroying the parent destroys its tiles.
    */
@@ -763,6 +982,7 @@ declare module "flux:gpu" {
     params?: ShaderParams | null,
     opts?: {
       depth?: boolean | "texture"
+      format?: "rgba8" | "rgba8-srgb" | "rgba16f"
       textures?: TextureBindings
       clearColor?: [number, number, number, number]
       render?: "auto" | "manual"
@@ -774,6 +994,46 @@ declare module "flux:gpu" {
     } & SamplerOptions &
       LabelOption,
   ): TextureId
+  /**
+   * Create a cube draw target: a draw target whose output is a `size` x
+   * `size` CUBE MAP, rendered one face at a time with `renderTarget(id,
+   * face)` (GL order: 0 +X, 1 -X, 2 +Y, 3 -Y, 4 +Z, 5 -Z) - the
+   * reflection-probe and sky-bake primitive. One entry list, shared params
+   * and bindings as on {@link createDrawTarget}; the app writes the face's
+   * camera into the shared params and renders, six times. Manual by
+   * contract (`render` defaults to "manual"; "auto" throws), one private
+   * depth renderbuffer for all faces (`depth: true`; "texture" throws), no
+   * `samples`, no `into`; `format` rgba8, rgba8-srgb or rgba16f. `mipmap:
+   * true` allocates the whole chain: a face
+   * render without a level regenerates it from level 0 (as every content
+   * write on a mipmapped target), a render into an explicit `level`
+   * writes that level alone at its own edge - how a prefiltered
+   * environment chain is rendered level by level. The id is a cube map to
+   * every consumer: bind it to a `samplerCube`, never display, read back,
+   * copy or resize it. Each face pass inverts the front-face rule: a GL cube
+   * face is seen from outside, the x mirror of a 2D target's image, so
+   * render every face through an x-mirrored projection and the pipelines'
+   * cull modes keep their meaning (derivative-built tangent frames flip
+   * with the mirror - a known artifact of mirrored views).
+   */
+  export function createCubeDrawTarget(
+    size: number,
+    params?: ShaderParams | null,
+    opts?: {
+      depth?: boolean
+      /** rgba8 (default); rgba8-srgb: the cube encodes what a pass writes
+       * and decodes on sample, like an uploaded sRGB cube; rgba16f: half
+       * float, the range a pass writes survives (HDR probes), renderable
+       * where `limits.halfFloatRenderable` (throws elsewhere - fall back to
+       * rgba8). Other formats throw: not color-renderable. */
+      format?: "rgba8" | "rgba8-srgb" | "rgba16f"
+      textures?: TextureBindings
+      clearColor?: [number, number, number, number]
+      render?: "manual"
+      loadOp?: "clear" | "load"
+    } & SamplerOptions &
+      LabelOption,
+  ): TextureId
   /**
    * The depth texture of a draw target created with `depth: "texture"`: a
    * texture id of its own, stable for the target's life (a
@@ -786,9 +1046,15 @@ declare module "flux:gpu" {
    * depth throws. SAMPLER-ONLY: it is not an upload texture and not a
    * readback source (`readTexture`/`copyTexture` throw - render it through a
    * pass to read it), its sampling is fixed at `nearest`/`clamp` (a depth
-   * texture is only complete at nearest without a comparison mode - filter
-   * in the shader, e.g. a PCF loop), and it dies with its target
-   * (`destroyTexture` on it throws). Displaying it via `<texture src>`
+   * texture is only complete at nearest without a comparison mode), and it
+   * dies with its target (`destroyTexture` on it throws). A pipeline
+   * program may instead declare the uniform as `sampler2DShadow`: the
+   * engine then binds a COMPARISON sampler for it - `texture(map,
+   * vec3(uv, ref))` returns the hardware LEQUAL compare of `ref` against
+   * the map, LINEAR-weighted over the 2x2 footprint (one-tap PCF). Only a
+   * depth texture may back a sampler2DShadow uniform (anything else is
+   * refused at bind); a plain `sampler2D` keeps the raw nearest reads.
+   * Displaying it via `<texture src>`
    * shows the depth in the red channel. Throws for a target without texture
    * depth.
    */
@@ -833,6 +1099,8 @@ declare module "flux:gpu" {
       /** One buffer per instance slot of the pipeline (index = the
        * attributes' `slot`); pass this OR `instanceBuffer`, not both. */
       instanceBuffers?: BufferId[]
+      /** Draw the instance records in key order (see {@link InstanceOrder}). */
+      instanceOrder?: InstanceOrder
       before?: DrawId
     } & (DrawRange | (IndexBinding & IndexRange)),
   ): DrawId
@@ -929,7 +1197,7 @@ declare module "flux:gpu" {
    * single entry, same partial merge, bounds validation, and vocabulary
    * rule (an indexed entry speaks {@link IndexRange}).
    */
-  export function setDrawRange(target: TextureId, draw: DrawId, update: DrawRange | IndexRange): void
+  export function setDrawRange(target: TextureId, draw: DrawId, update: (DrawRange | IndexRange) & OrderUpdate): void
   /**
    * Swap one draw entry's buffers: the {@link BufferUpdate} half of
    * {@link setDraw} addressed to a single entry, same replace-only rule and
@@ -945,7 +1213,9 @@ declare module "flux:gpu" {
    * back-to-front, and re-issue the order when the camera moves. Entry
    * state (params, textures, ranges) rides along untouched; ids are
    * unaffected. Like every draw-list write it re-renders an auto target
-   * once at the next flush, and folds silently on a manual one.
+   * once at the next flush, and folds silently on a manual one. (This
+   * orders a target's ENTRIES; ordering the instance RECORDS within one
+   * entry is {@link InstanceOrder}.)
    */
   export function setDrawOrder(target: TextureId, order: DrawId[]): void
   /**
@@ -960,9 +1230,16 @@ declare module "flux:gpu" {
    * the one counting. Ping-pong feedback is two manual targets sampling
    * each other, stepped alternately from `onFrame`; binding a target to
    * ITSELF still throws (same-pass GL feedback, undefined pixels regardless
-   * of who schedules it).
+   * of who schedules it). `face` (0..5) names the face of a cube draw
+   * target ({@link createCubeDrawTarget}) and is required there; a 2D
+   * target takes none. `level` names the mip level of that face to render
+   * into, on a `mipmap: true` cube target (0 up to the chain's last; the
+   * pass runs at the level's edge and regenerates nothing); without it the
+   * face's level 0 renders and the chain regenerates. Throws for a level
+   * on a 2D target or beyond the chain (a cube target without `mipmap`
+   * has level 0 only).
    */
-  export function renderTarget(id: TextureId): void
+  export function renderTarget(id: TextureId, face?: number, level?: number): void
   /**
    * Overwrite a `render: "manual"` target with another texture's current
    * pixels, GPU-side: the seed/history analog of {@link uploadTexture}
@@ -974,7 +1251,9 @@ declare module "flux:gpu" {
    * copy sees the copy, and targets sampling `dst` update afterwards.
    * Throws if either id is unknown, `dst` is not a manual target (the
    * runtime owns those contents), or `src === dst`. `src` may be any
-   * texture: uploaded, mutable, a camera frame, or another target's output.
+   * texture: uploaded, mutable, a camera frame, or another target's output -
+   * except a float-format texture (the copy would quantize its values to the
+   * target's rgba8; float textures are sample-only, so it throws).
    */
   export function copyTexture(src: TextureId, dst: TextureId): void
   /**
@@ -1013,7 +1292,8 @@ declare module "flux:gpu" {
    * Read back a registered texture's current pixels as RGBA8 (tightly packed,
    * top-to-bottom rows), for any texture id whatever created it (createTexture,
    * createShaderTexture, a render target). Synchronous. Throws if the id is
-   * unknown.
+   * unknown, or names a float-format texture (upload-and-sample only: float
+   * is not color-renderable in core GLES 3.0, so no readback path exists).
    */
   export function readTexture(id: TextureId): { width: number; height: number; data: Uint8Array }
 }

package/gui/rendertree.d.ts

@@ -15,7 +15,7 @@ declare module "flux:rendertree" {
     lineHeight?: number
     /** measureText only. */
     maxLines?: number
-    /** prepareText only: also report each unit's {@link TextUnit.carets}. */
+    /** prepareText only: also report each unit's {@link TextUnit.carets} (kerned per-glyph positions). */
     carets?: boolean
     /**
      * prepareText only: styled ranges over the text, in JS string offsets,
@@ -65,7 +65,11 @@ declare module "flux:rendertree" {
      * With `carets`: the caret positions inside the unit, one per grapheme
      * cluster boundary from its start (`offset` = start, x 0) to the end of
      * its shaped text (before any break characters), in order. `offset` is
-     * into the prepared text, `x` from the unit's pen position.
+     * into the prepared text, `x` from the unit's pen position. These are
+     * the per-glyph x positions of the shaping that is drawn, kerning
+     * included: for placing or animating single glyphs, use them rather
+     * than measuring characters one at a time with measureText, which sees
+     * no neighbors and drifts on every kerning pair.
      */
     carets?: { offset: number, x: number }[]
   }
@@ -165,8 +169,11 @@ declare module "flux:rendertree" {
   export function measureText(text: string, options?: MeasureTextOptions): { width: number, height: number }
   /**
    * Segment `text` into wrap units and shape each in the given font (through
-   * the shared word cache), for laying lines out in app code; see
-   * layoutNextLine in @solidrt/core. Single style; `maxLines` is ignored.
+   * the shared word cache, so a text already drawn or prepared costs no
+   * shaping), for app-side line breaking - text into a shape, around an
+   * obstacle, across columns, fitted by size, per glyph; see layoutNextLine
+   * in @solidrt/core. `runs` restyle ranges, `carets` adds glyph positions;
+   * `maxLines` is ignored.
    */
   export function prepareText(text: string, options?: MeasureTextOptions): PreparedText
   /**
@@ -182,6 +189,15 @@ declare module "flux:rendertree" {
    * semantics), for comparing against pointer event coordinates.
    */
   export function getBoundingBoxViewport(id: number): { x: number, y: number, width: number, height: number } | null
+  /**
+   * The node's laid-out box in its parent's frame: layout output before any
+   * transform composes (DOM offsetLeft/offsetTop/offsetWidth/offsetHeight
+   * semantics). The untransformed companion to getBoundingBox: pointer events
+   * report local coordinates in this box's units, whatever designSize fits or
+   * transforms sit on the ancestor chain. Null for detached nodes and before
+   * the first layout.
+   */
+  export function getLayoutBox(id: number): { x: number, y: number, width: number, height: number } | null
   /**
    * The texture id of a snapshot repaint boundary's retained rasterization
    * (its subtree's pixels at display scale, premultiplied, top-left origin,

package/gui/spatial.d.ts

@@ -97,16 +97,17 @@ declare module "flux:spatial" {
 
   export type ShapeId = number & { readonly __spatialShape: unique symbol }
 
-  /** One hit of raycast(), nearest first. `face`/`uv`/`normal` are present
-   * for nodes with a shape (uv only when the shape has UVs); a node with
-   * bounds but no shape reports its local box, distance and point only. */
+  /** One hit of raycast(), nearest first. `face`/`uv` are present for
+   * nodes with a shape (uv only when the shape has UVs); a node with
+   * bounds but no shape is its local box's twelve triangles, so its hit
+   * carries the struck face's normal and no face/uv. */
   export type Hit = {
     node: NodeId
     /** World units along the normalized ray. */
     distance: number
     point: [number, number, number]
     /** World-space geometric normal, facing the ray. */
-    normal?: [number, number, number]
+    normal: [number, number, number]
     /** Triangle index into the shape's index list. */
     face?: number
     uv?: [number, number]
@@ -116,6 +117,26 @@ declare module "flux:spatial" {
    * maxY, maxZ]. With one the node is in the picking index: its world box
    * follows the flush; hidden nodes stay in and are skipped at query time. */
   export function setBounds(node: NodeId, bounds: Float32Array | null): void
+  /**
+   * The clip volume gating every draw sink on `target`: its view-projection
+   * (Float32Array of 16, column-major), or null to lift it. An entry whose
+   * node box (grown by its cull margin) falls wholly outside reads
+   * instanceCount 0 like a hidden node, and comes back with a fresh params
+   * write. Nodes without a box, or with culling off, are never gated. Read
+   * at flush: set it before the flush that should see it.
+   */
+  export function setFrustum(target: TextureId, viewProj: Float32Array | null): void
+  /** Whether frustums gate the node's draw sinks (default true), and the
+   * world-unit margin the test grows its box by (default 0). */
+  export function setCull(node: NodeId, enabled: boolean, margin: number): void
+  /** A local box for culling ONLY - the node stays out of the picking
+   * index (setBounds is the indexed one). null falls back to its bounds. */
+  export function setCullBounds(node: NodeId, bounds: Float32Array | null): void
+  /** Cull the node by the union of these nodes' world boxes instead of
+   * its own (a skinned mesh by its joints): an empty list restores its
+   * own. Members without a box contribute nothing; with none at all the
+   * node is not culled. */
+  export function setCullGroup(node: NodeId, members: NodeId[]): void
   /**
    * Triangle data for the picking narrowphase, one copy shared by every
    * node that references it: positions read from an interleaved vertex
@@ -131,15 +152,48 @@ declare module "flux:spatial" {
    * direction need not be normalized; distances are world units. Reads
    * the index as of the last flush. */
   export function raycast(origin: Float32Array, direction: Float32Array): Hit[]
+  /** A query volume's layout for overlap/sweep: "capsule" is
+   * 7 floats (a, b, radius; a sphere when a == b), "box" is 10 (center,
+   * half extents, unit quaternion xyzw). */
+  export type VolumeKind = "capsule" | "box"
+  /** One node overlap() touches: its deepest contact - the point on
+   * the node's surface, the unit direction out of it, and the depth along
+   * that direction that clears the contact. */
+  export type Overlap = {
+    node: NodeId
+    point: [number, number, number]
+    normal: [number, number, number]
+    depth: number
+  }
+  /** One node sweep() touches: `time` is the fraction of the motion
+   * at first touch, `point` the touch point on the node's surface,
+   * `normal` the unit normal there facing the volume. */
+  export type Impact = {
+    node: NodeId
+    time: number
+    point: [number, number, number]
+    normal: [number, number, number]
+  }
+  /**
+   * Every shown node with bounds the volume touches, each with its
+   * deepest contact. A node with a shape is tested per triangle in world
+   * space, so it holds under any transform; a node without one is its
+   * local box's twelve triangles (a flat rect is four of them, so a
+   * rotated sprite tests exactly - the 2d marquee's box query is a "box"
+   * volume). Surfaces, not solids: a volume wholly inside a closed mesh
+   * with no triangle in reach touches nothing. Unordered; reads the index
+   * as of the last flush, like raycast.
+   */
+  export function overlap(kind: VolumeKind, volume: Float32Array): Overlap[]
   /**
-   * Every shown node with bounds whose local box, carried through its
-   * world transform, overlaps the world-axis box `bounds` (a Float32Array
-   * of 6: [minX, minY, minZ, maxX, maxY, maxZ]; touching counts, a point
-   * is min == max). Tested by separating axes, so a rotated flat rect -
-   * the 2d marquee case - tests exactly, never by its world AABB.
-   * Unordered; reads the index as of the last flush, like raycast.
+   * The volume moved by `motion` (a Float32Array of 3): every shown node
+   * with bounds it touches on the way, at its first touch, earliest
+   * first. A node already in contact reports time 0 while the motion
+   * closes in, and nothing while it leaves or slides along the contact;
+   * a zero motion touches nothing. Same testing and index contract as
+   * overlap.
    */
-  export function overlap(bounds: Float32Array): NodeId[]
+  export function sweep(kind: VolumeKind, volume: Float32Array, motion: Float32Array): Impact[]
 
   /**
    * Route the world DIRECTION of the node's local `vector` (a
@@ -150,14 +204,46 @@ declare module "flux:spatial" {
    * zeros. Every sink naming the same param shares one array (`len` must
    * agree); what the slots mean - light directions, an emitter axis - is
    * the caller's business, packed alongside its own non-spatial params.
-   * One slot sink per target, like bindDraw: rebinding on the same target
-   * replaces that sink (the abandoned slot zeroes), another target adds one.
+   * One slot sink per (target, name): rebinding the same param on the
+   * same target replaces that sink (the abandoned slot zeroes); another
+   * param or another target adds one, so a node may feed several arrays
+   * of one target (a spot light: its direction and its position).
    */
   export function bindDirectionSlot(node: NodeId, target: TextureId, name: string, len: number, index: number, vector: Float32Array): void
-  /** Remove the node's slot sink on `target`, or every slot sink without
+  /**
+   * Route the node's world POSITION into vec3 slot `index` of the
+   * `len`-float shared array param `name` on a draw target -
+   * bindDirectionSlot's translation sibling, with the same sharing,
+   * zeroing and per-(target, name) replacement rules. What a positional
+   * light's slot follows.
+   */
+  export function bindPositionSlot(node: NodeId, target: TextureId, name: string, len: number, index: number): void
+  /** Remove the node's slot sinks on `target`, or every slot sink without
    * one (the abandoned slots zero at the next flush). */
   export function unbindSlot(node: NodeId, target?: TextureId): void
 
+  /**
+   * Route the node's world matrix, post-multiplied by the constant `post`
+   * (a Float32Array of 16, column-major), into row `row` of a float
+   * texture: the flush writes the 16 floats as the row's four rgba32f
+   * texels - the matrix-palette channel a vertex shader `texelFetch`es
+   * (a skin binds each joint node with `post` its inverse bind). Writes
+   * batch: however many bound nodes moved, each flush uploads at most one
+   * whole palette per texture. With `anchor` - one node shared by every
+   * bind on the texture, and an ANCESTOR of every bound node - rows are
+   * anchor-local (`inverse(anchorWorld) * world * post`), so a model
+   * root's placement stays out of its own palette. Rows keep updating
+   * while nodes are hidden (visibility is the drawing entry's business),
+   * and an unbound or destroyed node's row keeps its last value. Validated
+   * at bind time: the texture must be an uploadable rgba32f texture 4
+   * texels wide with `row` inside it. Rebinding the same texture replaces
+   * the node's slot there; another texture adds one.
+   */
+  export function bindTextureSlot(node: NodeId, texture: TextureId, row: number, post: Float32Array, anchor?: NodeId): void
+  /** Remove the node's texture slot on `texture`, or every texture slot
+   * without one (abandoned rows keep their last value). */
+  export function unbindTextureSlot(node: NodeId, texture?: TextureId): void
+
   /**
    * Route the node's world pose to record slot `index` of vertex buffer
    * `buffer` used as an instance buffer: the flush writes the 5 floats
@@ -172,7 +258,23 @@ declare module "flux:spatial" {
    * Rebinding replaces the node's record sink; the abandoned slot zeroes.
    */
   export function bindPoseRecord(node: NodeId, buffer: BufferId, index: number): void
-  /** Remove the node's record sink (its slot zeroes at the next flush). */
+  /**
+   * Route the node's world matrix to record slot `index` of vertex buffer
+   * `buffer` as 16 floats (one column-major mat4) at float offset
+   * index * 16: the per-instance model matrix a vertex stage reads as
+   * four vec4 attributes. With `anchor` (an ANCESTOR of the node, one per
+   * buffer - every bind on the buffer names the same one) the record is
+   * the matrix RELATIVE to it, `inverse(anchorWorld) * world`, so a mesh's
+   * instances stay in the mesh's own space and its uModel still places
+   * the whole population (`uModel * instanceMatrix`); without one it is
+   * the plain world matrix. Batching, growth (retargetRecords) and
+   * rebinding as bindPoseRecord; a hidden, unbound or destroyed node's
+   * slot becomes a zero-scale matrix (w stays 1), so the instance
+   * collapses to a point and draws nothing. Every sink on one buffer
+   * shares one projection.
+   */
+  export function bindMatrixRecord(node: NodeId, buffer: BufferId, index: number, anchor?: NodeId): void
+  /** Remove the node's record sink (its slot hides at the next flush). */
   export function unbindRecord(node: NodeId): void
   /**
    * Move every record sink on buffer `old` to buffer `new`, slot indices
@@ -185,4 +287,83 @@ declare module "flux:spatial" {
    * when `new` already carries record sinks.
    */
   export function retargetRecords(old: BufferId, next: BufferId): void
+
+  /** A registered clip's handle (createClip). */
+  export type ClipId = number
+  /** A playing clip instance's handle (createPlayer). */
+  export type PlayerId = number
+
+  /**
+   * Register a baked animation clip: `duration` in seconds, `meta` four
+   * words per channel - [targetSlot, path (0 position, 1 rotation,
+   * 2 scale), interpolation (0 step, 1 linear, 2 cubic), keyCount] - and
+   * `times`/`values` every channel's key arrays concatenated in meta
+   * order (3 floats per key, 4 for rotation; cubic stores three elements
+   * per key: in-tangent, value, out-tangent, tangents per second - the
+   * glTF CUBICSPLINE layout). A clip is shared data: `targetSlot`
+   * indexes the target table each PLAYER supplies, so one clip drives
+   * any number of instances, and retargeting is a different table.
+   */
+  export function createClip(duration: number, meta: Uint32Array, times: Float32Array, values: Float32Array): ClipId
+  /** Free a clip. Players still on it drop at their next advance (a
+   * "dropped" spatialClipEnd). */
+  export function destroyClip(clip: ClipId): void
+  /**
+   * Start playing `clip`: `targets[slot]` is the node each channel
+   * animates - every target must be a live scene node (throws
+   * otherwise). Players advance on the frame clock BEFORE each frame's
+   * JS, sample and weight-blend every active player per (node, path) -
+   * two players on one node crossfade - and write the blended TRS into
+   * the arena, so frame handlers read and may overwrite freshly posed
+   * nodes (last write wins) and the frame's flush publishes the result.
+   * `speed` scales clip time (1 = as authored); `loop` wraps, else the
+   * player holds its final pose and reports once; `weight`/`fade` start
+   * the crossfade state (weight 0..1, fade = weight change per second -
+   * positive fades in, negative out; past 0 the player is removed).
+   * When a player finishes or is removed without finishing (faded out,
+   * clip or target destroyed), the "spatialClipEnd" engine event
+   * (srt:events) fires with payload { player, reason: "finished" |
+   * "dropped" }, before the same frame's handlers.
+   */
+  export function createPlayer(clip: ClipId, targets: NodeId[], speed: number, loop: boolean, weight: number, fade: number): PlayerId
+  /** Write the given fields of a player - the O(changes) crossfade
+   * channel. Setting `time` (seconds) also re-arms a finished player's
+   * end report. Throws on an id that already dropped. */
+  export function setPlayer(player: PlayerId, update: { weight?: number; fade?: number; speed?: number; time?: number }): void
+  /**
+   * Bind root motion to a player: `channel` of `clip` (a position channel
+   * - normally the ROOT track of the authored clip, while the player
+   * plays an in-place variant that holds the root still) is sampled at
+   * the player's time each advance, and its travel since the previous
+   * advance (continuous across a loop wrap, weighted by the player's
+   * weight) is reported as one "spatialRootMotion" engine event
+   * (srt:events) per advance, payload { player, x, y, z, yaw }, before
+   * the frame's handlers. The translation is given in the root's CURRENT
+   * facing (the clip's own turn so far undone), i.e. the character's
+   * local frame. `rotation`, a rotation channel of the same clip (the
+   * root's), adds the yaw half: the twist about `up`, in radians (zero
+   * without it). With an `anchor` the translation, rotated by the
+   * anchor's own rotation, is added to the anchor's position and the yaw
+   * turns the anchor about `up` in its own frame - Unity's
+   * applyRootMotion; without one it is Godot's root_motion_track, the
+   * app's to apply. `opts.up` is the root's parent-space up axis (default
+   * [0, 1, 0]); `opts.vertical: false` drops the component along it from
+   * the delta (the height stays in the pose). Binding primes at the
+   * player's current time, so the next advance already delivers. A
+   * second call rebinds. Throws on a dropped player, a wrong channel
+   * kind, a zero up axis, or a dead anchor.
+   */
+  export function bindRootMotion(player: PlayerId, clip: ClipId, channel: number, rotation?: number, anchor?: NodeId, opts?: { up?: [number, number, number]; vertical?: boolean }): void
+  /** Remove a player at once, holding whatever pose it last wrote (no
+   * event; stop-with-fade is a setPlayer fade write instead). A dropped
+   * id is fine. */
+  export function destroyPlayer(player: PlayerId): void
+  /**
+   * Fill `out` (a Float32Array of 10) with the node's CURRENT local
+   * transform - position xyz, quaternion xyzw, scale xyz - as the arena
+   * holds it, players' writes included. The pose read for root-motion
+   * strips and skeleton copies: JS-side mirrors of a node animated by a
+   * player go stale, this does not.
+   */
+  export function readTransform(node: NodeId, out: Float32Array): void
 }

package/index.d.ts

@@ -25,6 +25,7 @@
 /// <reference path="./standards/websocket.d.ts" />
 /// <reference path="./standards/abort.d.ts" />
 /// <reference path="./standards/crypto.d.ts" />
+/// <reference path="./standards/clipboard.d.ts" />
 
 // GUI capabilities (present only on a gui-enabled runtime). rendertree/camera/
 // microphone/gpu are flux:* modules like the rest; requestAnimationFrame stays a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.54",
+  "version": "0.0.56",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",

package/standards/clipboard.d.ts

@@ -0,0 +1,25 @@
+// navigator. The one navigator surface flux provides: the clipboard, text
+// only. Solidrt semantics on the standard shape: no permissions model and no
+// clipboard events - a single known app does not ask itself for permission.
+// GUI builds only (the clipboard belongs to the windowing platform); on a
+// headless flux there is no `navigator` at all, so
+// `typeof navigator !== "undefined"` is the availability check.
+
+interface Clipboard {
+  /**
+   * Resolves to the OS clipboard's text, "" when the clipboard is empty or
+   * holds no text. Rejects on platform failure.
+   */
+  readText(): Promise<string>
+  /**
+   * Replaces the OS clipboard's contents with `text`. Rejects on platform
+   * failure or a non-string argument.
+   */
+  writeText(text: string): Promise<void>
+}
+
+interface Navigator {
+  readonly clipboard: Clipboard
+}
+
+declare var navigator: Navigator