shaders 3.1.462 → 3.2.464

package/dist/core/std/sim/fluids.d.ts

@@ -0,0 +1,207 @@
+import { GpuComputeNode, GpuFragmentParams } from '../../gpu/contract';
+import { ComputeStep, KitComputePipeline } from '../../gpu/compute';
+import { StableFluidsKernels } from '../../gpu/scaffolds/fluids';
+import { PointerFrame, PointerLike, PointerVelocityTrackerOptions } from '../../gpu/kit/host/pointer';
+
+/** The TypeGPU root, via the contract (direct `typegpu` imports are restricted to src/gpu/). */
+export type FluidRoot = NonNullable<GpuFragmentParams['gpu']>['root'];
+/** A 2D-dispatched TGSL kernel over the N×N grid. */
+export type FluidKernel = (cx: number, cy: number) => void;
+/** The renderer's per-frame params, as the fluid consumers read them. */
+export interface FluidFrameParams {
+    pointer?: PointerLike;
+    deltaTime?: number;
+    dimensions?: {
+        width: number;
+        height: number;
+    };
+}
+/** One frame of the simulation, handed to every part and to `values`. */
+export interface FluidFrame {
+    /** Frame delta, clamped to `maxDeltaTime` (0.033 s default). */
+    dt: number;
+    /** `Date.now()` this frame — the idle gates' clock. */
+    now: number;
+    /** Local clock: sum of clamped deltas. An init part may reset it (Fog's warm-up). */
+    readonly elapsed: number;
+    setElapsed(t: number): void;
+    /** The noun-owned tracker's sample (config `pointer`), or null. Ribbons own their own. */
+    ptr: PointerFrame | null;
+    num(key: string, fallback: number): number;
+    getCpuValue(key: string): unknown;
+    frameParams: FluidFrameParams;
+    /** Write the params uniform directly (per-stamp rewrites inside ribbon thunks). */
+    writeParams(v: unknown): void;
+}
+/** What parts get to build their pipelines against at composition time. */
+export interface FluidSetupCtx {
+    params: GpuFragmentParams;
+    root: FluidRoot;
+    /** Grid resolution per axis. */
+    n: number;
+    buffers: {
+        velA: unknown;
+        velB: unknown;
+        dyeA: unknown;
+        dyeB: unknown;
+        pressure: unknown;
+        divergence: unknown;
+        maskBuf?: unknown;
+    };
+    /** The params uniform's buffer (for a part's own bind group). */
+    paramsBuffer: unknown;
+    /** The solve bind group every solver pass runs on. */
+    fluidBindGroup: unknown;
+    /** One kernel as a guarded pass — on the fluid bind group unless another is given. */
+    pass(kernel: FluidKernel, bindGroup?: unknown): KitComputePipeline;
+}
+/** An emission part: pre-gate bookkeeping, an optional idle gate, and this frame's dispatches. */
+export interface FluidEmitter<TParams = unknown> {
+    setup?(ctx: FluidSetupCtx): void;
+    /** Pre-gate bookkeeping (pointer sampling, colour-cycle drift, markActive). */
+    tick?(f: FluidFrame): void;
+    /** Idle gate: true → the whole frame is skipped (the settled field persists on screen). */
+    skip?(f: FluidFrame): boolean;
+    /** Push this frame's emission dispatches (they run before the solve chain). */
+    emit?(f: FluidFrame, nodes: ComputeStep[], values: TParams): void;
+}
+/** A per-SOLVE stage: runs inside every solve, including an init part's warm-up steps. */
+export interface FluidSolveStage {
+    stage: 'pre' | 'post';
+    kernel: FluidKernel;
+}
+/** Ambient body force (Fog's turbulence field) — dispatched before every solve chain. */
+export declare const ambientForce: (kernel: FluidKernel) => FluidSolveStage;
+/** Restoration pass (Fog's colour re-seed against numerical diffusion) — after every solve chain. */
+export declare const restoreToward: (kernel: FluidKernel) => FluidSolveStage;
+/** What an init part gets to append with. `writeParams` returns a QUEUED thunk (device.queue order). */
+export interface FluidInitIo<TParams> {
+    nodes: ComputeStep[];
+    writeParams(v: TParams): ComputeStep;
+    solve(nodes: ComputeStep[], jacobiIters: number): void;
+}
+export interface FluidInitPart<TParams = unknown> {
+    setup?(ctx: FluidSetupCtx): void;
+    stale(f: FluidFrame): boolean;
+    run(f: FluidFrame, io: FluidInitIo<TParams>): void;
+}
+/** What a container part (SmokeFill's confining shape) contributes. */
+export interface FluidContainerParts {
+    /** The mask pass, dispatched after the params write and before emission. */
+    maskPass: KitComputePipeline;
+    /** Extra compute outputs to expose (the volumetric field texture). */
+    outputs?: Record<string, unknown>;
+    /**
+     * Per-frame pre-nodes (the volumetric field pre-march). They run FIRST, and they are what a
+     * sub-millisecond frame still returns — a pending march is never dropped.
+     */
+    preFrame?(frameParams: unknown): ComputeStep[] | null;
+}
+export interface FluidSimConfig<TParams> {
+    /** Grid resolution per axis (structural — the kernels are baked against it). */
+    resolution: number;
+    /** The shader's fluid bind-group layout (the scaffolds/fluids entry-name contract). */
+    layout: unknown;
+    /** The output pass's layout (`dyeA` read-only + `outTex`). */
+    outputLayout: unknown;
+    /** The shader's per-frame params struct. */
+    paramsSchema: unknown;
+    solver: {
+        kernels: StableFluidsKernels;
+        jacobiIters: number;
+    };
+    /** The dye→texture publish pass and the `outputs` key the fragment samples it under. */
+    output: {
+        kernel: FluidKernel;
+        key: string;
+    };
+    /** How the per-frame params reach the GPU: one direct write (default) or a queued thunk. */
+    write?: 'direct' | 'thunk';
+    /** Noun-owned pointer tracker for cursor-force consumers; ribbon emitters own their own. */
+    pointer?: PointerVelocityTrackerOptions;
+    /** Confining shape container (allocates `maskBuf`, dispatches its mask pass every frame). */
+    container?: {
+        setup(ctx: FluidSetupCtx): FluidContainerParts;
+    };
+    init?: FluidInitPart<TParams>;
+    inject?: FluidEmitter<TParams>[];
+    solve?: FluidSolveStage[];
+    /** The per-frame params derivation — the one runtime surface. */
+    values(f: FluidFrame): TParams;
+    /** Upper bound on the frame delta. Default 0.033 s (every current consumer's clamp). */
+    maxDeltaTime?: number;
+}
+/**
+ * The fluid-simulation noun. Spread it into a definition: `...fluidSim((params, root) => ({...}))`.
+ *
+ * The build callback runs at COMPUTE-NODE creation (per instance, after the no-device bail), so
+ * parts and closures created inside it are instance state.
+ */
+export declare function fluidSim<TParams>(build: (params: GpuFragmentParams, root: FluidRoot) => FluidSimConfig<TParams>): {
+    compute: GpuComputeNode;
+};
+/** A fixed-source emission pass (Smoke's cone, SmokeFill's confined cone): one dispatch per frame. */
+export declare function splat<TParams = unknown>(opts: {
+    kernel: FluidKernel;
+} | {
+    setup: (ctx: FluidSetupCtx) => KitComputePipeline;
+}): FluidEmitter<TParams>;
+/** One ribbon's stamp geometry + payload, resolved per frame. */
+export interface CursorRibbonSpec<TPrepared> {
+    /** Spacing between stamps, in viewport UV. */
+    stepSize: number;
+    /** Hard cap on stamps per frame. */
+    maxSteps: number;
+    /** Per-stamp payload advanced at BUILD time in stamp order (InkFlow's colour cycle). */
+    prepare?: (t: number) => TPrepared;
+    /** Write the stamp's uniform — runs in a thunk right before that stamp's dispatch. */
+    write: (posX: number, posY: number, t: number, prepared: TPrepared) => void;
+}
+/**
+ * Stroke emission: a pointer-velocity tracker (teleport/drag policy as data), an idle gate that
+ * freezes the sim once the field has faded after the last stroke, and a per-frame ribbon of stamps
+ * interpolated along the drag path (`pathStampRibbon` — no dotted gaps on a fast flick).
+ *
+ * The part owns its tracker; read the frame's sample back via `.ptr()` / `.active()` (SmokeFlow's
+ * `values` derives the cursor fields from them).
+ */
+export declare function cursorRibbon<TParams = unknown, TPrepared = undefined>(opts: {
+    tracker?: PointerVelocityTrackerOptions;
+    /** When emission is live this frame — a live frame marks the idle gate active. */
+    activeWhen: (ptr: PointerFrame, f: FluidFrame) => boolean;
+    /** Idle window: seconds after the last activity before the sim may freeze. */
+    fadeSeconds: (f: FluidFrame) => number;
+    /** Extra pre-gate per-frame bookkeeping (InkFlow's colour-cycle time drift). */
+    onFrame?: (f: FluidFrame, ptr: PointerFrame) => void;
+    /** The stamp pass — on the fluid bind group, or a part-owned pipeline via `setup`. */
+    pass: {
+        kernel: FluidKernel;
+    } | {
+        setup: (ctx: FluidSetupCtx) => KitComputePipeline;
+    };
+    /** This frame's ribbon geometry + payload writer. */
+    ribbon: (f: FluidFrame, ptr: PointerFrame, values: TParams) => CursorRibbonSpec<TPrepared>;
+}): FluidEmitter<TParams> & {
+    ptr(): PointerFrame | null;
+    active(): boolean;
+};
+/**
+ * Deterministic field seeding + silent warm-up (Fog): when the seed key changes (or on first
+ * frame), dispatch the init kernel and run the whole solve `warm.steps` times with time-advancing
+ * param thunks, then hand the warm clock to the frame clock so ambient forces continue seamlessly.
+ */
+export declare function seededFieldInit<TParams>(opts: {
+    kernel: FluidKernel;
+    seed: (f: FluidFrame) => number;
+    warm: {
+        steps: number;
+        jacobiIters: number;
+        /** Simulated seconds per warm step. */
+        dt: number;
+        /** The warm clock's starting value (Fog randomizes it so two instances differ). */
+        startTime: () => number;
+        /** The full params object for a warm step at simulated time `t` (t = 0 is the init write). */
+        values: (t: number, f: FluidFrame) => TParams;
+    };
+}): FluidInitPart<TParams>;
+//# sourceMappingURL=fluids.d.ts.map

package/dist/core/std/sim/fluids.d.ts.map

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

package/dist/core/std/sim/grids.d.ts

@@ -0,0 +1,161 @@
+import { GpuComputeNode, GpuFragmentParams } from '../../gpu/contract';
+import { ComputeStep } from '../../gpu/compute';
+
+/** The TypeGPU root, via the contract (direct `typegpu` imports are restricted to src/gpu/). */
+export type GridRoot = NonNullable<GpuFragmentParams['gpu']>['root'];
+/** The renderer's per-frame params, as the grid consumers read them. */
+export interface GridFrameParams {
+    pointer?: {
+        x: number;
+        y: number;
+    };
+    deltaTime?: number;
+    dimensions?: {
+        width: number;
+        height: number;
+    };
+}
+/** One frame of the simulation, handed to every stage. */
+export interface GridFrame {
+    /** `fp.deltaTime ?? 0`, clamped to `clampDt`. */
+    dt: number;
+    /** `Date.now()` this frame — the settle gates' clock. */
+    now: number;
+    num(key: string, fallback: number): number;
+    getCpuValue(key: string): unknown;
+    frameParams: GridFrameParams;
+}
+/** One stage of the frame program. Phases run in order: ready → tick → skip → emit. */
+export interface GridStage {
+    /** Frame gate: false → the whole frame returns null (a late-bound input is still pending). */
+    ready?(): boolean;
+    /** Pre-gate bookkeeping (pointer smoothing, activity flags). */
+    tick?(f: GridFrame): void;
+    /** Settle gate: true → skip the frame entirely (the last published texture persists). */
+    skip?(f: GridFrame): boolean;
+    /** Push this stage's dispatches / uniform writes. */
+    emit?(f: GridFrame, nodes: ComputeStep[]): void;
+}
+export interface GridSimConfig {
+    /** Compute outputs the fragment samples (state/display textures, child RTT handles). */
+    outputs: Record<string, unknown>;
+    /** Late input binding (child RTT → luma prepass, child-modulated kernels). Spread only if set. */
+    bindInputs?: (resolve: (key: string) => {
+        texture: unknown;
+    } | undefined) => void;
+    /** Frame-delta clamp (seconds). */
+    clampDt: number;
+    /** Frames with `dt <= 0`: run anyway (default) or skip (Liquify's guard). */
+    zeroDt?: 'run' | 'skip';
+    stages: GridStage[];
+}
+/**
+ * The grid-simulation noun. Spread it into a definition: `...gridSim((params, root) => ({...}))`.
+ * The build callback runs at compute-node creation (per instance, after the no-device bail); it may
+ * return null to opt out entirely (a required child is missing).
+ */
+export declare function gridSim(build: (params: GpuFragmentParams, root: GridRoot) => GridSimConfig | null): {
+    compute: GpuComputeNode;
+};
+/** A parity-alternating sort chain's handle: which ping-pong side is current after this frame. */
+export interface SortPassStage extends GridStage {
+    side(): 'A' | 'B';
+}
+export declare const op: {
+    /** Named pre-gate host step (pointer smoothing, activity flags). Runs in the tick phase. */
+    readonly host: (name: string, run: (f: GridFrame) => void) => GridStage;
+    /** Named emit-phase host step (per-frame uniform writes / prop derivation). */
+    readonly values: (name: string, run: (f: GridFrame) => void) => GridStage;
+    /**
+     * Settle gate: once nothing has driven the sim for `settleMs`, skip frames entirely — the last
+     * published texture persists on screen, so a settled sim costs zero GPU time.
+     */
+    readonly settle: (opts: {
+        activeWhen: (f: GridFrame) => boolean;
+        settleMs: (f: GridFrame) => number;
+    }) => GridStage;
+    /** Frame gate on a late-bound input (child RTT arriving via `bindInputs`). */
+    readonly readyWhen: (fn: () => boolean) => GridStage;
+    /** One dispatch of a fixed pass. */
+    readonly pass: (step: ComputeStep) => GridStage;
+    /** A per-frame cache prepass, resolved per frame (PixelSort's late-rebound child-luma snapshot). */
+    readonly cache: (step: (f: GridFrame) => ComputeStep) => GridStage;
+    /** The publish tail: write the sim state into the texture the fragment samples. Resolved per
+     *  frame so it can follow a ping-pong side (`() => output.with(side() === 'A' ? bgA : bgB)`). */
+    readonly publish: (step: (f: GridFrame) => ComputeStep) => GridStage;
+    /** One-shot (re)initialisation ahead of the step loop, latched on `staleWhen`. */
+    readonly seedOnce: (opts: {
+        pass: ComputeStep;
+        staleWhen: (f: GridFrame) => boolean;
+        onSeed?: () => void;
+    }) => GridStage;
+    /** N ordered iterations of a step (the caller's `step` handles its own ping-pong swap). */
+    readonly iterate: (opts: {
+        count: (f: GridFrame) => number;
+        step: (i: number, nodes: ComputeStep[], f: GridFrame) => void;
+    }) => GridStage;
+    /**
+     * Odd-even transposition sort chain: `passes` compare-swap dispatches, alternating parity and
+     * ping-pong side per pass. The parity tick PERSISTS across frames (harness policy — a new frame
+     * continues the transposition sequence where the last one stopped, which is what makes the sort
+     * converge "bit by bit"). `side()` reports the current buffer for the publish pass.
+     */
+    readonly sortPass: (opts: {
+        passes: (f: GridFrame) => number;
+        pass: (parity: 0 | 1, side: "A" | "B") => ComputeStep;
+    }) => SortPassStage;
+};
+/**
+ * Viewport dimensions with the standard resize-tracked fallback: `tracked()` is the last
+ * `onResize` value (what a texture-space prepass wants), `safe(fp)` prefers this frame's reported
+ * dimensions and floors both at 1 (what an aspect computation wants).
+ */
+export declare function trackedViewport(params: GpuFragmentParams): {
+    tracked(): {
+        width: number;
+        height: number;
+    };
+    safe(fp: GridFrameParams): {
+        width: number;
+        height: number;
+    };
+};
+/** One frame of a CPU grid program. */
+export interface HostFrame {
+    /** Wall-clock delta since the last frame, clamped (these sims ignore the renderer's deltaTime). */
+    dt: number;
+    now: number;
+    pointer: {
+        x: number;
+        y: number;
+    };
+    frameParams: unknown;
+}
+/** A named CPU step. Return `'skip'` to end the frame (idle gate). */
+export interface HostStep {
+    name: string;
+    run(f: HostFrame): void | 'skip';
+}
+export declare const hostStep: (name: string, run: (f: HostFrame) => void | "skip") => HostStep;
+/**
+ * An ordered CPU frame program for `onBeforeRender`: wall-clock dt (clamped), then each named step
+ * in order until one skips.
+ */
+export declare function hostGridProgram(opts: {
+    clampDt: number;
+    steps: HostStep[];
+}): (fp: unknown) => void;
+/**
+ * The CPU field's GPU face: an rgba16float data texture (filterable — a filtering sampler rejects
+ * r32float, so cells are half-encoded before upload) registered as a media texture the fragment
+ * samples. `texData` is the upload staging buffer the publish step packs into.
+ */
+export declare function hostFieldTexture(params: GpuFragmentParams, opts: {
+    size: number;
+    label: string;
+}): {
+    texData: Uint16Array;
+    texture: ReturnType<GpuFragmentParams['registerMediaTexture']>;
+    upload(): void;
+};
+//# sourceMappingURL=grids.d.ts.map

package/dist/core/std/sim/grids.d.ts.map

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

package/dist/core/std/sim/shapeFields.d.ts

@@ -0,0 +1,87 @@
+import { d } from '../../gpu/kit/index';
+import { ShapeField3 } from './agentForces';
+
+/** The analytic 2D SDF menu's call shape (`sdf.buildAnalyticSdfFn`). */
+type AnalyticSdf2d = (uv: d.v2f, radius: number, sides: number, rounding: number, innerRatio: number, rotation: number, height: number, offset: number, aperture: number) => {
+    readonly x: number;
+};
+/** Params view for the extruded flat-shape fields: the CPU-resolved analytic sub-prop bundle
+ *  (the driveAnalyticSubProps convention) plus the extrusion half-depth. */
+interface ExtrudedAnalyticParamsView {
+    readonly saRadius: number;
+    readonly saSides: number;
+    readonly saRounding: number;
+    readonly saInnerRatio: number;
+    readonly saRotation: number;
+    readonly saHeight: number;
+    readonly saOffset: number;
+    readonly saAperture: number;
+    readonly halfDepth: number;
+}
+/** The per-axis sin/cos rotation bundle the sdf3d MarchParams carry. */
+interface RotSinCosView {
+    readonly cx: number;
+    readonly sx: number;
+    readonly cy: number;
+    readonly sy: number;
+    readonly cz: number;
+    readonly sz: number;
+}
+/** A layout whose MarchParams uniform carries the shape rotation (the sdf3d setups). */
+interface RotatedFieldLayout {
+    readonly $: {
+        readonly params: {
+            readonly rot: RotSinCosView;
+        };
+    };
+}
+/**
+ * Flat analytic shape extruded in z: the baked 2D SDF evaluated in shape-local uv (y up →
+ * v down), sub-props read live from `params.sa*`, rounded-extruded over `params.halfDepth`.
+ */
+declare function analyticExtruded(layout: {
+    readonly $: {
+        readonly params: ExtrudedAnalyticParamsView;
+    };
+}, sdf2d: AnalyticSdf2d): ShapeField3;
+/**
+ * Flat SVG outline extruded in z (nearest texel read — plenty for containment forces).
+ * Beyond the SDF texture's ±0.5 footprint the clamped field is flat (or, under a feature
+ * touching the border, even reads INSIDE) — which strands strays and draws plumb-line
+ * columns — so the field is extended with the exact distance to the footprint box, keeping
+ * magnitude + direction valid everywhere the swarm can roam.
+ */
+declare function svgExtruded(layout: {
+    readonly $: {
+        readonly params: {
+            readonly halfDepth: number;
+        };
+    };
+}, svgLayout: {
+    readonly $: {
+        readonly sdfSource: d.Infer<d.WgslTexture2d<d.F32>>;
+    };
+}, cfg: {
+    size: number;
+}): ShapeField3;
+/**
+ * True analytic 3D volume: the setup's baked SDF sampled at the rotated point — rotation
+ * (and any CPU-animated sub-props) arrive through the setup's MarchParams uniform, so the
+ * field moves under the swarm exactly like the marched render would.
+ */
+declare function analytic3d(layout: RotatedFieldLayout, baked: ShapeField3): ShapeField3;
+/**
+ * SVG lifted into 3D (the bevel-extruding SVG-3D setup's SDF), rotated by MarchParams and —
+ * like the flat SVG field — extended beyond the SDF texture's footprint with the exact
+ * distance to the footprint box (the clamped field is flat out there: zero gradient, and a
+ * border-touching feature can even read inside).
+ */
+declare function svgLifted3d(layout: RotatedFieldLayout, baked: ShapeField3): ShapeField3;
+export declare const shapeField: {
+    readonly analyticExtruded: typeof analyticExtruded;
+    readonly svgExtruded: typeof svgExtruded;
+    readonly analytic3d: typeof analytic3d;
+    readonly svgLifted3d: typeof svgLifted3d;
+};
+export {};
+//# sourceMappingURL=shapeFields.d.ts.map

package/dist/core/std/sim/shapeFields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapeFields.d.ts","sourceRoot":"","sources":["../../../src/std/sim/shapeFields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAO,CAAC,EAAa,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,eAAe,CAAA;AAU9C,wEAAwE;AACxE,KAAK,aAAa,GAAG,CACjB,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAC9E,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KACjE;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CAAC,CAAA;AAEzB;4EAC4E;AAC5E,UAAU,0BAA0B;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC7B;AAED,wEAAwE;AACxE,UAAU,aAAa;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CACtB;AAED,wFAAwF;AACxF,UAAU,kBAAkB;IACxB,QAAQ,CAAC,CAAC,EAAE;QAAC,QAAQ,CAAC,MAAM,EAAE;YAAC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAA;SAAC,CAAA;KAAC,CAAA;CAC/D;AAED;;;GAGG;AACH,iBAAS,gBAAgB,CACrB,MAAM,EAAE;IAAC,QAAQ,CAAC,CAAC,EAAE;QAAC,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAA;KAAC,CAAA;CAAC,EACnE,KAAK,EAAE,aAAa,GACrB,WAAW,CAQb;AAED;;;;;;GAMG;AACH,iBAAS,WAAW,CAChB,MAAM,EAAE;IAAC,QAAQ,CAAC,CAAC,EAAE;QAAC,QAAQ,CAAC,MAAM,EAAE;YAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAAA;CAAC,EACrE,SAAS,EAAE;IAAC,QAAQ,CAAC,CAAC,EAAE;QAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;KAAC,CAAA;CAAC,EAC9E,GAAG,EAAE;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GACpB,WAAW,CAcb;AAED;;;;GAIG;AACH,iBAAS,UAAU,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAK/E;AAED;;;;;GAKG;AACH,iBAAS,WAAW,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAQhF;AAED,eAAO,MAAM,UAAU;;;;;CAKb,CAAA"}

package/dist/core/std/sim.d.ts

@@ -0,0 +1,62 @@
+import { PropRef } from './values';
+import { PointerSignal, PointerSpeedSignal } from './signal';
+
+/** Damped `avg − prev` wave propagation. Needs `history: 2` (reads t−1 AND t−2). */
+export interface WaveOp {
+    readonly kind: 'op.wave';
+    readonly damping: PropRef;
+}
+/** Gaussian brush injection at a positioned signal, scaled by an amount signal. */
+export interface SplatOp {
+    readonly kind: 'op.splat';
+    readonly at: PointerSignal;
+    readonly amount: PointerSpeedSignal;
+    readonly radius: PropRef;
+}
+/** Central-difference gradient of the field → an RG vector-field texture (a derive op). */
+export interface GradientOp {
+    readonly kind: 'op.gradient';
+}
+export type GridStepOp = WaveOp | SplatOp;
+export type GridDeriveOp = GradientOp;
+export declare const op: {
+    readonly wave: (config: {
+        damping: PropRef;
+    }) => WaveOp;
+    readonly splat: (config: {
+        at: PointerSignal;
+        amount: PointerSpeedSignal;
+        radius: PropRef;
+    }) => SplatOp;
+    readonly gradient: () => GradientOp;
+};
+export interface GridSimConfig {
+    /** Square grid resolution (state texels per side). */
+    resolution: number;
+    /** History levels the step ops read (the wave equation needs 2: t−1 and t−2). */
+    history: number;
+    /** Ordered per-texel step ops, run once per frame. */
+    step: GridStepOp[];
+    /** Named derived outputs, consumable as fields by effects (`sim.output(name)`). */
+    derive: Record<string, GridDeriveOp>;
+    /** Rest semantics: when the engine may stop dispatching. */
+    rest?: {
+        settlesWhen: 'derived-from-damping';
+    };
+}
+/** A reference to one of a simulation's derived outputs (feeds effect slots). */
+export interface SimOutputRef {
+    readonly kind: 'simOutput';
+    readonly sim: GridSim;
+    readonly output: string;
+}
+/** A declared grid simulation. Reference its outputs by identity: `sim.output('name')`. */
+export declare class GridSim {
+    readonly config: GridSimConfig;
+    constructor(config: GridSimConfig);
+    output(name: string): SimOutputRef;
+}
+export declare const simulate: {
+    readonly grid: (config: GridSimConfig) => GridSim;
+};
+//# sourceMappingURL=sim.d.ts.map

package/dist/core/std/sim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim.d.ts","sourceRoot":"","sources":["../../src/std/sim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,UAAU,CAAA;AACrC,OAAO,KAAK,EAAC,aAAa,EAAE,kBAAkB,EAAC,MAAM,UAAU,CAAA;AAI/D,oFAAoF;AACpF,MAAM,WAAW,MAAM;IACnB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC5B;AAED,mFAAmF;AACnF,MAAM,WAAW,OAAO;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAC3B;AAED,2FAA2F;AAC3F,MAAM,WAAW,UAAU;IACvB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAC/B;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,CAAA;AACzC,MAAM,MAAM,YAAY,GAAG,UAAU,CAAA;AAErC,eAAO,MAAM,EAAE;4BACE;QAAC,OAAO,EAAE,OAAO,CAAA;KAAC,KAAG,MAAM;6BAG1B;QAAC,EAAE,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,kBAAkB,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAC,KAAG,OAAO;6BAG5E,UAAU;CAGhB,CAAA;AAIV,MAAM,WAAW,aAAa;IAC1B,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAA;IAClB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAA;IACf,sDAAsD;IACtD,IAAI,EAAE,UAAU,EAAE,CAAA;IAClB,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACpC,4DAA4D;IAC5D,IAAI,CAAC,EAAE;QAAC,WAAW,EAAE,sBAAsB,CAAA;KAAC,CAAA;CAC/C;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAC1B;AAED,2FAA2F;AAC3F,qBAAa,OAAO;IACJ,QAAQ,CAAC,MAAM,EAAE,aAAa;gBAArB,MAAM,EAAE,aAAa;IAE1C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;CAMrC;AAED,eAAO,MAAM,QAAQ;4BACJ,aAAa,KAAG,OAAO;CAG9B,CAAA"}

package/dist/core/std/slots.d.ts

@@ -0,0 +1,15 @@
+import { IdentityRule, RecompileRule } from './types';
+
+/** Recompose only when the prop value crosses `value` (identity ↔ effect boundary). */
+export declare function crosses(value: number): RecompileRule;
+/** Recompose when a bespoke predicate flips — the recompile escape hatch. */
+export declare function recompileWhen(predicate: (prev: any, next: any) => boolean): RecompileRule;
+/** The effect is a provable no-op when `prop` (or its default when unset) is exactly 0. */
+export declare function isZero(prop: string): IdentityRule;
+/** The effect is a provable no-op when `prop` (or its default when unset) equals `value`. */
+export declare function isValue(prop: string, value: unknown): IdentityRule;
+/** The effect is a no-op only when EVERY rule holds (multi-prop identities). */
+export declare function allOf(...rules: IdentityRule[]): IdentityRule;
+/** Identity escape hatch: a bespoke predicate over the listed props' CPU values. */
+export declare function identityWhenever(props: string[], when: (values: Record<string, unknown>) => boolean): IdentityRule;
+//# sourceMappingURL=slots.d.ts.map

package/dist/core/std/slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../src/std/slots.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAC,YAAY,EAAE,aAAa,EAAC,MAAM,SAAS,CAAA;AAExD,uFAAuF;AACvF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAEpD;AAED,6EAA6E;AAE7E,wBAAgB,aAAa,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,KAAK,OAAO,GAAG,aAAa,CAEzF;AAED,2FAA2F;AAC3F,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAEjD;AAED,6FAA6F;AAC7F,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,CAElE;AAED,gFAAgF;AAChF,wBAAgB,KAAK,CAAC,GAAG,KAAK,EAAE,YAAY,EAAE,GAAG,YAAY,CAE5D;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GAAG,YAAY,CAElH"}