@solidrt/flux-types 0.0.57 → 0.0.59

package/gui/gpu.d.ts

@@ -422,14 +422,14 @@ declare module "flux:gpu" {
    * Pair a linked program with draw state, returning a render pipeline id
    * (its own id space, like programs and buffers - not a texture id): the
    * pipeline state object of every modern GPU API. The pipeline owns HOW its
-   * targets draw - `attributes` (the interleaved vertex layout; omit for
-   * attributeless rendering via gl_VertexID), `instanceAttributes` (the
-   * per-instance layout, fetched from each entry's `instanceBuffer` - see
-   * the option's doc), `topology`, `blend`, `cull`, `depth`, `depthWrite`
+   * targets draw - `buffers` (the layouts of the buffers its vertex stage
+   * reads, see {@link VertexBufferLayout}; omit for attributeless rendering
+   * via gl_VertexID), `topology`, `blend`, `cull`, `depth`, `depthWrite`
    * (`false` requires `depth: true`) - while each target brings its own
-   * size, buffers, uniforms, and clear. Both layouts share one attribute
-   * namespace (each name is one `in` of the vertex stage), so a name in
-   * both lists throws. Creating a pipeline compiles nothing, and many
+   * size, buffers, uniforms, and clear. Every attribute name across the
+   * layouts is one `in` of the vertex stage, so a name twice throws, and
+   * every `in` the program reads must appear in some layout with a format
+   * of its component count. Creating a pipeline compiles nothing, and many
    * pipelines may share one program. The vocabulary is validated here, so a
    * bad word throws at this call site. Free with
    * {@link destroyRenderPipeline}; the program is yours and outlives it.
@@ -437,26 +437,7 @@ declare module "flux:gpu" {
   export function createRenderPipeline(
     program: ProgramId,
     opts?: {
-      attributes?: VertexAttribute[]
-      /**
-       * One interleaved record per INSTANCE (WebGPU's `stepMode:
-       * "instance"`): these attributes read from the entry's
-       * `instanceBuffer` and advance per instance instead of per vertex, so
-       * every vertex of instance N sees record N - real per-instance state
-       * (offsets, colors, a packed transform) with no `gl_InstanceID`
-       * arithmetic. Declaring any makes `instanceBuffer` required on every
-       * entry drawn with this pipeline. A mat4 per instance is its four
-       * vec4 columns, reassembled in the shader (attributes have no matrix
-       * formats, as in WebGPU). Instance N always reads record N of the
-       * entry's buffer, from record 0 (ES 3.0 has no base instance), so
-       * several independently culled groups cannot share one buffer as
-       * sub-ranges: give each group its own `instanceBuffer` and entry, and
-       * cull it by `instanceCount`. Each attribute's `slot` (default 0)
-       * picks a buffer of the entry's `instanceBuffers` list (see
-       * {@link InstanceAttribute}); a pipeline using only slot 0 binds via
-       * the plain `instanceBuffer` key.
-       */
-      instanceAttributes?: InstanceAttribute[]
+      buffers?: VertexBufferLayout[]
       topology?: Topology
       blend?: BlendMode
       cull?: CullMode
@@ -477,19 +458,18 @@ declare module "flux:gpu" {
    * a texture id exactly like the fused creates do (drive uniforms
    * via the `params` prop or {@link setTargetParams}, resize with
    * {@link setTargetSize}, destroy with {@link destroyTexture}). Many targets
-   * may share one pipeline, and creating a target compiles nothing. `buffer`
-   * supplies the concrete vertex buffer the pipeline's attribute layout
-   * describes (required when the pipeline declares attributes), and
-   * `instanceBuffer` the per-instance records its `instanceAttributes`
-   * describe (required exactly when it declares any); the
-   * {@link DrawRange} keys pick what is drawn from them - `vertexCount`
-   * defaults to the rest of the buffer from `firstVertex` on,
-   * `instanceCount` to one instance per instance-buffer record (1 without
-   * one) - and a fetch past either buffer's end throws here. A fullscreen
+   * may share one pipeline, and creating a target compiles nothing.
+   * `buffers` supplies the concrete buffers the pipeline's layouts
+   * describe, one id per layout in declaration order (required exactly for
+   * the declared layouts); the {@link DrawRange} keys pick what is drawn
+   * from them - `vertexCount` defaults to the rest of the tightest
+   * vertex-step buffer from `firstVertex` on, `instanceCount` to one
+   * instance per record of the tightest instance-step buffer (1 without
+   * one) - and a fetch past any buffer's end throws here. A fullscreen
    * pass over an attributeless pipeline is `vertexCount: 3` with a
-   * covering-triangle vertex stage. Draw-state keys
-   * (`attributes`, `topology`, `blend`, `depth`, `depthWrite`) belong to the
-   * pipeline and throw here. `params` and `textures` are validated against
+   * covering-triangle vertex stage. Draw-state keys (`topology`, `blend`,
+   * `depth`, `depthWrite`) belong to the pipeline and throw here, and so
+   * does a layout object where a buffer id belongs. `params` and `textures` are validated against
    * the pipeline's program (see {@link ShaderParams}).
    *
    * `render: "manual"` opts the target out of runtime-driven rendering (see
@@ -528,11 +508,8 @@ declare module "flux:gpu" {
     params?: ShaderParams | null,
     opts?: {
       textures?: TextureBindings
-      buffer?: BufferId
-      instanceBuffer?: BufferId
-      /** One buffer per instance slot of the pipeline (index = the
-       * attributes' `slot`); pass this OR `instanceBuffer`, not both. */
-      instanceBuffers?: BufferId[]
+      /** One buffer id per layout of the pipeline, in declaration order. */
+      buffers?: BufferId[]
       /** Draw the instance records in key order (see {@link InstanceOrder}). */
       instanceOrder?: InstanceOrder
       clearColor?: [number, number, number, number]
@@ -551,13 +528,15 @@ declare module "flux:gpu" {
    */
   export function destroyProgram(id: ProgramId): void
   /**
-   * The vertex attributes a linked program actually reads (name and format),
-   * as the compiler left them: an `in` the vertex stage never uses is not
-   * listed, and a type no layout can feed (a matrix, an integer vector) is
-   * rejected at linkProgram. This is the list a pipeline over the program
-   * must cover between `attributes` and `instanceAttributes` - an uncovered
-   * or mis-formatted one throws at createRenderPipeline. Answered locally,
-   * no GPU round trip.
+   * The vertex attributes a linked program actually reads, as the compiler
+   * left them: an `in` the vertex stage never uses is not listed, and a
+   * type no layout can feed (a matrix) is rejected at linkProgram. The
+   * format is the 32-bit form of the family the shader declares
+   * (`float32`..`float32x4` for `float`/`vec*`, `uint32`.. for `uint`/
+   * `uvec*`, `sint32`.. for `int`/`ivec*`); a layout feeds it with any
+   * format of the same kind and component count. This is the list a
+   * pipeline over the program must cover across its buffer layouts.
+   * Answered locally, no GPU round trip.
    */
   export function programAttributes(program: ProgramId): VertexAttribute[]
   export type Topology = "points" | "lines" | "line-strip" | "triangles" | "triangle-strip"
@@ -605,39 +584,73 @@ declare module "flux:gpu" {
    */
   export type CullMode = "none" | "back" | "front"
   /**
-   * One float attribute of an interleaved record - a vertex of `attributes`
-   * or an instance record of `instanceAttributes`. The list's order defines
-   * the byte layout; locations are resolved by name against the vertex
+   * The byte format of one vertex attribute: WebGPU's spelling of the
+   * (component type, count, normalized) triple. Every format is a multiple
+   * of 4 bytes, so offsets and strides are 4-aligned by construction. A
+   * format feeds the shader `in` of its kind and component count, WebGPU's
+   * rule: the float and normalized formats feed a float `in` (`vec4`; the
+   * fetch converts, mapping `unorm`/`snorm` integers onto 0..1 / -1..1),
+   * the `uint*` formats an unsigned integer `in` (`uvec4`) and the `sint*`
+   * formats a signed one (`ivec4`), each exact at every width. A pipeline
+   * whose layout crosses kinds is refused at creation.
+   */
+  export type VertexFormat =
+    | "float32" | "float32x2" | "float32x3" | "float32x4"
+    | "float16x2" | "float16x4"
+    | "unorm8x4" | "snorm8x4"
+    | "unorm16x2" | "unorm16x4" | "snorm16x2" | "snorm16x4"
+    | "uint8x4" | "uint16x2" | "uint16x4"
+    | "uint32" | "uint32x2" | "uint32x3" | "uint32x4"
+    | "sint8x4" | "sint16x2" | "sint16x4"
+    | "sint32" | "sint32x2" | "sint32x3" | "sint32x4"
+  /**
+   * One attribute of a buffer layout: the vertex-stage `in` it feeds (by
+   * name), its byte format, and its byte offset within the record
+   * (`offset`, default: right after the previous attribute in list order,
+   * 0 for the first). Locations are resolved by name against the vertex
    * shader's `in` declarations.
    */
-  export type VertexAttribute = { name: string; format: "f32" | "vec2" | "vec3" | "vec4" }
+  export type VertexAttribute = { name: string; format: VertexFormat; offset?: number }
   /**
-   * One float attribute of a per-instance record. `slot` (default 0) picks
-   * which buffer of the entry's `instanceBuffers` list the attribute
-   * fetches from: attributes sharing a slot interleave into one record in
-   * list order, distinct slots are distinct buffers with their own strides
-   * - which is what lets two writers own instance data independently (a
-   * core-written pose buffer beside an app-written style buffer). Slots
-   * must be dense from 0, at most 4; a single-slot pipeline (every `slot`
-   * omitted) binds via the plain `instanceBuffer` key.
+   * The layout of one buffer a pipeline reads, WebGPU's
+   * `GPUVertexBufferLayout`: a record of `arrayStride` bytes (default: the
+   * attributes' byte sum, so a plain list is tightly interleaved in list
+   * order) fetched once per vertex (`stepMode: "vertex"`, the default) or
+   * once per INSTANCE (`"instance"`: every vertex of instance N reads
+   * record N - real per-instance state, offsets, colors, a packed
+   * transform, with no `gl_InstanceID` arithmetic; a mat4 per instance is
+   * its four vec4 columns, reassembled in the shader). An explicit
+   * `arrayStride` wider than the attributes lets a layout name only some
+   * fields of a record - a depth pass reading positions alone out of a
+   * full vertex record - and attributes the shader does not read are
+   * skipped over the stride. Strides and offsets are multiples of 4, an
+   * attribute stays inside its record, a pipeline declares at most 8
+   * layouts, and the entry binds exactly one buffer per layout, in the
+   * same order. Instance N always reads record N (ES 3.0 has no base
+   * instance), so several independently culled groups cannot share one
+   * instance buffer as sub-ranges: give each group its own buffer and
+   * entry, and cull it by `instanceCount`. Two instance-step buffers on
+   * one entry are how two writers own instance data independently (a
+   * core-written pose buffer beside an app-written style buffer).
    */
-  export type InstanceAttribute = VertexAttribute & { slot?: number }
+  export type VertexBufferLayout = { stepMode?: "vertex" | "instance"; arrayStride?: number; attributes: VertexAttribute[] }
   /**
    * A pipeline target's draw as data, WebGPU-style: `firstVertex` +
    * `vertexCount` pick the vertex range `[firstVertex, firstVertex +
    * vertexCount)` of the buffer, `instanceCount` draws that range as N
    * instances (`glDrawArraysInstanced`) told apart by `gl_InstanceID` (and
-   * by their `instanceAttributes` records, when the pipeline declares any).
+   * by their instance-step records, when the pipeline declares any).
    * All keys optional: at create, `firstVertex` defaults to 0, `vertexCount`
-   * to the rest of the buffer, and `instanceCount` to one instance per
-   * record of the entry's `instanceBuffer` - 1 without one, the plain draw;
+   * to the rest of the tightest vertex-step buffer, and `instanceCount` to
+   * one instance per record of the tightest instance-step buffer - 1
+   * without one, the plain draw;
    * in {@link setDraw}, absent keys keep their current value.
    * `instanceCount: 0` draws nothing - a cheap off switch. With an instance
    * buffer bound, `instanceCount` is bounds-checked against it like every
    * fetch (instances 0..N-1 each read one record). Two GL facts worth
    * knowing: `gl_VertexID` includes `firstVertex` (as in WebGPU), and
    * `gl_InstanceID` always counts from 0 - ES 3.0 has no base instance, so
-   * instance N reads record N of the entry's `instanceBuffer` and a group
+   * instance N reads record N of every instance-step buffer and a group
    * that is culled independently needs its own buffer and entry.
    */
   export type DrawRange = { firstVertex?: number; vertexCount?: number; instanceCount?: number }
@@ -672,27 +685,21 @@ declare module "flux:gpu" {
    */
   export type IndexRange = { firstIndex?: number; indexCount?: number; instanceCount?: number }
   /**
-   * A draw entry's buffer swap: each key present re-points that role of the
-   * entry at another {@link createBuffer} buffer, absent keys keep their
-   * current buffer. Replace-only - the roles an entry fills are pipeline
-   * layout state (`attributes` needs a `buffer`, `instanceAttributes` an
-   * `instanceBuffer`) and indexing is its draw vocabulary, so naming a role
-   * the entry does not fill throws; `indexBuffer` travels with
-   * `indexFormat` as at create. The entry's current range is kept and
-   * rechecked against the new buffers' sizes: a swap to a buffer too small
-   * for the live range throws (shrink the range first); a larger buffer
-   * never does. This is the growth primitive: a population outgrowing its
-   * instance buffer creates a larger one, writes it, swaps, and destroys
-   * the old (the entry holds the old buffer alive until the swap lands, so
-   * either order is safe). `instanceBuffer` swaps slot 0;
-   * `instanceBuffers` swaps every slot at once and must fill exactly the
-   * slots the entry fills (pass one spelling or the other).
+   * A draw entry's buffer swap: `buffers` re-points every declared layout
+   * at another {@link createBuffer} buffer (one id per layout, the full
+   * list, as at create), an `indexBuffer` + `indexFormat` pair re-points
+   * the index binding; absent keys keep their current buffers.
+   * Replace-only - which buffers an entry binds is pipeline layout state
+   * and indexing is its draw vocabulary, so a list that adds or drops a
+   * layout throws, as does an index pair on an unindexed entry. The
+   * entry's current range is kept and rechecked against the new buffers'
+   * sizes: a swap to a buffer too small for the live range throws (shrink
+   * the range first); a larger buffer never does. This is the growth
+   * primitive: a population outgrowing its instance buffer creates a
+   * larger one, writes it, swaps, and destroys the old (the entry holds
+   * the old buffer alive until the swap lands, so either order is safe).
    */
-  export type BufferUpdate = {
-    buffer?: BufferId
-    instanceBuffer?: BufferId
-    instanceBuffers?: BufferId[]
-  } & ({} | IndexBinding)
+  export type BufferUpdate = { buffers?: BufferId[] } & ({} | IndexBinding)
   /**
    * A draw entry's instance ORDER, declared at creation via the
    * `instanceOrder` option: the entry draws the records of its instance
@@ -728,33 +735,36 @@ declare module "flux:gpu" {
    * `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
+   * An entry with SEVERAL instance-step buffers orders them all under ONE
+   * permutation: the key reads from the key buffer's records (`buffer`,
+   * default the first instance-step layout), and every other instance-step
+   * buffer'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
+   * draw order. This retains a copy of each buffer'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.
+   * themselves in the same frame. An ordered buffer must be bound once on
+   * the entry (not as another layout's buffer nor as its index buffer) and
+   * ordered by no other entry; a buffer swap ({@link BufferUpdate})
+   * carries the order to the new buffers, every swapped instance-step
+   * buffer at once - republish app-written buffers 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.
+     * The pipeline buffer index (into its `buffers` layouts) whose
+     * records hold the key; default the first instance-step layout. With
+     * several instance-step buffers the key may live in any one of them -
+     * a core-written pose buffer keyed by position, or an app-written
+     * style buffer keyed by an explicit sort field - and every other one
+     * gathers under its permutation.
      */
-    slot?: number
+    buffer?: 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
+     * move). Core keeps a CPU copy of each buffer'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
@@ -785,16 +795,16 @@ declare module "flux:gpu" {
    * pipeline's own; app-driven uniforms are the source's own declarations).
    * 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. `attributes`
-   * describes one interleaved vertex in `buffer` (a {@link createBuffer} id);
-   * omit both for attributeless rendering via gl_VertexID.
-   * `instanceAttributes` describes one per-instance record in
-   * `instanceBuffer` (see {@link createRenderPipeline}; declare both or
-   * neither). The {@link DrawRange} keys pick what is drawn: `vertexCount`
-   * defaults to the rest of the buffer from `firstVertex` on,
-   * `instanceCount` draws the range as N instances told apart by
-   * `gl_InstanceID` and defaults to one per instance-buffer record; a fetch
-   * past either buffer's end throws. With
+   * (or fold the flip into its projection) to display up. `buffers` lists
+   * the layouts the vertex stage reads (see {@link VertexBufferLayout}),
+   * each naming the {@link createBuffer} id it reads as `buffer` - the
+   * fused create's spelling of what the split API declares on the pipeline
+   * and binds on the entry; omit it for attributeless rendering via
+   * gl_VertexID. The {@link DrawRange} keys pick what is drawn:
+   * `vertexCount` defaults to the rest of the tightest vertex-step buffer
+   * from `firstVertex` on, `instanceCount` draws the range as N instances
+   * told apart by `gl_InstanceID` and defaults to one per record of the
+   * tightest instance-step buffer; a fetch past any buffer's end throws. With
    * `depth: true` the pipeline gets a private depth buffer, cleared and tested
    * on every render; `depthWrite: false` (requires `depth: true`) keeps the
    * test but stops the draw from writing depth. `blend` sets the draw's own blending (see
@@ -817,14 +827,8 @@ declare module "flux:gpu" {
     params?: ShaderParams | null,
     opts?: {
       textures?: TextureBindings
-      attributes?: VertexAttribute[]
-      buffer?: BufferId
-      /** See {@link createRenderPipeline}'s `instanceAttributes`. */
-      instanceAttributes?: InstanceAttribute[]
-      instanceBuffer?: BufferId
-      /** One buffer per instance slot (index = the attributes' `slot`);
-       * pass this OR `instanceBuffer`, not both. */
-      instanceBuffers?: BufferId[]
+      /** The pipeline's layouts, each with the buffer it reads. */
+      buffers?: (VertexBufferLayout & { buffer: BufferId })[]
       /** Draw the instance records in key order (see {@link InstanceOrder}). */
       instanceOrder?: InstanceOrder
       topology?: Topology
@@ -1076,9 +1080,10 @@ declare module "flux:gpu" {
    * {@link setDrawOrder}. An {@link IndexBinding} makes the entry draw
    * indexed - real meshes share most vertices, and indexing stores and
    * shades each one once - with the range in {@link IndexRange} spelling.
-   * `instanceBuffer` supplies the per-instance records the pipeline's
-   * `instanceAttributes` describe (required exactly when it declares any);
-   * `instanceCount` then defaults to one instance per record.
+   * `buffers` binds one buffer per layout the pipeline declares, in
+   * declaration order (required exactly for the declared layouts); with an
+   * instance-step layout bound, `instanceCount` defaults to one instance
+   * per record.
    *
    * Seed every uniform the entry's program declares - here, via the
    * target's shared params, or with a later write. GL uniform state lives
@@ -1094,11 +1099,8 @@ declare module "flux:gpu" {
     params?: ShaderParams | null,
     opts?: {
       textures?: TextureBindings
-      buffer?: BufferId
-      instanceBuffer?: BufferId
-      /** One buffer per instance slot of the pipeline (index = the
-       * attributes' `slot`); pass this OR `instanceBuffer`, not both. */
-      instanceBuffers?: BufferId[]
+      /** One buffer id per layout of the pipeline, in declaration order. */
+      buffers?: BufferId[]
       /** Draw the instance records in key order (see {@link InstanceOrder}). */
       instanceOrder?: InstanceOrder
       before?: DrawId

package/gui/spatial.d.ts

@@ -18,9 +18,43 @@ declare module "flux:spatial" {
 
   /** A new root node. `visible: false` hides the node's whole subtree. */
   export function createNode(transform: Float32Array, visible: boolean): NodeId
-  /** Free a node; its children become roots. A bound sink is dropped
-   * without a write (removing the entry is the caller's job). */
+  /** Free a node NOW, exit or no exit; its children become roots, except
+   * leaving ones (exitNode), which go with it. A bound sink is dropped
+   * without a write (removing the entry is the caller's job). On a leaving
+   * node this is the cancel: it frees where it stands and still reports
+   * through "spatialNodeFreed". */
   export function destroyNode(node: NodeId): void
+  /**
+   * Let go of a node the way its declaration says (the removal every
+   * consumer's destroy verb rides on): each component with an `exit`
+   * animates from where it is now to that value on the exit's own motion,
+   * and the node is LEAVING meanwhile - still drawn and flushed, invisible
+   * to raycast/overlap/sweep/moveAndSlide and every pick built on them,
+   * refused by setParent on either side - until its exit tracks settle and
+   * no leaving child remains under it, when it frees and one
+   * "spatialNodeFreed" engine event (payload `{ node }`) reports it.
+   * Children let go of first are those leaving children, so a subtree
+   * torn down children-first frees root-last with each corpse in its
+   * parent's frame to the end. Returns whether the node is now leaving:
+   * with nothing to animate (no exit declared, every exit value already
+   * held, nothing leaving below) it frees at once and returns false, so
+   * the caller cleans up synchronously and no event follows. No
+   * "spatialTransitionEnd" fires for an exit track; a second exitNode on
+   * a leaving node changes nothing.
+   */
+  export function exitNode(node: NodeId): boolean
+  /**
+   * The node's lifecycle state, for probing: whether it is leaving, its
+   * effective visibility as of the last flush, and the motion in force
+   * per component - one entry per running track or held write, `to` the
+   * target lanes, `heldUntil` the animation-clock ms a held write applies
+   * at (null for a running track).
+   */
+  export function describeNode(node: NodeId): {
+    leaving: boolean
+    shown: boolean
+    motion: { component: NodeComponent; to: number[]; heldUntil: number | null }[]
+  }
   /** Re-parent (null = make a root). Throws on a cycle. */
   export function setParent(node: NodeId, parent: NodeId | null): void
   /** Replace the local transform (compare before calling; an unchanged
@@ -29,25 +63,81 @@ declare module "flux:spatial" {
    * (last write wins - the producer rule). */
   export function setTransform(node: NodeId, transform: Float32Array): void
   /**
-   * One node-transition spec, the element `transition` vocabulary minus
-   * the lifecycle conveniences: `{ duration }` / `{ duration, bounce }`
-   * is a spring (the default kind; retargets keep position and velocity,
-   * rotation springs keep angular velocity along the geodesic),
-   * `{ duration, curve }` a tween (rotation tweens slerp the geodesic;
-   * retargets restart from the current value), or the shorthand string
-   * `"<duration>ms [curve]"`. Durations in ms; no delay, from or exit.
+   * One node-transition spec, the element `transition` vocabulary whole
+   * minus stagger: `{ duration }` / `{ duration, bounce }` is a spring
+   * (the default kind; retargets keep position and velocity, rotation
+   * springs keep angular velocity along the geodesic), `{ duration, curve }`
+   * a tween (rotation tweens slerp the geodesic; retargets restart from
+   * the current value), or the shorthand string
+   * `"<duration>ms [curve] [<delay>ms]"`. Durations and delays in ms; a
+   * `delay` holds every write to the component that long on the animation
+   * clock before it applies, and a held write that starts late (a hitch)
+   * runs as if started on time.
+   *
+   * `from` and `exit` on a component entry (not on `all`) are its
+   * lifecycle endpoints, in the lanes of the component - position and
+   * scale `[x, y, z]`, rotation a quaternion `[x, y, z, w]`, weights one
+   * number per morph target - each a bare lane array (the entry's motion)
+   * or the endpoint object
+   * `{ value, duration?, curve?, bounce?, delay? }` owning its direction's
+   * motion (a field left out is the entry's; naming a curve or a bounce
+   * decides the kind outright). `from` is the enter value: the node starts
+   * there and animates to the transform it holds at its first frame - its
+   * created transform, or the target of a write made in the creating
+   * tick; an enter plays once per node, at creation, so the declaration
+   * must be set in the creating tick (a later one animates writes only).
+   * `exit` is where the component animates to when exitNode lets go of
+   * the node.
    */
+  export type NodeEndpoint = {
+    value: number[]
+    duration?: number
+    curve?: "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | [number, number, number, number]
+    bounce?: number
+    delay?: number
+  }
   export type NodeTransitionSpec =
-    | { duration: number; bounce?: number }
-    | { duration: number; curve: "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | [number, number, number, number] }
+    | { duration: number; bounce?: number; delay?: number; from?: number[] | NodeEndpoint; exit?: number[] | NodeEndpoint }
+    | {
+        duration: number
+        curve: "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | [number, number, number, number]
+        delay?: number
+        from?: number[] | NodeEndpoint
+        exit?: number[] | NodeEndpoint
+      }
+    | string
+  /** A motion alone - a spec without lifecycle endpoints: what `all` and
+   * a one-off motion on a write (writeWeights) take. */
+  export type NodeMotionSpec =
+    | { duration: number; bounce?: number; delay?: number }
+    | {
+        duration: number
+        curve: "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | [number, number, number, number]
+        delay?: number
+      }
     | string
-  /** The declaration setTransition takes: a spec per transform component
-   * plus `all` as a catch-all (per-component entries win). */
+  /** The registers a node transition animates: the local TRS components
+   * (writeTransform) and the weights register (writeWeights). */
+  export type NodeComponent = "position" | "rotation" | "scale" | "weights"
+  /** The declaration setTransition takes: a spec per node component
+   * (the TRS components and `weights`, the morph target weights
+   * register) plus `all` as a catch-all (per-component entries win). `stagger`
+   * (ms) makes the node a stagger group: every descendant enter (`from`)
+   * or exit that begins in the same frame under it gets `index * stagger`
+   * of extra delay, indexed in occurrence order - creation order for
+   * enters, TREE order (children order, depth first) for exits whatever
+   * order the exits were let go of in, so a cascade out reads like the
+   * cascade in; enters and exits count separately. The nearest declaring
+   * ancestor wins, nested groups never compound, and it orchestrates
+   * descendants only: the node's own lifecycle is staggered by ITS
+   * ancestors, and ordinary writes never stagger. */
   export interface NodeTransition {
     position?: NodeTransitionSpec
     rotation?: NodeTransitionSpec
     scale?: NodeTransitionSpec
-    all?: NodeTransitionSpec
+    weights?: NodeTransitionSpec
+    all?: NodeMotionSpec
+    stagger?: number
   }
   /**
    * Declare (or with null clear) the node's transitions: with a config
@@ -63,15 +153,18 @@ declare module "flux:spatial" {
    * target), an undeclared one snaps. Without a declaration this is
    * setTransform. A component matching its running track's target is
    * left alone, so rewriting the whole array to move one component never
-   * restarts the others. Each settled component fires one
+   * restarts the others (a held write's target counts, so re-sending it
+   * does not restart its delay). Each settled component fires one
    * "spatialTransitionEnd" engine event (srt:events), payload
-   * `{ node, component: "position" | "rotation" | "scale" }`.
+   * `{ node, component: NodeComponent }` - on a live node; a leaving
+   * node's settles feed its free instead (exitNode).
    */
   export function writeTransform(node: NodeId, transform: Float32Array): void
   export function setVisible(node: NodeId, visible: boolean): void
   /**
    * Route the node's world matrix to one draw entry's `uModel` (and
-   * `uNormal`, the inverse-transpose, when `normal`). Validated like
+   * `uNormal`, the inverse-transpose, when `normal`; and with `fade` the
+   * LOD cross-fade band into `uLodFade`, see setLod). Validated like
    * setDrawParams: the entry must exist and declare those uniforms. The
    * entry is assumed switched off (instanceCount 0); the next flush turns it
    * on with `count` when the node is shown, and off again when hidden.
@@ -79,7 +172,7 @@ declare module "flux:spatial" {
    * into replaces that sink, binding on another target adds one - a mesh
    * drawn by a scene and by each of its views is one node with one flush.
    */
-  export function bindDraw(node: NodeId, target: TextureId, draw: DrawId, normal: boolean, count: number): void
+  export function bindDraw(node: NodeId, target: TextureId, draw: DrawId, normal: boolean, count: number, fade: boolean): void
   /** Remove the node's draw sink on `target`, or every draw sink without
    * one. Issues no write: the entries are the caller's to remove. */
   export function unbindDraw(node: NodeId, target?: TextureId): void
@@ -113,8 +206,9 @@ declare module "flux:spatial" {
     uv?: [number, number]
   }
 
-  /** Set (null clears) the node's LOCAL tight box [minX, minY, minZ, maxX,
-   * maxY, maxZ]. With one the node is in the picking index: its world box
+  /** Set (null clears) the LOCAL tight box [minX, minY, minZ, maxX, maxY,
+   * maxZ] of a node without a shape (a shaped node's box is its shape's:
+   * throws). 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
   /**
@@ -137,16 +231,82 @@ declare module "flux:spatial" {
    * own. Members without a box contribute nothing; with none at all the
    * node is not culled. */
   export function setCullGroup(node: NodeId, members: NodeId[]): void
+  /** One level of a LOD group (setLod): the node drawn at this level (a
+   * direct child of the group), absent for a population level (the
+   * instance nodes under the group carry one record buffer per level,
+   * bindMatrixRecord's list), and `size` - the projected size (the group's
+   * bounding sphere's diameter as a fraction of the viewport height) below
+   * which the level hands over to the next. */
+  export type LodLevel = { node?: NodeId; size: number }
+  /**
+   * Make the node a LOD group (an empty list makes it plain again):
+   * `levels` nearest first with strictly descending sizes, all naming a
+   * child or none at all (never mixed); the last level's size is the cull
+   * threshold, 0 for never culled. After the walk each flush measures the
+   * group on every target with a LOD view (setLodView) - the sphere
+   * around its own box, else around its levels' world boxes - and gates
+   * the draw sinks under each level to the level that target picked, so
+   * a thousand groups cost no JS per frame. `fade` widens each threshold
+   * `s` into a cross-fade band `[s, s * (1 + fade))` in which both levels
+   * draw with complementary screen-hash dithers (entries bound with
+   * bindDraw's `fade`; others switch hard at the band's midpoint); 0 is a
+   * hard switch with a one-sided hysteresis band, so a boundary never
+   * flickers. `reference` is the target population levels measure by
+   * (records are target-agnostic); node levels measure per target. A
+   * nested group chains: a node draws only where every group above it
+   * picked its level. A target with no LOD view draws the first level.
+   */
+  export function setLod(node: NodeId, levels: LodLevel[], fade: number, reference?: TextureId): void
+  /**
+   * What `target` measures projected size with: a Float32Array of 6 - the
+   * eye position xyz, the projection's vertical focal factor (the
+   * magnitude of `proj[5]`: `1 / tan(fov / 2)` for a perspective
+   * projection, `2 / (top - bottom)` for an orthographic one - positive,
+   * whatever clip flip the projection bakes in), 1 for orthographic else
+   * 0, and a bias every
+   * measured size is multiplied by (below 1 switches sooner) - or null to
+   * lift it. Read at flush, like setFrustum; set it beside the frustum on
+   * every camera move.
+   */
+  export function setLodView(target: TextureId, view: Float32Array | null): void
+  /**
+   * A geometry's positions as the core keeps them, one copy shared by
+   * every node that references it: the source of those nodes' local
+   * boxes, and the picking narrowphase's triangles when `indices` (a
+   * Uint16Array/Uint32Array triangle list) is given - without it the
+   * shape only gives its box. Positions are read from an interleaved
+   * vertex array (`stride` floats per vertex, xyz at `posOffset`, uv at
+   * `uvOffset`, -1 for none). Throws on out-of-range indices.
+   */
+  export function createShape(vertices: Float32Array, stride: number, posOffset: number, uvOffset: number, indices?: Uint16Array | Uint32Array): ShapeId
+  /**
+   * Rewrite the shape's vertices from `first` on with those in
+   * `vertices`, laid out as for createShape (uvs exactly when the shape
+   * has them). The box follows at the next flush on every node carrying
+   * the shape; the triangle index is rebuilt by the next query. Throws
+   * when the range runs past the shape's vertices.
+   */
+  export function updateShape(shape: ShapeId, vertices: Float32Array, stride: number, posOffset: number, uvOffset: number, first: number): void
+  /** One channel of an interleaved float vertex array: `stride` floats
+   * per vertex, the channel's floats at `offset` within each. */
+  export type VertexChannel = { data: Float32Array; stride: number; offset: number }
   /**
-   * Triangle data for the picking narrowphase, one copy shared by every
-   * node that references it: positions read from an interleaved vertex
-   * array (`stride` floats per vertex, xyz at `posOffset`, uv at
-   * `uvOffset`, -1 for none) and a Uint16Array/Uint32Array triangle list.
-   * Throws on out-of-range indices.
+   * Recompute vertex normals in place from a triangle list (a
+   * Uint16Array/Uint32Array): positions are read from the `positions`
+   * channel and unit normals written into the `normals` channel (its
+   * `data` may be the same array when the layout interleaves them). Each
+   * vertex sums the normals of the faces that name it, weighted by the
+   * corner angle, so the result does not depend on how a surface was
+   * triangulated; a vertex no face names gets zero. Throws on an index
+   * past the last vertex or an offset outside its stride.
    */
-  export function createShape(vertices: Float32Array, stride: number, posOffset: number, uvOffset: number, indices: Uint16Array | Uint32Array): ShapeId
-  /** Free a shape; nodes still referencing it fall back to their box. */
+  export function computeNormals(positions: VertexChannel, normals: VertexChannel, indices: Uint16Array | Uint32Array): void
+  /** Free a shape; nodes still referencing it keep their last box and
+   * fall back to it. */
   export function destroyShape(shape: ShapeId): void
+  /** Give the node a shape (null takes it away): its box is the shape's
+   * from here on, and setBounds is refused. A shape with no vertices
+   * leaves the node without a box. */
   export function setShape(node: NodeId, shape: ShapeId | null): void
   /** The node's layer membership bitmask (default 1), what a query's
    * `layers` mask is tested against. Query-only: needs no flush. */
@@ -156,12 +316,15 @@ declare module "flux:spatial" {
    * optional: `root` admits only the nodes under it (the caller's own
    * subtree in the arena every scene and layer shares), `layers` only
    * nodes whose mask intersects it (a node's mask of 0 then never
-   * reports), `nodes` only the listed ones. A dead root throws.
+   * reports), `nodes` only the listed ones, `target` only the LOD levels
+   * that draw target picks (setLod; without it every level reports). A
+   * dead root throws.
    */
   export type QueryFilter = {
     root?: NodeId
     layers?: number
     nodes?: NodeId[]
+    target?: TextureId
   }
   /** Every shown node with bounds the ray strikes, nearest first. The
    * direction need not be normalized; distances are world units. Reads
@@ -291,6 +454,46 @@ declare module "flux:spatial" {
   /** 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
+  /**
+   * Bind the node's WEIGHTS register (setWeights - a mesh's morph target
+   * weights) to row `row` of `texture`: four weights per texel across the
+   * texture's width, the register padded with zeros to the row (or cut
+   * to it), one whole-texture upload per texture per flush like a
+   * palette. Weights rows stage from the register, not the transform
+   * walk, so a weights write costs no matrix recompute. A texture holds
+   * one row kind - matrix rows (bindTextureSlot) or weights rows - never
+   * both. Validated at bind time: an uploadable rgba32f texture with
+   * `row` inside it. Rebinding the same texture replaces the node's slot
+   * there; another texture adds one.
+   */
+  export function bindWeightsSlot(node: NodeId, texture: TextureId, row: number): void
+  /** Remove the node's weights slot on `texture`, or every weights slot
+   * without one (abandoned rows keep their last value). */
+  export function unbindWeightsSlot(node: NodeId, texture?: TextureId): void
+  /** Write the node's weights register, any length; an equal write is
+   * free. Published through its weights slots at the next flush. Never
+   * consults or cancels a weights track (setTransform's rule): a running
+   * track overwrites it at the next frame. */
+  export function setWeights(node: NodeId, weights: Float32Array): void
+  /**
+   * Write the weights register THROUGH a motion, the writeTransform of
+   * the weights lane: with `transition` (a motion spec, the `all`
+   * vocabulary: `{ duration, bounce? | curve, delay? }` or a shorthand
+   * string) the write animates on it whatever the node declares - a
+   * one-off motion for this write; without one the declaration's
+   * `weights` entry (or `all`) decides, and with neither the write snaps
+   * like setWeights. One lane per target: a write shorter or longer than
+   * the register widens the track to the longer of the two, the missing
+   * lanes at zero. A write matching the running track's target is left
+   * alone (a tween never restarts on a re-send); each settle fires one
+   * "spatialTransitionEnd" with component "weights". The clip players
+   * write the same register (a weights channel, path code 3): both are
+   * producers, last write wins at each frame.
+   */
+  export function writeWeights(node: NodeId, weights: Float32Array, transition?: NodeMotionSpec | null): void
+  /** Fill `out` from the node's weights register as the arena holds it
+   * (zeros past the register's length) and return the register's length. */
+  export function readWeights(node: NodeId, out: Float32Array): number
 
   /**
    * Route the node's world pose to record slot `index` of vertex buffer
@@ -319,9 +522,13 @@ declare module "flux:spatial" {
    * 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.
+   * shares one projection. `buffers` names one buffer per LOD level of
+   * the anchor's group (setLod with population levels), slot `index` in
+   * each: the flush stages the record into the level the node's own
+   * projected size picks on the group's reference target and the hidden
+   * record into the others; one buffer is the plain population.
    */
-  export function bindMatrixRecord(node: NodeId, buffer: BufferId, index: number, anchor?: NodeId): void
+  export function bindMatrixRecord(node: NodeId, buffers: 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
   /**
@@ -342,13 +549,17 @@ declare module "flux:spatial" {
   export type PlayerId = number
 
   /**
-   * Register a baked animation clip: `duration` in seconds, `meta` four
+   * Register a baked animation clip: `duration` in seconds, `meta` five
    * 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`
+   * 2 scale, 3 weights), interpolation (0 step, 1 linear, 2 cubic),
+   * keyCount, elements] - and `times`/`values` every channel's key arrays
+   * concatenated in meta order (`elements` floats per key: 3 for position
+   * and scale, 4 for rotation, one per morph target for weights - the
+   * TRS counts are checked; cubic stores three elements per key:
+   * in-tangent, value, out-tangent, tangents per second - the glTF
+   * CUBICSPLINE layout). A weights channel writes the target node's
+   * weights register (setWeights), blended across players like a TRS
+   * path. 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.
    */

package/gui/video.d.ts

@@ -36,13 +36,14 @@ declare module "flux:video" {
   }
 
   /**
-   * Open a video file (MP4 with H.264 video; AAC audio plays, other audio
-   * tracks are ignored). The path resolves like file() paths (through the
-   * app's assets in a packed app). Playback starts paused; call `play()`.
-   * Rejects when the file is unreadable or its codec unsupported.
+   * Open a video file (MP4 with 8-bit 4:2:0 VP9 video, i.e. profile 0;
+   * AAC audio plays, other audio tracks are ignored). The path resolves
+   * like file() paths (through the app's assets in a packed app). Playback
+   * starts paused; call `play()`. Rejects when the file is unreadable or
+   * its codec unsupported.
    *
-   * The built-in software decoder does not decode B-frames; encode dev
-   * content with `-bf 0` until the platform hardware decoders land.
+   * Encode with `ffmpeg -c:v libvpx-vp9 -c:a aac out.mp4`; VP9 is
+   * royalty-free, so the decoder ships on every platform.
    */
   export function open(path: string): Promise<VideoPlayer>
 }

package/modules/fs.d.ts

@@ -99,4 +99,14 @@ declare module "flux:fs" {
    * @param path  Path to a file or directory.
    */
   export function realpath(path: string): Promise<string>
+  /**
+   * Move a file or directory from `from` to `to`. The OS rename: an existing
+   * target is replaced, a missing source rejects (nothing moved), and a move
+   * across filesystems rejects rather than falling back to a copy. Parent
+   * directories of `to` are not created.
+   *
+   * @param from  Path of the file or directory to move.
+   * @param to    Path it should have afterwards.
+   */
+  export function rename(from: string, to: string): Promise<void>
 }

package/package.json

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