@mkbabb/glass-ui 5.0.0 → 7.0.0

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

@@ -1,100 +1,82 @@
 /**
- * Aurora v4.1 runtime — the GL-lifecycle orchestrator over the `useWebGLCanvas`
- * substrate (AU.W6, the DEC-AT-1 transposition).
+ * Aurora runtime over the shared WebGPU/WebGL2 substrate.
  *
  * 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
+ *   - engine setup  — WebGPU or WebGL2 program resources
+ *   - uniform bridges — reactive config translated to the selected engine
+ *   - pointerField  — shared `usePointerVelocityField`: mass-spring attraction and
+ *                     engagement projected by `auroraCursorMapping` onto `uCursor*`
  *   - 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.
+ * It owns only Aurora-specific configuration, pointer state, frame work, and
+ * imperative controls. Context/device acquisition, resize, suspension, reduced
+ * motion, visibility, scheduling, recovery, and disposal belong to 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 RendererStatus } from "../../../composables/glass/webgpu/useGpuSubstrate";
 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
+ * The three independent reasons the frame loop may be suspended. Owned by the
+ * shared lifecycle 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`.
+ * - `"off-screen"` — the shared content-visibility owner.
+ * - `"off-screen-io"` — the deferred pre-arm intersection owner.
  * - `"manual"` — the public `pause()`/`resume()` API (and capture-mode seed).
  */
-export type SuspendReason = "tab-hidden" | "off-screen" | "manual";
+export type SuspendReason = "tab-hidden" | "off-screen" | "off-screen-io" | "manual";
 /**
- * When the expensive WebGL path (context creation, shader compile + GPU link,
- * first uniform upload, rAF arm) actually runs.
+ * When expensive GPU initialization 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
+ *   and returns immediately; GPU work is invoked later via `instance.armAsync()`.
+ *   The Vue wrapper `useAurora` schedules that acquisition 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.
+ * - `"eager"` — acquisition starts immediately. Capture, thumbnail-baking
+ *   consumers then await `armAsync()` before `renderAt`. `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"`.
+     * When to run expensive GPU initialization. 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.
+     * Optional attributed init-failure callback. Runtime status remains the
+     * always-available failure surface; `Aurora.vue` additionally adapts Vue's
+     * app error handler here when installed. `armAsync()` rejects so imperative
+     * consumers can own failure directly.
      *
-     * 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).
+     * A direct runtime that cannot animate under software rasterization reports
+     * that capability failure here and rejects `armAsync()`. `Aurora.vue` resolves
+     * the same host to its explicit CSS surface before constructing the runtime.
      */
     onInitError?: (err: Error) => void;
+    onRendererStatus?: (status: RendererStatus) => 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)
+     * Opt out of the runtime software-raster wedge catch.
+     * Default `false`: `createAurora` recognizes a software renderer and surfaces
+     * an attributed unavailable error rather than arming the page-wedging live GL
+     * layer. `true` is the named escape for a deterministic test that accepts the cost and
      * 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.
+     * 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
@@ -102,16 +84,26 @@ export interface AuroraRuntimeOptions {
      * (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
+     * was the gray stage: the bloom stamped at first-visible while the canvas
+     * still sat at `opacity: 0`, so the visible arrival opened inside the
+     * `brightness(0.54–0.83)` dim floor. 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).
+     * palette-derived first paint is the floor either way.
      */
     revealBloom?: boolean;
 }
+/**
+ * The canvas-present contract is mode-owned, not engine-owned. A live Aurora covers its
+ * stage, so both GPU backends present an opaque drawing buffer and the public pigment alpha
+ * is applied once by CSS over the palette ground. Capture keeps the historical transparent,
+ * premultiplied buffer so readback bytes retain their authored alpha.
+ */
+export declare function resolveAuroraPresentation(mode?: AuroraRuntimeMode): {
+    readonly opaque: boolean;
+    readonly alphaMode: "opaque" | "premultiplied";
+    readonly contextAlpha: boolean;
+};
 /**
  * The concrete `createAurora` return shape. It IS an {@link AuroraInstance}
  * (structurally assignable — every member matches) but widens `pause`/`resume` to
@@ -123,18 +115,24 @@ 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
+     * 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;
+     * a blank frame. 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). */
+    /** Drive the opt-in scroll-linked palette/breath phase in normalized 0..1 space. */
+    setScrollProgress(progress: number): void;
+    /** Live reduced-motion state; the cursor listener early-outs on it. */
     readonly reducedMotion: boolean;
 }
+/** One medium-aware predicate shared by pointer writes and uniform projection. */
+export declare function isAuroraPointerEnabled(config: AuroraConfig): boolean;
+/** One shader-time projection shared by the WebGPU and WebGL2 bridges. */
+export declare function resolveAuroraRenderTime(config: AuroraConfig, elapsedSec: number, progress: number, reducedMotion: boolean): number;
 export declare function createAurora(canvas: HTMLCanvasElement, initial: AuroraConfig, options?: AuroraRuntimeOptions): AuroraRuntime;

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

@@ -6,7 +6,7 @@
  * 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
+ * Crayon is a first-class medium (`uMedium == 4`), 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
@@ -18,22 +18,17 @@
 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
+ * 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).
+ * attractor (0..1, CSS-top — the bridge flips Y), and strength is the CPU-folded steady
+ * engagement plus bounded burst. Both engines consume the same four values.
  */
 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";
@@ -87,23 +82,23 @@ export declare const AURORA_CATCH_LIGHT_ANCHOR: OklchStop;
  */
 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
+ * The effective `uMedium` integer for a config: 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
+ * The `uStrokeMode` integer for a config. `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`,
+ * The `uStrokeOrient` integer 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
+ * `strokeOrient` (default `"flow"`). `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.
  */
@@ -117,4 +112,4 @@ export declare function resolveStrokeOrientId(cfg: AuroraConfig): number;
  * 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;
+export declare function createUniformBridge(gl: WebGL2RenderingContext, prog: WebGLProgram, U: UniformLocations, opaquePresentation?: boolean): (cfg: AuroraConfig) => void;

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

@@ -3,34 +3,33 @@
  *
  * 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.
+ * is structurally impossible because field order and byte offsets share one declaration.
  *
- * The struct packs every scalar into a vec4 lane + every per-nucleus row / palette stop
+ * 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)
+ *   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>, 8>  off 240  (pos.x, pos.y, radius, paletteBias)
+ *   nuc1: array<vec4<f32>, 8>  off 368  (valueBias, driftRadius, driftPhase, elong)
+ *   nuc2: array<vec4<f32>, 8>  off 496  (angle, _, _, _)
+ *   scalars4: vec4<f32>   off 624  (uStrokeAmount, uStrokeScale, uStrokeAnisotropy, uCanvasGrain)
+ *   scalars5: vec4<f32>   off 640  (uWetEdge, uGranulation, uBrokenColor, uKuwaharaQ)
+ *   kuwahara: vec4<f32>   off 656  (uKuwaharaRadius, uKuwaharaSectors, _, _)
+ *   total: 672 bytes (16-aligned)
  *
- * BC.W-VIZ-AURORA (T4) — the painterly-medium scalar lanes (scalars4/scalars5/kuwahara)
+ * 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.
+ * the typed-struct lockstep.
  *
  * 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.
@@ -38,7 +37,7 @@
 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;
+export declare const AURORA_WGPU_UNIFORM_BYTES = 672;
 /**
  * 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
@@ -57,4 +56,4 @@ export declare function createAuroraWGPUUniformScratch(): AuroraWGPUUniformScrat
  * 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;
+export declare function packAuroraWGPUUniforms(scratch: AuroraWGPUUniformScratch, cfg: AuroraConfig, cursor: AuroraCursorUniforms, timeSec: number, outputAlpha?: number): AuroraWGPUUniformScratch;

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

@@ -1,8 +1,8 @@
 /**
  * Aurora WGSL IMAGE uniform bridge — the typed-struct source-of-truth for the
- * `source:"image"` WebGPU program (BG.W-AUR-IMAGE-SOURCE).
+ * `source:"image"` WebGPU program.
  *
- * DISTINCT from `uniformBridgeWGPU.ts` (the 576-byte PALETTE struct): the image program
+ * DISTINCT from `uniformBridgeWGPU.ts` (the 672-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
@@ -11,20 +11,20 @@
  * 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)
+ *   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>, 8>  off  96   (pos.x, pos.y, radius, valueBias)
+ *   nuc1: array<vec4<f32>, 8>  off 224   (driftRadius, driftPhase, elong, angle)
+ *   total: 352 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 declare const AURORA_IMAGE_WGPU_UNIFORM_BYTES = 352;
 export interface AuroraImageWGPUScratch {
     buffer: ArrayBuffer;
     f32: Float32Array;
@@ -36,4 +36,4 @@ export declare function createAuroraImageWGPUScratch(): AuroraImageWGPUScratch;
  * 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;
+export declare function packAuroraImageWGPUUniforms(scratch: AuroraImageWGPUScratch, cfg: AuroraConfig, cursor: AuroraCursorUniforms, timeSec: number, aspect: number, outputAlpha?: number): AuroraImageWGPUScratch;

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

@@ -2,25 +2,24 @@ import { type Ref } from "vue";
 import { type AuroraRuntimeOptions } from "./runtime";
 import { type ConfigSource } from "./configSource";
 import type { AuroraConfig } from "../constants/presets";
+import { type RendererStatus } from "../../../composables/glass/webgpu/rendererStatus";
 /**
- * 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`).
+ * Adaptive-substrate options threaded down from `Aurora.vue`. `"webgl"` is the
+ * historical name of the animated GPU mode; the runtime itself prefers WebGPU
+ * and uses its supported WebGL2 path when acquisition cannot start.
  */
 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.
+     * Resolved render substrate. `"css"` short-circuits GPU initialization and
+     * keeps the `Aurora.vue` placeholder as the permanent surface. `"webgl"`
+     * (default) arms the deferred GPU runtime.
      */
     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
+ * Named return shape replacing the previous anonymous inline type. Parallels sibling composable return interfaces
  * (`ConfiguratorState<T>`, `SidebarState`, `UseSortableReturn`); consumers
  * can now annotate variables holding `useAurora` results without reaching
  * for `ReturnType<typeof useAurora>`.
@@ -37,13 +36,13 @@ export interface UseAuroraReturn {
     pause: () => void;
     resume: () => void;
     /**
-     * `true` once the WebGL runtime has armed (shader compiled + linked, first
+     * `true` once the GPU runtime has armed (device/context ready and 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.
+     * over the static palette ground. It stays false through asynchronous device
+     * acquisition and flips only when the backend readiness promise resolves.
      */
     isArmed: Readonly<Ref<boolean>>;
+    rendererStatus: Readonly<Ref<RendererStatus>>;
 }
 /**
  * Vue-side wrapper for the imperative `createAurora` runtime.
@@ -56,25 +55,17 @@ export interface UseAuroraReturn {
  * 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
+ * a cheap, un-armed instance and expensive GPU initialization is deferred past first paint via
  * `requestIdleCallback`, gated on the canvas's first viewport intersection
- * (composing `useIntersectionPause`). `Aurora.vue` paints a CSS-gradient
+ * (composing `useIntersectionPause`). `Aurora.vue` paints a palette-derived
  * 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.
+ * on the shader. Capture / `initStrategy: "eager"` consumers begin acquisition
+ * immediately and skip the defer; readiness still awaits the backend.
  *
- * 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.
+ * Init failures remain explicit through `rendererStatus`. An optional
+ * `onInitError` receives the attributed error; `Aurora.vue` adapts Vue's app
+ * error handler into that seam when present. The wrapper awaits backend
+ * readiness before exposing the live canvas and leaves the palette ground in
+ * place on failure.
  */
 export declare function useAurora(canvasRef: Ref<HTMLCanvasElement | null>, configSource: ConfigSource<AuroraConfig>, runtimeOptions?: AuroraRuntimeOptions, adaptiveOptions?: UseAuroraAdaptiveOptions): UseAuroraReturn;

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

@@ -16,27 +16,29 @@ import type { WebGPUCanvasFrame } from "../../../composables/glass/webgpu/useWeb
 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";
+import type { UsePointerVelocityField } from "../../../composables/motion/pointer/usePointerVelocityField";
 export interface AuroraWGPUSetupDeps {
     canvas: HTMLCanvasElement;
+    /** Live canvases present opaque; capture canvases retain premultiplied alpha. */
+    opaquePresentation: boolean;
     /** The cursor strength ceiling + radius (the runtime's imperative setters write these). */
     getCursorScalars: () => AuroraCursorScalars;
     getConfig: () => AuroraConfig;
     getReducedMotion: () => boolean;
+    /** Resolve shader time while pointer physics retain the real frame delta. */
+    getRenderTime: (elapsedSec: number) => number;
     /**
-     * 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.
+     * Shared viz-pointer-physics field. The WGPU frame callback feeds
+     * `tick(deltaMs)` on the same field instance as WebGL2; it owns no rAF.
      */
     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.
+     * 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
+     * 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.
      */

package/dist/components/aurora/constants/budget.d.ts

@@ -1,35 +1,24 @@
-/**
- * AV.W7 F6 — the WebGL-surface perf BUDGET constants (the named ceilings).
- *
- * Promotes the formerly-magic `Math.min(dpr, 2)` literal that lived inline in
- * the aurora + goo-blob `resize()` paths (the `2` was un-named in both) to ONE
- * named ceiling, and adds the consumer-preset budget caps the SOTA crosswalk
- * §2.F F6 calls for. A preset that exceeds a cap is CLAMPED at upload, so a
- * consumer cannot blow the frame/VRAM budget by over-authoring a config.
- *
- * Token-first (the wave precept): these are the CPU-side numeric ceilings.
- * They are NOT magic numbers scattered across runtimes — every WebGL surface
- * reads the same export, so a tuning change lands in one place.
- */
+/** Shared CPU-side ceilings for GPU surface work. Authored values are clamped at
+ * upload so a configuration cannot exceed the frame or VRAM budget. */
 /**
  * The device-pixel-ratio clamp. A retina/4K display reports `devicePixelRatio`
  * 2–3+; rendering a full-viewport `backdrop-filter`-adjacent WebGL surface at
  * 3× is ~2.25× the fill of 2× for no perceptible gain on a drift background.
  * Cap the backing-store resolution at 2× — the single biggest VRAM/fill lever
- * after the offscreen-park. Consumed by aurora's + goo-blob's `resize()`.
+ * after offscreen parking. Consumed by Aurora and Blob backing-store sizing.
  */
 export declare const AV_DPR_MAX = 2;
 /**
- * BB.W-PERF-PRODUCER A′-5 — the aurora decorative-WASH DPR ceiling, SUB-2× and
- * DISTINCT from the focal goo-blob's {@link AV_DPR_MAX}. The aurora atmosphere is a
+ * The Aurora decorative-wash DPR ceiling, distinct from the focal Blob's
+ * {@link AV_DPR_MAX}. The aurora atmosphere is a
  * heavily-blurred drift background, not a sharp-silhouette creature: backing it at
- * full-viewport 2× (the value.js LP1 trace: ~2880×1800, ~21.8 MB native heap) is
+ * full-viewport 2× (~2880×1800, ~21.8 MB native heap) is
  * visually indistinguishable from 1.5× on a drift wash (the per-pixel FBM is
  * already smoothed below the DPR-2 detail floor), so the 1.5× ceiling quarters the
- * GPU memory + per-composite raster for no perceptible loss. The FOCAL goo-blob
- * KEEPS {@link AV_DPR_MAX} = 2 — its silhouette is sharp; only the aurora wash
+ * GPU memory and composite raster cost without perceptible loss. The focal Blob
+ * keeps {@link AV_DPR_MAX} = 2 because its silhouette is sharp; only Aurora
  * reads this sub-cap. This is the CPU-side backing-store DIMENSION only; it never
- * reaches the shader (`aurora.frag` is byte-fenced — the GL fence is absolute).
+ * reaches the shader.
  */
 export declare const AV_AURORA_DPR_MAX = 1.5;
 /**
@@ -62,10 +51,8 @@ export declare function clampBudget(value: number, min: number, max: number): nu
  */
 export declare function resolveBudgetDpr(): number;
 /**
- * BB.W-PERF-PRODUCER A′-5 — resolve the budget-clamped backing-store DPR for the
- * aurora decorative WASH, at the SUB-2× {@link AV_AURORA_DPR_MAX} ceiling (distinct
- * from {@link resolveBudgetDpr}'s focal 2×). SSR-safe (returns `1` when `window` is
- * absent). The single CPU-side reader is aurora's `runtime.ts` `resize()`; the
- * focal goo-blob keeps {@link resolveBudgetDpr}.
+ * Resolve the backing-store DPR for the Aurora decorative wash at the
+ * {@link AV_AURORA_DPR_MAX} ceiling. SSR-safe; returns `1` without `window`.
+ * Focal Blob surfaces use {@link resolveBudgetDpr} instead.
  */
 export declare function resolveAuroraWashDpr(): number;