@mkbabb/glass-ui 4.2.0 → 5.0.0

package/dist/components/fourier-field/composables/uniformBridgeWGPU.d.ts

@@ -0,0 +1,41 @@
+import type { OklchStop } from "../../../composables/color";
+import { type BasisComponent } from "../math";
+/** One phasor lane in the storage buffer: (re, im, index, _pad). */
+export declare const FOURIER_PHASOR_BYTES = 16;
+export declare const FOURIER_COMPUTE_UNIFORM_BYTES = 32;
+export interface FourierUniformScratch {
+    buffer: ArrayBuffer;
+    f32: Float32Array;
+    i32: Int32Array;
+}
+export declare function createFourierComputeScratch(): FourierUniformScratch;
+/** Pack the compute uniforms in place. */
+export declare function packFourierComputeUniforms(scratch: FourierUniformScratch, headT: number, trailArc: number, harmonicN: number, epicycleArmN: number, sampleCount: number, phasorCount: number): FourierUniformScratch;
+export declare const FOURIER_RENDER_UNIFORM_BYTES: number;
+export declare function createFourierRenderScratch(): FourierUniformScratch;
+/** The model→clip fit transform (center + uniform scale) — computed once per spectrum. */
+export interface FourierFit {
+    centerX: number;
+    centerY: number;
+    /** The uniform scale s such that (model − center)·s maps the curve into clip [-1,1] with margin. */
+    scale: number;
+}
+/**
+ * Stable view-fit: sample the FULL reconstruction once over the period, bound its bbox,
+ * and derive the center + a margin-padded uniform scale. The render's fullscreen pass
+ * inverts this transform per fragment so the curve never clips and the scale is fixed.
+ */
+export declare function computeFourierFit(spectrum: readonly BasisComponent[]): FourierFit;
+/**
+ * Convert a CSS-px stroke width to MODEL units (the shader's space). The fit `scale` maps
+ * model → clip; clip spans [-1,1] over the min CSS dimension → cssPx-per-clip = canvasCssMin/2.
+ * model-per-cssPx = (1/scale)·(2/canvasCssMin).
+ */
+export declare function trailWidthToModel(trailWidthPx: number, scale: number, canvasCssMin: number): number;
+/** Pack the render uniforms in place. */
+export declare function packFourierRenderUniforms(scratch: FourierUniformScratch, fit: FourierFit, aspect: number, trailWidthModel: number, peakAlpha: number, headGlowAlpha: number, trailFadeExp: number, trailFloor: number, intensity: number, showEpicycles: boolean, rainbowChain: boolean, squashGain: number, celGain: number, edgeMargin: number, sampleCount: number, armCount: number, palette: OklchStop[]): FourierUniformScratch;
+/**
+ * Pack the phasor storage table (re, im, index, _pad) from the CPU-minted spectrum. The
+ * WGSL SUMS this per frame — it is the ONLY spectrum upload (no WGSL-side mint).
+ */
+export declare function packPhasorTable(spectrum: readonly BasisComponent[]): Float32Array;

package/dist/components/fourier-field/composables/useFourierField.d.ts

@@ -0,0 +1,55 @@
+import { type Ref } from "vue";
+import { type GpuBackend } from "../../../composables/glass/webgpu/useGpuSubstrate";
+import type { OklchStop } from "../../../composables/color";
+import type { FourierFieldConfig } from "../constants";
+import type { BasisComponent } from "../math";
+export interface UseFourierFieldOptions {
+    config: FourierFieldConfig;
+    /** The active phasor spectrum (CPU-minted; re-read each frame so a source-swap reaches the buffer). */
+    getSpectrum: () => readonly BasisComponent[];
+    /** Resolve the curve-color palette as OKLCh (the demo themes it; default warm-identity). */
+    getPalette: () => OklchStop[];
+    /** When true, hold the deterministic best-frame and never advance (the capture / freeze lever). */
+    freeze?: () => boolean;
+    /** The static deterministic best-frame parameter under `freeze`/PRM. Default 0.34. */
+    frozenT?: number;
+    /** Base forward period for one full traversal at 1× speed, in seconds. Default 16. */
+    periodS?: number;
+    /** `"capture"` → renderAt-only (the deterministic π capture path). Default `"live"`. */
+    mode?: "live" | "capture";
+    /**
+     * BI.W-FIELD-CORE — the route pointer BROADCASTER read (the SUBTLE-interactive background
+     * register). A full-bleed `pointer-events:none` field cannot listen for its own pointer, so
+     * an ambient consumer reads the route-level `useRoutePointer` and feeds the shared field
+     * from here each frame (viewport-normalized ≈ host-normalized for a full-bleed field). The
+     * lean/bias then read on a background field WITHOUT the field owning a pointer listener.
+     * Omit for the studio (which binds its own host listeners).
+     */
+    routePointer?: () => {
+        x: number;
+        y: number;
+        active: boolean;
+    } | null;
+}
+/** The uniform handle a consumer wires its lifecycle against (backend-agnostic). */
+export interface FourierFieldHandle {
+    /** The resolved backend (`"webgpu"` where supported, else the WebGL2 GLSL fallback). */
+    readonly backend: GpuBackend;
+    /** Park the loop (the WCAG-2.2.2 pause seam — `DockBackgroundToggle` wires this). */
+    pause: () => void;
+    /** Re-arm the loop. */
+    resume: () => void;
+    /** Re-arm a parked loop on demand. */
+    wake: () => void;
+    /** Draw one frame out-of-loop (capture / thumbnail). */
+    renderAt: (timeSec: number) => void;
+    /** The live `prefers-reduced-motion: reduce` state. */
+    readonly reducedMotion: boolean;
+    /** The current loop parameter `head_t ∈ [0,1)` (the scrubber reads/writes it). */
+    readonly headT: number;
+    /** Scrub the clock directly (the transport scrubber / a pointer drag). */
+    setHeadT: (t: number) => void;
+    /** Tear down the renderer + release GPU/GL resources. */
+    dispose: () => void;
+}
+export declare function useFourierField(canvasRef: Ref<HTMLCanvasElement | null>, options: UseFourierFieldOptions): FourierFieldHandle;

package/dist/components/fourier-field/constants.d.ts

@@ -0,0 +1,134 @@
+import type { OklchStop } from "../../composables/color";
+/**
+ * Curve-sampling resolution for the stable view-fit bbox pass — the renderer samples the
+ * epicycle curve this many times once at mount to size it to the canvas with a fixed
+ * margin (so the curve never clips and the scale is constant across the run). 720 = one
+ * sample per half-degree of the unit period.
+ */
+export declare const FOURIER_FIT_SAMPLES = 720;
+/**
+ * The phasor-table uniform ceiling — the WGSL `MAX_PHASORS` #define. The configurator's
+ * harmonic count maxes here; a >64-term custom trace books a storage-buffer widen (cheap —
+ * the flow-field already uses a storage buffer). The curated ℱ/heart/star set + the
+ * generated elliptic spectrum all sit under it.
+ */
+export declare const MAX_PHASORS = 64;
+/**
+ * The comet-curve sample ceiling — the storage-buffer array bound. The compute pass
+ * writes the partial-sum curve point at `M` samples back along the period from the head;
+ * the render pass reads them as the comet polyline. 384 gives a smooth bold stroke.
+ */
+export declare const MAX_CURVE_SAMPLES = 384;
+/** The palette-stop ceiling — the WGSL `MAX_FOURIER_STOPS` #define. */
+export declare const MAX_FOURIER_STOPS = 4;
+/**
+ * The cursor-velocity → head_t clock-coupling gain (BD.W-VIZ-BROKEN-FIX D6 — the weighted
+ * scrub). The cursor MOTION (not its absolute X) nudges the loop clock: a flick fast-
+ * forwards, a still cursor lets the field drift at its config speed. Velocity-continuous —
+ * the head never teleports (the prior `headT = pointerX` absolute-X scrub read as "not
+ * following" a 2-D cursor).
+ */
+export declare const SCRUB_GAIN = 0.15;
+/**
+ * The comet ribbon's TAIL width as a fraction of the head width (the head→tail taper). At the
+ * head (age 1) the stroke is the full `trailWidth`; at the tail (age 0) it is `RIBBON_TAIL_FRAC`
+ * of it. The taper is `f(age) = RIBBON_TAIL_FRAC + (1 − RIBBON_TAIL_FRAC)·age` (LINEAR, so the
+ * age-0.5 MID-BODY is `RIBBON_TAIL_FRAC + (1 − RIBBON_TAIL_FRAC)·0.5` of the head). Declared
+ * ONCE here + MIRRORED verbatim as the `RIBBON_TAIL_FRAC` const in BOTH shaders (the GLSL twin
+ * cannot import a TS constant); `proof:viz` FB1 cross-checks the three copies are equal so the
+ * mid-body floor below can never drift off the taper.
+ */
+export declare const RIBBON_TAIL_FRAC = 0.4;
+/** The mid-body taper fraction (age 0.5) — the width the {@link RIBBON_HEAD_FLOOR_PX} floor targets. */
+export declare const RIBBON_MID_TAPER_FRAC: number;
+/**
+ * The MID-BODY minimum in CSS px (the B1 "≥2.5px CSS mid-body at every DPR, never a 1px
+ * hairline polyline" bar). The width is DPR-independent by construction (converted to model
+ * via `canvasCssMin` = backing ÷ dpr), so a CSS-px floor holds at every DPR.
+ */
+export declare const RIBBON_MID_FLOOR_PX = 2.5;
+/**
+ * The HEAD-width floor in CSS px (the `trailWidth` clamp in `trailWidthToModel`). Sized so the
+ * mid-body (head × {@link RIBBON_MID_TAPER_FRAC}) clears {@link RIBBON_MID_FLOOR_PX} — even a
+ * consumer setting `trailWidth: 1` gets a ≥2.5px mid-body. A hair over the exact quotient for
+ * float safety.
+ */
+export declare const RIBBON_HEAD_FLOOR_PX: number;
+/**
+ * The degenerate-tangent guard (BD.W-FOURIER-LOOM §2b). At a cusp the head's instantaneous
+ * speed `s = length(head − headBack)` collapses to ~0 and the unit tangent `T = d/s` blows
+ * up; below `FOURIER_TANGENT_EPS` the shaders + the GL CPU bead path all fall back to the
+ * LAST stable tangent, so `s→0` resolves IDENTICALLY across both engines (the cross-engine
+ * cusp-parity fence — one shared constant, no per-engine drift).
+ */
+export declare const FOURIER_TANGENT_EPS = 0.0001;
+/**
+ * The head squash-and-stretch gain (BD.W-FOURIER-LOOM §2b). The round head bead becomes a
+ * volume-preserving anisotropic ellipse: the tangent extent scales `1 + k·ŝ`, the normal
+ * extent `1/(1 + k·ŝ)`, where `ŝ` is the normalized head speed. The library identity carries
+ * a SMALL non-zero gain (cartoon-weight at rest — the head is never a dead disc); a consumer
+ * vivid preset turns it to 11. `0` = the byte-frozen round disc.
+ */
+export declare const FOURIER_SQUASH_GAIN = 0.55;
+/**
+ * The cartoon cel-shadow gain (BD.W-FOURIER-LOOM §3b). Each chain ring/arm/dot + the comet
+ * rope paints a second darker copy OFFSET opposite its travel — the 1940s technicolor ink.
+ * The library identity carries a SMALL non-zero gain (a quiet weight under the chain); a
+ * consumer vivid preset floors it UP. `0` = no cel pass (byte-frozen). The offset rides the
+ * head tangent, mirrored on both engines off the SAME `curveSamples` tangent.
+ */
+export declare const FOURIER_CEL_GAIN = 0.35;
+/**
+ * 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.
+ */
+export interface FourierFieldConfig {
+    /** The active phasor spectrum source key — `"elliptic"` (generated) or a curated shape key. */
+    source: string;
+    /** TRUNCATE the partial sum — the harmonic count N (1..min(spectrum.length, MAX_PHASORS)). */
+    harmonics: number;
+    /** Draw the rotating epicycle chain (orthogonal to N). */
+    showEpicycles: boolean;
+    /** How many chain arms to draw (1..N; ≤ the harmonic count). */
+    epicycleArms: number;
+    /** Paint the chain as a warm-anchored hue sweep vs one analogous hue. */
+    rainbowChain: boolean;
+    /** Comet-body length as a fraction of the period (0.15..1.0). */
+    trailArc: number;
+    /** Comet stroke weight in CSS px (1..6). */
+    trailWidth: number;
+    /** Outer loudness envelope (per-layer alpha multiply, 0..2). */
+    intensity: number;
+    /** Character of the generated elliptic spectrum (0.05..0.4 — smooth ellipse → crinkled). */
+    harmonicScale: number;
+    /** Clock speed multiplier (0.25/0.5/1/2). */
+    speed: number;
+    /** The curve-color ramp (the library viz palette; warm default). Resolved via the ColorResolver. */
+    palette: OklchStop[];
+    /** ONE static frame then park under `prefers-reduced-motion: reduce`. */
+    respectReducedMotion: boolean;
+    /** Pointer scrubs `head_t` + a flick injects clock momentum (the W-VIZ-INTERACTION consume). */
+    interactive: boolean;
+    /**
+     * Head squash-and-stretch gain (BD.W-FOURIER-LOOM §2b). The head bead stretches along the
+     * curve tangent on straights, squashes across it on corners (volume-preserving). The
+     * library identity carries a small non-zero default (cartoon-weight at rest); a vivid
+     * consumer preset turns it to 11. 0 = the byte-frozen round disc.
+     */
+    squashGain: number;
+    /**
+     * Cartoon cel-shadow gain (BD.W-FOURIER-LOOM §3b). A second darker copy of the chain + rope,
+     * offset opposite the head travel (the technicolor ink). The library identity carries a
+     * small non-zero default; a vivid consumer preset floors it UP. 0 = no cel pass.
+     */
+    celGain: number;
+}
+/**
+ * The warm-cream identity palette (the library default — NOT teal). A two-stop warm-amber
+ * ramp over the warm-cream foreground family, resolved via the ColorResolver. The chain's
+ * rainbow sweep is warm-anchored over THIS base; a consumer (the demo) themes it through a
+ * preset, never a token edit.
+ */
+export declare const WARM_IDENTITY_PALETTE: OklchStop[];
+/** The shipped warm-identity default config. */
+export declare const DEFAULT_FOURIER_CONFIG: FourierFieldConfig;

package/dist/components/fourier-field/index.d.ts

@@ -0,0 +1,31 @@
+import type { ColorResolver, OklchStop } from "../../composables/color";
+import type { FourierFieldConfig } from "./constants";
+import type { BasisComponent } from "./math";
+export { default as FourierField } from "./FourierField.vue";
+export { comp, positionsAt, partialSumAt, dftFromPoints, makeEllipticSpectrum, makeHarmonicFigure, FOURIER_FIGURES, FOURIER_FIGURE_KEYS, type BasisComponent, type EllipticSpectrumOptions, type HarmonicTerm, } from "./math";
+export { DEFAULT_FOURIER_CONFIG, WARM_IDENTITY_PALETTE, MAX_PHASORS, MAX_CURVE_SAMPLES, type FourierFieldConfig, } from "./constants";
+export { useFourierField, type FourierFieldHandle, type UseFourierFieldOptions, } from "./composables/useFourierField";
+/**
+ * The props a consumer forwards when wrapping `<FourierField>` (the GPU-substrate epicycle
+ * field; ships via `/fourier-field`). Mirrors the component's inline `defineProps` shape (an
+ * SFC cannot export its inline props type). BC.W-VIZ-FOURIER — the `variant: "hero"|"final"`
+ * enum is RETIRED (folds into config presets); the renderer is the WGSL-primary GPU substrate.
+ */
+export interface FourierFieldProps {
+    /** The full author config (the studio's `useConfiguratorState` model). Defaults to the warm identity. */
+    config?: FourierFieldConfig;
+    /** An explicit CPU-minted spectrum (a curated shape's DFT). When absent, a seeded elliptic spectrum is generated. */
+    spectrum?: readonly BasisComponent[];
+    /** Resolve the curve palette as OKLCh (the studio themes it). */
+    getPalette?: () => OklchStop[];
+    /** Ambient-consumer color seam — a `var()`/`light-dark()` token or a literal; derives a warm palette. */
+    color?: string;
+    /** The color resolver (the GooBlob/Aurora seam) — required when `color` is a `var()` token. */
+    colorResolver?: ColorResolver;
+    /** Extra seed mixed into the generated elliptic spectrum PRNG. Default "". */
+    seed?: string;
+    /** Paint ONE static deterministic best-frame and never animate (the capture lever). Default false. */
+    freeze?: boolean;
+    /** Outer loudness envelope (scales the per-layer alpha). Overrides `config.intensity` when set; clamped [0, 2]. */
+    intensity?: number;
+}

package/dist/components/fourier-field/math.d.ts

@@ -0,0 +1,111 @@
+/**
+ * One Fourier phasor. `index` is the integer frequency (a counter-rotating pair
+ * is `+1` and `-1`); `coefficient` is the complex coefficient `[re, im]`;
+ * `amplitude`/`phase` are its polar form (carried for callers that prefer the
+ * polar read — the reconstruction uses the rectangular `coefficient`).
+ */
+export interface BasisComponent {
+    index: number;
+    coefficient: [number, number];
+    amplitude: number;
+    phase: number;
+}
+/**
+ * Build a {@link BasisComponent} from a frequency index and its rectangular
+ * coefficient `(re, im)`, deriving the polar `amplitude`/`phase`.
+ */
+export declare function comp(index: number, re: number, im: number): BasisComponent;
+/**
+ * The epicycle chain at parameter `t`: the running tip of each phasor stacked on
+ * the last, starting at the origin. `positions[0]` is `[0, 0]`; the final entry
+ * is the curve point — the inverse-DFT sum `Σ c_k * exp(2*pi*i*k*t)` at the same
+ * `t`. `maxCircles` truncates the chain (draw fewer arms than the spectrum
+ * carries).
+ */
+export declare function positionsAt(components: BasisComponent[], t: number, maxCircles?: number): [number, number][];
+/**
+ * The PARTIAL-SUM curve point at parameter `t` over the FIRST `maxTerms` phasors
+ * — the inverse-DFT truncated summation `Σ_{k<maxTerms} c_k * exp(2*pi*i*k*t)`.
+ * It is {@link positionsAt} truncated at `maxTerms` and read at the FINAL tip:
+ * the single curve POINT (not the whole chain). The truncation axis is the SAME
+ * one `positionsAt`'s `maxCircles` arg drives — `maxCircles` reads the whole
+ * chain truncated, `partialSumAt` reads only its endpoint — so the studio's
+ * N-harmonics slider can draw the assembling chain (`positionsAt(.., N)`) AND the
+ * resolving curve point (`partialSumAt(.., t, N)`) off the ONE axis. Sweeping `t`
+ * over `[0,1)` and joining the points traces the partial-sum CURVE: at `maxTerms`
+ * = 1 a single ellipse, growing toward the full reconstruction as `maxTerms`
+ * climbs to `components.length` (the reference's "watch it sum" beauty).
+ *
+ * `maxTerms` omitted (or ≥ `components.length`) is the full reconstruction — the
+ * same point `positionsAt(components, t)` returns at its final tip.
+ */
+export declare function partialSumAt(components: BasisComponent[], t: number, maxTerms?: number): [number, number];
+/**
+ * The forward DFT — the inverse of {@link positionsAt}. Takes a closed sequence
+ * of `[x, y]` samples around a curve (treated as the complex signal `x + i·y`,
+ * uniformly spaced in the parameter `t ∈ [0, 1)`) and returns the
+ * {@link BasisComponent} spectrum that {@link positionsAt} reconstructs.
+ *
+ * Frequencies run symmetrically around 0 — `0, +1, -1, +2, -2, …` up to the
+ * Nyquist limit — which is the index ordering the epicycle chain wants (the big
+ * low-order phasors first). The DC term (`index 0`) is the curve's centroid; the
+ * caller can subtract it (draw the chain centered) or keep it (draw at the
+ * sampled position).
+ *
+ * General: any point set drives it (a glyph outline, a hand-traced path, a
+ * digitized signature). It is NOT a special case — it is the literal forward
+ * transform whose inverse already ships as `positionsAt`.
+ */
+export declare function dftFromPoints(points: [number, number][]): BasisComponent[];
+/** Tuning for {@link makeEllipticSpectrum}. */
+export interface EllipticSpectrumOptions {
+    /**
+     * How many smaller higher-order harmonics to layer on top of the dominant
+     * counter-rotating pair (the dominant pair is always present). Default 4.
+     * The `final` preset passes a larger count for a denser, busier curve.
+     */
+    harmonics?: number;
+    /**
+     * Peak magnitude of the higher-order harmonics relative to the dominant
+     * phasor. Smaller keeps the curve a clean, smooth ellipse with a little
+     * character; larger crinkles it. Default ~0.22.
+     */
+    harmonicScale?: number;
+}
+/**
+ * Emit a procedural elliptic spectrum: a DOMINANT counter-rotating pair (index
+ * `+1` and `-1`) of UNEQUAL magnitude — the inequality is what draws a tilted
+ * ellipse rather than a circle — plus a few smaller higher-order harmonics with
+ * random small magnitudes and phases for character. Lower orders carry more
+ * weight (a `1 / order` falloff), so the curve stays large, smooth and
+ * few-big-phasor; the `harmonics` knob lifts it to the denser `final` look.
+ *
+ * Deterministic in `rng`: the same seeded `() => number` yields the same
+ * spectrum, so a frozen frame reproduces exactly.
+ */
+export declare function makeEllipticSpectrum(rng: () => number, opts?: EllipticSpectrumOptions): BasisComponent[];
+/** One integer-index harmonic term of a {@link FOURIER_FIGURES} recipe (polar form). */
+export interface HarmonicTerm {
+    /** The INTEGER frequency index (a closed figure requires integers — the period-1 fence). */
+    index: number;
+    /** The phasor magnitude (relative; the figure is scale-fit at render). */
+    mag: number;
+    /** The phase offset in turns (0..1 — multiplied by 2π; a phase rotates the figure). */
+    phase: number;
+}
+/**
+ * Build a {@link BasisComponent} spectrum from a closed-figure recipe (a list of integer-index
+ * {@link HarmonicTerm}s). The recipe's `phase` is in TURNS; the rectangular coefficient is
+ * `mag·(cos, sin)` at `2π·phase`. The result CLOSES (all indices integer) — feed it straight
+ * to `partialSumAt`/`positionsAt`.
+ */
+export declare function makeHarmonicFigure(terms: readonly HarmonicTerm[]): BasisComponent[];
+/**
+ * The curated FLOWER / closed-epicycle figure catalogue — few-term integer-ratio harmonic
+ * stacks, each a deliberate figure (the symmetry order is `|p − q|` for the dominant pair).
+ * Selectable/cyclable by key; the LIBRARY beauty register the `boring` random ellipse lacked.
+ * The magnitudes stay large + few-phasor so the figure reads bold, not crinkled.
+ */
+export declare const FOURIER_FIGURES: Record<string, HarmonicTerm[]>;
+/** The ordered figure keys (the demo/consumer cycle order). */
+export declare const FOURIER_FIGURE_KEYS: string[];

package/dist/components/fourier-field/shaders/fourier-field.glsl.d.ts

@@ -0,0 +1,4 @@
+/** The instanced ribbon VERTEX — expands the unit quad to each instance's covered bbox. */
+export declare const FOURIER_FIELD_VERT_GLSL = "#version 300 es\n// BI.W-FOURIER-RIBBON \u00A72b \u2014 MUST equal the WGSL twin + FOURIER_TANGENT_EPS (constants.ts).\n#define RIBBON_UNDERGLOW_SCALE 2.2\n\nin vec2 aCorner;   // the unit quad corner \u2208 [0,1]\u00B2\nin vec4 aSeg;      // (ax, ay, bx, by) \u2014 segment endpoints in MODEL space\nin vec4 aData;     // (age, strokeHalf, arg2, _pad) \u2014 strokeHalf/age/arg2 per layer\n\nuniform vec4 uFit;         // (centerX, centerY, scale, aspect) \u2014 model\u2192clip fit\nuniform int  uLayer;       // 0 trail \u00B7 1 epicycle \u00B7 2 head \u00B7 3 cel-rope \u00B7 4 cel-arm\nuniform float uEdgeMargin; // AA-feather slop in MODEL units (a few CSS px), padding the bbox\n\nout vec2 vP;       // the MODEL-space fragment coordinate (the fs runs the SDF on it)\nout vec2 vA;\nout vec2 vB;\nout float vAge;\nout float vHalf;\nout float vArg2;\n\nvoid main() {\n  vec2 a = aSeg.xy;\n  vec2 b = aSeg.zw;\n  float strokeHalf = aData.y;\n  vA = a; vB = b; vAge = aData.x; vHalf = strokeHalf; vArg2 = aData.z;\n\n  vec2 pos;\n  if (uLayer == 1 || uLayer == 2) {\n    // AABB around a \u2014 the epicycle orbit RING (radius = |b-a|) or the head HALO.\n    float ext = (uLayer == 1) ? (length(b - a) + strokeHalf * 0.7) : (strokeHalf * 4.5);\n    ext += uEdgeMargin;\n    pos = a + (aCorner * 2.0 - 1.0) * ext;\n  } else {\n    // Capsule along a\u2192b padded by the covered extent (trail under-glow / cel stroke).\n    float ext = (uLayer == 0) ? (strokeHalf * RIBBON_UNDERGLOW_SCALE) : strokeHalf;\n    ext += uEdgeMargin;\n    vec2 d = b - a;\n    float len = length(d);\n    vec2 dir = len > 1e-6 ? d / len : vec2(1.0, 0.0);\n    vec2 perp = vec2(-dir.y, dir.x);\n    vec2 along = mix(a - dir * ext, b + dir * ext, aCorner.x);\n    pos = along + perp * (aCorner.y * 2.0 - 1.0) * ext;\n  }\n\n  vP = pos;\n  vec2 center = uFit.xy;\n  float scale = max(uFit.z, 1e-6);\n  float aspect = max(uFit.w, 1e-4);\n  // model \u2192 clip (the inverse of the fs's p = center + vClip\u00B7aspect / scale).\n  float clipX = (pos.x - center.x) * scale / aspect;\n  float clipY = (pos.y - center.y) * scale;\n  gl_Position = vec4(clipX, clipY, 0.0, 1.0);\n}\n";
+/** The instanced ribbon FRAGMENT — the exact per-layer SDF over-composite, loop-free. */
+export declare const FOURIER_FIELD_FRAG_GLSL = "#version 300 es\nprecision highp float;\n\n#define MAX_FOURIER_STOPS 4\n// BD.W-FOURIER-LOOM \u00A72b \u2014 MUST equal the WGSL twin + FOURIER_TANGENT_EPS (constants.ts).\n#define TANGENT_EPS 1e-4\n#define SPEED_REF_HALFWIDTHS 6.0\n// BG.W-FOURIER-BEAUTY B1 \u2014 the THICK luminous RIBBON. RIBBON_TAIL_FRAC is MIRRORED verbatim\n// from constants.ts (the GLSL twin cannot import a TS const); proof:viz FB1 cross-checks the\n// two copies are equal so the mid-body floor (RIBBON_HEAD_FLOOR_PX) can never drift off it.\n#define RIBBON_TAIL_FRAC 0.4\n#define RIBBON_UNDERGLOW_SCALE 2.2\n#define RIBBON_UNDERGLOW_ALPHA 0.16\n\nin vec2 vP;\nin vec2 vA;\nin vec2 vB;\nin float vAge;\nin float vHalf;\nin float vArg2;\nout vec4 fragColor;\n\nuniform vec4 uTrail;      // (trailWidth, peakAlpha, headGlowAlpha, trailFadeExp)\nuniform vec4 uEnv;        // (trailFloor, intensity, showEpicycles, rainbowChain)\nuniform vec4 uLoom;       // (squashGain, celGain, _pad, _pad) \u2014 FOURIER-LOOM \u00A72b/\u00A73b\nuniform int  uLayer;      // 0 trail \u00B7 1 epicycle \u00B7 2 head \u00B7 3 cel-rope \u00B7 4 cel-arm\nuniform int  uStopCount;\nuniform vec3 uPalette[MAX_FOURIER_STOPS]; // linear-sRGB stops\n\nconst float PI = 3.141592653589793;\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// Negative-safe cube root (the WGSL chunk's cbrt3 twin; the GLSL chunk inlines it).\nvec3 cbrt3(vec3 v) { return sign(v) * pow(abs(v), vec3(1.0 / 3.0)); }\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 labA = LMS_TO_OKLAB * cbrt3(LINEAR_SRGB_TO_LMS * uPalette[i0]);\n  vec3 labB = LMS_TO_OKLAB * cbrt3(LINEAR_SRGB_TO_LMS * uPalette[i1]);\n  return oklabToLinearSrgb(mix(labA, labB, f));\n}\n\nvec3 chainColorLin(float seg, bool rainbow) {\n  vec3 baseLin = uPalette[0];\n  if (!rainbow) return baseLin;\n  vec3 lab = LMS_TO_OKLAB * cbrt3(LINEAR_SRGB_TO_LMS * baseLin);\n  vec3 lch = oklabToOklch(lab);\n  float hueShift = mix(-0.45, 1.15, clamp(seg, 0.0, 1.0));\n  vec3 lifted = vec3(0.66, max(lch.y, 0.14), lch.z + hueShift);\n  return oklabToLinearSrgb(oklchToOklab(lifted));\n}\n\nfloat segDist(vec2 p, vec2 a, vec2 b) {\n  vec2 pa = p - a;\n  vec2 ba = b - a;\n  float h = clamp(dot(pa, ba) / max(dot(ba, ba), 1e-8), 0.0, 1.0);\n  return length(pa - ba * h);\n}\n\n// BD.W-FOURIER-LOOM \u00A72b \u2014 the head travel frame (T, \u015D), the GLSL twin of the WGSL headFrame.\nstruct HeadFrame { vec2 T; float sHat; };\nHeadFrame headFrame(vec2 head, vec2 headBack, float halfW) {\n  vec2 d = head - headBack;\n  float s = length(d);\n  HeadFrame fr;\n  if (s <= TANGENT_EPS) { fr.T = vec2(1.0, 0.0); fr.sHat = 0.0; return fr; }\n  fr.T = d / s;\n  float refScale = max(halfW * SPEED_REF_HALFWIDTHS, 1e-6);\n  fr.sHat = clamp(s / refScale, 0.0, 1.0);\n  return fr;\n}\n\n// The volume-preserving anisotropic head distance (the WGSL headAniso twin).\nfloat headAniso(vec2 p, vec2 head, HeadFrame fr, float k) {\n  float g = 1.0 + k * fr.sHat;\n  vec2 n = vec2(-fr.T.y, fr.T.x);\n  vec2 rel = p - head;\n  float along = dot(rel, fr.T) / g;\n  float across = dot(rel, n) * g;\n  return length(vec2(along, across));\n}\n\nvoid main() {\n  vec2 p = vP;\n  float aa = max(fwidth(p.x) + fwidth(p.y), 1e-5) * 0.75;\n  float peak = uTrail.y * uEnv.y;\n  float headGlow = uTrail.z * uEnv.y;\n  float fadeExp = uTrail.w;\n  float trailFloor = uEnv.x;\n  bool rainbow = uEnv.w > 0.5;\n  float squashGain = uLoom.x;\n  float celGain = uLoom.y;\n  float halfW = vHalf;\n\n  if (uLayer == 0) {\n    // \u2500\u2500 TRAIL \u2014 the tapered luminous ribbon over its own soft under-glow \u2500\u2500\n    float age = vAge;\n    float d = segDist(p, vA, vB);\n    // B1 \u2014 the head\u2192tail TAPER: the ribbon half-width scales with age (thick head, thin tail).\n    float ribbonHalf = halfW * (RIBBON_TAIL_FRAC + (1.0 - RIBBON_TAIL_FRAC) * age);\n    vec3 lin = samplePaletteLin(1.0 - age * 0.4);\n    vec3 rgb = clamp(linearToSrgb(lin), vec3(0.0), vec3(1.0));\n    // B1 \u2014 the soft UNDER-GLOW: a wider, low-alpha copy UNDER the crisp ribbon (ONE color event).\n    float glowHalf = ribbonHalf * RIBBON_UNDERGLOW_SCALE;\n    float glowCover = 1.0 - smoothstep(glowHalf, glowHalf + aa * 3.0, d);\n    float ga = peak * RIBBON_UNDERGLOW_ALPHA * pow(age, fadeExp) * glowCover;\n    // the crisp tapered ribbon core.\n    float cover = 1.0 - smoothstep(ribbonHalf, ribbonHalf + aa, d);\n    float ca = max(peak * pow(age, fadeExp), peak * trailFloor) * cover;\n    // core OVER glow OVER transparent (both premultiplied on the SAME rgb \u2192 out = rgb\u00B7outA).\n    float outA = ca + ga * (1.0 - ca);\n    fragColor = vec4(rgb * outA, outA);\n  } else if (uLayer == 1) {\n    // \u2500\u2500 EPICYCLE \u2014 orbit RING + ARM + joint DOT union (MAX-blended, no join seam) \u2500\u2500\n    float seg = vArg2;\n    vec3 lin = chainColorLin(seg, rainbow);\n    vec3 rgb = clamp(linearToSrgb(lin), vec3(0.0), vec3(1.0));\n    float radius = length(vB - vA);\n    float dRing = abs(length(p - vA) - radius);\n    float ringW = max(halfW * 0.45, aa);\n    float ringMask = (1.0 - smoothstep(ringW, ringW + aa, dRing)) * 0.5;\n    float dArm = segDist(p, vA, vB);\n    float armMask = 1.0 - smoothstep(halfW * 0.55, halfW * 0.55 + aa, dArm);\n    float dotR = max(halfW * 0.7, aa * 2.0);\n    float dDot = length(p - vA);\n    float dotMask = 1.0 - smoothstep(dotR, dotR + aa, dDot);\n    float m = clamp(max(max(ringMask, armMask), dotMask), 0.0, 1.0) * peak * 0.7;\n    fragColor = vec4(rgb * m, m);\n  } else if (uLayer == 2) {\n    // \u2500\u2500 HEAD \u2014 squash-and-stretch (\u00A72b): halo + saturated core + white specular \u2500\u2500\n    vec2 head = vA;\n    vec2 headBack = vB;\n    HeadFrame fr = headFrame(head, headBack, halfW);\n    float dHead = headAniso(p, head, fr, squashGain);\n    float coreR = halfW * 1.5;\n    float haloR = coreR * 3.0;\n    vec3 headRgb = clamp(linearToSrgb(samplePaletteLin(0.0)), vec3(0.0), vec3(1.0));\n    float halo = (1.0 - smoothstep(0.0, haloR, dHead)) * headGlow * 0.35;\n    vec4 accum = vec4(headRgb * halo, halo);\n    float core = (1.0 - smoothstep(coreR, coreR + aa, dHead)) * headGlow;\n    accum = vec4(headRgb * core, core) + accum * (1.0 - core);\n    float spec = (1.0 - smoothstep(coreR * 0.4, coreR * 0.4 + aa, dHead)) * headGlow * 0.9;\n    accum = vec4(vec3(1.0) * spec, spec) + accum * (1.0 - spec);\n    fragColor = accum;\n  } else {\n    // \u2500\u2500 CEL \u2014 the technicolor ink shadow (rope uLayer==3 / arm uLayer==4) \u2500\u2500\n    float celA = clamp(celGain, 0.0, 1.0);\n    float d = segDist(p, vA, vB);\n    float cover = 1.0 - smoothstep(halfW, halfW + aa, d);\n    float m = cover * celA * peak * vArg2; // vArg2 = celStrength (1.0 rope / 0.7 arm)\n    fragColor = vec4(0.0, 0.0, 0.0, m);\n  }\n}\n";

package/dist/components/fourier-field/shaders/fourier-field.render.wgsl.d.ts

@@ -0,0 +1 @@
+export declare const FOURIER_FIELD_RENDER_WGSL = "\n// The instanced-ribbon LAYER selector (a pipeline-overridable constant \u2014 5 pipelines share the\n// ONE module, each specializing this): 0 trail \u00B7 1 epicycle \u00B7 2 head \u00B7 3 cel-rope \u00B7 4 cel-arm.\noverride LAYER: i32 = 0;\n\nconst PI: f32 = 3.141592653589793;\n// BD.W-FOURIER-LOOM \u00A72b \u2014 the degenerate-tangent guard (must equal FOURIER_TANGENT_EPS in\n// constants.ts + the GL CPU bead path so a cusp resolves IDENTICALLY across both engines).\nconst TANGENT_EPS: f32 = 1e-4;\nconst SPEED_REF_HALFWIDTHS: f32 = 6.0;\n// BG.W-FOURIER-BEAUTY B1 \u2014 the THICK luminous RIBBON. RIBBON_TAIL_FRAC is MIRRORED verbatim\n// from constants.ts (the WGSL twin cannot import a TS const); proof:viz FB1 cross-checks the\n// two copies are equal so the mid-body floor (RIBBON_HEAD_FLOOR_PX) can never drift off it.\nconst RIBBON_TAIL_FRAC: f32 = 0.4;\nconst RIBBON_UNDERGLOW_SCALE: f32 = 2.2;\nconst RIBBON_UNDERGLOW_ALPHA: f32 = 0.16;\n\n// \u2500\u2500 Render uniforms (the typed-struct source-of-truth \u2014 see uniformBridgeWGPU.ts) \u2500\u2500\nstruct RenderUniforms {\n  // r0: (centerX, centerY, scale, aspect)  \u2014 model\u2192clip fit transform\n  r0: vec4<f32>,\n  // r1: (trailWidth, peakAlpha, headGlowAlpha, trailFadeExp)\n  r1: vec4<f32>,\n  // r2: (trailFloor, intensity, showEpicycles, rainbowChain)\n  r2: vec4<f32>,\n  // r3: (squashGain, celGain, edgeMargin, _pad) \u2014 FOURIER-LOOM \u00A72b/\u00A73b + the ribbon bbox slop\n  r3: vec4<f32>,\n  // ints: (sampleCount, armCount, stopCount, _pad)\n  ints: vec4<i32>,\n  // palette stops: linear-sRGB rgb + _pad\n  palette: array<vec4<f32>, 4>,\n};\n\n@group(0) @binding(0) var<uniform> u: RenderUniforms;\n// curveSamples[i] = (x, y, age, _pad) in MODEL space \u2014 the render VERTEX-PULLS these.\n@group(0) @binding(1) var<storage, read> curveSamples: array<vec4<f32>>;\n// chainTips[k] = (x, y, _pad, _pad) in MODEL space.\n@group(0) @binding(2) var<storage, read> chainTips: array<vec4<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\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\nfn samplePaletteLin(t: f32) -> vec3<f32> {\n  let stopCount = u.ints.z;\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\nfn chainColorLin(seg: f32, rainbow: bool) -> vec3<f32> {\n  let baseLin = u.palette[0].rgb;\n  if (!rainbow) { return baseLin; }\n  let lab = LMS_TO_OKLAB * cbrt3(LINEAR_SRGB_TO_LMS * baseLin);\n  let lch = oklabToOklch(lab);\n  let hueShift = mix(-0.45, 1.15, clamp(seg, 0.0, 1.0));\n  let h = lch.z + hueShift;\n  let lifted = vec3<f32>(0.66, max(lch.y, 0.14), h);\n  return oklabToLinearSrgb(oklchToOklab(lifted));\n}\n\nfn segDist(p: vec2<f32>, a: vec2<f32>, b: vec2<f32>) -> f32 {\n  let pa = p - a;\n  let ba = b - a;\n  let h = clamp(dot(pa, ba) / max(dot(ba, ba), 1e-8), 0.0, 1.0);\n  return length(pa - ba * h);\n}\n\n// BD.W-FOURIER-LOOM \u00A72b \u2014 the head travel frame + the volume-preserving anisotropic distance.\nstruct HeadFrame { T: vec2<f32>, sHat: f32, };\nfn headFrame(head: vec2<f32>, headBack: vec2<f32>, halfW: f32) -> HeadFrame {\n  let d = head - headBack;\n  let s = length(d);\n  var out: HeadFrame;\n  if (s <= TANGENT_EPS) {\n    out.T = vec2<f32>(1.0, 0.0);\n    out.sHat = 0.0;\n    return out;\n  }\n  out.T = d / s;\n  let refScale = max(halfW * SPEED_REF_HALFWIDTHS, 1e-6);\n  out.sHat = clamp(s / refScale, 0.0, 1.0);\n  return out;\n}\n\nfn headAniso(p: vec2<f32>, head: vec2<f32>, fr: HeadFrame, k: f32) -> f32 {\n  let g = 1.0 + k * fr.sHat;\n  let n = vec2<f32>(-fr.T.y, fr.T.x);\n  let rel = p - head;\n  let along = dot(rel, fr.T) / g;\n  let across = dot(rel, n) * g;\n  return length(vec2<f32>(along, across));\n}\n\n// The cel ink lags behind the travel \u2014 the SAME \u2212T\u00B7halfW\u00B71.4 offset both engines apply (the\n// head frame is read straight off the compute-filled curveSamples[0]/[1], parity by construction).\nfn celOffset(halfW: f32) -> vec2<f32> {\n  let fr = headFrame(curveSamples[0].xy, curveSamples[1].xy, halfW);\n  return -fr.T * halfW * 1.4;\n}\n\n// The unit quad as two triangles (6 verts) in [0,1]\u00B2 \u2014 the instanced vertex expands it.\nfn quadCorner(vi: u32) -> vec2<f32> {\n  var c = array<vec2<f32>, 6>(\n    vec2<f32>(0.0, 0.0), vec2<f32>(1.0, 0.0), vec2<f32>(0.0, 1.0),\n    vec2<f32>(0.0, 1.0), vec2<f32>(1.0, 0.0), vec2<f32>(1.0, 1.0),\n  );\n  return c[vi];\n}\n\nstruct VSOut {\n  @builtin(position) pos: vec4<f32>,\n  @location(0) p: vec2<f32>,      // model-space fragment coordinate\n  @location(1) a: vec2<f32>,\n  @location(2) b: vec2<f32>,\n  @location(3) segData: vec3<f32>,   // (age, strokeHalf, arg2)\n};\n\n@vertex\nfn vs_main(@builtin(vertex_index) vi: u32, @builtin(instance_index) inst: u32) -> VSOut {\n  let corner = quadCorner(vi);\n  let center = u.r0.xy;\n  let scale = max(u.r0.z, 1e-6);\n  let aspect = max(u.r0.w, 1e-4);\n  let halfW = u.r1.x * 0.5;\n  let margin = u.r3.z;\n\n  var a: vec2<f32> = vec2<f32>(0.0);\n  var b: vec2<f32> = vec2<f32>(0.0);\n  var strokeHalf: f32 = halfW;\n  var age: f32 = 0.0;\n  var arg2: f32 = 0.0;\n  var isCapsule: bool = true;\n  var ext: f32 = halfW;\n\n  if (LAYER == 0) {\n    // TRAIL \u2014 the curve capsule; the covered extent is the head-width under-glow.\n    a = curveSamples[inst].xy;\n    b = curveSamples[inst + 1u].xy;\n    age = max(curveSamples[inst].z, curveSamples[inst + 1u].z);\n    ext = halfW * RIBBON_UNDERGLOW_SCALE;\n    isCapsule = true;\n  } else if (LAYER == 1) {\n    // EPICYCLE \u2014 the chain AABB around a (radius = |b\u2212a|).\n    a = chainTips[inst].xy;\n    b = chainTips[inst + 1u].xy;\n    arg2 = f32(inst) / max(f32(u.ints.y - 1), 1.0);\n    ext = length(b - a) + halfW * 0.7;\n    isCapsule = false;\n  } else if (LAYER == 2) {\n    // HEAD \u2014 the comet head at curveSamples[0], AABB by the halo radius.\n    a = curveSamples[0].xy;\n    b = curveSamples[1].xy;\n    ext = halfW * 4.5;\n    isCapsule = false;\n  } else if (LAYER == 3) {\n    // CEL-ROPE \u2014 the curve capsule, offset opposite travel; full-width ink.\n    let off = celOffset(halfW);\n    a = curveSamples[inst].xy + off;\n    b = curveSamples[inst + 1u].xy + off;\n    arg2 = 1.0;\n    ext = halfW;\n    isCapsule = true;\n  } else {\n    // CEL-ARM (LAYER == 4) \u2014 the chain capsule, offset; the narrower arm ink (0.55\u00B7halfW).\n    let off = celOffset(halfW);\n    a = chainTips[inst].xy + off;\n    b = chainTips[inst + 1u].xy + off;\n    strokeHalf = halfW * 0.55;\n    arg2 = 0.7;\n    ext = halfW * 0.55;\n    isCapsule = true;\n  }\n  ext = ext + margin;\n\n  var pos: vec2<f32>;\n  if (isCapsule) {\n    let d = b - a;\n    let len = length(d);\n    var dir = vec2<f32>(1.0, 0.0);\n    if (len > 1e-6) { dir = d / len; }\n    let perp = vec2<f32>(-dir.y, dir.x);\n    let along = mix(a - dir * ext, b + dir * ext, corner.x);\n    pos = along + perp * (corner.y * 2.0 - 1.0) * ext;\n  } else {\n    pos = a + (corner * 2.0 - vec2<f32>(1.0)) * ext;\n  }\n\n  let clipX = (pos.x - center.x) * scale / aspect;\n  let clipY = (pos.y - center.y) * scale;\n  var out: VSOut;\n  out.pos = vec4<f32>(clipX, clipY, 0.0, 1.0);\n  out.p = pos;\n  out.a = a;\n  out.b = b;\n  out.segData = vec3<f32>(age, strokeHalf, arg2);\n  return out;\n}\n\n@fragment\nfn fs_main(in: VSOut) -> @location(0) vec4<f32> {\n  let p = in.p;\n  let aa = max(fwidth(p.x) + fwidth(p.y), 1e-5) * 0.75;\n  let peak = u.r1.y * u.r2.y;\n  let headGlow = u.r1.z * u.r2.y;\n  let fadeExp = u.r1.w;\n  let trailFloor = u.r2.x;\n  let rainbow = u.r2.w > 0.5;\n  let squashGain = u.r3.x;\n  let celGain = u.r3.y;\n  let halfW = in.segData.y;\n  let age = in.segData.x;\n  let arg2 = in.segData.z;\n  let a = in.a;\n  let b = in.b;\n\n  if (LAYER == 0) {\n    // \u2500\u2500 TRAIL \u2014 the tapered luminous ribbon over its own soft under-glow \u2500\u2500\n    let d = segDist(p, a, b);\n    let ribbonHalf = halfW * (RIBBON_TAIL_FRAC + (1.0 - RIBBON_TAIL_FRAC) * age);\n    let lin = samplePaletteLin(1.0 - age * 0.4);\n    let rgb = clamp(linearToSrgb(lin), vec3<f32>(0.0), vec3<f32>(1.0));\n    let glowHalf = ribbonHalf * RIBBON_UNDERGLOW_SCALE;\n    let glowCover = 1.0 - smoothstep(glowHalf, glowHalf + aa * 3.0, d);\n    let ga = peak * RIBBON_UNDERGLOW_ALPHA * pow(age, fadeExp) * glowCover;\n    let cover = 1.0 - smoothstep(ribbonHalf, ribbonHalf + aa, d);\n    let ca = max(peak * pow(age, fadeExp), peak * trailFloor) * cover;\n    let outA = ca + ga * (1.0 - ca);\n    return vec4<f32>(rgb * outA, outA);\n  } else if (LAYER == 1) {\n    // \u2500\u2500 EPICYCLE \u2014 orbit RING + ARM + joint DOT union (MAX-blended, no join seam) \u2500\u2500\n    let lin = chainColorLin(arg2, rainbow);\n    let rgb = clamp(linearToSrgb(lin), vec3<f32>(0.0), vec3<f32>(1.0));\n    let radius = length(b - a);\n    let dRing = abs(length(p - a) - radius);\n    let ringW = max(halfW * 0.45, aa);\n    let ringMask = (1.0 - smoothstep(ringW, ringW + aa, dRing)) * 0.5;\n    let dArm = segDist(p, a, b);\n    let armMask = 1.0 - smoothstep(halfW * 0.55, halfW * 0.55 + aa, dArm);\n    let dotR = max(halfW * 0.7, aa * 2.0);\n    let dDot = length(p - a);\n    let dotMask = 1.0 - smoothstep(dotR, dotR + aa, dDot);\n    let m = clamp(max(max(ringMask, armMask), dotMask), 0.0, 1.0) * peak * 0.7;\n    return vec4<f32>(rgb * m, m);\n  } else if (LAYER == 2) {\n    // \u2500\u2500 HEAD \u2014 squash-and-stretch (\u00A72b): halo + saturated core + white specular \u2500\u2500\n    let head = a;\n    let headBack = b;\n    let fr = headFrame(head, headBack, halfW);\n    let dHead = headAniso(p, head, fr, squashGain);\n    let coreR = halfW * 1.5;\n    let haloR = coreR * 3.0;\n    let headRgb = clamp(linearToSrgb(samplePaletteLin(0.0)), vec3<f32>(0.0), vec3<f32>(1.0));\n    let halo = (1.0 - smoothstep(0.0, haloR, dHead)) * headGlow * 0.35;\n    var accum = vec4<f32>(headRgb * halo, halo);\n    let core = (1.0 - smoothstep(coreR, coreR + aa, dHead)) * headGlow;\n    accum = vec4<f32>(headRgb * core, core) + accum * (1.0 - core);\n    let spec = (1.0 - smoothstep(coreR * 0.4, coreR * 0.4 + aa, dHead)) * headGlow * 0.9;\n    accum = vec4<f32>(vec3<f32>(1.0) * spec, spec) + accum * (1.0 - spec);\n    return accum;\n  } else {\n    // \u2500\u2500 CEL \u2014 the technicolor ink shadow (rope LAYER==3 / arm LAYER==4) \u2500\u2500\n    let celA = clamp(celGain, 0.0, 1.0);\n    let d = segDist(p, a, b);\n    let cover = 1.0 - smoothstep(halfW, halfW + aa, d);\n    let m = cover * celA * peak * arg2; // arg2 = celStrength (1.0 rope / 0.7 arm)\n    return vec4<f32>(0.0, 0.0, 0.0, m);\n  }\n}\n";

package/dist/components/fourier-field/shaders/fourier-field.ribbon.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The ordered ribbon LAYER kinds — the fullscreen loop's draw order, one instanced draw each:
+ *   cel-rope → cel-arm  (the technicolor ink shadow, painted FIRST, UNDER the lit chain)
+ *   epicycle            (the orbit rings + arms + joint dots — the scaffold under the curve)
+ *   trail               (the tapered luminous ribbon over its own under-glow)
+ *   head                (the squash-and-stretch comet head — halo + core + specular)
+ */
+export type RibbonLayerKind = "cel-rope" | "cel-arm" | "epicycle" | "trail" | "head";
+/**
+ * The blend mode a layer draws with. `over` is the premultiplied source-over
+ * (`ONE, ONE_MINUS_SRC_ALPHA`) every layer but the epicycle uses. `max` (per-channel
+ * `blendEquation MAX`) is the FB5 fix for the epicycle-join over-composite SEAM: adjacent
+ * arms' rings/dots overlap, and over-compositing them separately double-darkened the joins
+ * (the named 9× residual); MAX makes the epicycle group a per-channel UNION so overlapping
+ * arms take the brighter contribution instead of stacking.
+ */
+export type RibbonBlend = "over" | "max";
+/** The shader LAYER selector (WGSL override `LAYER` / GLSL `uLayer`) per kind. */
+export declare const RIBBON_LAYER_ID: Readonly<Record<RibbonLayerKind, number>>;
+export interface RibbonLayer {
+    readonly kind: RibbonLayerKind;
+    /** The instance count for this layer's single `drawInstanced` (0 layers are omitted). */
+    readonly instanceCount: number;
+    readonly blend: RibbonBlend;
+}
+export interface RibbonPlanInput {
+    /** The comet-curve sample count — the trail draws `sampleCount − 1` capsule instances. */
+    readonly sampleCount: number;
+    /** The epicycle arm count (0 / `showEpicycles: false` → no epicycle + no cel-arm layer). */
+    readonly armCount: number;
+    readonly showEpicycles: boolean;
+    /** The cel-shadow gain — `0` omits the cel-rope + cel-arm layers (byte-frozen). */
+    readonly celGain: number;
+}
+/**
+ * The per-frame ribbon DRAW PLAN both backends iterate — the ordered list of instanced draws
+ * that reproduces the fullscreen loop's paint (cel first/under, head last/over). An empty
+ * layer (no arms, no cel) is omitted, never a zero-instance draw.
+ */
+export declare function planRibbonLayers(input: RibbonPlanInput): RibbonLayer[];
+/**
+ * The unit quad as a 4-vertex TRIANGLE_STRIP for the WebGL2 instanced draw — corners
+ * (0,0)(1,0)(0,1)(1,1) in `[0,1]²`; the instanced vertex expands each corner to the
+ * per-instance capsule (a→b padded) or AABB (ring / head halo) bbox. The WGPU render pass
+ * builds the SAME quad from `vertex_index` in-shader (a 6-vertex two-triangle list), so it
+ * consumes only {@link planRibbonLayers}, never this buffer.
+ */
+export declare const RIBBON_QUAD_STRIP: Float32Array<ArrayBuffer>;
+export declare const RIBBON_QUAD_STRIP_VERTS = 4;
+/** Floats per ribbon instance in the WebGL2 attribute buffer: `aSeg`(vec4) + `aData`(vec4). */
+export declare const RIBBON_INSTANCE_FLOATS = 8;

package/dist/components/handmark/composables/useHandMark.d.ts

@@ -0,0 +1,99 @@
+/**
+ * useHandMark.ts — the headless reactive core (L2/L3/L4; SPEC §9).
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Sits between the props and the SFC template so a future React/web-component skin
+ * reuses L1–L4. It orchestrates: resolve brush → shapeGeom → ink → animation. It
+ * owns NO DOM (the SFC anchors/measures/mounts the filter); it owns the reactive
+ * pipeline + the draw-on / boil state machine.
+ *
+ * Two draw-on mechanisms, picked by a FIELD (never an instrument `if`):
+ *   - clean ink (no grain): `stroke-dashoffset` on `pathLength="1"` — the slides
+ *     recipe, geometry-agnostic, compositor-cheap, no filter to re-raster.
+ *   - grained ink (crayon): a `clip-path: inset()` WIPE — the filter rasters ONCE
+ *     and the reveal mutates only the clip (`ds-crayon-handmark §5.1`). NEVER
+ *     dashoffset under a filter (it would re-raster the graph per frame — the Δ4
+ *     gate).
+ *
+ * PRM: every draw-on collapses to instant (finished static state); boil no-ops
+ * (`useLineBoil.start()` early-returns under reduced motion).
+ */
+import { type Ref } from "vue";
+import { type Brush, type BrushName } from "../brush";
+/**
+ * The boil clock surface the SFC binds — the `useLineBoil` return shape, declared
+ * structurally over glass-ui's OWN `Ref` (pencil-boil ships a nested `@vue`, so its
+ * `Ref` symbol differs; the no-op stub is built with this `ref`, hence the surface
+ * is named here rather than `ReturnType<typeof useLineBoil>`).
+ */
+export interface BoilClock {
+    currentFrame: Ref<number>;
+    start: () => void;
+    stop: () => void;
+}
+import { type ShapeGeom } from "../geometry";
+import { type SVGFragment } from "../ink";
+import type { HandAnimation, HandMarkProps, HandShape, MarkBox } from "../types";
+export interface UseHandMarkInput {
+    brush: BrushName | Partial<Brush>;
+    shape: HandShape;
+    color: string;
+    seed: number;
+    overrides?: Partial<Brush>;
+    animation: HandAnimation;
+    boilFps: number;
+    boilFrames: number;
+    roughness: number | null;
+    segments: number | null;
+    jagged: boolean;
+    /** NATURAL underline morphology (C-2) — procedural off the house-seeded engine. */
+    natural: boolean;
+    /** NATURAL-underline excursion knob (BG.W-HANDMARK-PERFECT (c)); `null` ⇒ derive from brush wobble. */
+    amplitude: number | null;
+    box: MarkBox | null;
+    path: string | null;
+    filterId: string;
+    /**
+     * The MEASURED text baseline as a fraction of the `.hm` box height (text-mode
+     * underline anchor). `null` until the SFC measures it (ResizeObserver +
+     * `document.fonts.ready`) — geometry falls back to the legacy constant for that
+     * one pre-measure frame. Ignored in positioned (`box`) mode.
+     */
+    baselineFrac: number | null;
+    /**
+     * The aspect-correct marking-space HEIGHT (BG.W-HANDMARK-PERFECT (a)) — `VB_W /
+     * boxAspect` from the SFC-measured `.hm` box px-aspect, so `preserveAspectRatio="none"`
+     * scales the text-mode wobble SHAPE uniformly (the humps stop crushing flat on a short
+     * word). Defaults to `VB_H`; used ONLY for the measured text-mode marks (the positioned/
+     * box path keeps `VB_H` byte-for-byte).
+     */
+    vbH: number;
+}
+/**
+ * Normalise raw HandMarkProps (with their defaults applied) into the core input.
+ * `baselineFrac` is the SFC's MEASURED text baseline (text-mode underline anchor) —
+ * passed in (not a prop) because it is a runtime measurement, `null` until measured.
+ */
+export declare function normalizeProps(props: HandMarkProps, filterId: string, baselineFrac?: number | null, vbH?: number): UseHandMarkInput;
+export interface HandMarkCore {
+    /** the resolved effective brush vector. */
+    brush: Ref<Brush>;
+    /** the static base geometry (boil re-perturbs THIS). */
+    baseGeom: Ref<ShapeGeom>;
+    /** the live SVG fragment (paths + filter defs). */
+    fragment: Ref<SVGFragment>;
+    /** the live `d` (escape-hatch path > boiled geometry > static base). */
+    pathD: Ref<string>;
+    /** does the brush emit a grain filter? (drives the draw-on mechanism). */
+    grained: Ref<boolean>;
+    /** the draw-on mechanism for this mark: dashoffset (pen) | clip (crayon). */
+    drawKind: Ref<"dashoffset" | "clip">;
+    /** does this animation draw on at all? */
+    draws: Ref<boolean>;
+    /** does this animation boil? */
+    boils: Ref<boolean>;
+    /** the boil clock (a real `useLineBoil` only when the mark boils; else a no-op stub). */
+    boil: BoilClock;
+    /** arm/disarm boil (draw-then-boil holds it until the draw finishes). */
+    boilArmed: Ref<boolean>;
+}
+export declare function useHandMark(input: Ref<UseHandMarkInput>): HandMarkCore;