@mkbabb/glass-ui 5.0.0 → 7.0.0

package/dist/components/aurora/composables/atoms.d.ts

@@ -1,5 +1,5 @@
 /**
- * AX.W10 — the aurora "atoms of control" door: the ONE consumer-facing surface
+ * Aurora's atoms-of-control door: the one consumer-facing surface
  * over the ~28-field author schema. `AuroraConfig` is the INTERNAL author schema
  * (the full escape hatch a preset author types against); `resolveAtoms` is the
  * SIMPLIFIED door the live config UI + every consumer drives.
@@ -12,7 +12,7 @@
  * saturation + valueVariance + breath + the warm/cool temperature, because moving any
  * one alone reads as a defect).
  *
- * Contract (machine-asserted by proof:aurora-atoms-roundtrip):
+ * Contract:
  *   - TOTAL — every atom combination (incl. out-of-range/adversarial inputs) produces
  *     a VALID in-range `AuroraConfig` respecting every `budget.ts` cap (no NaN, no
  *     out-of-range field). Clamp/saturate, never garbage.
@@ -25,8 +25,7 @@
  */
 import { type AuroraConfig, type AuroraMedium, type OklchStop } from "../constants/presets";
 import { type AuroraHarmony } from "./color";
-/** The motion atom — the three motion registers. */
-export type AuroraMotionAtom = "still" | "breathing" | "drifting";
+import { type AuroraMotionAtom, type AuroraZoneArrangement } from "./atoms-fields";
 /**
  * The ZONES arrangement character — selects the nuclei placement prior. NOT a bare
  * integer count: the same count reads as a different field per arrangement.
@@ -34,7 +33,6 @@ export type AuroraMotionAtom = "still" | "breathing" | "drifting";
  * - `composed`  — the rule-of-thirds prior (the deliberate, balanced field).
  * - `centred`   — a tight central cluster (one dominant glow, calm).
  */
-export type AuroraZoneArrangement = "scattered" | "composed" | "centred";
 /** The ZONES atom — a count + an arrangement character (default `composed`). */
 export interface AuroraZones {
     /** 1..MAX_NUCLEI — the number of color zones (nuclei). Clamped. */
@@ -55,38 +53,42 @@ export type AuroraMediumAtom = {
     amount?: number;
 };
 /**
- * The interactivity atom — ONLY the wired axes ship. `light` (cursor-as-light) and
- * `scroll` (scroll-coupled palette/breath) are wired downstream
- * (`frameLoop.ts`/`useAurora.ts`); the declared-but-unwired `flow`/`wake` axes are
- * EXCISED from the shipped atom shape (no declared-but-dead axis — excise-or-wire).
+ * The interactivity atom exposes only wired axes. `light` (cursor-as-light) and
+ * `scroll` (scroll-coupled palette/breath) are wired by
+ * `frameLoop.ts` and `useAurora.ts`.
  */
-export interface AuroraInteractivityAtom {
-    /** cursor drives the impasto light direction (cursor-as-light + idle orbit). */
-    light?: boolean;
+export interface AuroraFieldInteractivityAtom {
     /** palette/breath progress couples to scroll (via useScrollProgress). */
     scroll?: boolean;
     /**
-     * BI.W-FIELD-CORE (FC6/T-38) — the cursor SWIRL/luminance-lean axis, MEDIUM-GATED. On the
+     * Cursor swirl/luminance-lean axis, medium-gated. On the
      * `smooth` medium the cursor reads as a local LUMINANCE LEAN (engagement-driven, via the
-     * `auroraCursorMapping` strength → `uCursorStrength`, ZERO shader edit) instead of the dead
-     * impasto light the `light` axis drives ONLY on the painterly mediums — the T-38 "the
-     * swirl/burst axes are perceptually DEAD on the smooth medium" fix. Default coupled to
-     * `light` when unset (an interactive config reads on EVERY medium, not just painterly).
+     * `auroraCursorMapping` strength → `uCursorStrength`) instead of the dead
+     * impasto light the `light` axis drives only on painterly media. It defaults to
+     * the interactive state so every medium responds.
      */
     swirl?: boolean;
     /**
-     * BI.W-FIELD-CORE (FC6) — the SIZED amplitude atom (0..1, default 0.5). Sizes the cursor's
-     * field influence — how much the velocity BURST perturbs the domain-warp path near the
-     * cursor (routed through the existing `uCursorBurst`/`uWarp*` uniforms — no shader edit).
+     * Sized amplitude atom (0..1, default 0.5). Sizes the cursor's
+     * field influence — how much the velocity burst lifts the CPU-projected cursor strength.
      */
     amplitude?: number;
 }
+/** Smooth fields expose the cursor field but have no directional impasto light. */
+export interface AuroraSmoothInteractivityAtom extends AuroraFieldInteractivityAtom {
+    light?: never;
+}
+/** Textured media may additionally steer their directional light from the cursor. */
+export interface AuroraPainterlyInteractivityAtom extends AuroraFieldInteractivityAtom {
+    light?: boolean;
+}
+export type AuroraInteractivityAtom = AuroraSmoothInteractivityAtom | AuroraPainterlyInteractivityAtom;
 /**
  * The Tier-1 atoms of control (≤7) — the user's named control elements. EVERY atom is
  * OPTIONAL; an absent atom keeps the wispy-sky default for the fields it would drive,
  * so `DEFAULT_ATOMS` (the empty set) resolves to `DEFAULT_AURORA_CONFIG`.
  */
-export interface AuroraAtoms {
+interface AuroraAtomsBase {
     /** A seed color (CSS string or an OklchStop anchor) → drives the derived palette. */
     seed?: string | OklchStop;
     /** The hue scheme across the derived ramp. Default `analogous` (when a seed is set). */
@@ -99,31 +101,31 @@ export interface AuroraAtoms {
      */
     colorEnergy?: number;
     /**
-     * BI.W-AURORA-VIBRANCY (GAP-L2) — the lightness SCHEME of the derived ramp. `"light"`
+     * the lightness SCHEME of the derived ramp. `"light"`
      * (the default when a seed is set) is the light-pastel band; `"dark"` shifts the WHOLE
      * ramp into the luminous-dark band [0.18, 0.42] so a derived-from-seed field reads as a
      * rich luminous-dark wash behind glass in a dark shell — never a washed-pale salmon
-     * field with dark cards floating on it (the O-26 dark-leg defect). CONFIG-LEVEL: routes
+     * field with dark cards floating on it (the dark-leg defect). CONFIG-LEVEL: routes
      * to `deriveAurora`'s `scheme`; ZERO shader edit. Only read when a `seed` is set (the
      * door drives the DERIVE path; an authored-palette config has no scheme to resolve).
      */
     lightnessScheme?: "light" | "dark";
     /**
-     * BI.W-AURORA-VIBRANCY (GAP-L2) — an explicit derived L band `[min, max]` (OKLCh L
+     * an explicit derived L band `[min, max]` (OKLCh L
      * units) that OVERRIDES `lightnessScheme`. The single retune knob for a bespoke
      * luminosity window (e.g. `[0.18, 0.42]` for the deep luminous-dark identity). Routes
      * to `deriveAurora`'s `lBand`; only read when a `seed` is set.
      */
     lBand?: readonly [number, number];
     /**
-     * BI.W-AURORA-VIBRANCY (GAP-L2) — the analogous hue-walk width (degrees). Optional;
+     * the analogous hue-walk width (degrees). Optional;
      * omitted = the chroma-ADAPTIVE default (a higher `colorEnergy` widens the walk so a
      * vivid field carries a real second accent hue, a calm field stays a tight
      * neighbourhood). An explicit value wins. Only read when a `seed` is set.
      */
     hueSpread?: number;
     /**
-     * BI.W-AURORA-VIBRANCY (GAP-L2) — the cross-stop chroma VARIANCE (0..1, the T-26
+     * the cross-stop chroma VARIANCE (0..1, the
      * bracket grammar). 0 (default) = the uniform painterly ramp (every stop near the
      * anchor chroma); 1 = a WIDE bracket — the vivid stops toward marigold, the calm stops
      * toward the sage-whisper pole (C≈0.03), so the ramp carries an "interesting" chroma
@@ -132,9 +134,9 @@ export interface AuroraAtoms {
      */
     chromaVariance?: number;
     /**
-     * BI.W-AURORA-VIBRANCY (GAP-L2) — the counterpoint option. When true (and
+     * the counterpoint option. When true (and
      * `chromaVariance > 0`) the deepest ramp stop is pinned to the sage-whisper pole as a
-     * deliberate low-chroma "silence" note against the vivid mass (the T-26 "silence ←
+     * deliberate low-chroma "silence" note against the vivid mass (the "silence ←
      * whisper → marigold" grammar). Default false (the variance spreads without a dedicated
      * whisper stop). Only read when a `seed` is set.
      */
@@ -148,51 +150,51 @@ export interface AuroraAtoms {
      * clean isotropic zones, 1 = turbulent organic edges.
      */
     noise?: number;
-    /** The painterly medium + (textured mediums only) its dominant texture amount. */
-    medium?: AuroraMediumAtom;
     /** still | breathing | drifting — the three motion registers. */
     motion?: AuroraMotionAtom;
-    /** The pointer/scroll interactivity axes (default OFF). Only `light`/`scroll` ship. */
-    interactivity?: AuroraInteractivityAtom;
 }
+/**
+ * The medium-discriminated atoms surface. Smooth fields retain swirl/scroll/amplitude but
+ * reject the directional `light` axis; textured media expose it explicitly.
+ */
+export type AuroraAtoms = AuroraAtomsBase & ({
+    medium?: {
+        kind: "smooth";
+    };
+    interactivity?: AuroraSmoothInteractivityAtom;
+} | {
+    medium: {
+        kind: Exclude<AuroraMedium, "smooth">;
+        amount?: number;
+    };
+    interactivity?: AuroraPainterlyInteractivityAtom;
+});
 /**
  * The default atoms — the EMPTY set. `resolveAtoms(DEFAULT_ATOMS)` deep-equals the
  * wispy-sky `DEFAULT_AURORA_CONFIG` (machine-asserted). The user explicitly asked the
  * default to be preserved; the empty-atom pass-through is how the door honors it.
  */
 export declare const DEFAULT_ATOMS: AuroraAtoms;
-/**
- * The deterministic nuclei prior for `count` zones under an `arrangement` character.
- * ONE home for the rule-of-thirds prior (the AW duplicated prior pair is gone). Total:
- * clamps `count` to `[1, MAX_NUCLEI]`; every arrangement yields a valid in-range nuclei
- * array.
- *
- * - `composed`  — the rule-of-thirds anchor table (the deliberate balanced field).
- * - `scattered` — a golden-angle (φ⁻¹) low-discrepancy spread off-centre (loose).
- * - `centred`   — a tight cluster around the centre (one dominant glow).
- */
-export declare function nucleiPrior(count: number, arrangement?: AuroraZoneArrangement): AuroraConfig["nuclei"];
 /**
  * Expand the ≤7 Tier-1 atoms into a full, valid, in-range `AuroraConfig`. A PURE,
  * TOTAL function: clones the BASE config and applies ONLY the present atoms as clamped
  * overrides, so the empty atom set resolves to exactly the base and every atom
  * combination yields a config respecting every `budget.ts` cap.
  *
- * `base` defaults to the wispy-sky `DEFAULT_AURORA_CONFIG` (so `resolveAtoms(DEFAULT_ATOMS)`
- * deep-equals it — the machine-asserted default-preserving contract). A consumer that
+ * `base` defaults to the wispy-sky `DEFAULT_AURORA_CONFIG`, so
+ * `resolveAtoms(DEFAULT_ATOMS)` deep-equals it. A consumer that
  * REFINES a richer config (the live atoms studio seeding FROM the active preset) passes the
  * preset config as `base`, so the ~21 non-atom fields the ≤7-knob projection does NOT carry
  * (the hero's stroke params, the per-preset palette specifics beyond the seed) SURVIVE the
- * atom touch — the first atom edit refines the preset rather than clobbering it to the
- * wispy-sky default (the W-AUR-STUDIO D4 atoms-trap fix).
+ * atom touch: the first edit refines the active preset rather than replacing it.
  */
 export declare function resolveAtoms(atoms?: AuroraAtoms, base?: AuroraConfig): AuroraConfig;
 /**
  * Project a full `AuroraConfig` back onto the ≤7 Tier-1 atoms. The minimal recovered
- * set is seed / colorEnergy / zones-count / noise / medium(+amount) / motion; `harmony`
+ * set is seed, colorEnergy, zones-count, noise, medium(+amount), motion; `harmony`
  * and `zones.arrangement` take their door defaults (not recoverable — lossy by design).
  * `configToAtoms(resolveAtoms(a))` recovers the energy/noise/medium/motion/zone-count
- * axes of `a` within the projection's resolution (the round-trip the seed-from-preset
- * fix needs + the gate asserts).
+ * axes of `a` within the projection's resolution.
  */
 export declare function configToAtoms(cfg: AuroraConfig): AuroraAtoms;
+export {};

package/dist/components/aurora/composables/auroraFallbackGround.d.ts

@@ -1,14 +1,14 @@
 /**
- * Aurora luminance-faithful fallback ground (BB.W-AURORA-SWRASTER).
+ * Aurora luminance-faithful fallback ground.
  *
- * The headless / software-raster substrate cannot run the live WebGL field, but
- * speedtest's CI/witness harness must still certify text-on-aurora AA contrast
+ * The headless, software-raster substrate cannot run the live WebGL field, but
+ * a consumer's CI/witness harness must still certify text-on-aurora AA contrast
  * floors HEADLESS (no `--use-gl=angle`). The flat `paletteToCssGradient`
  * placeholder (`color.ts`) is a deliberate "visually-adjacent approximation" — a
  * gamma-sRGB-stop `linear-gradient(135deg, …)` band whose MEAN luminance and
  * SPATIAL distribution both diverge from the shader's nuclei-field composite, so a
  * contrast capture against it certifies the WRONG floor. This module REPLACES it,
- * in the software-raster / capture substrate, with a FIELD-SAMPLED ground derived
+ * in the software-raster, capture substrate, with a FIELD-SAMPLED ground derived
  * from the SAME inputs the shader uploads (the palette stops + the nuclei field),
  * matching the composite's mean + per-quadrant luminance within the certify band.
  *
@@ -17,7 +17,7 @@
  * `nucleiField` (the softmax-Gaussian over the nuclei → paletteId + valueMod) +
  * `samplePalette` (the linear-sRGB LUT lerp of the CPU-baked endpoints) + the
  * `valueVariance` modulation + the Khronos PBR-Neutral tonemap (`tonemap.glsl.ts`'s
- * `aces()`) + the mandatory `linearToSrgb` OETF (`proof:aurora-space-gamma`). The
+ * `aces()`) + the mandatory `linearToSrgb` OETF. The
  * palette LUT is `oklchToLinear` (the SAME value.js Ottosson bake `flattenPalette`
  * feeds the GPU) — ONE color source, no re-implemented OKLCh math. The
  * between-endpoint interpolation runs in LINEAR (the linear-baked endpoints the
@@ -31,20 +31,20 @@
  * bilinear, which preserves the per-quadrant MEAN luminance) — so the painted ground
  * reproduces the composite's SPATIAL luminance, not a partial-alpha approximation. It
  * paints once at mount and parks (no rAF, zero ongoing GPU). When no `document` is
- * available (SSR / happy-dom) it degrades to a deterministic pure-CSS layered
+ * available (SSR, happy-dom) it degrades to a deterministic pure-CSS layered
  * `radial-gradient` stack (zero canvas) — the same field samples, the SSR-safe form.
  * The luminance metrics (mean + the 4-quadrant relative luminance) are returned
- * alongside so the gate / π can MEASURE the faithfulness claim rather than assert it.
+ * alongside so the gate, π can MEASURE the faithfulness claim rather than assert it.
  */
 import type { AuroraConfig, AuroraNucleus } from "../constants/presets";
 /** A linear-sRGB triple in [0,1]. */
 type Lin = [number, number, number];
-/** Linear-sRGB relative luminance (Rec.709 / WCAG), the contrast-floor metric. */
+/** Linear-sRGB relative luminance (Rec.709, WCAG), the contrast-floor metric. */
 export declare function relativeLuminance([r, g, b]: Lin): number;
 /**
  * The static (t=0) nuclei field at normalized `(x, y)` — mirrors
  * `composition.glsl.ts`'s `nucleiField`. At t=0 the drift orbit term vanishes
- * (cos 0 / sin 0 → the nucleus sits at its authored position), so the field is a
+ * (cos 0, sin 0 → the nucleus sits at its authored position), so the field is a
  * pure softmax-Gaussian over the static nuclei: `w_i = exp(-β·d2_i/r_i²)`,
  * `paletteId = Σ(w_i·bias_i)/Σw_i`, `valueMod = Σ(w_i·vbias_i)/Σw_i`. The
  * anisotropic-ellipse local-frame rotation (elongation + angle) is reproduced.
@@ -64,12 +64,12 @@ export declare function nucleiFieldStatic(nuclei: readonly AuroraNucleus[], soft
  * Sample the aurora's STATIC composite at normalized `(x, y)` → a gamma-sRGB
  * `[r,g,b]` in [0,1]. The full CPU mirror of the shader main() output transfer:
  * field → linear palette LUT → valueVariance modulation → PBR-Neutral tonemap →
- * the `clamp(col*0.985 + 0.008)` toe → the `linearToSrgb` OETF. The drift / breath
- * / cursor / medium-texture terms are STATIC (t=0, no cursor, the atmospheric
+ * the `clamp(col*0.985 + 0.008)` toe → the `linearToSrgb` OETF. The drift, breath
+ *, cursor, medium-texture terms are STATIC (t=0, no cursor, the atmospheric
  * smooth pole) — the luminance ground the certify reads, not the live animation.
  */
 export declare function sampleAuroraField(config: AuroraConfig, x: number, y: number): Lin;
-/** The luminance metrics the gate / π MEASURES the faithfulness against. */
+/** The luminance metrics the gate, π MEASURES the faithfulness against. */
 export interface AuroraGroundMetrics {
     /** Mean relative luminance over the sample grid (gamma → relative-luminance). */
     mean: number;
@@ -92,7 +92,7 @@ export interface AuroraFallbackGround {
  * Build the luminance-faithful CSS fallback ground for an aurora config.
  *
  * Samples the static field at a `grid × grid` lattice (the SAME `sampleAuroraField`
- * the gate / π measures), emits a stack of soft `radial-gradient` layers — one per
+ * the gate, π measures), emits a stack of soft `radial-gradient` layers — one per
  * sample cell, centred on the cell, fading to transparent at ~the cell radius — over
  * a base fill at the FIELD-MEAN color. The base fill anchors the global luminance;
  * the radial layers paint the spatial nuclei-glow distribution, so the ground reads

package/dist/components/aurora/composables/auroraImageSource.d.ts

@@ -1,7 +1,7 @@
 /**
- * Aurora image-source coordination seam (BG.W-AUR-IMAGE-SOURCE).
+ * Aurora image-source coordination seam.
  *
- * The `source:"image"` decode + upload state machine, carved out of `runtime.ts` (the
+ * The `source:"image"` decode + upload state machine (the
  * no-god-module bound; the same colocation seam `glSetup`/`wgpuSetup` carry). It owns:
  *   - the ONE decode (through the shared `resolveImageSource` normalisation), de-duped on
  *     the same `src` so an `update()` burst never re-decodes;
@@ -13,13 +13,12 @@
  *     cross-engine parity floor), seeds the placeholder + any already-decoded photo, and
  *     returns a teardown.
  *
- * The runtime COMPOSES this leaf; the gate `proof:aur-image` reads it as the WebGL2
- * routing-through-the-primitive witness (the reader-follows-the-carve precedent).
+ * The runtime composes this leaf as the WebGL2 image-source path.
  */
 import { type UploadableImageSource } from "../../../composables/glass/textureUpload";
 import type { AuroraConfig } from "../constants/presets";
 export interface AuroraImageCoordinator {
-    /** The decoded photo (or null before decode / on a palette config). */
+    /** The decoded photo (or null before decode, on a palette config). */
     getDecodedImage(): UploadableImageSource | null;
     /**
      * Register the active backend's texture uploader; passing `null` clears it (teardown).

package/dist/components/aurora/composables/color.d.ts

@@ -12,7 +12,7 @@ export declare function flattenPalette(stops: OklchStop[], maxStops?: number, ou
 /**
  * Derive a cheap CSS `linear-gradient` from an Aurora palette — the static
  * first-frame placeholder painted under the WebGL canvas while the runtime
- * arms (see `useAurora`'s deferred init / Aurora.vue's placeholder element).
+ * arms (see `useAurora`'s deferred init, Aurora.vue's placeholder element).
  *
  * The shader interpolates the same OKLCh stops in linear sRGB; here we render
  * each stop as a gamma-sRGB hex so the browser's gradient compositor produces
@@ -27,16 +27,14 @@ export declare function paletteToCssGradient(stops: OklchStop[]): string;
 export declare function hexToOklchStop(hex: string): OklchStop;
 /**
  * Harmony schemes for {@link deriveAurora} — the PUBLIC alias of the shared
- * `ColorHarmony` vocabulary hoisted to the `/color` leaf (AW.W11.b). The blob and
+ * `ColorHarmony` vocabulary hoisted to the `/color` leaf (.b). The blob and
  * aurora derive from this ONE union; aurora keeps the `AuroraHarmony` name for
  * surface preservation. See `ColorHarmony` for the per-scheme semantics.
  */
 export type AuroraHarmony = ColorHarmony;
 /**
- * Eased L/C journey shapes for the derived ramp. `bell` (the W5 default for chroma)
- * peaks the chroma in the mids and desaturates the extremes — the painterly
- * "saturated body, calm edges" curve. `linear` is the prior monotone falloff
- * (the named pre-W5 branch — NOT a back-compat alias, a first-class choice).
+ * Eased L/C journey shapes for the derived ramp. `bell` peaks chroma in the
+ * middle and calms both extremes; `linear` provides a monotone falloff.
  */
 export type DeriveEasing = "linear" | "sine" | "bell";
 export interface DeriveAuroraOptions {
@@ -52,33 +50,30 @@ export interface DeriveAuroraOptions {
     hueSpread?: number;
     /** L-ramp easing across the band. Default `linear` (monotone ascent). */
     lightnessEasing?: DeriveEasing;
-    /** C-ramp easing. Default `bell` (peak in the mids — the W5 painterly default). */
+    /** C-ramp easing. `bell` peaks in the middle. Default `bell`. */
     chromaEasing?: DeriveEasing;
     /**
-     * Warm-light / cool-shadow temperature coupling (0..1). A hue delta that warms
+     * Warm-light, cool-shadow temperature coupling (0..1). A hue delta that warms
      * the lights and cools the shadows — the single most-cited painting rule, the
      * fold that makes the oil/oil-pastel mediums read as mixed paint. Default 0.
      */
     temperatureShift?: number;
     /**
-     * BC.W-VIZ-AURORA (A7) — the additive DERIVE-path hue-EXCLUSION axis (the
-     * speedtest-AX cross-repo fold). Named OKLCh hue bands (each `[startDeg, endDeg]`,
+     * Additive derive-path hue exclusions. Named OKLCh hue bands (each `[startDeg, endDeg]`,
      * wrap-around supported via `start > end`) that EVERY derived stop's hue must fall
      * OUTSIDE. The mechanism that makes "teal-on-navy is GONE" enforceable in the DERIVE
      * path, not just the static default — a consumer deriving a palette FROM any seed
      * can never re-introduce a purged band (e.g. `avoidHues: [[170, 200]]` excludes the
      * teal arc by construction). The exclusion RE-ROUTES the walked hue to the nearest
      * band EDGE (preserving L/C — no chroma flatten); it is NOT a post-hoc desaturate.
-     * Additive + default-unset → byte-identical derive (the `WarpMode`-additive-widen
-     * precedent: `proof:aurora-atoms-roundtrip` stays GREEN by construction).
+     * Leaving it unset preserves the ordinary derivation.
      */
     avoidHues?: readonly (readonly [number, number])[];
     /**
-     * BG.W-AUR-IMAGE-SOURCE (ASK-GU-AURORA-SCHEME-LUMA) — the luminance SCHEME preset. A
+     * The luminance scheme preset. A
      * derived palette's L band anchors the whole ramp's luminosity; the default
      * `"light"` band ([0.35, 0.95]) reads as a light-pastel field, which composites to a
-     * flat gray behind glass in a DARK app shell (the same luminous-dark identity concern
-     * `W-DARK-MATERIAL` owns). `"dark"` shifts the band toward the luminous-dark identity
+     * flat gray behind glass in a dark app shell. `"dark"` shifts the band toward the luminous-dark identity
      * (`DERIVE_L_BAND_DARK`, a deeper base + a lower apex) so a derived-from-seed field
      * reads as a rich luminous-dark wash, not a washed-pale composite. Additive +
      * default-unset → byte-identical derive (the `WarpMode`-additive-widen precedent).
@@ -86,7 +81,7 @@ export interface DeriveAuroraOptions {
      */
     scheme?: "light" | "dark";
     /**
-     * BG.W-AUR-IMAGE-SOURCE — an explicit L band `[min, max]` (OKLCh L units) that OVERRIDES
+     * an explicit L band `[min, max]` (OKLCh L units) that OVERRIDES
      * both the default band AND `scheme`. The single retune knob for a consumer whose
      * derived field needs a bespoke luminosity window. Clamped into [0, 1] defensively.
      */
@@ -95,13 +90,13 @@ export interface DeriveAuroraOptions {
 /**
  * Seed ONE color into a harmonious, gamut-safe N-stop aurora palette.
  *
- * A thin COMPOSING producer over the shipped value.js Ottosson core (inv J-10:
- * no color math is re-implemented here). The seed's `{L,C,h}` is the anchor; the
+ * A thin COMPOSING producer over the shipped value.js Ottosson core
+ * (no color math is re-implemented here). The seed's `{L,C,h}` is the anchor; the
  * ramp spreads L across a painterly band, falls C off toward the pale apex, and
  * walks the hue per `harmony`. EVERY derived stop is gamut-mapped through
- * value.js's `gamutMapOKLab` so none falls outside sRGB.
+ * value.js's `mapColorToGamut` so none falls outside sRGB.
  *
- * Deterministic and DOM-free (SSR / happy-dom safe — `cssToOklch` is the only
+ * Deterministic and DOM-free (SSR, happy-dom safe — `cssToOklch` is the only
  * string path and it parses via value.js, not a canvas). The returned length is
  * clamped to `[2, MAX_STOPS]`; L is monotonic ascending across the ramp.
  *

package/dist/components/aurora/composables/frameLoop.d.ts

@@ -1,38 +1,40 @@
 /**
  * Aurora frame loop — the per-frame draw + the render-demand gate.
  *
- * BI.W-FIELD-CORE — the retired `cursorModel.ts` is GONE. The cursor is now the mapped
+ * the retired `cursorModel.ts` is GONE. The cursor is now the mapped
  * readout of the SHARED `usePointerVelocityField` (`auroraCursorMapping`): the mass-spring
  * attractor is the cursor position, `engagement · strength` the attraction (so the
- * cursor-local luminance lean reads on the `smooth` medium, not a dead swirl axis), the
- * derived velocity + flick burst pass onto the EXISTING `uCursor*` uniforms (ZERO shader
- * edit). The field is FED `tick(deltaMs)` from THIS loop (the one-loop discipline — no own
+ * cursor-local luminance lean reads on the `smooth` medium, not a dead swirl axis), with
+ * the derived burst folded into that strength on the CPU. The field is FED `tick(deltaMs)`
+ * from THIS loop (the one-loop discipline — no own
  * rAF) and FREEZES under PRM via the MASTER TEMPO SCALAR (`tick(0)`).
  *
  * `drawFrame` re-sends the per-frame cursor + time uniforms and issues the single
  * full-screen-triangle draw. `needsAnimation` is the demand gate: `false` under
  * reduced-motion (the static frame draws once, then parks), `false` at steady-state (all
  * four drift uniforms 0 AND the field settled — the next frame is pixel-identical), and
- * `true` while drift is live or the field is still easing (engagement / speed / burst /
+ * `true` while drift is live or the field is still easing (engagement, speed, burst,
  * attractor motion above ε).
  */
 import type { UniformLocations } from "./glSetup";
 import type { AuroraCursorUniforms } from "./uniformBridge";
 import type { AuroraConfig } from "../constants/presets";
-import type { UsePointerVelocityField } from "../../../composables/motion/usePointerVelocityField";
+import type { UsePointerVelocityField } from "../../../composables/motion/pointer/usePointerVelocityField";
 /** The at-rest scalars a config-less cursor read seeds (strength ceiling + influence radius). */
 export interface AuroraCursorScalars {
     /** The active-strength ceiling (cfg.strength; scaled by engagement). */
     strength: number;
     /** The influence radius (0.05..0.5). */
     radius: number;
+    /** The bounded contribution of the pointer-field burst. */
+    amplitude: number;
 }
 export interface FrameLoopDeps {
     gl: WebGL2RenderingContext;
     prog: WebGLProgram;
     uniforms: UniformLocations;
     /**
-     * BI.W-FIELD-CORE — the shared viz-pointer-physics field (the ONE cursor source). FED
+     * the shared viz-pointer-physics field (the ONE cursor source). FED
      * `tick(deltaMs)` from THIS callback (the one-loop discipline — no own rAF). The
      * `auroraCursorMapping` projects its readout onto the `uCursor*` uniforms.
      */
@@ -43,6 +45,8 @@ export interface FrameLoopDeps {
     getConfig: () => AuroraConfig;
     /** Reduced-motion intent — parks the loop after one static frame. */
     getReducedMotion: () => boolean;
+    /** Resolve shader time without altering the pointer field's real frame delta. */
+    getRenderTime: (elapsedSec: number) => number;
 }
 export interface FrameLoop {
     /** Advance the field THEN draw — the per-frame step. */
@@ -53,14 +57,13 @@ export interface FrameLoop {
 /**
  * Map an ALREADY-TICKED shared pointer field onto the aurora `uCursor*` uniform shape (the
  * ONE cursor projection both backends — WebGL2 frameLoop + WGSL wgpuSetup — share). The
- * `auroraCursorMapping` projects the attractor/engagement/velocity/burst; the iOS-27 gel
- * SNAP-BACK folds a decel over-burst onto the shader's existing burst (tempo-gated so it
- * cannot leak under reduce).
+ * iOS-27 gel snap-back augments the field burst before `auroraCursorMapping` folds it
+ * into strength. Both shader engines consume the resulting four-value cursor shape.
  */
 export declare function mapAuroraCursor(pointerField: UsePointerVelocityField, scalars: AuroraCursorScalars, tempo: number): AuroraCursorUniforms;
 /**
  * The demand-gate liveness over the shared field state (the retired `cursorIsLive` over the
- * field) — engaged / moving / bursting / attractor mid-settle.
+ * field) — engaged, moving, bursting, attractor mid-settle.
  */
 export declare function auroraFieldLive(pointerField: UsePointerVelocityField): boolean;
 export declare function createFrameLoop(deps: FrameLoopDeps): FrameLoop;

package/dist/components/aurora/composables/glSetup.d.ts

@@ -1,6 +1,6 @@
 /**
  * Aurora GL setup seam — shader compile/link + geometry + the uniform location
- * cache. The GL-lifecycle orchestrator (`runtime.ts`) calls `createGlProgram` on a
+ * cache. `createAuroraGLSetup` calls `createGlProgram` on a
  * fresh context (on arm AND on every webglcontextrestored), so a GPU context loss
  * self-heals: each call rebuilds the program + the full-screen triangle + the
  * `UNIFORM_NAMES` location cache against the fresh `gl`.
@@ -9,7 +9,12 @@
  * shader-uniform boundary: a NEW uniform name must be added here, and the cache is
  * keyed off it, so a fresh uniform always gets a location slot.
  */
-export declare const UNIFORM_NAMES: readonly ["uTime", "uPalette", "uStopCount", "uNucleiCount", "uNucleiPos", "uNucleiRadius", "uNucleiPaletteBias", "uNucleiValueBias", "uNucleiDriftRadius", "uNucleiDriftPhase", "uNucleiElong", "uNucleiAngle", "uSoftmaxBeta", "uValueVariance", "uWarpAmount", "uWarpScale", "uWarpDrift", "uWarpMode", "uNoiseOctaves", "uMedium", "uHuePath", "uFlowPattern", "uFlowFocal", "uFlowAngle", "uFlowCurl", "uCursor", "uCursorStrength", "uCursorRadius", "uCursorVelocity", "uCursorBurst", "uStrokeAmount", "uStrokeScale", "uStrokeAnisotropy", "uStrokeLayers", "uStrokeMode", "uStrokeOrient", "uLightDir", "uLightColor", "uWetEdge", "uGranulation", "uImpasto", "uBrokenColor", "uCanvasGrain", "uMetalPolish", "uMetalHeightScale", "uNucleiDrift", "uPaletteDrift", "uBreathDepth", "uBreathPeriod", "uSaturation", "uPaperGrain", "uAlpha", "uVividness", "uImage", "uBlurMin", "uBlurMax", "uImageAspect"];
+import type { WebGLCanvasFrame } from "../../../composables/glass/webgpu/useGpuSubstrate";
+import type { UsePointerVelocityField } from "../../../composables/motion/pointer/usePointerVelocityField";
+import type { AuroraConfig } from "../constants/presets";
+import { type AuroraImageCoordinator } from "./auroraImageSource";
+import { type AuroraCursorScalars } from "./frameLoop";
+export declare const UNIFORM_NAMES: readonly ["uTime", "uPalette", "uStopCount", "uNucleiCount", "uNucleiPos", "uNucleiRadius", "uNucleiPaletteBias", "uNucleiValueBias", "uNucleiDriftRadius", "uNucleiDriftPhase", "uNucleiElong", "uNucleiAngle", "uSoftmaxBeta", "uValueVariance", "uWarpAmount", "uWarpScale", "uWarpDrift", "uWarpMode", "uNoiseOctaves", "uMedium", "uHuePath", "uFlowPattern", "uFlowFocal", "uFlowAngle", "uFlowCurl", "uCursor", "uCursorStrength", "uCursorRadius", "uStrokeAmount", "uStrokeScale", "uStrokeAnisotropy", "uStrokeLayers", "uStrokeMode", "uStrokeOrient", "uLightDir", "uLightColor", "uWetEdge", "uGranulation", "uImpasto", "uBrokenColor", "uCanvasGrain", "uMetalPolish", "uMetalHeightScale", "uNucleiDrift", "uPaletteDrift", "uBreathDepth", "uBreathPeriod", "uSaturation", "uPaperGrain", "uAlpha", "uVividness", "uImage", "uBlurMin", "uBlurMax", "uImageAspect"];
 export type UniformName = (typeof UNIFORM_NAMES)[number];
 export type UniformLocations = Record<UniformName, WebGLUniformLocation | null>;
 export interface GlProgram {
@@ -27,3 +32,15 @@ export interface GlProgram {
  * the viewport), and resolve the uniform location cache. Leaves the program bound.
  */
 export declare function createGlProgram(gl: WebGL2RenderingContext, vertexSrc: string, fragmentSrc: string): GlProgram;
+export interface AuroraGLSetupDeps {
+    opaquePresentation: boolean;
+    getConfig: () => AuroraConfig;
+    getReducedMotion: () => boolean;
+    getRenderTime: (elapsedSec: number) => number;
+    getCursorScalars: () => AuroraCursorScalars;
+    pointerField: UsePointerVelocityField;
+    imageCoordinator: AuroraImageCoordinator;
+    registerConfigUploader: (upload: ((config: AuroraConfig) => void) | null) => void;
+}
+/** Build the WebGL2 program, uniform bridge, frame loop, and teardown as one setup. */
+export declare function createAuroraGLSetup(deps: AuroraGLSetupDeps): (gl: WebGL2RenderingContext) => WebGLCanvasFrame;