shaders 3.0.453 → 3.1.455

package/dist/core/gpu/kit/blur.d.ts

@@ -1,5 +1,6 @@
-import { TgpuRoot, TgpuTexture, TgpuTextureView } from 'typegpu';
+import { TgpuRoot, TgpuTexture, TgpuTextureView, TgpuBindGroupLayout, TgpuFn } from 'typegpu';
 import { ComputeStep } from '../compute';
+import { Expr, GpuComputeNode, GpuFragmentParams, GpuMapInfo, GpuMapWindow } from '../contract';
 
 import * as d from 'typegpu/data';
 /** Default compute resolution. ~655k pixels — comparable to 0.5× of a 1080p canvas.
@@ -77,7 +78,7 @@ export interface VariableBlurComputeResult {
  * BlurCompute` calls this and then allocates the resources + pipelines.
  */
 export declare function buildFixedBlurGraph(halfKernel: number, computeWidth: number, computeHeight: number): {
-    hLayout: import('typegpu').TgpuBindGroupLayout<{
+    hLayout: TgpuBindGroupLayout<{
         input: {
             texture: d.WgslTexture2d<d.F32>;
         };
@@ -96,7 +97,7 @@ export declare function buildFixedBlurGraph(halfKernel: number, computeWidth: nu
             }>;
         };
     }>;
-    vLayout: import('typegpu').TgpuBindGroupLayout<{
+    vLayout: TgpuBindGroupLayout<{
         src: {
             storageTexture: d.WgslStorageTexture2d<"rgba16float", string>;
         };
@@ -113,8 +114,8 @@ export declare function buildFixedBlurGraph(halfKernel: number, computeWidth: nu
             }>;
         };
     }>;
-    kernelH: import('typegpu').TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
-    kernelV: import('typegpu').TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
+    kernelH: TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
+    kernelV: TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
     HParams: d.WgslStruct<{
         activeHalf: d.I32;
         inputWidth: d.F32;
@@ -142,7 +143,7 @@ export declare function createGaussianBlurCompute(root: TgpuRoot, inputTexture:
  * baked into the kernel bodies (comptime), so enabling it changes the emitted WGSL.
  */
 export declare function buildVariableBlurGraph(halfKernel: number, computeWidth: number, computeHeight: number, jitterTaps: boolean): {
-    hLayout: import('typegpu').TgpuBindGroupLayout<{
+    hLayout: TgpuBindGroupLayout<{
         blurMap: {
             storageTexture: d.WgslStorageTexture2d<"rgba32float", string>;
         };
@@ -163,7 +164,7 @@ export declare function buildVariableBlurGraph(halfKernel: number, computeWidth:
             }>;
         };
     }>;
-    vLayout: import('typegpu').TgpuBindGroupLayout<{
+    vLayout: TgpuBindGroupLayout<{
         blurMap: {
             storageTexture: d.WgslStorageTexture2d<"rgba32float", string>;
         };
@@ -183,8 +184,8 @@ export declare function buildVariableBlurGraph(halfKernel: number, computeWidth:
             }>;
         };
     }>;
-    kernelH: import('typegpu').TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
-    kernelV: import('typegpu').TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
+    kernelH: TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
+    kernelV: TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
     HParams: d.WgslStruct<{
         inputWidth: d.F32;
         inputHeight: d.F32;
@@ -206,4 +207,282 @@ export declare function buildVariableBlurGraph(halfKernel: number, computeWidth:
 export declare function createVariableGaussianBlurCompute(root: TgpuRoot, inputTexture: BlurInputTexture | null, inputWidth: number, inputHeight: number, onCleanup: (cb: () => void) => void, halfKernel?: number, computeWidth?: number, computeHeight?: number, options?: {
     jitterTaps?: boolean;
 }): VariableBlurComputeResult;
+/**
+ * Normalized Gaussian weights for `count` taps spread over ±1 of a Gaussian with std-dev `sigma`,
+ * i.e. tap `i` sits at `t = (i/(count-1) - 0.5) * 2`. Computed on the CPU at build time so the
+ * emitted WGSL carries literal weights instead of `exp()` per tap per pixel.
+ *
+ * σ² is rounded to 15 significant digits before the divide. `0.8 * 0.8` is `0.6400000000000001` in
+ * float64, and these weights land in the WGSL as FULL-PRECISION literals — the un-rounded product
+ * would move every consumer's snapshot for a one-ULP difference. 15 digits is lossless for any
+ * decimal σ an author writes, and reproduces the hand-written `/ 0.64` tables bit-for-bit.
+ */
+export declare function gaussianTapWeights(count: number, sigma: number): number[];
+export interface UnrolledTapGatherConfig {
+    /** One weight per tap; its length IS the tap count. Typically {@link gaussianTapWeights}. */
+    weights: number[];
+    /** Sample coordinate for tap `i` (0-based). */
+    tapCoord: (tapIndex: number) => Expr;
+    /** Sample the source at a coordinate — usually `(uv) => texture.sample(uv)`. */
+    sample: (coord: Expr) => Expr;
+    /**
+     * Reduce each sample to one channel before weighting (`'a'`, `'r'`, …). Omit to gather the
+     * whole vec4. Used by the alpha-silhouette blurs (DropShadow) that only carry one channel.
+     */
+    component?: string;
+}
+/**
+ * Build the weighted sum of N unrolled taps: `Σ sample(tapCoord(i)) * weights[i]`.
+ *
+ * WHY UNROLLED. `textureSample` is illegal under non-uniform control flow, so a runtime loop over
+ * taps is not available in a fragment shader. The builder emits a flat expression tree instead —
+ * one `textureSample` per tap, no control flow at all. The tree is left-folded in tap order
+ * (`((t0 + t1) + t2) …`) because float addition is not associative: any other grouping is a
+ * different result.
+ *
+ * The caller owns the alpha convention. When the source is a premultiplied RTT (the normal case
+ * for a filter) the result is premultiplied — finish with `blend.unpremultiplyAlpha`, or let
+ * `defineRttFilter` append that tail.
+ */
+export declare function unrolledTapGather(config: UnrolledTapGatherConfig): Expr;
+/**
+ * The four map-source channels a blur radius can be driven by — the same set the fragment path's
+ * `resolveMapForProp` supports. A BUILD-TIME constant at every consumer: the channel selects one
+ * of the memoized fns below, so each channel emits its own specialised WGSL.
+ */
+export type BlurMapChannel = 'luminance' | 'luminanceInverted' | 'alpha' | 'alphaInverted';
+/**
+ * Struct fields for the map-source canvas dimensions. Spread into a fill kernel's params struct so
+ * the kernel can map its compute pixel onto the source's canvas pixel. Spread ORDER is
+ * load-bearing (it is the uniform struct's member order) — these go before the remap window, which
+ * is the order all six kernels already used.
+ */
+export declare const MAP_SOURCE_DIM_FIELDS: {
+    readonly inputWidth: d.F32;
+    readonly inputHeight: d.F32;
+};
+/** Struct fields for the remap window — the CPU side of these is {@link GpuMapWindow}. */
+export declare const REMAP_WINDOW_FIELDS: {
+    readonly inputMin: d.F32;
+    readonly inputMax: d.F32;
+    readonly outputMin: d.F32;
+    readonly outputMax: d.F32;
+    readonly curve: d.F32;
+};
+/**
+ * The driving scalar a map source contributes at one texel, for `channel`. Memoized and `$name`d
+ * per channel (C3): a shader picks one at graph-build time and calls it from its kernel body.
+ *
+ * Deliberately `dot(rgb, vec3(0.2126, 0.7152, 0.0722))` rather than `tone.luma709`, which spells
+ * the same weights as a multiply-add chain. Same standard, different instruction sequence — and
+ * these kernels are gated byte-identical.
+ */
+export declare function mapSourceScalar(channel: BlurMapChannel): TgpuFn<(sample: d.Vec4f) => d.F32>;
+/**
+ * The map remap window, identical to the fragment path's: normalise `raw` into the input window,
+ * apply the curve as an exponent (`2^(-curve·2)`, so 0 is linear and the sign flips the bend), and
+ * mix across the output window. The input range is guarded against a zero-width window.
+ *
+ * Six scalar args rather than a struct (C1's threshold is "about five") because every consumer
+ * reads these straight off its own uniform struct — a struct param here would either force a
+ * per-kernel uniform-layout change or an inline struct construction, and these kernels are gated
+ * byte-identical below the call.
+ */
+export declare const applyRemapWindow: TgpuFn<(raw: d.F32, inputMin: d.F32, inputMax: d.F32, outputMin: d.F32, outputMax: d.F32, curve: d.F32) => d.F32>;
+/** Spread a live {@link GpuMapWindow} into a fill kernel's params write. */
+export declare function remapWindowValues(window: GpuMapWindow): GpuMapWindow;
+/**
+ * Bright-pixel extraction for a bloom, at one compute pixel.
+ *
+ * Two things are happening. First, the canvas-pixel FOOTPRINT of this compute pixel is
+ * area-averaged over a 4×4 stratified grid rather than point-sampled: that is energy-preserving, so
+ * a hairline or a dither dot contributes in proportion to its coverage instead of shimmering on and
+ * off as the grids slide past each other. Second, the threshold has a quadratic soft knee (the
+ * Unity / Call-of-Duty bloom curve) so brightness ramps INTO the bloom around the threshold instead
+ * of popping, and the mask is luminance-normalised so the extracted colour keeps its hue.
+ *
+ * Returns the extracted (premultiplied) colour to store in the bright buffer. The texture arrives
+ * as an fn argument per C6.
+ */
+export declare const bloomExtractSoftKnee: TgpuFn<(childTexture: d.WgslTexture2d<d.F32>, cx: d.U32, cy: d.U32, inputSize: d.Vec2f, computeSize: d.Vec2f, threshold: d.F32) => d.Vec4f>;
+/**
+ * A fill graph: the bind-group layout, the kernel that writes the radius map (and, for a bloom, the
+ * bright buffer), and the params struct. Built GPU-free so the kernel `tgpu.resolve`s for snapshots.
+ */
+export interface BlurFillGraph {
+    layout: TgpuBindGroupLayout;
+    kernel: (cx: number, cy: number) => void;
+    Params: d.AnyWgslStruct;
+}
+/**
+ * The bloom pre-pass graph with a UNIFORM blur radius: bright-extract the canvas-res child RTT into
+ * `brightMap` and write `params.size` into every texel of `blurMap`.
+ *
+ * `kernelName` is the emitted WGSL fn name — pass the consumer's existing name so its snapshot
+ * doesn't move.
+ */
+export declare function buildBloomExtractGraph(computeWidth: number, computeHeight: number, kernelName: string): {
+    layout: TgpuBindGroupLayout<{
+        childTexture: {
+            texture: d.WgslTexture2d<d.F32>;
+        };
+        brightMap: {
+            storageTexture: d.WgslStorageTexture2d<"rgba16float", string>;
+        };
+        blurMap: {
+            storageTexture: d.WgslStorageTexture2d<"rgba32float", string>;
+        };
+        params: {
+            uniform: d.WgslStruct<{
+                inputWidth: d.F32;
+                inputHeight: d.F32;
+                threshold: d.F32;
+                size: d.F32;
+            }>;
+        };
+    }>;
+    kernel: TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
+    Params: d.WgslStruct<{
+        inputWidth: d.F32;
+        inputHeight: d.F32;
+        threshold: d.F32;
+        size: d.F32;
+    }>;
+};
+/**
+ * The bloom pre-pass graph with a MAP-DRIVEN blur radius. Bright extraction is identical to
+ * {@link buildBloomExtractGraph}; the radius comes from a nearest tap on the map SOURCE (a
+ * canvas-resolution RTT, bound late) pushed through the shared remap window. No `× 0.36` scaling —
+ * a bloom's size prop is already in pixels.
+ */
+export declare function buildBloomExtractMapGraph(computeWidth: number, computeHeight: number, kernelName: string, channel: BlurMapChannel): {
+    layout: TgpuBindGroupLayout<{
+        childTexture: {
+            texture: d.WgslTexture2d<d.F32>;
+        };
+        source: {
+            texture: d.WgslTexture2d<d.F32>;
+        };
+        brightMap: {
+            storageTexture: d.WgslStorageTexture2d<"rgba16float", string>;
+        };
+        blurMap: {
+            storageTexture: d.WgslStorageTexture2d<"rgba32float", string>;
+        };
+        params: {
+            uniform: d.WgslStruct<{
+                inputMin: d.F32;
+                inputMax: d.F32;
+                outputMin: d.F32;
+                outputMax: d.F32;
+                curve: d.F32;
+                inputWidth: d.F32;
+                inputHeight: d.F32;
+                threshold: d.F32;
+            }>;
+        };
+    }>;
+    kernel: TgpuFn<(cx: d.U32, cy: d.U32) => d.Void>;
+    Params: d.WgslStruct<{
+        inputMin: d.F32;
+        inputMax: d.F32;
+        outputMin: d.F32;
+        outputMax: d.F32;
+        curve: d.F32;
+        inputWidth: d.F32;
+        inputHeight: d.F32;
+        threshold: d.F32;
+    }>;
+};
+/**
+ * Compute resolution for a bloom: cap the LONGER edge at the default long edge and derive the other
+ * from the canvas aspect. A fixed 1024×640 grid stretches the glow kernel on any other aspect —
+ * the blur works in compute pixels, so non-square compute pixels smear it directionally.
+ */
+export declare function aspectAwareComputeRes(canvasWidth: number, canvasHeight: number): {
+    width: number;
+    height: number;
+};
+/** What a `compute` hook returns. */
+type BlurComputeNode = NonNullable<ReturnType<GpuComputeNode>>;
+export interface FixedBlurComputeConfig {
+    /** Per-frame Gaussian radius in INPUT (canvas) pixels. Read live so mouse/auto drivers pull through. */
+    radius: () => number;
+    halfKernel?: number;
+    outputKey?: string;
+}
+/**
+ * A uniform-radius separable Gaussian over the composed child. Blur's static path and ChannelBlur.
+ */
+export declare function withFixedBlurCompute(params: GpuFragmentParams, config: FixedBlurComputeConfig): BlurComputeNode | null;
+export interface VariableBlurComputeConfig {
+    /**
+     * Build the radius-map fill graph at the blur's compute resolution. Its layout MUST bind
+     * `blurMap` (write-only, {@link BLUR_MAP_FORMAT}) and `params`; with `source` set it must also
+     * bind a `source` sampled texture.
+     */
+    buildFill: (computeWidth: number, computeHeight: number) => BlurFillGraph;
+    /**
+     * Per-frame values for the fill params. `dims` is the live canvas size in device pixels;
+     * `window` is the live remap window, present only on the map-driven path.
+     */
+    fillValues: (dims: {
+        width: number;
+        height: number;
+    }, window?: GpuMapWindow) => Record<string, number>;
+    /** Map-driven radius: pass `getMapInfo(prop)`. Its source RTT is bound late, like the child. */
+    source?: GpuMapInfo;
+    halfKernel?: number;
+    outputKey?: string;
+}
+/**
+ * A per-pixel-radius Gaussian whose radius map is filled by a caller-supplied kernel each frame.
+ * ProgressiveBlur, TiltShift, and Blur's map-driven path.
+ */
+export declare function withVariableBlurCompute(params: GpuFragmentParams, config: VariableBlurComputeConfig): BlurComputeNode | null;
+export interface BloomComputeConfig {
+    /**
+     * Build the extract graph at the bloom's compute resolution — normally a one-line delegate to
+     * {@link buildBloomExtractGraph} carrying the shader's own kernel name (so its snapshot is
+     * stable and its GPU-free resolve test has something to import).
+     */
+    buildExtract: (computeWidth: number, computeHeight: number) => BlurFillGraph;
+    /** The map-driven twin, via {@link buildBloomExtractMapGraph}. Required when `mapInfo` is given. */
+    buildExtractMap?: (computeWidth: number, computeHeight: number, channel: BlurMapChannel) => BlurFillGraph;
+    /** Map-driven radius: pass `getMapInfo(sizeProp)`, or null for the uniform path. */
+    mapInfo?: GpuMapInfo | null;
+    /** Per-frame soft-knee threshold in [0, 1]. */
+    threshold: () => number;
+    /** Per-frame uniform bloom radius in canvas pixels (uniform path only). */
+    radius: () => number;
+    /** Key the blurred bright buffer is published under (Glow: default; FilmStock: `halationTexture`). */
+    outputKey?: string;
+}
+/**
+ * A bloom: bright-extract the child at aspect-aware compute resolution, then blur the extract.
+ *
+ * The blur's input dimensions ARE its compute dimensions here (scaleY 1), so the H pass maps 1:1 and
+ * the blur never needs `setInputDimensions` — only the extract kernel's canvas dims change on
+ * resize. Tap jitter is on: the bloom radius is large and a fixed tap comb beats against periodic
+ * content as halo moiré.
+ */
+export declare function withBloomCompute(params: GpuFragmentParams, config: BloomComputeConfig): BlurComputeNode | null;
+/**
+ * The fragment tail every compute-backed blur shares: composite the canvas-resolution SHARP child
+ * against the compute-resolution BLURRED buffer, and unpremultiply on the way back into the
+ * straight-alpha blend pipeline (both textures hold premultiplied data — the child RTT always does).
+ *
+ * `compose` receives `(blurred, sharp)` samples at `ctx.uv` and returns the premultiplied result:
+ * `vec4(blurred.rgb, sharp.a)` for a plain blur, a mix by the shader's own blur-amount field for a
+ * selective one, a bloom add for a glow.
+ *
+ * When compute did not run — no device, or a shader's own bypass returned `null` from its `compute`
+ * hook — this falls back to a sharp passthrough of the child RTT. That fallback is what makes the
+ * GPU-free resolve gates work, so every consumer needs it and none should write it again.
+ */
+export declare function composeBlurredOverSharp(params: GpuFragmentParams, compose: (blurred: Expr, sharp: Expr) => Expr, options?: {
+    blurredKey?: string;
+    sharpKey?: string;
+}): Expr;
+export {};
 //# sourceMappingURL=blur.d.ts.map

package/dist/core/gpu/kit/blur.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blur.d.ts","sourceRoot":"","sources":["../../../src/gpu/kit/blur.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"blur.d.ts","sourceRoot":"","sources":["../../../src/gpu/kit/blur.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAa,EAAC,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,EAAE,KAAK,mBAAmB,EAAE,KAAK,MAAM,EAAC,MAAM,SAAS,CAAA;AAC1H,OAAO,KAAK,CAAC,MAAM,cAAc,CAAA;AAEjC,OAAO,EAAuB,KAAK,WAAW,EAA0B,MAAM,YAAY,CAAA;AAE1F,OAAO,KAAK,EAAC,IAAI,EAAE,cAAc,EAAE,iBAAiB,EAAE,UAAU,EAAE,YAAY,EAAa,MAAM,aAAa,CAAA;AAK9G;;;gDAGgD;AAChD,eAAO,MAAM,qBAAqB,OAAO,CAAA;AACzC,eAAO,MAAM,sBAAsB,MAAM,CAAA;AAazC,uEAAuE;AACvE,eAAO,MAAM,eAAe,EAAG,aAAsB,CAAA;AAErD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,eAAe,GAAG,WAAW,GAAG,cAAc,CAAA;AAE7E;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAY9D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAC,CAchH;AAED,MAAM,WAAW,yBAAyB;IACtC;;;;;OAKG;IACH,YAAY,EAAE,WAAW,EAAE,CAAA;IAC3B,iGAAiG;IACjG,aAAa,EAAE,WAAW,CAAA;IAC1B,YAAY,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3C,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,kBAAkB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3D;;;;;OAKG;IACH,eAAe,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAA;CACrD;AAED,MAAM,WAAW,yBAAyB;IACtC,YAAY,EAAE,WAAW,EAAE,CAAA;IAC3B,aAAa,EAAE,WAAW,CAAA;IAC1B;;;;OAIG;IACH,cAAc,EAAE,WAAW,CAAA;IAC3B,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,kBAAkB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3D,8FAA8F;IAC9F,eAAe,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAA;CACrD;AAWD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgElG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACrC,IAAI,EAAE,QAAQ,EACd,YAAY,EAAE,gBAAgB,GAAG,IAAI,EACrC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,EACnC,UAAU,GAAE,MAA4B,EACxC,YAAY,GAAE,MAA8B,EAC5C,aAAa,GAAE,MAA+B,GAC/C,yBAAyB,CAmG3B;AAUD;;;GAGG;AACH,wBAAgB,sBAAsB,CAClC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmFtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC7C,IAAI,EAAE,QAAQ,EACd,YAAY,EAAE,gBAAgB,GAAG,IAAI,EACrC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,EACnC,UAAU,GAAE,MAA4B,EACxC,YAAY,GAAE,MAA8B,EAC5C,aAAa,GAAE,MAA+B,EAC9C,OAAO,CAAC,EAAE;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAC,GACjC,yBAAyB,CAqE3B;AAUD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CASzE;AAED,MAAM,WAAW,uBAAuB;IACpC,6FAA6F;IAC7F,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,+CAA+C;IAC/C,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IACpC,gFAAgF;IAChF,MAAM,EAAE,CAAC,KAAK,EAAE,IAAI,KAAK,IAAI,CAAA;IAC7B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAUvE;AAYD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,mBAAmB,GAAG,OAAO,GAAG,eAAe,CAAA;AAE1F;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;CAAmD,CAAA;AAErF,0FAA0F;AAC1F,eAAO,MAAM,mBAAmB;;;;;;CAMtB,CAAA;AAIV;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,GAAG,CAAC,CAe3F;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,mHASF,CAAA;AAE3B,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAQpE;AAWD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,6IA4BD,CAAA;AAEhC;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC1B,MAAM,EAAE,mBAAmB,CAAA;IAC3B,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IACxC,MAAM,EAAE,CAAC,CAAC,aAAa,CAAA;CAC1B;AAOD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqBrG;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACrC,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmC1B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAOhH;AAeD,qCAAqC;AACrC,KAAK,eAAe,GAAG,WAAW,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAA;AAS9D,MAAM,WAAW,sBAAsB;IACnC,wGAAwG;IACxG,MAAM,EAAE,MAAM,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,sBAAsB,GAAG,eAAe,GAAG,IAAI,CA6BtH;AAED,MAAM,WAAW,yBAAyB;IACtC;;;;OAIG;IACH,SAAS,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,KAAK,aAAa,CAAA;IACzE;;;OAGG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,EAAE,MAAM,CAAC,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACpG,gGAAgG;IAChG,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,yBAAyB,GAAG,eAAe,GAAG,IAAI,CA0D5H;AAED,MAAM,WAAW,kBAAkB;IAC/B;;;;OAIG;IACH,YAAY,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,KAAK,aAAa,CAAA;IAC5E,oGAAoG;IACpG,eAAe,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,KAAK,aAAa,CAAA;IACzG,oFAAoF;IACpF,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAC3B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,MAAM,CAAA;IACvB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,MAAM,CAAA;IACpB,sGAAsG;IACtG,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,kBAAkB,GAAG,eAAe,GAAG,IAAI,CA+D9G;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACnC,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,KAAK,IAAI,EAC7C,OAAO,CAAC,EAAE;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAC,GACnD,IAAI,CAYN"}

package/dist/core/gpu/kit/cells.d.ts

@@ -0,0 +1,136 @@
+import { d } from './index';
+
+/** One square cell: its integer index and the `[0,1)²` coordinate within it. */
+export declare const CellTile: d.WgslStruct<{
+    /** Integer cell index — `floor(p)`. Stable per cell, so it is what you hash. */
+    cell: d.Vec2f;
+    /** Position within the cell, `[0,1)²` — `fract(p)`. What you draw against. */
+    local: d.Vec2f;
+}>;
+/**
+ * Split a scaled UV into its square cell index and in-cell coordinate.
+ *
+ * Both halves come back because a pattern needs both: `local` draws the cell's content, `cell`
+ * seeds its randomness. Splitting them at the call site is where sign bugs creep in — `fract` is
+ * floored in WGSL and `floor` matches it, so this pair is consistent for negative coordinates
+ * (which a rotation or an upstream distortion's `uvContext` will produce).
+ */
+export declare const squareTiling: import('typegpu').TgpuFn<(p: d.Vec2f) => d.WgslStruct<{
+    /** Integer cell index — `floor(p)`. Stable per cell, so it is what you hash. */
+    cell: d.Vec2f;
+    /** Position within the cell, `[0,1)²` — `fract(p)`. What you draw against. */
+    local: d.Vec2f;
+}>>;
+/** One hexagonal cell: the local vector from its centre, and the centre's own coordinate. */
+export declare const HexCell: d.WgslStruct<{
+    /** Vector from the nearest hex centre to the sample point. Drives edge distance and face cuts. */
+    gv: d.Vec2f;
+    /** The hex centre in lattice space (`p - gv`). Snap and round this to get a hashable index. */
+    id: d.Vec2f;
+}>;
+/**
+ * Hexagonal lattice lookup: find the nearest hex centre to `p` and return the local offset.
+ *
+ * The standard two-offset-grids trick — a hex lattice is two interleaved rectangular grids, so
+ * folding `p` into both and keeping whichever candidate centre is nearer lands on the correct hex
+ * without any branching. The fold uses {@link geom.flooredMod2} (not WGSL `%`, which is truncated)
+ * so it stays periodic for negative coordinates.
+ *
+ * `s` is the lattice period and picks the ORIENTATION:
+ *
+ * - `vec2f(SQRT3, 1)` — pointy-top hexagons (flat sides left/right). HexGrid's honeycomb.
+ * - `vec2f(1, SQRT3)` — the transpose, flat-top hexagons. What a rhombille / isometric-cube cut
+ *   needs, because the three rhombus faces have to meet at a vertical vertex.
+ *
+ * Those two really are the same code with `s` transposed, which is why the orientation is a
+ * parameter and not two functions.
+ */
+export declare const hexTiling: import('typegpu').TgpuFn<(p: d.Vec2f, s: d.Vec2f) => d.WgslStruct<{
+    /** Vector from the nearest hex centre to the sample point. Drives edge distance and face cuts. */
+    gv: d.Vec2f;
+    /** The hex centre in lattice space (`p - gv`). Snap and round this to get a hashable index. */
+    id: d.Vec2f;
+}>>;
+/**
+ * Skew an equilateral-triangle lattice onto a unit-square integer grid:
+ * `M · p` where `M = [[1, -1/√3], [0, 2/√3]]`.
+ *
+ * Equilateral triangles are awkward to index directly; after this skew each unit square holds
+ * exactly two triangles, split by the anti-diagonal, so `floor`/`fract` indexing works and the
+ * anti-diagonal test (`fract.x + fract.y > 1`) picks which of the pair you are in.
+ *
+ * The result is a sheared space: distances in it are NOT the distances in the original lattice, so
+ * take anti-aliasing footprints from this coordinate (which is what the derivative sees) and read
+ * edge distances in it too, consistently.
+ *
+ * The X term divides by `SQRT3` rather than multiplying by a folded `1/√3`: the two differ in the
+ * last bit, and the division is what the shipped lattice was authored against.
+ */
+export declare const triLattice: import('typegpu').TgpuFn<(p: d.Vec2f) => d.Vec2f>;
+/**
+ * Screen UV of the CENTRE of the cell containing `uv`, for a `cells`-per-shortest-edge lattice
+ * (aspect-corrected, Y-flipped, guarded aspect).
+ *
+ * This is what a pattern generator returns from `mapSampleUVs` so that mapped props are sampled
+ * once per cell rather than once per fragment. Without it, a mapped `thickness` or `dotSize` varies
+ * *within* a cell, which clips the cell's content against the map source's boundaries instead of
+ * transitioning whole cells — the difference between dots that grow and dots that get shaved.
+ *
+ * The round trip is deliberate: correct → snap → un-correct, so the returned value is a screen UV
+ * the composer can sample a map texture with directly.
+ *
+ * See {@link cellCentreUVRotated} for the lattice-with-rotation form. There are two functions
+ * rather than one with a rotation argument because a rotation of zero still costs a `cos`, a `sin`,
+ * and a second un-rotate in the unrotated case.
+ */
+export declare const cellCentreUV: import('typegpu').TgpuFn<(uv: d.Vec2f, viewport: d.Vec2f, cells: d.F32) => d.Vec2f>;
+/**
+ * {@link cellCentreUV} for a lattice rotated by `rotationRad` about the canvas centre: correct +
+ * flip, rotate, snap to the cell centre in rotated space, un-rotate, un-correct.
+ *
+ * The angle arrives in RADIANS — the caller converts, so the degrees-to-radians constant stays at
+ * the shader's own module scope where the rest of its rotation math reads it.
+ */
+export declare const cellCentreUVRotated: import('typegpu').TgpuFn<(uv: d.Vec2f, viewport: d.Vec2f, cells: d.F32, rotationRad: d.F32) => d.Vec2f>;
+/**
+ * Per-cell pseudo-random scalar in `[0, 1)` from an integer cell index.
+ *
+ * The legacy fract-only chain (NO `sin` — unlike {@link rowSpeedHash} below), byte-identical across
+ * the pattern fleet: scale the index by `(123.34, 345.45)` and take the fractional part, cross-couple
+ * the two components through `q + dot(q, q + 34.345)`, then fract their product. It is not a good
+ * hash — it has visible structure at large indices and is sensitive to float precision — but it is
+ * the hash every shipped preset's cell randomness was authored against, so it is frozen (D-6).
+ *
+ * Hash INTEGER indices. Feeding a continuous coordinate produces sub-pixel jitter within a cell
+ * instead of one value per cell; lattices whose centres fall on non-integers (hex, rhombille) must
+ * `round` them onto integers first.
+ *
+ * New shaders: use `noise.hash*` instead.
+ */
+export declare const cellHash: import('typegpu').TgpuFn<(id: d.Vec2f) => d.F32>;
+/**
+ * Per-ROW pseudo-random scalar in `[0, 1)` from a row index — the 1D member of the same legacy
+ * family, and the one that genuinely is a sin-fract chain
+ * (`fract(sin(row * 127.1) * 43758.5453)`), frozen for the same reason (D-6).
+ *
+ * Used to give each row of a pattern its own drift speed. Pass a floored row index.
+ */
+export declare const rowSpeedHash: import('typegpu').TgpuFn<(row: d.F32) => d.F32>;
+/**
+ * Turn a `[0,1)` row hash into a speed multiplier centred on 1: `1 + (hash - 0.5) * 4 * variance`.
+ *
+ * Centred on 1 so `variance = 0` leaves every row at the base speed, and scaled by 4 so a variance
+ * of 1 spans `[-1, 3]` — wide enough that some rows reverse, which is what makes the motion read as
+ * irregular rather than as a single sheared drift.
+ */
+export declare const rowSpeedMultiplier: import('typegpu').TgpuFn<(rowHash: d.F32, variance: d.F32) => d.F32>;
+/**
+ * Turn a `[0,1)` cell hash into a brightness multiplier: `max(1 + (rand - 0.5) * 2 * variation, 0)`.
+ *
+ * Centred on 1 so `variation = 0` is exactly the unmodified colour, spanning `[0, 2]` at full
+ * variation (some cells doubled, some black). The `max(_, 0)` floor matters because the multiplier
+ * is applied to a colour: a negative factor would flip the sign of the RGB and, once blended,
+ * produce colours that are not in the authored palette at all.
+ */
+export declare const variationFactor: import('typegpu').TgpuFn<(rand: d.F32, variation: d.F32) => d.F32>;
+//# sourceMappingURL=cells.d.ts.map

package/dist/core/gpu/kit/cells.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cells.d.ts","sourceRoot":"","sources":["../../../src/gpu/kit/cells.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAO,CAAC,EAAM,MAAM,SAAS,CAAA;AAUpC,gFAAgF;AAChF,eAAO,MAAM,QAAQ;IACjB,gFAAgF;;IAEhF,8EAA8E;;EAE9D,CAAA;AAEpB;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY;IAdrB,gFAAgF;;IAEhF,8EAA8E;;GAehF,CAAA;AAIF,6FAA6F;AAC7F,eAAO,MAAM,OAAO;IAChB,kGAAkG;;IAElG,+FAA+F;;EAEhF,CAAA;AAEnB;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS;IAvBlB,kGAAkG;;IAElG,+FAA+F;;GA4BjG,CAAA;AAIF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,mDAGrB,CAAA;AAIF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,qFAQvB,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,yGAqB9B,CAAA;AAIF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,kDAKnB,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,iDAGvB,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,sEAG7B,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,oEAG1B,CAAA"}

package/dist/core/gpu/kit/cellular.d.ts

@@ -0,0 +1,102 @@
+import { d } from './index';
+
+/**
+ * Cell coordinate → feature point in [0,1]², via the classic sin-fract hash
+ * (`fract(sin(vec2(dot(p, k1), dot(p, k2))) · 43758.5453)`).
+ *
+ * GPU-only: `sin` at these argument magnitudes is driver-approximate and diverges from JS `Math.sin`,
+ * so this cannot be golden-tested on the CPU.
+ */
+export declare const cellHash2: import('typegpu').TgpuFn<(p: d.Vec2f) => d.Vec2f>;
+/**
+ * {@link nearest2Cells}'s options, as a discriminated union: only the two pairings the builder
+ * actually implements are expressible. `distance` and `jitter` are NOT independent — pairing
+ * `length` with `mix` (or `selectableSquared` with `none`) has no branch and would silently fall
+ * through to the other form's emitted signature, so the type forbids it.
+ *
+ * - `{distance: 'length', jitter: 'none'}` — `length(delta)`, a true Euclidean distance per tap, and
+ *   the drifted feature point clamped into the cell interior and used directly. The fold carries real
+ *   distances, which is what a ratio reduction needs.
+ * - `{distance: 'selectableSquared', jitter: 'mix'}` — computes Euclidean-SQUARED, Manhattan and
+ *   Chebyshev and selects between them on a runtime `metric` argument (Euclidean stays squared
+ *   through the fold; the sqrt is deferred to {@link cellReduceSelectable}), and lerps from the cell
+ *   centre (0.5, 0.5) toward the clamped point by a runtime `jitter` argument, so 0 gives a rigid
+ *   lattice and 1 full randomness. All three metric branches are always computed — see the note on
+ *   branchlessness below.
+ */
+export type Nearest2Options = {
+    distance: 'length';
+    jitter: 'none';
+    /** Emitted WGSL identifier base. The option key is appended, so configs cannot collide. */
+    name?: string;
+} | {
+    distance: 'selectableSquared';
+    jitter: 'mix';
+    /** Emitted WGSL identifier base. The option key is appended, so configs cannot collide. */
+    name?: string;
+};
+/**
+ * The 3×3 nearest-two-features fold, as a builder. Emits a `tgpu.fn` taking the SCALED cell-space
+ * position and returning `vec2(d1, d2)` — the nearest and second-nearest feature distances (squared,
+ * for `distance: 'selectableSquared'`).
+ *
+ * Emitted signature, by options:
+ * - `{distance: 'length', jitter: 'none'}` → `(scaledUV: vec2f, animT: f32, seed: f32) → vec2f`
+ * - `{distance: 'selectableSquared', jitter: 'mix'}` →
+ *   `(scaledUV: vec2f, animT: f32, seed: f32, jitter: f32, metric: f32) → vec2f`
+ *   (`metric`: 0 Euclidean-squared, 1 Manhattan, 2 Chebyshev)
+ *
+ * The feature points DRIFT: each is displaced by `sin/cos` of its own hash plus `animT` (the y axis
+ * at 0.7× the rate, so the motion is not diagonal), then clamped away from the cell walls so a point
+ * cannot cross into a neighbour and pop the topology. The phase constant is the full-precision TAU;
+ * one consumer shipped a truncated `6.28` here and was corrected on adoption (Gate C).
+ *
+ * THE FOLD IS BRANCHLESS AND THAT IS DELIBERATE. `d2 = min(d2, max(dd, d1))` followed by
+ * `d1 = min(d1, dd)` maintains the sorted pair without a conditional, because the d2 update reads
+ * the PRE-update d1. It is exactly equivalent to the nested-select spelling — case `dd < d1` gives
+ * `(d1, dd)`, case `dd ≥ d1` gives `(min(d2, dd), d1)` — and both spellings only ever SELECT
+ * existing values, never arithmetic on them, so the choice is bit-neutral. The unified spelling is
+ * why a consumer that only wants F1 can still use this fold: the extra d2 work leaves d1 untouched.
+ *
+ * Likewise `selectableSquared` computes all three metrics and selects, rather than JS-branching per
+ * compile-time metric. That looks like waste but is not: the metric is a compile-time prop, so a
+ * branch would recompile the pipeline on every change, and the dead arithmetic is a handful of ALU
+ * ops the driver's dead-code pass largely removes. It is the FractalNoise "harmless waste" pattern.
+ */
+export declare function nearest2Cells(options: Nearest2Options): Nearest2Fn;
+/** {@link nearest2Cells}'s output. Trailing arguments exist only for the `selectableSquared` form. */
+export type Nearest2Fn = (scaledUV: d.v2f, animT: number, seed: number, jitterAmount?: number, metric?: number) => d.v2f;
+/** Feature-combination modes for {@link cellReduceSelectable}, and the enum a `mode` prop maps to. */
+export declare const CELL_MODES: Record<string, number>;
+/** Distance metrics for `nearest2Cells({distance: 'selectableSquared'})`, and the prop enum. */
+export declare const CELL_METRICS: Record<string, number>;
+/**
+ * Reduce a `(d1, d2)` pair to a scalar by {@link CELL_MODES} mode, taking the deferred Euclidean
+ * square root when `metric` is 0.
+ *
+ * The sqrt lives HERE rather than in the fold so the fold can keep squared distances (one multiply
+ * per tap instead of a sqrt), and taking it after the min-fold is exact: `sqrt` is monotonic and
+ * correctly rounded, so `sqrt(min(a, b)) == min(sqrt a, sqrt b)`.
+ *
+ * `sd1`/`sd2` unify the squared and linear cases so every mode is one expression for both — e.g.
+ * F1×F2 is `sd1·sd2`, which is `sqrt(d1·d2)`-equivalent for Euclidean and `d1·d2` otherwise.
+ */
+export declare const cellReduceSelectable: import('typegpu').TgpuFn<(d1: d.F32, d2: d.F32, metric: d.F32, mode: d.F32) => d.F32>;
+/**
+ * The scale-invariant cell gradient: `pow(clamp(2·d1 / (d1 + d2)), power)`.
+ *
+ * The `2·d1/(d1+d2)` ratio is the reason to compute d2 at all for a fill gradient — it maps 0 at a
+ * feature point to 1 at a cell boundary REGARDLESS of cell size, where a raw F1 would make large
+ * cells read darker than small ones. `power` shapes how much of the interior the far colour claims.
+ */
+export declare const cellRatio: import('typegpu').TgpuFn<(d1: d.F32, d2: d.F32, power: d.F32) => d.F32>;
+/**
+ * The cell-boundary line mask: `smoothstep(0, softness, (d2 − d1) / (d1 + d2))`, 0 ON the boundary
+ * and 1 in the interior.
+ *
+ * `(d2 − d1)` alone would give boundary lines whose apparent width scales with cell size; dividing
+ * by the sum normalizes it, so `softness` reads as a constant line width across the field. Callers
+ * that expose softness in cell units should pre-scale it by the cell count.
+ */
+export declare const cellEdgeMask: import('typegpu').TgpuFn<(d1: d.F32, d2: d.F32, softness: d.F32) => d.F32>;
+//# sourceMappingURL=cellular.d.ts.map

package/dist/core/gpu/kit/cellular.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cellular.d.ts","sourceRoot":"","sources":["../../../src/gpu/kit/cellular.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAO,CAAC,EAAM,MAAM,SAAS,CAAA;AAGpC;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,mDAIpB,CAAA;AAIF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,eAAe,GACrB;IACE,QAAQ,EAAE,QAAQ,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,2FAA2F;IAC3F,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB,GACC;IACE,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,MAAM,EAAE,KAAK,CAAA;IACb,2FAA2F;IAC3F,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,UAAU,CAmElE;AAED,sGAAsG;AACtG,MAAM,MAAM,UAAU,GAAG,CACrB,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KACnF,CAAC,CAAC,GAAG,CAAA;AAMV,sGAAsG;AACtG,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAM7C,CAAA;AAED,gGAAgG;AAChG,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAI/C,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,uFAa3B,CAAA;AAEN;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,yEAKpB,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,4EAKvB,CAAA"}