@mkbabb/glass-ui 4.2.0 → 6.0.0

package/dist/composables/dom/useUserInvalidAria.d.ts

@@ -1,14 +1,10 @@
+/**
+ * Options for {@link useUserInvalidAria}. Empty since the legacy
+ * `fallbackClasses` knob was retired at BG.NF.2 W-LEGACY-LADDER-COLLAPSE
+ * (`:user-invalid` is Baseline on the target set); the shape is kept as the
+ * canonical options seam for future extension.
+ */
 export interface UseUserInvalidAriaOptions {
-    /**
-     * Also toggle the `.user-invalid-fallback` / `.user-valid-fallback`
-     * classes the W4.1 CSS rungs key off (for engines without `:user-invalid`
-     * support).
-     *
-     * Default: auto — `true` only when `CSS.supports('selector(:user-invalid)')`
-     * resolves `false`. Pass an explicit boolean to force the path (e.g. for a
-     * test that stubs feature detection).
-     */
-    fallbackClasses?: boolean;
 }
 export interface UseUserInvalidAriaReturn {
     /**
@@ -29,4 +25,4 @@ export interface UseUserInvalidAriaReturn {
  * the `input` handler only CLEARS — never sets — so a programmatic `v-model`
  * write can at worst clear a stale error, never mint a false one.
  */
-export declare function useUserInvalidAria(opts?: UseUserInvalidAriaOptions): UseUserInvalidAriaReturn;
+export declare function useUserInvalidAria(_opts?: UseUserInvalidAriaOptions): UseUserInvalidAriaReturn;

package/dist/composables/glass/ambientHueHistogram.d.ts

@@ -0,0 +1,27 @@
+/** A 12-bucket chroma×alpha-weighted OKLCh hue accumulator over the SAME pixel pass. */
+export interface HueHistogram {
+    /** chroma×alpha mass per hue bucket (the bucket weight). */
+    weight: Float64Array;
+    /** Σ chroma×alpha·cos(h) per bucket (for the circular-mean refine). */
+    sumCos: Float64Array;
+    /** Σ chroma×alpha·sin(h) per bucket. */
+    sumSin: Float64Array;
+    /** total chroma×alpha mass (the null-detection denominator numerator). */
+    totalMass: number;
+    /** total pixels accumulated (the null-mass denominator). */
+    n: number;
+}
+export declare function makeHueHistogram(): HueHistogram;
+/**
+ * Bin ONE sRGB pixel (composited triple, already over-white) into the histogram,
+ * weighted by its OKLCh chroma × the source alpha — a low-chroma/gray pixel
+ * contributes ~0. The sRGB→OKLCh math is value.js's primitives (NOT hand-rolled).
+ */
+export declare function accumulateHuePixel(h: HueHistogram, r: number, g: number, b: number, alpha: number): void;
+/**
+ * Resolve the histogram → a complete `oklch()` ambient-hue string, or `transparent`
+ * for a NULL (gray) sample. The modal bucket's chroma-weighted CIRCULAR MEAN is the
+ * picked hue; it is emitted at the FIXED sub-perceptual chroma/L (a HUE event, never
+ * the backdrop's saturation).
+ */
+export declare function resolveAmbientHue(h: HueHistogram): string;

package/dist/composables/glass/backdropLuminanceSample.d.ts

@@ -0,0 +1,56 @@
+/** The per-sample result — the luminance AND the ambient hue (the FREE rider). */
+export interface SampleResult {
+    /** WCAG relative luminance of the sampled backdrop (0..1). */
+    luma: number;
+    /** A complete `oklch()` ambient-hue string, or `transparent` for a gray null. */
+    ambientHue: string;
+}
+/**
+ * The KNOWN background-layer source for the ANIMATED case — an HTMLCanvasElement, a
+ * getter, a CSS selector resolved against the document, or null. The observer's
+ * `backgroundCanvas` option is this type.
+ */
+export type BackgroundCanvasSource = HTMLCanvasElement | (() => HTMLCanvasElement | null) | string | null;
+/** The downsample resolution for the animated-field read (a 32×32 mean). */
+export declare const SAMPLE_DOWNSAMPLE = 32;
+export declare const FIELD_ALPHA_FLOOR = 0.02;
+/** BG.W-FIELD-ACCENT-RECONCILE — the library convention marking the ONE shell
+ *  field canvas (the recessive shell `<Aurora>` the demo chassis mounts behind every
+ *  non-focal route; also the WS8 BACKDROP-SAMPLE marker). A glass surface that does
+ *  NOT name an explicit `backgroundCanvas` auto-discovers this canvas so it samples
+ *  the LIVE field rather than a static stack-walk; absent it (a focal route where the
+ *  shell stands down, an SSR scope) the static `elementsFromPoint` path is the floor. */
+export declare const SHELL_FIELD_CANVAS_SELECTOR = "[data-glass-field-canvas] canvas, canvas[data-glass-field-canvas]";
+/**
+ * Resolve the animated-case source canvas from the observer's `backgroundCanvas`
+ * option (an element, a getter, a selector, or nullish). A nullish source
+ * auto-discovers the shell field canvas — the rewire to the live shell field
+ * (backward-safe: no field canvas → null → the static elementsFromPoint path).
+ */
+export declare function resolveSourceCanvas(src: BackgroundCanvasSource | undefined): HTMLCanvasElement | null;
+/**
+ * Robust CSS-color → sRGB `[r,g,b,a]`. `parseRgb` is the fast path for the legacy
+ * `rgb()/rgba()` serialization; ANY other valid CSS color form — the MODERN
+ * `oklch()` / `color(srgb …)` / `hsl()` tokens the warm-cream demo basis resolves to —
+ * is normalized by painting it onto the 1×1 corner of the reused 2D canvas (passed in)
+ * and reading the composited pixel back (`getImageData` ALWAYS returns integer sRGB
+ * whatever the source space). BG.W-GLASS-SIGNAL-TRUTH: without this `sampleStatic`
+ * returned null on a `color(srgb …)`/`oklch(…)` backdrop and wrote NOTHING — the static
+ * floor was a DEAD channel. The static floor is now writer-true over ANY backdrop.
+ */
+export declare function normalizeToRgb(css: string, ctx: CanvasRenderingContext2D | null): [number, number, number, number] | null;
+/**
+ * Sample the ANIMATED backdrop: downsample the resolved source canvas under the
+ * surface's bounding box → mean relative luminance + the ambient-hue histogram (a FREE
+ * rider over the SAME pixel pass). Returns null if no source / an all-transparent
+ * (unrendered) field / a tainted canvas — the caller falls to the static stack-walk.
+ */
+export declare function sampleAnimated(el: HTMLElement, source: HTMLCanvasElement | null, ctx: CanvasRenderingContext2D | null): SampleResult | null;
+/**
+ * Sample the STATIC backdrop: stack-walk `elementsFromPoint` at the surface centre,
+ * read the first element under it with a resolved non-transparent background, un-wrap
+ * the `var(--token)` through the resolveTokenColor leaf → relative luminance + the
+ * ambient hue (the single resolved background color binned the SAME way). The reusable
+ * 2D context (for the modern-color normalization paint-read) is passed in.
+ */
+export declare function sampleStatic(el: HTMLElement, ctx: CanvasRenderingContext2D | null): SampleResult | null;

package/dist/composables/glass/backdropSampleMath.d.ts

@@ -0,0 +1,5 @@
+/** WCAG relative luminance of an sRGB triple [0..255]. */
+export declare function relLuminance(r: number, g: number, b: number): number;
+/** Parse a `rgb()/rgba()` string → [r,g,b,a] (the un-wrapped concrete form). */
+export declare function parseRgb(str: string): [number, number, number, number] | null;
+export declare function isCanvas(v: unknown): v is HTMLCanvasElement;

package/dist/composables/glass/textureUpload.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The ONE shared texture-upload primitive (BG.W-AUR-IMAGE-SOURCE).
+ *
+ * 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
+ * `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
+ * `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
+ * relative import.
+ *
+ * The decode contract (BOTH legs share it):
+ *   `createImageBitmap(blob, { premultiplyAlpha: "none", colorSpaceConversion: "none" })`
+ * 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
+ * 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
+ * returned as-is. Deterministic + DOM-light (only the URL path touches `fetch`).
+ */
+export declare function resolveImageSource(src: ImageInputSource): Promise<UploadableImageSource>;
+/**
+ * A 1×1 mid-grey placeholder source — the texture a `source:"image"` program samples
+ * BEFORE its real photo has decoded (so the sampler is always complete + the first frame
+ * is a neutral wash, never black garbage). Routed through the SAME upload primitive so
+ * 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). */
+    linearFilter?: boolean;
+    /** Wrap mode. Default `CLAMP_TO_EDGE` (a cover-fit backdrop never tiles). */
+    clampToEdge?: boolean;
+}
+/**
+ * Upload an image into a fresh WebGL2 texture through the shared explicit flag set.
+ * Returns the bound texture (the caller sets the sampler uniform to its unit + binds
+ * it per draw). The premultiply/colour-space/flip-Y flags are declared explicitly,
+ * then restored so the primitive leaves no global GL residue.
+ */
+export declare function uploadImageTextureWebGL2(gl: WebGL2RenderingContext, source: UploadableImageSource, opts?: WebGL2TextureOptions): WebGLTexture;
+export interface WebGPUImageTexture {
+    texture: GPUTexture;
+    width: number;
+    height: number;
+}
+/**
+ * Upload an image into a fresh WebGPU texture through the shared explicit flag set.
+ * The `copyExternalImageToTexture` destination declares `premultipliedAlpha: false`
+ * EXPLICITLY (the WebGPU twin of the WebGL2 `UNPACK_PREMULTIPLY_ALPHA_WEBGL:false`) and
+ * the source declares `flipY: false` — so the decoded bytes land in the texture
+ * byte-identically to the WebGL2 leg (the cross-engine parity contract). Returns the
+ * texture + its dims (the caller builds the sampler + the bind group entry).
+ */
+export declare function uploadImageTextureWebGPU(device: GPUDevice, source: UploadableImageSource): WebGPUImageTexture;

package/dist/composables/glass/useGlassBackdropLuminance.d.ts

@@ -1,4 +1,5 @@
 import { type Ref } from "vue";
+import { type BackgroundCanvasSource } from "./backdropLuminanceSample";
 /** The discrete bucket the observer derives + writes (re-engages the W55 machinery). */
 export type GlassBackdropBucket = "light" | "dark";
 export interface UseGlassBackdropLuminanceOptions {
@@ -9,7 +10,7 @@ export interface UseGlassBackdropLuminanceOptions {
      * instead of the static `elementsFromPoint` stack-walk. The aurora/blob `<canvas>`
      * the surface floats over.
      */
-    backgroundCanvas?: HTMLCanvasElement | (() => HTMLCanvasElement | null) | string | null;
+    backgroundCanvas?: BackgroundCanvasSource;
     /**
      * Force the LIVE periodic re-sample loop on (mirrors the `data-glass-sample="live"`
      * attribute on the target). Default: read from the target's
@@ -35,17 +36,73 @@ export interface UseGlassBackdropLuminanceOptions {
      * `--glass-backdrop-luma` is written (a continuous-strength consumer).
      */
     writeBucket?: boolean;
+    /**
+     * BI.W-DOCK-LUMA-SHARE — mark this as the SHARED per-ROUTE observer. It stamps
+     * `GLASS_BACKDROP_SHARED_ATTR` on its target (the route/stage scope) so descendant
+     * glass surfaces (docks) DETECT the coverage and STAND DOWN — inheriting the route's
+     * `--glass-backdrop-luma` / `--glass-backdrop` / `--glass-ambient-*` via the cascade
+     * rather than each mounting its own readback loop (12 per-dock observers over ONE
+     * aurora → ONE per-route readback). Default false: a per-SURFACE observer, which
+     * stands down when a shared ancestor covers it and self-samples as the honest floor
+     * when standalone. N docks over the SAME aurora read ONE per-route signal.
+     */
+    shared?: boolean;
 }
 export interface UseGlassBackdropLuminanceControls {
     /** The last sampled backdrop relative luminance (0..1), or null before the first sample. */
     readonly luma: Readonly<Ref<number | null>>;
     /** The last derived bucket, or null before the first sample. */
     readonly bucket: Readonly<Ref<GlassBackdropBucket | null>>;
+    /**
+     * The observer's explicit sample provenance. A live request is never represented
+     * as a static sample: a missing or unreadable canvas reports `unavailable`.
+     */
+    readonly sample: Readonly<Ref<GlassBackdropSample>>;
     /** Force one sample now (bypasses the throttle — used on mount + resize-settle). */
     sampleNow: () => void;
     /** Stop the loop + detach every observer/listener. */
     dispose: () => void;
 }
+export type GlassBackdropSample = {
+    state: "pending";
+    mode: "live" | "static";
+    source: "canvas" | "elements";
+} | {
+    state: "sampled";
+    mode: "live" | "static";
+    source: "canvas" | "elements";
+    luma: number;
+    ambientHue: string;
+    sampledAt: number;
+    targetRect: GlassBackdropTargetRect;
+} | {
+    state: "unavailable";
+    mode: "live" | "static";
+    source: "canvas" | "elements";
+    reason: "source-unavailable" | "sample-unavailable";
+    sampledAt: number;
+    targetRect: GlassBackdropTargetRect;
+};
+export interface GlassBackdropTargetRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * BI.W-DOCK-LUMA-SHARE — the shared-coverage marker. A SHARED route observer
+ * (`shared: true`) stamps this attribute on its target (the route/stage scope); a
+ * per-SURFACE observer detects it on an ANCESTOR (`.closest`) and STANDS DOWN —
+ * inheriting the route's `--glass-backdrop-luma` / `--glass-backdrop` /
+ * `--glass-ambient-*` via the registered inheriting @property cascade instead of
+ * mounting its OWN `drawImage + getImageData` readback loop (the 12 per-dock observers
+ * over ONE DockStage aurora collapse to ONE per-route readback — PERF-6/FAM-5). A DOM
+ * marker, NOT provide/inject: provide/inject does not cross the `<slot>` boundary (the
+ * DockStage renders `<slot>`, the docks are slotted from the route, so the slotted
+ * content's instance-parent is the slot OWNER not the stage), and the marker rides the
+ * SAME DOM ancestry the inheriting custom property itself cascades over.
+ */
+export declare const GLASS_BACKDROP_SHARED_ATTR = "data-glass-backdrop-shared";
 /**
  * The sampled-luminance observer. Wire it on a glass surface (the dock root, a
  * content-glass panel) to write a DYNAMIC backdrop-luminance signal that refines the

package/dist/composables/glass/useSpecularPointer.d.ts

@@ -1,4 +1,4 @@
-import { ref, type CSSProperties } from "vue";
+import { type ComputedRef, type CSSProperties, type MaybeRefOrGetter } from "vue";
 /**
  * `useSpecularPointer` — the EVOLUTION of `useSpecularTracking` (BB.W-LENSING). It
  * writes the catch-light POSITION (`--mouse-x`/`--mouse-y`, as today) PLUS the
@@ -23,11 +23,30 @@ import { ref, type CSSProperties } from "vue";
  * centred 50% and `--specular-angle` to its `0deg` static rest). The composable
  * disposes the core (cancel the pending rAF + drop the cached PRM listener) on scope
  * teardown.
+ *
+ * BG.W-GLASS-DYNAMICS — the OPTIONAL press-couple (absorbs 13.5, soft-gated by F5.1).
+ * A consumer may pass `press` (a 0..1 press scalar — a `useSpringPress` `.value`, or
+ * any press signal); it is folded reactively into the emitted style as the ONE
+ * `--glass-btn-press-t` channel the `.glass-material::before` specular magnitude reads
+ * (material.css). Reusing the SINGLE press channel (never a forked `--*-press-t`) keeps
+ * ONE drive, two legs — the gleam SWELLS + SETTLES with the press spring. The merge is
+ * a `computed` so the press tracks the spring INDEPENDENTLY of pointer moves (a press
+ * settles while the pointer is still). SOFT-GATED: when `press` is OMITTED the emitted
+ * style carries NO press channel (the CSS `--glass-btn-press-t` default 0 holds — no
+ * hard F5.1 dependency), and the position/angle write is byte-identical to before.
  */
+export interface UseSpecularPointerOptions {
+    /** Optional 0..1 press scalar (soft-gated) folded into `--glass-btn-press-t`. */
+    press?: MaybeRefOrGetter<number>;
+}
 export interface UseSpecularPointer {
-    /** Bind to the host element's `:style`. Carries `--mouse-x/--mouse-y` + `--specular-angle`. */
-    specularStyle: ReturnType<typeof ref<CSSProperties>>;
+    /**
+     * Bind to the host element's `:style`. Carries `--mouse-x/--mouse-y` +
+     * `--specular-angle` (+ the press-coupled `--glass-btn-press-t` when `press` is
+     * supplied).
+     */
+    specularStyle: ComputedRef<CSSProperties>;
     /** Bind to the host's `@pointermove`. Schedules the rAF-coalesced position+angle write (PRM-gated). */
     onPointerMove: (event: PointerEvent) => void;
 }
-export declare function useSpecularPointer(): UseSpecularPointer;
+export declare function useSpecularPointer(options?: UseSpecularPointerOptions): UseSpecularPointer;

package/dist/composables/glass/useSpecularTracking.d.ts

@@ -2,7 +2,7 @@ import { ref, type CSSProperties } from "vue";
 /**
  * `useSpecularTracking` — the pointer-anchored moving-specular write seam
  * (AX.W09). The single DRY home for the catch-light position write that was
- * hand-copied VERBATIM in `Card.vue` and `DockIconButton.vue`.
+ * hand-copied VERBATIM in `Card.vue` and `DockControl.vue`.
  *
  * On pointer-move it writes the cursor position (`--mouse-x`/`--mouse-y`, as
  * percentages of the host box) onto the host's inline style; the unified

package/dist/composables/glass/wave/waveField.d.ts

@@ -83,6 +83,14 @@ export declare function facePlateau(g: Vec2, inset: number, uvDeriv: Vec2): numb
  * swirled coordinate.
  */
 export declare function cursorSwirl(g: Vec2, cursor: Vec2, strength: number, radius: number): Vec2;
+/**
+ * The `waveFlow` second-flow FREQUENCY RATIO (shared across JS↔GLSL↔WGSL — the round-trip fence).
+ * The secondary counter-flow term samples the curl at `warpFreq · this` so it drifts on a slightly
+ * different spatial scale (the anti-loop variety) while staying the SAME order of magnitude as the
+ * primary. `0.6 · 1.833333 ≈ 1.1` reproduces concentric's unit-scale pair; the GLSL/WGSL
+ * transcriptions carry the identical literal.
+ */
+export declare const WAVE_FLOW_SECOND_RATIO = 1.833333;
 /**
  * A CONTINUOUS divergence-free flow warp gated by the traveling wave — the SMOOTH twin of
  * `cellTwist` for surfaces that need an unbroken coordinate (the level-set contours shatter
@@ -91,8 +99,21 @@ export declare function cursorSwirl(g: Vec2, cursor: Vec2, strength: number, rad
  * the SAME traveling Gaussian crest sweeping along `waveDir`. So the contours flow + twist as
  * the wave passes OVER and THROUGH them, with NO cell-boundary discontinuity. Returns the
  * warped coordinate.
+ *
+ * BG.W-GRID-AFFINE — the LOCALLY-AFFINE frequency law. `warpFreq` is the HOST-supplied spatial
+ * frequency (in the caller's OWN coordinate units) at which the curl-flow potential is sampled.
+ * The caller passes a frequency an ORDER OF MAGNITUDE BELOW its own grid/contour frequency, so
+ * the warp-displacement gradient is ~constant across any ONE cell (the warp Jacobian is locally
+ * affine): the major gridlines bow as ONE smooth continuous curve across the frame, NEVER the
+ * per-cell crackle a cell-scale sampling frequency produces. liquid-grid feeds a CELL-scale
+ * coordinate (`uv · gridScale`, span ~14–40 cells) so it passes a tiny `warpFreq` (~0.03 →
+ * wavelength of MANY cells); concentric feeds a UNIT-scale domain (`vUv`, span ~1) so it passes
+ * the unit-scale `0.6`. The amplitude is UNCHANGED (the curl magnitude is the intrinsic q-space
+ * gradient at the fixed `CURL_EPS`, independent of `warpFreq` — only the spatial frequency drops,
+ * the bow amplitude `twistMax · env` is preserved). The `t·` drift coefficients are host-agnostic
+ * (they set the flow's temporal evolution rate in q-space, independent of `warpFreq`).
  */
-export declare function waveFlow(curlFn: (p: Vec2) => Vec2, g: Vec2, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number, twistMax: number, amp: number): Vec2;
+export declare function waveFlow(curlFn: (p: Vec2) => Vec2, g: Vec2, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number, twistMax: number, amp: number, warpFreq?: number): Vec2;
 /**
  * A LOW-octave value-noise topography H(p) — the scalar field concentric extracts level-set
  * contours of. `octaves` LOW (3) keeps the nested loops CLEAN (not high-freq speckle — the

package/dist/composables/glass/wave/waveField.glsl.d.ts

@@ -1 +1 @@
-export declare const WAVE_FIELD_GLSL = "\n#ifndef WAVE_FIELD_TAU\n#define WAVE_FIELD_TAU 6.283185307179586\n#endif\n\n// The traveling-wave envelope \u2014 a moving Gaussian crest band sweeping along waveDir.\nfloat travelingEnvelope(vec2 pivot, float t, vec2 waveDir, float waveK, float waveOmega, float waveSigma) {\n  float coord = dot(pivot, waveDir) * waveK - t * waveOmega;\n  float crest = fract(coord / WAVE_FIELD_TAU);\n  float z = (crest - 0.5) * 2.0;\n  return exp(-(z * z) / max(waveSigma, 1e-3));\n}\n\n// The curl-direction scalar \u2014 the smooth low-freq director the per-cell twist follows.\nfloat curlScalar(vec2 cc, float t) {\n  vec2 f = curlFBM(vec2(cc.x * 0.5 + t * 0.08, cc.y * 0.5 - t * 0.06));\n  return clamp(f.x, -1.0, 1.0);\n}\n\n// The directed-twist FLOOR (the visibility cure): keep the curl SIGN (adjacent cells lean\n// together) but floor the magnitude so a crest-band cell ALWAYS rotates decisively.\n#ifndef WAVE_FIELD_TWIST_FLOOR\n#define WAVE_FIELD_TWIST_FLOOR 0.62\n#endif\nfloat directedTwist(float s, float floorMag) {\n  float mag = max(floorMag, abs(s));\n  float sgn = tanh(s * 6.0);\n  return sgn * mag;\n}\n\n// \u2500\u2500 The FACE leaf (the structurally-absent RE-INVENT \u2014 height-lit filled cell interior) \u2500\u2500\n// Defined ABOVE cellTwist: cellTwist rides cellHeight via the driver so twist + face read ONE\n// envelope.\n\n// The sheet displacement at a cell center = the EXACT traveling-wave scalar the twist rides.\nfloat cellHeight(vec2 cc, float t, vec2 waveDir, float waveK, float waveOmega, float waveSigma, float amp) {\n  return travelingEnvelope(cc, t, waveDir, waveK, waveOmega, waveSigma) * amp;\n}\n\n// The pre-twist driver (FOLD A): the cell pivot cc + the crest envelope env the twist AND the\n// face both ride. The face samples height/relief at THIS pre-twist cc (floor(twisted_g) at the\n// crest lights a NEIGHBOUR cell). cc in .xy, env in .z.\nvec3 cellDriver(vec2 g, float cellSize, float t, vec2 waveDir, float waveK, float waveOmega,\n                float waveSigma, float amp) {\n  float cs = max(cellSize, 1e-3);\n  vec2 cc = (floor(g / cs) + 0.5) * cs;\n  float env = cellHeight(cc, t, waveDir, waveK, waveOmega, waveSigma, amp);\n  return vec3(cc, env);\n}\n\n// The central-difference slope of cellHeight across a cell (eps = 0.5\u00B7cellSize) \u2014 derivative-\n// FREE (NO dFdx on the height) \u2192 Safari WebGL2-safe. Returns \u2207H.\nvec2 faceRelief(vec2 cc, float cellSize, float t, vec2 waveDir, float waveK, float waveOmega,\n                float waveSigma, float amp) {\n  float eps = max(cellSize, 1e-3) * 0.5;\n  float hxp = cellHeight(cc + vec2(eps, 0.0), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  float hxm = cellHeight(cc - vec2(eps, 0.0), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  float hyp = cellHeight(cc + vec2(0.0, eps), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  float hym = cellHeight(cc - vec2(0.0, eps), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  return vec2((hxp - hxm) / (2.0 * eps), (hyp - hym) / (2.0 * eps));\n}\n\n// Soft inset-square coverage inside a (warped) cell \u2014 the filled FACE plateau. d is the distance\n// into the cell from the nearest gutter (the Golus triangle-wave); the inset retreats as it grows\n// (the squash). aa = the shader's fwidth(g) (JS passes a fixed uvDeriv).\nfloat facePlateau(vec2 g, float inset, vec2 uvDeriv) {\n  vec2 tri = 1.0 - abs(fract(g) * 2.0 - 1.0);\n  float d = min(tri.x, tri.y);\n  float aa = max(uvDeriv.x, uvDeriv.y) * 1.5;\n  return smoothstep(inset, inset + 2.0 * aa, d);\n}\n\n// The cell-local twist about each cell's own center, gated by the traveling wave + directed\n// by the curl flow. amp is the spring-eased envelope amplitude the JS host drives. FOLD C: the\n// TWIST_FLOOR is crest-gated by env so OFF-crest cells relax to flat calm paper (the traveling\n// read, not static foil).\nvec2 cellTwist(vec2 g, float cellSize, float t, vec2 waveDir, float waveK, float waveOmega,\n               float waveSigma, float twistMax, float shearMax, float amp) {\n  vec3 drv = cellDriver(g, cellSize, t, waveDir, waveK, waveOmega, waveSigma, amp);\n  vec2 cc = drv.xy;\n  float env = drv.z;\n  float floorMag = WAVE_FIELD_TWIST_FLOOR * env;   // FOLD C: crest-gated floor\n  float theta = twistMax * env * directedTwist(curlScalar(cc, t), floorMag);\n  float shear = shearMax * env * directedTwist(curlScalar(cc + vec2(17.3, 9.1), t), floorMag);\n  vec2 local = g - cc;\n  float ct = cos(theta);\n  float st = sin(theta);\n  vec2 rot = vec2(ct * local.x - st * local.y, st * local.x + ct * local.y);\n  rot.x += shear * rot.y;   // a small skew so the box MORPHS, not just rotates\n  return cc + rot;\n}\n\n// The CONTINUOUS traveling-wave FLOW warp \u2014 the SMOOTH twin of cellTwist (no per-cell seam;\n// for the level-set contours that shatter into a mesh under the cell discontinuity).\nvec2 waveFlow(vec2 g, float t, vec2 waveDir, float waveK, float waveOmega, float waveSigma,\n              float twistMax, float amp) {\n  float env = travelingEnvelope(g, t, waveDir, waveK, waveOmega, waveSigma) * amp;\n  vec2 f = curlFBM(vec2(g.x * 0.6 + t * 0.05, g.y * 0.6 - t * 0.04));\n  vec2 f2 = curlFBM(vec2(g.x * 1.1 - t * 0.03, g.y * 1.1 + t * 0.035));\n  float k = twistMax * env;\n  return g + (f + f2 * 0.5) * k;\n}\n\n// The local cursor swirl \u2014 the finger twists the cells around it (re-aimed cursorBulge).\nvec2 cursorSwirl(vec2 g, vec2 cursor, float strength, float radius) {\n  vec2 to = g - cursor;\n  float d2 = dot(to, to);\n  float r = max(radius, 1e-4);\n  float theta = strength * exp(-d2 / (2.0 * r * r));\n  float ct = cos(theta);\n  float st = sin(theta);\n  return cursor + vec2(ct * to.x - st * to.y, st * to.x + ct * to.y);\n}\n\n// The LOW-octave value-noise topography \u2014 the scalar field concentric extracts contours of.\nfloat heightField(vec2 p, float octavesF, float seed) {\n  float v = 0.0;\n  float amp = 0.5;\n  float freq = 1.0;\n  float px = p.x + seed;\n  float py = p.y - seed;\n  int n = int(clamp(octavesF, 1.0, 6.0));\n  for (int i = 0; i < 6; i++) {\n    if (i >= n) break;\n    v += amp * valueNoise(px * freq, py * freq);\n    float rx = 0.8 * px - 0.6 * py;\n    float ry = 0.6 * px + 0.8 * py;\n    px = rx;\n    py = ry;\n    freq *= 2.0;\n    amp *= 0.5;\n  }\n  return v;\n}\n\n// The \u03C9=\u221A(g\u00B7k) breathing swell \u2014 basins inflate/deflate with weight.\nfloat waveSwell(float t, float phase) {\n  return sin(t * 0.35 + phase) * 0.5 + sin(t * 0.21 + phase * 1.7) * 0.5;\n}\n";
+export declare const WAVE_FIELD_GLSL = "\n#ifndef WAVE_FIELD_TAU\n#define WAVE_FIELD_TAU 6.283185307179586\n#endif\n\n// The traveling-wave envelope \u2014 a moving Gaussian crest band sweeping along waveDir.\nfloat travelingEnvelope(vec2 pivot, float t, vec2 waveDir, float waveK, float waveOmega, float waveSigma) {\n  float coord = dot(pivot, waveDir) * waveK - t * waveOmega;\n  float crest = fract(coord / WAVE_FIELD_TAU);\n  float z = (crest - 0.5) * 2.0;\n  return exp(-(z * z) / max(waveSigma, 1e-3));\n}\n\n// The curl-direction scalar \u2014 the smooth low-freq director the per-cell twist follows.\nfloat curlScalar(vec2 cc, float t) {\n  vec2 f = curlFBM(vec2(cc.x * 0.5 + t * 0.08, cc.y * 0.5 - t * 0.06));\n  return clamp(f.x, -1.0, 1.0);\n}\n\n// The directed-twist FLOOR (the visibility cure): keep the curl SIGN (adjacent cells lean\n// together) but floor the magnitude so a crest-band cell ALWAYS rotates decisively.\n#ifndef WAVE_FIELD_TWIST_FLOOR\n#define WAVE_FIELD_TWIST_FLOOR 0.62\n#endif\nfloat directedTwist(float s, float floorMag) {\n  float mag = max(floorMag, abs(s));\n  float sgn = tanh(s * 6.0);\n  return sgn * mag;\n}\n\n// \u2500\u2500 The FACE leaf (the structurally-absent RE-INVENT \u2014 height-lit filled cell interior) \u2500\u2500\n// Defined ABOVE cellTwist: cellTwist rides cellHeight via the driver so twist + face read ONE\n// envelope.\n\n// The sheet displacement at a cell center = the EXACT traveling-wave scalar the twist rides.\nfloat cellHeight(vec2 cc, float t, vec2 waveDir, float waveK, float waveOmega, float waveSigma, float amp) {\n  return travelingEnvelope(cc, t, waveDir, waveK, waveOmega, waveSigma) * amp;\n}\n\n// The pre-twist driver (FOLD A): the cell pivot cc + the crest envelope env the twist AND the\n// face both ride. The face samples height/relief at THIS pre-twist cc (floor(twisted_g) at the\n// crest lights a NEIGHBOUR cell). cc in .xy, env in .z.\nvec3 cellDriver(vec2 g, float cellSize, float t, vec2 waveDir, float waveK, float waveOmega,\n                float waveSigma, float amp) {\n  float cs = max(cellSize, 1e-3);\n  vec2 cc = (floor(g / cs) + 0.5) * cs;\n  float env = cellHeight(cc, t, waveDir, waveK, waveOmega, waveSigma, amp);\n  return vec3(cc, env);\n}\n\n// The central-difference slope of cellHeight across a cell (eps = 0.5\u00B7cellSize) \u2014 derivative-\n// FREE (NO dFdx on the height) \u2192 Safari WebGL2-safe. Returns \u2207H.\nvec2 faceRelief(vec2 cc, float cellSize, float t, vec2 waveDir, float waveK, float waveOmega,\n                float waveSigma, float amp) {\n  float eps = max(cellSize, 1e-3) * 0.5;\n  float hxp = cellHeight(cc + vec2(eps, 0.0), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  float hxm = cellHeight(cc - vec2(eps, 0.0), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  float hyp = cellHeight(cc + vec2(0.0, eps), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  float hym = cellHeight(cc - vec2(0.0, eps), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  return vec2((hxp - hxm) / (2.0 * eps), (hyp - hym) / (2.0 * eps));\n}\n\n// Soft inset-square coverage inside a (warped) cell \u2014 the filled FACE plateau. d is the distance\n// into the cell from the nearest gutter (the Golus triangle-wave); the inset retreats as it grows\n// (the squash). aa = the shader's fwidth(g) (JS passes a fixed uvDeriv).\nfloat facePlateau(vec2 g, float inset, vec2 uvDeriv) {\n  vec2 tri = 1.0 - abs(fract(g) * 2.0 - 1.0);\n  float d = min(tri.x, tri.y);\n  float aa = max(uvDeriv.x, uvDeriv.y) * 1.5;\n  return smoothstep(inset, inset + 2.0 * aa, d);\n}\n\n// The cell-local twist about each cell's own center, gated by the traveling wave + directed\n// by the curl flow. amp is the spring-eased envelope amplitude the JS host drives. FOLD C: the\n// TWIST_FLOOR is crest-gated by env so OFF-crest cells relax to flat calm paper (the traveling\n// read, not static foil).\nvec2 cellTwist(vec2 g, float cellSize, float t, vec2 waveDir, float waveK, float waveOmega,\n               float waveSigma, float twistMax, float shearMax, float amp) {\n  vec3 drv = cellDriver(g, cellSize, t, waveDir, waveK, waveOmega, waveSigma, amp);\n  vec2 cc = drv.xy;\n  float env = drv.z;\n  float floorMag = WAVE_FIELD_TWIST_FLOOR * env;   // FOLD C: crest-gated floor\n  float theta = twistMax * env * directedTwist(curlScalar(cc, t), floorMag);\n  float shear = shearMax * env * directedTwist(curlScalar(cc + vec2(17.3, 9.1), t), floorMag);\n  vec2 local = g - cc;\n  float ct = cos(theta);\n  float st = sin(theta);\n  vec2 rot = vec2(ct * local.x - st * local.y, st * local.x + ct * local.y);\n  rot.x += shear * rot.y;   // a small skew so the box MORPHS, not just rotates\n  return cc + rot;\n}\n\n// The CONTINUOUS traveling-wave FLOW warp \u2014 the SMOOTH twin of cellTwist (no per-cell seam;\n// for the level-set contours that shatter into a mesh under the cell discontinuity).\n// BG.W-GRID-AFFINE \u2014 warpFreq is the HOST-supplied curl-sampling spatial frequency (the caller's\n// own coordinate units): an order of magnitude BELOW its grid frequency so the warp is locally\n// affine (major lines bow as ONE smooth curve, no sub-cell crackle). liquid-grid (cell-scale g0)\n// passes ~0.03; concentric (unit-scale p) passes 0.6. The 1.833333 second-flow ratio transcribes\n// WAVE_FLOW_SECOND_RATIO. Amplitude unchanged \u2014 curl magnitude is the intrinsic gradient at the\n// fixed CURL_EPS, independent of warpFreq; the t-drift is host-agnostic.\nvec2 waveFlow(vec2 g, float t, vec2 waveDir, float waveK, float waveOmega, float waveSigma,\n              float twistMax, float amp, float warpFreq) {\n  float env = travelingEnvelope(g, t, waveDir, waveK, waveOmega, waveSigma) * amp;\n  vec2 f = curlFBM(vec2(g.x * warpFreq + t * 0.05, g.y * warpFreq - t * 0.04));\n  float wf2 = warpFreq * 1.833333;\n  vec2 f2 = curlFBM(vec2(g.x * wf2 - t * 0.03, g.y * wf2 + t * 0.035));\n  float k = twistMax * env;\n  return g + (f + f2 * 0.5) * k;\n}\n\n// The local cursor swirl \u2014 the finger twists the cells around it (re-aimed cursorBulge).\nvec2 cursorSwirl(vec2 g, vec2 cursor, float strength, float radius) {\n  vec2 to = g - cursor;\n  float d2 = dot(to, to);\n  float r = max(radius, 1e-4);\n  float theta = strength * exp(-d2 / (2.0 * r * r));\n  float ct = cos(theta);\n  float st = sin(theta);\n  return cursor + vec2(ct * to.x - st * to.y, st * to.x + ct * to.y);\n}\n\n// The LOW-octave value-noise topography \u2014 the scalar field concentric extracts contours of.\nfloat heightField(vec2 p, float octavesF, float seed) {\n  float v = 0.0;\n  float amp = 0.5;\n  float freq = 1.0;\n  float px = p.x + seed;\n  float py = p.y - seed;\n  int n = int(clamp(octavesF, 1.0, 6.0));\n  for (int i = 0; i < 6; i++) {\n    if (i >= n) break;\n    v += amp * valueNoise(px * freq, py * freq);\n    float rx = 0.8 * px - 0.6 * py;\n    float ry = 0.6 * px + 0.8 * py;\n    px = rx;\n    py = ry;\n    freq *= 2.0;\n    amp *= 0.5;\n  }\n  return v;\n}\n\n// The \u03C9=\u221A(g\u00B7k) breathing swell \u2014 basins inflate/deflate with weight.\nfloat waveSwell(float t, float phase) {\n  return sin(t * 0.35 + phase) * 0.5 + sin(t * 0.21 + phase * 1.7) * 0.5;\n}\n";

package/dist/composables/glass/wave/waveField.wgsl.d.ts

@@ -1 +1 @@
-export declare const WAVE_FIELD_WGSL = "\nconst WAVE_FIELD_TAU: f32 = 6.283185307179586;\n\n// The traveling-wave envelope \u2014 a moving Gaussian crest band sweeping along waveDir.\nfn travelingEnvelope(pivot: vec2f, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32, waveSigma: f32) -> f32 {\n  let coord = dot(pivot, waveDir) * waveK - t * waveOmega;\n  let crest = fract(coord / WAVE_FIELD_TAU);\n  let z = (crest - 0.5) * 2.0;\n  return exp(-(z * z) / max(waveSigma, 1e-3));\n}\n\n// The curl-direction scalar \u2014 the smooth low-freq director the per-cell twist follows.\nfn curlScalar(cc: vec2f, t: f32) -> f32 {\n  let f = curlFBM(vec2f(cc.x * 0.5 + t * 0.08, cc.y * 0.5 - t * 0.06));\n  return clamp(f.x, -1.0, 1.0);\n}\n\n// The directed-twist FLOOR (the visibility cure): keep the curl SIGN (adjacent cells lean\n// together) but floor the magnitude so a crest-band cell ALWAYS rotates decisively.\nconst WAVE_FIELD_TWIST_FLOOR: f32 = 0.62;\nfn directedTwist(s: f32, floorMag: f32) -> f32 {\n  let mag = max(floorMag, abs(s));\n  let sgn = tanh(s * 6.0);\n  return sgn * mag;\n}\n\n// \u2500\u2500 The FACE leaf (the structurally-absent RE-INVENT \u2014 height-lit filled cell interior) \u2500\u2500\n// DECLARED ABOVE cellTwist (no WGSL forward declaration): cellTwist rides cellHeight via the\n// driver so twist + face read ONE envelope.\n\n// The sheet displacement at a cell center = the EXACT traveling-wave scalar the twist rides.\nfn cellHeight(cc: vec2f, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32, waveSigma: f32, amp: f32) -> f32 {\n  return travelingEnvelope(cc, t, waveDir, waveK, waveOmega, waveSigma) * amp;\n}\n\n// The pre-twist driver (FOLD A): the cell pivot cc + the crest envelope env the twist AND the\n// face both ride. The face samples height/relief at THIS pre-twist cc (the crest twist crosses\n// the cell boundary \u2192 floor(twisted_g) would light a NEIGHBOUR cell). cc in .xy, env in .z.\nfn cellDriver(g: vec2f, cellSize: f32, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32,\n              waveSigma: f32, amp: f32) -> vec3f {\n  let cs = max(cellSize, 1e-3);\n  let cc = (floor(g / cs) + 0.5) * cs;\n  let env = cellHeight(cc, t, waveDir, waveK, waveOmega, waveSigma, amp);\n  return vec3f(cc, env);\n}\n\n// The central-difference slope of cellHeight across a cell (eps = 0.5\u00B7cellSize) \u2014 derivative-\n// FREE (NO dFdx on the height) \u2192 Safari WebGL2-safe. Returns \u2207H.\nfn faceRelief(cc: vec2f, cellSize: f32, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32,\n              waveSigma: f32, amp: f32) -> vec2f {\n  let eps = max(cellSize, 1e-3) * 0.5;\n  let hxp = cellHeight(cc + vec2f(eps, 0.0), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  let hxm = cellHeight(cc - vec2f(eps, 0.0), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  let hyp = cellHeight(cc + vec2f(0.0, eps), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  let hym = cellHeight(cc - vec2f(0.0, eps), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  return vec2f((hxp - hxm) / (2.0 * eps), (hyp - hym) / (2.0 * eps));\n}\n\n// Soft inset-square coverage inside a (warped) cell \u2014 the filled FACE plateau. d is the\n// distance into the cell from the nearest gutter (the Golus triangle-wave); the inset retreats\n// as it grows (the squash). aa = the shader's fwidth(g) (JS passes a fixed uvDeriv).\nfn facePlateau(g: vec2f, inset: f32, uvDeriv: vec2f) -> f32 {\n  let tri = 1.0 - abs(fract(g) * 2.0 - 1.0);\n  let d = min(tri.x, tri.y);\n  let aa = max(uvDeriv.x, uvDeriv.y) * 1.5;\n  return smoothstep(inset, inset + 2.0 * aa, d);\n}\n\n// The cell-local twist about each cell's own center, gated by the traveling wave + directed\n// by the curl flow. amp is the spring-eased envelope amplitude the JS host drives. FOLD C: the\n// TWIST_FLOOR is crest-gated by env so OFF-crest cells relax to flat calm paper (the traveling\n// read, not static foil).\nfn cellTwist(g: vec2f, cellSize: f32, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32,\n             waveSigma: f32, twistMax: f32, shearMax: f32, amp: f32) -> vec2f {\n  let drv = cellDriver(g, cellSize, t, waveDir, waveK, waveOmega, waveSigma, amp);\n  let cc = drv.xy;\n  let env = drv.z;\n  let floorMag = WAVE_FIELD_TWIST_FLOOR * env;   // FOLD C: crest-gated floor\n  let theta = twistMax * env * directedTwist(curlScalar(cc, t), floorMag);\n  let shear = shearMax * env * directedTwist(curlScalar(cc + vec2f(17.3, 9.1), t), floorMag);\n  let local = g - cc;\n  let ct = cos(theta);\n  let st = sin(theta);\n  var rot = vec2f(ct * local.x - st * local.y, st * local.x + ct * local.y);\n  rot.x = rot.x + shear * rot.y;   // a small skew so the box MORPHS, not just rotates\n  return cc + rot;\n}\n\n// The CONTINUOUS traveling-wave FLOW warp \u2014 the SMOOTH twin of cellTwist (no per-cell seam;\n// for the level-set contours that shatter into a mesh under the cell discontinuity).\nfn waveFlow(g: vec2f, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32, waveSigma: f32,\n            twistMax: f32, amp: f32) -> vec2f {\n  let env = travelingEnvelope(g, t, waveDir, waveK, waveOmega, waveSigma) * amp;\n  let f = curlFBM(vec2f(g.x * 0.6 + t * 0.05, g.y * 0.6 - t * 0.04));\n  let f2 = curlFBM(vec2f(g.x * 1.1 - t * 0.03, g.y * 1.1 + t * 0.035));\n  let k = twistMax * env;\n  return g + (f + f2 * 0.5) * k;\n}\n\n// The local cursor swirl \u2014 the finger twists the cells around it (re-aimed cursorBulge).\nfn cursorSwirl(g: vec2f, cursor: vec2f, strength: f32, radius: f32) -> vec2f {\n  let to = g - cursor;\n  let d2 = dot(to, to);\n  let r = max(radius, 1e-4);\n  let theta = strength * exp(-d2 / (2.0 * r * r));\n  let ct = cos(theta);\n  let st = sin(theta);\n  return cursor + vec2f(ct * to.x - st * to.y, st * to.x + ct * to.y);\n}\n\n// The LOW-octave value-noise topography \u2014 the scalar field concentric extracts contours of.\nfn heightField(p: vec2f, octavesF: f32, seed: f32) -> f32 {\n  var v = 0.0;\n  var amp = 0.5;\n  var freq = 1.0;\n  var px = p.x + seed;\n  var py = p.y - seed;\n  let n = i32(clamp(octavesF, 1.0, 6.0));\n  for (var i = 0; i < 6; i = i + 1) {\n    if (i >= n) { break; }\n    v = v + amp * valueNoise(px * freq, py * freq);\n    let rx = 0.8 * px - 0.6 * py;\n    let ry = 0.6 * px + 0.8 * py;\n    px = rx;\n    py = ry;\n    freq = freq * 2.0;\n    amp = amp * 0.5;\n  }\n  return v;\n}\n\n// The \u03C9=\u221A(g\u00B7k) breathing swell \u2014 basins inflate/deflate with weight.\nfn waveSwell(t: f32, phase: f32) -> f32 {\n  return sin(t * 0.35 + phase) * 0.5 + sin(t * 0.21 + phase * 1.7) * 0.5;\n}\n";
+export declare const WAVE_FIELD_WGSL = "\nconst WAVE_FIELD_TAU: f32 = 6.283185307179586;\n\n// The traveling-wave envelope \u2014 a moving Gaussian crest band sweeping along waveDir.\nfn travelingEnvelope(pivot: vec2f, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32, waveSigma: f32) -> f32 {\n  let coord = dot(pivot, waveDir) * waveK - t * waveOmega;\n  let crest = fract(coord / WAVE_FIELD_TAU);\n  let z = (crest - 0.5) * 2.0;\n  return exp(-(z * z) / max(waveSigma, 1e-3));\n}\n\n// The curl-direction scalar \u2014 the smooth low-freq director the per-cell twist follows.\nfn curlScalar(cc: vec2f, t: f32) -> f32 {\n  let f = curlFBM(vec2f(cc.x * 0.5 + t * 0.08, cc.y * 0.5 - t * 0.06));\n  return clamp(f.x, -1.0, 1.0);\n}\n\n// The directed-twist FLOOR (the visibility cure): keep the curl SIGN (adjacent cells lean\n// together) but floor the magnitude so a crest-band cell ALWAYS rotates decisively.\nconst WAVE_FIELD_TWIST_FLOOR: f32 = 0.62;\nfn directedTwist(s: f32, floorMag: f32) -> f32 {\n  let mag = max(floorMag, abs(s));\n  let sgn = tanh(s * 6.0);\n  return sgn * mag;\n}\n\n// \u2500\u2500 The FACE leaf (the structurally-absent RE-INVENT \u2014 height-lit filled cell interior) \u2500\u2500\n// DECLARED ABOVE cellTwist (no WGSL forward declaration): cellTwist rides cellHeight via the\n// driver so twist + face read ONE envelope.\n\n// The sheet displacement at a cell center = the EXACT traveling-wave scalar the twist rides.\nfn cellHeight(cc: vec2f, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32, waveSigma: f32, amp: f32) -> f32 {\n  return travelingEnvelope(cc, t, waveDir, waveK, waveOmega, waveSigma) * amp;\n}\n\n// The pre-twist driver (FOLD A): the cell pivot cc + the crest envelope env the twist AND the\n// face both ride. The face samples height/relief at THIS pre-twist cc (the crest twist crosses\n// the cell boundary \u2192 floor(twisted_g) would light a NEIGHBOUR cell). cc in .xy, env in .z.\nfn cellDriver(g: vec2f, cellSize: f32, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32,\n              waveSigma: f32, amp: f32) -> vec3f {\n  let cs = max(cellSize, 1e-3);\n  let cc = (floor(g / cs) + 0.5) * cs;\n  let env = cellHeight(cc, t, waveDir, waveK, waveOmega, waveSigma, amp);\n  return vec3f(cc, env);\n}\n\n// The central-difference slope of cellHeight across a cell (eps = 0.5\u00B7cellSize) \u2014 derivative-\n// FREE (NO dFdx on the height) \u2192 Safari WebGL2-safe. Returns \u2207H.\nfn faceRelief(cc: vec2f, cellSize: f32, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32,\n              waveSigma: f32, amp: f32) -> vec2f {\n  let eps = max(cellSize, 1e-3) * 0.5;\n  let hxp = cellHeight(cc + vec2f(eps, 0.0), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  let hxm = cellHeight(cc - vec2f(eps, 0.0), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  let hyp = cellHeight(cc + vec2f(0.0, eps), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  let hym = cellHeight(cc - vec2f(0.0, eps), t, waveDir, waveK, waveOmega, waveSigma, amp);\n  return vec2f((hxp - hxm) / (2.0 * eps), (hyp - hym) / (2.0 * eps));\n}\n\n// Soft inset-square coverage inside a (warped) cell \u2014 the filled FACE plateau. d is the\n// distance into the cell from the nearest gutter (the Golus triangle-wave); the inset retreats\n// as it grows (the squash). aa = the shader's fwidth(g) (JS passes a fixed uvDeriv).\nfn facePlateau(g: vec2f, inset: f32, uvDeriv: vec2f) -> f32 {\n  let tri = 1.0 - abs(fract(g) * 2.0 - 1.0);\n  let d = min(tri.x, tri.y);\n  let aa = max(uvDeriv.x, uvDeriv.y) * 1.5;\n  return smoothstep(inset, inset + 2.0 * aa, d);\n}\n\n// The cell-local twist about each cell's own center, gated by the traveling wave + directed\n// by the curl flow. amp is the spring-eased envelope amplitude the JS host drives. FOLD C: the\n// TWIST_FLOOR is crest-gated by env so OFF-crest cells relax to flat calm paper (the traveling\n// read, not static foil).\nfn cellTwist(g: vec2f, cellSize: f32, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32,\n             waveSigma: f32, twistMax: f32, shearMax: f32, amp: f32) -> vec2f {\n  let drv = cellDriver(g, cellSize, t, waveDir, waveK, waveOmega, waveSigma, amp);\n  let cc = drv.xy;\n  let env = drv.z;\n  let floorMag = WAVE_FIELD_TWIST_FLOOR * env;   // FOLD C: crest-gated floor\n  let theta = twistMax * env * directedTwist(curlScalar(cc, t), floorMag);\n  let shear = shearMax * env * directedTwist(curlScalar(cc + vec2f(17.3, 9.1), t), floorMag);\n  let local = g - cc;\n  let ct = cos(theta);\n  let st = sin(theta);\n  var rot = vec2f(ct * local.x - st * local.y, st * local.x + ct * local.y);\n  rot.x = rot.x + shear * rot.y;   // a small skew so the box MORPHS, not just rotates\n  return cc + rot;\n}\n\n// The CONTINUOUS traveling-wave FLOW warp \u2014 the SMOOTH twin of cellTwist (no per-cell seam;\n// for the level-set contours that shatter into a mesh under the cell discontinuity).\n// BG.W-GRID-AFFINE \u2014 warpFreq is the HOST-supplied curl-sampling spatial frequency (the caller's\n// own coordinate units): an order of magnitude BELOW its grid frequency so the warp is locally\n// affine (major lines bow as ONE smooth curve, no sub-cell crackle). liquid-grid (cell-scale g0)\n// passes ~0.03; concentric (unit-scale p) passes 0.6. The 1.833333 second-flow ratio transcribes\n// WAVE_FLOW_SECOND_RATIO. Amplitude unchanged \u2014 curl magnitude is the intrinsic gradient at the\n// fixed CURL_EPS, independent of warpFreq; the t-drift is host-agnostic.\nfn waveFlow(g: vec2f, t: f32, waveDir: vec2f, waveK: f32, waveOmega: f32, waveSigma: f32,\n            twistMax: f32, amp: f32, warpFreq: f32) -> vec2f {\n  let env = travelingEnvelope(g, t, waveDir, waveK, waveOmega, waveSigma) * amp;\n  let f = curlFBM(vec2f(g.x * warpFreq + t * 0.05, g.y * warpFreq - t * 0.04));\n  let wf2 = warpFreq * 1.833333;\n  let f2 = curlFBM(vec2f(g.x * wf2 - t * 0.03, g.y * wf2 + t * 0.035));\n  let k = twistMax * env;\n  return g + (f + f2 * 0.5) * k;\n}\n\n// The local cursor swirl \u2014 the finger twists the cells around it (re-aimed cursorBulge).\nfn cursorSwirl(g: vec2f, cursor: vec2f, strength: f32, radius: f32) -> vec2f {\n  let to = g - cursor;\n  let d2 = dot(to, to);\n  let r = max(radius, 1e-4);\n  let theta = strength * exp(-d2 / (2.0 * r * r));\n  let ct = cos(theta);\n  let st = sin(theta);\n  return cursor + vec2f(ct * to.x - st * to.y, st * to.x + ct * to.y);\n}\n\n// The LOW-octave value-noise topography \u2014 the scalar field concentric extracts contours of.\nfn heightField(p: vec2f, octavesF: f32, seed: f32) -> f32 {\n  var v = 0.0;\n  var amp = 0.5;\n  var freq = 1.0;\n  var px = p.x + seed;\n  var py = p.y - seed;\n  let n = i32(clamp(octavesF, 1.0, 6.0));\n  for (var i = 0; i < 6; i = i + 1) {\n    if (i >= n) { break; }\n    v = v + amp * valueNoise(px * freq, py * freq);\n    let rx = 0.8 * px - 0.6 * py;\n    let ry = 0.6 * px + 0.8 * py;\n    px = rx;\n    py = ry;\n    freq = freq * 2.0;\n    amp = amp * 0.5;\n  }\n  return v;\n}\n\n// The \u03C9=\u221A(g\u00B7k) breathing swell \u2014 basins inflate/deflate with weight.\nfn waveSwell(t: f32, phase: f32) -> f32 {\n  return sin(t * 0.35 + phase) * 0.5 + sin(t * 0.21 + phase * 1.7) * 0.5;\n}\n";

package/dist/composables/glass/webgl/backingSize.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The freshly-measured backing geometry the leaf hands the consumer's `resize`. The
+ * consumer no longer MEASURES (the leaf owns the gBCR + the bounded ancestor walk +
+ * the DPR clamp + the NEVER-300×150 floor, ONE implementation); it only UPLOADS these
+ * dims to its viewport/uniforms. `changed` is `false` when the buffer already matched
+ * (an idempotent same-box tick — the consumer can skip a redundant uniform upload).
+ */
+export interface BackingSize {
+    w: number;
+    h: number;
+    dpr: number;
+    changed: boolean;
+}
+/**
+ * The consumer's DPR policy — either a flat multiplier or a box-aware resolver (e.g.
+ * aurora's 1.5× wash ceiling vs goo-blob's 2× focal `resolveBudgetDpr`). The leaf owns
+ * the MEASUREMENT + the floor; the consumer owns ONLY the DPR number.
+ */
+export type DprPolicy = number | ((box: {
+    w: number;
+    h: number;
+}) => number);
+/**
+ * BD.W-SUBSTRATE-SIZE-UNIFY (G1) — the ONE canonical backing-store sizer.
+ *
+ * Aurora's PROVEN gBCR-ancestor sizer, lifted into the agnostic leaf so it lives ONCE
+ * (DRY) instead of in N drifted consumer `resize()` closures (the three incompatible
+ * `clientWidth || 320` / `clientWidth || canvasSize` / one-parent-gBCR conventions the
+ * DELTA-ASSAY reproduced as the live 300×150 stuck-canvas).
+ *
+ * Measures the LAID-OUT border-box via `getBoundingClientRect` — NOT `clientWidth`,
+ * which reads 0 under a `content-visibility:auto` skip (the born-skipped trap). Walks
+ * ancestors ONLY when our own rect is still zero (truly un-laid-out), and the walk is
+ * BOUNDED (H-B): cap depth at 3 AND stop at the first sized / contained / container /
+ * positioned ancestor — never an unbounded gBCR storm to `<body>` (O(depth) reflow per
+ * tick), never an over-recovered wide flex/grid grandparent that sizes the backing to
+ * the viewport. Idempotent: the realloc (which CLEARS the drawing buffer) is skipped
+ * when the buffer already matches the box.
+ *
+ * Pure CSS-geometry — ZERO dependency on which GPU API is live, so it runs SYNCHRONOUSLY
+ * at mount before the async WebGPU device resolves (G2). Engine-identical in Chromium +
+ * WebKit (gBCR reflects the real box across a CV skip in both).
+ */
+export declare function sizeBacking(canvas: HTMLCanvasElement, dprPolicy: DprPolicy): BackingSize;

package/dist/composables/glass/webgl/createCanvasLifecycle.d.ts

@@ -1,41 +1,7 @@
 export type CanvasSuspendReason = "tab-hidden" | "off-screen" | "off-screen-io" | "manual";
-export interface BackingSize {
-    w: number;
-    h: number;
-    dpr: number;
-    changed: boolean;
-}
-/**
- * The consumer's DPR policy — either a flat multiplier or a box-aware resolver (e.g.
- * aurora's 1.5× wash ceiling vs goo-blob's 2× focal `resolveBudgetDpr`). The leaf owns
- * the MEASUREMENT + the floor; the consumer owns ONLY the DPR number.
- */
-export type DprPolicy = number | ((box: {
-    w: number;
-    h: number;
-}) => number);
-/**
- * BD.W-SUBSTRATE-SIZE-UNIFY (G1) — the ONE canonical backing-store sizer.
- *
- * Aurora's PROVEN gBCR-ancestor sizer, lifted into the agnostic leaf so it lives ONCE
- * (DRY) instead of in N drifted consumer `resize()` closures (the three incompatible
- * `clientWidth || 320` / `clientWidth || canvasSize` / one-parent-gBCR conventions the
- * DELTA-ASSAY reproduced as the live 300×150 stuck-canvas).
- *
- * Measures the LAID-OUT border-box via `getBoundingClientRect` — NOT `clientWidth`,
- * which reads 0 under a `content-visibility:auto` skip (the born-skipped trap). Walks
- * ancestors ONLY when our own rect is still zero (truly un-laid-out), and the walk is
- * BOUNDED (H-B): cap depth at 3 AND stop at the first sized / contained / container /
- * positioned ancestor — never an unbounded gBCR storm to `<body>` (O(depth) reflow per
- * tick), never an over-recovered wide flex/grid grandparent that sizes the backing to
- * the viewport. Idempotent: the realloc (which CLEARS the drawing buffer) is skipped
- * when the buffer already matches the box.
- *
- * Pure CSS-geometry — ZERO dependency on which GPU API is live, so it runs SYNCHRONOUSLY
- * at mount before the async WebGPU device resolves (G2). Engine-identical in Chromium +
- * WebKit (gBCR reflects the real box across a CV skip in both).
- */
-export declare function sizeBacking(canvas: HTMLCanvasElement, dprPolicy: DprPolicy): BackingSize;
+import { sizeBacking, type BackingSize, type DprPolicy } from "./backingSize";
+export { sizeBacking };
+export type { BackingSize, DprPolicy };
 /** The per-frame hooks a backend's `buildContext` returns to the lifecycle core. */
 export interface CanvasFrameHooks {
     /** Draw one frame at `timeSec`. */
@@ -59,21 +25,30 @@ export interface CanvasLifecycleOptions {
     /**
      * Upload the backing geometry to the viewport/uniforms.
      *
-     * BD.W-SUBSTRATE-SIZE-UNIFY (G1): the leaf now MEASURES + sizes the backing store
-     * (via `sizeBacking`, the ONE sizer) and passes the freshly-computed `BackingSize`
-     * here so the consumer can never re-derive a wrong one. The arg is OPTIONAL only so
-     * a legacy consumer that still self-measures keeps compiling during the consumer
-     * cut-over; a consumer SHOULD read `s` and skip its own gBCR/DPR block. When the
-     * leaf owns sizing (`dprPolicy` provided) the buffer is already correct on entry —
-     * the consumer body shrinks to `gl.viewport(0,0,s.w,s.h)` / `uploadResolution`.
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G1): the leaf MEASURES + sizes the backing store (via
+     * `sizeBacking`, the ONE sizer) and passes the freshly-computed `BackingSize` here so
+     * the consumer can never re-derive a wrong one. When the leaf owns sizing (`dprPolicy`
+     * provided) the buffer is already correct on entry — the consumer body is UPLOAD-ONLY,
+     * shrinking to `gl.viewport(0,0,s.w,s.h)` / `uploadResolution` (a WGPU swap-chain leg
+     * is a no-op — it auto-resizes to the backing the leaf set).
+     *
+     * BG.W-VIZ-RESIZE-ADOPT: every GL/WGPU procedural viz has HARD-ADOPTED the leaf sizer
+     * (all 9 pass `dprPolicy` + read `s` upload-only; ZERO viz self-measures the backing —
+     * `proof:viz` enforces `backing == round(gBCR × dpr)` with no surviving `canvas.width =`
+     * self-size). The arg stays optional ONLY for the un-migrated `useCanvas2D` leg + the
+     * substrate contract tests; dropping the `?` (the flag-day) is booked to their adopt.
      */
     resize: (s?: BackingSize) => void;
     /**
      * The consumer's DPR policy, handed to the leaf's `sizeBacking`. When PRESENT the
      * leaf owns the backing-store MEASUREMENT + sizing (the G1 inversion) and the live
      * `BackingSize` rides every `resize` call. When ABSENT the leaf falls back to the
-     * legacy behaviour (the consumer's `resize()` self-measures) — the migration seam
-     * so a consumer can adopt the leaf sizer one viz at a time without a flag-day break.
+     * legacy behaviour (the consumer's `resize()` self-measures) — the migration seam.
+     *
+     * BG.W-VIZ-RESIZE-ADOPT: the GL/WGPU substrate (the `createGpuSubstrate` picker + both
+     * legs) is UNIVERSALLY on this seam now — every one of the 9 procedural viz threads its
+     * budget DPR here (`resolveBudgetDpr` / `resolveAuroraWashDpr`), so the STANDARD is
+     * `dprPolicy`-present; the ABSENT branch survives only for `useCanvas2D`.
      */
     dprPolicy?: DprPolicy;
     /**
@@ -93,7 +68,7 @@ export interface CanvasLifecycleOptions {
      * via `sizeBacking` (the reveal belt-and-braces, the load-bearing path on WebKit
      * where `contentvisibilityautostatechange` support is weaker).
      *
-     * Default `false` — OPT-IN. Today several consumers (goo-blob, goo-dot-matrix)
+     * Default `false` — OPT-IN. Today several consumers (goo-blob, aurora)
      * already write `"off-screen-io"` from their OWN `useIntersectionPause`; a leaf IO
      * defaulting on would DOUBLE-WRITE that reason and breach the one-writer invariant.
      * The atomic retirement of those per-consumer calls (so the leaf IO becomes the sole
@@ -104,14 +79,20 @@ export interface CanvasLifecycleOptions {
     /** `rootMargin` for the leaf-composed IO park (G3). Default `"256px"` (pre-warm). */
     intersectionRootMargin?: string;
     /**
-     * BD.W-SUBSTRATE-REVEAL-BLOOM (G6) — the cold-first-paint reveal seam. When set, the
-     * leaf toggles a `--substrate-reveal-t` 0→1 scalar on the canvas at the cold-arm
-     * paint (ONCE, never on an IO/CV re-reveal of an already-seen viz). The shader reads
-     * it to ramp luminance/saturation/drift — a FIELD bloom (the canvas rect stays
-     * `scale(1)`, no box-zoom gutter). Gated on the Band-0 `--ease-cartoon-punch` +
-     * `--motion-weight` tokens (NOT shipped today); absent, this is a no-op so the
-     * substrate paints exactly as before. PRM → the scalar is set to its settled `1`
-     * immediately (zero ramp).
+     * BG.W-VIZ-REVEAL-BLOOM — the one-shot cold-first-VISIBLE entrance bloom. When set,
+     * the leaf sets a one-shot `data-substrate-reveal` ATTRIBUTE on the canvas at the
+     * moment it FIRST becomes visible (a dedicated one-shot IntersectionObserver — NOT
+     * at `arm()`, which a content-skipped / below-fold viz would burn on an invisible
+     * paint). The CANVAS-targeted CSS `@keyframes substrate-reveal-bloom` (`viz-reveal.css`)
+     * then ramps `filter: brightness()/saturate()` from a dim floor, OVERSHOOTS past 1.0
+     * on the `--ease-cartoon-punch` linear() curve (the EFFECTS-channel sanctioned
+     * overshoot — opacity clamps at 1.0, only `filter: brightness` can exceed the
+     * settle), and settles to the canvas's own no-resting-filter rest — a FIELD bloom
+     * (the canvas rect stays `scale(1)`, no box-zoom gutter). The `revealFired` guard
+     * keeps it ONE-SHOT: an IO/CV re-reveal of an already-seen viz is a silent re-attach
+     * → ZERO second bloom on scroll-off-and-back. PRM → the leaf skips the attr AND the
+     * CSS animation sits inside `@media (prefers-reduced-motion: no-preference)`, so the
+     * field paints settled from frame 0 (zero ramp). Default `false` (opt-in per viz).
      */
     revealBloom?: boolean;
 }