shaders 3.0.453 → 3.1.455

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

@@ -0,0 +1,52 @@
+/**
+ * Shared numeric constants for shader code.
+ *
+ * WHY THIS FILE EXISTS: `Math.*` must never be referenced inside a `'use gpu'` body — the TGSL
+ * transpiler has no `Math` in scope, so a `Math.PI` in a body produces wrong WGSL rather than an
+ * error. The house workaround is to fold the value into a module-scope `const` and reference THAT
+ * from the body; typegpu captures the const's JS value and emits it as a numeric literal. Every
+ * shader used to declare its own copy (~54 files), which is how six of them ended up with
+ * truncated degree-to-radian values. These are the one shared set.
+ *
+ * Being module-scope `const number`s is load-bearing, not incidental: keep the arithmetic
+ * (`Math.PI / 180`) here at module scope so it evaluates on the CPU at import time. An imported
+ * const inlines to exactly the same literal as a local one, so adopting these is byte-identical
+ * WGSL for any shader whose local value already equalled the true constant.
+ *
+ * HOW TO REFERENCE THESE FROM A BODY — not any import will do. The transpiler folds a plain
+ * module-scope IDENTIFIER whose value is a JS number; a MEMBER EXPRESSION on a namespace object
+ * (`constants.DEG_TO_RAD` inside a `'use gpu'` body) is not that pattern and must not be relied on.
+ * So either use a named import:
+ *
+ *     import {DEG_TO_RAD} from '@coreroot/gpu/kit/constants'
+ *
+ * or, when the file already imports the `constants` namespace off the kit facade (what the shader
+ * fleet does), re-bind once at module scope and reference that identifier from the body:
+ *
+ *     import {constants} from '@coreroot/gpu/kit'
+ *     const DEG_TO_RAD = constants.DEG_TO_RAD    // ← the body references THIS
+ */
+/** Degrees → radians. `Math.PI / 180`. */
+export declare const DEG_TO_RAD: number;
+/** Radians → degrees. `180 / Math.PI`. */
+export declare const RAD_TO_DEG: number;
+/** π. */
+export declare const PI: number;
+/** 2π — one full turn. */
+export declare const TAU: number;
+/** Alias of {@link TAU}; both spellings exist across the shader fleet. */
+export declare const TWO_PI: number;
+/** π/2 — a quarter turn. */
+export declare const HALF_PI: number;
+/** √3 — the hex/triangular lattice ratio. */
+export declare const SQRT3: number;
+/**
+ * The golden angle in radians (`π · (3 − √5)` ≈ 2.39996322972865332). Used to give each octave /
+ * particle / sample an incommensurate direction so successive items never line up.
+ *
+ * DIVERGENCE (Gate C when adopted): `shaders/FractalNoise/index.ts` inlines a truncated
+ * `2.39996`. Swapping it for this constant is a real (if tiny) pixel change to the octave drift
+ * directions, so it belongs on the Gate C visual-review list rather than in a Gate A migration.
+ */
+export declare const GOLDEN = 2.3999632297286535;
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/gpu/kit/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,0CAA0C;AAC1C,eAAO,MAAM,UAAU,QAAgB,CAAA;AAEvC,0CAA0C;AAC1C,eAAO,MAAM,UAAU,QAAgB,CAAA;AAEvC,SAAS;AACT,eAAO,MAAM,EAAE,QAAU,CAAA;AAEzB,0BAA0B;AAC1B,eAAO,MAAM,GAAG,QAAc,CAAA;AAE9B,0EAA0E;AAC1E,eAAO,MAAM,MAAM,QAAM,CAAA;AAEzB,4BAA4B;AAC5B,eAAO,MAAM,OAAO,QAAc,CAAA;AAElC,6CAA6C;AAC7C,eAAO,MAAM,KAAK,QAAe,CAAA;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,qBAAsB,CAAA"}

package/dist/core/gpu/kit/effects/index.d.ts

@@ -1,7 +1,7 @@
 /**
- * Shared effect helpers: glass / neon / emboss / prism / raymarch3d / thinFilm — reused across the
+ * Shared effect helpers: glass / neon / emboss / raymarch3d / thinFilm — reused across the
  * shape-effect shaders (Glass, Crystal, Neon, Emboss, LiquidMetal, Plastic, Holographic, Frost,
- * ThinFilm, Form3D, Prism, …). Each is an Expr-level builder
+ * ThinFilm, Form3D, …). Each is an Expr-level builder
  * `apply<X>Effect(params, sdfSampler?, …) => Expr` (see the individual files for the exact
  * signature) plus its pure-math `'use gpu'` fns. Consumed as
  * `kit.effects.glass.applyGlassEffect(...)` etc.
@@ -10,7 +10,6 @@ export * as bevel from './bevel';
 export * as glass from './glass';
 export * as neon from './neon';
 export * as emboss from './emboss';
-export * as prism from './prism';
 export * as raymarch3d from './raymarch3d';
 export * as thinFilm from './thinFilm';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/gpu/kit/effects/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/gpu/kit/effects/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAA;AAChC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAA;AAChC,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAA;AAC9B,OAAO,KAAK,MAAM,MAAM,UAAU,CAAA;AAClC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAA;AAChC,OAAO,KAAK,UAAU,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/gpu/kit/effects/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAA;AAChC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAA;AAChC,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAA;AAC9B,OAAO,KAAK,MAAM,MAAM,UAAU,CAAA;AAClC,OAAO,KAAK,UAAU,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAA"}

package/dist/core/gpu/kit/effects/raymarch3d.d.ts

@@ -1,27 +1,18 @@
 import { d } from '../index';
-import { Expr, GpuFragmentParams, KitTexture } from '../../contract';
 
 /**
- * A raymarched 3D solid: `sdf(p) → signed distance` and `surfaceUV(hitPos, normal) → vec2` texture
- * coords. Both are `tgpu.fn`s with the shape's size params baked in (the caller builds them from its
- * size uniforms).
+ * A raw shape SDF `tgpu.fn`: `(p, rp0, rp1, rp2, t) => f32` — called DIRECTLY inside the trace body
+ * (a `'use gpu'` body invokes tgpu.fns directly, never the builder-level `call`). Give each shape's
+ * fn a distinct `$name`: the trace calls it through a closure alias, so typegpu can't derive a name
+ * from the const and would emit a generic `fn sdf` that collides across two differently-shaped nodes
+ * in one composition.
  */
-export interface Shape3D {
-    sdf: (p: any) => any;
-    surfaceUV: (hitPos: any, normal: any) => any;
-}
-/** Uniform keys the distortion builder reads via `params.uniforms.<key>`. */
-export interface Distortion3DUniforms {
-    center: unknown;
-    zoom: unknown;
-    glossiness: unknown;
-    lighting: unknown;
-    uvMode: unknown;
-}
+export type ParamThreadedSdf = (p: unknown, rp0: unknown, rp1: unknown, rp2: unknown, t: unknown) => unknown;
+/** The march budget. `maxDistance` defaults to 20 (the ray gives up past it). */
 export interface MarchOptions {
-    steps?: number;
-    stepCap?: number;
-    hitEps?: number;
+    steps: number;
+    stepCap: number;
+    hitEps: number;
     maxDistance?: number;
 }
 /** The march result: shape-local hit position, surface normal, view ray direction, hit flag (0/1). */
@@ -48,25 +39,17 @@ export declare const applyUVMode3d: import('typegpu').TgpuFn<(uv: d.Vec2f, uvMod
 export declare const distortion3dLighting: import('typegpu').TgpuFn<(surfaceColor: d.Vec4f, normal: d.Vec3f, rd: d.Vec3f, hit: d.F32, uvVisible: d.F32, glossAmt: d.F32, lightAmt: d.F32) => d.Vec4f>;
 /**
  * Build the orthographic sphere-march + tetrahedron normal into a resolvable
- * `tgpu.fn([d.vec2f, d.f32, d.vec2f, d.f32], Distortion3DTrace)` — `(uv, aspect, center, zoom)`. The
- * shape's baked `sdf` is closed over; the march budget (`steps`/`stepCap`/`hitEps`/`maxDistance`) is
- * baked build-time. The march loop uses `for`/`if`/`break`/`let`.
+ * `tgpu.fn([d.vec2f, d.f32, d.vec2f, d.f32, d.vec4f, d.vec4f, d.vec4f, d.f32], Distortion3DTrace)` —
+ * `(uv, aspect, center, zoom, rp0, rp1, rp2, t)`. The shape's `sdf` is closed over and receives the
+ * packed params (`rp0`/`rp1`/`rp2`/`t`) at every march step and every tetrahedron-normal tap; the
+ * march budget (`steps`/`stepCap`/`hitEps`/`maxDistance`) is baked build-time. The march loop uses
+ * `for`/`if`/`break`/`let`. Left unnamed — the consumer's `call(trace, 'name', …)` pins a WGSL name
+ * distinct per shape.
  */
-export declare function buildDistortion3dTrace(sdfFn: Shape3D['sdf'], opts: Required<MarchOptions>): import('typegpu').TgpuFn<(uv: d.Vec2f, aspect: d.F32, center: d.Vec2f, zoom: d.F32) => d.WgslStruct<{
+export declare function buildParamThreadedTrace(sdf: ParamThreadedSdf, opts: MarchOptions): import('typegpu').TgpuFn<(uv: d.Vec2f, aspect: d.F32, center: d.Vec2f, zoom: d.F32, rp0: d.Vec4f, rp1: d.Vec4f, rp2: d.Vec4f, t: d.F32) => d.WgslStruct<{
     hitPos: d.Vec3f;
     normal: d.Vec3f;
     rd: d.Vec3f;
     hit: d.F32;
 }>>;
-/**
- * Apply the 3D distortion effect: raymarch `shape` orthographically, sample the child through the
- * shape's surface UV (with the boundary mode), and shade with Blinn-Phong + Fresnel. Composition-time
- * Expr builder — see the file header for the notes.
- *
- * @param params        the fragment builder params (reads `uniforms`/`ctx`)
- * @param childTexture  the child RTT (from the shader's `convertToTexture(childNode)`)
- * @param shape         the 3D shape's baked `sdf` + `surfaceUV` `tgpu.fn`s
- * @param march         optional march budget (steps / stepCap / hitEps / maxDistance)
- */
-export declare function applyDistortion3D(params: GpuFragmentParams, childTexture: KitTexture, shape: Shape3D, march?: MarchOptions): Expr;
 //# sourceMappingURL=raymarch3d.d.ts.map

package/dist/core/gpu/kit/effects/raymarch3d.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"raymarch3d.d.ts","sourceRoot":"","sources":["../../../../src/gpu/kit/effects/raymarch3d.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAO,CAAC,EAAM,MAAM,UAAU,CAAA;AAGrC,OAAO,KAAK,EAAC,IAAI,EAAE,iBAAiB,EAAE,UAAU,EAAC,MAAM,gBAAgB,CAAA;AAEvE;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACpB,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,GAAG,CAAA;IACpB,SAAS,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,GAAG,CAAA;CAC/C;AAED,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACjC,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAC1F;AAED,MAAM,WAAW,YAAY;IACzB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,sGAAsG;AACtG,eAAO,MAAM,iBAAiB;;;;;EAK5B,CAAA;AAMF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,mEAsBxB,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,4JAqB3B,CAAA;AAMN;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC;;;;;IAoDzF;AAMD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,iBAAiB,EACzB,YAAY,EAAE,UAAU,EACxB,KAAK,EAAE,OAAO,EACd,KAAK,GAAE,YAAiB,GACzB,IAAI,CA4BN"}
+{"version":3,"file":"raymarch3d.d.ts","sourceRoot":"","sources":["../../../../src/gpu/kit/effects/raymarch3d.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAO,CAAC,EAAM,MAAM,UAAU,CAAA;AAErC;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,KAAK,OAAO,CAAA;AAE5G,iFAAiF;AACjF,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,sGAAsG;AACtG,eAAO,MAAM,iBAAiB;;;;;EAK5B,CAAA;AAMF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,mEAsBxB,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,4JAqB3B,CAAA;AAMN;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,YAAY;;;;;IAoChF"}

package/dist/core/gpu/kit/effects/thinFilm.d.ts

@@ -47,7 +47,9 @@ export interface ThinFilmEffectOptions {
 export declare const thinFilmShade: import('typegpu').TgpuFn<(sdfRaw: d.F32, scale: d.F32, gradX: d.F32, gradY: d.F32, edgeSoftness: d.F32, rimWidthUniform: d.F32, thickness: d.F32, dispersion: d.F32, hueShift: d.F32, lightAngle: d.F32, animTime: d.F32, volumetric: d.F32) => d.Vec2f>;
 /**
  * IQ cosine palette → smooth iridescent spectrum (oil-slick / anodised metal). `t = phase`.
- * `cos((phase + k)·2π)·0.5 + 0.5` per channel with k = 0, 1/3, 2/3. Pure — CPU-golden-testable.
+ * `cos((phase + k)·2π)·0.5 + 0.5` per channel with the TRUNCATED thirds this effect has always
+ * used (0.3333 / 0.6667) — passed as arguments to the shared `lighting.cosinePalette`, which
+ * Holographic calls with exact thirds. Unifying them would move pixels in one of the two. Pure.
  */
 export declare const thinFilmRainbow: import('typegpu').TgpuFn<(phase: d.F32) => d.Vec3f>;
 /**

package/dist/core/gpu/kit/effects/thinFilm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"thinFilm.d.ts","sourceRoot":"","sources":["../../../../src/gpu/kit/effects/thinFilm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAO,CAAC,EAAmB,MAAM,UAAU,CAAA;AAElD,OAAO,KAAK,EAAC,IAAI,EAAE,iBAAiB,EAAC,MAAM,gBAAgB,CAAA;AAQ3D;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACnC,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;IACtE,QAAQ,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;IACjF,UAAU,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;IAC3E,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CACxF;AAED,MAAM,WAAW,qBAAqB;IAClC;;0DAEsD;IACtD,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;2FACuF;IACvF,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,IAAI,CAAA;IAChC;4FACwF;IACxF,cAAc,CAAC,EAAE,OAAO,CAAA;CAC3B;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,0PAqCpB,CAAA;AAEN;;;GAGG;AACH,eAAO,MAAM,eAAe,qDAO1B,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,qDAU/B,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,4GAO1B,CAAA;AAMF;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,IAAI,EAC9B,OAAO,CAAC,EAAE,qBAAqB,GAChC,IAAI,CAqDN"}
+{"version":3,"file":"thinFilm.d.ts","sourceRoot":"","sources":["../../../../src/gpu/kit/effects/thinFilm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAO,CAAC,EAAmB,MAAM,UAAU,CAAA;AAElD,OAAO,KAAK,EAAC,IAAI,EAAE,iBAAiB,EAAC,MAAM,gBAAgB,CAAA;AAS3D;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACnC,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;IACtE,QAAQ,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;IACjF,UAAU,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;IAC3E,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CACxF;AAED,MAAM,WAAW,qBAAqB;IAClC;;0DAEsD;IACtD,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;2FACuF;IACvF,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,IAAI,CAAA;IAChC;4FACwF;IACxF,cAAc,CAAC,EAAE,OAAO,CAAA;CAC3B;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,0PAqCpB,CAAA;AAEN;;;;;GAKG;AACH,eAAO,MAAM,eAAe,qDAG1B,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,qDAU/B,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,4GAO1B,CAAA;AAMF;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,IAAI,EAC9B,OAAO,CAAC,EAAE,qBAAqB,GAChC,IAAI,CAqDN"}

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

@@ -0,0 +1,143 @@
+import { d } from './index';
+
+/**
+ * The exponential-scale noise framing: aspect-correct the UV (x scaled, y left alone), scale by
+ * `exp(scale)`, and offset by `seed`. Returns the sampling position for a 2D/3D noise field.
+ *
+ * `exp(scale)` rather than `scale` is what makes the UI slider feel linear — each +1 doubles-ish
+ * the frequency — and it is why every noise texture's `scale` prop runs over a small signed range
+ * (−2…5) rather than a cell count.
+ *
+ * `seed` is added to BOTH axes after scaling (not before), which is why changing the seed slides
+ * the pattern rather than rescaling it.
+ */
+export declare const aspectScaledDomain: import('typegpu').TgpuFn<(uv: d.Vec2f, viewport: d.Vec2f, scale: d.F32, seed: d.F32) => d.Vec2f>;
+/**
+ * The per-pixel framing: floor the device-pixel position into `grain`-sized cells, offset by
+ * `seed`. For patterns that are defined on the pixel grid rather than in UV space (blue noise,
+ * ordered dither) — the `floor` is load-bearing, it is what makes the result piecewise-constant per
+ * cell instead of resampling the hash continuously.
+ *
+ * `viewport` must be the EFFECTIVE viewport (`effectiveViewportSize ?? ctx.viewportSize`) so a
+ * resize-fit box grains at its own pixel scale rather than the canvas's.
+ */
+export declare const pixelGridDomain: import('typegpu').TgpuFn<(uv: d.Vec2f, viewport: d.Vec2f, grain: d.F32, seed: d.F32) => d.Vec2f>;
+/**
+ * Lift a 2D position into 3D by walking the third axis with time: `vec3(pos.xy, t * rate)`.
+ *
+ * This is the difference between noise that MORPHS in place and noise that slides. Offsetting the
+ * 2D position by time translates the pattern across the screen; walking a third axis of a 3D noise
+ * evolves it without moving it, which is what every "…that morphs over time" generator wants.
+ * `rate` scales the evolution independently of the node's `speed` prop.
+ */
+export declare const timeAxisDomain: import('typegpu').TgpuFn<(pos: d.Vec2f, t: d.F32, rate: d.F32) => d.Vec3f>;
+/** Per-octave drift shape — see {@link fbmGated}. */
+export type FbmDrift = 'goldenAngle' | 'timeSeed';
+export interface FbmGatedOptions {
+    /**
+     * The fixed loop count. STRUCTURAL: it is baked into the emitted WGSL, so the octave slider's
+     * MAXIMUM belongs here and its current value is a runtime gate (see the `octaveCount` argument).
+     * Unrolling exactly the active count instead would recompile on every slider step.
+     */
+    maxOctaves: number;
+    /**
+     * How successive octaves are decorrelated:
+     * - `goldenAngle` — each octave's domain is offset by `animTime · (cos(i·GOLDEN), sin(i·GOLDEN))`.
+     *   Incommensurate directions, so octaves interfere rather than translating together.
+     * - `timeSeed` — each octave gets its own time and seed offset (`animTime + i·stride.x`,
+     *   `seed + i·stride.y`), for field functions that animate internally.
+     */
+    drift: FbmDrift;
+    /** Per-octave (time, seed) stride for `drift: 'timeSeed'`. Folded to literals. */
+    stride?: [number, number];
+    /** Emitted WGSL identifier base. The option key is appended, so configs cannot collide. */
+    name?: string;
+}
+/**
+ * The gated fractal-sum loop, as a builder: sum `maxOctaves` evaluations of `fieldFn` at
+ * geometrically increasing frequency and decreasing amplitude, with octaves at or beyond a RUNTIME
+ * `octaveCount` contributing exactly zero.
+ *
+ * Returns a `tgpu.fn` yielding `vec2(accumulated, totalWeight)` — NOT a normalized value. The
+ * normalization tail is deliberately left to the caller because the consumers disagree about it
+ * (one divides raw and remaps to [0,1]; the other guards the divide and applies a per-mode scale),
+ * and folding those into an option record would have been four more flags for no shared code.
+ *
+ * The emitted signature depends on `drift`:
+ *
+ * - `goldenAngle`: `(base: vec2f, baseFreq, lacunarity, persistence, animTime, seedOffset: vec2f,
+ *   octaveCount) → vec2f`, calling `fieldFn(coord: vec2f) → f32`.
+ * - `timeSeed`: `(base: vec2f, baseFreq, lacunarity, persistence, animTime, seed, extra: vec3f,
+ *   octaveCount) → vec2f`, calling `fieldFn(oUV, animT, seedOff, extra.x, extra.y, extra.z) → f32`.
+ *   The `extra` vec3 is the C1 struct-over-scalars rule applied cheaply: field functions with their
+ *   own parameters (jitter, metric, reduction) pass them through one bundle.
+ *
+ * NAMING CONSEQUENCE: the captured field function is emitted into WGSL under the BUILDER's local
+ * identifier (`octaveField`), not its own name — a transpiled body registers its externals by the
+ * identifier the source text uses. So a shader that passes `noise.mxNoiseFloat2` will see
+ * `fn octaveField(p: vec2f)` in its WGSL. Harmless (the resolver uniquifies collisions), but it means
+ * a snapshot diff over an fbm migration shows the field fn renamed as well as the loop moved.
+ *
+ * The active-octave gate is spelled per drift mode (`i32` compare for `goldenAngle`, `f32` compare
+ * for `timeSeed`), matching what each consumer emitted before migration. The two spellings are
+ * equivalent for integral counts.
+ *
+ * TRAP: the accumulator/weight/frequency locals are initialized from `d.f32(…)`, not bare literals
+ * — an integer-valued literal initializer transpiles to i32 and truncates the whole sum.
+ */
+export declare function fbmGated(fieldFn: FbmField2, options: FbmGatedOptions & {
+    drift: 'goldenAngle';
+}): FbmGoldenSumFn;
+export declare function fbmGated(fieldFn: FbmFieldParametric, options: FbmGatedOptions & {
+    drift: 'timeSeed';
+}): FbmTimeSeedSumFn;
+/** A field function of one 2D position, for `drift: 'goldenAngle'`. */
+export type FbmField2 = (coord: d.v2f) => number;
+/** A field function with its own time/seed/parameter arguments, for `drift: 'timeSeed'`. */
+export type FbmFieldParametric = (oUV: d.v2f, animT: number, seedOff: number, a: number, b: number, c: number) => number;
+/** `drift: 'goldenAngle'` output — callable from a body, returning `vec2(accumulated, totalWeight)`. */
+export type FbmGoldenSumFn = (base: d.v2f, baseFreq: number, lacunarity: number, persistence: number, animTime: number, seedOffset: d.v2f, octaveCount: number) => d.v2f;
+/** `drift: 'timeSeed'` output — callable from a body, returning `vec2(accumulated, totalWeight)`. */
+export type FbmTimeSeedSumFn = (base: d.v2f, baseFreq: number, lacunarity: number, persistence: number, animTime: number, seed: number, extra: d.v3f, octaveCount: number) => d.v2f;
+export interface DomainWarp2Options {
+    /**
+     * The four 3D offsets that decorrelate the warp samples — two per level, one per displacement
+     * component — applied as `pos + offset`. Defaults to the canonical Inigo-Quilez set (as used by
+     * Plasma).
+     *
+     * WHICH COMPONENTS TIME-SCALE IS FIXED PER SLOT, not inferred from the values. `q[0]` is the only
+     * entry whose x and y are time RATES (emitted as `vec3f(t·x, t·y, z)`, so its third component is
+     * a plain spatial z); `q[1]`, `r[0]` and `r[1]` all take x/y as plain spatial offsets and their
+     * third component as a time rate (`vec3f(x, y, t·z)`). Changing a slot's layout means editing the
+     * builder body, not the table.
+     */
+    offsets?: {
+        /** Level 1: `q[0]` is `[xTimeRate, yTimeRate, z]`; `q[1]` is `[x, y, zTimeRate]`. */
+        q: [[number, number, number], [number, number, number]];
+        /** Level 2: both entries are `[x, y, zTimeRate]`. */
+        r: [[number, number, number], [number, number, number]];
+    };
+    /** Emitted WGSL identifier base. */
+    name?: string;
+}
+/**
+ * Two-level Inigo-Quilez domain warping over a 3D field function: sample the field twice to build a
+ * 2D displacement, displace the sampling position, do it again from the displaced position, then
+ * return the position to sample the field at for the final value.
+ *
+ * Both levels displace the ORIGINAL position (`pos + d`), not the previous level's — level 2 only
+ * uses the level-1 result to decide WHERE to take its displacement samples. That is what keeps the
+ * warp from compounding into mush at high `warpAmount`.
+ *
+ * The emitted signature is `(pos: vec3f, t: f32, warpAmount: f32) → vec3f`: the final sampling
+ * position, so the caller owns the last field evaluation and any remap of it.
+ *
+ * Which offset components are multiplied by `t` is fixed per slot rather than inferred from the
+ * values — see {@link DomainWarp2Options.offsets} and {@link IQ_WARP_OFFSETS}.
+ */
+export declare function domainWarp2(fieldFn: Warp3Field, options?: DomainWarp2Options): Warp3Fn;
+/** A 3D scalar field function (`mxNoiseFloat3`, `perlin13`, …). */
+export type Warp3Field = (p: d.v3f) => number;
+/** {@link domainWarp2}'s output: `(pos, t, warpAmount) → final sampling position`. */
+export type Warp3Fn = (pos: d.v3f, t: number, warpAmount: number) => d.v3f;
+//# sourceMappingURL=fields.d.ts.map

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

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

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

@@ -0,0 +1,129 @@
+import { d } from './index';
+
+/**
+ * Aspect ratio (width / height) from a viewport size, guarded: `x / max(y, 1e-6)`.
+ *
+ * The guard exists because a canvas can report a zero height for one frame during init/resize;
+ * unguarded, that frame renders NaN. 1e-6 is far below any real pixel height, so the guard is
+ * unreachable for every valid viewport — it only replaces division by exactly-or-near zero.
+ */
+export declare const aspectOf: import('typegpu').TgpuFn<(viewport: d.Vec2f) => d.F32>;
+/**
+ * Floored modulo of a scalar: `x - m * floor(x / m)`. Unlike WGSL's `%` (truncated, keeps the
+ * sign of the dividend) this always returns a value in [0, m) for positive `m`, which is what
+ * tiling wants for negative coordinates.
+ */
+export declare const flooredMod1: import('typegpu').TgpuFn<(x: d.F32, m: d.F32) => d.F32>;
+/**
+ * Per-component floored modulo of a vec2 — the tiling primitive. Body is the exact math from
+ * `shaders/HexGrid/index.ts`'s local copy (component-wise, not vector ops) so adopting it emits
+ * an identical body.
+ */
+export declare const flooredMod2: import('typegpu').TgpuFn<(p: d.Vec2f, m: d.Vec2f) => d.Vec2f>;
+/**
+ * Sign-preserving guarded divide: `n / den`, with `den` pushed out to at least 1e-5 in magnitude
+ * on whichever side of zero it already sits.
+ *
+ * Preserving the sign matters — clamping to `max(den, eps)` would flip the quotient's sign for
+ * small negative denominators, which reads as a discontinuity through zero rather than a large
+ * value. 1e-5 is the epsilon the fleet's hand-rolled copies use: small enough that any
+ * geometrically meaningful denominator passes through untouched, large enough that the quotient
+ * stays inside f32 range for UV-scale numerators.
+ *
+ * The parameter is named `den`, not `d` — `d` is the data-schema namespace in kit scope.
+ */
+export declare const safeDiv: import('typegpu').TgpuFn<(n: d.F32, den: d.F32) => d.F32>;
+/**
+ * Rotate a 2D point about the origin by a precomputed cos/sin pair. Takes the pair rather than an
+ * angle so callers that rotate many points (or that already resolved the angle on the CPU) compute
+ * the trig once; for a constant angle it folds to two literals.
+ */
+export declare const rotate2: import('typegpu').TgpuFn<(p: d.Vec2f, cosA: d.F32, sinA: d.F32) => d.Vec2f>;
+/**
+ * Aspect-corrected screen UV, **no Y flip**: `(uv.x * aspect, uv.y)`, with the guarded aspect.
+ *
+ * This is the framing that makes a pattern's cells square: X is stretched into the same units as Y,
+ * so the domain runs `[0, aspect] × [0, 1]` and the canvas centre sits at `(aspect * 0.5, 0.5)`.
+ *
+ * The flip choice is in the name, not an argument — see {@link aspectCorrectedUVFlipY} and the
+ * D-1 note in this file's header.
+ */
+export declare const aspectCorrectedUV: import('typegpu').TgpuFn<(uv: d.Vec2f, viewport: d.Vec2f) => d.Vec2f>;
+/**
+ * Aspect-corrected screen UV **with the Y flip**: `(uv.x * aspect, 1 - uv.y)`, guarded aspect.
+ *
+ * Y-flipping puts the pattern's origin at the bottom-left rather than the top-left, so a row index
+ * of 0 is the bottom row. Sibling generators genuinely disagree about this (Grid and DotGrid flip,
+ * HexGrid and Truchet do not) and both looks are shipped, which is why neither is the default.
+ */
+export declare const aspectCorrectedUVFlipY: import('typegpu').TgpuFn<(uv: d.Vec2f, viewport: d.Vec2f) => d.Vec2f>;
+/**
+ * Recover the authored Y of a position prop: `(p.x, 1 - p.y)`.
+ *
+ * `transformPosition` stores a position as `(x, 1 - y)` so the design editor's top-left origin
+ * round-trips, which means every shader reading a position prop has to undo the flip. This is that
+ * undo, named — the bare `1.0 - center.y` is the single most-copied line in the gradient fleet.
+ */
+export declare const unflipPosition: import('typegpu').TgpuFn<(p: d.Vec2f) => d.Vec2f>;
+/**
+ * A `transformPosition`-stored centre, moved into aspect-corrected space: `(pos.x * aspect, 1 - pos.y)`.
+ *
+ * Combines {@link unflipPosition} with the D-1 center-scaled rule in one step, because that pair is
+ * what a centred generator actually needs. `aspect` is passed in rather than derived so a caller
+ * that scales several centres (MultiPointGradient's five control points) divides once.
+ */
+export declare const aspectCentrePosition: import('typegpu').TgpuFn<(pos: d.Vec2f, aspect: d.F32) => d.Vec2f>;
+/**
+ * Vector from a `transformPosition`-stored centre to a screen UV, both in aspect-corrected space:
+ * `(uv.x * aspect - center.x * aspect, uv.y - (1 - center.y))`. Guarded aspect.
+ *
+ * This is the canonical D-1 delta — the centre is scaled, NOT the UV alone. It is the opening of
+ * every centred field (radial/conic/diamond gradients, spirals): everything downstream is a
+ * function of this delta.
+ */
+export declare const aspectCenteredDelta: import('typegpu').TgpuFn<(uv: d.Vec2f, center: d.Vec2f, viewport: d.Vec2f) => d.Vec2f>;
+/**
+ * Vector from the canvas centre to a screen UV in aspect-corrected space:
+ * `(uv.x * aspect - aspect * 0.5, uv.y - 0.5)`.
+ *
+ * The fixed-centre case of {@link aspectCenteredDelta} (equivalent to passing a centre of
+ * `(0.5, 0.5)`), for the patterns that pivot on the canvas centre and have no centre prop. It takes
+ * `aspect` rather than the viewport because these callers need `aspect` again afterwards — to
+ * un-correct the rotated result, or to size the lattice.
+ */
+export declare const canvasCentredDelta: import('typegpu').TgpuFn<(uv: d.Vec2f, aspect: d.F32) => d.Vec2f>;
+/**
+ * Rotate an ALREADY aspect-corrected UV about the canvas centre `(aspect * 0.5, 0.5)`, by a
+ * precomputed cos/sin pair.
+ *
+ * Rotating about the centre rather than the origin is what makes a `rotation` prop read as "spin
+ * the pattern in place" instead of "swing it off screen". Callers own the sign: negate the angle
+ * before taking cos/sin if positive rotation should read clockwise.
+ *
+ * The centre is derived from `aspect`, so this must be handed a UV in the
+ * {@link aspectCorrectedUV} / {@link aspectCorrectedUVFlipY} framing — not a raw `[0,1]²` UV.
+ */
+export declare const rotateAboutCanvasCentre: import('typegpu').TgpuFn<(p: d.Vec2f, aspect: d.F32, cosA: d.F32, sinA: d.F32) => d.Vec2f>;
+/**
+ * Signed projection of a point onto a direction given as a cos/sin pair: `p.x * cosA + p.y * sinA`.
+ *
+ * The scalar coordinate every directional pattern is a function of — stripe phase, linear-gradient
+ * parameter, chevron axis. One number instead of a rotated vector, so the perpendicular component
+ * is never computed for patterns that do not use it.
+ */
+export declare const directionalProjection: import('typegpu').TgpuFn<(p: d.Vec2f, cosA: d.F32, sinA: d.F32) => d.F32>;
+/**
+ * Cartesian → polar: `(length(p), atan2(p.y, p.x))`. The angle is in radians on `[-π, π]`, zero at
+ * the 3-o'clock position, increasing counter-clockwise in a Y-up frame.
+ *
+ * Returns both components because the callers that want one usually want the other one step later
+ * (a spiral is radius plus angle; a conic band is angle alone). Divide the angle by
+ * `constants.TAU` to get a `[-0.5, 0.5]` turn fraction.
+ */
+export declare const toPolar: import('typegpu').TgpuFn<(p: d.Vec2f) => d.Vec2f>;
+/**
+ * Polar → cartesian: `(r * cos(theta), r * sin(theta))`. The inverse of {@link toPolar}, exact for
+ * any `r >= 0` and `theta` in `[-π, π]`.
+ */
+export declare const fromPolar: import('typegpu').TgpuFn<(r: d.F32, theta: d.F32) => d.Vec2f>;
+//# sourceMappingURL=geom.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"geom.d.ts","sourceRoot":"","sources":["../../../src/gpu/kit/geom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAO,CAAC,EAAM,MAAM,SAAS,CAAA;AAEpC;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,wDAGnB,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,yDAGtB,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,+DAGtB,CAAA;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,2DAKlB,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,OAAO,6EAGlB,CAAA;AAIF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,uEAI5B,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,uEAIjC,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,mDAGzB,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,oEAG/B,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,wFAI9B,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,mEAG7B,CAAA;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,4FAOlC,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,2EAGhC,CAAA;AAIF;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,mDAGlB,CAAA;AAEF;;;GAGG;AACH,eAAO,MAAM,SAAS,+DAGpB,CAAA"}

package/dist/core/gpu/kit/host/canvasRaster.d.ts

@@ -0,0 +1,104 @@
+import { GpuFragmentParams } from '../../contract';
+
+export interface CanvasRasterTargetOptions {
+    /** Hard cap per axis, in texels. WebGPU's floor is 8192; the fleet's convention is 4096. */
+    maxAxis?: number;
+    /**
+     * Supersample factor applied ON TOP of the device pixel ratio. The headroom is what survives
+     * MAGNIFICATION: a distortion that scales rastered content past the atlas's density resamples
+     * texels, and past ~2× that reads as soft edges. Default 1 (no supersampling).
+     */
+    supersample?: number;
+    /** Passed through to `getContext('2d')` — Ascii and ObjectTracker want `willReadFrequently`. */
+    contextAttributes?: CanvasRenderingContext2DSettings;
+}
+export interface RasterSize {
+    /** Device-pixels per CSS pixel actually used, after the max-axis clamp. */
+    scale: number;
+    /** Texture width, `max(2, round(cssWidth · scale))`. */
+    texW: number;
+    /** Texture height, `max(2, round(cssHeight · scale))`. */
+    texH: number;
+}
+export interface CanvasRasterTarget {
+    /**
+     * The 2D context, creating the canvas on first call. Null when the host has no 2D context (or
+     * after cleanup) — every caller must handle that, as a rasterizing shader with no context can
+     * only render transparent.
+     */
+    context(): CanvasRenderingContext2D | null;
+    /** The backing canvas — pass it to `mediaTexture.write`. Null before the first `context()`. */
+    canvas(): HTMLCanvasElement | null;
+    /**
+     * Resolve the raster resolution for a CSS-pixel box: device pixel ratio × supersample, clamped so
+     * NEITHER axis exceeds `maxAxis`, then rounded with a 2-texel floor. Degrading the density is the
+     * correct failure mode for a long text run — an over-cap texture allocation would throw.
+     */
+    rasterSize(cssWidth: number, cssHeight: number): RasterSize;
+    /** Resize the canvas to `w`×`h` and clear it. Returns the context, or null when unavailable. */
+    resize(w: number, h: number): CanvasRenderingContext2D | null;
+    /** The host's real device-pixel ratio, derived from the canvas vs the logical dimensions. */
+    devicePixelRatio(): number;
+    /** True once the shader has been cleaned up. */
+    readonly disposed: boolean;
+}
+/**
+ * An offscreen 2D canvas sized in device pixels, with the scale invariant and the teardown wired up.
+ *
+ * The canvas is created LAZILY: an atlas shader that never rasters (empty `characters`, labels off)
+ * must not allocate a multi-megabyte backing store at composition time. Cleanup sets both axes to 0,
+ * which is what actually releases that store — dropping the reference alone leaves it to the GC.
+ */
+export declare function createCanvasRasterTarget(params: GpuFragmentParams, opts?: CanvasRasterTargetOptions): CanvasRasterTarget;
+export interface RasterInvalidatorOptions {
+    /**
+     * Everything the raster depends on, as one string. Include the canvas size for anything measured
+     * in device pixels — a resize changes the raster even when no prop did.
+     */
+    key(): string;
+    /**
+     * Minimum ms between key CHECKS, not between rasters. The check reads live prop handles, so it is
+     * not free; 16 ms (one frame at 60fps) is the fleet default, and an atlas whose props change
+     * rarely can afford 100 ms.
+     */
+    minIntervalMs?: number;
+    /** Re-raster. Called only when the key actually changed. */
+    run(): void;
+    /**
+     * Key value to treat as already-rendered. Pass the key matching a raster the shader performed
+     * eagerly at composition, so the first frame does not immediately redo it. Default `''` — no key
+     * matches, so the first check after the interval triggers a run.
+     */
+    initialKey?: string;
+}
+/** A throttled key-diff over `onBeforeRender`. */
+export declare function createRasterInvalidator(params: GpuFragmentParams, opts: RasterInvalidatorOptions): void;
+export interface FontDependentRasterOptions {
+    /** Font identity (family | weight | italic). A change re-triggers the load. */
+    key(): string;
+    /** Load the font for the CURRENT key. Rejection is expected and means "keep the fallback". */
+    load(): Promise<unknown>;
+    /**
+     * Re-raster now that the real font is available. Anything that must invalidate a MEASURE cache
+     * belongs at the top of this callback — `measureText` keys on font availability, so a cache
+     * populated with the fallback's metrics has to be dropped before re-measuring.
+     */
+    onLoaded(): void;
+}
+export interface FontDependentRaster {
+    /**
+     * Load the current font if it changed, then re-raster. Cheap and idempotent per key — call it
+     * next to every raster, including the invalidator's.
+     */
+    ensure(): void;
+}
+/**
+ * The two-pass webfont raster: draw immediately with whatever font is resolvable (so text appears on
+ * the first frame), then re-draw once the real font has loaded.
+ *
+ * Skipping the first pass and waiting for the font is the tempting simplification and it is wrong —
+ * a font load is a network round trip, and a text layer that renders nothing until it completes
+ * flashes empty on every cold load.
+ */
+export declare function createFontDependentRaster(opts: FontDependentRasterOptions): FontDependentRaster;
+//# sourceMappingURL=canvasRaster.d.ts.map

package/dist/core/gpu/kit/host/canvasRaster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvasRaster.d.ts","sourceRoot":"","sources":["../../../../src/gpu/kit/host/canvasRaster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,gBAAgB,CAAA;AAIrD,MAAM,WAAW,yBAAyB;IACtC,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gGAAgG;IAChG,iBAAiB,CAAC,EAAE,gCAAgC,CAAA;CACvD;AAED,MAAM,WAAW,UAAU;IACvB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAA;IACb,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IAC/B;;;;OAIG;IACH,OAAO,IAAI,wBAAwB,GAAG,IAAI,CAAA;IAC1C,+FAA+F;IAC/F,MAAM,IAAI,iBAAiB,GAAG,IAAI,CAAA;IAClC;;;;OAIG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,CAAA;IAC3D,gGAAgG;IAChG,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,wBAAwB,GAAG,IAAI,CAAA;IAC7D,6FAA6F;IAC7F,gBAAgB,IAAI,MAAM,CAAA;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACpC,MAAM,EAAE,iBAAiB,EACzB,IAAI,GAAE,yBAA8B,GACrC,kBAAkB,CA2DpB;AAID,MAAM,WAAW,wBAAwB;IACrC;;;OAGG;IACH,GAAG,IAAI,MAAM,CAAA;IACb;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,4DAA4D;IAC5D,GAAG,IAAI,IAAI,CAAA;IACX;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,kDAAkD;AAClD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,wBAAwB,GAAG,IAAI,CAcvG;AAID,MAAM,WAAW,0BAA0B;IACvC,+EAA+E;IAC/E,GAAG,IAAI,MAAM,CAAA;IACb,8FAA8F;IAC9F,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IACxB;;;;OAIG;IACH,QAAQ,IAAI,IAAI,CAAA;CACnB;AAED,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAA;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,0BAA0B,GAAG,mBAAmB,CAU/F"}