@mkbabb/glass-ui 6.0.0 → 8.0.0

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

@@ -1,102 +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";
+import { type RendererStatus } from "../../../composables/glass/webgpu/useGpuSubstrate.js";
+import type { AuroraConfig, AuroraInstance } from "../constants/presets.js";
 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) when no handler
-     * is supplied. `Aurora.vue` adapts its Vue `app.config.errorHandler` into
-     * this callback; direct composable consumers provide their own handler.
+     * 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
@@ -104,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
@@ -125,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/{composables/glass → components/aurora/composables}/textureUpload.d.ts

@@ -1,22 +1,20 @@
 /**
- * The ONE shared texture-upload primitive (BG.W-AUR-IMAGE-SOURCE).
+ * The ONE shared texture-upload primitive.
  *
  * A photo entering a dual-engine (WebGL2 + WebGPU) shader family has ONE genuine
- * cross-engine hazard: the WebGL2 and WebGPU uploads DIFFER on premultiply /
- * colour-space / flip-Y defaults (gpuweb #4356; Safari's
+ * cross-engine hazard: the WebGL2 and WebGPU uploads differ on premultiply,
+ * colour-space and flip-Y defaults (gpuweb #4356; Safari's
  * `copyExternalImageToTexture(ImageBitmap)` history). Left ad-hoc per site it bites
  * invisibly and per-backend. This module NORMALISES the decode + declares the SAME
  * flag set EXPLICITLY on both upload legs, so a texture reads identically on Chromium
  * and WebKit — the single seam every image-consuming viz routes through.
  *
- * The ≥2-consumer bar is met by construction: `<Aurora source="image">` is consumer
- * #1 (this wave BUILDS the seam); `BD.W-DOT-IMAGE` (the dot-matrix image variant) is
- * the booked consumer #2 — whichever landed first BUILDS it, the other CONSUMES it
- * (the first-to-land-builds contract). Recorded in
+ * `<Aurora source="image">` consumes this upload seam. Further image-backed
+ * substrates can share it without adding another texture path.
  * `docs/consumer-evidence/texture-upload.md`.
  *
- * INTERNAL — off the public `src/composables/glass/index.ts` barrel (the WebGL2 /
- * WebGPU substrates are likewise): aurora + dot-image compose it via a direct
+ * Internal and absent from the public `src/composables/glass/index.ts` barrel, like the
+ * WebGL2 and WebGPU substrates: Aurora and dot-image compose it via a direct
  * relative import.
  *
  * The decode contract (BOTH legs share it):
@@ -24,25 +22,17 @@
  * so the decoded bytes are raw sRGB-encoded, un-premultiplied — the shader owns the
  * sRGB→linear transfer + the premultiply-on-display, exactly like the procedural path.
  */
-/** The shared decode options — the ONE normalised `createImageBitmap` flag set. */
-export declare const IMAGE_DECODE_OPTIONS: ImageBitmapOptions;
 /**
  * An already-uploadable image source — a decoded bitmap or a live DOM raster that
  * both `gl.texImage2D` and `queue.copyExternalImageToTexture` accept directly.
  */
 export type UploadableImageSource = ImageBitmap | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageData;
 /**
- * Anything a consumer may hand the axis: a URL string / `Blob` (needs a decode) OR an
+ * Anything a consumer may hand the axis: a URL string, `Blob` (needs a decode) OR an
  * already-uploadable source (passed straight through). `resolveImageSource` normalises
  * every form to an {@link UploadableImageSource} via the shared decode contract.
  */
 export type ImageInputSource = UploadableImageSource | Blob | string;
-/**
- * Decode a `Blob` to an `ImageBitmap` through the shared normalised flag set. The
- * single decode home — a consumer NEVER re-spells `createImageBitmap` with its own
- * (divergent) options.
- */
-export declare function decodeImageBitmap(blob: Blob): Promise<ImageBitmap>;
 /**
  * Normalise any {@link ImageInputSource} to an uploadable source. A URL string is
  * fetched → blob → decoded; a `Blob` is decoded; an already-uploadable source is
@@ -56,11 +46,6 @@ export declare function resolveImageSource(src: ImageInputSource): Promise<Uploa
  * texture creation has exactly ONE home (the anti-evasion floor). DOM-only (`ImageData`).
  */
 export declare function placeholderImageSource(): ImageData;
-/** The intrinsic pixel dimensions of an uploadable source (both legs size the texture from it). */
-export declare function imageSourceDimensions(src: UploadableImageSource): {
-    width: number;
-    height: number;
-};
 /** WebGL2 upload options — the sampling register the texture is created with. */
 export interface WebGL2TextureOptions {
     /** Min/mag filter. Default `LINEAR` (the smooth-bokeh dissolve register). */

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
@@ -15,28 +15,23 @@
  * 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";
+import type { OklchStop } from "../../../composables/color/index.js";
+import type { UniformLocations } from "./glSetup.js";
 /**
- * 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";
+import { type AuroraConfig } from "../constants/presets.js";
 export declare const MEDIUM_ID: {
     readonly smooth: 0;
     readonly pastel: 1;
@@ -73,37 +68,20 @@ export declare const WARP_ID: {
     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
+ * 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
- * `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 +95,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,42 +3,41 @@
  *
  * 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.
  */
-import { type AuroraConfig } from "../constants/presets";
-import type { AuroraCursorUniforms } from "./uniformBridge";
+import { type AuroraConfig } from "../constants/presets.js";
+import type { AuroraCursorUniforms } from "./uniformBridge.js";
 /** 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";
+import { type AuroraConfig } from "../constants/presets.js";
+import type { AuroraCursorUniforms } from "./uniformBridge.js";
 /** 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

@@ -1,27 +1,25 @@
 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";
+import { type AuroraRuntimeOptions } from "./runtime.js";
+import { type ConfigSource } from "./configSource.js";
+import type { AuroraConfig } from "../constants/presets.js";
+import { type RendererStatus } from "../../../composables/glass/webgpu/rendererStatus.js";
 /**
- * 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>`.
@@ -38,11 +36,10 @@ 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>>;
@@ -58,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. when using `Aurora.vue`, install a Vue global `app.config.errorHandler`
- *      (the component adapts it into `onInitError`), 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/useCursorInteraction.d.ts

@@ -1,6 +1,6 @@
 import { type Ref } from "vue";
-import { type ConfigSource } from "./configSource";
-import type { AuroraConfig } from "../constants/presets";
+import { type ConfigSource } from "./configSource.js";
+import type { AuroraConfig } from "../constants/presets.js";
 export interface CursorInteractionOptions {
     /** Fires `setCursor(x,y,strength)` for continuous swirl. */
     setCursor: (x: number, y: number, strength?: number) => void;