@mkbabb/glass-ui 4.1.0 → 5.0.0

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

@@ -0,0 +1,136 @@
+/** A 2-vector. */
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+/**
+ * The directed-twist magnitude FLOOR (the visibility cure — shared across JS↔GLSL↔WGSL).
+ * The curl scalar alone sits ~|0.3|, damping the crest twist to a whisper; a cell in the
+ * crest band always rotates at least this fraction of `twistMax` so the wave READS.
+ */
+export declare const TWIST_FLOOR = 0.62;
+/**
+ * A moving Gaussian crest band sweeping along `waveDir` at angular speed `waveOmega`.
+ * Returns the envelope in [0,1]: ~0 where the wave has NOT reached, ~1 at the crest,
+ * relaxing back to ~0 behind it. `coord` is the wave phase at a point; `crest` wraps it
+ * to a single 0..1 cycle and `env` is the Gaussian about the cycle midpoint. The crest
+ * "passes OVER and THROUGH" the field — the cells are calm ahead, twist HARD at the
+ * crest, relax behind.
+ */
+export declare function travelingEnvelope(pivot: Vec2, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number): number;
+/**
+ * The curl-noise vorticity read at the cell center — a smooth low-frequency scalar in
+ * roughly [-1,1] that DIRECTS the per-cell twist so adjacent cells lean TOGETHER (a
+ * flowing read, never per-cell noise). The host supplies `curlFn(p) -> Vec2` (the shared
+ * divergence-free curl of its own noise basis); this takes the x-component as the signed
+ * director and folds a slow time drift so the flow itself evolves. Basis-agnostic.
+ */
+export declare function curlScalar(curlFn: (p: Vec2) => Vec2, cc: Vec2, t: number): number;
+/** The cell pivot `cc` + the spring-eased crest envelope `env` a cell rides. */
+export interface CellDriver {
+    /** The PRE-twist cell center (the per-cell pivot the twist rotates about). */
+    cc: Vec2;
+    /** The traveling-Gaussian crest envelope × amp at that pivot ([0,1] · amp). */
+    env: number;
+}
+/**
+ * The pre-twist driver for the grid coordinate `g`: floor `g` to its cell, return that cell's
+ * center `cc` + the traveling-wave crest envelope `env` evaluated AT that center (= `cellHeight`,
+ * so there is provably ONE envelope). FOLD A: the face must sample its height/relief at THIS
+ * pre-twist `cc`, NOT at `floor(twisted_g)` (the crest twist crosses the cell boundary → the
+ * face would light a NEIGHBOUR cell). `cellTwist` rides the SAME driver, so twist and face fuse.
+ */
+export declare function cellDriver(g: Vec2, cellSize: number, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number, amp: number): CellDriver;
+/**
+ * Twist the grid coordinate `g` about its OWN cell center, gated by the traveling wave
+ * and directed by the curl flow. The pivot is the cell center (a per-cell constant) so the
+ * box rotates about its middle — the cell stays in place but TWISTS (a windmill of warped
+ * boxes where the crest passes; calm square cells elsewhere). `amp` is the spring-eased
+ * envelope amplitude the JS host drives (the liquid-weight inertia). Returns the twisted
+ * coordinate (still in grid space; the host evaluates its extraction at it).
+ *
+ * FOLD C — the `TWIST_FLOOR` is CREST-GATED: the floor is multiplied by the crest envelope so
+ * OFF-crest cells relax to near-flat (calm paper) and only the crest band crinkles. Without
+ * this every cell crinkles regardless of the wave (static foil, no traveling read).
+ */
+export declare function cellTwist(curlFn: (p: Vec2) => Vec2, g: Vec2, cellSize: number, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number, twistMax: number, shearMax: number, amp: number): Vec2;
+/**
+ * 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`
+ * (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;
+/**
+ * The central-difference slope of `cellHeight` across a cell (`ε = 0.5·cellSize`) — the lit-fold
+ * normal source. Pure, derivative-FREE (NO `dFdx` on the height) → Safari WebGL2-safe by
+ * construction (only the Golus AA uses `fwidth`). Returns ∇H = (∂H/∂x, ∂H/∂y) at `cc`.
+ */
+export declare function faceRelief(cc: Vec2, cellSize: number, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number, amp: number): Vec2;
+/**
+ * Soft inset-square coverage inside a (warped) cell — the filled FACE plateau. `d` is the
+ * distance into the cell from the nearest gutter (per axis, on the triangle-wave the Golus
+ * grid already uses); `smoothstep(inset, inset+2·aa, d)` floors the face to a soft-edged tile
+ * that retreats as `inset` grows (the squash). The shaders pass `aa = fwidth(g)` (crisp at any
+ * DPR — the Golus precedent); the JS round-trip passes a fixed `uvDeriv` (reproducible).
+ * Returns face coverage [0..1].
+ */
+export declare function facePlateau(g: Vec2, inset: number, uvDeriv: Vec2): number;
+/**
+ * A LOCAL Gaussian-gated rotation about the cursor — the finger twists the cells around
+ * it (the re-aimed `cursorBulge`: a swirl, not a radial push). `strength` is the peak
+ * twist angle at the cursor; `radius` the Gaussian falloff (grid units). Returns the
+ * 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
+ * into a mesh under the per-cell discontinuity; they need this continuous warp). The curl
+ * flow direction is read at `g` itself (no per-cell pivot → no seam), its magnitude gated by
+ * 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, 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
+ * legibility floor). The host supplies its `noiseFn(x,y)` (the SAME value-noise basis its
+ * `potentialFBM` uses, basis-agnostic). Returns the un-normalized height.
+ */
+export declare function heightField(noiseFn: (x: number, y: number) => number, p: Vec2, octaves: number, seed: number): number;
+/**
+ * The ω=√(g·k) breathing swell — a slow global rise/fall the topography rides so basins
+ * inflate/deflate with weight (the deep-water dispersion the suite shares). A pure
+ * f(t) the host adds onto H. `phase` lets a host offset its own swell.
+ */
+export declare function waveSwell(t: number, phase: number): number;
+/**
+ * The cell-warp applied BEFORE the height eval (concentric's `cellWarpBeforeHeight`). It
+ * is the SAME `cellTwist` paper-grid runs — concentric warps the SAMPLING coordinate so
+ * the contours twist/flow as the traveling wave crosses (kinship with paper-grid). A thin
+ * alias for the gate's by-name assert + the host's call-site clarity.
+ */
+export declare function cellWarpBeforeHeight(curlFn: (p: Vec2) => Vec2, g: Vec2, cellSize: number, t: number, waveDir: Vec2, waveK: number, waveOmega: number, waveSigma: number, twistMax: number, shearMax: number, amp: number): Vec2;

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

@@ -0,0 +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";

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

@@ -0,0 +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";

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,4 +1,7 @@
 export type CanvasSuspendReason = "tab-hidden" | "off-screen" | "off-screen-io" | "manual";
+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`. */
@@ -19,8 +22,35 @@ export interface CanvasLifecycleOptions {
      * on a backend context-restore. Throws on backend-unavailable / setup failure.
      */
     buildContext: () => CanvasFrameHooks;
-    /** Resize the backing store + viewport. The consumer owns its DPR policy. */
-    resize: () => void;
+    /**
+     * Upload the backing geometry to the viewport/uniforms.
+     *
+     * 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.
+     *
+     * 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;
     /**
      * Bind/unbind backend-specific context-loss/restore listeners. `rebuild` re-runs
      * `buildContext` on a fresh context + resumes the loop (the self-heal); the backend
@@ -29,9 +59,53 @@ export interface CanvasLifecycleOptions {
      */
     bindContextEvents?: (rebuild: () => void, markContextLost: () => void) => void;
     unbindContextEvents?: () => void;
+    /**
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G3) — 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
+     * DISTINCT `"off-screen-io"` reason. On `isIntersecting → true` it ALSO re-measures
+     * 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, 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
+     * 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.
+     */
+    composeIntersectionPark?: boolean;
+    /** `rootMargin` for the leaf-composed IO park (G3). Default `"256px"` (pre-warm). */
+    intersectionRootMargin?: string;
+    /**
+     * 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;
 }
 export interface CanvasLifecycleHandle {
     arm: () => void;
+    /**
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing store + 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
+     * no-op once `arm()` has run it. A no-op when no `dprPolicy` was supplied (legacy).
+     */
+    presize: () => void;
     suspend: (reason?: CanvasSuspendReason) => void;
     resume: (reason?: CanvasSuspendReason) => void;
     wake: () => void;

package/dist/composables/glass/webgl/shaders/glass-refract.glsl.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The pinned chromatic-dispersion scale — ONE source-of-truth across BOTH refraction
+ * stacks (this GLSL floor + the WGSL `glassShader.wgsl` twin). An ABSOLUTE rim-offset
+ * multiplier: `|ca| = inward · rim · uChromatic · CHROMATIC_SCALE`. Pinned here so a
+ * cross-stack drift (the 0.003/0.004/0.0045 three-way split the Tier-2 literal `0.004`
+ * carried) is impossible — the shipped WGSL twin replaces its literal with this value.
+ */
+export declare const CHROMATIC_SCALE = 0.0045;
+/** The uniform-name contract — the ONE spelling map the JS binder + the fence read. */
+export declare const GLASS_REFRACT_UNIFORMS: {
+    readonly resolution: "uResolution";
+    readonly time: "uTime";
+    readonly panelCount: "uPanelCount";
+    readonly bounds: "uBounds";
+    readonly lightPos: "uLightPos";
+    readonly blurRadius: "uBlurRadius";
+    readonly refractionStrength: "uRefractionStrength";
+    /** the fence operator — refraction=depth, hue=this absolute rim offset. */
+    readonly chromatic: "uChromatic";
+    readonly metalStrength: "uMetalStrength";
+    readonly valveKnee: "uValveKnee";
+    readonly plateAlphaMax: "uPlateAlphaMax";
+    readonly backdrop: "uBackdrop";
+};
+/** The maximum panel count the fragment loop unrolls (mirrors Tier-2 `MAX_PANELS`). */
+export declare const GLASS_REFRACT_MAX_PANELS = 8;
+/** The full-screen-triangle vertex pass (the substrate's standard fullscreen pass). */
+export declare const GLASS_REFRACT_VERT_GLSL = "#version 300 es\nprecision highp float;\nin vec2 aPosition;\nout vec2 vUv;\nvoid main() {\n  vUv = aPosition * 0.5 + 0.5;   // [-1,1]\u00B2 clip \u2192 [0,1]\u00B2 UV\n  gl_Position = vec4(aPosition, 0.0, 1.0);\n}";
+/**
+ * The Tier-1 WebGL2 refraction fragment source. Renders the FULL ship pass: squircle
+ * depth-refraction → 3×3 blur → absolute-rim chromatic split → curl drapery sheen →
+ * ridge-local plate-alpha valve → directional specular + Fresnel rim. Splices the
+ * SHARED `CURL_FBM_GLSL` chunk (the drapery term); `potentialFBM` is defined below
+ * the uniforms per the splice-order law (the host owns the noise basis).
+ */
+export declare const GLASS_REFRACT_FRAG_GLSL = "#version 300 es\nprecision highp float;\n\n#define MAX_PANELS 8\n\nin vec2 vUv;\nout vec4 fragColor;\n\nuniform vec2  uResolution;\nuniform float uTime;\nuniform int   uPanelCount;\nuniform vec4  uBounds[MAX_PANELS];   // per-panel rect: xy = origin (UV), zw = size (UV)\nuniform vec2  uLightPos;             // key-light position (UV)\nuniform float uBlurRadius;           // blur kernel px scale\nuniform float uRefractionStrength;   // the DEPTH knob (squircle displacement)\nuniform float uChromatic;            // the fence operator \u2014 the absolute rim hue split\nuniform float uMetalStrength;        // the drapery/metal sheen composite\nuniform float uValveKnee;            // the K12 plate valve knee (structLuma threshold)\nuniform float uPlateAlphaMax;        // the alpha the valve firms to over a bright ridge\nuniform sampler2D uBackdrop;         // the field render (bound by the keystone FBO pass)\n\n// The pinned cross-stack chromatic scale (ONE source-of-truth; see CHROMATIC_SCALE).\nconst float CHROMATIC_SCALE = 0.0045;\n\n// \u2500\u2500 the ONE backdrop-read wrapper (explicit LOD; the Tier-2 sampleBG discipline) \u2500\u2500\nvec3 sampleBG(vec2 uv) {\n  return textureLod(uBackdrop, clamp(uv, 0.0, 1.0), 0.0).rgb;\n}\n\n// 4th-order squircle bevel profile: f(x)=\u2074\u221A(1-(1-x)\u2074). 0 at centre, 1 at rim, the\n// edge-concentrated slope (Snell n=1.5 thin-interior lens, NOT a uniform radial).\nfloat squircleProfile(float x) {\n  float t = 1.0 - clamp(x, 0.0, 1.0);\n  float t4 = t * t * t * t;\n  return sqrt(sqrt(max(0.0, 1.0 - t4)));\n}\n\nfloat fresnel(float cosTheta, float ior) {\n  float r0 = pow((1.0 - ior) / (1.0 + ior), 2.0);\n  return r0 + (1.0 - r0) * pow(1.0 - cosTheta, 5.0);\n}\n\nfloat luma(vec3 c) { return dot(c, vec3(0.2126, 0.7152, 0.0722)); }\n\n// scalar fbm potential \u2014 the host's noise basis, wrapped so curlFBM stays basis-\n// agnostic (the flow.glsl splice-order law). A cheap value-noise fbm for the sheen.\nfloat hash21(vec2 p) {\n  vec3 p3 = fract(vec3(p.xyx) * 0.1031);\n  p3 += dot(p3, p3.yzx + 33.33);\n  return fract((p3.x + p3.y) * p3.z);\n}\nfloat vnoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 w = f * f * (3.0 - 2.0 * f);\n  return mix(mix(hash21(i), hash21(i + vec2(1.0, 0.0)), w.x),\n             mix(hash21(i + vec2(0.0, 1.0)), hash21(i + vec2(1.0, 1.0)), w.x), w.y);\n}\nfloat potentialFBM(vec2 p) {\n  float v = 0.0, a = 0.5;\n  vec2 q = p;\n  for (int i = 0; i < 3; i++) { v += a * vnoise(q); q = q * 2.02 + vec2(1.7, 9.2); a *= 0.5; }\n  return v;\n}\n\n\nconst float CURL_EPS = 0.012;\n\n// Scalar fbm potential psi \u2014 the host's noise basis, wrapped so the curl operator is\n// basis-agnostic. A host carrying its own fbm defines this as: return fbm(p);\nfloat potentialFBM(vec2 p);\n\n// \u2207\u00D7\u03C8 in 2D \u2014 the divergence-free flow direction. Central finite differences of the\n// scalar potential give the partials; the cross-pairing (\u2202y, \u2212\u2202x) is the 2D curl.\nvec2 curlFBM(vec2 p) {\n  float dx = potentialFBM(p + vec2(CURL_EPS, 0.0)) - potentialFBM(p - vec2(CURL_EPS, 0.0));\n  float dy = potentialFBM(p + vec2(0.0, CURL_EPS)) - potentialFBM(p - vec2(0.0, CURL_EPS));\n  // \u03C8-gradient is (dx, dy)/(2\u00B7eps); the curl rotates it 90\u00B0: (\u2202\u03C8/\u2202y, \u2212\u2202\u03C8/\u2202x).\n  vec2 g = vec2(dx, dy) / (2.0 * CURL_EPS);\n  return vec2(g.y, -g.x);\n}\n\n\n// The glass material over one panel rect. Every sample flows through sampleBG.\nvec4 glassSample(vec2 uv, vec4 b) {\n  vec2 gmin = b.xy;\n  vec2 size = b.zw;\n  vec2 local = (uv - gmin) / size;      // 0..1 within panel\n  vec2 centered = local - vec2(0.5);    // -0.5..0.5\n\n  // REFRACTION = DEPTH: rim-concentrated squircle displacement (a pure UV offset).\n  float r = clamp(length(centered) * 2.0, 0.0, 1.0);\n  float prof = squircleProfile(r);\n  vec2 dir = normalize(centered + vec2(1e-5));\n  vec2 disp = dir * prof * (uRefractionStrength * 0.04 / 1.5);   // n=1.5\n  vec2 refrUv = uv + disp;\n\n  // the canonical edge-band rim mask (GLSL source-of-truth) \u2014 hue rides the RIM only.\n  vec2 toEdge = vec2(0.5) - abs(centered);       // 0 at the panel edge, 0.5 at centre\n  float edge = min(toEdge.x, toEdge.y);\n  float rim = 1.0 - smoothstep(0.0, 0.16, edge); // 1 at the rim band, 0 by 16% inward\n\n  vec2 px = 1.0 / uResolution;\n\n  // 3\u00D73 blur around the displaced UV (the demoted-blur read carrier) \u2014 explicit LOD.\n  vec3 col = vec3(0.0);\n  float wsum = 0.0;\n  for (int x = -1; x <= 1; x++) {\n    for (int y = -1; y <= 1; y++) {\n      vec2 o = vec2(float(x), float(y)) * px * max(uBlurRadius, 0.5);\n      float wgt = 1.0 - 0.25 * float(abs(x) + abs(y));\n      col += sampleBG(refrUv + o) * wgt;\n      wsum += wgt;\n    }\n  }\n  col /= wsum;\n\n  // HUE = ABSOLUTE rim offset: split R/B by ca = inward \u00B7 rim \u00B7 uChromatic \u00B7 CHROMATIC_SCALE.\n  vec2 inward = dir;\n  vec2 ca = inward * rim * uChromatic * CHROMATIC_SCALE;\n  float cr = sampleBG(refrUv + ca).r;\n  float cb = sampleBG(refrUv - ca).b;\n  col.r = mix(col.r, cr, rim * 0.6);\n  col.b = mix(col.b, cb, rim * 0.6);\n\n  // FULL PASS \u2014 the curl-drapery metal sheen (2nd curlFBM), gated by uMetalStrength.\n  vec2 flow = curlFBM(local * 3.0 + uTime * 0.05);\n  float sheen = potentialFBM(local * 5.0 + flow * 1.5 + uTime * 0.08);\n  col += vec3(smoothstep(0.55, 0.95, sheen) * uMetalStrength * 0.12);\n\n  // directional specular + Fresnel rim.\n  vec3 n = normalize(vec3(centered * 0.6, 1.0));\n  float spec = fresnel(max(n.z, 0.0), 1.5);\n  vec2 ldir = normalize(uLightPos - uv);\n  float ldot = max(dot(centered, ldir), 0.0);\n  col += vec3(spec * (0.3 + 0.7 * ldot) * 0.15);\n\n  // K12 ridge-local plate VALVE: firm the alpha toward uPlateAlphaMax over a BRIGHT\n  // ridge (AA legibility); the dim valley stays translucent so the metal reads.\n  float structLuma = luma(col);\n  float valve = smoothstep(uValveKnee, 1.0, structLuma);\n  float plateA = mix(0.9, uPlateAlphaMax, valve);\n\n  return vec4(col, plateA);\n}\n\nvoid main() {\n  vec2 uv = vUv;\n  vec3 color = sampleBG(uv);   // BASE: the field passes through unchanged.\n  float alpha = 1.0;\n\n  for (int i = 0; i < MAX_PANELS; i++) {\n    if (i >= uPanelCount) break;\n    vec4 b = uBounds[i];\n    vec2 gmin = b.xy;\n    vec2 gmax = b.xy + b.zw;\n    bool inside = uv.x >= gmin.x && uv.x <= gmax.x && uv.y >= gmin.y && uv.y <= gmax.y;\n    if (inside) {\n      vec4 s = glassSample(uv, b);\n      color = s.rgb;\n      alpha = s.a;\n    }\n  }\n\n  fragColor = vec4(color, alpha);\n}";

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

@@ -1,3 +1,5 @@
+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
@@ -14,6 +16,21 @@
  * `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 {
@@ -21,8 +38,14 @@ export interface WebGLCanvasFrame {
     frame: (timeSec: number) => void;
     /** Demand-gate: is there live motion to render next frame? `false` → park. */
     shouldContinue: () => boolean;
-    /** Size the canvas + set the viewport. The consumer owns its DPR policy. */
-    resize: () => void;
+    /**
+     * Upload the backing geometry to the viewport/uniforms. BD.W-SUBSTRATE-SIZE-UNIFY:
+     * 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
+     * consumer keeps compiling until it adopts the leaf sizer.
+     */
+    resize: (s?: BackingSize) => void;
     /** Frame time from elapsed seconds — the consumer owns frozen/reduced-motion. */
     time?: (elapsedSec: number) => number;
     /** Delete GL resources (program/buffers/VAO). Runs on dispose + before a restore re-setup. */
@@ -42,6 +65,19 @@ export interface WebGLCanvasOptions {
      * reads the live value via `handle.reducedMotion` (e.g. aurora's frozen-t).
      */
     respectReducedMotion?: boolean;
+    /**
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G1/G2) — 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). */
+    composeIntersectionPark?: boolean;
+    /** `rootMargin` for the leaf IO park (G3). */
+    intersectionRootMargin?: string;
+    /** Fire the one-shot cold-first-VISIBLE entrance bloom (BG.W-VIZ-REVEAL-BLOOM — the `data-substrate-reveal` attr). Default `false`. */
+    revealBloom?: boolean;
     /**
      * Build the program + geometry on a fresh context. Called on `arm()` AND on
      * every `webglcontextrestored`. Returns the per-frame hooks.
@@ -51,6 +87,8 @@ export interface WebGLCanvasOptions {
 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). */
+    presize: () => void;
     suspend: (reason?: WebGLSuspendReason) => void;
     resume: (reason?: WebGLSuspendReason) => void;
     /** Re-arm a parked loop (a setter that re-introduced motion calls this). */

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

@@ -0,0 +1,42 @@
+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
+ * 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).
+ */
+export interface CanvasVisibilityDeps {
+    canvas: HTMLCanvasElement;
+    suspend: (reason: CanvasSuspendReason) => void;
+    resume: (reason: CanvasSuspendReason) => void;
+    resize: () => void;
+    wake: () => void;
+    isArmed: () => boolean;
+    hasHooks: () => boolean;
+    isDisposed: () => boolean;
+    isReducedMotion: () => boolean;
+    composeIntersectionPark: boolean;
+    intersectionRootMargin?: string;
+    revealBloom: boolean;
+}
+export interface CanvasVisibility {
+    /**
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing store + 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.
+     */
+    presize(): void;
+    /** Bind the content-visibility + intersection park observers (called at arm). */
+    bindPark(): void;
+    /** Arm the one-shot first-visible entrance bloom (called at arm, after armed=true). */
+    armRevealBloom(): void;
+    /** Detach every observer/listener owned here. */
+    dispose(): void;
+}
+/**
+ * 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.
+ */
+export declare function createCanvasVisibility(deps: CanvasVisibilityDeps): CanvasVisibility;

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

@@ -1,2 +1,3 @@
 export { createWebGPUCanvas, supportsWebGPU, WebGPUInitError, type WebGPUCanvasFrame, type WebGPUCanvasHandle, type WebGPUCanvasOptions, type WebGPUSuspendReason, } from "./useWebGPUCanvas";
 export { createGpuSubstrate, type GpuBackend, type GpuSubstrateHandle, type GpuSubstrateOptions, } from "./useGpuSubstrate";
+export { sizeBacking, type BackingSize, type DprPolicy, } from "../webgl/createCanvasLifecycle";

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

@@ -1,4 +1,6 @@
 import { type WebGLCanvasFrame, type WebGLCanvasOptions } from "../webgl/useWebGLCanvas";
+import type { DprPolicy } from "../webgl/createCanvasLifecycle";
+export type { BackingSize, DprPolicy } from "../webgl/createCanvasLifecycle";
 import { supportsWebGPU, type WebGPUCanvasFrame, type WebGPUCanvasOptions } from "./useWebGPUCanvas";
 export { supportsWebGPU };
 /** Which backend the picker resolved. */
@@ -15,6 +17,33 @@ export interface GpuSubstrateOptions {
     setupWGPU?: WebGPUCanvasOptions["setup"];
     /** The GLSL program builder (the WebGL2 fallback path — always required). */
     setupGL: WebGLCanvasOptions["setup"];
+    /**
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G1/G2) — the consumer's DPR policy (a flat multiplier
+     * or a box-aware resolver). When PRESENT the leaf owns the backing-store measurement
+     * + sizes it SYNCHRONOUSLY at mount (the ONE sizer; before the async acquire on the
+     * WebGPU path), handing the live `BackingSize` to each `setup`'s `resize(s)`. When
+     * ABSENT the legacy path runs (the consumer self-measures) — the per-viz adoption
+     * seam, identical on both backends.
+     */
+    dprPolicy?: DprPolicy;
+    /**
+     * G3 — compose the leaf IntersectionObserver park (a consumer inherits the
+     * off-screen IO-park ORed with content-visibility, no per-viz `useIntersectionPause`
+     * wiring). Default `false` (OPT-IN): several consumers already write `"off-screen-io"`
+     * from their own `useIntersectionPause` and a leaf IO default-on would double-write
+     * that reason. A viz with NO IO wiring (concentric/fourier/dot-flow) opts IN.
+     */
+    composeIntersectionPark?: boolean;
+    /** `rootMargin` for the leaf IO park (G3). Default `"256px"`. */
+    intersectionRootMargin?: string;
+    /**
+     * BG.W-VIZ-REVEAL-BLOOM — fire the one-shot cold-first-VISIBLE entrance bloom (a
+     * one-shot `data-substrate-reveal` attr on the canvas the CSS `@keyframes
+     * substrate-reveal-bloom` reads to ramp `filter: brightness()` from a dim floor,
+     * overshoot past 1.0 on `--ease-cartoon-punch`, then settle). Fires at first-visible,
+     * one-shot (zero second bloom), PRM-instant. Default `false` (opt-in per viz).
+     */
+    revealBloom?: boolean;
     /** WebGPU `context.configure` alpha mode (default `"premultiplied"`). */
     alphaMode?: WebGPUCanvasOptions["alphaMode"];
     /** WebGPU adapter/device request options. */
@@ -55,6 +84,15 @@ export interface GpuSubstrateHandle {
     armAsync: () => Promise<void>;
     /** Synchronous arm (the WebGL2 net arms immediately; the WebGPU path is a no-op until the device resolves). */
     arm: () => void;
+    /**
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing store + start the leaf RO
+     * SYNCHRONOUSLY, decoupled from the (async) backend acquire. Call it the instant the
+     * canvas is in the DOM so the field is sharp from frame 0 while the device resolves
+     * (the ≤6s blurry-flash close). `armAsync` already calls it internally on both legs;
+     * exposed so a consumer can presize even earlier (e.g. immediately on mount, before
+     * the awaited `armAsync`). A no-op when no `dprPolicy` was supplied (legacy).
+     */
+    presize: () => void;
     suspend: (reason?: "tab-hidden" | "off-screen" | "off-screen-io" | "manual") => void;
     resume: (reason?: "tab-hidden" | "off-screen" | "off-screen-io" | "manual") => void;
     wake: () => void;