@mkbabb/glass-ui 4.2.0 → 5.0.0

package/dist/components/_shared/useMotionAxis.d.ts

@@ -0,0 +1,41 @@
+import { type MaybeRefOrGetter } from "vue";
+import type { Motion } from "./axes";
+/**
+ * Resolve a prop `Motion` value (default `full`) DOWN under live PRM. The prop may
+ * only clamp DOWN — PRM forces `full`/`reduced` → `reduced` (never an escalation),
+ * `off` is preserved (the prop went below PRM, which is legal).
+ */
+export declare function resolveMotion(motion: Motion | undefined): Motion;
+/**
+ * The resolved-motion state a carrier reads. `armed` gates the JS gesture
+ * enrichment (drag/press/spring-mount/liquid-drag); `dataMotion`/`hostStyle` are the
+ * `:data-motion`/`:style` binds the carrier spreads onto its root (both undefined at
+ * the `full` default — the zero-delta no-op floor).
+ */
+export interface MotionAxis {
+    /** The PRM-clamped resolved rung (`full`/`reduced`/`off`). */
+    readonly resolved: Motion;
+    /** True iff resolved `full` — the JS gesture enrichment is armed. */
+    readonly armed: boolean;
+    /** `undefined` at `full` (no attr); the rung string otherwise. */
+    readonly dataMotion: "reduced" | "off" | undefined;
+    /** `undefined` unless `off` (then `{ "--motion-weight": "0" }`). */
+    readonly hostStyle: Record<string, string> | undefined;
+}
+/**
+ * The reactive motion resolver — the ONE seam every carrier threads. Pass the
+ * component's `motion` prop (a ref/getter/value); read `.armed` to gate JS
+ * enrichments, bind `.dataMotion` to `:data-motion`, spread `.hostStyle` into the
+ * root `:style`. All four derive from the ONE `resolveMotion` clamp so PRM
+ * precedence + the zero-delta default are single-sourced.
+ *
+ *   const motion = useMotionAxis(() => props.motion)
+ *   // <Root :data-motion="motion.dataMotion.value" :style="motion.hostStyle.value">
+ *   // if (motion.armed.value) { …arm the drag/press/spring enrichment… }
+ */
+export declare function useMotionAxis(motion: MaybeRefOrGetter<Motion | undefined>): {
+    resolved: import("vue").ComputedRef<"full" | "reduced" | "off">;
+    armed: import("vue").ComputedRef<boolean>;
+    dataMotion: import("vue").ComputedRef<"reduced" | "off" | undefined>;
+    hostStyle: import("vue").ComputedRef<Record<string, string> | undefined>;
+};

package/dist/components/_shared/useSurfaceAxis.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The shared surface-decoration axis — three rungs, ONE grammar.
+ *
+ *   glass   — the resolved tier's plain glass rung (default). The translucent
+ *             blur surface, the maximal glass-first register.
+ *   veil    — the borderless/rimless text-legibility plate: the `--glass-bg-quiet`
+ *             fill + blur with the box border AND rim STRIPPED (the boxed look
+ *             reads as a dividing line on a text plate). Reads the same `--glass-*`
+ *             ladder + W55 `--glass-tint-*` seam, so `--glass-level` / the bright
+ *             bucket retune it in lockstep with every glass surface.
+ *   opaque  — the `--glass-level:0` solid-card escape: solid `--card` + `blur(0)`
+ *             through the ONE level knob. The explicit opt-out from the maximal
+ *             glass default.
+ *
+ * (BE.W-CLEAR-VARIANT's `clear` member was RETIRED at BI.W-CLEAR-FOLD — a full
+ * mechanism with zero binding consumers; the substrate-without-consumer invariant
+ * J-inv-10 retires it. proof:surface-axis W9 (member-consumption) gate-locks the
+ * union against a future dead member riding vacuously.)
+ */
+export type Surface = "glass" | "veil" | "opaque";
+/**
+ * The 5-rung glass-ladder tier the surface paints its base over. Mirrors the
+ * `.glass-{wash,quiet,resting,floating,overlay}` ladder. A surface passes the rung
+ * it already paints (Card's `resting`, Dialog/Sheet/Popover's `floating`); the
+ * resolver maps it to the `glass-${tier}` base class. `opaque` is NOT a ladder
+ * rung here — it is a decoration on TOP of a base tier (the `.glass-opaque`
+ * escape keeps the tier's edge/rim), exactly as Card composes it.
+ */
+export type SurfaceTier = "wash" | "quiet" | "resting" | "floating" | "overlay";
+/**
+ * Resolve a (surface, tier) pair to the class string a surface composes. Pairs
+ * with a `:data-surface="surface"` attribute binding on the same element — the
+ * CSS seam (`surface-axis.css`) reads the attr to apply the veil/opaque
+ * decoration UNIFORMLY, while this resolver emits the back-compat decoration
+ * classes (`veil-surface` / `glass-opaque`) so Card's three shared rungs stay
+ * byte-identical and a surface composing the class set alone (no attr) still
+ * paints correctly.
+ *
+ *   surfaceClass("glass",  "floating") → "glass-floating"
+ *   surfaceClass("veil",   "floating") → "glass-floating veil-surface"
+ *   surfaceClass("opaque", "floating") → "glass-floating glass-opaque"
+ *
+ * @param surface the decoration rung (`glass` default · `veil` · `opaque`)
+ * @param tier    the base ladder rung (default `resting`)
+ */
+export declare function surfaceClass(surface?: Surface, tier?: SurfaceTier): string;
+/**
+ * Resolve ONLY the decoration class for a surface — no base-tier prefix
+ * (BI.W-SURFACE-EXTRACT). The SINGLE source of the veil/opaque decoration
+ * string; `surfaceClass()` (above) composes it after the base tier. This KILLS
+ * the `surfaceClass(x).replace(/^glass-.../, "")` tier-strip DRY wart every
+ * reka-portaled overlay hand-rolled to strip the base tier off `surfaceClass`'s
+ * output (the `^glass-<tier>` prefix, whitespace-trimmed): a
+ * surface that already composes its OWN base tier (Card `glass-${tier}`,
+ * Dialog/Sheet/Popover's baked `glass-floating`, the drawer recipe) reaches
+ * for the decoration ALONE through this function — ONE regex-free source.
+ *
+ *   decorationClass("glass")  → ""              (the identity — the bare tier paints)
+ *   decorationClass("veil")   → "veil-surface"
+ *   decorationClass("opaque") → "glass-opaque"
+ *
+ * @param surface the decoration rung (`glass` default · `veil` · `opaque`)
+ */
+export declare function decorationClass(surface?: Surface): string;

package/dist/components/alert/Alert.vue.d.ts

@@ -0,0 +1,19 @@
+import type { HTMLAttributes } from 'vue';
+import { type AlertVariants } from './';
+type __VLS_Props = {
+    class?: HTMLAttributes['class'];
+    tone?: AlertVariants['tone'];
+};
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/alert/index.d.ts

@@ -0,0 +1,8 @@
+import { type VariantProps } from 'class-variance-authority';
+export { default as Alert } from './Alert.vue';
+export { default as AlertDescription } from './AlertDescription.vue';
+export { default as AlertTitle } from './AlertTitle.vue';
+export declare const alertVariants: (props?: ({
+    tone?: "neutral" | "success" | "warning" | "info" | "destructive" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type AlertVariants = VariantProps<typeof alertVariants>;

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

@@ -0,0 +1,104 @@
+import type { AuroraRuntimeOptions } from "./composables/runtime";
+import { type AuroraConfig } from "./constants/presets";
+import { type AuroraRenderMode } from "./constants/renderMode";
+/**
+ * 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>>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    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[];