@mkbabb/glass-ui 4.1.0 → 4.2.0

package/dist/components/custom/dock/composables/useDockItemDrag.d.ts

@@ -0,0 +1,18 @@
+import { type Ref } from "vue";
+export interface UseDockItemDragParams {
+    /** The dock root element (the items live in its active layer). */
+    rootEl: Ref<HTMLElement | null>;
+    /** Whether the axis is armed (the `:draggable-items` prop). May be a getter. */
+    enabled: () => boolean;
+    /** The morph axis (`"x"` horizontal · `"y"` vertical). A getter (orientation flips). */
+    axis: () => "x" | "y";
+    /** Fired once on settle with the committed (from, to) item indices. */
+    onReorder?: (from: number, to: number) => void;
+}
+export interface UseDockItemDragReturn {
+    /** True while a dock item is being dragged. */
+    dragging: Readonly<Ref<boolean>>;
+    /** Tear down the gesture + listeners. */
+    detach: () => void;
+}
+export declare function useDockItemDrag(params: UseDockItemDragParams): UseDockItemDragReturn;

package/dist/components/custom/dock/composables/useDockShellProps.d.ts

@@ -154,6 +154,44 @@ export interface DockProps {
      * byte-identical to HEAD (the slot + the data-attr are present only when authored).
      */
     search?: boolean;
+    /**
+     * BD.W-DOCK-CORE (A13 / II.2) — arm the SHIPPED fission seam (additive, default
+     * `false`). When true the dock composes `useDockFission` (the n-ary detach
+     * orchestrator on the SAME `DOCK_SPRING` clock, BESIDE the morph engine — box-
+     * INVIOLATE, never editing `dockMorphContext`), auto-registers every child marked
+     * `data-dock-splittable` as a fission PIECE (its detach vector derived from its
+     * FLIP-measured center relative to the dock center), feeds the seam-tension on
+     * `@pointermove`, and exposes `split()`/`merge()`/`toggle()` via `defineExpose`. A
+     * non-splittable dock is byte-identical to HEAD. The ONE `<GooFilter>` mount must be mounted
+     * once at the app root (the goo `<filter>` the necks reference).
+     */
+    splittable?: boolean;
+    /**
+     * BD.W-DOCK-CORE (A13) — the fission CONTEXT (the `DOCK_SPLIT_SIGNATURES` row): the
+     * detach-vector family + neck stagger. `"nav"` (default) is inward-merge; `"search"`
+     * is a radial bloom; `"media"` is a lateral peel.
+     */
+    splitContext?: "search" | "media" | "nav";
+    /**
+     * BD.W-DOCK-CORE (A13) — where the detached sibling dock lands (reads the split
+     * vector). `"beside"` (default) is the radial/lateral lateral landing; `"above"`/
+     * `"below"` are the V-axis landings.
+     */
+    splitPlacement?: "beside" | "above" | "below";
+    /**
+     * BD.W-DOCK-CORE (A12) — arm the draggable-ITEMS axis (additive, default `false`).
+     * When true every child marked `data-dock-draggable` (or, lacking marks, every
+     * `.dock-icon-button` in the active layer) becomes GRABBABLE: a pointer-capture grab
+     * lets the user pull a dock item and the gesture follows ~1:1 with a volume-preserving
+     * gel-squish (the SHIPPED `useDragMorph` composing kf `Draggable` + `useLiquidFlex`
+     * "tanh" velocity-squish — NO second drag engine), then flings velocity-continuously to
+     * the nearest slot, committing a REORDER via `update:order`. Compositor-only
+     * (`transform: translate` — never a layout property); PRM-safe (the gesture still
+     * functions, the squish off, the release an instant nearest-snap); the roving-tabindex
+     * keyboard contract on the dock controls is preserved (a draggable strip that is
+     * keyboard-dead is the worse failure). A non-draggable dock is byte-identical to HEAD.
+     */
+    draggableItems?: boolean;
 }
 /** The resolved shell-prop computeds the GlassDock SFC binds. */
 export interface DockShellProps {

package/dist/components/custom/dock/constants.d.ts

@@ -17,6 +17,17 @@ export interface DockStackItem {
     icon?: Component;
     /** Optional per-member select handler (fired alongside the model write). */
     onSelect?: () => void;
+    /**
+     * BE.W-DOCK-RAIL-REALIZE — the per-FACET accent hue (the `mode="facets"` context
+     * carousel only — IGNORED by the macOS `mode="stack"` glyph fan). A complete
+     * `<color>` (a consumer DATA/context hue) written to the chip's `--glass-accent`
+     * (the BB.W-GLASS-ACCENT per-instance chromatic-rim axis, `rim.css`/`material.css`),
+     * so each context facet carries its OWN rim+glint hue — the AZ context-carousel
+     * identity. Unset ⇒ the neutral warm-cream rim (the `--glass-accent: transparent`
+     * no-op floor). NOT a plate-background fill (the accent rides the THIN rim/glint;
+     * presets-in-consumers — no consumer hue enters a library token).
+     */
+    accent?: string;
 }
 /**
  * BA.W-DOCK-SECTIONS — the three named zone kinds the declarative `<DockSection>`
@@ -61,8 +72,8 @@ export interface DockSectionDescriptor {
  * prior copies were a DRY hazard — a re-tune had to touch both).
  */
 export declare const DOCK_SPRING: {
-    readonly response: 0.32;
-    readonly dampingFraction: 0.7;
+    readonly response: number;
+    readonly dampingFraction: number;
 };
 /**
  * The CSS properties whose `transitionend` the dock-morph window watches to know a
@@ -84,4 +95,4 @@ export declare const DOCK_MORPH_LABEL = "glass-ui:dock-morph-context";
  *  edge sweeping past the cursor, not a real exit. */
 export declare const HOVER_INTENT_MS = 60;
 export declare const EDGE_BAND_PX = 24;
-export declare const MORPH_SETTLE_MS = 320;
+export declare const MORPH_SETTLE_MS = 840;

package/dist/components/custom/dock/index.d.ts

@@ -6,6 +6,7 @@ export { default as DockBackgroundToggle } from "./DockBackgroundToggle.vue";
 export { default as DockTabButton } from "./DockTabButton.vue";
 export { default as DockSelectTrigger } from "./DockSelectTrigger.vue";
 export { default as DockDropdownTrigger } from "./DockDropdownTrigger.vue";
+export { default as DockPopoverTrigger } from "./DockPopoverTrigger.vue";
 export { default as DockSeparator } from "./DockSeparator.vue";
 export { default as DockStack } from "./DockStack.vue";
 export type { DockStackItem } from "./constants";
@@ -19,3 +20,5 @@ export { useDockOrientationMorph, type DockMorphOrientation, type UseDockOrienta
 export { useDockCtaReceive, type UseDockCtaReceiveOptions, type UseDockCtaReceiveReturn, type DockCtaReceivePreset, } from "../../../composables/motion/useDockCtaReceive";
 export { useDockSearch } from "./composables";
 export type { UseDockSearchOptions, UseDockSearchReturn } from "./composables";
+export { GooFilter } from "../goo-filter";
+export { useDockFission, DOCK_SPLIT_SIGNATURES, type DockSplitContext, type DockSplitVector, type DockSplitSquishPeak, type DockSplitSignature, type DockFissionPieceRegistration, type DockFissionPieceHandle, type UseDockFissionOptions, type UseDockFissionReturn, } from "./composables/useDockFission";

package/dist/components/custom/dot-flow-field/composables/flowField.d.ts

@@ -38,6 +38,27 @@ export declare function curlFBM(p: Vec2): Vec2;
  * the round-trip anchor + the analytic ∇⊥h the displacement reads.
  */
 export declare function sampleVelocity(p: Vec2, timeSec: number, waves: readonly WaveComponent[], windSpeed: number, curlStrength: number): Vec2;
+/** The cursor-vortex lever set (the √φ-laddered radius + the spin/drag/burst gains). */
+export interface VortexParams {
+    cursor: Vec2;
+    /** Pointer velocity (domain units / sec). */
+    pointerVel: Vec2;
+    /** Flick-burst impulse 0..1. */
+    burst: number;
+    /** Pointer active? (inert when false — the vortex is off). */
+    active: boolean;
+    radius: number;
+    spin: number;
+    dragGain: number;
+    burstShove: number;
+}
+/**
+ * The velocity the cursor injects at `p` — the perturbation `cs_flow` adds to the curl
+ * current. A true tangential vortex (∇⊥ of the radial), plus a drag-along (the streamlines
+ * follow the gesture) and a radial flick shove (the shockwave), all gaussian-falling off the
+ * vortex radius. Returns the un-normalized perturbation in domain/sec.
+ */
+export declare function pointerVortex(p: Vec2, v: VortexParams): Vec2;
 /** The shipped domain half-extent (the lattice is laid out over [-half, half]²). */
 export declare const FLOW_DOMAIN_HALF = 0.85;
 /**

package/dist/components/custom/dot-flow-field/composables/flowGLProgram.d.ts

@@ -0,0 +1,8 @@
+export declare function compileGL(gl: WebGL2RenderingContext, type: number, src: string): WebGLShader;
+export declare function linkGL(gl: WebGL2RenderingContext, vsSrc: string, fsSrc: string): WebGLProgram;
+/** Probe whether an internal format is color-renderable as a float FBO target (R-A). */
+export declare function probeRenderable(gl: WebGL2RenderingContext, internal: number, type: number): boolean;
+/** Pack a Float32Array to half-float (RGBA16F upload) — the RGBA32F-absent fallback (R-A). */
+export declare function float32ToHalf(src: Float32Array): Uint16Array;
+/** IEEE-754 float32 → float16 bits (the standard round-to-nearest packing). */
+export declare function f32ToF16(val: number): number;

package/dist/components/custom/dot-flow-field/composables/flowSetupGL.d.ts

@@ -0,0 +1,9 @@
+import type { WebGLCanvasFrame } from "../../../../composables/glass/webgl/useWebGLCanvas";
+import { type FlowSetupDeps } from "./useFlowParticles";
+/**
+ * Build the `setupGL(gl)` callback the picker invokes on the WebGL2 path (the LIVE path).
+ * `field` is the kept fullscreen-fragment dot-lattice; `flow` routes to the state-texture
+ * GPGPU + two-FBO trail + point-sprite motes + present composite (flowSetupGLFlow) — the SAME
+ * advected-population gestalt as the WGPU compute path (the ONE math source via the GLSL chunk).
+ */
+export declare function createFlowGLSetup(deps: FlowSetupDeps): (gl: WebGL2RenderingContext) => WebGLCanvasFrame;

package/dist/components/custom/dot-flow-field/composables/flowSetupGLFlow.d.ts

@@ -0,0 +1,12 @@
+import type { WebGLCanvasFrame } from "../../../../composables/glass/webgl/useWebGLCanvas";
+import { type FlowSetupDeps } from "./useFlowParticles";
+/**
+ * The `flow` WebGL2 channel — the AURORA CURRENT, made real + measurable + equal-gestalt:
+ *   1. STATE-TEXTURE GPGPU advect pass (one texel per mote; pos/speed/life ping-pong),
+ *   2. TRAIL decay-blit (prev → cur at the derived α) on a two-FBO RGBA16F ping-pong,
+ *   3. MOTE point-sprite draw (additive into the trail; speed→hue/brightness),
+ *   4. PRESENT composite (trail over the warm floor + corner-bloom → the swapchain).
+ * The float state/trail RTs fall RGBA32F→RGBA16F where the render extension is absent (R-A);
+ * the trail is pinned NEAREST (no half-float-linear extension dependency).
+ */
+export declare function createFlowGLFlow(deps: FlowSetupDeps): (gl: WebGL2RenderingContext) => WebGLCanvasFrame;

package/dist/components/custom/dot-flow-field/composables/flowSetupWGPU.d.ts

@@ -0,0 +1,7 @@
+import type { WebGPUCanvasFrame } from "../../../../composables/glass/webgpu/useWebGPUCanvas";
+import { type FlowSetupDeps } from "./useFlowParticles";
+/**
+ * Build the dot-flow-field `setupWGPU(device, context, format)` callback. Closes over the
+ * config/palette getters + the renderer's demand gate + the pointer `onFrame`/`getPointer`.
+ */
+export declare function createFlowWGPUSetup(deps: FlowSetupDeps): (device: GPUDevice, context: GPUCanvasContext, format: GPUTextureFormat) => WebGPUCanvasFrame;

package/dist/components/custom/dot-flow-field/composables/uniformBridgeWGPU.d.ts

@@ -12,15 +12,34 @@ export interface FlowGridGeometry {
 export declare const FLOW_MAX_LATTICE = 16384;
 export declare function flowGridGeometry(gridPitchPx: number, canvasCssMin: number): FlowGridGeometry;
 export declare const FLOW_COMPUTE_UNIFORM_BYTES: number;
+/** The live pointer/vortex state the renderer feeds the compute kernel each frame. */
+export interface FlowPointerState {
+    /** Cursor in domain space ([-half,half]²). */
+    cursorX: number;
+    cursorY: number;
+    /** Pointer velocity in domain units / sec. */
+    velX: number;
+    velY: number;
+    /** Flick-burst impulse (0..1). */
+    burst: number;
+    /** Pointer active (1) / inert (0). */
+    active: number;
+}
+/** A rest (pointer-inert) state — the vortex is off. */
+export declare const FLOW_POINTER_REST: FlowPointerState;
 export interface FlowUniformScratch {
     buffer: ArrayBuffer;
     f32: Float32Array;
     i32: Int32Array;
 }
 export declare function createFlowComputeScratch(): FlowUniformScratch;
-/** Pack the compute uniforms in place. */
-export declare function packFlowComputeUniforms(scratch: FlowUniformScratch, config: FlowFieldConfig, timeSec: number, dt: number, geometry: FlowGridGeometry): FlowUniformScratch;
+/** Pack the compute uniforms in place. `count` is the live mote/lattice count (flow mode
+ *  uses particleCount; field mode uses the lattice geometry count). */
+export declare function packFlowComputeUniforms(scratch: FlowUniformScratch, config: FlowFieldConfig, timeSec: number, dt: number, geometry: FlowGridGeometry, count: number, pointer?: FlowPointerState): FlowUniformScratch;
 export declare const FLOW_RENDER_UNIFORM_BYTES: number;
+/** The speed normalizer (the modal mote speed maps to the ramp MIDDLE — H2: so the full
+ *  ember→gold→white spread paints, not a unimodal-amber blowout). */
+export declare const FLOW_SPEED_NORM = 0.022;
 export declare function createFlowRenderScratch(): FlowUniformScratch;
 /** The base resting brightness (the calm-lattice floor before the band lights a dot). */
 export declare const FLOW_BASE_BRIGHT = 0.22;
@@ -37,3 +56,10 @@ export declare const FLOW_PARTICLE_BYTES = 16;
  * so the seed only needs the starting position (the lattice settles on the first frames).
  */
 export declare function seedLatticeBuffer(geometry: FlowGridGeometry): Float32Array;
+/**
+ * BD.W-DOTFLOW-AURORA-CURRENT — seed the FLOW mote buffer: each mote scattered across the
+ * domain, life STAGGERED across [0, lifetimeSec) so deaths/respawns don't synchronize (the
+ * field never blinks). `(pos.x, pos.y, speed=0, life)` per index. A deterministic hash so
+ * the capture path reproduces.
+ */
+export declare function seedFlowBuffer(count: number, lifetimeSec: number): Float32Array;

package/dist/components/custom/dot-flow-field/composables/useFlowParticles.d.ts

@@ -1,7 +1,12 @@
-import type { WebGPUCanvasFrame } from "../../../../composables/glass/webgpu/useWebGPUCanvas";
-import type { WebGLCanvasFrame } from "../../../../composables/glass/webgl/useWebGLCanvas";
 import type { OklchStop } from "../../../../composables/color";
 import type { FlowFieldConfig } from "../constants";
+import { type FlowPointerState } from "./uniformBridgeWGPU";
+export { flowGridGeometry } from "./uniformBridgeWGPU";
+/** The deep warm-near-black floor + the warm rose corner-bloom (linear-sRGB), the §3 ground.
+ *  Resolved off a warm-fire-adjacent OKLCh ground (NOT teal). The demo preset overrides via
+ *  `config.background`; this is the fallback ground for the flow present-composite. */
+export declare const FLOW_FLOOR_OKLCH: OklchStop;
+export declare const FLOW_BLOOM_OKLCH: OklchStop;
 export interface FlowSetupDeps {
     canvas: HTMLCanvasElement;
     config: FlowFieldConfig;
@@ -11,21 +16,17 @@ export interface FlowSetupDeps {
     shouldContinue: () => boolean;
     /**
      * The per-frame pointer hook — useDotFlowField advances the shared
-     * `usePointerVelocityField` here (the no-own-rAF discipline; the renderer's loop feeds
-     * the push-API tick). ZERO own rAF.
+     * `usePointerVelocityField` here (the no-own-rAF discipline). ZERO own rAF.
      */
     onFrame?: (timeSec: number) => void;
+    /** The live pointer/vortex state the renderer feeds the flow kernel (rest = inert). */
+    getPointer?: () => FlowPointerState;
 }
-/**
- * Build the dot-flow-field `setupWGPU(device, context, format)` callback. Closes over the
- * config/palette getters + the renderer's demand gate + the pointer `onFrame` hook.
- */
-export declare function createFlowWGPUSetup(deps: FlowSetupDeps): (device: GPUDevice, context: GPUCanvasContext, format: GPUTextureFormat) => WebGPUCanvasFrame;
-/**
- * Build the `setupGL(gl)` callback the `createGpuSubstrate` WebGL2 path invokes — a clean
- * aurora-class fullscreen fragment pass (the retopology made the dot-lattice + brightness
- * model fragment-friendly; the Canvas2D point-cloud is GONE, clean break). It evaluates
- * the SAME `flowField.ts` height/displacement field the WGSL primary does, splicing the
- * SHARED GLSL color chunk (the ONE color source → no drift between the two backends).
- */
-export declare function createFlowGLSetup(deps: FlowSetupDeps): (gl: WebGL2RenderingContext) => WebGLCanvasFrame;
+/** A px-min reader (the lattice density rides the min CSS dimension). */
+export declare function cssMin(canvas: HTMLCanvasElement): number;
+/** The flow mote count, clamped to the storage/state cap. */
+export declare function flowCount(config: FlowFieldConfig): number;
+/** The square state-texture side that holds `count` motes (one texel each). */
+export declare function stateCols(count: number): number;
+export { createFlowWGPUSetup } from "./flowSetupWGPU";
+export { createFlowGLSetup } from "./flowSetupGL";

package/dist/components/custom/dot-flow-field/constants.d.ts

@@ -6,6 +6,14 @@ export declare const MAX_PARTICLES = 16384;
 export declare const MAX_WAVE_COMPONENTS = 8;
 /** Compile-time palette cap — mirrors the WGSL `MAX_FLOW_STOPS` #define. */
 export declare const MAX_FLOW_STOPS = 4;
+export declare const PHI = 1.618033988749895;
+export declare const SQRT_PHI: number;
+/**
+ * The per-frame trail decay α DERIVED from a half-life in seconds (DRY — `trailDecay` is
+ * NOT a free knob; the streak persistence is a proportion of `trailHalfLife`). At a 60fps
+ * reference cadence, α = 2^(−dtRef / halfLife) so the trail fades to ½ over `halfLife`.
+ */
+export declare function flowTrailDecay(halfLifeSec: number, dtRef?: number): number;
 /**
  * The full author schema — the studio's `useConfiguratorState` model. Every field is a
  * tunable the demo configurator drives; the SFC resolves it into the uniform table.
@@ -16,6 +24,49 @@ export declare const MAX_FLOW_STOPS = 4;
  * `displaceAmp`/`springK`; `coherence` maps the octave count + persistence.
  */
 export interface FlowFieldConfig {
+    /**
+     * BD.W-DOTFLOW-AURORA-CURRENT — the topology discriminator (the dock `dim`-idiom
+     * discipline: ONE schema, two orthogonal lever sets, no fork). `"flow"` (default) is
+     * the AURORA CURRENT — a dense population ADVECTED along the curl current, trailing
+     * fading ribbons of warm-fire light, the cursor a live vortex. `"field"` is the calm
+     * anchored halftone (the rebuild's content-deferential backdrop — the kept register).
+     */
+    mode: "flow" | "field";
+    /** Mote population (flow mode) — re-introduced, mode-scoped (field keeps gridPitch). */
+    particleCount: number;
+    /** Trail streak half-life in seconds (the √φ τ₀ anchor); `trailDecay` derives from it. */
+    trailHalfLife: number;
+    /** Half-res trail buffer scale (R-D — quarters the float fillrate at 0.5). */
+    trailScale: number;
+    /** Inertia 0..1: the velocity lerp rate (LOW = weighty arcs, eases into the field). */
+    turnRate: number;
+    /** Advection speed gain (|V| → displacement-per-frame). */
+    speedScale: number;
+    /** Brightness-from-speed gain (the velocity-map glow). */
+    speedGlow: number;
+    /** Mote lifetime in seconds before respawn (the √φ τ₀·φ rung). */
+    lifetimeSec: number;
+    /** Density-vignette strength (shared with field; thins spawns behind the content rect). */
+    edgeBias: number;
+    /** The clear content region (the v4 content-deferential vignette; shared with field). */
+    contentMask: {
+        cx: number;
+        cy: number;
+        rx: number;
+        ry: number;
+    } | null;
+    /** Cursor-vortex fall-off radius (the √φ r₀ anchor). */
+    vortexRadius: number;
+    /** Cursor-vortex tangential spin gain (the swirl). */
+    vortexSpin: number;
+    /** Cursor-drag advection gain (the streamlines follow the gesture). */
+    dragGain: number;
+    /** Flick-burst radial shove gain (the shockwave). */
+    burstShove: number;
+    /** WebGPU cartoon-cast shadow offset (drops on WebGL2/PRM/PRT). */
+    shadowOffset: number;
+    /** WebGPU velocity-anisotropic squash-stretch amount (drops on WebGL2/PRM/PRT). */
+    stretchAmp: number;
     /** The Gerstner sum-of-sines table (1..MAX_WAVE_COMPONENTS) — the LARGE-wave ladder. */
     waveComponents: WaveComponent[];
     /** The dispersion-driven sweep speed (scales ω). LOW = slow sweep (default 0.3). */

package/dist/components/custom/dot-flow-field/index.d.ts

@@ -1,5 +1,5 @@
 export { default as DotFlowField } from "./DotFlowField.vue";
 export { useDotFlowField, type DotFlowFieldHandle, type UseDotFlowFieldOptions, } from "./composables/useDotFlowField";
 export { type FlowFieldConfig, DEFAULT_FLOW_CONFIG, DEFAULT_WAVE_COMPONENTS, WARM_IDENTITY_PALETTE, MAX_PARTICLES, MAX_WAVE_COMPONENTS, MAX_FLOW_STOPS, } from "./constants";
-export { type WaveComponent, type Vec2, sampleVelocity, gerstnerVelocity, curlFBM, buildWaveLadder, gridOrigin, sampleHeight, sampleDisplacement, waveBand, FLOW_GRAVITY, FLOW_DOMAIN_HALF, } from "./composables/flowField";
+export { type WaveComponent, type Vec2, sampleVelocity, gerstnerVelocity, curlFBM, pointerVortex, type VortexParams, buildWaveLadder, gridOrigin, sampleHeight, sampleDisplacement, waveBand, FLOW_GRAVITY, FLOW_DOMAIN_HALF, } from "./composables/flowField";
 export type { OklchStop } from "../../../composables/color";

package/dist/components/custom/dot-flow-field/shaders/flow-field.compute.wgsl.d.ts

@@ -1 +1 @@
-export declare const FLOW_FIELD_COMPUTE_WGSL = "\nconst MAX_WAVE_COMPONENTS: i32 = 8;\nconst PI: f32 = 3.141592653589793;\nconst TAU: f32 = 6.283185307179586;\nconst FLOW_GRAVITY: f32 = 9.81;\nconst CURL_EPS: f32 = 0.012;\nconst FBM_ROT: mat2x2<f32> = mat2x2<f32>(0.8, 0.6, -0.6, 0.8);\n\nstruct Particle {\n  // (pos.x, pos.y, height, |disp|) \u2014 the anchored-lattice live state\n  data: vec4<f32>,\n};\n\n// \u2500\u2500 Uniforms (the typed-struct source-of-truth \u2014 see uniformBridgeWGPU.ts) \u2500\u2500\nstruct FlowUniforms {\n  // p0: (uTime, uDt, uWindSpeed, uCurlStrength)\n  p0: vec4<f32>,\n  // p1: (uGridPitch, uDisplaceAmp, uSpringK, uGridCols)  \u2014 the lattice geometry\n  p1: vec4<f32>,\n  // ints: (uWaveCount, uParticleCount, uGridColsI, _pad)\n  ints: vec4<i32>,\n  // each wave row: (amplitude, wavelength, directionDeg, phase)\n  waves: array<vec4<f32>, 8>,\n};\n\n@group(0) @binding(0) var<uniform> u: FlowUniforms;\n@group(0) @binding(1) var<storage, read_write> particles: array<Particle>;\n\n// \u2500\u2500 The deterministic lattice origin (transcribes flowField.ts gridOrigin) \u2500\u2500\nfn gridOrigin(index: u32, cols: i32, pitch: f32) -> vec2<f32> {\n  let c = max(cols, 1);\n  let col = i32(index) % c;\n  let row = i32(index) / c;\n  let half = f32(c - 1) * pitch * 0.5;\n  return vec2<f32>(f32(col) * pitch - half, f32(row) * pitch - half);\n}\n\n// \u2500\u2500 The Gerstner-sum analytic \u2207\u22A5h velocity (transcribes flowField.ts gerstnerVelocity) \u2500\u2500\nfn gerstnerVelocity(p: vec2<f32>, t: f32) -> vec2<f32> {\n  var dhdx = 0.0;\n  var dhdy = 0.0;\n  let windSpeed = u.p0.z;\n  let waveCount = u.ints.x;\n  for (var i = 0; i < MAX_WAVE_COMPONENTS; i = i + 1) {\n    if (i >= waveCount) { break; }\n    let w = u.waves[i];\n    let amplitude = w.x;\n    let wavelength = max(w.y, 1e-4);\n    let dirRad = w.z * PI / 180.0;\n    let phase = w.w;\n    let k = TAU / wavelength;\n    let d = vec2<f32>(cos(dirRad), sin(dirRad));\n    let omega = sqrt(FLOW_GRAVITY * k) * windSpeed;\n    let theta = k * (d.x * p.x + d.y * p.y) - omega * t + phase;\n    let akc = amplitude * k * cos(theta);\n    dhdx = dhdx + akc * d.x;\n    dhdy = dhdy + akc * d.y;\n  }\n  // v = \u2207\u22A5h = (\u2202h/\u2202y, \u2212\u2202h/\u2202x).\n  return vec2<f32>(dhdy, -dhdx);\n}\n\n// \u2500\u2500 The scalar Gerstner HEIGHT (transcribes flowField.ts sampleHeight \u2014 the brightness\n//    driver, normalized to \u2248[-1,1] by the total amplitude so the band thresholds are\n//    wave-table-independent). \u2500\u2500\nfn sampleHeight(o: vec2<f32>, t: f32) -> f32 {\n  var h = 0.0;\n  var ampSum = 0.0;\n  let windSpeed = u.p0.z;\n  let waveCount = u.ints.x;\n  for (var i = 0; i < MAX_WAVE_COMPONENTS; i = i + 1) {\n    if (i >= waveCount) { break; }\n    let w = u.waves[i];\n    let k = TAU / max(w.y, 1e-4);\n    let dirRad = w.z * PI / 180.0;\n    let d = vec2<f32>(cos(dirRad), sin(dirRad));\n    let omega = sqrt(FLOW_GRAVITY * k) * windSpeed;\n    let theta = k * (d.x * o.x + d.y * o.y) - omega * t + w.w;\n    h = h + w.x * sin(theta);\n    ampSum = ampSum + abs(w.x);\n  }\n  return h / max(ampSum, 1e-4);\n}\n\n// \u2500\u2500 Shared curl-noise basis (the WGSL twin of flow.glsl.ts curlFBM) \u2500\u2500\nfn hash21(p: vec2<f32>) -> f32 {\n  var p3 = fract(vec3<f32>(p.x, p.y, p.x) * 0.1031);\n  p3 = p3 + dot(p3, p3.yzx + 33.33);\n  return fract((p3.x + p3.y) * p3.z);\n}\n\nfn valueNoise(p: vec2<f32>) -> f32 {\n  let i = floor(p);\n  let f = fract(p);\n  let u2 = f * f * f * (f * (f * 6.0 - 15.0) + 10.0);\n  let a = hash21(i + vec2<f32>(0.0, 0.0));\n  let b = hash21(i + vec2<f32>(1.0, 0.0));\n  let c = hash21(i + vec2<f32>(0.0, 1.0));\n  let d = hash21(i + vec2<f32>(1.0, 1.0));\n  return mix(mix(a, b, u2.x), mix(c, d, u2.x), u2.y);\n}\n\nfn potentialFBM(p0: vec2<f32>) -> f32 {\n  var v = 0.0;\n  var amp = 0.5;\n  var freq = 1.0;\n  var p = p0;\n  for (var i = 0; i < 3; i = i + 1) {\n    v = v + amp * valueNoise(p * freq);\n    p = FBM_ROT * p;\n    freq = freq * 2.0;\n    amp = amp * 0.5;\n  }\n  return v;\n}\n\nfn curlFBM(p: vec2<f32>) -> vec2<f32> {\n  let dx = potentialFBM(p + vec2<f32>(CURL_EPS, 0.0)) - potentialFBM(p - vec2<f32>(CURL_EPS, 0.0));\n  let dy = potentialFBM(p + vec2<f32>(0.0, CURL_EPS)) - potentialFBM(p - vec2<f32>(0.0, CURL_EPS));\n  let g = vec2<f32>(dx, dy) / (2.0 * CURL_EPS);\n  return vec2<f32>(g.y, -g.x);\n}\n\n// The composite flow velocity (transcribes flowField.ts sampleVelocity EXACTLY \u2014 the\n// coarse \u00D70.55 curl domain-scale, the \u00A73.2 inversion).\nfn sampleVelocity(p: vec2<f32>, t: f32) -> vec2<f32> {\n  let curlStrength = u.p0.w;\n  var v = gerstnerVelocity(p, t);\n  if (curlStrength > 0.0) {\n    let c = curlFBM(vec2<f32>(p.x * 0.55 + t * 0.15, p.y * 0.55));\n    v = v + c * curlStrength;\n  }\n  return v;\n}\n\n// The sub-cell DISPLACEMENT (transcribes flowField.ts sampleDisplacement \u2014 \u2207\u22A5h + the\n// coarse curl break, soft-clamped through tanh so the magnitude rides into [0,1)).\nfn sampleDisplacement(o: vec2<f32>, t: f32) -> vec2<f32> {\n  let v = sampleVelocity(o, t);\n  let mag = length(v);\n  if (mag < 1e-5) { return vec2<f32>(0.0, 0.0); }\n  let bounded = tanh(mag);\n  return v * (bounded / mag);\n}\n\n@compute @workgroup_size(64)\nfn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let idx = gid.x;\n  let count = u32(u.ints.y);\n  if (idx >= count) { return; } // bounds-guard the dispatch tail\n\n  let t = u.p0.x;\n  let dt = u.p0.y;\n  let pitch = u.p1.x;\n  let displaceAmp = u.p1.y;\n  let springK = u.p1.z;\n  let cols = u.ints.z;\n\n  // The PERMANENT anchor \u2014 no wrap, no re-seed (the coherence fix).\n  let o = gridOrigin(idx, cols, pitch);\n  let disp = sampleDisplacement(o, t);\n  let anchorTarget = o + disp * (displaceAmp * pitch);\n\n  var pr = particles[idx];\n  var pos = pr.data.xy;\n  // Framerate-independent critically-damped pull-to-anchor:\n  //   p \u2190 mix(p, anchorTarget, 1 - exp(-springK\u00B7dt))  (the GPGPU influence-pull pattern).\n  let k = 1.0 - exp(-springK * dt);\n  pos = mix(pos, anchorTarget, k);\n\n  let h = sampleHeight(o, t);\n  particles[idx] = Particle(vec4<f32>(pos, h, length(disp)));\n}\n";
+export declare const FLOW_FIELD_COMPUTE_WGSL = "\nconst MAX_WAVE_COMPONENTS: i32 = 8;\nconst PI: f32 = 3.141592653589793;\nconst TAU: f32 = 6.283185307179586;\nconst FLOW_GRAVITY: f32 = 9.81;\nconst CURL_EPS: f32 = 0.012;\nconst FBM_ROT: mat2x2<f32> = mat2x2<f32>(0.8, 0.6, -0.6, 0.8);\n\nstruct Particle {\n  // field: (pos.x, pos.y, height, |disp|) \u2014 the anchored-lattice live state\n  // flow:  (pos.x, pos.y, speed, life)    \u2014 the advected-mote live state\n  data: vec4<f32>,\n};\n\n// \u2500\u2500 Uniforms (the typed-struct source-of-truth \u2014 see uniformBridgeWGPU.ts) \u2500\u2500\nstruct FlowUniforms {\n  // p0: (uTime, uDt, uWindSpeed, uCurlStrength)\n  p0: vec4<f32>,\n  // p1: (uGridPitch, uDisplaceAmp, uSpringK, uGridCols)  \u2014 the lattice geometry (field)\n  p1: vec4<f32>,\n  // ints: (uWaveCount, uParticleCount, uGridColsI, uMode)  \u2014 uMode: 0=field, 1=flow\n  ints: vec4<i32>,\n  // f0: (uTurnRate, uSpeedScale, uLifetimeSec, uDomainHalf)  \u2014 the flow advection levers\n  f0: vec4<f32>,\n  // f1: (uVortexRadius, uVortexSpin, uDragGain, uBurstShove)  \u2014 the cursor vortex\n  f1: vec4<f32>,\n  // ptr: (cursor.x, cursor.y, vel.x, vel.y)  \u2014 the pointer in domain space + its velocity\n  ptr: vec4<f32>,\n  // ptr2: (burst, pointerActive, edgeBias, _pad)\n  ptr2: vec4<f32>,\n  // each wave row: (amplitude, wavelength, directionDeg, phase)\n  waves: array<vec4<f32>, 8>,\n};\n\n@group(0) @binding(0) var<uniform> u: FlowUniforms;\n@group(0) @binding(1) var<storage, read_write> particles: array<Particle>;\n\n// \u2500\u2500 The deterministic lattice origin (transcribes flowField.ts gridOrigin) \u2500\u2500\nfn gridOrigin(index: u32, cols: i32, pitch: f32) -> vec2<f32> {\n  let c = max(cols, 1);\n  let col = i32(index) % c;\n  let row = i32(index) / c;\n  let half = f32(c - 1) * pitch * 0.5;\n  return vec2<f32>(f32(col) * pitch - half, f32(row) * pitch - half);\n}\n\n// \u2500\u2500 The Gerstner-sum analytic \u2207\u22A5h velocity (transcribes flowField.ts gerstnerVelocity) \u2500\u2500\nfn gerstnerVelocity(p: vec2<f32>, t: f32) -> vec2<f32> {\n  var dhdx = 0.0;\n  var dhdy = 0.0;\n  let windSpeed = u.p0.z;\n  let waveCount = u.ints.x;\n  for (var i = 0; i < MAX_WAVE_COMPONENTS; i = i + 1) {\n    if (i >= waveCount) { break; }\n    let w = u.waves[i];\n    let amplitude = w.x;\n    let wavelength = max(w.y, 1e-4);\n    let dirRad = w.z * PI / 180.0;\n    let phase = w.w;\n    let k = TAU / wavelength;\n    let d = vec2<f32>(cos(dirRad), sin(dirRad));\n    let omega = sqrt(FLOW_GRAVITY * k) * windSpeed;\n    let theta = k * (d.x * p.x + d.y * p.y) - omega * t + phase;\n    let akc = amplitude * k * cos(theta);\n    dhdx = dhdx + akc * d.x;\n    dhdy = dhdy + akc * d.y;\n  }\n  // v = \u2207\u22A5h = (\u2202h/\u2202y, \u2212\u2202h/\u2202x).\n  return vec2<f32>(dhdy, -dhdx);\n}\n\n// \u2500\u2500 The scalar Gerstner HEIGHT (transcribes flowField.ts sampleHeight \u2014 the brightness\n//    driver, normalized to \u2248[-1,1] by the total amplitude so the band thresholds are\n//    wave-table-independent). \u2500\u2500\nfn sampleHeight(o: vec2<f32>, t: f32) -> f32 {\n  var h = 0.0;\n  var ampSum = 0.0;\n  let windSpeed = u.p0.z;\n  let waveCount = u.ints.x;\n  for (var i = 0; i < MAX_WAVE_COMPONENTS; i = i + 1) {\n    if (i >= waveCount) { break; }\n    let w = u.waves[i];\n    let k = TAU / max(w.y, 1e-4);\n    let dirRad = w.z * PI / 180.0;\n    let d = vec2<f32>(cos(dirRad), sin(dirRad));\n    let omega = sqrt(FLOW_GRAVITY * k) * windSpeed;\n    let theta = k * (d.x * o.x + d.y * o.y) - omega * t + w.w;\n    h = h + w.x * sin(theta);\n    ampSum = ampSum + abs(w.x);\n  }\n  return h / max(ampSum, 1e-4);\n}\n\n// \u2500\u2500 Shared curl-noise basis (the WGSL twin of flow.glsl.ts curlFBM) \u2500\u2500\nfn hash21(p: vec2<f32>) -> f32 {\n  var p3 = fract(vec3<f32>(p.x, p.y, p.x) * 0.1031);\n  p3 = p3 + dot(p3, p3.yzx + 33.33);\n  return fract((p3.x + p3.y) * p3.z);\n}\n\nfn valueNoise(p: vec2<f32>) -> f32 {\n  let i = floor(p);\n  let f = fract(p);\n  let u2 = f * f * f * (f * (f * 6.0 - 15.0) + 10.0);\n  let a = hash21(i + vec2<f32>(0.0, 0.0));\n  let b = hash21(i + vec2<f32>(1.0, 0.0));\n  let c = hash21(i + vec2<f32>(0.0, 1.0));\n  let d = hash21(i + vec2<f32>(1.0, 1.0));\n  return mix(mix(a, b, u2.x), mix(c, d, u2.x), u2.y);\n}\n\nfn potentialFBM(p0: vec2<f32>) -> f32 {\n  var v = 0.0;\n  var amp = 0.5;\n  var freq = 1.0;\n  var p = p0;\n  for (var i = 0; i < 3; i = i + 1) {\n    v = v + amp * valueNoise(p * freq);\n    p = FBM_ROT * p;\n    freq = freq * 2.0;\n    amp = amp * 0.5;\n  }\n  return v;\n}\n\nfn curlFBM(p: vec2<f32>) -> vec2<f32> {\n  let dx = potentialFBM(p + vec2<f32>(CURL_EPS, 0.0)) - potentialFBM(p - vec2<f32>(CURL_EPS, 0.0));\n  let dy = potentialFBM(p + vec2<f32>(0.0, CURL_EPS)) - potentialFBM(p - vec2<f32>(0.0, CURL_EPS));\n  let g = vec2<f32>(dx, dy) / (2.0 * CURL_EPS);\n  return vec2<f32>(g.y, -g.x);\n}\n\n// The composite flow velocity (transcribes flowField.ts sampleVelocity EXACTLY \u2014 the\n// coarse \u00D70.55 curl domain-scale, the \u00A73.2 inversion).\nfn sampleVelocity(p: vec2<f32>, t: f32) -> vec2<f32> {\n  let curlStrength = u.p0.w;\n  var v = gerstnerVelocity(p, t);\n  if (curlStrength > 0.0) {\n    let c = curlFBM(vec2<f32>(p.x * 0.55 + t * 0.15, p.y * 0.55));\n    v = v + c * curlStrength;\n  }\n  return v;\n}\n\n// The sub-cell DISPLACEMENT (transcribes flowField.ts sampleDisplacement \u2014 \u2207\u22A5h + the\n// coarse curl break, soft-clamped through tanh so the magnitude rides into [0,1)).\nfn sampleDisplacement(o: vec2<f32>, t: f32) -> vec2<f32> {\n  let v = sampleVelocity(o, t);\n  let mag = length(v);\n  if (mag < 1e-5) { return vec2<f32>(0.0, 0.0); }\n  let bounded = tanh(mag);\n  return v * (bounded / mag);\n}\n\n// \u2500\u2500 The cursor VORTEX injected into the velocity field (transcribes flowField.ts\n//    pointerVortex). r = p \u2212 cursor; a gaussian fall-off; a TRUE tangential \u2207\u22A5 swirl +\n//    a drag-along term + a radial burst shove. Inert when the pointer is inactive. \u2500\u2500\nfn pointerVortex(p: vec2<f32>) -> vec2<f32> {\n  if (u.ptr2.y < 0.5) { return vec2<f32>(0.0, 0.0); } // pointer inactive \u2192 no vortex\n  let cursor = u.ptr.xy;\n  let vel = u.ptr.zw;\n  let burst = u.ptr2.x;\n  let radius = max(u.f1.x, 1e-3);\n  let r = p - cursor;\n  let d = length(r);\n  let fall = exp(-(d * d) / (radius * radius));\n  let swirl = normalize(vec2<f32>(-r.y, r.x) + vec2<f32>(1e-6, 0.0)); // tangential \u2207\u22A5\n  let radial = r / max(d, 1e-4);\n  let v = swirl * u.f1.y          // the spin\n        + vel * u.f1.z            // the drag (streamlines follow the gesture)\n        + radial * burst * u.f1.w; // the flick shockwave\n  return v * fall;\n}\n\n// \u2500\u2500 density-weighted respawn: a hash-stratified seed inside the domain, biased toward the\n//    edges by edgeBias (a faint vignette \u2014 the field never thins to a hole). \u2500\u2500\nfn respawn(idx: u32, t: f32) -> vec2<f32> {\n  let half = u.f0.w;\n  let s = f32(idx) * 0.013 + t * 0.37;\n  let rx = hash21(vec2<f32>(s, 1.7)) * 2.0 - 1.0;\n  let ry = hash21(vec2<f32>(3.1, s)) * 2.0 - 1.0;\n  // edgeBias>0 pushes the seed toward the perimeter (a power-curve on |coord|).\n  let bias = clamp(u.ptr2.z, 0.0, 1.0);\n  let bx = sign(rx) * pow(abs(rx), mix(1.0, 0.5, bias));\n  let by = sign(ry) * pow(abs(ry), mix(1.0, 0.5, bias));\n  return vec2<f32>(bx, by) * half;\n}\n\n// \u2500\u2500 cs_field \u2014 the ANCHORED-LATTICE evaluator (BYTE-MOVED from cs_main; the field-mode\n//    fence-scoped unit; F1 greps the no-advection/no-reseed witness WITHIN this brace-span).\nfn cs_field(idx: u32, t: f32, dt: f32) {\n  let pitch = u.p1.x;\n  let displaceAmp = u.p1.y;\n  let springK = u.p1.z;\n  let cols = u.ints.z;\n\n  // The PERMANENT anchor \u2014 no wrap, no re-seed (the coherence fix).\n  let o = gridOrigin(idx, cols, pitch);\n  let disp = sampleDisplacement(o, t);\n  let anchorTarget = o + disp * (displaceAmp * pitch);\n\n  var pr = particles[idx];\n  var pos = pr.data.xy;\n  // Framerate-independent critically-damped pull-to-anchor:\n  //   p \u2190 mix(p, anchorTarget, 1 - exp(-springK\u00B7dt))  (the GPGPU influence-pull pattern).\n  let k = 1.0 - exp(-springK * dt);\n  pos = mix(pos, anchorTarget, k);\n\n  let h = sampleHeight(o, t);\n  particles[idx] = Particle(vec4<f32>(pos, h, length(disp)));\n}\n\n// \u2500\u2500 cs_flow \u2014 the AURORA CURRENT (the RE-INVENT register). Momentum-integrated advection\n//    along the curl current + the live cursor vortex, with lifetime decay + density-weighted\n//    respawn. F1b greps the pos+=v*dt + respawn( + pointerVortex( witness in THIS function.\nfn cs_flow(idx: u32, t: f32, dt: f32) {\n  let half = u.f0.w;\n  let turnRate = u.f0.x;\n  let speedScale = u.f0.y;\n  let lifetimeSec = max(u.f0.z, 1e-3);\n\n  var pr = particles[idx];\n  var pos = pr.data.xy;\n  var life = pr.data.w;\n\n  // First-frame / dead / out-of-domain seed (the density-weighted respawn).\n  let outOfDomain = max(abs(pos.x), abs(pos.y)) > half * 1.05;\n  if (life <= 0.0 || outOfDomain) {\n    pos = respawn(idx, t);\n    // stratify the initial life across [0,lifetime] so deaths don't synchronize.\n    life = lifetimeSec * hash21(vec2<f32>(f32(idx) * 0.027, t * 0.11));\n  }\n\n  // The target velocity: the divergence-free curl current + the cursor vortex.\n  let vField = sampleVelocity(pos, t) + pointerVortex(pos);\n  // Momentum/inertia: the low turnRate scales how hard the mote commits to the field\n  // each step \u2014 a weighty ease into the current's turns (arcs, not snaps), the\n  // overlapping-action/follow-through on a particle (R4-motion).\n  let v = vField * turnRate * speedScale;\n  // Forward-Euler advection step (the integrator \u2014 F1b's witness pos = pos + v*dt).\n  pos = pos + v * dt * 60.0;\n\n  life = life - dt;\n  let speed = length(v);\n  particles[idx] = Particle(vec4<f32>(pos, speed, life));\n}\n\n@compute @workgroup_size(64)\nfn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let idx = gid.x;\n  let count = u32(u.ints.y);\n  if (idx >= count) { return; } // bounds-guard the dispatch tail\n\n  let t = u.p0.x;\n  let dt = u.p0.y;\n  let mode = u.ints.w;\n\n  if (mode == 1) {\n    cs_flow(idx, t, dt);\n  } else {\n    cs_field(idx, t, dt);\n  }\n}\n";

package/dist/components/custom/dot-flow-field/shaders/flow-field.glsl.d.ts

@@ -2,3 +2,32 @@
 export declare const FLOW_FIELD_VERT_GLSL = "#version 300 es\nprecision highp float;\nin vec2 aPosition;\nout vec2 vUv;\nvoid main() {\n  vUv = aPosition;            // [-1,1]\u00B2 domain\n  gl_Position = vec4(aPosition, 0.0, 1.0);\n}";
 /** The dot-lattice + sweeping-brightness fragment source (the anchored-grid model). */
 export declare const FLOW_FIELD_FRAG_GLSL = "#version 300 es\nprecision highp float;\n\n#define PI 3.141592653589793\n#define TAU 6.283185307179586\n#define FLOW_GRAVITY 9.81\n#define CURL_EPS 0.012\n#define MAX_WAVE_COMPONENTS 8\n#define MAX_FLOW_STOPS 4\n\nin vec2 vUv;\nout vec4 fragColor;\n\nuniform float uTime;\nuniform float uWindSpeed;\nuniform float uCurlStrength;\nuniform float uDomainHalf;\nuniform float uAspect;\nuniform float uGridPitchDomain;  // lattice pitch in DOMAIN units\nuniform float uDotRadiusDomain;  // dot radius in DOMAIN units\nuniform float uDisplaceAmp;      // sub-cell drift in pitch fractions\nuniform float uContrast;\nuniform float uBaseBright;\nuniform float uWaveBandCenter;\nuniform float uWaveBandWidth;\nuniform float uGlobeMask;\nuniform int   uWaveCount;\nuniform int   uStopCount;\nuniform float uHasBackground;\nuniform vec3  uBg;\nuniform vec4  uWaves[MAX_WAVE_COMPONENTS];   // (amplitude, wavelength, directionDeg, phase)\nuniform vec3  uPalette[MAX_FLOW_STOPS];      // linear-sRGB stops\n\nconst mat2 FBM_ROT = mat2(0.8, 0.6, -0.6, 0.8);\n\n\nfloat srgbToLinearCh(float c) {\n    return c <= 0.04045 ? c / 12.92 : pow((c + 0.055) / 1.055, 2.4);\n}\nvec3 srgbToLinear(vec3 c) {\n    return vec3(srgbToLinearCh(c.r), srgbToLinearCh(c.g), srgbToLinearCh(c.b));\n}\n\nfloat linearToSrgbCh(float c) {\n    return c <= 0.0031308 ? c * 12.92 : 1.055 * pow(c, 1.0 / 2.4) - 0.055;\n}\nvec3 linearToSrgb(vec3 c) {\n    return vec3(linearToSrgbCh(c.r), linearToSrgbCh(c.g), linearToSrgbCh(c.b));\n}\n\n// value.js LINEAR_SRGB_TO_LMS (constants.ts), row-major; written here as GLSL\n// columns (= the transpose) so mat3 * vec3 evaluates the row-major M\u00B7v.\nconst mat3 LINEAR_SRGB_TO_LMS = mat3(\n    0.4122214708, 0.2119034982, 0.0883024619,\n    0.5363325363, 0.6806995451, 0.2817188376,\n    0.0514459929, 0.1073969566, 0.6299787005\n);\n\n// value.js srgbToOKLab's INLINE LMS\u2192OKLab coefficients (gamut.ts lines 295-297 \u2014\n// these differ at the ~1e-9 digit from LMS_TO_OKLAB_MATRIX; use the inline ones to\n// mirror the exact value.js path), row-major \u2192 GLSL columns.\nconst mat3 LMS_TO_OKLAB = mat3(\n    0.2104542553, 1.9779984951, 0.0259040371,\n    0.7936177850, -2.4285922050, 0.7827717662,\n    -0.0040720468, 0.4505937099, -0.8086757660\n);\n\n// value.js OKLAB_TO_LMS_COEFF (constants.ts), row-major \u2192 GLSL columns. Rows:\n// l = [1, 0.3963377774, 0.2158037573], m = [1, -0.1055613458, -0.0638541728],\n// s = [1, -0.0894841775, -1.2914855480].\nconst mat3 OKLAB_TO_LMS = mat3(\n    1.0, 1.0, 1.0,\n    0.3963377774, -0.1055613458, -0.0894841775,\n    0.2158037573, -0.0638541728, -1.2914855480\n);\n\n// value.js LMS_TO_LINEAR_SRGB (constants.ts), row-major \u2192 GLSL columns.\nconst mat3 LMS_TO_LINEAR_SRGB = mat3(\n    4.0767416621, -1.2684380046, -0.0041960863,\n    -3.3077115913, 2.6097574011, -0.7034186147,\n    0.2309699292, -0.3413193965, 1.7076147010\n);\n\n// Gamma sRGB \u2192 raw OKLab (L, a, b). Mirrors value.js srgbToOKLab.\nvec3 srgbToOklab(vec3 c) {\n    vec3 lin = srgbToLinear(c);\n    vec3 lms = LINEAR_SRGB_TO_LMS * lin;\n    vec3 lmsCbrt = sign(lms) * pow(abs(lms), vec3(1.0 / 3.0));\n    return LMS_TO_OKLAB * lmsCbrt;\n}\n\n// Raw OKLab (L, a, b) \u2192 linear sRGB. Mirrors value.js oklabToLinearSRGB.\nvec3 oklabToLinearSrgb(vec3 lab) {\n    vec3 lms_ = OKLAB_TO_LMS * lab;\n    vec3 lms = lms_ * lms_ * lms_;\n    return LMS_TO_LINEAR_SRGB * lms;\n}\n\n// OKLab \u2192 OKLCh: H in RADIANS. Mirrors value.js rawOklabToOklch (which returns\n// degrees; we stay in radians and only fold to [0, 2pi)).\nvec3 oklabToOklch(vec3 lab) {\n    float C = length(lab.yz);\n    float H = atan(lab.z, lab.y);\n    if (H < 0.0) H += 2.0 * PI;\n    return vec3(lab.x, C, H);\n}\n\n// OKLCh (H radians) \u2192 OKLab. Mirrors value.js rawOklchToOklab.\nvec3 oklchToOklab(vec3 lch) {\n    return vec3(lch.x, lch.y * cos(lch.z), lch.y * sin(lch.z));\n}\n\n// \u2500\u2500 The Gerstner-sum analytic \u2207\u22A5h velocity (transcribes flowField.ts gerstnerVelocity) \u2500\u2500\nvec2 gerstnerVelocity(vec2 p, float t) {\n  float dhdx = 0.0;\n  float dhdy = 0.0;\n  for (int i = 0; i < MAX_WAVE_COMPONENTS; i++) {\n    if (i >= uWaveCount) break;\n    vec4 w = uWaves[i];\n    float k = TAU / max(w.y, 1e-4);\n    float dirRad = w.z * PI / 180.0;\n    vec2 d = vec2(cos(dirRad), sin(dirRad));\n    float omega = sqrt(FLOW_GRAVITY * k) * uWindSpeed;\n    float theta = k * (d.x * p.x + d.y * p.y) - omega * t + w.w;\n    float akc = w.x * k * cos(theta);\n    dhdx += akc * d.x;\n    dhdy += akc * d.y;\n  }\n  return vec2(dhdy, -dhdx);\n}\n\n// \u2500\u2500 The scalar Gerstner HEIGHT (transcribes flowField.ts sampleHeight) \u2500\u2500\nfloat sampleHeight(vec2 o, float t) {\n  float h = 0.0;\n  float ampSum = 0.0;\n  for (int i = 0; i < MAX_WAVE_COMPONENTS; i++) {\n    if (i >= uWaveCount) break;\n    vec4 w = uWaves[i];\n    float k = TAU / max(w.y, 1e-4);\n    float dirRad = w.z * PI / 180.0;\n    vec2 d = vec2(cos(dirRad), sin(dirRad));\n    float omega = sqrt(FLOW_GRAVITY * k) * uWindSpeed;\n    float theta = k * (d.x * o.x + d.y * o.y) - omega * t + w.w;\n    h += w.x * sin(theta);\n    ampSum += abs(w.x);\n  }\n  return h / max(ampSum, 1e-4);\n}\n\n// \u2500\u2500 Shared curl-noise basis (the GLSL twin of flow.glsl.ts curlFBM) \u2500\u2500\nfloat hash21(vec2 p) {\n  vec3 p3 = fract(vec3(p.x, p.y, p.x) * 0.1031);\n  p3 += dot(p3, p3.yzx + 33.33);\n  return fract((p3.x + p3.y) * p3.z);\n}\nfloat valueNoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u2 = f * f * f * (f * (f * 6.0 - 15.0) + 10.0);\n  float a = hash21(i + vec2(0.0, 0.0));\n  float b = hash21(i + vec2(1.0, 0.0));\n  float c = hash21(i + vec2(0.0, 1.0));\n  float d = hash21(i + vec2(1.0, 1.0));\n  return mix(mix(a, b, u2.x), mix(c, d, u2.x), u2.y);\n}\nfloat potentialFBM(vec2 p0) {\n  float v = 0.0;\n  float amp = 0.5;\n  float freq = 1.0;\n  vec2 p = p0;\n  for (int i = 0; i < 3; i++) {\n    v += amp * valueNoise(p * freq);\n    p = FBM_ROT * p;\n    freq *= 2.0;\n    amp *= 0.5;\n  }\n  return v;\n}\nvec2 curlFBM(vec2 p) {\n  float dx = potentialFBM(p + vec2(CURL_EPS, 0.0)) - potentialFBM(p - vec2(CURL_EPS, 0.0));\n  float dy = potentialFBM(p + vec2(0.0, CURL_EPS)) - potentialFBM(p - vec2(0.0, CURL_EPS));\n  vec2 g = vec2(dx, dy) / (2.0 * CURL_EPS);\n  return vec2(g.y, -g.x);\n}\nvec2 sampleVelocity(vec2 p, float t) {\n  vec2 v = gerstnerVelocity(p, t);\n  if (uCurlStrength > 0.0) {\n    vec2 c = curlFBM(vec2(p.x * 0.55 + t * 0.15, p.y * 0.55));\n    v += c * uCurlStrength;\n  }\n  return v;\n}\n// sub-cell displacement (transcribes flowField.ts sampleDisplacement \u2014 tanh soft-clamp).\nvec2 sampleDisplacement(vec2 o, float t) {\n  vec2 v = sampleVelocity(o, t);\n  float mag = length(v);\n  if (mag < 1e-5) return vec2(0.0);\n  return v * (tanh(mag) / mag);\n}\n\n// The sweeping bright-stripe band (transcribes flowField.ts waveBand).\nfloat waveBand(float h, float center, float width) {\n  float w = max(width, 1e-3);\n  float d = abs(h - center);\n  return 1.0 - smoothstep(0.0, w, d);\n}\n\n// The optional soft-disc globe mask (the reference's two-sphere composition).\nfloat globeMask(vec2 o, float t, float on) {\n  if (on <= 0.5) return 1.0;\n  float cx = 0.35 * sin(t * 0.13);\n  float cy = 0.28 * cos(t * 0.11);\n  float d = length(o - vec2(cx, cy));\n  return 1.0 - smoothstep(0.45, 0.75, d);\n}\n\nvec3 samplePaletteLin(float t) {\n  if (uStopCount <= 1) return uPalette[0];\n  float n = float(uStopCount);\n  float ft = clamp(t, 0.0, 1.0) * (n - 1.0);\n  int i0 = int(floor(ft));\n  int i1 = min(i0 + 1, uStopCount - 1);\n  float f = ft - float(i0);\n  vec3 lmsA = LINEAR_SRGB_TO_LMS * uPalette[i0];\n  vec3 lmsB = LINEAR_SRGB_TO_LMS * uPalette[i1];\n  vec3 labA = LMS_TO_OKLAB * (sign(lmsA) * pow(abs(lmsA), vec3(1.0 / 3.0)));\n  vec3 labB = LMS_TO_OKLAB * (sign(lmsB) * pow(abs(lmsB), vec3(1.0 / 3.0)));\n  return oklabToLinearSrgb(mix(labA, labB, f));\n}\n\nvoid main() {\n  float aspect = max(uAspect, 1e-4);\n  // Domain-space pixel (aspect-corrected x so the lattice stays square).\n  vec2 p = vec2(vUv.x * aspect, vUv.y);\n  float pitch = max(uGridPitchDomain, 1e-3);\n\n  // The nearest lattice cell ORIGIN (the anchored grid \u2014 the deterministic gridOrigin\n  // mapping, evaluated per-pixel: round p/pitch to the nearest cell center).\n  vec2 cell = floor(p / pitch + 0.5);\n  vec2 o = cell * pitch;\n\n  // The dot DRIFTS toward o + disp\u00B7displaceAmp\u00B7pitch (the same sub-cell offset the\n  // compute kernel writes \u2014 here evaluated analytically per pixel).\n  vec2 disp = sampleDisplacement(o, uTime);\n  vec2 dotCenter = o + disp * (uDisplaceAmp * pitch);\n\n  // The soft circle around the (drifted) dot center.\n  float dist = length(p - dotCenter);\n  float radius = max(uDotRadiusDomain, 1e-4);\n  float mask = 1.0 - smoothstep(radius * 0.6, radius, dist);\n  if (mask < 0.002) {\n    if (uHasBackground > 0.5) {\n      fragColor = vec4(clamp(linearToSrgb(uBg), vec3(0.0), vec3(1.0)), 1.0);\n    } else {\n      fragColor = vec4(0.0);\n    }\n    return;\n  }\n\n  // The brightness lights the dot \u2014 the SWEEPING band over the height at the anchor.\n  float h = sampleHeight(o, uTime);\n  float band = waveBand(h, uWaveBandCenter, uWaveBandWidth);\n  float bright = (uBaseBright + band * uContrast) * globeMask(o, uTime, uGlobeMask);\n  bright = clamp(bright, 0.0, 1.6);\n\n  float tone = clamp(bright, 0.0, 1.0);\n  vec3 lin = samplePaletteLin(tone) * bright;\n  vec3 rgb = clamp(linearToSrgb(lin), vec3(0.0), vec3(1.0));\n  float alpha = mask * clamp(bright * 0.8 + 0.12, 0.0, 1.0);\n\n  if (uHasBackground > 0.5) {\n    vec3 bg = clamp(linearToSrgb(uBg), vec3(0.0), vec3(1.0));\n    fragColor = vec4(mix(bg, rgb, alpha), 1.0);\n    return;\n  }\n  fragColor = vec4(rgb * alpha, alpha);\n}";
+/** The fullscreen-quad vertex pass for the GPGPU/trail passes (a [-1,1] clip quad). */
+export declare const FLOW_FIELD_QUAD_VERT_GLSL = "#version 300 es\nprecision highp float;\nin vec2 aPosition;\nout vec2 vUv;\nvoid main() {\n  vUv = aPosition * 0.5 + 0.5;   // [0,1] texel space\n  gl_Position = vec4(aPosition, 0.0, 1.0);\n}";
+/**
+ * The STATE-TEXTURE GPGPU advect pass (proof:dotflow-fence F4 — the GPGPU export replacing
+ * the FLOW_FIELD_FRAG_GLSL mandate). One texel per mote, RGBA = (pos.x, pos.y, speed, life).
+ * Each frame: read prev state, advect along the curl current + the cursor VORTEX with
+ * momentum (turnRate), decrement life, density-weighted respawn on death/out-of-domain.
+ * The math twin of cs_flow (WGSL) — F3 round-trips the SAME sampleVelocity.
+ */
+export declare const FLOW_FIELD_STATE_GLSL = "#version 300 es\nprecision highp float;\nin vec2 vUv;\nout vec4 fragColor;\n\nuniform sampler2D uState;        // prev particle state (RGBA = pos.xy, speed, life)\nuniform float uDt;\nuniform float uDomainHalf;\nuniform float uTurnRate;\nuniform float uSpeedScale;\nuniform float uLifetimeSec;\nuniform float uEdgeBias;\nuniform vec2  uCursor;           // pointer in domain space\nuniform vec2  uPointerVel;       // pointer velocity (domain/s)\nuniform float uBurst;            // flick-burst impulse\nuniform float uPointerActive;    // 0/1\nuniform float uVortexRadius;\nuniform float uVortexSpin;\nuniform float uDragGain;\nuniform float uBurstShove;\n\n\n#define PI 3.141592653589793\n#define TAU 6.283185307179586\n#define FLOW_GRAVITY 9.81\n#define CURL_EPS 0.012\n#define MAX_WAVE_COMPONENTS 8\nconst mat2 FBM_ROT = mat2(0.8, 0.6, -0.6, 0.8);\n\nuniform float uTime;\nuniform float uWindSpeed;\nuniform float uCurlStrength;\nuniform int   uWaveCount;\nuniform vec4  uWaves[MAX_WAVE_COMPONENTS];   // (amplitude, wavelength, directionDeg, phase)\n\nvec2 gerstnerVelocity(vec2 p, float t) {\n  float dhdx = 0.0; float dhdy = 0.0;\n  for (int i = 0; i < MAX_WAVE_COMPONENTS; i++) {\n    if (i >= uWaveCount) break;\n    vec4 w = uWaves[i];\n    float k = TAU / max(w.y, 1e-4);\n    float dirRad = w.z * PI / 180.0;\n    vec2 d = vec2(cos(dirRad), sin(dirRad));\n    float omega = sqrt(FLOW_GRAVITY * k) * uWindSpeed;\n    float theta = k * (d.x * p.x + d.y * p.y) - omega * t + w.w;\n    float akc = w.x * k * cos(theta);\n    dhdx += akc * d.x; dhdy += akc * d.y;\n  }\n  return vec2(dhdy, -dhdx);\n}\nfloat hash21f(vec2 p) {\n  vec3 p3 = fract(vec3(p.x, p.y, p.x) * 0.1031);\n  p3 += dot(p3, p3.yzx + 33.33);\n  return fract((p3.x + p3.y) * p3.z);\n}\nfloat valueNoiseF(vec2 p) {\n  vec2 i = floor(p); vec2 f = fract(p);\n  vec2 u2 = f * f * f * (f * (f * 6.0 - 15.0) + 10.0);\n  float a = hash21f(i + vec2(0.0, 0.0));\n  float b = hash21f(i + vec2(1.0, 0.0));\n  float c = hash21f(i + vec2(0.0, 1.0));\n  float d = hash21f(i + vec2(1.0, 1.0));\n  return mix(mix(a, b, u2.x), mix(c, d, u2.x), u2.y);\n}\nfloat potentialFBMf(vec2 p0) {\n  float v = 0.0; float amp = 0.5; float freq = 1.0; vec2 p = p0;\n  for (int i = 0; i < 3; i++) { v += amp * valueNoiseF(p * freq); p = FBM_ROT * p; freq *= 2.0; amp *= 0.5; }\n  return v;\n}\nvec2 curlFBMf(vec2 p) {\n  float dx = potentialFBMf(p + vec2(CURL_EPS, 0.0)) - potentialFBMf(p - vec2(CURL_EPS, 0.0));\n  float dy = potentialFBMf(p + vec2(0.0, CURL_EPS)) - potentialFBMf(p - vec2(0.0, CURL_EPS));\n  vec2 g = vec2(dx, dy) / (2.0 * CURL_EPS);\n  return vec2(g.y, -g.x);\n}\nvec2 sampleVelocityF(vec2 p, float t) {\n  vec2 v = gerstnerVelocity(p, t);\n  if (uCurlStrength > 0.0) { v += curlFBMf(vec2(p.x * 0.55 + t * 0.15, p.y * 0.55)) * uCurlStrength; }\n  return v;\n}\n\n\nvec2 pointerVortex(vec2 p) {\n  if (uPointerActive < 0.5) return vec2(0.0);\n  vec2 r = p - uCursor;\n  float d = length(r);\n  float radius = max(uVortexRadius, 1e-3);\n  float fall = exp(-(d * d) / (radius * radius));\n  vec2 swirl = normalize(vec2(-r.y, r.x) + vec2(1e-6, 0.0));\n  vec2 radial = r / max(d, 1e-4);\n  vec2 v = swirl * uVortexSpin + uPointerVel * uDragGain + radial * uBurst * uBurstShove;\n  return v * fall;\n}\n\nvec2 respawn(vec2 seed, float t) {\n  float rx = hash21f(seed + vec2(t * 0.37, 1.7)) * 2.0 - 1.0;\n  float ry = hash21f(seed.yx + vec2(3.1, t * 0.37)) * 2.0 - 1.0;\n  float bias = clamp(uEdgeBias, 0.0, 1.0);\n  float bx = sign(rx) * pow(abs(rx), mix(1.0, 0.5, bias));\n  float by = sign(ry) * pow(abs(ry), mix(1.0, 0.5, bias));\n  return vec2(bx, by) * uDomainHalf;\n}\n\nvoid main() {\n  vec4 st = texture(uState, vUv);\n  vec2 pos = st.xy;\n  float life = st.w;\n  float half = uDomainHalf;\n\n  bool dead = life <= 0.0;\n  bool outOfDomain = max(abs(pos.x), abs(pos.y)) > half * 1.05;\n  if (dead || outOfDomain) {\n    pos = respawn(vUv, uTime);\n    life = max(uLifetimeSec, 1e-3) * hash21f(vUv * 7.0 + uTime * 0.11);\n  }\n\n  vec2 vField = sampleVelocityF(pos, uTime) + pointerVortex(pos);\n  // momentum: low turnRate = weighty arcs (eases into the current's turns).\n  vec2 v = vField * uTurnRate * uSpeedScale;\n  // forward-Euler advection (pos = pos + v*dt \u2014 the integrand twin of cs_flow).\n  pos = pos + v * uDt * 60.0;\n  life = life - uDt;\n\n  fragColor = vec4(pos, length(v), life);\n}";
+/**
+ * The MOTE point-sprite pass — reads the advected state texture by gl_VertexID, places a
+ * point sprite at the mote, sizes/brightens/hues it by SPEED·life (the velocity-map). Drawn
+ * additively into the trail FBO. The warm-fire palette is spliced via the shared color seam.
+ */
+export declare const FLOW_FIELD_POINT_VERT_GLSL = "#version 300 es\nprecision highp float;\nuniform sampler2D uState;\nuniform int   uStateCols;\nuniform float uDomainHalf;\nuniform float uPointSize;\nuniform float uSpeedNorm;     // the speed\u2192[0,1] normalizer (modal-speed at ramp middle)\nuniform float uStretchAmp;\nout float vSpeedNorm;\nout float vFade;\nvoid main() {\n  int id = gl_VertexID;\n  int col = id % uStateCols;\n  int row = id / uStateCols;\n  vec2 uv = (vec2(float(col), float(row)) + 0.5) / float(uStateCols);\n  vec4 st = texture(uState, uv);\n  vec2 pos = st.xy;\n  float speed = st.z;\n  float life = st.w;\n  float sn = clamp(speed / max(uSpeedNorm, 1e-4), 0.0, 1.0);\n  vSpeedNorm = sn;\n  vFade = clamp(life * 3.0, 0.0, 1.0);\n  // NDC: domain [-half,half] \u2192 [-1,1].\n  gl_Position = vec4(pos / uDomainHalf, 0.0, 1.0);\n  // faster motes read as larger hot speed-cores (the cartoon \"more\" as point size).\n  gl_PointSize = max(uPointSize * (1.0 + sn * (uStretchAmp + 1.0)), 1.0);\n}";
+export declare const FLOW_FIELD_POINT_FRAG_GLSL = "#version 300 es\nprecision highp float;\n#define MAX_FLOW_STOPS 4\nin float vSpeedNorm;\nin float vFade;\nout vec4 fragColor;\nuniform int  uStopCount;\nuniform vec3 uPalette[MAX_FLOW_STOPS];\nuniform float uSpeedGlow;\n\n\nfloat srgbToLinearCh(float c) {\n    return c <= 0.04045 ? c / 12.92 : pow((c + 0.055) / 1.055, 2.4);\n}\nvec3 srgbToLinear(vec3 c) {\n    return vec3(srgbToLinearCh(c.r), srgbToLinearCh(c.g), srgbToLinearCh(c.b));\n}\n\nfloat linearToSrgbCh(float c) {\n    return c <= 0.0031308 ? c * 12.92 : 1.055 * pow(c, 1.0 / 2.4) - 0.055;\n}\nvec3 linearToSrgb(vec3 c) {\n    return vec3(linearToSrgbCh(c.r), linearToSrgbCh(c.g), linearToSrgbCh(c.b));\n}\n\n// value.js LINEAR_SRGB_TO_LMS (constants.ts), row-major; written here as GLSL\n// columns (= the transpose) so mat3 * vec3 evaluates the row-major M\u00B7v.\nconst mat3 LINEAR_SRGB_TO_LMS = mat3(\n    0.4122214708, 0.2119034982, 0.0883024619,\n    0.5363325363, 0.6806995451, 0.2817188376,\n    0.0514459929, 0.1073969566, 0.6299787005\n);\n\n// value.js srgbToOKLab's INLINE LMS\u2192OKLab coefficients (gamut.ts lines 295-297 \u2014\n// these differ at the ~1e-9 digit from LMS_TO_OKLAB_MATRIX; use the inline ones to\n// mirror the exact value.js path), row-major \u2192 GLSL columns.\nconst mat3 LMS_TO_OKLAB = mat3(\n    0.2104542553, 1.9779984951, 0.0259040371,\n    0.7936177850, -2.4285922050, 0.7827717662,\n    -0.0040720468, 0.4505937099, -0.8086757660\n);\n\n// value.js OKLAB_TO_LMS_COEFF (constants.ts), row-major \u2192 GLSL columns. Rows:\n// l = [1, 0.3963377774, 0.2158037573], m = [1, -0.1055613458, -0.0638541728],\n// s = [1, -0.0894841775, -1.2914855480].\nconst mat3 OKLAB_TO_LMS = mat3(\n    1.0, 1.0, 1.0,\n    0.3963377774, -0.1055613458, -0.0894841775,\n    0.2158037573, -0.0638541728, -1.2914855480\n);\n\n// value.js LMS_TO_LINEAR_SRGB (constants.ts), row-major \u2192 GLSL columns.\nconst mat3 LMS_TO_LINEAR_SRGB = mat3(\n    4.0767416621, -1.2684380046, -0.0041960863,\n    -3.3077115913, 2.6097574011, -0.7034186147,\n    0.2309699292, -0.3413193965, 1.7076147010\n);\n\n// Gamma sRGB \u2192 raw OKLab (L, a, b). Mirrors value.js srgbToOKLab.\nvec3 srgbToOklab(vec3 c) {\n    vec3 lin = srgbToLinear(c);\n    vec3 lms = LINEAR_SRGB_TO_LMS * lin;\n    vec3 lmsCbrt = sign(lms) * pow(abs(lms), vec3(1.0 / 3.0));\n    return LMS_TO_OKLAB * lmsCbrt;\n}\n\n// Raw OKLab (L, a, b) \u2192 linear sRGB. Mirrors value.js oklabToLinearSRGB.\nvec3 oklabToLinearSrgb(vec3 lab) {\n    vec3 lms_ = OKLAB_TO_LMS * lab;\n    vec3 lms = lms_ * lms_ * lms_;\n    return LMS_TO_LINEAR_SRGB * lms;\n}\n\n// OKLab \u2192 OKLCh: H in RADIANS. Mirrors value.js rawOklabToOklch (which returns\n// degrees; we stay in radians and only fold to [0, 2pi)).\nvec3 oklabToOklch(vec3 lab) {\n    float C = length(lab.yz);\n    float H = atan(lab.z, lab.y);\n    if (H < 0.0) H += 2.0 * PI;\n    return vec3(lab.x, C, H);\n}\n\n// OKLCh (H radians) \u2192 OKLab. Mirrors value.js rawOklchToOklab.\nvec3 oklchToOklab(vec3 lch) {\n    return vec3(lch.x, lch.y * cos(lch.z), lch.y * sin(lch.z));\n}\n\nvec3 samplePaletteLin(float t) {\n  if (uStopCount <= 1) return uPalette[0];\n  float n = float(uStopCount);\n  float ft = clamp(t, 0.0, 1.0) * (n - 1.0);\n  int i0 = int(floor(ft));\n  int i1 = min(i0 + 1, uStopCount - 1);\n  float f = ft - float(i0);\n  vec3 lmsA = LINEAR_SRGB_TO_LMS * uPalette[i0];\n  vec3 lmsB = LINEAR_SRGB_TO_LMS * uPalette[i1];\n  vec3 labA = LMS_TO_OKLAB * (sign(lmsA) * pow(abs(lmsA), vec3(1.0 / 3.0)));\n  vec3 labB = LMS_TO_OKLAB * (sign(lmsB) * pow(abs(lmsB), vec3(1.0 / 3.0)));\n  return oklabToLinearSrgb(mix(labA, labB, f));\n}\n\nvoid main() {\n  // soft round sprite \u2014 a tight hot core (mask\u00B2 caps the white wash, H2).\n  vec2 pc = gl_PointCoord * 2.0 - 1.0;\n  float r = length(pc);\n  float mask = 1.0 - smoothstep(0.55, 1.0, r);\n  if (mask < 0.002) discard;\n  float core = mask * mask;\n  float bright = (0.35 + vSpeedNorm * uSpeedGlow) * vFade;\n  vec3 lin = samplePaletteLin(vSpeedNorm) * bright;\n  vec3 rgb = clamp(linearToSrgb(lin), vec3(0.0), vec3(1.0));\n  float a = core * clamp(bright, 0.0, 1.0);\n  fragColor = vec4(rgb * a, a);   // additive premultiplied (the trail braids the ribbons)\n}";
+/**
+ * The TRAIL decay-blit — draws the PREVIOUS trail frame back at the derived decay α (toward
+ * the warm floor), so the motes drawn additively after it leave fading ribbons of light.
+ * The headline gestalt lever. Pinned NEAREST (no half-float-linear extension dependency).
+ */
+export declare const FLOW_FIELD_TRAIL_FRAG_GLSL = "#version 300 es\nprecision highp float;\nin vec2 vUv;\nout vec4 fragColor;\nuniform sampler2D uPrev;\nuniform float uDecay;       // per-frame trail persistence (DERIVED from trailHalfLife)\nvoid main() {\n  vec4 prev = texture(uPrev, vUv);\n  fragColor = prev * uDecay;  // fade toward black; the warm floor is the present-blit's\n}";
+/**
+ * The PRESENT blit — composites the trail buffer over the warm-near-black floor + the
+ * colorful corner-bloom (the §3 colorful-field-behind-glass ground), tone-mapped so the hot
+ * cores read without a white wash. The full-bleed ground is HERE, not a parallel plane.
+ */
+export declare const FLOW_FIELD_PRESENT_FRAG_GLSL = "#version 300 es\nprecision highp float;\nin vec2 vUv;\nout vec4 fragColor;\nuniform sampler2D uTrail;\nuniform vec3 uFloor;        // the deep warm-near-black floor (linear-sRGB)\nuniform vec3 uBloomColor;   // the warm rose/magenta corner-bloom (linear-sRGB)\nuniform float uHasGround;   // 0 \u2192 transparent (compose over the page field); 1 \u2192 opaque floor\n\n\nfloat srgbToLinearCh(float c) {\n    return c <= 0.04045 ? c / 12.92 : pow((c + 0.055) / 1.055, 2.4);\n}\nvec3 srgbToLinear(vec3 c) {\n    return vec3(srgbToLinearCh(c.r), srgbToLinearCh(c.g), srgbToLinearCh(c.b));\n}\n\nfloat linearToSrgbCh(float c) {\n    return c <= 0.0031308 ? c * 12.92 : 1.055 * pow(c, 1.0 / 2.4) - 0.055;\n}\nvec3 linearToSrgb(vec3 c) {\n    return vec3(linearToSrgbCh(c.r), linearToSrgbCh(c.g), linearToSrgbCh(c.b));\n}\n\nvoid main() {\n  vec3 trail = texture(uTrail, vUv).rgb;\n  // soft tone-map the accumulated additive trail (Reinhard \u2014 hot cores, not white wash).\n  vec3 mapped = trail / (trail + vec3(0.85));\n  if (uHasGround < 0.5) {\n    // compose OVER the page's warm field: emit the lit ribbons premultiplied, no floor.\n    vec3 rgb = clamp(linearToSrgb(mapped), vec3(0.0), vec3(1.0));\n    float a = clamp(max(mapped.r, max(mapped.g, mapped.b)), 0.0, 1.0);\n    fragColor = vec4(rgb * a, a);\n    return;\n  }\n  // the corner-bloom: a faint warm rose radial in one corner (NOT teal).\n  float bloom = smoothstep(1.3, 0.0, distance(vUv, vec2(0.12, 0.88)));\n  vec3 floorLin = uFloor + uBloomColor * bloom * 0.5;\n  vec3 lin = floorLin + mapped;             // the ribbons sit OVER the warm floor\n  vec3 rgb = clamp(linearToSrgb(lin), vec3(0.0), vec3(1.0));\n  fragColor = vec4(rgb, 1.0);\n}";

package/dist/components/custom/dot-flow-field/shaders/flow-field.render.wgsl.d.ts

@@ -1 +1,2 @@
-export declare const FLOW_FIELD_RENDER_WGSL = "\nconst PI: f32 = 3.141592653589793;\nconst TAU: f32 = 6.283185307179586;\nconst MAX_FLOW_STOPS: i32 = 4;\n\nstruct Particle {\n  // (pos.x, pos.y, height, |disp|)\n  data: vec4<f32>,\n};\n\n// \u2500\u2500 Render uniforms (the typed-struct source-of-truth \u2014 see uniformBridgeWGPU.ts) \u2500\u2500\nstruct RenderUniforms {\n  // r0: (uTime, uContrast, uBaseBright, uDomainHalf)\n  r0: vec4<f32>,\n  // r1: (uDotSize, uSizePulse, uAspect, uGridPitch)\n  r1: vec4<f32>,\n  // r2: (uWaveBandCenter, uWaveBandWidth, uGlobeMask, _pad)\n  r2: vec4<f32>,\n  // ints: (uStopCount, uParticleCount, _pad, _pad)\n  ints: vec4<i32>,\n  // bg: (background.rgb, hasBackground)\n  bg: vec4<f32>,\n  // each palette stop: linear-sRGB rgb + _pad\n  palette: array<vec4<f32>, 4>,\n};\n\n@group(0) @binding(0) var<uniform> u: RenderUniforms;\n@group(0) @binding(1) var<storage, read> particles: array<Particle>;\n\n\nfn srgbToLinearCh(c: f32) -> f32 {\n  if (c <= 0.04045) { return c / 12.92; }\n  return pow((c + 0.055) / 1.055, 2.4);\n}\nfn srgbToLinear(c: vec3<f32>) -> vec3<f32> {\n  return vec3<f32>(srgbToLinearCh(c.r), srgbToLinearCh(c.g), srgbToLinearCh(c.b));\n}\n\nfn linearToSrgbCh(c: f32) -> f32 {\n  if (c <= 0.0031308) { return c * 12.92; }\n  return 1.055 * pow(c, 1.0 / 2.4) - 0.055;\n}\nfn linearToSrgb(c: vec3<f32>) -> vec3<f32> {\n  return vec3<f32>(linearToSrgbCh(c.r), linearToSrgbCh(c.g), linearToSrgbCh(c.b));\n}\n\n// value.js LINEAR_SRGB_TO_LMS, row-major \u2192 WGSL columns (= the transpose).\nconst LINEAR_SRGB_TO_LMS: mat3x3<f32> = mat3x3<f32>(\n  0.4122214708, 0.2119034982, 0.0883024619,\n  0.5363325363, 0.6806995451, 0.2817188376,\n  0.0514459929, 0.1073969566, 0.6299787005\n);\n\n// value.js srgbToOKLab's INLINE LMS\u2192OKLab coefficients, row-major \u2192 WGSL columns.\nconst LMS_TO_OKLAB: mat3x3<f32> = mat3x3<f32>(\n  0.2104542553, 1.9779984951, 0.0259040371,\n  0.7936177850, -2.4285922050, 0.7827717662,\n  -0.0040720468, 0.4505937099, -0.8086757660\n);\n\n// value.js OKLAB_TO_LMS_COEFF, row-major \u2192 WGSL columns.\nconst OKLAB_TO_LMS: mat3x3<f32> = mat3x3<f32>(\n  1.0, 1.0, 1.0,\n  0.3963377774, -0.1055613458, -0.0894841775,\n  0.2158037573, -0.0638541728, -1.2914855480\n);\n\n// value.js LMS_TO_LINEAR_SRGB, row-major \u2192 WGSL columns.\nconst LMS_TO_LINEAR_SRGB: mat3x3<f32> = mat3x3<f32>(\n  4.0767416621, -1.2684380046, -0.0041960863,\n  -3.3077115913, 2.6097574011, -0.7034186147,\n  0.2309699292, -0.3413193965, 1.7076147010\n);\n\nfn cbrt3(v: vec3<f32>) -> vec3<f32> {\n  return sign(v) * pow(abs(v), vec3<f32>(1.0 / 3.0));\n}\n\n// Gamma sRGB \u2192 raw OKLab (L, a, b). Mirrors value.js srgbToOKLab.\nfn srgbToOklab(c: vec3<f32>) -> vec3<f32> {\n  let lin = srgbToLinear(c);\n  let lms = LINEAR_SRGB_TO_LMS * lin;\n  return LMS_TO_OKLAB * cbrt3(lms);\n}\n\n// Raw OKLab (L, a, b) \u2192 linear sRGB. Mirrors value.js oklabToLinearSRGB.\nfn oklabToLinearSrgb(lab: vec3<f32>) -> vec3<f32> {\n  let lms_ = OKLAB_TO_LMS * lab;\n  let lms = lms_ * lms_ * lms_;\n  return LMS_TO_LINEAR_SRGB * lms;\n}\n\n// OKLab \u2192 OKLCh: H in RADIANS, folded to [0, 2pi). Mirrors value.js rawOklabToOklch.\nfn oklabToOklch(lab: vec3<f32>) -> vec3<f32> {\n  let C = length(lab.yz);\n  var H = atan2(lab.z, lab.y);\n  if (H < 0.0) { H = H + 2.0 * PI; }\n  return vec3<f32>(lab.x, C, H);\n}\n\n// OKLCh (H radians) \u2192 OKLab. Mirrors value.js rawOklchToOklab.\nfn oklchToOklab(lch: vec3<f32>) -> vec3<f32> {\n  return vec3<f32>(lch.x, lch.y * cos(lch.z), lch.y * sin(lch.z));\n}\n\n// The sweeping bright-stripe band (transcribes flowField.ts waveBand): a soft two-sided\n// ridge over the normalized height \u2014 1 at the band center, falling to 0 at \u00B1width.\nfn waveBand(h: f32, center: f32, width: f32) -> f32 {\n  let w = max(width, 1e-3);\n  let d = abs(h - center);\n  return 1.0 - smoothstep(0.0, w, d);\n}\n\n// The optional soft-disc globe mask \u2014 a slow Lissajous-drifting radial field (the\n// reference's two-sphere composition). OFF when uGlobeMask <= 0.5 (returns 1).\nfn globeMask(o: vec2<f32>, t: f32, on: f32) -> f32 {\n  if (on <= 0.5) { return 1.0; }\n  // a slow Lissajous center drift within the domain\n  let cx = 0.35 * sin(t * 0.13);\n  let cy = 0.28 * cos(t * 0.11);\n  let d = length(o - vec2<f32>(cx, cy));\n  // a soft disc of radius ~0.6 with a feathered edge\n  return 1.0 - smoothstep(0.45, 0.75, d);\n}\n\n// Sample the multi-stop palette (linear-sRGB stops, OKLab mix). t in [0,1].\nfn samplePaletteLin(t: f32) -> vec3<f32> {\n  let stopCount = u.ints.x;\n  if (stopCount <= 1) { return u.palette[0].rgb; }\n  let n = f32(stopCount);\n  let ft = clamp(t, 0.0, 1.0) * (n - 1.0);\n  let i0 = i32(floor(ft));\n  let i1 = min(i0 + 1, stopCount - 1);\n  let f = ft - f32(i0);\n  let labA = LMS_TO_OKLAB * cbrt3(LINEAR_SRGB_TO_LMS * u.palette[i0].rgb);\n  let labB = LMS_TO_OKLAB * cbrt3(LINEAR_SRGB_TO_LMS * u.palette[i1].rgb);\n  return oklabToLinearSrgb(mix(labA, labB, f));\n}\n\nstruct VSOut {\n  @builtin(position) pos: vec4<f32>,\n  @location(0) local: vec2<f32>,   // [-1,1] billboard-local coords for the soft circle\n  @location(1) bright: f32,        // band-driven brightness [0, ~1.6]\n};\n\n@vertex\nfn vs_main(\n  @builtin(vertex_index) vi: u32,\n  @builtin(instance_index) ii: u32,\n) -> VSOut {\n  // Two-triangle quad corners in billboard-local space.\n  var corners = array<vec2<f32>, 6>(\n    vec2<f32>(-1.0, -1.0), vec2<f32>(1.0, -1.0), vec2<f32>(-1.0, 1.0),\n    vec2<f32>(-1.0, 1.0), vec2<f32>(1.0, -1.0), vec2<f32>(1.0, 1.0),\n  );\n  let local = corners[vi];\n\n  let pr = particles[ii].data;\n  let p = pr.xy;\n  let h = pr.z;\n  let dispMag = pr.w;\n  let half = u.r0.w;\n\n  // Brightness = base + band\u00B7contrast, masked by the optional globe (read at the live\n  // position \u2014 close enough to the anchor at the sub-cell cap). The band SWEEPS as h\n  // translates across the lattice.\n  let band = waveBand(h, u.r2.x, u.r2.y);\n  var bright = u.r0.z + band * u.r0.y;\n  bright = bright * globeMask(p, u.r0.x, u.r2.z);\n\n  // A subtle drift-driven size pulse (never a re-seed \u2014 the dot only breathes).\n  let sizePulse = u.r1.y;\n  let sizeWorld = u.r1.x * (1.0 + dispMag * sizePulse);\n\n  // Position the quad at the dot in clip space. Domain [-half,half] \u2192 NDC [-1,1];\n  // the quad half-extent rides sizeWorld (in domain units, aspect-corrected x).\n  let aspect = u.r1.z;\n  let ndc = p / half;\n  let off = local * sizeWorld / half;\n  let offX = off.x / max(aspect, 1e-4);\n\n  var out: VSOut;\n  out.pos = vec4<f32>(ndc.x + offX, ndc.y + off.y, 0.0, 1.0);\n  out.local = local;\n  out.bright = bright;\n  return out;\n}\n\n@fragment\nfn fs_main(in: VSOut) -> @location(0) vec4<f32> {\n  // Soft circle \u2014 radial smoothstep over the billboard-local radius.\n  let r = length(in.local);\n  let feather = 0.4;\n  let mask = 1.0 - smoothstep(1.0 - feather, 1.0, r);\n  if (mask < 0.002) { return vec4<f32>(0.0); }\n\n  // The brightness lights the dot core; the palette tints it (the warm-cream identity).\n  let bright = clamp(in.bright, 0.0, 1.6);\n  let tone = clamp(bright, 0.0, 1.0);\n  let lin = samplePaletteLin(tone) * bright;\n  // A floor alpha so even an off-band dot stays a faint lattice point (the calm grid).\n  let alpha = mask * clamp(bright * 0.8 + 0.12, 0.0, 1.0);\n  let rgb = clamp(linearToSrgb(lin), vec3<f32>(0.0), vec3<f32>(1.0));\n  // Premultiplied-alpha output.\n  return vec4<f32>(rgb * alpha, alpha);\n}\n";
+export declare const FLOW_FIELD_RENDER_WGSL = "\nconst PI: f32 = 3.141592653589793;\nconst TAU: f32 = 6.283185307179586;\nconst MAX_FLOW_STOPS: i32 = 4;\n\nstruct Particle {\n  // field: (pos.x, pos.y, height, |disp|)   flow: (pos.x, pos.y, speed, life)\n  data: vec4<f32>,\n};\n\n// \u2500\u2500 Render uniforms (the typed-struct source-of-truth \u2014 see uniformBridgeWGPU.ts) \u2500\u2500\nstruct RenderUniforms {\n  // r0: (uTime, uContrast, uBaseBright, uDomainHalf)\n  r0: vec4<f32>,\n  // r1: (uDotSize, uSizePulse, uAspect, uGridPitch)\n  r1: vec4<f32>,\n  // r2: (uWaveBandCenter, uWaveBandWidth, uGlobeMask, uMode)  \u2014 uMode: 0=field, 1=flow\n  r2: vec4<f32>,\n  // ints: (uStopCount, uParticleCount, _pad, _pad)\n  ints: vec4<i32>,\n  // bg: (background.rgb, hasBackground)\n  bg: vec4<f32>,\n  // f0: (uSpeedGlow, uSpeedNorm, uShadowOffset, uStretchAmp)  \u2014 the flow velocity-map levers\n  f0: vec4<f32>,\n  // each palette stop: linear-sRGB rgb + _pad\n  palette: array<vec4<f32>, 4>,\n};\n\n@group(0) @binding(0) var<uniform> u: RenderUniforms;\n@group(0) @binding(1) var<storage, read> particles: array<Particle>;\n\n\nfn srgbToLinearCh(c: f32) -> f32 {\n  if (c <= 0.04045) { return c / 12.92; }\n  return pow((c + 0.055) / 1.055, 2.4);\n}\nfn srgbToLinear(c: vec3<f32>) -> vec3<f32> {\n  return vec3<f32>(srgbToLinearCh(c.r), srgbToLinearCh(c.g), srgbToLinearCh(c.b));\n}\n\nfn linearToSrgbCh(c: f32) -> f32 {\n  if (c <= 0.0031308) { return c * 12.92; }\n  return 1.055 * pow(c, 1.0 / 2.4) - 0.055;\n}\nfn linearToSrgb(c: vec3<f32>) -> vec3<f32> {\n  return vec3<f32>(linearToSrgbCh(c.r), linearToSrgbCh(c.g), linearToSrgbCh(c.b));\n}\n\n// value.js LINEAR_SRGB_TO_LMS, row-major \u2192 WGSL columns (= the transpose).\nconst LINEAR_SRGB_TO_LMS: mat3x3<f32> = mat3x3<f32>(\n  0.4122214708, 0.2119034982, 0.0883024619,\n  0.5363325363, 0.6806995451, 0.2817188376,\n  0.0514459929, 0.1073969566, 0.6299787005\n);\n\n// value.js srgbToOKLab's INLINE LMS\u2192OKLab coefficients, row-major \u2192 WGSL columns.\nconst LMS_TO_OKLAB: mat3x3<f32> = mat3x3<f32>(\n  0.2104542553, 1.9779984951, 0.0259040371,\n  0.7936177850, -2.4285922050, 0.7827717662,\n  -0.0040720468, 0.4505937099, -0.8086757660\n);\n\n// value.js OKLAB_TO_LMS_COEFF, row-major \u2192 WGSL columns.\nconst OKLAB_TO_LMS: mat3x3<f32> = mat3x3<f32>(\n  1.0, 1.0, 1.0,\n  0.3963377774, -0.1055613458, -0.0894841775,\n  0.2158037573, -0.0638541728, -1.2914855480\n);\n\n// value.js LMS_TO_LINEAR_SRGB, row-major \u2192 WGSL columns.\nconst LMS_TO_LINEAR_SRGB: mat3x3<f32> = mat3x3<f32>(\n  4.0767416621, -1.2684380046, -0.0041960863,\n  -3.3077115913, 2.6097574011, -0.7034186147,\n  0.2309699292, -0.3413193965, 1.7076147010\n);\n\nfn cbrt3(v: vec3<f32>) -> vec3<f32> {\n  return sign(v) * pow(abs(v), vec3<f32>(1.0 / 3.0));\n}\n\n// Gamma sRGB \u2192 raw OKLab (L, a, b). Mirrors value.js srgbToOKLab.\nfn srgbToOklab(c: vec3<f32>) -> vec3<f32> {\n  let lin = srgbToLinear(c);\n  let lms = LINEAR_SRGB_TO_LMS * lin;\n  return LMS_TO_OKLAB * cbrt3(lms);\n}\n\n// Raw OKLab (L, a, b) \u2192 linear sRGB. Mirrors value.js oklabToLinearSRGB.\nfn oklabToLinearSrgb(lab: vec3<f32>) -> vec3<f32> {\n  let lms_ = OKLAB_TO_LMS * lab;\n  let lms = lms_ * lms_ * lms_;\n  return LMS_TO_LINEAR_SRGB * lms;\n}\n\n// OKLab \u2192 OKLCh: H in RADIANS, folded to [0, 2pi). Mirrors value.js rawOklabToOklch.\nfn oklabToOklch(lab: vec3<f32>) -> vec3<f32> {\n  let C = length(lab.yz);\n  var H = atan2(lab.z, lab.y);\n  if (H < 0.0) { H = H + 2.0 * PI; }\n  return vec3<f32>(lab.x, C, H);\n}\n\n// OKLCh (H radians) \u2192 OKLab. Mirrors value.js rawOklchToOklab.\nfn oklchToOklab(lch: vec3<f32>) -> vec3<f32> {\n  return vec3<f32>(lch.x, lch.y * cos(lch.z), lch.y * sin(lch.z));\n}\n\n// The sweeping bright-stripe band (transcribes flowField.ts waveBand): a soft two-sided\n// ridge over the normalized height \u2014 1 at the band center, falling to 0 at \u00B1width.\nfn waveBand(h: f32, center: f32, width: f32) -> f32 {\n  let w = max(width, 1e-3);\n  let d = abs(h - center);\n  return 1.0 - smoothstep(0.0, w, d);\n}\n\n// The optional soft-disc globe mask \u2014 a slow Lissajous-drifting radial field (the\n// reference's two-sphere composition). OFF when uGlobeMask <= 0.5 (returns 1).\nfn globeMask(o: vec2<f32>, t: f32, on: f32) -> f32 {\n  if (on <= 0.5) { return 1.0; }\n  // a slow Lissajous center drift within the domain\n  let cx = 0.35 * sin(t * 0.13);\n  let cy = 0.28 * cos(t * 0.11);\n  let d = length(o - vec2<f32>(cx, cy));\n  // a soft disc of radius ~0.6 with a feathered edge\n  return 1.0 - smoothstep(0.45, 0.75, d);\n}\n\n// Sample the multi-stop palette (linear-sRGB stops, OKLab mix). t in [0,1].\nfn samplePaletteLin(t: f32) -> vec3<f32> {\n  let stopCount = u.ints.x;\n  if (stopCount <= 1) { return u.palette[0].rgb; }\n  let n = f32(stopCount);\n  let ft = clamp(t, 0.0, 1.0) * (n - 1.0);\n  let i0 = i32(floor(ft));\n  let i1 = min(i0 + 1, stopCount - 1);\n  let f = ft - f32(i0);\n  let labA = LMS_TO_OKLAB * cbrt3(LINEAR_SRGB_TO_LMS * u.palette[i0].rgb);\n  let labB = LMS_TO_OKLAB * cbrt3(LINEAR_SRGB_TO_LMS * u.palette[i1].rgb);\n  return oklabToLinearSrgb(mix(labA, labB, f));\n}\n\nstruct VSOut {\n  @builtin(position) pos: vec4<f32>,\n  @location(0) local: vec2<f32>,   // [-1,1] billboard-local coords for the soft circle\n  @location(1) bright: f32,        // brightness [0, ~1.6]\n  @location(2) ramp: f32,          // palette-ramp coord (field: tone, flow: speedNorm)\n  @location(3) flowFade: f32,      // flow life-fade [0,1] (field: 1)\n};\n\n@vertex\nfn vs_main(\n  @builtin(vertex_index) vi: u32,\n  @builtin(instance_index) ii: u32,\n) -> VSOut {\n  // Two-triangle quad corners in billboard-local space.\n  var corners = array<vec2<f32>, 6>(\n    vec2<f32>(-1.0, -1.0), vec2<f32>(1.0, -1.0), vec2<f32>(-1.0, 1.0),\n    vec2<f32>(-1.0, 1.0), vec2<f32>(1.0, -1.0), vec2<f32>(1.0, 1.0),\n  );\n  let local = corners[vi];\n\n  let pr = particles[ii].data;\n  let p = pr.xy;\n  let half = u.r0.w;\n  let aspect = u.r1.z;\n  let mode = i32(u.r2.w + 0.5);\n\n  var bright: f32;\n  var ramp: f32;\n  var sizeWorld: f32;\n  var flowFade: f32 = 1.0;\n\n  if (mode == 1) {\n    // \u2500\u2500 flow (AURORA CURRENT): speed\u2192hue, speed\u00B7life\u2192brightness, speed\u2192size bloom \u2500\u2500\n    let speed = pr.z;\n    let life = pr.w;\n    let speedNorm = clamp(speed / max(u.f0.y, 1e-4), 0.0, 1.0);\n    // life fades the mote over its last third (the trail's tail / overlapping-action).\n    flowFade = clamp(life * 3.0, 0.0, 1.0);\n    ramp = speedNorm;\n    bright = (0.35 + speedNorm * u.f0.x) * flowFade;\n    // a speed bloom (the cartoon \"more\" on WGPU \u2014 faster motes read as hot speed-cores) +\n    // the \u221A\u03C6 stretch lever scales the bloom (the squash-stretch as an isotropic core here).\n    sizeWorld = u.r1.x * (1.0 + speedNorm * (u.f0.w + 1.0));\n  } else {\n    // \u2500\u2500 field: the sweeping bright band over the anchored lattice (BC.W-VIZ-DOTFLOW) \u2500\u2500\n    let h = pr.z;\n    let dispMag = pr.w;\n    let band = waveBand(h, u.r2.x, u.r2.y);\n    bright = (u.r0.z + band * u.r0.y) * globeMask(p, u.r0.x, u.r2.z);\n    ramp = clamp(bright, 0.0, 1.0);\n    sizeWorld = u.r1.x * (1.0 + dispMag * u.r1.y);\n  }\n\n  // Position the quad at the dot in clip space. Domain [-half,half] \u2192 NDC [-1,1];\n  // the quad half-extent rides sizeWorld (in domain units, aspect-corrected x).\n  let ndc = p / half;\n  let off = local * sizeWorld / half;\n  let offX = off.x / max(aspect, 1e-4);\n\n  var out: VSOut;\n  out.pos = vec4<f32>(ndc.x + offX, ndc.y + off.y, 0.0, 1.0);\n  out.local = local;\n  out.bright = bright;\n  out.ramp = ramp;\n  out.flowFade = flowFade;\n  return out;\n}\n\n@fragment\nfn fs_main(in: VSOut) -> @location(0) vec4<f32> {\n  // Soft circle \u2014 radial smoothstep over the billboard-local radius.\n  let r = length(in.local);\n  let feather = 0.4;\n  let mask = 1.0 - smoothstep(1.0 - feather, 1.0, r);\n  if (mask < 0.002) { return vec4<f32>(0.0); }\n\n  let mode = i32(u.r2.w + 0.5);\n  let bright = clamp(in.bright, 0.0, 1.6);\n  let lin = samplePaletteLin(in.ramp) * bright;\n  let rgb = clamp(linearToSrgb(lin), vec3<f32>(0.0), vec3<f32>(1.0));\n\n  if (mode == 1) {\n    // flow: additive premultiplied \u2014 a soft glowing core, alpha rides speed\u00B7life.\n    let coreAlpha = mask * mask; // a tighter hot core (less white wash \u2014 H2 cap)\n    let a = coreAlpha * clamp(bright, 0.0, 1.0);\n    return vec4<f32>(rgb * a, a);\n  }\n  // field: a floor alpha so even an off-band dot stays a faint lattice point.\n  let alpha = mask * clamp(bright * 0.8 + 0.12, 0.0, 1.0);\n  return vec4<f32>(rgb * alpha, alpha);\n}\n";
+export declare const FLOW_FIELD_TRAIL_WGSL = "\nstruct TrailUniforms {\n  // (decay, hasGround, time, _pad)\n  p: vec4<f32>,\n  // floor.rgb (linear-sRGB) + _pad\n  floorC: vec4<f32>,\n  // bloom.rgb (linear-sRGB) + _pad\n  bloomC: vec4<f32>,\n};\n@group(0) @binding(0) var<uniform> u: TrailUniforms;\n@group(0) @binding(1) var samp: sampler;\n@group(0) @binding(2) var tex: texture_2d<f32>;\n\n\nfn srgbToLinearCh(c: f32) -> f32 {\n  if (c <= 0.04045) { return c / 12.92; }\n  return pow((c + 0.055) / 1.055, 2.4);\n}\nfn srgbToLinear(c: vec3<f32>) -> vec3<f32> {\n  return vec3<f32>(srgbToLinearCh(c.r), srgbToLinearCh(c.g), srgbToLinearCh(c.b));\n}\n\nfn linearToSrgbCh(c: f32) -> f32 {\n  if (c <= 0.0031308) { return c * 12.92; }\n  return 1.055 * pow(c, 1.0 / 2.4) - 0.055;\n}\nfn linearToSrgb(c: vec3<f32>) -> vec3<f32> {\n  return vec3<f32>(linearToSrgbCh(c.r), linearToSrgbCh(c.g), linearToSrgbCh(c.b));\n}\n\nstruct FSQ { @builtin(position) pos: vec4<f32>, @location(0) uv: vec2<f32> };\n\n@vertex\nfn vs_fsq(@builtin(vertex_index) vi: u32) -> FSQ {\n  var c = array<vec2<f32>, 3>(\n    vec2<f32>(-1.0, -1.0), vec2<f32>(3.0, -1.0), vec2<f32>(-1.0, 3.0),\n  );\n  let p = c[vi];\n  var out: FSQ;\n  out.pos = vec4<f32>(p, 0.0, 1.0);\n  out.uv = p * 0.5 + 0.5;\n  return out;\n}\n\n@fragment\nfn fs_decay(in: FSQ) -> @location(0) vec4<f32> {\n  let prev = textureSample(tex, samp, in.uv);\n  return prev * u.p.x;   // fade toward black\n}\n\n@fragment\nfn fs_present(in: FSQ) -> @location(0) vec4<f32> {\n  let trail = textureSample(tex, samp, in.uv).rgb;\n  let mapped = trail / (trail + vec3<f32>(0.85)); // Reinhard \u2014 hot cores, not white wash\n  if (u.p.y < 0.5) {\n    let rgb = clamp(linearToSrgb(mapped), vec3<f32>(0.0), vec3<f32>(1.0));\n    let a = clamp(max(mapped.r, max(mapped.g, mapped.b)), 0.0, 1.0);\n    return vec4<f32>(rgb * a, a);\n  }\n  let bloom = smoothstep(1.3, 0.0, distance(in.uv, vec2<f32>(0.12, 0.88)));\n  let floorLin = u.floorC.rgb + u.bloomC.rgb * bloom * 0.5;\n  let lin = floorLin + mapped;\n  let rgb = clamp(linearToSrgb(lin), vec3<f32>(0.0), vec3<f32>(1.0));\n  return vec4<f32>(rgb, 1.0);\n}\n";

package/dist/components/custom/dot-matrix/composables/uniformBridgeWGPU.d.ts

@@ -20,6 +20,15 @@ export interface DotPointerState {
     push: number;
     /** The accel-burst brightness/scale bloom 0..1 (the flick term). */
     bloom: number;
+    /**
+     * The travel VELOCITY (normalized-host units/sec, the shared field's already-computed
+     * `pointer.velocity` — the dead-lever reclaim). Drives the anisotropic squash/stretch +
+     * the comet-tail wake direction. Mapped to NDC/frame deltas in the shader.
+     */
+    velX: number;
+    velY: number;
+    /** The flick-take ACCEL magnitude (`hypot(pointer.acceleration)`, also unused today). */
+    accelMag: number;
 }
 /** A fresh resting pointer state. */
 export declare function restingPointer(): DotPointerState;
@@ -39,7 +48,7 @@ export declare function createDotRenderScratch(): DotUniformScratch;
  * phyllotaxis on the GPU — the JS+GPU agree by construction).
  */
 export declare function buildDotsBuffer(config: DotMatrixConfig): Float32Array;
-/** The total dot instance count for a config (per-sphere × spheres). */
+/** The total dot instance count for a config (per-sphere × spheres; plane is single). */
 export declare function dotInstanceCount(config: DotMatrixConfig): number;
 /**
  * Pack the per-frame render uniforms in place. `timeSec` drives the spin matrix + the

package/dist/components/custom/dot-matrix/composables/useDotSphere.d.ts

@@ -14,6 +14,13 @@ export interface DotSetupDeps {
     shouldContinue: () => boolean;
     /** The per-frame pointer hook — advances the shared field (the no-own-rAF discipline). */
     onFrame?: (timeSec: number) => void;
+    /**
+     * The live `prefers-reduced-motion` state (read lazily — the handle resolves AFTER the
+     * setup closure is built). When true the frame PINS uTime to a fixed √φ rung so the spin
+     * AND the per-dot twinkle `sin` are bit-identical across runs (the deterministic static
+     * frame — G9). Capture mode is already deterministic via `renderAt(fixedT)`.
+     */
+    getReducedMotion?: () => boolean;
 }
 /** Build the dot-matrix `setupWGPU(device, context, format)` callback. */
 export declare function createDotWGPUSetup(deps: DotSetupDeps): (device: GPUDevice, context: GPUCanvasContext, format: GPUTextureFormat) => WebGPUCanvasFrame;

package/dist/components/custom/dot-matrix/constants.d.ts

@@ -5,6 +5,8 @@ export declare const MAX_DOTS = 4000;
 export declare const MAX_DOT_STOPS = 4;
 /** Pointer interaction mode — a repel pushes dots off the surface, attract pulls them in. */
 export type DotPointerMode = "repel" | "attract";
+/** The dot layout register — a 3D phyllotaxis SPHERE (kept) or a flat 2D background PLANE. */
+export type DotLayout = "sphere" | "plane";
 /**
  * The full author schema — the studio's `useConfiguratorState` model. Every field is a
  * tunable the demo configurator drives; the composable resolves it into the uniform table.
@@ -33,12 +35,24 @@ export interface DotMatrixConfig {
     palette: OklchStop[];
     /** The ground color (the demo sets near-black; default transparent). */
     background: OklchStop | "transparent";
+    /** The layout register — 3D sphere (kept preset) or a flat 2D background plane (the default). */
+    layout: DotLayout;
     /** Pointer parallax + repel + accel-burst (the §T7 interaction). */
     interactive: boolean;
     /** repel ↔ attract (the dimple direction). */
     pointerMode: DotPointerMode;
     /** The pointer-parallax depth (0–0.3; the screen-center tracks the cursor). */
     parallax: number;
+    /** The cursor-gravity well depth — how far a near dot is pulled toward the cursor (NDC). */
+    gravityStrength: number;
+    /** The cursor-gravity well radius — the falloff width (NDC; WIDE → many dots feel it). */
+    gravityRadius: number;
+    /**
+     * The resting per-dot TWINKLE rate (the living-constellation floor): each dot's opacity
+     * breathes on an `instance_index`-hashed phase at this rate (0 = a dead-still field; the
+     * demo lifts it). Frozen under PRM (the `sin` reads the pinned capture time).
+     */
+    twinkle: number;
     /** ONE static frame then park under `prefers-reduced-motion: reduce`. */
     respectReducedMotion: boolean;
 }