shaders 3.0.453 → 3.1.455

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

@@ -0,0 +1,77 @@
+import { ComponentProps } from '../../types';
+import { Expr, GpuFragmentParams, GpuShaderDefinition } from '../contract';
+
+/**
+ * A `'use gpu'` body fn plus the name hint it resolves under. The hint LANDS IN THE EMITTED WGSL,
+ * so it is part of every shader's snapshot — keep it equal to the exported fn's variable name.
+ */
+export interface FilterBody {
+    /** The `tgpu.fn`. Typed `unknown` to match `call`'s signature (no TgpuFn import needed here). */
+    fn: unknown;
+    hint: string;
+}
+/**
+ * A filter's identity (no-op) condition, driving both the `compileTimeWhen` recompose and the
+ * bypass. Declare the identity here rather than hand-rolling the `if` in a fragment: the scaffold
+ * applies the right bypass for its alpha convention and adds the map-driver guard below.
+ *
+ * MAP-DRIVER GUARD (why `props` is required): `propValues` carries a prop's BASE CPU value and is
+ * deliberately driver-unaware (`composer.ts propValuesFor` reads the handle mirror). A prop with a
+ * MAP driver varies per pixel around that base, so bypassing on the base value would make the map
+ * dead. The scaffold therefore refuses the bypass when any listed prop is map-driven
+ * (`getMapInfo(prop) !== null`).
+ *
+ * KNOWN GAP (needs a contract change — `planning/PRIMITIVES_PLAN.md` Phase 12): mouse/auto
+ * drivers are NOT detectable from a fragment builder. A prop whose base value is the identity but
+ * which is mouse/auto-driven still gets bypassed, so the driver appears dead until the base value
+ * changes. This predates the scaffold (Saturation/HueShift/Sharpness shipped with it); the fix is
+ * to expose driver presence on `GpuFragmentParams`, at which point this one method covers all
+ * consumers at once.
+ */
+export interface FilterIdentity {
+    /** Every prop `when` reads. A map driver on any of them disables the bypass. */
+    props: string[];
+    /** True when the filter is a provable no-op at these CPU values. */
+    when: (propValues: Record<string, unknown>) => boolean;
+}
+/** `GpuFragmentParams` narrowed to the post-guard state: the child is present. */
+export interface FilterParams extends GpuFragmentParams {
+    childNode: Expr;
+}
+export interface PointwiseFilterConfig<T extends ComponentProps = ComponentProps> extends Omit<GpuShaderDefinition<T>, 'fragment' | 'requiresRTT' | 'requiresChild' | 'uvRemap'> {
+    /**
+     * The body fn, or a picker reading compile-time `propValues` when the shader has a body PAIR
+     * (Tint's plain/preserve-luminosity variants). Only the picked body emits into the WGSL, so the
+     * selecting prop MUST be `compileTime: true`.
+     */
+    body: FilterBody | ((propValues: Record<string, unknown>) => FilterBody);
+    /**
+     * The body's arguments AFTER the child colour (which is always first). Gets the whole builder
+     * params so a filter can read `ctx` (Vignette's `ctx.uv`/`ctx.aspect`, FilmGrain's viewport)
+     * alongside `uniforms`.
+     */
+    args?: (params: FilterParams) => Expr[];
+    /** Builder-level work on the body's RESULT — colour-space mixes, a palette branch, a tail call. */
+    compose?: (result: Expr, params: FilterParams) => Expr;
+    /** The no-op condition. Omit for a filter with no identity (Invert, Grayscale, Posterize). */
+    identity?: FilterIdentity;
+    /**
+     * Message for the missing-child `console.error`. Omit to fail SILENTLY (still returns `ZERO`) —
+     * preserve whichever each shader does today; these strings are user-facing.
+     */
+    missingChildMessage?: string;
+    /**
+     * Per-composition side effects that are not part of the returned Expr — registering an
+     * `onBeforeRender` to drive an `extraFields` value (FilmGrain's grain clock). Runs after the
+     * guard and only on the non-identity path (nothing to drive when the filter is bypassed).
+     */
+    setup?: (params: FilterParams) => void;
+}
+/** Build a complete pointwise colour-filter definition. See the module header for the recipe. */
+export declare function definePointwiseFilter<T extends ComponentProps = ComponentProps>(config: PointwiseFilterConfig<T>): GpuShaderDefinition<T>;
+/**
+ * Shared identity test for both filter scaffolds: the declared condition AND no map driver on any
+ * prop it reads (see {@link FilterIdentity}).
+ */
+export declare function isFilterIdentity(identity: FilterIdentity | undefined, params: GpuFragmentParams): boolean;
+//# sourceMappingURL=pointwiseFilter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pointwiseFilter.d.ts","sourceRoot":"","sources":["../../../src/gpu/scaffolds/pointwiseFilter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,aAAa,CAAA;AAE/C,OAAO,KAAK,EAAC,IAAI,EAAE,iBAAiB,EAAE,mBAAmB,EAAC,MAAM,aAAa,CAAA;AAE7E;;;GAGG;AACH,MAAM,WAAW,UAAU;IACvB,iGAAiG;IACjG,EAAE,EAAE,OAAO,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC3B,gFAAgF;IAChF,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,oEAAoE;IACpE,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAA;CACzD;AAED,kFAAkF;AAClF,MAAM,WAAW,YAAa,SAAQ,iBAAiB;IACnD,SAAS,EAAE,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,CAC5E,SAAQ,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,UAAU,GAAG,aAAa,GAAG,eAAe,GAAG,SAAS,CAAC;IAC9F;;;;OAIG;IACH,IAAI,EAAE,UAAU,GAAG,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,UAAU,CAAC,CAAA;IACxE;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,EAAE,CAAA;IACvC,mGAAmG;IACnG,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,CAAA;IACtD,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAA;CACzC;AAED,iGAAiG;AACjG,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EAC3E,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,GACjC,mBAAmB,CAAC,CAAC,CAAC,CAkBxB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAMzG"}

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

@@ -0,0 +1,35 @@
+import { ComponentProps } from '../../types';
+import { Expr, GpuFragmentParams, GpuShaderDefinition, KitTexture } from '../contract';
+import { FilterIdentity } from './pointwiseFilter';
+
+/** `GpuFragmentParams` plus the child's RTT — what an RTT filter's `build` hook works with. */
+export interface RttFilterParams extends GpuFragmentParams {
+    childNode: Expr;
+    /** The composed child as a texture. PREMULTIPLIED — see the module header. */
+    texture: KitTexture;
+    /**
+     * Sample the child RTT and unpremultiply → STRAIGHT alpha. For a filter whose math must run on
+     * straight colour (a luminance threshold, a colour quantiser). A filter doing linear-in-RGB
+     * work (a convolution) should sample `texture` directly and stay premultiplied throughout.
+     */
+    sampleStraight: (uv: Expr) => Expr;
+}
+export interface RttFilterConfig<T extends ComponentProps = ComponentProps> extends Omit<GpuShaderDefinition<T>, 'fragment' | 'requiresRTT' | 'requiresChild'> {
+    /** Build the filtered colour from the child RTT. Returns premultiplied unless `resultAlpha`. */
+    build: (params: RttFilterParams) => Expr;
+    /**
+     * The alpha convention of `build`'s return value. `'premultiplied'` (default) → the scaffold
+     * appends `blend.unpremultiplyAlpha`. `'straight'` → returned as-is, for a filter that already
+     * unpremultiplied its taps via `sampleStraight`.
+     */
+    resultAlpha?: 'premultiplied' | 'straight';
+    /** The no-op condition. Bypasses to a centre sample, NOT to `childNode` — see the header. */
+    identity?: FilterIdentity;
+    /** Message for the missing-child `console.error`. Omit to fail silently (still returns `ZERO`). */
+    missingChildMessage?: string;
+    /** Per-composition side effects (an `onBeforeRender` driving an `extraFields` value). */
+    setup?: (params: RttFilterParams) => void;
+}
+/** Build a complete RTT filter definition. See the module header for the alpha contract. */
+export declare function defineRttFilter<T extends ComponentProps = ComponentProps>(config: RttFilterConfig<T>): GpuShaderDefinition<T>;
+//# sourceMappingURL=rttFilter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rttFilter.d.ts","sourceRoot":"","sources":["../../../src/gpu/scaffolds/rttFilter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,aAAa,CAAA;AAE/C,OAAO,KAAK,EAAC,IAAI,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,UAAU,EAAC,MAAM,aAAa,CAAA;AAEzF,OAAO,EAAmB,KAAK,cAAc,EAAC,MAAM,mBAAmB,CAAA;AAEvE,+FAA+F;AAC/F,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACtD,SAAS,EAAE,IAAI,CAAA;IACf,8EAA8E;IAC9E,OAAO,EAAE,UAAU,CAAA;IACnB;;;;OAIG;IACH,cAAc,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,IAAI,CAAA;CACrC;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,CACtE,SAAQ,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,UAAU,GAAG,aAAa,GAAG,eAAe,CAAC;IAClF,gGAAgG;IAChG,KAAK,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC;;;;OAIG;IACH,WAAW,CAAC,EAAE,eAAe,GAAG,UAAU,CAAA;IAC1C,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,mGAAmG;IACnG,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,yFAAyF;IACzF,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAA;CAC5C;AAED,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EACrE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,GAC3B,mBAAmB,CAAC,CAAC,CAAC,CAsBxB"}

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

@@ -0,0 +1,98 @@
+import { GpuShaderDefinition } from '../contract';
+import { BoundingBoxBindingType, BoundingBoxDeclaration, ComponentProps, PropConfig } from '../../types';
+import { shapeStrokeProps } from '../../utilities/propConfigs';
+
+/**
+ * Any prop config, whatever the prop's value type. Shape props are heterogeneous by nature (a
+ * number, a `DimensionalValue`, a colour string), and the factory only ever moves them around, so
+ * the value type is deliberately unconstrained here — the shader's own `ComponentProps` interface is
+ * where the per-prop types are stated.
+ */
+type AnyPropConfig = PropConfig<any>;
+/**
+ * How the shape's bounding box is declared.
+ *
+ * `size` is the declarative form thirteen shapes use: x/y bind `center`, width/height bind the
+ * named size props, and rotation binds `rotation` unless `rotatable: false`. `as` defaults to
+ * `'half-canvas-height'` (the prop is a half-extent); Circle passes `'canvas-height'` because its
+ * `radius` names the full visual size and the shader halves it internally.
+ *
+ * `custom` is the escape hatch for the two shapes whose box cannot be read off a single prop: Ring
+ * (outer edge = midline radius + half-band thickness) and Trapezoid (visual width = the WIDER of
+ * its two edges). Those pass a complete `BoundingBoxDeclaration` — `computeBounds` / `writeBounds`
+ * are per-shape geometry, not something a factory can infer.
+ */
+export type SdfShapeBounds = {
+    size: {
+        width: string;
+        height: string;
+        as?: BoundingBoxBindingType;
+    };
+    custom?: never;
+} | {
+    custom: BoundingBoxDeclaration;
+    size?: never;
+};
+export interface SdfShapeShaderSpec {
+    name: string;
+    description: string;
+    /** Defaults to `'Shapes'`. */
+    category?: string;
+    /**
+     * The `'use gpu'` mask body fn, defined in the shader file (see the file header for the
+     * template and the argument-order contract). Returns a `sdf.ShapeMask`.
+     */
+    shapeFn: unknown;
+    /**
+     * The `call` hint for `shapeFn` — must stay equal to the fn's emitted WGSL name (`'starShape'`),
+     * because that name appears in the WGSL snapshots.
+     */
+    shapeFnName: string;
+    /**
+     * The uniform prop names `shapeFn` takes between `center` and `softness`, in BODY order —
+     * including `rotation` for a rotatable shape. This is a separate list from `shapeProps` because
+     * the two orders can differ (Trapezoid declares `bottomWidth, topWidth, height` but its body
+     * takes `topWidth, bottomWidth, height`).
+     */
+    bodyArgs: string[];
+    /** The `color` prop's description ("Fill color of the star"). */
+    colorDescription: string;
+    /** The `center` prop's description ("Center position of the star"). */
+    centerDescription: string;
+    /** Circle labels its center prop 'Center Position'; the rest use the factory default. */
+    centerLabel?: string;
+    /** The 1–3 props that make this shape itself, in declaration order. */
+    shapeProps: Record<string, AnyPropConfig>;
+    /** `false` for the rotationally symmetric shapes (Circle, Ring): no rotation prop, no rotation box axis. */
+    rotatable?: boolean;
+    /** Cross explains the 45° case; everything else uses the default wording. */
+    rotationDescription?: string;
+    bounds: SdfShapeBounds;
+    /** Passed straight to `shapeStrokeProps` (Ring's wording + max, Circle's wording). */
+    stroke?: Parameters<typeof shapeStrokeProps>[0];
+    /** Circle's `colorSpace` description mentions soft edges. */
+    colorSpaceDescription?: string;
+    /**
+     * Prop configs that REPLACE a factory-built one, keyed by prop name. Spread last, so a replaced
+     * prop keeps its position in the key order. Circle uses this for its widened, map-driveable
+     * `softness` / `strokeThickness`.
+     */
+    propOverrides?: Record<string, AnyPropConfig>;
+    /**
+     * Explicit prop key order, when the shader's current order is not the fleet-canonical one.
+     * Must list every prop exactly once — a mismatch throws, because a silently dropped prop would
+     * change the uniform struct.
+     */
+    propOrder?: string[];
+}
+/**
+ * Build a complete analytic-2D-shape shader definition from its shape props, its mask body fn and
+ * its box declaration.
+ *
+ * The emitted definition is byte-identical to the hand-written one for all fifteen migrated shapes
+ * (Gate A): same props in the same order, same `boundingBoxDeclaration`, and a fragment that emits
+ * the same `call` sequence.
+ */
+export declare function defineSdfShapeShader<T extends ComponentProps = ComponentProps>(spec: SdfShapeShaderSpec): GpuShaderDefinition<T>;
+export {};
+//# sourceMappingURL=sdfShape.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sdfShape.d.ts","sourceRoot":"","sources":["../../../src/gpu/scaffolds/sdfShape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,OAAO,KAAK,EAA0B,mBAAmB,EAAC,MAAM,aAAa,CAAA;AAG7E,OAAO,KAAK,EACR,sBAAsB,EACtB,sBAAsB,EAEtB,cAAc,EACd,UAAU,EACb,MAAM,aAAa,CAAA;AAEpB,OAAO,EAIH,gBAAgB,EACnB,MAAM,6BAA6B,CAAA;AAEpC;;;;;GAKG;AAEH,KAAK,aAAa,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;AAEpC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GACpB;IAAC,IAAI,EAAE;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,sBAAsB,CAAA;KAAC,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAC,GACpF;IAAC,MAAM,EAAE,sBAAsB,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAC,CAAA;AAEpD,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAA;IAElB,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,CAAA;IACxB,uEAAuE;IACvE,iBAAiB,EAAE,MAAM,CAAA;IACzB,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IAEzC,4GAA4G;IAC5G,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAE5B,MAAM,EAAE,cAAc,CAAA;IAEtB,sFAAsF;IACtF,MAAM,CAAC,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAA;IAC/C,6DAA6D;IAC7D,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAE9B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IAC7C;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB;AAuDD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EAC1E,IAAI,EAAE,kBAAkB,GACzB,mBAAmB,CAAC,CAAC,CAAC,CA8CxB"}

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

@@ -0,0 +1,16 @@
+import { d } from '../kit';
+
+/**
+ * The legacy sin-fract hash, mapping a float to [-1, 1].
+ *
+ * `fract(sin(x · 12.9898) · 43758.5453)` is the classic GLSL one-liner; the `(· − 0.5) · 2` tail
+ * re-centres it. BarShift (`barHash`) and ConcentricSpin (`csHash`) declared this byte-identically,
+ * which is what makes deduping it safe.
+ *
+ * TRAP: this is NOT `noise.hash11` and must not be swapped for it. The bit-exact integer hashes in
+ * `kit/noise.ts` produce a different sequence, so substituting one changes every consumer's look.
+ * Hash policy (PRIMITIVES.md, D-6) is that existing shaders keep this one and NEW shaders use
+ * `noise.hash*`.
+ */
+export declare const legacySinHash11: import('typegpu').TgpuFn<(x: d.F32) => d.F32>;
+//# sourceMappingURL=shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/gpu/scaffolds/shared.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAO,CAAC,EAAM,MAAM,QAAQ,CAAA;AAEnC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,+CAG1B,CAAA"}

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

@@ -0,0 +1,61 @@
+import { d } from '../kit';
+
+/**
+ * Plain Gaussian brush weight from a PRE-SQUARED distance and radius: `exp(-distSq / radiusSq)`.
+ *
+ * Peaks at 1 in the centre and never reaches zero — cells outside the nominal radius still receive
+ * ~37% and below. This is what the fluid splats shipped with before the edge-shifted form existed;
+ * it stays available because a few consumers deliberately want the long tail.
+ *
+ * `radiusSq` must already be guarded (`max(r*r, eps)`) by the caller — the grid-space consumers
+ * clamp to one cell (`max(r*r, 1.0)`), which is a different floor than a UV-space consumer wants.
+ */
+export declare const gaussianBrushSq: import('typegpu').TgpuFn<(distSq: d.F32, radiusSq: d.F32) => d.F32>;
+/**
+ * Edge-shifted Gaussian brush weight: `(exp(-distSq/radiusSq) - e⁻¹) / (1 - e⁻¹)`, clamped to
+ * [0, 1].
+ *
+ * Still exactly 1 at the centre, but falls to exactly 0 at `distSq == radiusSq` and is clamped flat
+ * beyond it — no truncation step, no staircase. PixelThrow's CPU sim has had this since it shipped;
+ * D-8 propagates it to the GPU brush sites.
+ */
+export declare const gaussianBrushShiftedSq: import('typegpu').TgpuFn<(distSq: d.F32, radiusSq: d.F32) => d.F32>;
+/** Vector form of {@link gaussianBrushSq} — takes the cell and brush centres. */
+export declare const gaussianBrushRaw: import('typegpu').TgpuFn<(cellPos: d.Vec2f, center: d.Vec2f, radiusSq: d.F32) => d.F32>;
+/** Vector form of {@link gaussianBrushShiftedSq} — takes the cell and brush centres. */
+export declare const gaussianBrushShifted: import('typegpu').TgpuFn<(cellPos: d.Vec2f, center: d.Vec2f, radiusSq: d.F32) => d.F32>;
+/**
+ * The edge-shifted brush at a given TRUNCATION RADIUS, expressed in sigmas.
+ *
+ * `radiusSq` is always σ² — the Gaussian's own scale. `cutoffSigmas` is how far out the CALLER stops
+ * evaluating, and it sets the edge constant to `exp(-cutoffSigmas²)` so the falloff reaches exactly
+ * zero there and nowhere else. Get it wrong and the brush changes width, not just its edge: passing
+ * a 3σ consumer the 1σ constant rescales the whole profile.
+ *
+ * Memoised per cutoff, and `$name`d per cutoff so two differently-truncated brushes in one tree do
+ * not collide on a WGSL identifier.
+ */
+export declare function gaussianBrushShiftedSqFn(cutoffSigmas?: number): import('typegpu').TgpuFn<(distSq: d.F32, radiusSq: d.F32) => d.F32>;
+/** Vector form of {@link gaussianBrushShiftedSqFn} — takes the cell and brush centres. */
+export declare function gaussianBrushShiftedFn(cutoffSigmas?: number): import('typegpu').TgpuFn<(cellPos: d.Vec2f, center: d.Vec2f, radiusSq: d.F32) => d.F32>;
+/** Which falloff a consumer wants. `edgeShift` is the corrected form and the recommended default. */
+export interface GaussianBrushOptions {
+    edgeShift: boolean;
+    /**
+     * Truncation radius in sigmas — where the caller stops evaluating the brush. Default 1 (the
+     * fluid/PixelThrow case: cut at the radius the Gaussian is scaled by). Ignored when
+     * `edgeShift` is false, since an unshifted brush has no edge constant.
+     */
+    cutoffSigmas?: number;
+}
+/**
+ * Pick the squared-distance brush fn for an option record — the form the fluid splat kernels use,
+ * since they have already computed `dx`/`dy` for the spread/perpendicular maths and would otherwise
+ * subtract twice.
+ *
+ * Structural (C5): `edgeShift` is read at composition time, so it costs nothing on the GPU.
+ */
+export declare function gaussianBrushFnSq(opts: GaussianBrushOptions): import('typegpu').TgpuFn<(distSq: d.F32, radiusSq: d.F32) => d.F32>;
+/** Pick the vector-form brush fn for an option record. See {@link gaussianBrushFnSq}. */
+export declare function gaussianBrushFn(opts: GaussianBrushOptions): import('typegpu').TgpuFn<(cellPos: d.Vec2f, center: d.Vec2f, radiusSq: d.F32) => d.F32>;
+//# sourceMappingURL=simShared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"simShared.d.ts","sourceRoot":"","sources":["../../../src/gpu/scaffolds/simShared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAO,CAAC,EAAM,MAAM,QAAQ,CAAA;AAenC;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,qEAG1B,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,qEAGjC,CAAA;AAEF,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,yFAI3B,CAAA;AAEF,wFAAwF;AACxF,eAAO,MAAM,oBAAoB,yFAI/B,CAAA;AAaF;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,GAAE,MAA8B,uEAYpF;AAED,0FAA0F;AAC1F,wBAAgB,sBAAsB,CAAC,YAAY,GAAE,MAA8B,2FAYlF;AAED,qGAAqG;AACrG,MAAM,WAAW,oBAAoB;IACjC,SAAS,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,oBAAoB,uEAE3D;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,IAAI,EAAE,oBAAoB,2FAEzD"}

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

@@ -0,0 +1,134 @@
+import { Expr, GpuShaderDefinition, KitTexture, GpuStorageBuffer } from '../contract';
+
+/**
+ * A map that also produces coverage. `coverage` is a 0..1 scalar Expr: it multiplies sampled ALPHA
+ * on the fragment path and the coverage MASK on the uvRemap path — the two spellings of the same
+ * thing. Return this form (rather than a bare `Expr`) when the coordinate and the coverage come out
+ * of one shared computation, which is the only reason the form exists.
+ */
+export interface UvMapResult {
+    uv: Expr;
+    coverage?: Expr;
+}
+/** What a `map` may return: just the coordinate, or the coordinate plus coverage. */
+export type UvMapped = Expr | UvMapResult;
+/**
+ * The parameters both hooks share. Deliberately the INTERSECTION of `GpuFragmentParams` and the
+ * `uvRemap` ctx, so a map factory written against it cannot accidentally reach for something only
+ * one hook has (`ctx.uv` differs between them — that is why the coordinate arrives as an argument
+ * to `map` rather than being read off the params).
+ *
+ * `props` + `uniforms` are exactly what `animatedTime(params)` needs, so an animated distortion
+ * calls it inside its factory and the accumulated-time Expr lands in both hooks.
+ */
+export interface UvRemapHookParams {
+    props: Expr;
+    uniforms: Record<string, Expr>;
+    propValues: Record<string, unknown>;
+    computeOutputs?: Record<string, KitTexture | GpuStorageBuffer>;
+}
+/**
+ * The one definition that drives both hooks.
+ *
+ * `map` is a PURE coordinate function: given the incoming UV Expr and the aspect Expr, return the
+ * coordinate to look up. It must not sample the child (that is the scaffold's job) and must not
+ * depend on which hook is calling it — that independence is the whole point.
+ */
+export interface UvMap {
+    map: (uv: Expr, aspect: Expr) => UvMapped;
+}
+/**
+ * A `UvMap`, or a factory that builds one from the hook params. Nearly every shader wants the
+ * factory form, because the map closes over `uniforms` / `propValues` / `computeOutputs`.
+ */
+export type UvMapSource = UvMap | ((params: UvRemapHookParams) => UvMap);
+/**
+ * How the compile-time edge mode is chosen:
+ * - `'prop'` (default) — `(propValues.edges as number) ?? 0`, i.e. the shader declares an `edges`
+ *   prop via `edgesPropConfig`. What 15 of the 17 distortions do.
+ * - a number — a FIXED mode baked at composition. SliceWipe hard-codes transparent (1) because
+ *   the vacated strips must clip, not stretch; there is no user-facing choice.
+ * - `'none'` — no edge handling at all. Only legitimate when the map provably stays inside [0,1],
+ *   which is true for exactly one shader: Flip maps [0,1] onto [0,1]. The fragment samples straight
+ *   and `uvRemap` passes the mask through untouched.
+ */
+export type UvRemapEdgeSource = 'prop' | 'none' | number;
+export interface UvRemapShaderOptions {
+    /** See {@link UvRemapEdgeSource}. Default `'prop'`. */
+    edges?: UvRemapEdgeSource;
+    /**
+     * Reconstruction filter for the fragment path.
+     * - `'catmullRom'` (default) — `edges.sampleRemappedExpr`, which picks the right 9-tap filter
+     *   per edge mode. Correct for anything that can magnify content.
+     * - `'bilinear'` — a single tap through `edges.applyEdgeHandlingExpr`. For distortions that are
+     *   deliberately blocky, already low-pass, or take many taps per pixel.
+     */
+    resample?: 'catmullRom' | 'bilinear';
+    /**
+     * Message logged (once, on `console.error`) when the shader is composed with no child. Omit for
+     * the silent-`ZERO` behaviour — Perspective, CornerPin, GridDistortion and Liquify are silent
+     * today and this scaffold preserves that rather than normalising it, because the guard text is
+     * user-visible and normalising it is a separate decision.
+     */
+    requireChildMessage?: string;
+    /**
+     * `uvRemap`-ONLY bail-out to the identity remap. Exists for the two compute-driven distortions
+     * (GridDistortion, Liquify): their displacement comes from their own compute texture, and when
+     * that texture is absent (GPU-free composition, or before the compute hook has run) `uvRemap`
+     * must return the incoming `{uv, mask}` verbatim.
+     *
+     * It is uvRemap-only because the fragment path handles the same condition differently and
+     * deliberately: it substitutes a zero-displacement `vec2f(0.0, 0.0)` INSIDE the map and still
+     * goes through the sample + edge path, so the RTT pass stays structurally identical whether or
+     * not the compute output exists. Do not "fix" the asymmetry — it is two correct answers to two
+     * different questions.
+     */
+    uvRemapIdentityWhen?: (params: UvRemapHookParams) => boolean;
+}
+/**
+ * Lerp a map toward the identity by a runtime scalar: `mix(uv, map(uv), amount)`.
+ *
+ * PolarCoordinates and RectangularCoordinates both expose this as an `intensity` prop — 0 leaves
+ * the content alone, 1 is the full coordinate-system change. Note this blends COORDINATES, not
+ * colours, so intermediate values are a genuine partial warp rather than a cross-fade.
+ */
+export declare function lerpToIdentity(inner: UvMap, amount: (uv: Expr, aspect: Expr) => Expr): UvMap;
+/**
+ * Pick between two maps by a HARD 0/1 selector: `mix(a(uv), b(uv), pick)`.
+ *
+ * This is the combinator that closes Mirror's fragment-vs-uvRemap divergence. Mirror's fragment
+ * used to sample the child TWICE — once at the original UV, once at the reflected UV — and mix the
+ * two COLOURS by `shouldMirror`; its `uvRemap` mixed the two COORDINATES. Both are correct, but
+ * only because `shouldMirror` is `step(0, signedDistance)`, an exact 0 or 1: at 0 the colour mix
+ * returns the first sample and the coordinate mix returns the first coordinate, and likewise at 1.
+ * For a hard selector the two forms are identical, and the coordinate form costs one sample instead
+ * of two.
+ *
+ * `pick` MUST be exactly 0 or 1. Hand it a smooth selector and the forms diverge for real: mixing
+ * coordinates half-way samples a point between the two lookups, which is not the average of the two
+ * colours.
+ */
+export declare function selectMap(a: (uv: Expr, aspect: Expr) => Expr, b: (uv: Expr, aspect: Expr) => Expr, pick: (uv: Expr, aspect: Expr) => Expr): UvMap;
+/**
+ * Build the `fragment` + `uvRemap` pair for an RTT distortion from a single `UvMap`.
+ *
+ * Spread the result into the definition:
+ *
+ *     export const componentDefinition: GpuShaderDefinition<ComponentProps> = {
+ *         name: "Twirl",
+ *         requiresRTT: true,
+ *         requiresChild: true,
+ *         props: {…, edges: edgesPropConfig('stretch', '…')},
+ *         ...uvRemapShader(
+ *             ({uniforms}) => ({
+ *                 map: (uv, aspect) => call(twirlUV, 'twirlUV', [uniforms.center, uniforms.intensity, uv, aspect]),
+ *             }),
+ *             {requireChildMessage: 'You must pass a child component into the Twirl shader.'},
+ *         ),
+ *     }
+ *
+ * The shader keeps its own `'use gpu'` mapping fn — that is the durable, resolve-tested artifact and
+ * the scaffold never touches it. What the scaffold owns is the plumbing around it.
+ */
+export declare function uvRemapShader(source: UvMapSource, opts?: UvRemapShaderOptions): Pick<GpuShaderDefinition, 'fragment' | 'uvRemap'>;
+//# sourceMappingURL=uvRemapShader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"uvRemapShader.d.ts","sourceRoot":"","sources":["../../../src/gpu/scaffolds/uvRemapShader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,KAAK,EAAC,IAAI,EAAqB,mBAAmB,EAAE,UAAU,EAAE,gBAAgB,EAAC,MAAM,aAAa,CAAA;AAQ3G;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IACxB,EAAE,EAAE,IAAI,CAAA;IACR,QAAQ,CAAC,EAAE,IAAI,CAAA;CAClB;AAED,qFAAqF;AACrF,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,WAAW,CAAA;AAEzC;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAC9B,KAAK,EAAE,IAAI,CAAA;IACX,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,gBAAgB,CAAC,CAAA;CACjE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IAClB,GAAG,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,KAAK,QAAQ,CAAA;CAC5C;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,iBAAiB,KAAK,KAAK,CAAC,CAAA;AAMxE;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;AAExD,MAAM,WAAW,oBAAoB;IACjC,uDAAuD;IACvD,KAAK,CAAC,EAAE,iBAAiB,CAAA;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;IACpC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,OAAO,CAAA;CAC/D;AAMD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,KAAK,IAAI,GAAG,KAAK,CAQ5F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CACrB,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,KAAK,IAAI,EACnC,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,KAAK,IAAI,EACnC,IAAI,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,KAAK,IAAI,GACvC,KAAK,CAEP;AAWD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CACzB,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE,oBAAyB,GAChC,IAAI,CAAC,mBAAmB,EAAE,UAAU,GAAG,SAAS,CAAC,CAiDnD"}