shaders 3.0.452 → 3.1.454

package/dist/core/gpu/scaffolds/agentSystem.d.ts

@@ -0,0 +1,244 @@
+import { TgpuBindGroupLayout } from 'typegpu';
+import { AnyWgslStruct, Infer } from 'typegpu/data';
+import { ComputeStep, KitComputePipeline } from '../compute';
+import { GpuFragmentParams, KitTexture } from '../contract';
+import { d } from '../kit';
+
+/** A value with a lower setting for coarse-pointer (phone/tablet) GPUs. */
+export interface DeviceTier {
+    desktop: number;
+    mobile: number;
+}
+/**
+ * Pick the coarse-pointer or the desktop value.
+ *
+ * BUILD-TIME CONSTANT BY DESIGN for a resolution: the accumulator length lives in a module-scope
+ * `tgpu.bindGroupLayout`, so it must be decided at import time, not per composition. SSR and the
+ * GPU-free tests resolve to `desktop`.
+ */
+export declare function resolveDeviceTier(tier: DeviceTier): number;
+/**
+ * The square render/accumulator resolution for this device tier.
+ *
+ * PAIR THIS WITH A FIXED `SIZE_REF_RES`. Agent body sizes are authored in texels, so deriving them
+ * from the live (tiered) resolution makes the same preset render a *larger* flock on a phone —
+ * fewer texels across the same canvas means each texel covers more screen. Size math must divide by
+ * {@link SIZE_REF_RES}; only the buffer/texture extents use the tiered value.
+ */
+export declare function resolveRenderRes(tier: DeviceTier): number;
+/** The fixed resolution agent sizes are authored against, decoupling them from {@link resolveRenderRes}. */
+export declare const SIZE_REF_RES = 1024;
+/**
+ * Fixed-point gains for the atomic energy accumulators.
+ *
+ * The resolve's alpha curve is `1 − e^(−1.6·E)` with `E = raw/255`, which reaches 1.0 only
+ * asymptotically. A HARD shape's interior returns coverage exactly 1, so at a gain of 255 its
+ * centre would resolve to `1 − e^(−1.6)` ≈ 0.80 — a solid dot rendering 80% grey. `HARD`
+ * over-drives the scale by 2.5× so those interiors saturate; `SOFT` keeps the true scale because a
+ * Gaussian skirt is *supposed* to top out below opaque.
+ */
+export declare const FIXED_POINT_GAINS: {
+    readonly HARD: 637;
+    readonly SOFT: 255;
+};
+/**
+ * The R2 sequence's irrational strides (the 2D "plastic constant" generalization of the golden
+ * ratio): `frac(0.5 + i·α)` gives quasi-uniform coverage for ANY prefix of `i`, so a count slider
+ * can grow or shrink the population without re-seeding and without leaving holes. Positions derived
+ * from the index alone need no storage.
+ */
+export declare const R2_ALPHA: readonly [0.7548776662466927, 0.5698402909980532];
+/**
+ * The R3 sequence's strides — the same construction one dimension up. Used per FRAME rather than
+ * per agent: stepping a sub-cell offset along R3 dithers a voxel lattice evenly over time, which is
+ * what keeps a density grid from standing in coherent moiré with a shape boundary.
+ */
+export declare const R3_ALPHA: readonly [0.8191725133961645, 0.6710436067037893, 0.5497004779019703];
+/** Per-frame values every agent shader derives from the renderer's frame params. */
+export interface AgentFrame {
+    /** Frame delta clamped to [1ms, 33ms] — one stalled frame must not teleport the simulation. */
+    dt: number;
+    /** Viewport aspect (guarded against a zero-height canvas). */
+    aspect: number;
+    pointerX: number;
+    pointerY: number;
+}
+/** The subset of the renderer's frame params an agent simulation reads. */
+export interface AgentFrameParams {
+    pointer?: {
+        x: number;
+        y: number;
+    };
+    deltaTime?: number;
+    dimensions?: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Normalize the renderer's frame params: dt clamp, aspect, pointer defaults.
+ *
+ * The dt clamp is load-bearing in both directions. The floor stops a division blowing up on a
+ * 0ms frame; the 33ms ceiling means a tab-switch or a long GC pause advances the sim by one slow
+ * frame instead of integrating a one-second step and throwing every agent off-screen.
+ *
+ * `fallbackAspect` is what a shader wants when the canvas has no height yet — 16/9 for a
+ * generator that fills the viewport, 1 for one whose grid is refit to the aspect each frame.
+ */
+export declare function readAgentFrame(frameParams: unknown, fallbackAspect?: number): AgentFrame;
+/**
+ * The numeric prop reader every one of these shaders declared inline (10 copies).
+ *
+ * Why a fallback per call rather than reading the prop's declared default: a dynamic prop (a range
+ * map, a mouse binding) can resolve to a non-number for a frame, and a kernel uniform must never
+ * receive `undefined`.
+ */
+export declare function makeCpuValueGetter(getCpuValue: (prop: string) => unknown): (key: string, fallback: number) => number;
+/** Clamp a raw count prop into `[min, cap]` — the runtime cap, never the prop's declared range. */
+export declare function clampAgentCount(raw: number, min: number, cap: number): number;
+/** Inclusive texel bounds of a splat window, already clipped to the accumulator. */
+export declare const SplatWindow: d.WgslStruct<{
+    x0: d.I32;
+    x1: d.I32;
+    y0: d.I32;
+    y1: d.I32;
+}>;
+/**
+ * The splat window for an agent living in WORLD space — x ∈ [0, aspect], y ∈ [0, 1], 1 unit == the
+ * canvas height — splatting into a SQUARE `res × res` accumulator.
+ *
+ * Two things make this worth having in one place. First, the window is sized to the agent's ACTUAL
+ * reach rather than a fixed box, which is a correctness fix and not just an optimization: a fixed
+ * ±16-texel window hard-clipped large `arrow` / `streak` / `glow` shapes into squares. Second, the
+ * radius is PER AXIS. The accumulator is square but the world domain is `aspect` wide, so one
+ * x-texel covers `aspect` times as much world as a y-texel — hence the divide. Getting that wrong
+ * is invisible at 1:1 and stretches every agent on a wide canvas.
+ *
+ * `reach` is the world-space accept radius (shape extent + AA margin). Clipping happens once here,
+ * so the caller's inner loop carries no bounds test, and an off-screen agent clips to an empty
+ * range — which is also the off-target early-out.
+ */
+export declare const worldSplatWindow: import('typegpu').TgpuFn<(pos: d.Vec2f, reach: d.F32, aspect: d.F32, res: d.F32) => d.WgslStruct<{
+    x0: d.I32;
+    x1: d.I32;
+    y0: d.I32;
+    y1: d.I32;
+}>>;
+/**
+ * The splat window for an agent already projected to TEXEL coordinates, with an isotropic radius
+ * (the projected-3D consumers, whose render target has square texels so no aspect term survives).
+ *
+ * `last` is the inclusive maximum texel per axis, passed rather than derived because the target
+ * extent can be a per-frame uniform (a target fitted to the frame aspect).
+ */
+export declare const texelSplatWindow: import('typegpu').TgpuFn<(center: d.Vec2f, rad: d.I32, last: d.Vec2i) => d.WgslStruct<{
+    x0: d.I32;
+    x1: d.I32;
+    y0: d.I32;
+    y1: d.I32;
+}>>;
+/**
+ * Accumulated energy → coverage alpha: `1 − e^(−k·energy)`. Saturating, so overlapping agents
+ * deepen toward opaque without ever clipping, and empty texels resolve to exactly 0 (fully
+ * transparent gaps, so the field composites over anything).
+ *
+ * WHY THE READ-THEN-ZERO ISN'T HERE. Every consumer's resolve reads its accumulator with
+ * `atomicLoad` and immediately `atomicStore`s 0 — one thread owns each cell and nothing else is in
+ * flight, so that needs no exchange and replaces a separate full-target clear pass. It cannot be
+ * shared as a `tgpu.fn` because WGSL cannot take a storage array as a function parameter, so the
+ * two-line load/store stays in each shader, next to the layout entry it names.
+ */
+export declare const energyCoverageAlpha: import('typegpu').TgpuFn<(energy: d.F32, k: d.F32) => d.F32>;
+/**
+ * Semi-implicit Euler with exponential drag and a speed clamp — the integrator the force-based
+ * consumers share.
+ *
+ * Semi-implicit (velocity updated first, then position from the NEW velocity) is what keeps an
+ * underdamped spring stable at the frame rates a browser actually delivers; explicit Euler gains
+ * energy and eventually explodes. `dragMul` is `exp(−drag·dt)` computed on the CPU, so the decay is
+ * frame-rate independent rather than a per-frame multiply. The clamp is a safety net, not a feel
+ * knob: without it one bad frame's force can launch an agent out of the domain entirely.
+ */
+export declare const integrateSemiImplicitEuler: import('typegpu').TgpuFn<(vel: d.Vec3f, force: d.Vec3f, dt: d.F32, dragMul: d.F32, maxSpeed: d.F32) => d.Vec3f>;
+/** How many threads a step dispatches. */
+export type AgentThreads = 
+/** The runtime agent count, passed to `frame({count})`. */
+'agents'
+/** `maxAgents` — the static bound, for a one-shot init/re-seed over every slot. */
+ | 'max'
+/** A per-frame 2D grid, passed to `frame({grid})`. */
+ | 'grid'
+/** A fixed size given by `size` (a full render target, a voxel grid). */
+ | 'fixed';
+export interface AgentPipelineSpec {
+    /** A module-scope `tgpu.fn` kernel: `(i)` for 1D dispatch, `(x, y)` for `'grid'` / 2D `'fixed'`. */
+    kernel: ((i: number) => void) | ((x: number, y: number) => void);
+    threads: AgentThreads;
+    /** Required for `threads: 'fixed'`; its length picks the 1D or 2D dispatch. */
+    size?: [number] | [number, number];
+    /** Chain `extraBindGroup` onto this pipeline (a shape family's own SDF resources). */
+    extra?: boolean;
+}
+export interface AgentSystemConfig<TParams extends AnyWgslStruct> {
+    /**
+     * The shader's module-scope bind group layout. Buffers are allocated by introspecting it, and
+     * the kernels reference it directly — so its key names are the WGSL identifiers.
+     */
+    layout: TgpuBindGroupLayout;
+    /** Schema of the layout's `uniform` entry — the per-frame CPU-derived inputs. */
+    params: TParams;
+    /** The output storage texture the resolve writes and the fragment samples. */
+    output: {
+        /** Layout key of the `storageTexture` entry. */
+        key: string;
+        /** Key in the returned `outputs` record (what the fragment reads off `computeOutputs`). */
+        name: string;
+        size: [number, number];
+        format: 'rgba16float';
+    };
+    /** The static dispatch/loop bound — how many slots the state buffers hold. */
+    maxAgents: number;
+    /** Effective count ceiling per device tier. The prop's declared range is unchanged. */
+    countCap?: DeviceTier;
+    /** Layout keys bound late, from another node's output (a child RTT). See `bindExternal`. */
+    externalKeys?: readonly string[];
+    /** A second bind group chained onto every pipeline marked `extra: true`. */
+    extraBindGroup?: unknown;
+    pipelines: Record<string, AgentPipelineSpec>;
+    /** Per-frame execution order (keys of `pipelines`). */
+    program: readonly string[];
+    /** Key of the one-shot step run before the first frame's program, and again on a reseed. */
+    initStep?: string;
+}
+export interface AgentSystem<TParams extends AnyWgslStruct> {
+    /** Spread into the compute hook's `outputs`. */
+    outputs: Record<string, KitTexture>;
+    /** Write the whole per-frame uniform struct (strict layout — a plain struct has no partial patch). */
+    writeParams: (values: Infer<TParams>) => void;
+    /** The effective agent-count ceiling for this device. */
+    readonly countCap: number;
+    /** Clamp a raw count prop into `[min, countCap]`. */
+    resolveCount: (raw: number, min?: number) => number;
+    /** The created pipelines, by config key — for a shader that needs to dispatch one itself. */
+    pipelines: Record<string, KitComputePipeline>;
+    /** Bind the late-arriving external resources (call from `bindInputs`). */
+    bindExternal: (entries: Record<string, unknown>) => void;
+    /**
+     * The frame's compute steps, with the one-shot init prepended on the first call (and whenever
+     * `reseed` changes). `null` until every external key is bound.
+     */
+    frame: (opts?: {
+        count?: number;
+        grid?: [number, number];
+        reseed?: number;
+    }) => ComputeStep[] | null;
+}
+/**
+ * Build the runtime side of an agent simulation: state buffers, the output texture, the uniform,
+ * the bind group, the guarded pipelines, and the per-frame step list.
+ *
+ * Returns `null` when there is no GPU device (SSR, the GPU-free resolve tests) — the caller returns
+ * `null` from its `compute` hook and the fragment falls back.
+ */
+export declare function createAgentSystem<TParams extends AnyWgslStruct>(params: GpuFragmentParams, config: AgentSystemConfig<TParams>): AgentSystem<TParams> | null;
+//# sourceMappingURL=agentSystem.d.ts.map

package/dist/core/gpu/scaffolds/agentSystem.d.ts.map

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

package/dist/core/gpu/scaffolds/feedbackSim.d.ts

@@ -0,0 +1,102 @@
+import { ComputeStep, PingPongPair } from '../compute';
+import { GpuFragmentParams, KitTexture } from '../contract';
+
+export { createPingPongPair, type PingPongPair } from '../compute';
+/** Texture size as `[width, height]`, or one number for a square. */
+export type SimSize = number | readonly [number, number];
+/** One side of the ping-pong: the state texture plus any extra lockstep-swapping slots. */
+export interface SimSlot {
+    /** The state texture for this side. */
+    state: unknown;
+    /** Extra per-side textures declared via `extraSlots`, keyed by their declared name. */
+    extra: Record<string, unknown>;
+}
+/** What `bindGroups` / `staticGroups` get to build bind groups from. */
+export interface SimBindContext {
+    /** The child RTT, already typed for `root.createBindGroup`. */
+    childTexture: never;
+    /** The display copy the fragment samples (a write-only storage target for the kernel). */
+    display: unknown;
+    /** Orientation-independent textures declared via `textures`, keyed by name. */
+    textures: Record<string, unknown>;
+}
+/** What the per-frame callback gets. */
+export interface SimTick<TGroups, TStatic> {
+    /** Bind groups for the CURRENT orientation. */
+    groups: TGroups;
+    /** Orientation-independent bind groups (from `staticGroups`), or `undefined` if none declared. */
+    shared: TStatic;
+    /** Frame delta, clamped to `maxDeltaTime` and multiplied by the `speedProp` value. */
+    dt: number;
+    /** Sum of every `dt` so far — the sim's own clock, unaffected by the global time uniform. */
+    localTime: number;
+    /** The raw frame delta before clamping and speed scaling. */
+    rawDeltaTime: number;
+}
+export interface FeedbackTrailSimOptions<TGroups, TStatic> {
+    /** State + display resolution. */
+    size: SimSize;
+    /** Storage format for state, display and extra textures. Must be a core storage format. */
+    format: 'rgba16float' | 'rgba32float';
+    /**
+     * Extra texture pairs that swap in LOCKSTEP with the state (TimeTrail's previous-live-frame
+     * copy). Value is that slot's size — pass `[1, 1]` for a stub a compile-time-disabled kernel
+     * variant never touches but the bind group still has to fill.
+     */
+    extraSlots?: Record<string, SimSize>;
+    /** Orientation-independent extra textures (KeyFrames' feature grid). */
+    textures?: Record<string, SimSize>;
+    /** Prop whose value scales `dt`. Omit for an unscaled (real-time) sim. */
+    speedProp?: string;
+    /** Upper bound on the frame delta before speed scaling. Defaults to 0.05 s. */
+    maxDeltaTime?: number;
+    /** Build the bind groups for one orientation. Called twice (once per orientation), late. */
+    bindGroups: (ctx: SimBindContext, read: SimSlot, write: SimSlot) => TGroups;
+    /** Build orientation-independent bind groups. Called once, late. */
+    staticGroups?: (ctx: SimBindContext) => TStatic;
+}
+export interface FeedbackTrailSim<TGroups, TStatic> {
+    /** The child's RTT handle — put it in `outputs` so the fragment samples it rather than re-RTTing. */
+    readonly childTexture: KitTexture;
+    /** The registered display copy — put it in `outputs`; the fragment samples this. */
+    readonly display: KitTexture;
+    /** The raw state pair, for a shader that needs the textures directly. */
+    readonly pair: PingPongPair<SimSlot>;
+    /** Hand straight to the compute node's `bindInputs`. */
+    bindInputs: (resolve: (key: string) => {
+        texture: unknown;
+    } | undefined) => void;
+    /**
+     * The body of `getComputeNodes`. Returns `null` before the child RTT is bound. Otherwise
+     * advances the clock, invokes `frame`, and swaps the ping-pong — but only if `frame` returned
+     * steps, so an idle-skip frame leaves the orientation untouched.
+     */
+    tick: (frameParams: unknown, frame: (t: SimTick<TGroups, TStatic>) => ComputeStep[] | null) => ComputeStep[] | null;
+}
+/**
+ * Allocate and wire a state-texture feedback simulation. Returns `null` when there is no child or
+ * no GPU device, which is the "fragment falls back to a passthrough" branch every consumer has.
+ *
+ * @example
+ * const sim = createFeedbackTrailSim(params, {
+ *     size: STATE_RES,
+ *     format: 'rgba16float',
+ *     speedProp: 'speed',
+ *     bindGroups: ({childTexture, display}, read, write) =>
+ *         root.createBindGroup(moshLayout, {
+ *             src: childTexture, prev: read.state, next: write.state, display,
+ *             params: paramsBuf.buffer,
+ *         } as never),
+ * })
+ * if (!sim) return null
+ * return {
+ *     outputs: {childTexture: sim.childTexture, display: sim.display},
+ *     bindInputs: sim.bindInputs,
+ *     getComputeNodes: (fp) => sim.tick(fp, ({groups, dt, localTime}) => {
+ *         paramsBuf.write({time: localTime, dt, ...})
+ *         return [pipeline.with(groups)]
+ *     }),
+ * }
+ */
+export declare function createFeedbackTrailSim<TGroups, TStatic = undefined>(params: GpuFragmentParams, opts: FeedbackTrailSimOptions<TGroups, TStatic>): FeedbackTrailSim<TGroups, TStatic> | null;
+//# sourceMappingURL=feedbackSim.d.ts.map

package/dist/core/gpu/scaffolds/feedbackSim.d.ts.map

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

package/dist/core/gpu/scaffolds/fluids.d.ts

@@ -0,0 +1,170 @@
+import { d } from '../kit';
+import { ComputeStep, KitComputePipeline } from '../compute';
+import { TgpuRoot } from 'typegpu';
+
+/**
+ * The storage-texture form every fluid consumer publishes through: rgba16float, write-only. Half
+ * floats are enough for a velocity or dye field and they give the fragment hardware-bilinear
+ * filtering on the upsample, which a 32-bit format would not on most Android GPUs.
+ */
+export type FluidStorageTexture = d.textureStorage2d<'rgba16float', 'write-only'>;
+/** The solve uniforms every kernel set reads. */
+export interface FluidSolveParams {
+    readonly dt: number;
+    readonly curlStrength: number;
+    readonly velFade: number;
+}
+/** The additional uniforms the dye passes read. */
+export interface FluidDyeParams extends FluidSolveParams {
+    readonly dyeFade: number;
+    readonly colorDecay: number;
+}
+/**
+ * The union of every layout entry the solver can touch.
+ *
+ * Which entries are actually required depends on the options, and TypeScript cannot express
+ * "`dyeA` is required iff `dye !== 'none'`" across one signature — so the builder takes the core
+ * shape and casts once internally. A layout missing an entry its options need fails at
+ * `tgpu.resolve` time, which every consumer's resolve gate exercises.
+ */
+export interface FluidSolverLayout {
+    readonly $: {
+        readonly velA: d.v4f[];
+        readonly velB: d.v4f[];
+        readonly pressure: number[];
+        readonly divergence: number[];
+        readonly params: FluidSolveParams;
+    };
+}
+/** The output pass's layout: the dye buffer read-only, plus the storage texture it publishes to. */
+export interface FluidOutputLayout {
+    readonly $: {
+        readonly dyeA: d.v4f[];
+        readonly outTex: FluidStorageTexture;
+    };
+}
+/**
+ * How the grid edges behave.
+ *
+ * - `clamped` — neighbour lookups clamp to the grid, and the divergence pass reflects the wall-normal
+ *   velocity at the border (free-slip): the fluid is in a box.
+ * - `toroidal` — neighbour lookups and advection backtraces wrap modulo N: the field is seamless and
+ *   has no walls at all. Fog uses this so its cloud has no visible frame.
+ */
+export type FluidBoundary = 'clamped' | 'toroidal';
+/**
+ * What the dye field carries.
+ *
+ * - `none` — velocity only. The consumer reads the field for something else (ParticleFlow advects
+ *   particles through it), so there is no dye to advect, copy or publish.
+ * - `densityAge` — `x` = density, `y` = age in [0, 1]. The fragment colours density by age, which is
+ *   what gives smoke its fresh→aged ramp.
+ * - `rgb` — `xyz` = colour. The dye IS the picture (InkFlow).
+ */
+export type FluidDyeMode = 'none' | 'densityAge' | 'rgb';
+export interface StableFluidsOptions {
+    /** Grid resolution per axis. The kernels are dispatched 2D over N×N. */
+    n: number;
+    /**
+     * Prefix for every kernel's `$name`. Kernel names appear in the emitted WGSL, so this is what
+     * keeps each consumer's snapshots stable and keeps two fluid shaders in one tree from colliding
+     * on WGSL identifiers (C3).
+     */
+    namePrefix: string;
+    boundary: FluidBoundary;
+    dye: FluidDyeMode;
+    /** Divide advected dye by `1 + dyeFade·dt` and floor it at zero. Fog's fog is permanent. */
+    dyeDissipation?: boolean;
+    /** Advance the age channel by `dt · 0.4 · colorDecay` (capped at 1). `densityAge` only. */
+    ageAdvance?: boolean;
+    /**
+     * Gate the fluid on `maskBuf.x`: cells outside the mask are solid walls in the divergence pass,
+     * and advected velocity/dye is zeroed there. SmokeFill uses it to confine smoke to a shape.
+     * `clamped` only — a toroidal field with interior walls is not a configuration we ship.
+     */
+    solidMask?: boolean;
+    /**
+     * Clamp the post-projection velocity magnitude to this many grid cells per second. Fog needs it
+     * because a permanent, never-dissipating field can otherwise accumulate enough energy over
+     * minutes to advect further than one cell per step and go unstable.
+     */
+    velocityCap?: number;
+    /** Also `textureStore` the solved velocity into `velOutTex` from the copy pass. */
+    publishVelocityTexture?: boolean;
+    /** Per-frame pressure retention in the divergence pass (the warm start). Default 0.8. */
+    pressureDecay?: number;
+}
+/**
+ * The neighbour flat index for a (row, col) plus a (di, dj) offset, under the given boundary mode.
+ * Exported for consumers whose own kernels need the same lookup (a mask or obstacle pass).
+ */
+export declare function neighbourIndex(n: number, boundary: FluidBoundary): import('typegpu').TgpuFn<(ii: d.I32, ji: d.I32, di: d.I32, dj: d.I32) => d.U32>;
+/** The kernel set for one configuration. Absent members are the ones the options exclude. */
+export interface StableFluidsKernels {
+    curl: (cx: number, cy: number) => void;
+    vorticity: (cx: number, cy: number) => void;
+    divergence: (cx: number, cy: number) => void;
+    jacobi: (cx: number, cy: number) => void;
+    gradSubtract: (cx: number, cy: number) => void;
+    advectVel: (cx: number, cy: number) => void;
+    copyVel: (cx: number, cy: number) => void;
+    advectDye?: (cx: number, cy: number) => void;
+    copyDye?: (cx: number, cy: number) => void;
+}
+/**
+ * Bake the solver kernels against a consumer's layout.
+ *
+ * Call this at MODULE scope, next to the layout declaration — the kernels are `tgpu.fn`s and want to
+ * exist once per module, not once per component instance.
+ */
+export declare function buildStableFluidsKernels(layoutIn: FluidSolverLayout, opts: StableFluidsOptions): StableFluidsKernels;
+/**
+ * The output pass: publish the dye buffer to a storage texture the fragment samples.
+ *
+ * Separate from `buildStableFluidsKernels` because it reads a DIFFERENT bind group — the dye buffer
+ * bound read-only alongside a write-only storage texture — and a kernel may only reference one
+ * layout.
+ *
+ * `densityAge` writes `(density, age, 0, 0)`; `rgb` writes `(r, g, b, 1)`. Both formats are
+ * rgba16float, so the fragment gets hardware-bilinear filtering for free on the upsample.
+ */
+export declare function buildFluidOutputKernel(layout: FluidOutputLayout, opts: {
+    n: number;
+    namePrefix: string;
+    dye: Exclude<FluidDyeMode, 'none'>;
+}): import('typegpu').TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
+/** The guarded compute pipelines for one kernel set, plus the ordered chain that drives them. */
+export interface StableFluidsPasses {
+    curl: KitComputePipeline;
+    vorticity: KitComputePipeline;
+    divergence: KitComputePipeline;
+    jacobi: KitComputePipeline;
+    gradSubtract: KitComputePipeline;
+    advectVel: KitComputePipeline;
+    copyVel: KitComputePipeline;
+    advectDye?: KitComputePipeline;
+    copyDye?: KitComputePipeline;
+    /**
+     * The core per-frame chain: curl → vorticity → divergence → J× jacobi → gradSubtract →
+     * advectVel → copyVel → advectDye → copyDye.
+     *
+     * Emission splats go BEFORE it, the output pass and any per-shader restoration go after. Pass
+     * `vorticity` to substitute a shader's own variant (ParticleFlow folds an ambient breeze into
+     * that pass) without giving up the rest of the chain.
+     */
+    solveSteps(opts: {
+        jacobiIters: number;
+        vorticity?: ComputeStep;
+    }): ComputeStep[];
+}
+/**
+ * Wrap a kernel set in guarded compute pipelines bound to the caller's bind group.
+ *
+ * All passes share one bind group and one 2D dispatch size, which is what makes the whole solve a
+ * flat ordered list of dispatches with no per-pass rebinding.
+ */
+export declare function createStableFluidsPasses(root: TgpuRoot, kernels: StableFluidsKernels, opts: {
+    n: number;
+    bindGroup: unknown;
+}): StableFluidsPasses;
+//# sourceMappingURL=fluids.d.ts.map

package/dist/core/gpu/scaffolds/fluids.d.ts.map

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

package/dist/core/gpu/scaffolds/lateBoundChild.d.ts

@@ -0,0 +1,51 @@
+import { GpuFragmentParams, KitTexture } from '../contract';
+
+/** The resolver the pass manager passes to `bindInputs`: texture key → bound texture. */
+type InputResolver = (key: string) => {
+    texture: unknown;
+} | undefined;
+export interface LateBoundChildInput<TGroups> {
+    /**
+     * The child's RTT handle. Put it in the compute node's `outputs` so the fragment can sample
+     * the same texture (`computeOutputs.childTexture`) instead of RTT-ing the child twice.
+     */
+    readonly childTexture: KitTexture;
+    /** Hand straight to the compute node's `bindInputs`. */
+    bindInputs: (resolve: InputResolver) => void;
+    /**
+     * The bind groups built by `buildGroups`, or `null` while the child RTT is still unallocated.
+     * The canonical first line of `getComputeNodes` is `const g = child.bound(); if (!g) return null`.
+     */
+    bound(): TGroups | null;
+    /** Boolean form of {@link bound}, for readability in tests and guards. */
+    ready(): boolean;
+}
+/**
+ * Name a compute hook's child input and defer its bind-group construction to `bindInputs`.
+ *
+ * `buildGroups` receives the resolved child texture — already cast to the type
+ * `root.createBindGroup` accepts — and returns whatever collection of bind groups the shader
+ * needs (a single group, a `{a, b}` orientation pair, an object of several). It re-runs on every
+ * recompose, so anything it allocates must be safe to rebuild.
+ *
+ * Returns `null` when the node has no child at all, so a child-REQUIRED shader can write
+ * `if (!child) return null` and inherit the "no child → no compute" branch.
+ *
+ * @example
+ * const child = createLateBoundChildInput(params, (src) => ({
+ *     bg: root.createBindGroup(layout, {src, prev: stateA, next: stateB, params: buf.buffer}),
+ * }))
+ * if (!child) return null
+ * return {
+ *     outputs: {childTexture: child.childTexture, display},
+ *     bindInputs: child.bindInputs,
+ *     getComputeNodes: () => {
+ *         const g = child.bound()
+ *         if (!g) return null
+ *         return [pipeline.with(g.bg)]
+ *     },
+ * }
+ */
+export declare function createLateBoundChildInput<TGroups>(params: GpuFragmentParams, buildGroups: (childTexture: never) => TGroups): LateBoundChildInput<TGroups> | null;
+export {};
+//# sourceMappingURL=lateBoundChild.d.ts.map

package/dist/core/gpu/scaffolds/lateBoundChild.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lateBoundChild.d.ts","sourceRoot":"","sources":["../../../src/gpu/scaffolds/lateBoundChild.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAC,iBAAiB,EAAE,UAAU,EAAC,MAAM,aAAa,CAAA;AAE9D,yFAAyF;AACzF,KAAK,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK;IAAC,OAAO,EAAE,OAAO,CAAA;CAAC,GAAG,SAAS,CAAA;AAEpE,MAAM,WAAW,mBAAmB,CAAC,OAAO;IACxC;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAA;IACjC,wDAAwD;IACxD,UAAU,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;IAC5C;;;OAGG;IACH,KAAK,IAAI,OAAO,GAAG,IAAI,CAAA;IACvB,0EAA0E;IAC1E,KAAK,IAAI,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAC7C,MAAM,EAAE,iBAAiB,EACzB,WAAW,EAAE,CAAC,YAAY,EAAE,KAAK,KAAK,OAAO,GAC9C,mBAAmB,CAAC,OAAO,CAAC,GAAG,IAAI,CAiBrC"}