@mkbabb/glass-ui 4.1.0 → 5.0.0

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

@@ -0,0 +1,140 @@
+/**
+ * Aurora v4.1 runtime — the GL-lifecycle orchestrator over the `useWebGLCanvas`
+ * substrate (AU.W6, the DEC-AT-1 transposition).
+ *
+ * This module composes four cohesive seams atop the substrate:
+ *   - glSetup       — compile/link + geometry + the uniform location cache
+ *   - uniformBridge — the reactive-config → GL-uniform translation + enum dispatch
+ *   - pointerField  — the shared `usePointerVelocityField` (the retired cursorModel's
+ *                     successor, BI.W-FIELD-CORE): the mass-spring attractor + engagement
+ *                     the `auroraCursorMapping` projects onto the `uCursor*` uniforms
+ *   - frameLoop     — the per-frame draw + the render-demand gate
+ *
+ * It owns ONLY the aurora-specific glue: threading the seams through the
+ * substrate's `setup`/`frame`/`shouldContinue`/`resize`/`time`/`teardown`
+ * callbacks, the reduced-motion frozen-t, the DPR policy, and the imperative
+ * setters/pause/resume. The generic WebGL2 lifecycle — context creation, the
+ * three-reason suspend/resume model, the demand-driven rAF loop, the tab-visibility
+ * owner, the ResizeObserver, and the webglcontextlost/restored robustness — lives
+ * in the substrate.
+ *
+ * Y-origin convention: config authoring is CSS-top-origin (0 = top). The seams
+ * flip Y at the uniform boundary (`flipY` in uniformBridge/frameLoop).
+ */
+import type { AuroraConfig, AuroraInstance } from "../constants/presets";
+export type AuroraRuntimeMode = "live" | "capture";
+/**
+ * The three independent reasons the rAF loop may be suspended. Owned by the
+ * `useWebGLCanvas` substrate as a `Set<reason>`: the loop runs IFF the set is
+ * empty and each reason is cleared ONLY by the source that set it. This makes
+ * resume-while-still-suspended structurally unreachable — a `resume("tab-hidden")`
+ * cannot lift an `"off-screen"` suspension.
+ *
+ * - `"tab-hidden"` — the substrate's `document.visibilitychange` owner.
+ * - `"off-screen"` — viewport-intersection, driven by `useIntersectionPause`.
+ * - `"manual"` — the public `pause()`/`resume()` API (and capture-mode seed).
+ */
+export type SuspendReason = "tab-hidden" | "off-screen" | "manual";
+/**
+ * When the expensive WebGL path (context creation, shader compile + GPU link,
+ * first uniform upload, rAF arm) actually runs.
+ *
+ * - `"deferred"` (default) — `createAurora` constructs a cheap, un-armed instance
+ *   and returns immediately; the GL work is invoked later via `instance.arm()`.
+ *   The Vue wrapper `useAurora` schedules `arm()` past first paint on an idle
+ *   tick, gated on canvas visibility — so the shader compile-link never lands on
+ *   the consumer's first-paint critical path.
+ * - `"eager"` — `createAurora` arms synchronously before returning. Capture /
+ *   thumbnail-baking consumers need this: `renderAt` must draw a real frame the
+ *   instant `createAurora` returns. `mode: "capture"` forces eager regardless.
+ */
+export type AuroraInitStrategy = "eager" | "deferred";
+export interface AuroraRuntimeOptions {
+    mode?: AuroraRuntimeMode;
+    preserveDrawingBuffer?: boolean;
+    /**
+     * When to run the expensive WebGL init. Defaults to `"deferred"`.
+     * `mode: "capture"` forces `"eager"` (a capture runtime must be able to
+     * `renderAt` synchronously). See {@link AuroraInitStrategy}.
+     */
+    initStrategy?: AuroraInitStrategy;
+    /**
+     * Init-failure handler. A WebGL2/shader-compile/link failure is a
+     * library-internal contract violation (O invariant 24). On the EAGER path
+     * `createAurora` throws synchronously and `useAurora` rethrows by default so
+     * the signal reaches the consumer's error boundary / dev console. On the
+     * DEFERRED path the failure happens on an idle tick — outside any mount-time
+     * boundary — so the runtime routes it here, and `useAurora` re-surfaces it on
+     * the microtask queue (so it still reaches the dev console /
+     * `app.config.errorHandler`) when no handler is supplied. Provide this
+     * callback to opt into silent handling on either path.
+     *
+     * NOTE: this is the `useAurora` Vue-wrapper contract surface. The imperative
+     * `createAurora(...)` runtime throws on eager init failure and — for
+     * `instance.arm()` on the deferred path — rethrows from `arm()`.
+     *
+     * BB.W-AURORA-SWRASTER — a SOFTWARE-RASTER fall is NOT a contract violation:
+     * it never reaches `onInitError`. The wedge catch (see {@link createAurora})
+     * recognizes the software-raster signal at arm time, leaves the canvas
+     * un-armed (the placeholder stays the surface), and returns CLEANLY — so a
+     * consumer who pins `mode:"capture"`/`mode:"webgl"` under SwiftShader never
+     * has to wire `onInitError` to avoid the hang. The handler is preserved for
+     * GENUINE violations (a malformed shader, an OOM, a real link failure).
+     */
+    onInitError?: (err: Error) => void;
+    /**
+     * BB.W-AURORA-SWRASTER — opt OUT of the runtime software-raster wedge catch.
+     * Default `false`: the wedge catch is the safe default — `createAurora`
+     * recognizes a software renderer at arm time and falls cleanly to the
+     * placeholder rather than arming the page-wedging live GL layer. `true` (the
+     * named, recorded escape for a deterministic test that ACCEPTS the cost)
+     * arms WebGL even under a detected software renderer. Mirrors the
+     * `resolveRenderMode` escape of the same name — ONE consumer-facing flag,
+     * threaded through both seams.
+     */
+    forceWebGLUnderSoftwareRaster?: boolean;
+    /**
+     * BI.W-E10-AURORA-ENTRANCE (value.js T-60) — the reveal-bloom CONSUMER DOOR.
+     *
+     * The one-shot cold-first-VISIBLE `filter`-bloom (`data-substrate-reveal` →
+     * `@keyframes substrate-reveal-bloom`, viz-reveal.css). It defaults `false` for
+     * the aurora: the aurora already materializes as the palette-derived GROUND
+     * (Aurora.vue's `auroraFallbackGround` placeholder) with the live canvas
+     * OPACITY cross-fading over it — a same-palette dissolve, the "defined bloom
+     * choreography". Arming the `filter`-bloom ON TOP of that opacity cross-fade
+     * was the T-60 gray stage: the bloom stamped at first-visible while the canvas
+     * still sat at `opacity: 0`, so the visible arrival always opened INSIDE the
+     * `brightness(0.54–0.83)` dim floor (a `brightness<1`/`saturate<1` veil over a
+     * chromatic field — the condemned form). The door is the opt-out (default) AND
+     * the arrival-sync seam: a consumer who wants the bloom passes `true` (the
+     * keyframe is now palette-honest — brightness/saturate never dip below 1). The
+     * palette-derived first paint is the floor either way (UF-E10, value.js co-signed).
+     */
+    revealBloom?: boolean;
+}
+/**
+ * The concrete `createAurora` return shape. It IS an {@link AuroraInstance}
+ * (structurally assignable — every member matches) but widens `pause`/`resume` to
+ * carry an optional {@link SuspendReason}, defaulting to `"manual"`. The Vue
+ * wrapper passes `"off-screen"` for the intersection seam; a bare
+ * `pause()`/`resume()` reads identically to the `AuroraInstance` contract.
+ */
+export interface AuroraRuntime extends Omit<AuroraInstance, "pause" | "resume"> {
+    pause(reason?: SuspendReason): void;
+    resume(reason?: SuspendReason): void;
+    /**
+     * BC.W-VIZ-AURORA (T2) — the device-resolved arm PROMISE. On the WebGPU
+     * backend `renderAt`/`arm` are NO-OPS until `armAsync()` resolves the async
+     * adapter→device→configure→setup prelude (`useGpuSubstrate.armAsync` tries
+     * WebGPU then falls to the WebGL2 net). A CAPTURE consumer (`renderAt(t)` +
+     * `toDataURL`) MUST `await armAsync()` before the first `renderAt` — the
+     * synchronous `arm()` cannot guarantee the WebGPU device is present, so a
+     * synchronous `renderAt` right after `createAurora(…,{mode:"capture"})` paints
+     * a BLANK frame (the dead-preview defect). Resolves once the backend is armed;
+     * the WebGL2 fallback resolves immediately. Idempotent + safe post-dispose.
+     */
+    armAsync(): Promise<void>;
+    /** AW.W8.1 — the live reduced-motion state (the cursor listener early-outs on it). */
+    readonly reducedMotion: boolean;
+}
+export declare function createAurora(canvas: HTMLCanvasElement, initial: AuroraConfig, options?: AuroraRuntimeOptions): AuroraRuntime;

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

@@ -0,0 +1,120 @@
+/**
+ * Aurora uniform bridge — the reactive-config → GL-uniform translation seam.
+ *
+ * Owns the sealed enum↔shader-int dispatch maps and the per-config uniform upload.
+ * Each map is `as const` constrained by a `satisfies Record<Union, number>` so a
+ * NEW union member is a COMPILE error until it gets a slot — no silent stale-Record
+ * gap where a fresh enum value uploads `undefined`.
+ *
+ * Crayon is a FIRST-CLASS medium (`uMedium == 4`, AX.W13), NOT a stroke mode: the
+ * shader has a dedicated `mediumCrayon()` body (DRY wax-on-tooth). `MEDIUM_ID` carries
+ * the `crayon: 4` slot and `StrokeMode` no longer has a `crayon` member — the legacy
+ * `oil` + `strokeMode:"crayon"` peer-route is REMOVED (clean break); a crayon surface
+ * selects `medium:"crayon"`.
+ *
+ * The pre-allocated upload buffers live in the bridge: a slider drag refills them
+ * in place rather than allocating ~8 Float32Arrays per frame.
+ */
+import type { OklchStop } from "../../../composables/color";
+import type { UniformLocations } from "./glSetup";
+/**
+ * BI.W-FIELD-CORE — the aurora cursor UNIFORM shape (the `uCursor*` upload inputs). The
+ * retired `cursorModel.ts` `CursorState` is GONE — the cursor is now the mapped readout of
+ * the shared `usePointerVelocityField` (`auroraCursorMapping`): x/y = the mass-spring
+ * attractor (0..1, CSS-top — the bridge flips Y), strength = engagement·ceil, velX/velY the
+ * derived velocity, burst the flick impulse. The GLSL path uploads all seven; the WGPU
+ * struct packs only x/y/strength/radius. `AURORA_CURSOR_UNIFORM_REST` is the neutral
+ * at-rest seed the bridge inits with (re-sent per frame by the frame loop).
+ */
+export interface AuroraCursorUniforms {
+    x: number;
+    y: number;
+    strength: number;
+    radius: number;
+    velX: number;
+    velY: number;
+    burst: number;
+}
+export declare const AURORA_CURSOR_UNIFORM_REST: AuroraCursorUniforms;
+import { type AuroraConfig } from "../constants/presets";
+export declare const MEDIUM_ID: {
+    readonly smooth: 0;
+    readonly pastel: 1;
+    readonly watercolor: 2;
+    readonly oil: 3;
+    readonly crayon: 4;
+    readonly vangogh: 5;
+    readonly "oil-pastel": 6;
+    readonly kuwahara: 7;
+    readonly metal: 8;
+    readonly "metal-gradient": 9;
+};
+export declare const HUE_PATH_ID: {
+    readonly shorter: 0;
+    readonly longer: 1;
+    readonly increasing: 2;
+    readonly decreasing: 3;
+};
+export declare const FLOW_ID: {
+    readonly none: 0;
+    readonly radial: 1;
+    readonly swirl: 2;
+    readonly diagonal: 3;
+    readonly multi: 4;
+    readonly tensor: 5;
+};
+export declare const STROKE_ORIENT_ID: {
+    readonly flow: 0;
+    readonly tensor: 1;
+};
+export declare const WARP_ID: {
+    readonly fbm: 0;
+    readonly cellular: 1;
+    readonly hybrid: 2;
+    readonly curl: 3;
+};
+export declare const STROKE_MODE_ID: {
+    readonly oil: 0;
+    readonly knife: 1;
+    readonly chunky: 3;
+};
+export declare const AURORA_CATCH_LIGHT_ANCHOR: OklchStop;
+/**
+ * Resolve a config's `lightColor` to a LINEAR-light `[r,g,b]` triple. Accepts either
+ * a raw linear triple (the array form, passed through) OR an `{L,C,h}` OKLCh anchor
+ * (derived through the shared `warmCatchLight` helper). Omitted = the canonical aurora
+ * warm-white from `AURORA_CATCH_LIGHT_ANCHOR`.
+ */
+export declare function resolveLightColor(lightColor: [number, number, number] | OklchStop | undefined): [number, number, number];
+/**
+ * The effective `uMedium` int for a config. AX.W13 — a pure identity map over the
+ * medium union (the `oil` + `strokeMode:"crayon"` peer-route is REMOVED; crayon is its
+ * own first-class `medium:"crayon"`). `medium` is total over `MEDIUM_ID` (the
+ * `satisfies` guarantees it), so this never resolves `undefined`.
+ */
+export declare function resolveMediumId(cfg: AuroraConfig): number;
+/**
+ * The `uStrokeMode` int for a config. AX.W13 — `strokeMode` is total over
+ * `STROKE_MODE_ID` (no `crayon` special-case), so this is a direct map.
+ */
+export declare function resolveStrokeModeId(cfg: AuroraConfig): number;
+/**
+ * AX.W13 — the `uStrokeOrient` int for a config. The painterly mediums (`vangogh`,
+ * `oil-pastel`, `crayon`) FORCE the structure-tensor orientation regardless of the
+ * config's `strokeOrient` field — their marks must hug the color zones (the
+ * congruent-to-real-works contract). Every other medium honors the config's
+ * `strokeOrient` (default `"flow"`). BB.W-AUR-KUWAHARA — `kuwahara` ALSO forces
+ * tensor: the anisotropic Kuwahara kernel is squeezed along the structure-tensor
+ * minor eigenvector, so the orientation source must be the tensor field.
+ */
+export declare function resolveStrokeOrientId(cfg: AuroraConfig): number;
+/**
+ * Build the per-config uniform uploader bound to a program's uniform location
+ * cache + cursor state. Returns `uploadConfig` — call it to push a fresh
+ * `AuroraConfig` into the live program. The cursor uniforms are initialised here
+ * and re-sent per frame by the frame loop.
+ *
+ * Y-origin: config authoring is CSS-top-origin (0 = top); the bridge flips Y at
+ * the uniform boundary (`flipY`).
+ */
+export declare function createUniformBridge(gl: WebGL2RenderingContext, prog: WebGLProgram, U: UniformLocations): (cfg: AuroraConfig) => void;

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

@@ -0,0 +1,60 @@
+/**
+ * Aurora WGSL uniform bridge — the typed-struct SOURCE OF TRUTH for the WebGPU primary.
+ *
+ * The WGSL `Uniforms` struct (`aurora.wgsl.ts`) and the JS `ArrayBuffer` write offsets
+ * are generated from the SAME layout table here, so a std140-vs-WGSL alignment mismatch
+ * (the parity-ΔE-blowout trap the wave's §Triumvirate names) is structurally impossible:
+ * the field order + the byte offsets are ONE declaration.
+ *
+ * The struct packs every scalar into a vec4 lane + every per-nucleus row / palette stop
+ * into a vec4 so the array stride is the natural 16 bytes (no std140 16-byte-array-stride
+ * surprise). The byte layout (all offsets in bytes, std140-compatible — vec4 align 16):
+ *
+ *   scalars0 : vec4<f32>   off   0   (uTime, uSoftmaxBeta, uValueVariance, uWarpAmount)
+ *   scalars1 : vec4<f32>   off  16   (uWarpScale, uWarpDrift, uSaturation, uPaperGrain)
+ *   scalars2 : vec4<f32>   off  32   (uAlpha, uNucleiDrift, uPaletteDrift, uBreathDepth)
+ *   scalars3 : vec4<f32>   off  48   (uBreathPeriod, uCursorStrength, uCursorRadius, uVividness)
+ *   cursor   : vec4<f32>   off  64   (uCursor.x, uCursor.y, uMetalPolish, uMetalHeightScale)
+ *   ints0    : vec4<i32>   off  80   (uStopCount, uNucleiCount, uWarpMode, uNoiseOctaves)
+ *   ints1    : vec4<i32>   off  96   (uMedium, uHuePath, _, _)
+ *   palette  : array<vec4<f32>, 8>  off 112  (rgb linear-sRGB stop + pad)
+ *   nuc0     : array<vec4<f32>, 6>  off 240  (pos.x, pos.y, radius, paletteBias)
+ *   nuc1     : array<vec4<f32>, 6>  off 336  (valueBias, driftRadius, driftPhase, elong)
+ *   nuc2     : array<vec4<f32>, 6>  off 432  (angle, _, _, _)
+ *   scalars4 : vec4<f32>   off 528  (uStrokeAmount, uStrokeScale, uStrokeAnisotropy, uCanvasGrain)
+ *   scalars5 : vec4<f32>   off 544  (uWetEdge, uGranulation, uBrokenColor, uKuwaharaQ)
+ *   kuwahara : vec4<f32>   off 560  (uKuwaharaRadius, uKuwaharaSectors, _, _)
+ *   total    : 576 bytes (16-aligned)
+ *
+ * BC.W-VIZ-AURORA (T4) — the painterly-medium scalar lanes (scalars4/scalars5/kuwahara)
+ * are APPENDED after the arrays, so EVERY pre-existing offset is byte-identical and the
+ * smooth-default parity capture is byte-equivalent (these lanes pack 0 on a smooth config).
+ * The WGSL `Uniforms` struct (`aurora.wgsl.ts`) carries the SAME three trailing lanes —
+ * the typed-struct lockstep: a one-sided add reds the parity-ΔE.
+ *
+ * Y-origin: config authoring is CSS-top-origin (0 = top); the bridge flips Y at the
+ * uniform boundary (`flipY`), exactly as the GLSL `uniformBridge` does.
+ */
+import { type AuroraConfig } from "../constants/presets";
+import type { AuroraCursorUniforms } from "./uniformBridge";
+/** The total uniform-buffer byte size (16-aligned). */
+export declare const AURORA_WGPU_UNIFORM_BYTES = 576;
+/**
+ * The packed scratch buffer + the dual ArrayBuffer views. A slider drag refills this
+ * in place (no per-frame allocation) — mirroring the GLSL bridge's pre-allocated
+ * upload buffers. The Float32 view writes the float lanes; the Int32 view writes the
+ * two int lanes (a WGSL `i32` shares the buffer at the 16-byte-aligned offsets).
+ */
+export interface AuroraWGPUUniformScratch {
+    buffer: ArrayBuffer;
+    f32: Float32Array;
+    i32: Int32Array;
+    paletteScratch: Float32Array;
+}
+export declare function createAuroraWGPUUniformScratch(): AuroraWGPUUniformScratch;
+/**
+ * Pack an {@link AuroraConfig} + the live cursor + the frame time into the uniform
+ * scratch buffer. The byte layout mirrors the WGSL `Uniforms` struct EXACTLY. Returns
+ * the same scratch (the caller `queue.writeBuffer`s `scratch.buffer`).
+ */
+export declare function packAuroraWGPUUniforms(scratch: AuroraWGPUUniformScratch, cfg: AuroraConfig, cursor: AuroraCursorUniforms, timeSec: number): AuroraWGPUUniformScratch;

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

@@ -0,0 +1,39 @@
+/**
+ * Aurora WGSL IMAGE uniform bridge — the typed-struct source-of-truth for the
+ * `source:"image"` WebGPU program (BG.W-AUR-IMAGE-SOURCE).
+ *
+ * DISTINCT from `uniformBridgeWGPU.ts` (the 576-byte PALETTE struct): the image program
+ * is a SEPARATE compiled pipeline with its OWN, smaller uniform buffer + its own bind
+ * group (uniform + texture + sampler). The image lane never touches the palette struct —
+ * the construction-time permutation's isolation, so the palette parity capture is
+ * byte-untouched.
+ *
+ * The byte layout (all offsets in bytes, std140-compatible — vec4 align 16) MIRRORS the
+ * `ImageUniforms` WGSL struct (`aurora-image.wgsl.ts`) EXACTLY:
+ *
+ *   scalars0 : vec4<f32>            off   0   (uTime, uWarpAmount, uWarpScale, uWarpDrift)
+ *   scalars1 : vec4<f32>            off  16   (uSoftmaxBeta, uNucleiDrift, uCursorStrength, uCursorRadius)
+ *   scalars2 : vec4<f32>            off  32   (uSaturation, uPaperGrain, uAlpha, uVividness)
+ *   image    : vec4<f32>            off  48   (uBlurMin, uBlurMax, uImageAspect, _)
+ *   cursor   : vec4<f32>            off  64   (uCursor.x, uCursor.y, _, _)
+ *   ints     : vec4<i32>            off  80   (uNucleiCount, uNoiseOctaves, _, _)
+ *   nuc0     : array<vec4<f32>, 6>  off  96   (pos.x, pos.y, radius, valueBias)
+ *   nuc1     : array<vec4<f32>, 6>  off 192   (driftRadius, driftPhase, elong, angle)
+ *   total    : 288 bytes (16-aligned)
+ */
+import { type AuroraConfig } from "../constants/presets";
+import type { AuroraCursorUniforms } from "./uniformBridge";
+/** The total image-uniform-buffer byte size (16-aligned). */
+export declare const AURORA_IMAGE_WGPU_UNIFORM_BYTES = 288;
+export interface AuroraImageWGPUScratch {
+    buffer: ArrayBuffer;
+    f32: Float32Array;
+    i32: Int32Array;
+}
+export declare function createAuroraImageWGPUScratch(): AuroraImageWGPUScratch;
+/**
+ * Pack an {@link AuroraConfig} + the live cursor + the frame time + the live canvas
+ * aspect into the image-uniform scratch buffer. The byte layout mirrors the
+ * `ImageUniforms` WGSL struct EXACTLY.
+ */
+export declare function packAuroraImageWGPUUniforms(scratch: AuroraImageWGPUScratch, cfg: AuroraConfig, cursor: AuroraCursorUniforms, timeSec: number, aspect: number): AuroraImageWGPUScratch;

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

@@ -0,0 +1,80 @@
+import { type Ref } from "vue";
+import { type AuroraRuntimeOptions } from "./runtime";
+import { type ConfigSource } from "./configSource";
+import type { AuroraConfig } from "../constants/presets";
+/**
+ * Adaptive-substrate options threaded down from `Aurora.vue` (AM.W1). The
+ * render mode is the RESOLVED concrete substrate (`"auto"` already collapsed
+ * to `"webgl"`/`"css"` at the component boundary via `resolveRenderMode`).
+ */
+export interface UseAuroraAdaptiveOptions {
+    /**
+     * Resolved render substrate. `"css"` short-circuits the WebGL arm schedule
+     * entirely — no webgl2 context is ever created; the `Aurora.vue`
+     * placeholder stays the permanent surface. `"webgl"` (default) arms the
+     * deferred WebGL path as before.
+     */
+    renderMode?: "webgl" | "css";
+}
+/**
+ * Public return shape of {@link useAurora}.
+ *
+ * O.W4 Lane B — Fix 2 (Rγ L2): authored to replace the previous anonymous
+ * inline-typed literal. Parallels sibling composable return interfaces
+ * (`ConfiguratorState<T>`, `SidebarState`, `UseSortableReturn`); consumers
+ * can now annotate variables holding `useAurora` results without reaching
+ * for `ReturnType<typeof useAurora>`.
+ *
+ * NOT a /api discovery-surface candidate (per /api preamble: composable
+ * option/return types change with implementation). Exposed only via the
+ * `@mkbabb/glass-ui/aurora` package barrel.
+ */
+export interface UseAuroraReturn {
+    setCursor: (x: number, y: number, strength?: number) => void;
+    clearCursor: () => void;
+    setCursorRadius: (r: number) => void;
+    renderAt: (t: number) => void;
+    pause: () => void;
+    resume: () => void;
+    /**
+     * `true` once the WebGL runtime has armed (shader compiled + linked, first
+     * frame drawable). `Aurora.vue` watches this to cross-fade the canvas in
+     * over the static CSS-gradient placeholder. Eager / capture consumers see
+     * it flip `true` synchronously within `onMounted`; deferred consumers see
+     * it flip on the post-first-paint idle tick.
+     */
+    isArmed: Readonly<Ref<boolean>>;
+}
+/**
+ * Vue-side wrapper for the imperative `createAurora` runtime.
+ *
+ * Accepts the config as a plain object, a ref, or a getter. Internally we
+ * watch it deeply with `{ deep: true }` so both:
+ *   (a) parent swaps the reference (e.g. preset switch), and
+ *   (b) parent mutates the reactive object (slider drag),
+ * trigger a uniform re-upload. Passing a raw object works for single-config
+ * use; passing a getter or ref works for preset-switch scenarios.
+ *
+ * Lazy-arm: by default (`initStrategy: "deferred"`) `createAurora` constructs
+ * a cheap, un-armed instance and the expensive WebGL init (shader compile +
+ * GPU link — the dominant synchronous cost) is deferred past first paint via
+ * `requestIdleCallback`, gated on the canvas's first viewport intersection
+ * (composing `useIntersectionPause`). `Aurora.vue` paints a CSS-gradient
+ * placeholder under the canvas so the consumer's first paint is never blocked
+ * on the shader. Capture / `initStrategy: "eager"` consumers arm synchronously
+ * inside `createAurora` and skip the defer entirely.
+ *
+ * Init-failure contract (O invariant 24 — "fails explicitly by default"). A
+ * WebGL2/shader-compile/link failure is a library-internal contract violation.
+ * On the DEFERRED path the failure lands on an idle tick, OUTSIDE any
+ * mount-time error boundary, so the consumer MUST handle it through exactly one
+ * of three paths:
+ *   1. pass an `onInitError(err)` handler in `runtimeOptions` (the explicit
+ *      opt-in — receives the error directly), OR
+ *   2. install a Vue global `app.config.errorHandler` (the re-surfaced
+ *      microtask rejection reaches it), OR
+ *   3. knowingly accept the unhandled rejection (the dev console still gets it).
+ * Armed deferred with NO `onInitError`, `useAurora` dev-warns ONCE so the
+ * silent-by-omission case is visible. WebGL2-unavailable still throws HARD.
+ */
+export declare function useAurora(canvasRef: Ref<HTMLCanvasElement | null>, configSource: ConfigSource<AuroraConfig>, runtimeOptions?: AuroraRuntimeOptions, adaptiveOptions?: UseAuroraAdaptiveOptions): UseAuroraReturn;

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

@@ -0,0 +1,25 @@
+import { type Ref } from "vue";
+import { type ConfigSource } from "./configSource";
+import type { AuroraConfig } from "../constants/presets";
+export interface CursorInteractionOptions {
+    /** Fires `setCursor(x,y,strength)` for continuous swirl. */
+    setCursor: (x: number, y: number, strength?: number) => void;
+    clearCursor: () => void;
+    /**
+     * Nucleus-ring hit fraction: a nucleus is "hit" when distance ≤ radius × this.
+     * 0.35 matches the overlay's default ring thickness.
+     */
+    hitFraction?: number;
+}
+/**
+ * Wires pointer events on the stage element to (a) continuous cursor swirl,
+ * and (b) CRUD on `getCfg().nuclei` — spawn (alt-click), remove (shift-click /
+ * right-click), drag, delete key.
+ *
+ * Accepts the config as a plain object, ref, or getter; every pointer event
+ * re-resolves the current config, so CRUD always targets the active preset
+ * even after a preset switch swaps the underlying config reference.
+ */
+export declare function useCursorInteraction(stageRef: Ref<HTMLElement | null>, configSource: ConfigSource<AuroraConfig>, options: CursorInteractionOptions): {
+    isDragging: () => number | null;
+};

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

@@ -0,0 +1,50 @@
+/**
+ * Aurora WGSL setup seam — the WebGPU twin of `glSetup` + `frameLoop`.
+ *
+ * `createAuroraWGPUSetup` returns a `setupWGPU(device, context, format)` callback the
+ * `useGpuSubstrate` picker invokes on the async arm (AND on every device-restore). It
+ * builds the render pipeline (the `aurora.wgsl` full-screen-triangle pass), the uniform
+ * buffer (the `uniformBridgeWGPU` typed-struct source-of-truth), and the bind group, then
+ * returns the substrate's per-frame hooks (`frame`/`shouldContinue`/`resize`/`time`/
+ * `teardown`).
+ *
+ * The render-demand gate + the cursor-advance + the DPR resize mirror the WebGL2
+ * `frameLoop`/`runtime.resize` exactly — the loop is substrate-AGNOSTIC, so the same
+ * `getConfig`/`getReducedMotion`/`cursor` closures drive both backends.
+ */
+import type { WebGPUCanvasFrame } from "../../../composables/glass/webgpu/useWebGPUCanvas";
+import { type AuroraCursorScalars } from "./frameLoop";
+import { type UploadableImageSource } from "../../../composables/glass/textureUpload";
+import type { AuroraConfig } from "../constants/presets";
+import type { UsePointerVelocityField } from "../../../composables/motion/usePointerVelocityField";
+export interface AuroraWGPUSetupDeps {
+    canvas: HTMLCanvasElement;
+    /** The cursor strength ceiling + radius (the runtime's imperative setters write these). */
+    getCursorScalars: () => AuroraCursorScalars;
+    getConfig: () => AuroraConfig;
+    getReducedMotion: () => boolean;
+    /**
+     * BC.W-VIZ-AURORA (T5) — the shared viz-pointer-physics field (BB.B4). FED
+     * `tick(deltaMs)` from the WGPU frame callback (the SAME field instance the WebGL2
+     * loop feeds — one source, no own rAF); the renderer reads `acceleration` for the
+     * iOS-27 gel snap-back.
+     */
+    pointerField: UsePointerVelocityField;
+    /**
+     * BG.W-AUR-IMAGE-SOURCE — the decoded photo the `source:"image"` program samples (or
+     * `null` before decode / on a palette config). Read at setup + on re-upload.
+     */
+    getDecodedImage: () => UploadableImageSource | null;
+    /**
+     * BG.W-AUR-IMAGE-SOURCE — register the backend's texture uploader with the runtime so
+     * a late-arriving decode re-uploads into the live GPU texture. Passing `null` clears
+     * it (teardown). The runtime calls the registered fn when a decode resolves.
+     */
+    registerImageUploader: (fn: ((src: UploadableImageSource) => void) | null) => void;
+}
+/**
+ * Build the aurora `setupWGPU(device, context, format)` callback. Closes over the
+ * aurora-specific state (cursor/config/reduced-motion) the runtime owns — identical to
+ * the closures the WebGL2 `setup` threads.
+ */
+export declare function createAuroraWGPUSetup(deps: AuroraWGPUSetupDeps): (device: GPUDevice, context: GPUCanvasContext, format: GPUTextureFormat) => WebGPUCanvasFrame;