shaders 2.5.135 → 3.0.436

package/dist/core/gpu/contract.d.ts

@@ -0,0 +1,508 @@
+import { TgpuBindGroupLayout } from 'typegpu';
+import { WgslStruct, AnyWgslData } from 'typegpu/data';
+import { MaskType, NodeMetadata, BoundingBoxDeclaration, ComponentProps, PropConfig, CleanupCallback, RenderCallback, ResizeCallback, BlendMode } from '../types';
+
+/** The context threaded through `Expr.emit` — implemented by the composer's serialiser. */
+export interface EmitContext {
+    /**
+     * Register an external (a `TgpuFn`, a bind-group layout, or a plain resolvable) and
+     * return the STABLE identifier to reference it by in the WGSL template. Identical
+     * externals (same object) dedupe to the same name, so a blend fn used 20 times is
+     * declared once. `hint` seeds a readable name.
+     */
+    external(value: unknown, hint: string): string;
+    /** Append a statement to the current fragment body's preamble (driver-override locals). */
+    statement(wgsl: string): void;
+    /** A fresh unique local-variable name (driver-override copies, RTT sample temporaries). */
+    freshLocal(hint: string): string;
+    /**
+     * Run `factory` at most once per `key` within this fragment and cache its result. Used
+     * for driver-override locals: the first reference to a driver-overridden node's `props`
+     * declares `var p = …; p.field = …;` and subsequent references reuse `p`.
+     */
+    memo(key: string, factory: () => string): string;
+}
+/**
+ * A GPU-side expression. The composer's currency. Immutable;
+ * the fluent helpers return new `Expr`s. `emit` is package-internal — shader code only ever
+ * constructs `Expr`s via the factories in `composer.ts` (`expr`, `call`, `vec4`, …) and the
+ * `params` handed to `fragment`.
+ */
+export declare class Expr {
+    /** @internal */
+    readonly _emit: (ctx: EmitContext) => string;
+    constructor(emit: (ctx: EmitContext) => string);
+    /** `expr.<prop>` — member/swizzle access (`.rgb`, `.a`, `.xyz`, `.x`, or a struct field). */
+    member(prop: string): Expr;
+    /** `expr * other` — scalar/vector multiply (WGSL infix; both operands parenthesised). */
+    mul(other: Expr | number): Expr;
+    /** `expr + other`. */
+    add(other: Expr | number): Expr;
+}
+/** True when a value is a KitExpr. */
+export declare function isExpr(value: unknown): value is Expr;
+/** WGSL float literal — always with a decimal so it types as f32, never i32. */
+export declare function formatFloat(n: number): string;
+/** A texture handle the composer/shaders sample. Backed by a texture bind-group entry. */
+export interface KitTexture {
+    /** The bind-group layout entry key (e.g. `rtt_0`, `media_2`, `video_0`). */
+    readonly key: string;
+    /**
+     * A texture sample at the given UV. For a regular sampled texture this is
+     * `textureSample(tex.$.<key>, samp.$.<sampler>, uv)`; for an external (video/webcam)
+     * texture it is `textureSampleBaseClampToEdge(ext.$.<key>, samp.$.<sampler>, uv)` (the
+     * only sampling builtin external textures support — clamp-to-edge is implicit).
+     */
+    sample(uv: Expr, sampler?: SharedSamplerName): Expr;
+    /** The raw accessor expression (`tex.$.<key>` / `ext.$.<key>`) for shader-body fn args. */
+    accessor(): Expr;
+    /**
+     * The texture's pixel dimensions as a `vec2f` Expr (`vec2f(textureDimensions(<accessor>))`).
+     * For external textures this is the CURRENT video frame's size, read on the GPU every frame
+     * (no CPU-tracked `videoWidth`/`videoHeight` uniforms needed).
+     */
+    dimensions(): Expr;
+}
+/** The four shared samplers the kit exposes (kit-owned fixed sampler layout). */
+export type SharedSamplerName = 'linearClamp' | 'nearestClamp' | 'linearRepeat' | 'nearestRepeat';
+/**
+ * The resolved remap window of a map-driven prop (post dynamic-bound resolution) — the same
+ * five values the fragment path reads from the `_map_<prop>_*` synthetic uniforms. `window()` on a
+ * `GpuMapInfo` re-reads this each call so a per-frame change (e.g. a resized px-unit output bound)
+ * is reflected without a recompose.
+ */
+export interface GpuMapWindow {
+    inputMin: number;
+    inputMax: number;
+    outputMin: number;
+    outputMax: number;
+    curve: number;
+}
+/**
+ * The "compute-map interplay" handle — everything a COMPUTE hook needs to reproduce the
+ * fragment path's map resolve (sample the map source → extract the channel → remap) for a
+ * map-driven prop, per compute pixel. Obtained via `GpuFragmentParams.getMapInfo(prop)`; returns
+ * null when `prop` has no active `type:'map'` driver.
+ */
+export interface GpuMapInfo {
+    /**
+     * The map SOURCE rendered to an RTT boundary, as a KitTexture. Bind it LATE inside the compute
+     * node's `bindInputs` by resolving `sourceTexture.key` (exactly like the child RTT — the pass
+     * manager allocates it after composition), then feed the bound texture to the fill kernel.
+     */
+    sourceTexture: KitTexture;
+    /** Channel to extract as the driving scalar ('luminance'|'luminanceInverted'|'alpha'|'alphaInverted'). */
+    channel: string;
+    /** The live resolved remap window (re-read each call). Matches the fragment `_map_<prop>_*` uniforms. */
+    window(): GpuMapWindow;
+}
+/** Options for a shader-owned media texture (image/canvas/DOM upload target). */
+export interface GpuMediaTextureOptions {
+    width: number;
+    height: number;
+    /** Base (linear) format. Default `rgba8unorm`. */
+    format?: GPUTextureFormat;
+    /** Add an `-srgb` viewFormat + expose `createSrgbView()` (rarely needed — decode in-shader). */
+    srgb?: boolean;
+    mipLevelCount?: number;
+    label?: string;
+}
+/**
+ * Options for a shader-owned DATA texture — a fixed-size GPU texture uploaded from a raw
+ * CPU `ArrayBufferView` (via `device.queue.writeTexture`, NOT `copyExternalImageToTexture`), for
+ * float fields the shader computes/loads rather than image content. The SVG-SDF samplers use this
+ * (an `r16float`/`r32float` field loaded from a `.bin`). Distinct from a media texture only in the
+ * upload path + the float-only `format`; the returned handle is the same `GpuMediaTexture` shape.
+ */
+export interface GpuDataTextureOptions {
+    width: number;
+    height: number;
+    /**
+     * `r16float` (single-channel, always linear-filterable) or `r32float` (needs `float32-filterable`),
+     * or `rgba16float` for a filterable multi-channel field texture (ChromaFlow's flow+density,
+     * PixelThrow's 2D displacement) — half-encode each texel with kit `toHalfFloat` before upload.
+     */
+    format: 'r16float' | 'r32float' | 'rgba16float';
+    /** Optional initial pixel data. */
+    data?: ArrayBufferView;
+    label?: string;
+}
+/**
+ * A shader-owned media texture: a fixed-size GPU texture the shader uploads image/canvas/video-frame
+ * content into (`write`), and whose raw `GPUTexture` it can reach (`unwrap`, for DOMTexture's
+ * `queue.copyElementImageToTexture`). Media textures are STATIC-sized — to change the size (a new
+ * image at its native resolution, a re-rastered text run, a resized DOM capture) create a NEW one and
+ * point the registered getter at it (see `registerMediaTexture`); the pass manager rebuilds the
+ * sampling pass's bind group when it sees the backing texture change (no recompose).
+ */
+export interface GpuMediaTexture {
+    /** The underlying TypeGPU texture — pass to `registerMediaTexture`'s getter / bind path. */
+    readonly texture: unknown;
+    readonly width: number;
+    readonly height: number;
+    /** Upload pixel content (an ImageBitmap / HTMLCanvasElement / ImageData / TypedArray). */
+    write(source: unknown): void;
+    /** The raw `GPUTexture` (for `queue.copyElementImageToTexture`). */
+    unwrap(): GPUTexture;
+    /** Destroy the GPU texture (WebGPU keeps it alive for already-submitted frames). */
+    destroy(): void;
+}
+/** System/context accessors a fragment builder reads (the `_sys` block + the uv varying). */
+export interface KitCtx {
+    /** The fullscreen-pass UV varying (`in.uv`), Y-orientation resolved once by the composer. */
+    readonly uv: Expr;
+    /** `_sys.time` — CPU-accumulated seconds. */
+    readonly time: Expr;
+    /** `_sys.viewportSize` — device-pixel backing-buffer size (vec2f). */
+    readonly viewportSize: Expr;
+    /** `_sys.logicalViewportSize` — CSS-pixel authored-frame size (vec2f). */
+    readonly logicalViewportSize: Expr;
+    /** `_sys.aspect` — width / height. */
+    readonly aspect: Expr;
+    /** `_sys.pointer` — pointer position in UV space (vec2f). */
+    readonly pointer: Expr;
+}
+/**
+ * Params passed to a fragment builder. The builder runs at COMPOSITION time and returns a
+ * `KitExpr` — inside it authors call their pre-transpiled `'use gpu'` fns, wiring
+ * `props`/`uniforms`/`ctx`/textures as KitExpr arguments.
+ */
+export interface GpuFragmentParams {
+    /**
+     * The node's props as a single struct accessor (`uni.$.uniforms.n_<id>`), OR a local
+     * driver-overridden copy when the node has active map/mouse/auto drivers. Pass this as
+     * the `props` argument of the shader's `'use gpu'` fn.
+     */
+    props: Expr;
+    /**
+     * Per-prop KitExpr accessors (`props.<field>`), keyed by prop name. For builders that
+     * reference individual fields (aspect math) rather than the whole struct. Driver-overridden
+     * props resolve to the local copy's field.
+     */
+    uniforms: Record<string, Expr>;
+    /**
+     * Per-prop CPU VALUES (post-transform), keyed by prop name — the mirror of `uniforms`, for
+     * COMPILE-TIME BRANCHING. A `compileTime` prop (e.g. `edges`, `colorSpace`, a stop count)
+     * is read here as a plain number/enum so the builder can JS-branch and emit specialised
+     * WGSL. These values are part of the pipeline structural hash, so a change recomposes → the
+     * builder re-runs. Scalars come through as numbers; vector fields as the store's live view
+     * (rarely needed at build time — prefer the `uniforms`/`props` accessors for GPU math).
+     */
+    propValues: Record<string, unknown>;
+    /** Composed children — an RTT texture sample expression when this node consumes a child. */
+    childNode?: Expr;
+    /** System/context accessors. */
+    ctx: KitCtx;
+    /** Composed UV from a UV-propagating parent (`uvContext ?? ctx.uv` idiom). */
+    uvContext?: Expr;
+    /**
+     * True on a `providesUVContextViaCompute` LINK when `tryComposeViaUVContext` has PRE-EVALUATED
+     * the child generator at this link's looked-up UV (so `childNode` is already the colour at the right
+     * UV — composite it directly). Absent → the link re-samples its RTT child at the looked-up UV.
+     * Surface3D is the first consumer.
+     */
+    uvPropagationActive?: boolean;
+    /** Pre-computed bbox clip mask (float 1 inside / 0 outside) for early-discard. */
+    bboxMask?: Expr;
+    /** Box pixel dimensions as the effective viewport (generator resize-fit). */
+    effectiveViewportSize?: Expr;
+    /** CSS-pixel authored-frame size, for resolution-stable feature counts. */
+    logicalViewportSize?: Expr;
+    /** Compute-pass outputs (storage textures / buffers) forwarded to the fragment. */
+    computeOutputs?: Record<string, KitTexture | GpuStorageBuffer>;
+    /** Live child-shape bounds (Repeater). */
+    childBoundsParams?: GpuBoundsParams;
+    /** This node's own active bbox bounds (Repeater). */
+    ownBoundsParams?: GpuBoundsParams;
+    /** Register a texture the shader BODY samples via a fn-arg (media textures). */
+    declareTexture(tex: KitTexture): void;
+    /**
+     * Register an EXTERNAL texture (video/webcam) the shader samples. Returns a KitTexture
+     * whose `.sample(uv)` emits `textureSampleBaseClampToEdge(ext.$.<key>, …)` and whose
+     * `.dimensions()` emits `textureDimensions(ext.$.<key>)` (the live frame size). `getSource`
+     * is polled EACH FRAME by the pass manager: it returns the live `HTMLVideoElement`/`VideoFrame`
+     * when a decodable frame exists, or `null` when unavailable — in which case the pass is skipped
+     * for that frame (nothing to bind). The external texture is re-imported + its group-3 bind group
+     * rebuilt every frame; the emitted WGSL is fixed, so readiness never triggers a recompile.
+     */
+    registerExternalTexture(getSource: () => unknown): KitTexture;
+    /** Convert a composed expression to an RTT texture (registers a boundary). */
+    convertToTexture(expr: Expr): KitTexture;
+    /**
+     * Register a compute-WRITTEN texture (created with `storage`+`sampled` usage) so the
+     * fragment / uvRemap can sample it via the returned KitTexture. Registers a `kind:'compute'`
+     * texture binding; the pass manager binds the given texture into the sampling pass's texture
+     * group. This is how a compute hook's storage-texture outputs (Blur's blurred buffer, Glow's
+     * bloom pyramid, …) reach the fragment.
+     */
+    registerComputeTexture(texture: unknown): KitTexture;
+    /**
+     * Create a shader-owned media texture (fixed-size GPU upload target). Wired to the
+     * renderer's TextureManager, so it's counted + destroyed with the renderer. A media shader
+     * (ImageTexture/Text/DOMTexture) creates a placeholder here at composition, uploads content via
+     * `write` / `queue.copyElementImageToTexture`, and swaps to a fresh (differently-sized) texture
+     * as content loads — see `registerMediaTexture`.
+     */
+    createMediaTexture(options: GpuMediaTextureOptions): GpuMediaTexture;
+    /**
+     * Create a shader-owned DATA texture (r16float/r32float) uploaded from a raw
+     * `ArrayBufferView`. Same lifecycle + return shape as `createMediaTexture`, but the write path is
+     * `queue.writeTexture` (raw float data), not an image copy. The SVG-SDF samplers create one here,
+     * async-load the `.bin` field into it, and register it via `registerMediaTexture` for the fragment
+     * to sample. Wired to the renderer's TextureManager (`createDataTexture`); throws if none injected.
+     */
+    createDataTexture(options: GpuDataTextureOptions): GpuMediaTexture;
+    /**
+     * Register a media texture the shader BODY samples. `getTexture` returns the CURRENT backing
+     * TypeGPU texture each time it is read — a media shader keeps a mutable `current` and reassigns it
+     * when it swaps to a differently-sized texture (image loaded at native size, text re-rastered, DOM
+     * resized). The pass manager reads the getter every frame and rebuilds ONLY the sampling pass's
+     * group-1 bind group when the backing texture identity changes (cheap — no pipeline rebuild, no
+     * recompose). Returns the `KitTexture` for the body's `.sample(uv)` / `.dimensions()`.
+     */
+    registerMediaTexture(getTexture: () => unknown): KitTexture;
+    /**
+     * The LIVE post-transform CPU value of a prop, re-read on every call — for per-frame
+     * compute updates (Blur's radius from intensity). Unlike `propValues` (a compose-time snapshot
+     * for structural branching), this reads the node's live uniform handle, so a reactive value
+     * that changed since composition (without recompose) is reflected. Returns undefined for an
+     * unknown / cpu-only prop.
+     */
+    getCpuValue(prop: string): unknown;
+    /**
+     * Compute-map interplay. For a MAP-driven prop (`metadata.maps[prop].type === 'map'`),
+     * returns everything a compute pass needs to reproduce the fragment path's map resolve per
+     * compute pixel — the map SOURCE texture (a late-bound RTT KitTexture, bound in the compute
+     * node's `bindInputs`), the channel to extract, and a live remap-window reader. Returns null
+     * when `prop` has no active map driver (the caller falls back to its static path). The source
+     * RTT is shared with the fragment override (one boundary per node+prop). See Blur's compute
+     * hook for the reference consumer.
+     */
+    getMapInfo(prop: string): GpuMapInfo | null;
+    /**
+     * Write an `extraFields` field's CPU value (a scalar or a vecNf's components) on this
+     * node's LIVE handle — call from an `onBeforeRender` callback to drive a derived uniform each
+     * frame (Blob's normalized light direction). Patches the packed buffer for the next flush, so
+     * the value is picked up the SAME frame (frame order: onBeforeRender → flush → render). No-op
+     * for an undeclared name or before a composition is bound. Read the same field back in the
+     * builder via `uniforms.<name>`.
+     */
+    setExtraField(name: string, value: number | number[]): void;
+    onCleanup: (cb: CleanupCallback) => void;
+    onBeforeRender: (cb: RenderCallback) => void;
+    onAfterRender: (cb: RenderCallback) => void;
+    onResize: (cb: ResizeCallback) => void;
+    canvas: HTMLCanvasElement;
+    dimensions: {
+        width: number;
+        height: number;
+    };
+    domCanvas?: HTMLCanvasElement;
+    /** Raw device + root for DOMTexture / texture uploads. */
+    gpu: {
+        device: GPUDevice;
+        root: import('typegpu').TgpuRoot;
+    };
+}
+/** UV-space rectangle bounds as KitExpr accessors (Repeater). */
+export interface GpuBoundsParams {
+    centerX: Expr;
+    centerY: Expr;
+    halfWidth: Expr;
+    halfHeight: Expr;
+    rotation: Expr;
+}
+/** A storage buffer produced by a compute pass (particle/simulation state). */
+export interface GpuStorageBuffer {
+    readonly key: string;
+    accessor(): Expr;
+}
+/** A fragment builder — runs at composition, returns the node's colour expression. */
+export type GpuFragment = (params: GpuFragmentParams) => Expr;
+/** Pure coordinate bend (KitExpr currency). */
+export type GpuUvRemap = (ctx: {
+    uv: Expr;
+    mask: Expr;
+    uniforms: Record<string, Expr>;
+    /** Per-prop CPU values (post-transform) for compile-time branching — mirror of `uniforms` (see GpuFragmentParams). */
+    propValues: Record<string, unknown>;
+    props: Expr;
+    aspect: Expr;
+    onBeforeRender: (cb: RenderCallback) => void;
+    computeOutputs?: Record<string, KitTexture | GpuStorageBuffer>;
+}) => {
+    uv: Expr;
+    mask: Expr;
+};
+/** One compute step — a dispatchable kit pipeline or an inline thunk. */
+export type GpuComputeStep = import('./compute').ComputeStep;
+/** A compute node — KitTexture/GpuStorageBuffer outputs. */
+export type GpuComputeNode = (params: GpuFragmentParams) => {
+    outputs: Record<string, KitTexture | GpuStorageBuffer>;
+    getComputeNodes: (frameParams: unknown) => GpuComputeStep[] | null;
+    /**
+     * (Re)bind compute-pass INPUTS that read composition RTT boundaries. A compute
+     * hook that consumes its child via `convertToTexture(childNode)` can only build its input
+     * bind group once the physical RTT texture exists — and that is allocated by the pass manager
+     * AFTER composition. The composer records this callback per compute node; the pass manager
+     * invokes it right after allocating RTT textures (and again on every recompose), passing a
+     * resolver from a texture key (the `KitTexture.key` returned by `convertToTexture`) to the
+     * bound texture. Blur is the first shader to need this; see gpu/passManager `setComposition`.
+     */
+    bindInputs?: (resolve: (key: string) => {
+        texture: unknown;
+    } | undefined) => void;
+} | null;
+/**
+ * Custom per-prop sample UVs for prop maps (DotGrid, Grid). Returns a per-prop map of
+ * the UV a map-driven prop's SOURCE texture should be sampled at (e.g. the cell-CENTER UV for a
+ * tiled pattern, so a mapped `dotSize`/`thickness` reads one value per cell rather than varying
+ * per-fragment and clipping the shape at source boundaries). Any prop NOT in the returned map
+ * falls back to the fragment UV.
+ *
+ * Receives `ctx` (the same `KitCtx` a fragment builder gets) so the cell-center math can read
+ * `ctx.uv` / `ctx.viewportSize`. `uniforms` are the node's BASE (non-driver-overridden) prop
+ * accessors (the sample-UV math reads static prop values like `density`/`cells`/`rotation`,
+ * never the mapped value being resolved).
+ */
+export type GpuMapSampleUVs = (params: {
+    uniforms: Record<string, Expr>;
+    ctx: KitCtx;
+}) => Record<string, Expr>;
+/**
+ * A field the uniform store registers for this shader. These are derived from the shader's
+ * `props` (default + transform). The `propsSchema` is the composer's view of the node's struct;
+ * individual `FieldInit`s carry the transform + cpu-only marking for the store.
+ */
+export interface GpuPropField {
+    name: string;
+    /** WGSL schema (omit to infer from the transformed default). */
+    schema?: AnyWgslData;
+    /** CPU transform (transformColor/transformPosition/…) — retained on the FieldHandle. */
+    transform?: (value: unknown) => unknown;
+    /** CPU-only prop (string/JSON/select) — no struct field. */
+    cpu?: boolean;
+}
+/**
+ * The GPU shader definition. Declarative fields carry the shader's static metadata;
+ * GPU-code members take KitExpr currency.
+ */
+export interface GpuShaderDefinition<T extends ComponentProps = ComponentProps> {
+    name: string;
+    category?: string;
+    description?: string;
+    requiresRTT?: boolean;
+    requiresChild?: boolean;
+    blendWithChildren?: boolean;
+    usesPointer?: boolean;
+    acceptsUVContext?: boolean;
+    providesUVContextViaCompute?: boolean;
+    capturesDOM?: boolean;
+    wantsBoundsParams?: boolean;
+    boundingBoxDeclaration?: BoundingBoxDeclaration;
+    experimental?: ComponentProps;
+    /**
+     * Declares per-node ANIMATED TIME. When set, the renderer registers a synthetic `_animTime`
+     * f32 field on this node's struct and advances it CPU-side every frame by
+     * `deltaTime * <speed prop>.value` (speed=0 PAUSES — no rewind). `speed` names the prop the
+     * accumulation rate reads.
+     * Read the accumulated value inside the `fragment` / `uvRemap` builder via the porters
+     * facade's `animatedTime(params[, seedName])` — do NOT read `ctx.time` for speed-controlled
+     * motion (`ctx.time` is the global, un-paused, un-scaled clock). Seed is added on the GPU by
+     * the helper, so it stays an ordinary uniform and is not named here.
+     */
+    animatedTime?: {
+        speed: string;
+    };
+    /**
+     * ADDITIONAL per-node animated-time clocks beyond the primary `_animTime`, for shaders
+     * with two+ INDEPENDENT flow clocks (FlowField: a flow-drift speed AND an evolution speed).
+     * Each entry `{<key>: '<speedProp>'}` registers a synthetic `_animTime_<key>` f32 field,
+     * advanced every frame by `deltaTime * <speedProp>.value` on its OWN accumulator (keyed on the
+     * speed prop, distinct from the primary), exactly like `_animTime`. speed=0 pauses. Read the
+     * accumulated value in the builder via `animatedTime(params, seed?, '_animTime_<key>')`. Not a
+     * prop → never in the structural hash, so a per-frame change patches in place.
+     */
+    extraAnimatedTimes?: Record<string, string>;
+    /**
+     * EXTRA per-node uniform fields the shader DERIVES on the CPU each frame and READS on the
+     * GPU — for values that are neither a prop nor a system uniform (Blob's normalized light
+     * direction, precomputed so `normalize()` doesn't run per fragment). A shader cannot add
+     * ad-hoc uniforms inside its builder, so it DECLARES them here. Each entry registers an
+     * f32/vecNf field on this node's `n_<id>` struct (exactly like `_animTime`), seeded with
+     * `initial`. The builder reads it as `params.uniforms.<name>` (a GPU accessor Expr); an
+     * `onBeforeRender` callback writes it each frame via `params.setExtraField(<name>, value)`.
+     * The value changes per frame WITHOUT recomposing (it is not a prop, so not in the structural
+     * hash) — same contract as `_animTime`.
+     */
+    extraFields?: Record<string, {
+        schema: AnyWgslData;
+        initial: number | number[];
+    }>;
+    props: {
+        [K in keyof T]: PropConfig<T[K]>;
+    };
+    /**
+     * The node's per-node uniform struct (the `n_<id>` sub-struct of the packed buffer).
+     * The composer nests it under a runtime key; shader fns take an instance as their
+     * `props` arg. Optional: when omitted the composer infers it from `propFields`.
+     */
+    propsSchema?: WgslStruct;
+    /** Store field descriptors (transforms / cpu-only markers) derived from `props`. */
+    propFields?: GpuPropField[];
+    /** The fragment builder. */
+    fragment: GpuFragment;
+    /** Optional pure-analytic UV bend. */
+    uvRemap?: GpuUvRemap;
+    /** Optional compute pass. */
+    compute?: GpuComputeNode;
+    /** Optional custom per-prop sample UVs for prop maps. */
+    mapSampleUVs?: GpuMapSampleUVs;
+}
+/** A driver config attached to a prop (map/mouse/auto) — opaque here; resolved by the composer. */
+export type PropDriverConfig = import('../types').PropDriver;
+/** One node as the composer sees it. */
+export interface RegistryNode {
+    /** Internal unique node id. */
+    id: string;
+    /** Custom id used for mask/map source references (`metadata.id`, sanitised). */
+    customId?: string;
+    componentName: string;
+    parentId: string | null;
+    definition: GpuShaderDefinition;
+    /** Blend/opacity/visible/mask/maps/transform/boundingBox — the composition metadata. */
+    metadata: NodeMetadata;
+    /**
+     * The node's uniform handles keyed by prop name (from the uniform store). The composer
+     * reads `.accessorPath` / `store.gpuAccessor(handle)` to emit GPU references, and reads
+     * `.value` for compile-time-relevant prop values (hashing, bbox math).
+     */
+    handles: Record<string, UniformHandleView>;
+    /** Per-node DOM-capture host canvas (DOMTexture `capturesDOM`) — forwarded to `params.domCanvas`. */
+    domCanvas?: HTMLCanvasElement;
+}
+/** The subset of a FieldHandle / ArrayFieldHandle the composer needs. */
+export interface UniformHandleView {
+    readonly accessorPath: string;
+    readonly cpu: boolean;
+    readonly value: unknown;
+}
+/** The composer's read-only view over the node registry. */
+export interface RegistryView {
+    rootId: string | null;
+    /** All nodes by internal id. */
+    getNode(id: string): RegistryNode | undefined;
+    /** Direct children of a node, unsorted. */
+    getChildren(parentId: string): RegistryNode[];
+    /** Resolve a custom id (mask/map source) to an internal node id. */
+    resolveCustomId(customId: string): string | null;
+    /** The uniform store (for `gpuAccessor` + the combined layout). */
+    store: {
+        gpuAccessor(handle: {
+            accessorPath: string;
+        }, layoutVar?: string): string;
+        readonly layout?: TgpuBindGroupLayout;
+    };
+}
+export type { BlendMode, MaskType };
+//# sourceMappingURL=contract.d.ts.map

package/dist/core/gpu/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/gpu/contract.ts"],"names":[],"mappings":"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"}

package/dist/core/gpu/frame.d.ts

@@ -0,0 +1,120 @@
+import { TgpuRoot } from 'typegpu';
+
+/**
+ * Spring-damper step for smooth mouse tracking. Returns `[newPosition, newVelocity]`.
+ * When smoothing and momentum are both 0 the target is returned immediately (zero cost).
+ */
+export declare function applySpring(current: number, velocity: number, target: number, smoothing: number, momentum: number, dt: number): [number, number];
+/** The easing names the auto-animate driver accepts. */
+export type EasingName = 'linear' | 'quad' | 'expo' | 'bounce' | 'sine';
+/** Uncharted-style multi-segment bounce ease. */
+export declare function applyBounceEase(t: number): number;
+/** Maps a 0..1 phase through the named easing. Default is `sine`. */
+export declare function applyEasing(t: number, easing: string): number;
+export interface ClampEnv {
+    /** Device `maxTextureDimension2D` (or the 8192 spec-minimum fallback pre-init). */
+    maxTextureDim: number;
+    /** The DPR factor we back the canvas at. */
+    pixelRatio: number;
+    /** Live viewport width in CSS px (window.innerWidth). */
+    viewportWidth: number;
+    /** Live viewport height in CSS px (window.innerHeight). */
+    viewportHeight: number;
+}
+/**
+ * Clamps requested CSS-pixel dimensions to a safe GPU buffer size while preserving aspect
+ * ratio. The buffer (cssSize × pixelRatio) never exceeds the viewport or
+ * `maxTextureDimension2D`. Pure (env injected) so it is golden-testable; `index.ts` wraps it
+ * with the live window + DPR. The `-1` slack guards a borderline value from rounding over the
+ * cap.
+ */
+export declare function clampToTextureCap(w: number, h: number, env: ClampEnv): {
+    width: number;
+    height: number;
+};
+/**
+ * The elapsed-seconds clock the shader `time` uniform reads. With a shared wall-clock origin
+ * (synced multi-tile animation), time is `(now - origin)/1000` so every renderer sharing the
+ * origin lands on the same value and self-heals across pauses. Without one, it accumulates
+ * the (already clamped) per-frame delta — "seconds since this renderer started".
+ */
+export declare function deriveElapsedTime(sharedTimeOrigin: number | null, prevElapsed: number, deltaTime: number, now: number): number;
+/** Off-screen render interval (1 FPS) when not forced to full frame rate. */
+export declare const OFF_SCREEN_FPS_INTERVAL = 1000;
+/**
+ * On-screen minimum frame interval — a 60 FPS cap with 1ms jitter tolerance so a 60Hz
+ * display hits a true 60fps without the aliasing that a cap exactly equal to the refresh
+ * interval produces.
+ */
+export declare const MIN_FRAME_INTERVAL: number;
+export interface FrameGateState {
+    /** Timestamp (performance.now ms) of the last rendered frame, or 0 if none yet. */
+    lastRenderTime: number;
+    /** IntersectionObserver visibility — false throttles to 1 FPS. */
+    isVisible: boolean;
+    /** When true, off-screen throttling is bypassed (hidden-canvas partner integrations). */
+    forceFullFrameRate: boolean;
+}
+export interface FrameGateResult {
+    /** Whether this frame should render (false = skip, throttled). */
+    render: boolean;
+    /** Delta since the last frame, in seconds, clamped to 0.1. */
+    deltaTime: number;
+}
+/**
+ * Decides whether the current tick should render and, if so, the clamped delta. Variable
+ * frame rate: 1 FPS off-screen, up to 60 FPS on-screen (with the jitter-tolerant cap), delta
+ * clamped to 0.1s. The synthetic-frame path bypasses this entirely (see {@link syntheticDelta});
+ * it is only used by the RAF-driven live loop.
+ */
+export declare function frameGate(now: number, state: FrameGateState): FrameGateResult;
+/**
+ * Resolves when the device has finished all previously submitted work, via
+ * `device.queue.onSubmittedWorkDone()`. Falls back to a one-frame timeout if the queue does
+ * not expose the API (never expected on a real device; keeps the screenshot/export path from
+ * hanging on a mock).
+ */
+export declare function awaitGpuIdle(root: TgpuRoot): Promise<void>;
+/**
+ * The ordered per-frame steps. Kept as an interface + a pure runner so the canonical order is
+ * declared once and unit-testable with mocks that record call order (no device needed).
+ */
+export interface FrameSequence {
+    /** CPU driver springs / easing + animated-time advance (before anything is flushed). */
+    updateDrivers(): void;
+    /** Ensure the desired composition is built + bound. Return false to skip (nothing to draw). */
+    ensureComposition(): boolean;
+    /** onBeforeRender shader callbacks — they write uniforms, so they run before flush. */
+    beforeRender(): void;
+    /** Coalesced uniform buffer patch for the bound composition. */
+    flush(): void;
+    /** Draw the composition currently selected by the pipeline cache (swap-when-ready). */
+    render(): void;
+    /** Promote the pending composition once it has drawn a frame + fire onReady. */
+    markReady(): void;
+    /** onAfterRender shader callbacks. */
+    afterRender(): void;
+}
+/**
+ * Runs one frame's steps in the canonical order: drivers/time → [ensure composition] →
+ * onBeforeRender → flush → render → markReady → onAfterRender. `ensureComposition` returning
+ * false short-circuits the rest (no root composed yet). onBeforeRender precedes flush because
+ * those callbacks write uniforms; in steady state `ensureComposition` is a cache-hit no-op.
+ */
+export declare function runFrameSequence(seq: FrameSequence): void;
+export interface FrameLoop {
+    /** Start the loop (idempotent). No-op if already running. */
+    start(): void;
+    /** Stop the loop and cancel any pending frame. */
+    stop(): void;
+    /** Whether the loop is currently running. */
+    readonly running: boolean;
+}
+/**
+ * A minimal `requestAnimationFrame` loop that invokes `tick` once per frame. The throttle
+ * decision lives in `tick` itself (via {@link frameGate}); this factory only owns the RAF
+ * scheduling + teardown. SSR-safe: `requestAnimationFrame` is resolved lazily at `start()`,
+ * never at import.
+ */
+export declare function createFrameLoop(tick: () => void): FrameLoop;
+//# sourceMappingURL=frame.d.ts.map

package/dist/core/gpu/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../src/gpu/frame.ts"],"names":[],"mappings":"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"}