@mkbabb/glass-ui 5.0.0 → 7.0.0

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

@@ -1,11 +1,11 @@
 import { type Ref } from "vue";
 import { type BackgroundCanvasSource } from "./backdropLuminanceSample";
-/** The discrete bucket the observer derives + writes (re-engages the W55 machinery). */
+/** The discrete backdrop bucket derived and written by the observer. */
 export type GlassBackdropBucket = "light" | "dark";
 export interface UseGlassBackdropLuminanceOptions {
     /**
      * The KNOWN background-layer source for the ANIMATED case — an HTMLCanvasElement
-     * (or a getter / a CSS selector resolved against the document). When present, the
+     * (or a getter, a CSS selector resolved against the document). When present, the
      * observer downsamples this canvas under the surface's bounding box each settle
      * instead of the static `elementsFromPoint` stack-walk. The aurora/blob `<canvas>`
      * the surface floats over.
@@ -26,8 +26,7 @@ export interface UseGlassBackdropLuminanceOptions {
     lightThreshold?: number;
     /**
      * Minimum milliseconds between samples on the live loop (the ≤ 4 Hz throttle floor).
-     * Default 250 (4 Hz). Bounded ≥ 250 (the budget floor — a faster sample is the
-     * C5-9 frame-budget risk the H3 arm-(a) default-on profile must hold).
+     * Default 250 (4 Hz) and bounded to at least 250ms.
      */
     minSampleIntervalMs?: number;
     /**
@@ -37,10 +36,10 @@ export interface UseGlassBackdropLuminanceOptions {
      */
     writeBucket?: boolean;
     /**
-     * BI.W-DOCK-LUMA-SHARE — mark this as the SHARED per-ROUTE observer. It stamps
+     * 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
+     * `--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
@@ -53,29 +52,53 @@ export interface UseGlassBackdropLuminanceControls {
     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.
+ * Shared-coverage marker. A route observer stamps this on its target; descendant
+ * surface observers stand down and inherit its custom properties. A DOM marker is
+ * required because provide/inject does not follow the rendered slot ancestry that
+ * the custom properties use.
  */
 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
- * W55 declarative bucket. Default-on for the dock (H3 arm a); a dark-substrate consumer
+ * content-glass panel) to write a dynamic backdrop-luminance signal that refines the
+ * declarative bucket. Default on for Dock; a dark-substrate consumer
  * opts out by setting `--glass-tint-strength: 0%` on the surface (the declarative floor
  * stays the guarantee — the observer only refines).
  *

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

@@ -1,18 +1,18 @@
 import { type ComputedRef, type CSSProperties, type MaybeRefOrGetter } from "vue";
 /**
- * `useSpecularPointer` — the EVOLUTION of `useSpecularTracking` (BB.W-LENSING). It
+ * `useSpecularPointer` — the EVOLUTION of `useSpecularTracking`. It
  * writes the catch-light POSITION (`--mouse-x`/`--mouse-y`, as today) PLUS the
  * `--specular-angle` channel — the pointer's angle-from-center the EDGE-glint conic
  * sweep reads (the `.glass-material::before` recipe, material.css). The angle feed is
  * what turns the centered disc into a motion-reactive RIM glint (the glass-THICKNESS
  * read); the leaf is the ONE shared specular source the hover/button waves consume.
  *
- * SINGLE-SOURCE (the W-LIQUIDHOVER reconcile, EXTENDED here — NOT a fork). There is
+ * SINGLE-SOURCE (the reconcile, EXTENDED here — NOT a fork). There is
  * exactly ONE position-write core: `createSpecularWriter` (useSpecularTracking.ts) —
  * the rAF-coalesced, cached-PRM, scope-dispose seam. This composable WRAPS that core;
  * the angle is DERIVED in the sink from the SAME `(x, y)` percentage the core already
  * computes (`angle = atan2(y - 50, x - 50)`), so there is NO duplicate
- * `getBoundingClientRect` / `--mouse-x` write — the core owns the layout read + the
+ * `getBoundingClientRect`, `--mouse-x` write — the core owns the layout read + the
  * coordinate math, this leaf only adds the angle derivation onto the existing sink.
  * `useSpecularTracking` (the position-only delivery) STAYS for the bare-position call
  * sites; `useSpecularPointer` is the angle-adding delivery for an edge-glint consumer.
@@ -24,8 +24,8 @@ import { type ComputedRef, type CSSProperties, type MaybeRefOrGetter } from "vue
  * 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
+ * The optional press coupling.
+ * A consumer may pass `press` (a 0..1 press scalar — a `useLiquidPress` `.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
@@ -33,7 +33,7 @@ import { type ComputedRef, type CSSProperties, type MaybeRefOrGetter } from "vue
  * 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.
+ * hard press dependency), and the position/angle write is unchanged.
  */
 export interface UseSpecularPointerOptions {
     /** Optional 0..1 press scalar (soft-gated) folded into `--glass-btn-press-t`. */

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

@@ -1,15 +1,14 @@
 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 `DockControl.vue`.
+ * `useSpecularTracking` is the pointer-anchored moving-specular writer shared by
+ * Card and DockControl.
  *
  * 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
  * `.glass-material::before` recipe (`glass.css`) MAPS that host write onto its
  * typed `--specular-x`/`--specular-y` channel and paints the travelling glow.
  *
- * VOCAB (HARDENING §G #28): `--mouse-x`/`--mouse-y` is the HOST WRITE this seam
+ * VOCAB: `--mouse-x`/`--mouse-y` is the HOST WRITE this seam
  * owns; `--specular-x`/`--specular-y` is the CSS-internal MAPPED channel the
  * recipe reads. The host writes `--mouse-x/y`; the recipe maps it.
  *
@@ -21,20 +20,18 @@ import { ref, type CSSProperties } from "vue";
  *
  * PRM-aware: under `prefers-reduced-motion: reduce` the seam DOES NOT write the
  * position (the CSS half pins the catch-light static at the centred `50%`
- * fallback). The PRM signal is read from a SINGLE cached `matchMedia` listener
- * minted once at composable setup (NOT a fresh `matchMedia` per pointer event) —
- * the AV.W7 `useWebGLCanvas` substrate pattern.
+ * fallback). The PRM signal comes from the shared reduced-motion authority, never a
+ * fresh `matchMedia` read per pointer event.
  *
- * AY.W-A11Y-PERF O-3 — the pointer write is rAF-COALESCED: `onPointerMove` only
+ * The pointer write is rAF-coalesced: `onPointerMove` only
  * stashes the raw event + schedules ONE `requestAnimationFrame`; the rAF callback
  * does the single `getBoundingClientRect()` + style write, so a 120–1000 Hz pointer
  * collapses to ONE batched layout read + ONE style write per animation frame (under
- * W54 maximal-glass every blurred-surface repaint is amortized to the frame, not the
- * event). The composable cancels the pending rAF + removes the matchMedia listener on
+ * each blurred-surface repaint is amortized to the frame rather than the
+ * event). The composable cancels the pending rAF + its shared-preference watch on
  * scope dispose (cleanup discipline).
  *
- * BB.W-LIQUIDHOVER — the rAF-coalesce + cached-PRM + cleanup LOGIC is extracted to
- * `createSpecularWriter()`, the SINGLE position-write core. The composable below wraps
+ * `createSpecularWriter()` owns rAF coalescing, cached PRM, and cleanup. The composable wraps
  * it for the Vue `:style`-ref case (Card's prop-gated `specular` opt-in); the
  * tier-root auto-arm (`vSpecular`) wraps the SAME core to write directly on the
  * directive host's `el.style` (the zero-wiring delivery). ONE position-write source,
@@ -47,12 +44,12 @@ export interface UseSpecularTracking {
     onPointerMove: (event: PointerEvent) => void;
 }
 /**
- * The SINGLE position-write core (BB.W-LIQUIDHOVER) — the rAF-coalesced,
+ * The SINGLE position-write core — the rAF-coalesced,
  * PRM-aware `--mouse-x/y` write seam, sink-agnostic. `sink(x, y)` receives the
  * percentage position once per animation frame; the composable sinks into its
  * `specularStyle` ref, the `vSpecular` directive sinks into `el.style.setProperty`.
- * Returns the event handler + a `dispose` (cancel the pending rAF + drop the cached
- * PRM listener) so BOTH deliveries share ONE cleanup discipline.
+ * Returns the event handler + a `dispose` (cancel the pending rAF + preference watch)
+ * so BOTH deliveries share ONE cleanup discipline.
  */
 export interface SpecularWriter {
     onPointerMove: (event: PointerEvent) => void;

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

@@ -57,7 +57,7 @@ export declare function cellTwist(curlFn: (p: Vec2) => Vec2, g: Vec2, cellSize:
 /**
  * The sheet displacement at a cell center `cc` — the EXACT traveling-wave scalar the twist
  * rides (`travelingEnvelope · amp`), surfaced as a named leaf fn so the face reads ONE
- * envelope. Range [0,1]·amp: ~0 ahead of / behind the crest, ~amp at the crest. `cellTwist`
+ * envelope. Range [0,1]·amp: ~0 ahead of, behind the crest, ~amp at the crest. `cellTwist`
  * (via `cellDriver`) calls this, so a sign drift reds the numeric parity gate everywhere.
  */
 export declare function cellHeight(cc: Vec2, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number, amp: number): number;
@@ -100,7 +100,7 @@ export declare const WAVE_FLOW_SECOND_RATIO = 1.833333;
  * 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
+ * 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

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).\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";
+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 neighbouring cell). cc is in .xy and 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// 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). LiquidGrid (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).\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";
+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 neighbouring cell). cc is in .xy and 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// 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). LiquidGrid (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

@@ -21,24 +21,21 @@ export type DprPolicy = number | ((box: {
     h: number;
 }) => number);
 /**
- * BD.W-SUBSTRATE-SIZE-UNIFY (G1) — the ONE canonical backing-store sizer.
+ * The 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).
+ * The shared ancestor-aware sizer replaces per-consumer `resize()` conventions.
  *
  * 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
+ * Bounded: cap depth at 3 and stop at the first sized, contained, container-positioned
+ * ancestor — never an unbounded gBCR walk 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 +
+ * at mount before the async WebGPU device resolves. Engine-identical in Chromium and
  * 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/compile.d.ts

@@ -1,5 +1,5 @@
 /**
- * Shared WebGL2 shader compile/link pair (AV.W14) — the single error-checked
+ * Shared WebGL2 shader compile/link pair: the single error-checked
  * source the aurora GL setup (`glSetup.ts`) and the goo-blob renderer
  * (`useMetaballRenderer.ts`) both build their program from. Each consumer was
  * hand-rolling a byte-identical `compile`/`link` differing only in the error

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

@@ -19,36 +19,32 @@ export interface CanvasLifecycleOptions {
     respectReducedMotion?: boolean;
     /**
      * Acquire the backend context + build the per-frame hooks. Called on `arm()` AND
-     * on a backend context-restore. Throws on backend-unavailable / setup failure.
+     * on a backend context-restore. Throws on backend-unavailable, setup failure.
      */
     buildContext: () => CanvasFrameHooks;
     /**
      * Upload the backing geometry to the viewport/uniforms.
      *
-     * BD.W-SUBSTRATE-SIZE-UNIFY (G1): the leaf MEASURES + sizes the backing store (via
+     * The leaf measures and 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
+     * 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.
+     * Procedural scenes, including Canvas2D, pass `dprPolicy` and use this upload-only
+     * size. The optional argument remains only for direct legacy WebGL/WebGPU callers
+     * that omit a DPR policy.
      */
     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
+     * leaf owns backing-store measurement and sizing, 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.
      *
-     * 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`.
+     * Procedural scenes use the present branch. The absent branch remains for direct
+     * legacy WebGL/WebGPU callers.
      */
     dprPolicy?: DprPolicy;
     /**
@@ -59,8 +55,12 @@ export interface CanvasLifecycleOptions {
      */
     bindContextEvents?: (rebuild: () => void, markContextLost: () => void) => void;
     unbindContextEvents?: () => void;
+    /** Project the lifecycle's existing loss/rebuild state without creating a second clock. */
+    onContextStateChange?: (state: "lost" | "restored") => void;
+    /** Surface a failed restore or a bounded context-loss storm to the owner. */
+    onContextError?: (error: Error) => void;
     /**
-     * BD.W-SUBSTRATE-SIZE-UNIFY (G3) — compose the IntersectionObserver park detector
+     * Compose the IntersectionObserver park detector
      * at the leaf (DRY) so a consumer inherits the off-screen IO-park ORed with the
      * content-visibility park, with NO per-viz `useIntersectionPause` wiring. The leaf
      * wires a plain (scope-free, reactivity-free) IO observing the canvas, writing the
@@ -73,16 +73,16 @@ export interface CanvasLifecycleOptions {
      * 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
      * writer, default-on) lands in the viz lanes. Until then a viz with NO IO wiring
-     * (concentric / fourier / dot-flow — the live PARK gap) opts IN to inherit the park.
+     * (concentric, fourier, dot-flow — the live PARK gap) opts IN to inherit the park.
      */
     composeIntersectionPark?: boolean;
-    /** `rootMargin` for the leaf-composed IO park (G3). Default `"256px"` (pre-warm). */
+    /** `rootMargin` for the leaf-composed IO park. Default `"256px"` for pre-warm. */
     intersectionRootMargin?: string;
     /**
-     * BG.W-VIZ-REVEAL-BLOOM — the one-shot cold-first-VISIBLE entrance bloom. When set,
+     * 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
+     * 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
@@ -99,7 +99,7 @@ export interface CanvasLifecycleOptions {
 export interface CanvasLifecycleHandle {
     arm: () => void;
     /**
-     * BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing store + start the leaf RO
+     * Size the backing store and start the leaf RO
      * SYNCHRONOUSLY, decoupled from the (async) context acquire. The WebGPU backend
      * calls this BEFORE `armAsync`'s device request so the canvas is sharp from frame 0
      * while the device resolves behind it (the ≤6s blurry-flash close). Idempotent: a
@@ -116,7 +116,7 @@ export interface CanvasLifecycleHandle {
     readonly running: boolean;
     readonly reducedMotion: boolean;
     /**
-     * BC.W-SAFARI-WEBGL — the circuit-breaker has tripped: the surface lost-and-restored
+     * the circuit-breaker has tripped: the surface lost-and-restored
      * its context more than N times within T ms (a real eviction storm), so the lifecycle
      * is HOLDING the parked state without re-arming (no throw). Resets once the loss window
      * passes quiet; a healthy single loss never trips it.

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

@@ -1,36 +1,20 @@
 import { type BackingSize, type DprPolicy } from "./createCanvasLifecycle";
 export type { BackingSize, DprPolicy } from "./createCanvasLifecycle";
 /**
- * The ONE `getContext("webgl2")` capability probe (BB.W-CI-GREEN — the
- * single-bootstrap rule). A throwaway WebGL2 context is created here, in the
- * substrate (the sole webgl2-creating module per `proof:webgl-substrate-single`),
- * so a consumer feature-detecting WebGL2 / reading the unmasked renderer string
+ * The one `getContext("webgl2")` capability probe. A throwaway WebGL2 context is
+ * created here in the substrate,
+ * so a consumer feature-detecting WebGL2, reading the unmasked renderer string
  * NEVER creates a second context of its own. The probe canvas is detached, its
  * context released via `WEBGL_lose_context` under the per-page context cap; the
  * read is one-shot (a mount-time device-tier decision, not a reactive one).
  *
  * Returns the lower-cased `UNMASKED_RENDERER_WEBGL` string (e.g.
- * `"google swiftshader"`), or `null` when WebGL2 / the debug-renderer extension
+ * `"google swiftshader"`), or `null` when WebGL2, the debug-renderer extension
  * is unavailable or the probe throws — the caller treats `null` as "cannot prove"
  * (the conservative-but-lossy fall-back). SSR-safe (returns `null` with no
  * `document`).
  */
 export declare function probeWebGL2Renderer(): string | null;
-/**
- * The WebGPU→WebGL2 fall POISON test — can THIS specific canvas still host WebGL2?
- * (BD.W-VIZ-BROKEN-FIX — the single-bootstrap home for the probe.) Once `getContext("webgpu")`
- * has run on a canvas, the HTML one-context-type rule locks it to `webgpu` forever and
- * `getContext("webgl2")` returns `null`. The picker's fall-to-WebGL2 path probes this to
- * decide whether it must clone+swap the canvas (genuinely poisoned) or can keep the original
- * (a fall that ran BEFORE any `getContext("webgpu")` — no-adapter / device-reject / acquire-
- * timeout — never poisoned it; reusing it avoids orphaning the consumer's captured canvas
- * reference). The `getContext("webgl2")` bootstrap stays in THIS substrate (the sole webgl2-
- * creating module per `proof:webgl-substrate-single` clause B); the picker composes this
- * helper rather than calling `getContext("webgl2")` itself. `getContext` is idempotent for
- * the same type, so on a clean canvas the probe returns the very context the net re-acquires
- * (no extra cost). Returns `true` if the canvas can host WebGL2, `false` if poisoned/unable.
- */
-export declare function canvasCanHostWebGL2(canvas: HTMLCanvasElement): boolean;
 export type WebGLSuspendReason = "tab-hidden" | "off-screen" | "off-screen-io" | "manual";
 /** The per-frame hooks a consumer's `setup(gl)` returns. */
 export interface WebGLCanvasFrame {
@@ -39,7 +23,7 @@ export interface WebGLCanvasFrame {
     /** Demand-gate: is there live motion to render next frame? `false` → park. */
     shouldContinue: () => boolean;
     /**
-     * Upload the backing geometry to the viewport/uniforms. BD.W-SUBSTRATE-SIZE-UNIFY:
+     * Upload the backing geometry to the viewport/uniforms.:
      * when a `dprPolicy` is supplied the leaf MEASURES + sizes the backing and passes
      * the live `BackingSize` here (the consumer body shrinks to
      * `gl.viewport(0,0,s.w,s.h)`); the arg is optional so a legacy self-measuring
@@ -66,37 +50,41 @@ export interface WebGLCanvasOptions {
      */
     respectReducedMotion?: boolean;
     /**
-     * BD.W-SUBSTRATE-SIZE-UNIFY (G1/G2) — the consumer's DPR policy. When PRESENT the
+     * The consumer's DPR policy. When present the
      * leaf owns the backing-store measurement + sizing (the ONE sizer, sized
      * synchronously at mount before any acquire) and hands the live `BackingSize` to
      * `resize(s)`. When ABSENT the legacy path runs (the consumer self-measures).
      */
     dprPolicy?: DprPolicy;
-    /** Compose the leaf IO park (G3). Default `false` (opt-in; see createCanvasLifecycle). */
+    /** Compose the leaf IO park. Default `false`; see createCanvasLifecycle. */
     composeIntersectionPark?: boolean;
-    /** `rootMargin` for the leaf IO park (G3). */
+    /** `rootMargin` for the leaf IO park. */
     intersectionRootMargin?: string;
-    /** Fire the one-shot cold-first-VISIBLE entrance bloom (BG.W-VIZ-REVEAL-BLOOM — the `data-substrate-reveal` attr). Default `false`. */
+    /** Fire the one-shot cold-first-visible entrance bloom via `data-substrate-reveal`. Default `false`. */
     revealBloom?: boolean;
     /**
      * Build the program + geometry on a fresh context. Called on `arm()` AND on
      * every `webglcontextrestored`. Returns the per-frame hooks.
      */
     setup: (gl: WebGL2RenderingContext) => WebGLCanvasFrame;
+    /** Internal lifecycle projection used by the shared renderer-status owner. */
+    onContextStateChange?: (state: "lost" | "restored") => void;
+    /** Surface a failed context restore or a bounded loss storm. */
+    onContextError?: (error: Error) => void;
 }
 export interface WebGLCanvasHandle {
     /** Run the expensive init (context + `setup` + arm the loop). Idempotent; no-op post-dispose. */
     arm: () => void;
-    /** BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing + start the leaf RO synchronously (pre-acquire). */
+    /** Size the backing and start the leaf RO synchronously before acquire. */
     presize: () => void;
     suspend: (reason?: WebGLSuspendReason) => void;
     resume: (reason?: WebGLSuspendReason) => void;
     /** Re-arm a parked loop (a setter that re-introduced motion calls this). */
     wake: () => void;
-    /** Draw one frame at `timeSec` out-of-loop (capture / thumbnail). */
+    /** Draw one frame at `timeSec` out-of-loop (capture, thumbnail). */
     renderAt: (timeSec: number) => void;
     dispose: () => void;
-    /** The live context (null before arm / after dispose / mid-loss). */
+    /** The live context (null before arm, after dispose, mid-loss). */
     readonly gl: WebGL2RenderingContext | null;
     /**
      * The live `prefers-reduced-motion: reduce` state. The shared lifecycle core

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

@@ -1,7 +1,7 @@
 import type { CanvasSuspendReason } from "./createCanvasLifecycle";
 /**
  * The scheduler seam the observers drive. Each observer writes a DISTINCT suspend
- * reason (`tab-hidden` / `off-screen` / `off-screen-io`) — the one-writer-per-reason
+ * reason (`tab-hidden`, `off-screen`, `off-screen-io`) — the one-writer-per-reason
  * invariant — and reads the scheduler's live `armed`/`hooks`/`disposed`/`reducedMotion`
  * state through the getters (never a shared closure var, so the two files stay decoupled).
  */
@@ -21,7 +21,7 @@ export interface CanvasVisibilityDeps {
 }
 export interface CanvasVisibility {
     /**
-     * BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing store + start the leaf RO
+     * Size the backing store and start the leaf RO
      * SYNCHRONOUSLY, decoupled from the (async) context acquire. Idempotent: a no-op
      * once it has run. The WebGPU backend calls this BEFORE its async device request so
      * the canvas is sharp from frame 0 while the device resolves.
@@ -36,7 +36,6 @@ export interface CanvasVisibility {
 }
 /**
  * The canvas visibility observers. Constructing this binds the tab-visibility owner +
- * seeds the initial `document.hidden` suspend (the pre-arm seed), matching the prior
- * inline behaviour byte-for-byte.
+ * seeds the initial `document.hidden` suspend (the pre-arm seed).
  */
 export declare function createCanvasVisibility(deps: CanvasVisibilityDeps): CanvasVisibility;

package/dist/composables/glass/webgpu/rendererStatus.d.ts

@@ -0,0 +1,13 @@
+export type RendererEngine = "webgpu" | "webgl2" | "canvas2d" | "css";
+export interface RendererStatus {
+    phase: "initializing" | "ready" | "error";
+    engine: RendererEngine;
+    adapter: string;
+    error?: string;
+}
+export declare const pendingRenderer: (engine: RendererEngine) => RendererStatus;
+export declare const canvas2DRenderer: () => RendererStatus;
+export declare const cssRenderer: () => RendererStatus;
+export declare function describeWebGPUAdapter(info?: GPUAdapterInfo): string;
+export declare function describeWebGL2Adapter(gl: WebGL2RenderingContext | null): string;
+export declare function rendererFailure(engine: RendererEngine, adapter: string, error: unknown): RendererStatus;