@mkbabb/glass-ui 4.2.0 → 6.0.0

package/dist/components/aurora/Aurora.vue.d.ts

@@ -0,0 +1,110 @@
+import type { AuroraRuntimeOptions } from "./composables/runtime";
+import { type AuroraConfig } from "./constants/presets";
+import { type AuroraRenderMode } from "./constants/renderMode";
+import type { RendererStatus } from "../../composables/glass/webgpu/rendererStatus";
+/**
+ * Aurora — a painterly WebGL2 background.
+ *
+ * Renders into a single canvas sized to its container via ResizeObserver.
+ * Config is reactive; the composable watches it deeply and re-uploads
+ * uniforms on change. Cursor interaction is deliberately not wired here —
+ * use `useCursorInteraction` (or call the exposed `setCursor` API) against
+ * the container element so the consumer controls pointer policy.
+ *
+ * Lazy-arm (HA4 §1): by default the expensive WebGL init (shader compile +
+ * GPU link) is deferred past the consumer's first paint. Until the runtime
+ * arms, a palette-derived GROUND placeholder (`auroraFallbackGround` — the
+ * field-sampled nuclei-glow, BI.W-E10-AURORA-ENTRANCE) paints the first frame
+ * with zero JS / zero GPU; the canvas cross-fades in over it once armed. The
+ * ground is derived from the SAME palette + nuclei the WebGL path uploads, so
+ * FRAME 0 is palette-COLORED (never the retired flat gray band) and the live
+ * canvas WARMS INTO it — a same-palette dissolve with no tone jump (the UF-E10
+ * "no repulsive-gray fade" law). The placeholder stays mounted underneath as
+ * the natural WebGL2-unavailable visual fallback (HA4 §1.5). Capture /
+ * thumbnail-baking consumers pass `runtimeOptions.initStrategy: "eager"` (or
+ * `mode: "capture"`) to arm synchronously.
+ *
+ * Init failures (WebGL2 unavailable, shader compile/link failure) are
+ * library-internal contract violations and surface by default (O invariant
+ * 24): synchronously on the eager path, on the microtask queue on the
+ * deferred path. Pass `onInitError` to handle the error and leave the canvas
+ * unmounted instead — the canonical opt-in path back to silent fallback.
+ *
+ * `opacityCeiling` (A3 §6.R-9, G-AK-D11) is the outer compositing envelope:
+ * `1.0` (default) for hero surfaces, `~0.5` for quiet content-over-aurora
+ * routes where form/text density would otherwise compete with the drift.
+ * It applies uniformly to the placeholder and the canvas so the cross-fade
+ * rides under the clamped ceiling and the shader's per-pixel `alpha`
+ * remains an orthogonal authoring concern.
+ */
+type __VLS_Props = {
+    /**
+     * Aurora field configuration (palette, nuclei, warp, media). Optional —
+     * omit it and the canonical `DEFAULT_AURORA_CONFIG` painterly look
+     * renders (gap 11, AM.W1). Pass a full config to author a custom field,
+     * or a preset object from `./constants/presets`. The default is supplied via a
+     * `withDefaults` factory so each mount gets its own (un-shared) object.
+     */
+    config?: AuroraConfig;
+    runtimeOptions?: AuroraRuntimeOptions;
+    onInitError?: (err: Error) => void;
+    /**
+     * Adaptive render substrate (AM.W1; `aurora-lazy-init §3.1`). Aurora is
+     * NEVER retired — the warm wash always composites; only the substrate
+     * adapts:
+     *   - `"webgl"` — arm the WebGL path (still deferred to idle past first
+     *     paint via the `initStrategy:"deferred"` default).
+     *   - `"css"`   — never arm WebGL; the `auroraFallbackGround` palette-
+     *     derived ground stays the permanent surface (the warm wash
+     *     composites, it just does not animate).
+     *   - `"auto"` (default) — resolves to `"webgl"` on every device EXCEPT a
+     *     detected SOFTWARE renderer (SwiftShader / llvmpipe / MS Basic Render),
+     *     which falls to `"css"` (the page-wedging-software-raster guard, the only
+     *     surviving `"css"` signal). BC.W-VIZ-AURORA (T1) RETIRED the dead-static
+     *     `hardwareConcurrency <= 4` / `saveData` / `reduced-motion` falls: a
+     *     2026-capable low-core / throttled tab no longer gets a frozen gradient
+     *     (the "renders SLOW" defect root), and reduced-motion is handled SOLELY by
+     *     the substrate's live `matchMedia` freeze (one static frame then park,
+     *     re-arms on un-reduce). Resolved once at setup; SSR / missing-API safe
+     *     (assumes capable → `"webgl"` when the probes are unavailable).
+     */
+    renderMode?: AuroraRenderMode;
+    /**
+     * Per-route aurora saturation clamp (A3 §6.R-9 / G-AK-D11).
+     *
+     * The shader's `alpha` config field is per-pixel pigment opacity inside
+     * the painted image. `opacityCeiling` is the *outer envelope* — the
+     * maximum compositing opacity the aurora surface (placeholder +
+     * canvas) is allowed to reach against page content. It applies
+     * uniformly to both layers via the `--aurora-opacity-ceiling` custom
+     * property so the cross-fade preserves the clamped ceiling.
+     *
+     * Defaults to `1.0` (the dial route — full brand register). Quiet
+     * content-over-aurora routes (survey, thankyou, admin-login) opt in
+     * to `0.5` so the drift recedes behind form/text density. Clamped to
+     * `[0, 1]` defensively.
+     */
+    opacityCeiling?: number;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    config: AuroraConfig;
+    canvasRef: import("vue").Ref<HTMLCanvasElement | null, HTMLCanvasElement | null>;
+    setCursor: (x: number, y: number, strength?: number) => void;
+    clearCursor: () => void;
+    setCursorRadius: (r: number) => void;
+    renderAt: (t: number) => void;
+    pause: () => void;
+    resume: () => void;
+    isArmed: Readonly<import("vue").Ref<boolean, boolean>>;
+    rendererStatus: Readonly<import("vue").Ref<RendererStatus, RendererStatus>>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    rendererStatus: (status: RendererStatus) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onRendererStatus?: ((status: RendererStatus) => any) | undefined;
+}>, {
+    config: AuroraConfig;
+    renderMode: AuroraRenderMode;
+    opacityCeiling: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -0,0 +1,43 @@
+import { type AuroraConfig, type AuroraMedium } from "../constants/presets";
+import type { AuroraMotionAtom } from "./atoms";
+/** Linear interpolation over a co-varying axis (the continuous curve, not a LUT). */
+export declare function lerp(a: number, b: number, t: number): number;
+/** The motion atom → the three motion fields. */
+export interface MotionFields {
+    nucleiDrift: number;
+    paletteDrift: number;
+    warpDrift: number;
+    breathDepth: number;
+}
+/** The calm↔vivid poles for each co-varying COLOR-energy axis. */
+export declare const COLOR_ENERGY: {
+    readonly saturation: {
+        readonly calm: 0.85;
+        readonly vivid: 1.2;
+    };
+    readonly valueVariance: {
+        readonly calm: 0.04;
+        readonly vivid: 0.14;
+    };
+    readonly breathDepth: {
+        readonly calm: 0.03;
+        readonly vivid: 0.08;
+    };
+    readonly temperatureShift: {
+        readonly calm: 0.15;
+        readonly vivid: 0.5;
+    };
+    readonly hueSpread: {
+        readonly calm: 16;
+        readonly vivid: 44;
+    };
+};
+export declare const MOTION_FIELDS: Record<AuroraMotionAtom, MotionFields>;
+/** The textured medium → its dominant texture knob. Only reached for a textured medium. */
+export declare function applyTexture(cfg: AuroraConfig, medium: Exclude<AuroraMedium, "smooth">, amount: number): void;
+/** Read back the textured medium's dominant texture amount (the applyTexture inverse). */
+export declare function textureAmountFor(cfg: AuroraConfig, kind: Exclude<AuroraMedium, "smooth">): number;
+/** Classify the motion atom from the config's drift fields (the resolveAtoms forward map). */
+export declare function motionFor(cfg: AuroraConfig): AuroraMotionAtom;
+/** Invert a clamped lerp(calm, vivid, t) back to t∈[0,1] (the energy/noise inverses). */
+export declare function unlerp(value: number, lo: number, hi: number): number;

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

@@ -0,0 +1,198 @@
+/**
+ * AX.W10 — the aurora "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.
+ *
+ * The atoms are the user's named control elements (§2.7) — COLOR, ZONES, NOISE,
+ * MEDIUM(+texture), MOTION — ≤7 intuitive knobs, each normalized and total
+ * (Burley's "Principled" 5-rule discipline: intuitive, few, normalized, robust for
+ * EVERY combination). Each atom maps to a co-varying cluster of config fields so one
+ * knob moves the entangled axes together (a single COLOR-energy knob co-varies
+ * saturation + valueVariance + breath + the warm/cool temperature, because moving any
+ * one alone reads as a defect).
+ *
+ * Contract (machine-asserted by proof:aurora-atoms-roundtrip):
+ *   - 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.
+ *   - DEFAULT-PRESERVING — `resolveAtoms(DEFAULT_ATOMS)` deep-equals
+ *     `DEFAULT_AURORA_CONFIG` (the wispy-sky default survives the door).
+ *
+ * Mechanism: clone `DEFAULT_AURORA_CONFIG` and apply ONLY the atoms that are PRESENT
+ * as clamped overrides. An absent atom keeps the default's value, so the empty atom
+ * set (`DEFAULT_ATOMS`) resolves to exactly the wispy-sky default by construction.
+ */
+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";
+/**
+ * The ZONES arrangement character — selects the nuclei placement prior. NOT a bare
+ * integer count: the same count reads as a different field per arrangement.
+ * - `scattered` — radial-ish spread off the centre (loose, atmospheric).
+ * - `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. */
+    count: number;
+    /** The placement prior. Default `composed` (rule-of-thirds). */
+    arrangement?: AuroraZoneArrangement;
+}
+/**
+ * The MEDIUM atom — the painterly medium + (only for a TEXTURED medium) its dominant
+ * texture amount. `amount` is STRUCTURALLY ABSENT for `smooth`: a smooth medium has
+ * no dominant texture knob, so the door does not offer/accept one (no silent-inert
+ * arm). For a textured medium `amount` (0..1) drives the medium's signature knob.
+ */
+export type AuroraMediumAtom = {
+    kind: "smooth";
+} | {
+    kind: Exclude<AuroraMedium, "smooth">;
+    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).
+ */
+export interface AuroraInteractivityAtom {
+    /** cursor drives the impasto light direction (cursor-as-light + idle orbit). */
+    light?: boolean;
+    /** 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
+     * `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).
+     */
+    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).
+     */
+    amplitude?: number;
+}
+/**
+ * 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 {
+    /** 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). */
+    harmony?: AuroraHarmony;
+    /**
+     * 0..1 — the color ENERGY knob. One scalar co-varies the entangled chroma/value
+     * cluster: saturation, valueVariance, breath, AND the warm-light/cool-shadow
+     * temperature on the derived palette. 0 = calm/muted, 1 = vivid/charged. A
+     * continuous curve, not a 3-point named LUT.
+     */
+    colorEnergy?: number;
+    /**
+     * BI.W-AURORA-VIBRANCY (GAP-L2) — 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
+     * 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
+     * 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;
+     * 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
+     * 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
+     * counterpoint rather than a flat monochrome. Applied post-derive (chroma-only —
+     * hue/L preserved, each stop re-gamut-mapped). Only read when a `seed` is set.
+     */
+    chromaVariance?: number;
+    /**
+     * BI.W-AURORA-VIBRANCY (GAP-L2) — 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 ←
+     * whisper → marigold" grammar). Default false (the variance spreads without a dedicated
+     * whisper stop). Only read when a `seed` is set.
+     */
+    chromaCounterpoint?: boolean;
+    /** The color zones (nuclei) — a count + an arrangement character. */
+    zones?: AuroraZones;
+    /**
+     * 0..1 — the NOISE knob. One scalar fans to the organic-boundary cluster:
+     * warpAmount (how much the zones distort), warpScale (the distortion frequency),
+     * warpMode (smooth fBm → cellular as it climbs), and noiseOctaves (detail). 0 =
+     * 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 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
+ * 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).
+ */
+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`
+ * 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).
+ */
+export declare function configToAtoms(cfg: AuroraConfig): AuroraAtoms;

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

@@ -0,0 +1,44 @@
+/**
+ * Aurora image-source coordination seam (BG.W-AUR-IMAGE-SOURCE).
+ *
+ * The `source:"image"` decode + upload state machine, carved out of `runtime.ts` (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;
+ *   - the backend-registered `imageUploader` (the WebGL2 runtime OR the WebGPU setup
+ *     registers it) — a late-arriving decode flushes into the live GPU texture + wakes the
+ *     parked loop;
+ *   - the WebGL2 image-texture ARM (`armWebGL2ImageTexture`) — it builds the uploader via
+ *     the ONE shared `uploadImageTextureWebGL2` primitive (NEVER a raw `texImage2D` — the
+ *     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).
+ */
+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). */
+    getDecodedImage(): UploadableImageSource | null;
+    /**
+     * Register the active backend's texture uploader; passing `null` clears it (teardown).
+     * Setting a fn immediately flushes any already-decoded photo into the fresh texture.
+     */
+    setImageUploader(fn: ((src: UploadableImageSource) => void) | null): void;
+    /** Kick a decode when the config selects `source:"image"` + supplies a `src`. */
+    ensureDecoded(cfg: AuroraConfig): void;
+}
+export declare function createAuroraImageCoordinator(deps: {
+    /** Re-arm the (possibly parked) render loop after a late decode uploads. */
+    wake: () => void;
+    /** A decode-failure sink (the runtime routes it to `onInitError`). */
+    onError?: (err: Error) => void;
+}): AuroraImageCoordinator;
+/**
+ * Arm the WebGL2 image texture (unit 0) for a live program. Routes EVERY texture creation
+ * through the ONE shared primitive; seeds the neutral placeholder so the sampler is always
+ * complete, then any already-decoded photo; registers the uploader so a later decode
+ * re-uploads live. Returns a teardown that deletes the texture + un-registers the uploader.
+ */
+export declare function armWebGL2ImageTexture(gl: WebGL2RenderingContext, prog: WebGLProgram, coord: AuroraImageCoordinator): () => void;

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

@@ -0,0 +1,111 @@
+import { type ColorHarmony, type OklchStop } from "../../../composables/color";
+export { cssToOklch, oklchStopToHex, oklchToLinear, gamutMapStop, } from "../../../composables/color";
+export type { OklchStop } from "../../../composables/color";
+export type { ColorHarmony } from "../../../composables/color";
+/**
+ * Pack up to `maxStops` OklchStops into linear-sRGB triples. When `out` is
+ * provided the buffer is filled in place (no allocation) — the runtime owns a
+ * single buffer reused on every config update so a slider drag does not churn
+ * the GC. Unused slots are zero-filled; the shader clamps via `uStopCount`.
+ */
+export declare function flattenPalette(stops: OklchStop[], maxStops?: number, out?: Float32Array): Float32Array;
+/**
+ * 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).
+ *
+ * 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
+ * a visually-adjacent approximation with zero JS and zero GPU on first paint.
+ * A diagonal axis (135deg) reads as atmospheric depth rather than a flat band.
+ *
+ * Single-stop palettes degrade to a flat fill; an empty palette yields
+ * `transparent` so the placeholder is simply invisible (the canvas still
+ * fades in over it once armed).
+ */
+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
+ * 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).
+ */
+export type DeriveEasing = "linear" | "sine" | "bell";
+export interface DeriveAuroraOptions {
+    /** Number of stops to produce. Default 4; clamped to [2, MAX_STOPS]. */
+    stopCount?: number;
+    /** Hue scheme across the ramp. Default "analogous". */
+    harmony?: AuroraHarmony;
+    /** Total L travel across the ramp, in OKLCh L units. Default ~0.32. */
+    lightnessSpread?: number;
+    /** C multiplier at the pale apex (toward 1 = no falloff). Default ~0.85. */
+    chromaFalloff?: number;
+    /** Hue walk in degrees for analogous; ignored by monochrome. Default ~28. */
+    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). */
+    chromaEasing?: DeriveEasing;
+    /**
+     * 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]`,
+     * 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).
+     */
+    avoidHues?: readonly (readonly [number, number])[];
+    /**
+     * BG.W-AUR-IMAGE-SOURCE (ASK-GU-AURORA-SCHEME-LUMA) — 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
+     * (`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).
+     * A raw `lBand` override wins over `scheme` (the escape hatch).
+     */
+    scheme?: "light" | "dark";
+    /**
+     * BG.W-AUR-IMAGE-SOURCE — 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.
+     */
+    lBand?: readonly [number, number];
+}
+/**
+ * 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
+ * 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.
+ *
+ * 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.
+ *
+ * @param seed any CSS color string OR an `OklchStop` anchor.
+ * @param options ramp shape — stop count, harmony, L/C/h spreads.
+ */
+export declare function deriveAurora(seed: string | OklchStop, options?: DeriveAuroraOptions): OklchStop[];

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

@@ -0,0 +1,66 @@
+/**
+ * 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
+ * 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
+ * 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 /
+ * 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";
+/** 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;
+}
+export interface FrameLoopDeps {
+    gl: WebGL2RenderingContext;
+    prog: WebGLProgram;
+    uniforms: UniformLocations;
+    /**
+     * BI.W-FIELD-CORE — 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.
+     */
+    pointerField: UsePointerVelocityField;
+    /** The cursor strength ceiling + radius (the runtime's imperative setters write these). */
+    getCursorScalars: () => AuroraCursorScalars;
+    /** The live config (drift uniforms gate the demand loop). */
+    getConfig: () => AuroraConfig;
+    /** Reduced-motion intent — parks the loop after one static frame. */
+    getReducedMotion: () => boolean;
+}
+export interface FrameLoop {
+    /** Advance the field THEN draw — the per-frame step. */
+    frame: (timeSec: number) => void;
+    /** Demand gate — is there live motion to render on the next frame? */
+    needsAnimation: () => boolean;
+}
+/**
+ * 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).
+ */
+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.
+ */
+export declare function auroraFieldLive(pointerField: UsePointerVelocityField): boolean;
+export declare function createFrameLoop(deps: FrameLoopDeps): FrameLoop;

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

@@ -0,0 +1,29 @@
+/**
+ * Aurora GL setup seam — shader compile/link + geometry + the uniform location
+ * cache. The GL-lifecycle orchestrator (`runtime.ts`) 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`.
+ *
+ * The `UNIFORM_NAMES` const-assertion is the single source of truth for the
+ * 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"];
+export type UniformName = (typeof UNIFORM_NAMES)[number];
+export type UniformLocations = Record<UniformName, WebGLUniformLocation | null>;
+export interface GlProgram {
+    program: WebGLProgram;
+    vs: WebGLShader;
+    fs: WebGLShader;
+    uniforms: UniformLocations;
+    geometry: {
+        vao: WebGLVertexArrayObject;
+        buf: WebGLBuffer;
+    };
+}
+/**
+ * Compile + link the shader pair, build the full-screen triangle (one draw covers
+ * the viewport), and resolve the uniform location cache. Leaves the program bound.
+ */
+export declare function createGlProgram(gl: WebGL2RenderingContext, vertexSrc: string, fragmentSrc: string): GlProgram;