kuinetic 0.1.3 → 0.2.0

package/dist/esm/advanced/index.mjs

@@ -0,0 +1,4727 @@
+import {
+  createStyleClaim
+} from "../chunk-AEQGC2KM.mjs";
+
+// src/advanced/glsl.ts
+var AUDIO_GAIN_GLSL = `uniform float u_audio;
+float audioGain() { return 1.0 + clamp(u_audio, 0.0, 1.0); }
+`;
+var SHAPE_MASK_GLSL = `uniform vec4 u_maskBox;
+uniform vec4 u_maskRx;
+uniform vec4 u_maskRy;
+uniform float u_maskAlpha;
+float shapeMask() {
+  if (u_maskBox.z <= 0.0 || u_maskBox.w <= 0.0) return u_maskAlpha;
+  vec2 p = gl_FragCoord.xy - u_maskBox.xy;
+  vec2 h = u_maskBox.zw;
+  bool left = p.x < 0.0;
+  float rx = p.y >= 0.0 ? (left ? u_maskRx.x : u_maskRx.y) : (left ? u_maskRx.w : u_maskRx.z);
+  float ry = p.y >= 0.0 ? (left ? u_maskRy.x : u_maskRy.y) : (left ? u_maskRy.w : u_maskRy.z);
+  rx = min(rx, h.x);
+  ry = min(ry, h.y);
+  if (rx <= 0.0 || ry <= 0.0) return u_maskAlpha;
+  vec2 q = abs(p) - (h - vec2(rx, ry));
+  if (q.x <= 0.0 || q.y <= 0.0) return u_maskAlpha;
+  float d = (length(q / vec2(rx, ry)) - 1.0) * min(rx, ry);
+  return u_maskAlpha * clamp(0.5 - d, 0.0, 1.0);
+}
+`;
+var NOISE_GLSL = `const int KUI_MAX_OCTAVES = 6;
+
+/**
+ * Integer avalanche over one lattice coordinate.
+ *
+ * Deliberately not the \`fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453)\` idiom. That relies
+ * on the low bits of a large sine, which \`highp\` does not reliably have: on several mobile GPUs
+ * neighbouring cells stay correlated and the field bands visibly. GLSL ES 3.00 has real unsigned
+ * integer arithmetic, so a proper mix is both better distributed and cheaper.
+ */
+uint kuiHash(uvec3 v) {
+  uint h = v.x * 0x8da6b343u ^ v.y * 0xd8163841u ^ v.z * 0xcb1ab31fu;
+  h ^= h >> 15u; h *= 0x2c1b3c6du;
+  h ^= h >> 12u; h *= 0x297a2d39u;
+  h ^= h >> 15u;
+  return h;
+}
+
+/**
+ * A unit gradient vector for one lattice corner.
+ *
+ * The three components read *non-overlapping* 10-bit fields. Overlapping slices of one hash are
+ * correlated with each other, which shows up as gradients clustering around a diagonal and the
+ * noise developing a directional grain. The \`1e-5\` keeps \`normalize\` defined for the one input
+ * that hashes to exactly zero.
+ */
+vec3 kuiGradient(uvec3 cell) {
+  uint h = kuiHash(cell);
+  vec3 g = vec3(
+    float((h        ) & 1023u),
+    float((h >> 10u ) & 1023u),
+    float((h >> 20u ) & 1023u)
+  ) * (2.0 / 1023.0) - 1.0;
+  return normalize(g + vec3(1e-5));
+}
+
+/**
+ * One octave of gradient noise, approximately -1..1.
+ *
+ * The lattice index is biased into unsigned space before hashing: seeds, scroll and a centred UV
+ * field all reach negative coordinates, and \`uvec3\` of a negative \`ivec3\` wraps \u2014 which is
+ * harmless for a hash, but only once every negative input maps somewhere distinct rather than
+ * folding onto its positive twin.
+ */
+float kuiNoise(vec3 p) {
+  vec3 i = floor(p);
+  vec3 f = p - i;
+  vec3 w = f * f * f * (f * (f * 6.0 - 15.0) + 10.0);
+  uvec3 c = uvec3(ivec3(i) + 0x10000);
+  float n000 = dot(kuiGradient(c + uvec3(0u, 0u, 0u)), f - vec3(0.0, 0.0, 0.0));
+  float n100 = dot(kuiGradient(c + uvec3(1u, 0u, 0u)), f - vec3(1.0, 0.0, 0.0));
+  float n010 = dot(kuiGradient(c + uvec3(0u, 1u, 0u)), f - vec3(0.0, 1.0, 0.0));
+  float n110 = dot(kuiGradient(c + uvec3(1u, 1u, 0u)), f - vec3(1.0, 1.0, 0.0));
+  float n001 = dot(kuiGradient(c + uvec3(0u, 0u, 1u)), f - vec3(0.0, 0.0, 1.0));
+  float n101 = dot(kuiGradient(c + uvec3(1u, 0u, 1u)), f - vec3(1.0, 0.0, 1.0));
+  float n011 = dot(kuiGradient(c + uvec3(0u, 1u, 1u)), f - vec3(0.0, 1.0, 1.0));
+  float n111 = dot(kuiGradient(c + uvec3(1u, 1u, 1u)), f - vec3(1.0, 1.0, 1.0));
+  float nx00 = mix(n000, n100, w.x);
+  float nx10 = mix(n010, n110, w.x);
+  float nx01 = mix(n001, n101, w.x);
+  float nx11 = mix(n011, n111, w.x);
+  // 2/sqrt(3) \u2014 a 3D gradient-noise octave peaks near sqrt(3)/2, so this brings it to about -1..1.
+  return mix(mix(nx00, nx10, w.y), mix(nx01, nx11, w.y), w.z) * 1.1547;
+}
+
+/**
+ * Octaves summed and **normalised by the amplitude sum**, approximately -1..1 at every octave count.
+ *
+ * The division is the whole point of the function. Without it, raising the octave count raises the
+ * total amplitude, so the one authored knob that means "how much fine structure" would silently be
+ * a contrast control as well \u2014 two behaviours behind one parameter, which is the class of bug this
+ * repository keeps rediscovering. Gain and lacunarity stay fixed at 0.5 and 2.0: they are the two
+ * numbers that make layered noise look wrong in a hundred ways and right in one.
+ *
+ * The loop bound is a constant with an early break because a loop bound that is itself a uniform
+ * forces some drivers to unroll against the worst case anyway, and this way the cost of a low
+ * \`detail\` is genuinely low.
+ */
+float kuiFbm(vec3 p, int octaves) {
+  float amp = 1.0;
+  float freq = 1.0;
+  float sum = 0.0;
+  float norm = 0.0;
+  for (int i = 0; i < KUI_MAX_OCTAVES; i++) {
+    if (i >= octaves) break;
+    sum += amp * kuiNoise(p * freq);
+    norm += amp;
+    amp *= 0.5;
+    freq *= 2.0;
+  }
+  return sum / max(norm, 1e-5);
+}
+`;
+var FILTER_NOISE_GLSL = `uniform float u_noise;
+uniform float u_seed;
+uniform float u_scale;
+uniform float u_warp;
+uniform int u_detail;
+
+/**
+ * A sine's RMS is 0.707. Amplitude-normalised fbm's is about 0.23 \u2014 it reaches its \`1.0\` peak
+ * rarely, which is what makes it look like noise rather than a wave. Handing the programs the raw
+ * field would therefore read as the *effect being turned down*, not as it being re-textured, and
+ * the first thing anyone trying \`noise: 1\` would do is reach for \`strength\`. This brings the two
+ * to the same typical magnitude so the amount is a change of texture and nothing else.
+ */
+const float KUI_FBM_SINE_RMS = 3.0;
+
+/**
+ * One scalar of animated noise, scaled to stand in for a unit sine at a stated rate.
+ *
+ * \`cycles\` and \`rate\` are the spatial and temporal frequency of the term being replaced, in
+ * cycles rather than radians \u2014 each call site divides its own trig coefficients by 2*pi and passes
+ * the result, so \`noise: 1\` lands on the same feature size and the same speed as the wave it took
+ * over from. That is the entire mechanism keeping this from being a new look.
+ *
+ * \`phase\` decorrelates sibling calls: two components of one flow vector must not be the same
+ * field, and offsetting the seed is cheaper than hashing a second one.
+ *
+ * \`u_warp\` costs two further fbm evaluations and is skipped entirely when it is zero.
+ */
+float kuiFilterField(vec2 uv, float t, float cycles, float rate, float phase) {
+  vec3 s = vec3(u_seed * 137.31, u_seed * 71.17, u_seed * 29.73) + phase;
+  vec3 q = vec3((uv - 0.5) * cycles * max(u_scale, 0.05), t * rate) + s;
+  if (u_warp > 0.0) {
+    float wx = kuiFbm(q * 0.5 + vec3(5.2, 1.3, 7.1), u_detail);
+    float wy = kuiFbm(q * 0.5 + vec3(19.7, 11.1, 3.7), u_detail);
+    q.xy += vec2(wx, wy) * u_warp;
+  }
+  return kuiFbm(q, u_detail) * KUI_FBM_SINE_RMS;
+}
+`;
+var FULLSCREEN_QUAD_VS = `#version 300 es
+in vec2 a_position;
+uniform vec2 u_uvOrigin;
+uniform vec2 u_uvScale;
+out vec2 v_uv;
+void main() {
+  vec2 uv = (a_position + 1.0) * 0.5;
+  uv.y = 1.0 - uv.y;
+  v_uv = u_uvOrigin + uv * u_uvScale;
+  gl_Position = vec4(a_position, 0.0, 1.0);
+}
+`;
+var DISPLACE_FS = `#version 300 es
+precision highp float;
+in vec2 v_uv;
+out vec4 fragColor;
+uniform sampler2D u_image;
+uniform float u_time;
+uniform float u_strength;
+uniform float u_frequency;
+uniform float u_chromatic;
+uniform vec2 u_mouse;
+uniform vec4 u_tint;
+uniform int u_blend;
+uniform float u_duotone;
+uniform vec4 u_color1;
+uniform vec4 u_color2;
+uniform float u_progress;
+${AUDIO_GAIN_GLSL}${SHAPE_MASK_GLSL}
+vec4 applyBlend(vec4 base, vec4 tint, int mode) {
+  // \`base\` is premultiplied \u2014 \`createGLTexture\` uploads with \`UNPACK_PREMULTIPLY_ALPHA_WEBGL\` to
+  // match a \`premultipliedAlpha: true\` context \u2014 while \`tint\` is straight rgba out of
+  // \`parseColor\`. All four blends are defined on *straight* colour, so every mode takes the same
+  // path: un-premultiply, blend, and re-premultiply by this pixel's own coverage.
+  //
+  // Screen and add were the obvious cases. Run over all four premultiplied components,
+  // \`screen((0,0,0,0), (1,0,0,1))\` is \`(1,0,0,1)\`, an opaque red pixel where the source had no
+  // coverage at all \u2014 \`blend: screen tint: red\` filled a transparent PNG's surround with a solid
+  // red rectangle. Normal and multiply *looked* safe as a plain \`base * tint\`, because a transparent
+  // base does multiply to transparent whatever the tint is. It is the tint's alpha they got wrong:
+  // \`(1,1,1,1) * (1,0,0,0)\` is \`(1,0,0,0)\`, red at zero coverage, and a premultiplied canvas
+  // composites \`rgb > a\` *additively* \u2014 \`tint: rgba(255,0,0,0)\`, a fully transparent tint, turned
+  // an opaque image red, and any translucent tint bled the same way in proportion.
+  //
+  // The \`min\` on \`s\` is for \`main()\`'s chromatic sampling, which reads the three colour channels
+  // at three offsets and \`a\` at a fourth: at a transparent PNG's edge that can pair \`rgb\` from
+  // opaque neighbours with \`a\` from a transparent centre, an input that already breaks the
+  // invariant. Clamping the un-premultiplied colour to 1 is what keeps the output inside it.
+  //
+  // Alpha is \`base.a * tint.a\` \u2014 the source's coverage, faded by a translucent tint. Whatever the
+  // mode, the result satisfies \`rgb <= a\`, which is the whole contract of a premultiplied pixel.
+  float a = base.a * tint.a;
+  vec3 s = base.a > 0.0 ? min(base.rgb / base.a, vec3(1.0)) : vec3(0.0);
+  vec3 c = mode == 1 ? 1.0 - (1.0 - s) * (1.0 - tint.rgb)
+         : mode == 3 ? min(s + tint.rgb, vec3(1.0))
+         : s * tint.rgb;
+  return vec4(c * a, a);
+}
+
+void main() {
+  vec2 m = u_mouse;
+  float d = distance(v_uv, m);
+  float ripple = sin(d * u_frequency - u_time * 3.0) * exp(-d * 4.0);
+  float pFactor = u_progress >= 0.0 ? u_progress : 1.0;
+  // Audio widens the ripple's throw (up to 2x), leaving its shape and speed alone.
+  vec2 disp = normalize(v_uv - m + 0.0001) * ripple * u_strength * 0.05 * pFactor * audioGain();
+
+  float cr = texture(u_image, v_uv + disp * (1.0 + u_chromatic)).r;
+  float cg = texture(u_image, v_uv + disp).g;
+  float cb = texture(u_image, v_uv + disp * (1.0 - u_chromatic)).b;
+  float ca = texture(u_image, v_uv + disp).a;
+  vec4 color = vec4(cr, cg, cb, ca);
+
+  if (u_duotone > 0.5) {
+    float lum = dot(color.rgb, vec3(0.299, 0.587, 0.114));
+    // \`* color.a\` because the ramp's two colours are straight rgba and everything downstream of
+    // here is premultiplied. Assigning one of them to a transparent pixel's \`rgb\` left \`rgb > 0\`
+    // with \`a == 0\`, which a \`premultipliedAlpha: true\` canvas composites *additively* \u2014 a
+    // transparent PNG's surround glowing in \`color1\` over whatever the page put behind it.
+    //
+    // \`lum\` is still read off the premultiplied colour, which is deliberate and unchanged: it
+    // makes a half-covered pixel map nearer \`color1\`, matching how the alpha stencil in
+    // \`GENERATIVE_FS\` reads the same kind of edge.
+    color.rgb = mix(u_color1.rgb, u_color2.rgb, lum) * color.a;
+  }
+
+  fragColor = applyBlend(color, u_tint, u_blend) * shapeMask();
+}
+`;
+var FLUID_FS = `#version 300 es
+precision highp float;
+in vec2 v_uv;
+out vec4 fragColor;
+uniform sampler2D u_image;
+uniform float u_time;
+uniform float u_strength;
+uniform vec2 u_mouse;
+uniform vec4 u_tint;
+uniform float u_progress;
+${AUDIO_GAIN_GLSL}${SHAPE_MASK_GLSL}${NOISE_GLSL}${FILTER_NOISE_GLSL}
+void main() {
+  vec2 uv = v_uv;
+  vec2 m = u_mouse;
+  float d = distance(uv, m);
+  // Audio scales both halves of the flow \u2014 the ambient drift and the pointer's push \u2014 so a beat
+  // reads as the whole surface moving faster, not just around the cursor.
+  float gain = audioGain();
+  float force = exp(-d * 6.0) * u_strength * gain;
+  // The ambient drift. Two perpendicular waves at 10 rad across the box and 1 rad/s, which is
+  // 10/2pi = 1.5915 cycles and 1/2pi = 0.1592 cycles a second \u2014 the numbers kuiFilterField needs
+  // to put its field at the same size and speed. The drift is the whole of the ambient motion
+  // here, so this is the mode where the noise core reads most strongly: a regular cross-hatched
+  // sway becomes an irregular current.
+  vec2 wave = vec2(sin(u_time + uv.y * 10.0), cos(u_time + uv.x * 10.0));
+  if (u_noise > 0.0) {
+    wave = mix(wave, vec2(
+      kuiFilterField(uv, u_time, 1.5915, 0.1592, 0.0),
+      kuiFilterField(uv, u_time, 1.5915, 0.1592, 31.4)
+    ), u_noise);
+  }
+  vec2 flow = wave * 0.02 * gain;
+  float pFactor = u_progress >= 0.0 ? u_progress : 1.0;
+  vec2 offset = (flow + (uv - m) * force * 0.1) * pFactor;
+  fragColor = texture(u_image, uv + offset) * u_tint * shapeMask();
+}
+`;
+var LIQUID_FS = `#version 300 es
+precision highp float;
+in vec2 v_uv;
+out vec4 fragColor;
+uniform sampler2D u_image;
+uniform float u_time;
+uniform float u_strength;
+uniform vec4 u_tint;
+uniform float u_progress;
+${AUDIO_GAIN_GLSL}${SHAPE_MASK_GLSL}${NOISE_GLSL}${FILTER_NOISE_GLSL}
+void main() {
+  vec2 uv = v_uv;
+  // 12 rad and 2 rad/s is 1.9099 cycles at 0.3183 a second; 10 rad and 1.5 rad/s is 1.5915 at
+  // 0.2387. The two waves keep their own rates under noise rather than being merged into one
+  // field, because the difference between them is what stops the surface reading as a single
+  // sheet sliding.
+  float w1 = sin(uv.y * 12.0 + u_time * 2.0);
+  float w2 = cos(uv.x * 10.0 - u_time * 1.5);
+  if (u_noise > 0.0) {
+    w1 = mix(w1, kuiFilterField(uv, u_time, 1.9099, 0.3183, 0.0), u_noise);
+    w2 = mix(w2, kuiFilterField(uv, u_time, 1.5915, 0.2387, 47.3), u_noise);
+  }
+  w1 *= 0.015;
+  w2 *= 0.015;
+  float pFactor = u_progress >= 0.0 ? u_progress : 1.0;
+  // Audio deepens the wave (up to 2x) without changing its wavelength or speed.
+  vec2 offset = vec2(w1, w2) * u_strength * pFactor * audioGain();
+  fragColor = texture(u_image, uv + offset) * u_tint * shapeMask();
+}
+`;
+var PARTICLES_FS = `#version 300 es
+precision highp float;
+in vec2 v_uv;
+out vec4 fragColor;
+uniform sampler2D u_image;
+uniform float u_time;
+uniform float u_strength;
+uniform vec4 u_tint;
+uniform float u_progress;
+${AUDIO_GAIN_GLSL}${SHAPE_MASK_GLSL}${NOISE_GLSL}${FILTER_NOISE_GLSL}
+// No u_mouse here, deliberately. This program declared one from the day it was written and never
+// read it, so particles has never responded to the pointer \u2014 the declaration was a promise the
+// body did not keep, and the compiler dropped it anyway (an unused uniform gets no location, so
+// uploadCoordUniforms was already skipping it and removing it changes no pixel). It is deleted
+// rather than wired because wiring it would restyle a mode that is already in use without anyone
+// asking, which is the same argument FILTER_NOISE_GLSL's doc makes for noise: being opt-in. The
+// pointer gesture that *was* asked for lives on the generative program below, under hover:.
+void main() {
+  vec2 uv = v_uv;
+  vec2 grid = fract(uv * 40.0) - 0.5;
+  float dist = length(grid);
+  // 100 rad across the box and 5 rad/s is 15.915 cycles at 0.7958 a second. That is by far the
+  // highest frequency of the four, and deliberately so: the trig term here is a diagonal travelling
+  // stripe, which is the most visible of the four repeats. Under noise the stripe becomes a
+  // scintillation, which is the largest change of the set and is the reason the parameter exists
+  // rather than the swap being unconditional.
+  //
+  // The clamp is not damage control. Mapped through KUI_FBM_SINE_RMS the field reaches 0 and 1
+  // often, which is what a sine does too \u2014 sin()*0.5+0.5 is arcsine-distributed and spends most of
+  // its time at the extremes. Clamping reproduces that; a soft field would give a duller sparkle
+  // than the one being replaced.
+  //
+  // Cost: this is one fbm per pixel, three with warp on, over the whole quad. At detail 6 the
+  // finest octave here sits near 509 cycles across the box, which is sub-pixel on a small element
+  // and will alias \u2014 high detail belongs on the low-frequency modes.
+  float sparkle = sin(u_time * 5.0 + dot(uv, vec2(100.0))) * 0.5 + 0.5;
+  if (u_noise > 0.0) {
+    float n = clamp(kuiFilterField(uv, u_time, 15.915, 0.7958, 0.0) * 0.5 + 0.5, 0.0, 1.0);
+    sparkle = mix(sparkle, n, u_noise);
+  }
+  vec4 tex = texture(u_image, uv);
+  float pFactor = u_progress >= 0.0 ? u_progress : 1.0;
+  float dotMask = smoothstep(0.4, 0.2, dist) * u_strength * pFactor;
+  // Audio brightens the sparkle (0.3 -> at most 0.6) rather than growing the dots: the mask is
+  // already multiplied by an unbounded u_strength and feeds a mix(), so widening it would
+  // extrapolate past the texture over a larger and larger area.
+  fragColor = mix(tex, tex * u_tint + sparkle * 0.3 * audioGain(), dotMask) * shapeMask();
+}
+`;
+var MORPH_FS = `#version 300 es
+precision highp float;
+in vec2 v_uv;
+out vec4 fragColor;
+uniform sampler2D u_image;
+uniform sampler2D u_image_to;
+uniform float u_time;
+uniform float u_strength;
+uniform float u_progress;
+${AUDIO_GAIN_GLSL}${SHAPE_MASK_GLSL}${NOISE_GLSL}${FILTER_NOISE_GLSL}
+void main() {
+  vec2 uv = v_uv;
+  float progress = u_progress >= 0.0 ? clamp(u_progress, 0.0, 1.0) : clamp(u_strength, 0.0, 1.0);
+  // Audio wobbles the crossfade harder. Deliberately not applied to u_progress: the morph's
+  // position between the two images belongs to the author (or to scroll), and letting a beat
+  // drive it would make the transition jump backwards on every quiet frame.
+  //
+  // 20 rad and 1 rad/s is 3.1831 cycles at 0.1592 a second. The 0.7071 is the one place the shared
+  // RMS gain is wrong by construction: the term being replaced is a *product* of two unit sines,
+  // whose RMS is 0.5 rather than a single sine's 0.7071, so matching it means taking the field
+  // down by that ratio. Without it the displacement under noise would be about 40% deeper than
+  // the one it stands in for \u2014 a visibly stronger morph, not the same one better textured.
+  float noise = sin(uv.x * 20.0 + u_time) * cos(uv.y * 20.0 + u_time);
+  if (u_noise > 0.0) {
+    noise = mix(noise, kuiFilterField(uv, u_time, 3.1831, 0.1592, 0.0) * 0.7071, u_noise);
+  }
+  noise = noise * 0.05 * audioGain();
+  vec4 c1 = texture(u_image, uv + vec2(noise * (1.0 - progress)));
+  vec4 c2 = texture(u_image_to, uv - vec2(noise * progress));
+  fragColor = mix(c1, c2, smoothstep(0.2, 0.8, progress)) * shapeMask();
+}
+`;
+var GRADIENT_FS = `#version 300 es
+precision highp float;
+in vec2 v_uv;
+out vec4 fragColor;
+uniform float u_time;
+uniform float u_strength;
+uniform float u_frequency;
+uniform float u_chromatic;
+uniform float u_iridescence;
+uniform float u_progress;
+uniform float u_seed;
+uniform float u_scale;
+uniform float u_warp;
+uniform float u_grain;
+uniform float u_hue;
+uniform int u_detail;
+uniform int u_bands;
+uniform int u_colorCount;
+uniform vec4 u_colors[5];
+uniform vec4 u_tint;
+uniform sampler2D u_image;
+uniform int u_maskMode;
+uniform vec2 u_mouse;
+uniform int u_hover;
+uniform vec4 u_backdrop;
+uniform float u_angle;
+uniform int u_motion;
+${AUDIO_GAIN_GLSL}${SHAPE_MASK_GLSL}${NOISE_GLSL}
+
+/** \`hover:\` as bits, so \`both\` is \`stir | light\` rather than a third code path. */
+const int KUI_HOVER_STIR = 1;
+const int KUI_HOVER_LIGHT = 2;
+
+/** \`motion:\` \u2014 \`0\` is \`evolve\`, which is this program's original behaviour and its default. */
+const int KUI_MOTION_DRIFT = 1;
+const int KUI_MOTION_SWIRL = 2;
+
+/**
+ * Rotate a point of the field's domain.
+ *
+ * \`v_uv\` is y-down, so this matrix \u2014 the ordinary counter-clockwise one \u2014 turns the *picture*
+ * clockwise, which is \`transform: rotate()\`'s direction and therefore the one an author already
+ * has an intuition for. Every call site passes \`-angle\`: rotating the sample point one way is
+ * what rotates what you see the other.
+ */
+vec2 kuiRotate(vec2 v, float a) {
+  float c = cos(a);
+  float s = sin(a);
+  return vec2(v.x * c - v.y * s, v.x * s + v.y * c);
+}
+
+/**
+ * The pair of factors that carry a centred UV offset into a space that is isotropic **on screen**,
+ * and back out again by dividing.
+ *
+ * \`v_uv\` is normalised per axis, so one unit of \`v_uv.x\` is the box's whole width and one unit of
+ * \`v_uv.y\` is its whole height \u2014 two different numbers of screen pixels as soon as the box is not
+ * square. Anything round or rigid has to leave that space first. Scaling by \`(k, 1/k)\` for
+ * \`k = sqrt(halfWidth / halfHeight)\` puts both axes in units of \`sqrt(width * height)\`: a circle
+ * stays a circle, a rotation stays a rotation, and the unit tracks the box's overall size rather
+ * than one of its two dimensions. On a square box the pair is exactly \`(1, 1)\` and every user of
+ * it degenerates to the plain UV arithmetic it had before.
+ *
+ * It is a *ratio* of the two half-extents, so it is DPR-invariant \u2014 device pixel ratio scales
+ * \`u_maskBox.z\` and \`u_maskBox.w\` together and cancels.
+ *
+ * A zero half-extent is \`shapeMask()\`'s "no box measured" signal and is read the same way here:
+ * fall back to \`(1, 1)\` rather than divide by it.
+ */
+vec2 kuiAspectAxes() {
+  if (u_maskBox.z > 0.0 && u_maskBox.w > 0.0) {
+    float k = sqrt(u_maskBox.z / u_maskBox.w);
+    return vec2(k, 1.0 / k);
+  }
+  return vec2(1.0);
+}
+
+/**
+ * Turn a centred UV offset by \`a\`, rigidly **on screen** rather than in the field's own stretched
+ * space.
+ *
+ * \`A^-1 \xB7 R(a) \xB7 A\`, with \`A = diag(kuiAspectAxes())\`: leave the per-axis-normalised space, turn
+ * there, come back. Rotating without the conjugation turns *and shears* \u2014 on a 160x100 box an
+ * authored \`angle: 45deg\` actually travels at 32 degrees, an error that grows with how far from
+ * square the box is. \`angle\` is documented as \`transform: rotate()\`'s convention, and this is what
+ * makes that true of a wide box and not only of a square one.
+ *
+ * **Not bit-identical at \`a == 0\`**, and that matters: \`A^-1 \xB7 I \xB7 A\` is \`diag(k * (1/k), (1/k) * k)\`,
+ * which in IEEE 754 is about an ulp away from the identity per axis rather than exactly it. Every
+ * caller must therefore keep its existing exact-zero guard \u2014 the defaults are unchanged because
+ * nothing here executes at them, not because this collapses.
+ *
+ * \`scale\` is a scalar and commutes with all three matrices, so a zoomed offset can be passed
+ * straight in: \`A^-1 R A (zoom * d)\` is \`zoom * (A^-1 R A d)\`.
+ */
+vec2 kuiRotateScreen(vec2 v, float a) {
+  vec2 s = kuiAspectAxes();
+  return kuiRotate(v * s, a) / s;
+}
+
+/**
+ * How strongly the pointer reaches this fragment: 1 under it, falling to nothing at the edge of a
+ * **round** pool.
+ *
+ * Round is the whole difficulty. \`v_uv\` and \`u_mouse\` are both normalised per axis, so the
+ * obvious \`distance(v_uv, u_mouse)\` draws an *ellipse* as soon as the box is not square \u2014 and the
+ * boxes this mode is documented for are full-bleed bands, card faces and footer strips, i.e.
+ * precisely the wide ones. \`kuiAspectAxes()\` is the correction, and measuring the offset there
+ * makes the pool a circle on screen whose size tracks the box's overall scale rather than one of
+ * its two dimensions. On a square box the pair is exactly \`(1, 1)\` and this degenerates to the
+ * plain UV distance \`displace\` already uses.
+ *
+ * Gaussian rather than \`smoothstep\`, because a pool of light has no edge to see.
+ */
+float kuiHoverFalloff() {
+  vec2 d = (v_uv - u_mouse) * kuiAspectAxes();
+  return exp(-dot(d, d) * 6.0);
+}
+
+/**
+ * One point of the element's UV square, in the field's own frame.
+ *
+ * A rigid motion \u2014 one rotation and one translation \u2014 so that carrying the pointer through the
+ * same call puts it at the same place relative to the field that it occupies on screen. That is
+ * what lets \`stir\` swirl the field about a centre the cursor is actually sitting on, at any
+ * \`angle\`, mid-\`drift\`, mid-\`swirl\`.
+ *
+ * The turn is \`kuiRotateScreen\`, so it is rigid **on screen** on a box of any shape: \`angle: 45deg\`
+ * points at 45 degrees on a 160x100 band, and \`motion: drift\` travels along exactly the axis the
+ * author named instead of a sheared one.
+ *
+ * Inert at the defaults by construction: \`orient\` of zero skips the rotation entirely and
+ * \`travel\` of zero subtracts an exact zero, so \`motion: evolve\` at \`angle: 0deg\` computes the
+ * same \`(v_uv - 0.5) * scale\` this program has always computed, bit for bit. **The guard is the
+ * whole of that promise** \u2014 \`kuiRotateScreen\` does not collapse to the identity at zero, it only
+ * gets within an ulp, so deleting the guard because "a rotation is cheap" would silently move the
+ * last bit of every generative pixel already on the web.
+ */
+vec2 kuiFieldPoint(vec2 uv, float zoom, float orient, float travel) {
+  vec2 v = (uv - 0.5) * zoom;
+  if (orient != 0.0) v = kuiRotateScreen(v, -orient);
+  v.x -= travel;
+  return v;
+}
+
+/**
+ * \`hover: stir\` \u2014 one vortex of the sample point about the pointer.
+ *
+ * A turn that dies away from the cursor, plus a push of the *sample point* outward, which is the
+ * field spiralling inward and is the whole difference between a rotating disc and a stir.
+ * \`rel / (length(rel) + eps)\` rather than \`normalize\`, so the push fades to nothing at the centre
+ * instead of kicking the one pixel under the cursor in whatever direction the epsilon points.
+ *
+ * Both halves run inside \`kuiAspectAxes()\`, for the same reason \`kuiHoverFalloff\` does: the
+ * falloff that drives this is already a circle on screen, so a vortex measured in raw UV would be
+ * a round pool turning an elliptical gesture \u2014 two different ideas of "the same distance from the
+ * cursor" in one effect.
+ */
+vec2 kuiStirPoint(vec2 pt, vec2 centre, float zoom, float fall) {
+  vec2 s = kuiAspectAxes();
+  vec2 rel = (pt - centre) * s;
+  vec2 turned = kuiRotate(rel, 1.6 * fall) + rel / (length(rel) + 1e-4) * (0.10 * zoom * fall);
+  return centre + turned / s;
+}
+
+/**
+ * The host image read as a stencil: 1 where the mark is, 0 where the page should show through.
+ *
+ * Three ways to ask, because a logo file answers the question differently depending on what it is:
+ *
+ * - \`0\` \u2014 no stencil. \`mode: gradient\`; \`u_image\` is not sampled at all.
+ * - \`1\` (\`mask: alpha\`) \u2014 the image's own alpha. An SVG or PNG mark on a transparent ground,
+ *   which is what a logo asset usually is. The texture is uploaded premultiplied, so \`a\` is the
+ *   coverage and multiplying all four channels by it stays premultiplied-correct.
+ * - \`2\`/\`3\` (\`mask: luma\` / \`luma-invert\`) \u2014 luminance, for a format with no alpha to read. A
+ *   JPEG has none, so a black-on-white mark under \`alpha\` would give an all-opaque stencil and
+ *   fill the whole rectangle with field. \`luma\` takes the *bright* pixels as the mark (white on
+ *   black); \`luma-invert\` takes the dark ones (black on white, which is the common logo file).
+ *   Both directions exist because guessing one silently produces a perfect negative of the mark \u2014
+ *   an image that looks deliberate and is exactly wrong.
+ *
+ * Luminance is taken from the premultiplied colour, so a transparent pixel is black. Under
+ * \`luma\` that reads as "not the mark", which is the sensible answer for a file that has alpha and
+ * was asked for a luma stencil anyway. Under \`luma-invert\` the same pixel reads as *solid* mark \u2014
+ * correct for the opaque JPEG the keyword exists for, and wrong for anything with a transparent
+ * surround, which should be using \`alpha\`.
+ */
+float glyphMask() {
+  if (u_maskMode == 0) return 1.0;
+  vec4 src = texture(u_image, v_uv);
+  if (u_maskMode == 1) return src.a;
+  float lum = dot(src.rgb, vec3(0.299, 0.587, 0.114));
+  return u_maskMode == 2 ? lum : 1.0 - lum;
+}
+
+/**
+ * The palette ramp, interpolated in linear-light rather than straight sRGB.
+ *
+ * \`mix()\` between two sRGB triples passes through a desaturated middle \u2014 the classic muddy
+ * midpoint of a naive gradient, worst exactly where two saturated brand colours meet. Squaring
+ * into approximately linear light, mixing there, and taking the square root back is a two-operation
+ * approximation of a gamma-2.0 space that removes almost all of it.
+ *
+ * \`smoothstep\` on the segment fraction, not a straight lerp, so the ramp has no visible crease at
+ * each stop \u2014 a crease that banding (\`u_bands\`) would otherwise land on and amplify.
+ */
+vec3 kuiPalette(float t) {
+  int n = max(u_colorCount, 2);
+  float x = clamp(t, 0.0, 1.0) * float(n - 1);
+  int i = int(floor(x));
+  int j = min(i + 1, n - 1);
+  float f = smoothstep(0.0, 1.0, x - float(i));
+  vec3 a = u_colors[i].rgb;
+  vec3 b = u_colors[j].rgb;
+  return sqrt(mix(a * a, b * b, f));
+}
+
+/** Rotate a colour about the grey axis \u2014 Rodrigues' formula, which needs no colour-space change. */
+vec3 kuiHueRotate(vec3 c, float angle) {
+  const vec3 axis = vec3(0.57735026);
+  float s = sin(angle);
+  float k = cos(angle);
+  return c * k + cross(axis, c) * s + axis * dot(axis, c) * (1.0 - k);
+}
+
+/** Per-pixel film grain. Quantised in time so it flickers at ~60 steps a second rather than per frame. */
+float kuiGrain(vec2 fragCoord, float t) {
+  uint h = kuiHash(uvec3(uvec2(fragCoord), uint(int(t * 60.0) + 0x10000)));
+  return float(h & 0xffffu) / 65535.0 - 0.5;
+}
+
+void main() {
+  // Centred and aspect-free: the field is authored in the element's own UV space, so the same
+  // parameters give the same picture whatever size the box is.
+  float zoom = max(u_scale, 0.05);
+  vec3 seed = vec3(u_seed * 137.31, u_seed * 71.17, u_seed * 29.73);
+  float t = u_time;
+  float pFactor = u_progress >= 0.0 ? u_progress : 1.0;
+
+  // Orientation and travel, as one rigid motion of the domain. \`angle\` names the field's axis;
+  // \`motion: swirl\` turns that axis over time; \`motion: drift\` slides along it. Both are *added
+  // to* the third-axis evolution below rather than replacing it, so a drifting field is still
+  // changing as it goes rather than being one frozen picture towed across the box.
+  float spin = u_motion == KUI_MOTION_SWIRL ? t * 0.2 : 0.0;
+  float orient = u_angle + spin;
+  // Multiplied by the zoom, so \`drift\` crosses the box at the same visual rate whatever \`scale\`
+  // is. Without it, zooming in would slow the travel down \u2014 one knob quietly moving two things,
+  // which is the bug kuiFbm's \`/norm\` divisor exists to avoid on the octave count.
+  float travel = u_motion == KUI_MOTION_DRIFT ? t * 0.12 * zoom : 0.0;
+
+  vec2 p = kuiFieldPoint(v_uv, zoom, orient, travel);
+  // One evaluation, shared by both gestures, and skipped entirely when there is no pointer
+  // response authored.
+  float hoverFall = u_hover != 0 ? kuiHoverFalloff() : 0.0;
+
+  // Domain warp: a second field displaces the sample point of the first. This is the whole
+  // difference between concentric fbm contours and something that reads as liquid.
+  //
+  // **This displacement is deliberately NOT aspect-corrected, and it is the one thing here that
+  // is not.** \`vec2(wx, wy)\` is isotropic in the field's own normalised space, which means it is
+  // anisotropic on screen \u2014 the same flaw \`kuiRotateScreen\` exists to fix for \`angle\`, \`motion\`
+  // and the \`stir\` vortex. It is left alone because \`warp\` is *shipped and in use*: multiplying
+  // it through \`kuiAspectAxes()\` would restyle every live page that authored one, which is a
+  // price a correctness argument does not get to charge. The rule the rest of this program follows
+  // and this line does not: **orientation and the pointer vortex are screen-true; the domain warp
+  // is field-true.** If you are here to "finish the job", that is a behaviour change to real
+  // sites and it needs the owner, not a tidy-up commit.
+  vec2 q = p;
+  if (u_warp > 0.0) {
+    float wf = u_frequency * 0.1;
+    float wx = kuiFbm(vec3(p * wf, t * 0.35) + seed, u_detail);
+    float wy = kuiFbm(vec3(p * wf + 5.2, t * 0.35 + 1.3) + seed, u_detail);
+    q += vec2(wx, wy) * u_warp;
+  }
+
+  // \`hover: stir\` \u2014 the cursor dragged through the colour, like stirring thick paint.
+  //
+  // Applied here, last, to the finished sample point: the gesture is dragging paint that is
+  // already there, not re-warping the field before it exists. It also means \`stir\` works at the
+  // library defaults, where \`warp\` is 0 and there is no domain warp to ride on.
+  //
+  // A vortex, which is one gesture and not two \u2014 see \`kuiStirPoint\`, which also explains why both
+  // halves of it are measured in the same screen-isotropic space as the falloff that drives them.
+  //
+  // On \`mode: logo\` this cannot touch the mark's edges: \`glyphMask()\` samples \`u_image\` at the
+  // undistorted \`v_uv\` and multiplies the finished colour, so stirring \`q\` swirls the fill and
+  // leaves the stencil exactly where it was.
+  if ((u_hover & KUI_HOVER_STIR) != 0) {
+    vec2 pm = kuiFieldPoint(u_mouse, zoom, orient, travel);
+    q = kuiStirPoint(q, pm, zoom, hoverFall);
+  }
+
+  // Audio and progress scale the field's *amplitude*, leaving its shape and rate alone \u2014 so a
+  // beat swells the contrast and a scroll at 0 leaves a flat single colour rather than a jump cut.
+  float field = kuiFbm(vec3(q, t * 0.25) + seed, u_detail);
+  field *= u_strength * pFactor * audioGain();
+  float v = clamp(field * 0.5 + 0.5, 0.0, 1.0);
+
+  // Iridescence wraps the ramp back on itself, so one palette reads as many sheens across the box.
+  float wrapped = u_iridescence > 0.0 ? fract(v * u_iridescence) : v;
+
+  // Posterise. Divided by bands-1 so the top step reaches the end of the ramp; a plain /bands
+  // would stop one step short and quietly desaturate the brightest colour.
+  if (u_bands > 0) {
+    float steps = float(u_bands);
+    wrapped = floor(wrapped * steps) / max(steps - 1.0, 1.0);
+  }
+
+  // Fringing offsets the *ramp position* per channel rather than re-sampling the field three
+  // times: three palette lookups are nearly free, three more fbm evaluations would triple the
+  // program's cost for a decorative edge.
+  vec3 color;
+  if (u_chromatic > 0.0) {
+    float d = u_chromatic * 0.04;
+    color = vec3(
+      kuiPalette(wrapped + d).r,
+      kuiPalette(wrapped).g,
+      kuiPalette(wrapped - d).b
+    );
+  } else {
+    color = kuiPalette(wrapped);
+  }
+
+  if (u_hue != 0.0) color = kuiHueRotate(color, u_hue);
+
+  // \`hover: light\` \u2014 a torch held over the surface.
+  //
+  // A multiply rather than a blend toward white. Multiplying preserves the hue and *raises* the
+  // saturation, so what appears under the pointer is the author's own colour becoming vivid;
+  // mixing toward white would wash the palette out at exactly the point the eye is on. The gain is
+  // 1.0 in the far field, which is what makes this a highlight rather than a restyling \u2014 a palette
+  // already at the top of the range has nowhere to go, and that is the honest behaviour of a torch.
+  if ((u_hover & KUI_HOVER_LIGHT) != 0) color *= 1.0 + 0.7 * hoverFall;
+
+  if (u_grain > 0.0) color += kuiGrain(gl_FragCoord.xy, t) * u_grain * 0.25;
+
+  // Opaque before masking, and premultiplied trivially because alpha is 1 \u2014 the element's own
+  // shape and its ancestors' opacity arrive through shapeMask(), the mark's shape through
+  // glyphMask(), and both multiply all four channels, which is the right operation on
+  // premultiplied colour and is what leaves the page visible around a logo.
+  float sm = shapeMask();
+  float gm = glyphMask();
+  vec4 px = vec4(clamp(color, 0.0, 1.0), 1.0) * u_tint * sm * gm;
+
+  // \`backdrop\` \u2014 the colour the field is composited *over*, inside the element's own shape.
+  //
+  // Premultiplied "over", because everything in this program already is. \`u_tint.a * gm\` is the
+  // field's coverage before the shape mask, so the backdrop is pulled through the same \`sm\` as the
+  // field rather than being masked twice \u2014 which would otherwise thin the backdrop along an
+  // antialiased rounded corner.
+  //
+  // What it is *for*: \`mode: logo\`'s plate. Outside the mark the coverage is zero and the backdrop
+  // is all there is, so a mark gets a solid ground instead of the page showing through. A bare
+  // \`gradient\` is opaque, so there this is a no-op by construction \u2014 visible only through a \`tint\`
+  // whose alpha is below 1. That is a property of an opaque field, not an oversight.
+  if (u_backdrop.a > 0.0) {
+    px += vec4(u_backdrop.rgb * u_backdrop.a, u_backdrop.a) * sm * (1.0 - u_tint.a * gm);
+  }
+  fragColor = px;
+}
+`;
+
+// src/advanced/base.ts
+function clamp(val, min, max) {
+  return Math.min(Math.max(val, min), max);
+}
+function styleOf(ledgers, el) {
+  if (!el || typeof el.hasAttribute !== "function") return null;
+  if (!el.style) return null;
+  return ledgers.style(el);
+}
+function createAdvancedLedgers(host) {
+  const claim = createStyleClaim();
+  return {
+    style: (el) => claim.style(el),
+    /*
+     * One element's teardown must not cost the rest of the subtree's.
+     *
+     * This loop is the *only* thing that ever gives a found element back — a `camera-layer`, a
+     * `scene-step` — because nothing else holds a claim on it. `createStyleLedger.restore()` ends
+     * in `removeProperty`/`setProperty`/`removeAttribute` calls straight against the author's
+     * element, and any of those can throw on a page that patched the CSSOM, froze a node, or runs a
+     * `MutationObserver` that throws in the same task. An unguarded loop therefore turned one such
+     * element into *every element after it in the claim set*, host included, keeping this library's
+     * inline transforms permanently: `openClaimBook.leave` drops the claim before the restore that
+     * threw, so those elements were never coming back — no later owner can be the last one out of
+     * an entry the failed sweep already deleted, and `createEffectInstance.destroy()` latches
+     * `isDestroyed` before `opts.destroy()`, so a second `destroy()` cannot retry either.
+     *
+     * The failures are collected rather than swallowed: `destroy()` throwing is contained upstream
+     * (`js-effect-preparer.ts` warns and moves on; the animator's `runQuietly` swallows), and an
+     * element the library genuinely could not hand back is worth saying so about. Aggregated so the
+     * first failure does not hide the fifth.
+     */
+    restore() {
+      const failures = [];
+      const release = (el) => {
+        try {
+          claim.release(el);
+        } catch (error) {
+          failures.push(error);
+        }
+      };
+      for (const el of claim.elements()) {
+        if (el !== host) release(el);
+      }
+      release(host);
+      if (failures.length > 0) {
+        throw new AggregateError(
+          failures,
+          `kuinetic: ${failures.length} element(s) could not be given back`
+        );
+      }
+    },
+    elements: () => claim.elements()
+  };
+}
+var effectNamePatterns = /* @__PURE__ */ new Map();
+function effectNamePattern(name) {
+  let pattern = effectNamePatterns.get(name);
+  if (!pattern) {
+    pattern = new RegExp(String.raw`(?:^|,)\s*${name}(?=[\s,]|$)`);
+    effectNamePatterns.set(name, pattern);
+  }
+  return pattern;
+}
+function declaresEffect(el, name) {
+  if (typeof el.getAttribute !== "function") return false;
+  const attr = el.getAttribute("data-kui");
+  return Boolean(attr) && effectNamePattern(name).test(attr);
+}
+function isNearestHostOfKind(host, el, hostEffect) {
+  let node = el?.parentElement;
+  while (node && node !== host) {
+    if (declaresEffect(node, hostEffect)) return false;
+    node = node.parentElement;
+  }
+  return true;
+}
+function ownedDescendants(host, hostEffect, descendantEffect) {
+  if (typeof host.querySelectorAll !== "function") return [];
+  const owned = [];
+  for (const el of host.querySelectorAll(`[data-kui*="${descendantEffect}"]`)) {
+    if (declaresEffect(el, descendantEffect) && isNearestHostOfKind(host, el, hostEffect)) owned.push(el);
+  }
+  return owned;
+}
+function lerp(start, end, progress) {
+  return start + (end - start) * progress;
+}
+function defaultRaf(win, fn) {
+  if (win && typeof win.requestAnimationFrame === "function") {
+    return win.requestAnimationFrame(fn);
+  }
+  return null;
+}
+function defaultCaf(win, id) {
+  if (win && typeof win.cancelAnimationFrame === "function" && id != null) {
+    win.cancelAnimationFrame(id);
+  }
+  return null;
+}
+function defaultSetTimer(fn, ms) {
+  if (typeof globalThis.setTimeout !== "function") return null;
+  return globalThis.setTimeout(fn, ms);
+}
+function defaultClearTimer(id) {
+  if (typeof globalThis.clearTimeout === "function" && id != null) {
+    globalThis.clearTimeout(id);
+  }
+}
+function resolveWindow(ctx, env) {
+  if (ctx?.win !== void 0) return ctx.win;
+  if (env.window !== void 0) return env.window;
+  return typeof window !== "undefined" ? window : null;
+}
+function resolveDocument(ctx, env) {
+  if (ctx?.doc !== void 0) return ctx.doc;
+  if (env.document !== void 0) return env.document;
+  return typeof document !== "undefined" ? document : null;
+}
+var defaultCanvasFactories = /* @__PURE__ */ new WeakMap();
+var noDocumentCanvas = () => null;
+function resolveCreateCanvas(c, env, doc) {
+  if (c?.createCanvas) return c.createCanvas;
+  if (env.createCanvas) return env.createCanvas;
+  if (!doc) return noDocumentCanvas;
+  const cached = defaultCanvasFactories.get(doc);
+  if (cached) return cached;
+  const factory = () => typeof doc.createElement === "function" ? doc.createElement("canvas") : null;
+  defaultCanvasFactories.set(doc, factory);
+  return factory;
+}
+function resolveRaf(c, env, win) {
+  if (c?.raf) return c.raf;
+  if (env.raf) return env.raf;
+  return (fn) => defaultRaf(win, fn);
+}
+function resolveCaf(c, env, win) {
+  if (c?.caf) return c.caf;
+  if (env.caf) return env.caf;
+  return (id) => defaultCaf(win, id);
+}
+function resolveTimers(c, env) {
+  if (c?.setTimer && c.clearTimer) return [c.setTimer, c.clearTimer];
+  if (env.setTimer && env.clearTimer) return [env.setTimer, env.clearTimer];
+  return [defaultSetTimer, defaultClearTimer];
+}
+function resolveEnv(ctx = null, env = {}) {
+  const c = ctx;
+  const win = resolveWindow(c, env);
+  const doc = resolveDocument(c, env);
+  const [setTimer, clearTimer] = resolveTimers(c, env);
+  return {
+    window: win,
+    document: doc,
+    createCanvas: resolveCreateCanvas(c, env, doc),
+    raf: resolveRaf(c, env, win),
+    caf: resolveCaf(c, env, win),
+    setTimer,
+    clearTimer
+  };
+}
+function isReducedMotion(ctx) {
+  if (!ctx) return false;
+  const rm = ctx.reducedMotion;
+  if (rm === true) return true;
+  if (typeof rm === "object" && rm && rm.enabled === true) return true;
+  return false;
+}
+function createEffectInstance(opts = {}) {
+  let isDestroyed = false;
+  let isFinished = false;
+  let resolveFinished;
+  const finishedPromise = new Promise((resolve) => {
+    resolveFinished = resolve;
+  });
+  return {
+    continuous: Boolean(opts.continuous),
+    activate() {
+      if (isDestroyed) return;
+      if (typeof opts.activate === "function") opts.activate();
+    },
+    cancel() {
+      if (isDestroyed) return;
+      if (typeof opts.cancel === "function") opts.cancel();
+      if (!isFinished && resolveFinished) {
+        isFinished = true;
+        resolveFinished();
+      }
+    },
+    finish() {
+      if (isDestroyed) return;
+      if (typeof opts.finish === "function") opts.finish();
+      if (!isFinished && resolveFinished) {
+        isFinished = true;
+        resolveFinished();
+      }
+    },
+    finished: opts.continuous ? Promise.resolve() : finishedPromise,
+    /*
+     * `finally`, because `destroy()` is the one call that cannot be made twice.
+     *
+     * `cancel()` and `finish()` throwing leave the instance alive, so a later call still settles
+     * `finished`. `destroy()` latches `isDestroyed` first — deliberately, so that a teardown which
+     * threw partway cannot be re-entered and a later `activate()` cannot resurrect a destroyed
+     * effect through ledgers that rejoin on write (`owned-styles.ts`). The cost of that latch was
+     * that a throwing `opts.destroy()` also skipped the resolve below, and every subsequent call
+     * returned at the guard: a non-continuous instance's `finished` then never settled at all, so
+     * anything awaiting it waited for the life of the page. The teardown still throws — the caller
+     * is told — but the promise it advertises is honoured on the way out.
+     */
+    destroy() {
+      if (isDestroyed) return;
+      isDestroyed = true;
+      try {
+        if (typeof opts.destroy === "function") opts.destroy();
+      } finally {
+        if (!isFinished && resolveFinished) {
+          isFinished = true;
+          resolveFinished();
+        }
+      }
+    }
+  };
+}
+function createInertInstance(destroy) {
+  let isDestroyed = false;
+  return {
+    continuous: false,
+    activate() {
+    },
+    cancel() {
+    },
+    finish() {
+    },
+    finished: Promise.resolve(),
+    destroy() {
+      if (isDestroyed) return;
+      isDestroyed = true;
+      if (typeof destroy === "function") destroy();
+    }
+  };
+}
+function toList(val) {
+  return Array.isArray(val) ? val : [val];
+}
+function hasRegistrarShape(value) {
+  if (!value || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.registerPrimitives === "function" && typeof v.registerPresets === "function";
+}
+function asRegistry(target) {
+  if (!target || typeof target !== "object") return void 0;
+  if (hasRegistrarShape(target)) return target;
+  const host = target;
+  if (hasRegistrarShape(host.registry)) return host.registry;
+  return void 0;
+}
+function registerInto(target, primitives, presets, name = "module") {
+  const reg = asRegistry(target);
+  if (!reg) {
+    throw new Error(`kuinetic: register${name} requires a Registry or Animator instance`);
+  }
+  reg.registerPrimitives(toList(primitives));
+  reg.registerPresets(toList(presets));
+  return target;
+}
+
+// src/advanced/gl-utils.ts
+function compileShader(gl, type, source) {
+  const shader = gl.createShader(type);
+  if (!shader) return null;
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    gl.deleteShader(shader);
+    return null;
+  }
+  return shader;
+}
+function createProgram(gl, vsSource, fsSource) {
+  const vs = compileShader(gl, gl.VERTEX_SHADER, vsSource);
+  const fs = compileShader(gl, gl.FRAGMENT_SHADER, fsSource);
+  if (!vs || !fs) {
+    if (vs) gl.deleteShader(vs);
+    if (fs) gl.deleteShader(fs);
+    return null;
+  }
+  const program = gl.createProgram();
+  if (!program) {
+    gl.deleteShader(vs);
+    gl.deleteShader(fs);
+    return null;
+  }
+  gl.attachShader(program, vs);
+  gl.attachShader(program, fs);
+  gl.linkProgram(program);
+  gl.deleteShader(vs);
+  gl.deleteShader(fs);
+  if (typeof gl.getProgramParameter === "function" && !gl.getProgramParameter(program, gl.LINK_STATUS)) {
+    gl.deleteProgram(program);
+    return null;
+  }
+  return program;
+}
+function extractLocations(gl, program) {
+  if (!program) return null;
+  return {
+    program,
+    a_position: gl.getAttribLocation(program, "a_position"),
+    u_image: gl.getUniformLocation(program, "u_image"),
+    u_image_to: gl.getUniformLocation(program, "u_image_to"),
+    u_uvOrigin: gl.getUniformLocation(program, "u_uvOrigin"),
+    u_uvScale: gl.getUniformLocation(program, "u_uvScale"),
+    u_maskBox: gl.getUniformLocation(program, "u_maskBox"),
+    u_maskRx: gl.getUniformLocation(program, "u_maskRx"),
+    u_maskRy: gl.getUniformLocation(program, "u_maskRy"),
+    u_maskAlpha: gl.getUniformLocation(program, "u_maskAlpha"),
+    u_time: gl.getUniformLocation(program, "u_time"),
+    u_strength: gl.getUniformLocation(program, "u_strength"),
+    u_frequency: gl.getUniformLocation(program, "u_frequency"),
+    u_chromatic: gl.getUniformLocation(program, "u_chromatic"),
+    u_iridescence: gl.getUniformLocation(program, "u_iridescence"),
+    u_mouse: gl.getUniformLocation(program, "u_mouse"),
+    u_tint: gl.getUniformLocation(program, "u_tint"),
+    u_color1: gl.getUniformLocation(program, "u_color1"),
+    u_color2: gl.getUniformLocation(program, "u_color2"),
+    u_duotone: gl.getUniformLocation(program, "u_duotone"),
+    u_blend: gl.getUniformLocation(program, "u_blend"),
+    u_progress: gl.getUniformLocation(program, "u_progress"),
+    u_seed: gl.getUniformLocation(program, "u_seed"),
+    u_scale: gl.getUniformLocation(program, "u_scale"),
+    u_warp: gl.getUniformLocation(program, "u_warp"),
+    u_grain: gl.getUniformLocation(program, "u_grain"),
+    u_hue: gl.getUniformLocation(program, "u_hue"),
+    u_detail: gl.getUniformLocation(program, "u_detail"),
+    u_bands: gl.getUniformLocation(program, "u_bands"),
+    u_colorCount: gl.getUniformLocation(program, "u_colorCount"),
+    u_colors: gl.getUniformLocation(program, "u_colors"),
+    // Which stencil the generative program applies: 0 none (`gradient`), 1 alpha, 2 luma,
+    // 3 inverted luma. See `glyphMask()` in `glsl.ts`.
+    u_maskMode: gl.getUniformLocation(program, "u_maskMode"),
+    u_hover: gl.getUniformLocation(program, "u_hover"),
+    u_backdrop: gl.getUniformLocation(program, "u_backdrop"),
+    u_angle: gl.getUniformLocation(program, "u_angle"),
+    u_motion: gl.getUniformLocation(program, "u_motion")
+  };
+}
+function disposeGLResources(gl, quadBuffer, programs) {
+  if (!gl) return;
+  if (quadBuffer && gl.deleteBuffer) gl.deleteBuffer(quadBuffer);
+  for (const info of Object.values(programs)) {
+    const prog = info && typeof info === "object" && "program" in info ? info.program : info;
+    if (prog && gl.deleteProgram) gl.deleteProgram(prog);
+  }
+}
+function sourceExtent(source) {
+  const s = source;
+  const w = Number(s.naturalWidth ?? s.videoWidth ?? s.width ?? 0);
+  const h = Number(s.naturalHeight ?? s.videoHeight ?? s.height ?? 0);
+  return [Number.isFinite(w) ? w : 0, Number.isFinite(h) ? h : 0];
+}
+function exceedsTextureLimit(gl, source) {
+  if (typeof gl.getParameter !== "function") return false;
+  const limit = Number(gl.getParameter(gl.MAX_TEXTURE_SIZE));
+  if (!Number.isFinite(limit) || limit <= 0) return false;
+  const [w, h] = sourceExtent(source);
+  return w > limit || h > limit;
+}
+function drainGLErrors(gl) {
+  if (typeof gl.getError !== "function") return;
+  for (let i = 0; i < 8; i += 1) {
+    if (Number(gl.getError()) === 0) return;
+  }
+}
+function glRaisedError(gl) {
+  if (typeof gl.getError !== "function") return false;
+  const code = gl.getError();
+  return typeof code === "number" && code !== 0;
+}
+function createGLTexture(gl, source) {
+  if (exceedsTextureLimit(gl, source)) return null;
+  const tex = gl.createTexture();
+  if (!tex) return null;
+  drainGLErrors(gl);
+  try {
+    gl.bindTexture(gl.TEXTURE_2D, tex);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    if (typeof gl.pixelStorei === "function") gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, 1);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
+    if (glRaisedError(gl)) {
+      if (gl.deleteTexture) gl.deleteTexture(tex);
+      return null;
+    }
+    return tex;
+  } catch {
+    if (gl.deleteTexture) gl.deleteTexture(tex);
+    return null;
+  }
+}
+
+// src/advanced/audio.ts
+var AUDIO_CHANNELS = [
+  "--kui-audio-bass",
+  "--kui-audio-mid",
+  "--kui-audio-treble",
+  "--kui-audio-level",
+  "--kui-audio"
+];
+var AUDIO_BAND_PROPERTIES = {
+  bass: "--kui-audio-bass",
+  mid: "--kui-audio-mid",
+  treble: "--kui-audio-treble",
+  level: "--kui-audio-level"
+};
+var AUDIO_BANDS = Object.keys(AUDIO_BAND_PROPERTIES);
+function parseBandValue(raw) {
+  if (!raw) return null;
+  const val = parseFloat(raw);
+  return Number.isFinite(val) ? clamp(val, 0, 1) : null;
+}
+function parseAudioBand(raw) {
+  if (!raw) return null;
+  const name = raw.trim();
+  return Object.hasOwn(AUDIO_BAND_PROPERTIES, name) ? name : null;
+}
+function readAudioBand(el, band) {
+  const prop = AUDIO_BAND_PROPERTIES[band];
+  const fromInline = parseBandValue(el.style?.getPropertyValue?.(prop));
+  if (fromInline !== null) return fromInline;
+  const view = el.ownerDocument?.defaultView;
+  return parseBandValue(view?.getComputedStyle?.(el).getPropertyValue(prop)) ?? 0;
+}
+function computeFrequencyBands(data, sampleRate) {
+  const binCount = data.length;
+  if (binCount === 0) return { bass: 0, mid: 0, treble: 0, level: 0 };
+  const nyquist = sampleRate > 0 ? sampleRate / 2 : 22050;
+  const hzPerBin = nyquist / binCount;
+  const getAverage = (minHz, maxHz) => {
+    const startBin = Math.max(0, Math.floor(minHz / hzPerBin));
+    const endBin = Math.min(binCount, Math.max(startBin + 1, Math.ceil(maxHz / hzPerBin)));
+    let sum = 0;
+    let count = 0;
+    for (let i = startBin; i < endBin; i++) {
+      sum += data[i];
+      count++;
+    }
+    return count > 0 ? sum / (count * 255) : 0;
+  };
+  let totalSum = 0;
+  for (let i = 0; i < binCount; i++) totalSum += data[i];
+  const level = totalSum / (binCount * 255);
+  return {
+    bass: clamp(getAverage(20, 250), 0, 1),
+    mid: clamp(getAverage(250, 4e3), 0, 1),
+    treble: clamp(getAverage(4e3, 16e3), 0, 1),
+    level: clamp(level, 0, 1)
+  };
+}
+var DEFAULT_MEDIA_SELECTOR = "audio, video";
+function isMediaElement(el, win) {
+  const injected = win?.HTMLMediaElement;
+  const ctor = injected ?? (typeof HTMLMediaElement !== "undefined" ? HTMLMediaElement : null);
+  return ctor ? el instanceof ctor : false;
+}
+function findMediaElement(el, authored, win, doc) {
+  if (isMediaElement(el, win)) return el;
+  const local = el.querySelector?.(authored ?? DEFAULT_MEDIA_SELECTOR);
+  if (local) return local;
+  if (!authored) return null;
+  return doc?.querySelector?.(authored) || null;
+}
+function safeDisconnect(node) {
+  if (!node || typeof node.disconnect !== "function") return;
+  try {
+    node.disconnect();
+  } catch {
+    return;
+  }
+}
+function safeDisconnectFrom(node, destination) {
+  if (!node || typeof node.disconnect !== "function" || !destination) return;
+  try {
+    node.disconnect(destination);
+  } catch {
+    return;
+  }
+}
+var FFT_SIZES = [32, 64, 128, 256, 512, 1024, 2048];
+function snapFftSize(requested) {
+  let best = FFT_SIZES[0];
+  for (const size of FFT_SIZES) {
+    if (Math.abs(size - requested) < Math.abs(best - requested)) best = size;
+  }
+  return best;
+}
+var GESTURE_EVENTS = ["pointerdown", "keydown", "touchend"];
+var sharedGraphs = /* @__PURE__ */ new WeakMap();
+function createMutedSink(ctx) {
+  if (typeof ctx.createGain !== "function") return null;
+  try {
+    const gain = ctx.createGain();
+    if (gain.gain) gain.gain.value = 0;
+    gain.connect(ctx.destination);
+    return gain;
+  } catch {
+    return null;
+  }
+}
+function acquireSharedGraph(win) {
+  const existing = sharedGraphs.get(win);
+  if (existing) {
+    existing.consumers++;
+    return existing;
+  }
+  const AudioCtxCtor = win.AudioContext || win.webkitAudioContext;
+  if (!AudioCtxCtor) return null;
+  try {
+    const ctx = new AudioCtxCtor();
+    const graph = {
+      ctx,
+      sources: /* @__PURE__ */ new WeakMap(),
+      sink: createMutedSink(ctx),
+      consumers: 1,
+      ownsMediaOutput: false
+    };
+    sharedGraphs.set(win, graph);
+    return graph;
+  } catch {
+    return null;
+  }
+}
+function releaseSharedGraph(win, graph) {
+  graph.consumers--;
+  if (graph.consumers > 0 || graph.ownsMediaOutput) return;
+  sharedGraphs.delete(win);
+  const closing = graph.ctx.close?.();
+  if (closing) closing.catch(() => void 0);
+}
+function mediaSourceFor(graph, mediaEl) {
+  const existing = graph.sources.get(mediaEl);
+  if (existing) return existing;
+  if (typeof graph.ctx.createMediaElementSource !== "function") return null;
+  try {
+    const source = graph.ctx.createMediaElementSource(mediaEl);
+    source.connect(graph.ctx.destination);
+    graph.sources.set(mediaEl, source);
+    graph.ownsMediaOutput = true;
+    return source;
+  } catch {
+    return null;
+  }
+}
+var AudioSourceController = class {
+  element;
+  options;
+  env;
+  window;
+  document;
+  raf;
+  caf;
+  audioCtx = null;
+  analyser = null;
+  sourceNode = null;
+  stream = null;
+  freqData = null;
+  rafId = null;
+  isActive = false;
+  /** The window-wide graph this instance is currently counted against. */
+  graph = null;
+  /**
+   * Whether `sourceNode` belongs to the shared graph rather than to this instance.
+   *
+   * True for `source: media` — the node feeds the page's speakers as well as this analyser, so
+   * teardown may only cut its edge to *this* analyser. False for `source: mic`, where the node and
+   * its stream are this instance's alone and must be released in full.
+   */
+  sourceIsShared = false;
+  /**
+   * The author's inline custom properties, and what this module replaced them with.
+   *
+   * Not a snapshot taken here: the ledger for `element` is opened at the first write in
+   * `updateFrame`, so what it restores is whatever the author had at that instant. The field it
+   * replaced captured all five properties in this constructor and restored them on destroy, which
+   * meant an author who wrote `--kui-audio-bass` any time after `prepare` had that write silently
+   * reverted to a value from before their own.
+   *
+   * Shared with every other controller writing to this element — see `createAdvancedLedgers`. Two
+   * `audio-source` effects on one element (`audio-reactive` plus `audio-mic`, say) would otherwise
+   * open a ledger each, and the second would capture the first's `0.000` as the author's value.
+   */
+  ledgers;
+  /**
+   * Which microphone request is the live one.
+   *
+   * `getUserMedia` cannot be cancelled — the permission prompt belongs to the browser, and the
+   * promise settles whenever the visitor answers it. Every `stop()` bumps this, so a request the
+   * visitor grants *after* the effect was cancelled resolves into a handler that no longer
+   * recognises its own generation and stops the tracks instead of connecting them. Without it,
+   * cancelling while the prompt is open and then granting leaves the microphone recording until
+   * the element is eventually destroyed.
+   */
+  micRequestToken = 0;
+  /** Detaches the one-shot gesture listeners armed by {@link armGestureResume}. */
+  releaseGestureResume = null;
+  constructor(element, options = {}, env = {}) {
+    this.element = element;
+    this.options = options;
+    this.env = env;
+    const resolved = resolveEnv(null, env);
+    this.window = resolved.window;
+    this.document = resolved.document;
+    this.raf = resolved.raf;
+    this.caf = resolved.caf;
+    this.ledgers = createAdvancedLedgers(element);
+  }
+  connectMicSource(graph, analyser, win) {
+    const nav = win?.navigator;
+    if (!nav?.mediaDevices?.getUserMedia) return;
+    const token = ++this.micRequestToken;
+    nav.mediaDevices.getUserMedia({ audio: true }).then((stream) => {
+      if (token !== this.micRequestToken || this.analyser !== analyser) {
+        for (const track of stream.getTracks()) track.stop();
+        return;
+      }
+      this.stream = stream;
+      this.sourceNode = graph.ctx.createMediaStreamSource(stream);
+      this.sourceIsShared = false;
+      this.sourceNode.connect(analyser);
+      if (this.resumeContext()) this.startLoopIfReady();
+    }).catch(() => void 0);
+  }
+  connectMediaSource(graph, analyser, win) {
+    const doc = this.document;
+    try {
+      const mediaEl = findMediaElement(this.element, this.options.target || null, win, doc);
+      if (!mediaEl) return;
+      const source = mediaSourceFor(graph, mediaEl);
+      if (!source) return;
+      source.connect(analyser);
+      this.sourceNode = source;
+      this.sourceIsShared = true;
+    } catch {
+      return;
+    }
+  }
+  /**
+   * This instance's analyser, already on a live path to the destination.
+   *
+   * @returns The analyser, or `null` when the context refused to build one.
+   */
+  buildAnalyser(graph) {
+    try {
+      const analyser = graph.ctx.createAnalyser();
+      analyser.fftSize = snapFftSize(this.options.fftSize || 256);
+      analyser.smoothingTimeConstant = this.options.smoothing ?? 0.8;
+      if (graph.sink) analyser.connect(graph.sink);
+      return analyser;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Join the window's audio graph and give this instance an analyser on it.
+   *
+   * `this.analyser`, not `this.audioCtx`, is the "already initialised" test, and nothing is
+   * recorded on `this` until the analyser exists. Assigning the context first is what left a
+   * half-built instance behind — an open context, no analyser, and a loop writing zeros — whenever
+   * `createAnalyser` or `fftSize` threw.
+   */
+  initAudio() {
+    if (this.analyser) return true;
+    const win = this.window;
+    if (!win) return false;
+    const graph = acquireSharedGraph(win);
+    if (!graph) return false;
+    const analyser = this.buildAnalyser(graph);
+    if (!analyser) {
+      releaseSharedGraph(win, graph);
+      return false;
+    }
+    this.graph = graph;
+    this.audioCtx = graph.ctx;
+    this.analyser = analyser;
+    this.freqData = new Uint8Array(new ArrayBuffer(analyser.frequencyBinCount));
+    if (this.options.source === "mic") this.connectMicSource(graph, analyser, win);
+    else this.connectMediaSource(graph, analyser, win);
+    return true;
+  }
+  /**
+   * Go live — but only run a frame loop once there is something for it to read.
+   *
+   * The loop used to start unconditionally, and both ways that can be wrong were reachable:
+   *
+   * - **Initialisation failed.** No Web Audio, or an `AudioContext` the browser refused to build.
+   *   `initAudio()` is only ever called from here and here early-returns on `isActive`, so there is
+   *   no retry path at all — the loop sampled nothing, wrote the same `0.000` forever and could
+   *   never recover.
+   * - **The context is suspended.** `defaultActivation` is `'load'`, so this normally runs before
+   *   the visitor has touched anything and the context starts suspended. The gesture retry below
+   *   is the fix for *that*, but the loop does not have to run while it waits: a suspended context
+   *   fills zeros, and {@link GESTURE_EVENTS} is `pointerdown`/`keydown`/`touchend` — a visitor who
+   *   only ever scrolls with a wheel fires none of them, so "while it waits" was the rest of the
+   *   session at 60fps.
+   *
+   * - **There is nothing to read.** `initAudio()` answers `true` as soon as the analyser exists,
+   *   and the analyser can exist with nothing connected to it: `audio-source target:#missing`, or a
+   *   page with no media under the element, leaves `connectMediaSource` with no node to attach;
+   *   `audio-mic` leaves `connectMicSource` waiting on a permission prompt the visitor may close,
+   *   refuse, or never answer. A loop over a disconnected analyser is the first case again — the
+   *   same `0.000` at 60fps, for the life of the page, with nothing coming to change it.
+   *
+   * One frame of silence covers all three, and it is all any of them needs: nothing is going to
+   * change these five values until a resume or a stream lands, and writing them once still says
+   * "there is a driver on this element and it is silent" to a consumer that would otherwise inherit
+   * an ancestor's live band. The loop is then started by whichever arrives last — the `resume()`
+   * that succeeds, or the microphone the visitor grants — see {@link startLoopIfReady}.
+   */
+  start() {
+    if (this.isActive) return;
+    this.isActive = true;
+    if (!this.initAudio() || !this.resumeContext() || !this.sourceNode) {
+      this.updateFrame();
+      return;
+    }
+    this.startLoop();
+  }
+  /**
+   * Wake a context the browser suspended for autoplay policy.
+   *
+   * `defaultActivation` is `'load'`, so the context is very often constructed before the visitor
+   * has touched anything, and a context built outside a user gesture starts `suspended`. A bare
+   * `resume()` there is rejected or left pending — WebKit is strict about it, and iOS is this
+   * repo's main audience — after which `getByteFrequencyData` fills zeros and all five properties
+   * sit at `0.000` for the rest of the session. `on:click` only worked by luck, because it happens
+   * to run inside a gesture.
+   *
+   * So: try immediately, and arm a one-shot retry on the visitor's first gesture. The `on:click`
+   * path still succeeds on the first attempt and the listeners are never needed.
+   *
+   * @returns `true` when the context is already live and {@link start} may run its loop now,
+   *   `false` when a resume has been arranged and the loop is that resume's job to start.
+   */
+  resumeContext() {
+    const ctx = this.audioCtx;
+    if (!ctx || ctx.state !== "suspended") return true;
+    ctx.resume().then(() => this.startLoopIfReady()).catch(() => void 0);
+    this.armGestureResume();
+    return false;
+  }
+  /**
+   * Start the loop, unless the effect was torn down while the context was still waking up — or
+   * there is still nothing connected for it to read.
+   *
+   * `resume()` settles whenever the browser gets to it, which can be long after a `cancel()` — the
+   * same race {@link micRequestToken} closes for `getUserMedia`, and with the same consequence if
+   * it is left open: a resume landing after teardown would start a frame loop on a stopped
+   * instance, and nothing would ever come back to stop it.
+   *
+   * The source check is the other half of the gate {@link start} applies: a resume that lands
+   * before the microphone is granted, or on an element with no media to bind, has nothing to start
+   * a loop over. When the stream does arrive, `connectMicSource` comes back through here.
+   */
+  startLoopIfReady() {
+    if (this.isActive && this.sourceNode) this.startLoop();
+  }
+  armGestureResume() {
+    const win = this.window;
+    if (this.releaseGestureResume || !win?.addEventListener || !win.removeEventListener) return;
+    const onGesture = () => {
+      this.releaseGestureResume?.();
+      this.audioCtx?.resume().then(() => this.startLoopIfReady()).catch(() => void 0);
+    };
+    this.releaseGestureResume = () => {
+      this.releaseGestureResume = null;
+      for (const type of GESTURE_EVENTS) win.removeEventListener?.(type, onGesture);
+    };
+    for (const type of GESTURE_EVENTS) win.addEventListener(type, onGesture, { passive: true });
+  }
+  startLoop() {
+    if (this.rafId) return;
+    const tick = () => {
+      this.updateFrame();
+      if (this.isActive) {
+        this.rafId = this.raf(tick);
+      } else {
+        this.rafId = null;
+      }
+    };
+    this.rafId = this.raf(tick);
+  }
+  updateFrame() {
+    const style = styleOf(this.ledgers, this.element);
+    if (!style) return;
+    let bands = { bass: 0, mid: 0, treble: 0, level: 0 };
+    if (this.analyser && this.freqData && this.audioCtx) {
+      this.analyser.getByteFrequencyData(this.freqData);
+      bands = computeFrequencyBands(this.freqData, this.audioCtx.sampleRate);
+    }
+    const level = bands.level.toFixed(3);
+    this.writeChannel(style, "--kui-audio-bass", bands.bass.toFixed(3));
+    this.writeChannel(style, "--kui-audio-mid", bands.mid.toFixed(3));
+    this.writeChannel(style, "--kui-audio-treble", bands.treble.toFixed(3));
+    this.writeChannel(style, "--kui-audio-level", level);
+    this.writeChannel(style, "--kui-audio", level);
+  }
+  /**
+   * One channel, written only when it would actually change anything.
+   *
+   * These are unregistered custom properties, so they inherit: five unconditional `setProperty`
+   * calls per frame per instance dirty the whole subtree's style 60 times a second even on a page
+   * whose audio is silent or whose context never resumed, where all five values are the identical
+   * `0.000`.
+   *
+   * The comparison reads the live inline value rather than a remembered one on purpose. A cache
+   * would go stale the moment the author wrote the property themselves — this module would agree
+   * with its own record, skip the write, and look dead. Reading the CSSOM's own map is a lookup,
+   * not a style resolution, so it costs nothing a `setProperty` would not already cost.
+   *
+   * `claim()` first and unconditionally, because the very first frame can legitimately skip its
+   * write (the author happened to have written the same string), and the ledger still has to have
+   * captured what was there to restore it.
+   *
+   * @complexity O(1).
+   */
+  writeChannel(style, property, value) {
+    style.claim(property);
+    if (this.element.style.getPropertyValue(property) === value) return;
+    style.set(property, value);
+  }
+  /**
+   * Give back everything this instance owns: the frame loop, its analyser, the microphone.
+   *
+   * This is what `cancel()` and `finish()` reach, and it is deliberately a full release of the
+   * *instance's* half of the graph. A cancelled `audio-mic` that only stopped its loop left the
+   * stream connected and the recording indicator lit until the element was eventually destroyed —
+   * the visitor stopped the effect and the microphone stayed on.
+   *
+   * What it deliberately does **not** do is touch the page's own audio or the author's styles.
+   * The shared media source keeps its edge to the destination (see {@link SharedAudioGraph}), and
+   * the ledger is left as it is because `EffectInstance.cancel` means "stop where it is, leaving
+   * the element mid-effect" — unwinding the five custom properties here would snap every rule
+   * reading `var(--kui-audio-bass, 0)` back to its fallback on a pause, which is not what the
+   * other five modules in this directory do. `destroy()` is where the styles go back.
+   *
+   * Idempotent, and safe on a controller that was never started — every step below no-ops on an
+   * empty graph. It runs unguarded for that reason: the old `isActive` early-return meant a
+   * controller cancelled twice, or destroyed without ever activating, skipped the parts that had
+   * nothing to do with the loop.
+   */
+  stop() {
+    this.isActive = false;
+    this.micRequestToken++;
+    if (this.rafId) {
+      this.caf(this.rafId);
+      this.rafId = null;
+    }
+    this.releaseGestureResume?.();
+    this.disconnectAudioNodes();
+  }
+  disconnectAudioNodes() {
+    if (this.stream) {
+      for (const track of this.stream.getTracks()) track.stop();
+      this.stream = null;
+    }
+    const analyser = this.analyser;
+    if (this.sourceIsShared) safeDisconnectFrom(this.sourceNode, analyser);
+    else safeDisconnect(this.sourceNode);
+    this.sourceNode = null;
+    this.sourceIsShared = false;
+    safeDisconnect(analyser);
+    this.analyser = null;
+    this.freqData = null;
+    this.audioCtx = null;
+    if (this.graph) {
+      releaseSharedGraph(this.window, this.graph);
+      this.graph = null;
+    }
+  }
+  /**
+   * Everything `stop()` gives back, plus the author's inline styles.
+   *
+   * `try`/`finally` because the restore must not be hostage to the graph teardown: the animator
+   * swallows a throwing `instance.destroy()` (`runQuietly`), and an element this module reached on
+   * its own — a `camera-layer`, a `scene-step` — is in no ledger the animator will ever restore.
+   * A single throw on the way out would otherwise leave the library's values on it permanently.
+   */
+  destroy() {
+    try {
+      this.stop();
+    } finally {
+      this.ledgers.restore();
+    }
+  }
+};
+function prepareAudioSource(el, params, ctx) {
+  if (isReducedMotion(ctx)) return createInertInstance();
+  const resolvedEnv = resolveEnv(ctx);
+  const rawSource = params.text ? params.text("source", "media") : "media";
+  const source = rawSource === "mic" ? "mic" : "media";
+  const target = params.text ? params.text("target", "") : "";
+  const smoothing = clamp(params.num ? params.num("smoothing", 0.8) : 0.8, 0, 0.99);
+  const fftSize = snapFftSize(clamp(params.num ? params.num("fft", 256) : 256, 32, 2048));
+  const controller = new AudioSourceController(
+    el,
+    { source, target, smoothing, fftSize },
+    resolvedEnv
+  );
+  return createEffectInstance({
+    continuous: true,
+    activate() {
+      controller.start();
+    },
+    cancel() {
+      controller.stop();
+    },
+    finish() {
+      controller.stop();
+    },
+    destroy() {
+      controller.destroy();
+    }
+  });
+}
+var AUDIO_PARAMETERS = {
+  source: { type: "keyword", default: "media", keywords: ["media", "mic"], cssProperty: "--kui-audio-source" },
+  /**
+   * Which media element to analyse — the library's one spelling for "this effect names another
+   * element", declared exactly as every other primitive that owns the key declares it — see
+   * `compile.ts`'s `liftTarget` for the current set — down to the shared `--kui-target`.
+   *
+   * It was `media:`, which was both a second word for `target:`'s job and a live footgun:
+   * `compile.ts`'s `liftTarget` only leaves `target:` in a primitive's own parameters when that
+   * primitive declares it, and otherwise *relocates the whole effect* onto the elements the
+   * selector matched. So `audio-source target:#track` used to move the analyser onto the `<audio>`
+   * element itself — which happens to work, silently writing the five custom properties on the
+   * wrong element. Declaring the key here claims it and closes that.
+   *
+   * No `scope: SCOPE_PARAM` alongside it, unlike its peers: this resolves its own two-step search
+   * (`findMediaElement` — the host's own subtree first, the document only for an authored
+   * selector), and importing core's shared declaration would be a value import from `src/effects`
+   * into a tier whose bundle weight is measured (see `base.ts`'s `asRegistry`).
+   */
+  target: { type: "text", default: "", cssProperty: "--kui-target" },
+  smoothing: { type: "number", default: "0.8", minimum: 0, maximum: 0.99, cssProperty: "--kui-audio-smoothing" },
+  fft: { type: "number", default: "256", minimum: 32, maximum: 2048, cssProperty: "--kui-audio-fft" }
+};
+var AUDIO_PRIMITIVES = [
+  {
+    id: "audio-source",
+    renderer: "javascript",
+    // The five custom properties `updateFrame` writes, named exactly. `[]` said this primitive
+    // touched nothing, so the registry's conflict detection could not see a second source writing
+    // the same variables and let the two race, last frame wins.
+    channels: [...AUDIO_CHANNELS],
+    parameters: AUDIO_PARAMETERS,
+    supportedTimelines: ["time"],
+    // `manual` alongside the existing three (same additive shape as `interaction-proximity.ts`
+    // and `interaction.ts`): `on:load` (the default) leaves `resumeContext`'s one-shot
+    // page-gesture listener as the fallback, but an author who wants the AudioContext to wake on
+    // one specific, deliberate gesture — a "start visualiser" button, not the visitor's next
+    // incidental tap anywhere on the page — can now write `on:manual` and call `.play()` from
+    // that button's own handler, which still lands inside the same user gesture the browser
+    // requires.
+    supportedActivations: ["load", "enter", "click", "manual"],
+    defaultActivation: "load",
+    perfClass: "continuous",
+    reducedMotion: "disable",
+    prepare: prepareAudioSource
+  }
+];
+var AUDIO_PRESETS = [
+  { name: "audio-source", primitive: "audio-source" },
+  { name: "audio-reactive", primitive: "audio-source" },
+  { name: "audio-mic", primitive: "audio-source", params: { source: "mic" } }
+];
+function registerAudio(target) {
+  return registerInto(target, AUDIO_PRIMITIVES[0], AUDIO_PRESETS, "AudioSource");
+}
+
+// src/advanced/shaders.ts
+function parseHex(raw) {
+  if (!/^[0-9a-fA-F]{3,8}$/.test(raw)) return null;
+  if (raw.length === 3 || raw.length === 4) {
+    const a = raw.length === 4 ? parseInt(raw[3] + raw[3], 16) / 255 : 1;
+    return [parseInt(raw[0] + raw[0], 16) / 255, parseInt(raw[1] + raw[1], 16) / 255, parseInt(raw[2] + raw[2], 16) / 255, a];
+  }
+  if (raw.length === 6 || raw.length === 8) {
+    const a = raw.length === 8 ? parseInt(raw.slice(6, 8), 16) / 255 : 1;
+    return [parseInt(raw.slice(0, 2), 16) / 255, parseInt(raw.slice(2, 4), 16) / 255, parseInt(raw.slice(4, 6), 16) / 255, a];
+  }
+  return null;
+}
+var RGBA_REGEX = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)(?:\s*,\s*([\d.]+))?\s*\)$/i;
+function parseRgbFunctional(val) {
+  const match = RGBA_REGEX.exec(val);
+  if (!match || !match[1] || !match[2] || !match[3]) return null;
+  const r = Math.min(255, Math.max(0, parseInt(match[1], 10))) / 255;
+  const g = Math.min(255, Math.max(0, parseInt(match[2], 10))) / 255;
+  const b = Math.min(255, Math.max(0, parseInt(match[3], 10))) / 255;
+  const a = match[4] !== void 0 ? Math.min(1, Math.max(0, parseFloat(match[4]))) : 1;
+  return [r, g, b, a];
+}
+var NAMED_COLORS = {
+  transparent: [0, 0, 0, 0],
+  black: [0, 0, 0, 1],
+  white: [1, 1, 1, 1],
+  red: [1, 0, 0, 1],
+  green: [0, 0.5, 0, 1],
+  blue: [0, 0, 1, 1],
+  yellow: [1, 1, 0, 1],
+  cyan: [0, 1, 1, 1],
+  magenta: [1, 0, 1, 1],
+  gray: [0.5, 0.5, 0.5, 1],
+  grey: [0.5, 0.5, 0.5, 1],
+  orange: [1, 0.647, 0, 1],
+  purple: [0.5, 0, 0.5, 1]
+};
+var colorContexts = /* @__PURE__ */ new WeakMap();
+function colorContextFor(createCanvas) {
+  const cached = colorContexts.get(createCanvas);
+  if (cached !== void 0) return cached;
+  let ctx = null;
+  try {
+    const canvas = createCanvas();
+    if (canvas) {
+      canvas.width = 1;
+      canvas.height = 1;
+      ctx = canvas.getContext?.("2d", { willReadFrequently: true }) ?? null;
+    }
+  } catch {
+    ctx = null;
+  }
+  if (ctx) colorContexts.set(createCanvas, ctx);
+  return ctx;
+}
+function parseColorWithCanvas(val, createCanvas) {
+  try {
+    const ctx = colorContextFor(createCanvas);
+    if (!ctx) return null;
+    ctx.clearRect(0, 0, 1, 1);
+    ctx.fillStyle = "#000000";
+    ctx.fillStyle = val;
+    ctx.fillRect(0, 0, 1, 1);
+    const data = ctx.getImageData(0, 0, 1, 1).data;
+    return [data[0] / 255, data[1] / 255, data[2] / 255, data[3] / 255];
+  } catch {
+    return null;
+  }
+}
+function parseColor(str, createCanvas = resolveEnv(null).createCanvas) {
+  if (!str) return [1, 1, 1, 1];
+  const val = str.trim();
+  if (val.startsWith("#")) {
+    const hex = parseHex(val.slice(1));
+    if (hex) return hex;
+  }
+  const rgb = parseRgbFunctional(val);
+  if (rgb) return rgb;
+  const lower = val.toLowerCase();
+  if (lower in NAMED_COLORS) return NAMED_COLORS[lower];
+  const canvasColor = parseColorWithCanvas(val, createCanvas);
+  if (canvasColor) return canvasColor;
+  return [1, 1, 1, 1];
+}
+var ANGLE_UNITS = {
+  deg: Math.PI / 180,
+  grad: Math.PI / 200,
+  rad: 1,
+  turn: Math.PI * 2
+};
+function parseAngleRadians(raw) {
+  if (!raw) return 0;
+  const match = /^([+-]?(?:\d+(?:\.\d+)?|\.\d+))(deg|grad|rad|turn)?$/i.exec(raw.trim());
+  if (!match) return 0;
+  const value = parseFloat(match[1]);
+  if (!Number.isFinite(value)) return 0;
+  return value * (ANGLE_UNITS[(match[2] ?? "deg").toLowerCase()] ?? ANGLE_UNITS.deg);
+}
+var PALETTE_SIZE = 5;
+var DEFAULT_PALETTE = [
+  [0.09, 0.11, 0.25, 1],
+  [0.45, 0.29, 0.78, 1]
+];
+function buildPalette(authored, createCanvas) {
+  const set = authored.filter((raw) => raw.trim() !== "").slice(0, PALETTE_SIZE);
+  const stops = set.length >= 2 ? set.map((raw) => parseColor(raw, createCanvas)) : [...DEFAULT_PALETTE];
+  const palette = new Float32Array(PALETTE_SIZE * 4);
+  for (let i = 0; i < PALETTE_SIZE; i += 1) {
+    const stop = stops[Math.min(i, stops.length - 1)];
+    palette.set(stop, i * 4);
+  }
+  return { palette, colorCount: stops.length };
+}
+function cacheLocalLocations(gl, locs, program) {
+  if (locs.u_audio === void 0) locs.u_audio = gl.getUniformLocation(program, "u_audio");
+  if (locs.u_noise === void 0) locs.u_noise = gl.getUniformLocation(program, "u_noise");
+  return locs;
+}
+function resolveLocations(gl, progInfo) {
+  if (!progInfo) return null;
+  if ("program" in progInfo && progInfo.program) return cacheLocalLocations(gl, progInfo, progInfo.program);
+  const p = progInfo;
+  const g = (n) => gl.getUniformLocation(p, n);
+  return {
+    u_time: g("u_time"),
+    u_strength: g("u_strength"),
+    u_frequency: g("u_frequency"),
+    u_chromatic: g("u_chromatic"),
+    u_iridescence: g("u_iridescence"),
+    u_mouse: g("u_mouse"),
+    u_uvOrigin: g("u_uvOrigin"),
+    u_uvScale: g("u_uvScale"),
+    u_tint: g("u_tint"),
+    u_blend: g("u_blend"),
+    u_duotone: g("u_duotone"),
+    u_color1: g("u_color1"),
+    u_color2: g("u_color2"),
+    u_image: g("u_image"),
+    u_image_to: g("u_image_to"),
+    u_progress: g("u_progress"),
+    u_audio: g("u_audio"),
+    u_noise: g("u_noise"),
+    u_maskBox: g("u_maskBox"),
+    u_maskRx: g("u_maskRx"),
+    u_maskRy: g("u_maskRy"),
+    u_maskAlpha: g("u_maskAlpha"),
+    u_seed: g("u_seed"),
+    u_scale: g("u_scale"),
+    u_warp: g("u_warp"),
+    u_grain: g("u_grain"),
+    u_hue: g("u_hue"),
+    u_detail: g("u_detail"),
+    u_bands: g("u_bands"),
+    u_colorCount: g("u_colorCount"),
+    u_colors: g("u_colors"),
+    // `u_maskMode` was missing from this branch while `extractLocations` looked it up, so an
+    // external caller handing this module a bare `WebGLProgram` got a generative draw with no
+    // stencil. Latent — everything inside this file goes through `extractLocations` — but the two
+    // lists are supposed to answer the same question, and one of them was a stop short.
+    u_maskMode: g("u_maskMode"),
+    u_hover: g("u_hover"),
+    u_backdrop: g("u_backdrop"),
+    u_angle: g("u_angle"),
+    u_motion: g("u_motion")
+  };
+}
+var NO_MASK_BOX = [0, 0, 0, 0];
+var NO_BACKDROP = [0, 0, 0, 0];
+function uploadMaskUniforms(gl, locs, opt) {
+  if (locs.u_maskBox) gl.uniform4fv(locs.u_maskBox, opt.maskBox ?? NO_MASK_BOX);
+  if (locs.u_maskRx) gl.uniform4fv(locs.u_maskRx, opt.maskRx ?? NO_MASK_BOX);
+  if (locs.u_maskRy) gl.uniform4fv(locs.u_maskRy, opt.maskRy ?? NO_MASK_BOX);
+  uploadFloat(gl, locs.u_maskAlpha, opt.maskAlpha ?? 1);
+}
+function uploadFloat(gl, loc, val) {
+  if (loc && val !== void 0) gl.uniform1f(loc, val);
+}
+function uploadInt(gl, loc, val) {
+  if (loc && val !== void 0) gl.uniform1i(loc, Math.round(val));
+}
+function uploadFieldSamplingUniforms(gl, locs, opt) {
+  uploadFloat(gl, locs.u_seed, opt.seed ?? 0);
+  uploadFloat(gl, locs.u_scale, opt.scale ?? 1);
+  uploadFloat(gl, locs.u_warp, opt.warp ?? 0);
+  uploadFloat(gl, locs.u_noise, opt.noise ?? 0);
+}
+function uploadFieldTextureUniforms(gl, locs, opt) {
+  uploadFloat(gl, locs.u_grain, opt.grain ?? 0);
+  uploadFloat(gl, locs.u_hue, opt.hue ?? 0);
+  uploadInt(gl, locs.u_detail, opt.detail ?? 3);
+  uploadInt(gl, locs.u_bands, opt.bands ?? 0);
+}
+function uploadFieldBranchUniforms(gl, locs, opt) {
+  uploadInt(gl, locs.u_maskMode, opt.maskMode ?? 0);
+  uploadInt(gl, locs.u_hover, opt.hover ?? 0);
+  uploadFloat(gl, locs.u_angle, opt.angle ?? 0);
+  uploadInt(gl, locs.u_motion, opt.motion ?? 0);
+}
+function uploadFieldUniforms(gl, locs, opt) {
+  uploadFieldSamplingUniforms(gl, locs, opt);
+  uploadFieldTextureUniforms(gl, locs, opt);
+  uploadFieldBranchUniforms(gl, locs, opt);
+  if (locs.u_backdrop) gl.uniform4fv(locs.u_backdrop, opt.backdropRgba ?? NO_BACKDROP);
+}
+function uploadCoordUniforms(gl, locs, opt) {
+  if (locs.u_mouse && opt.localMouse) gl.uniform2f(locs.u_mouse, opt.localMouse.x, opt.localMouse.y);
+  if (locs.u_uvOrigin && opt.uvOrigin) gl.uniform2f(locs.u_uvOrigin, opt.uvOrigin[0], opt.uvOrigin[1]);
+  if (locs.u_uvScale && opt.uvScale) gl.uniform2f(locs.u_uvScale, opt.uvScale[0], opt.uvScale[1]);
+}
+function uploadUniforms(gl, progInfo, opt) {
+  const locs = resolveLocations(gl, progInfo);
+  if (!locs) return;
+  const timeVal = opt.time !== void 0 ? opt.time * (opt.speed ?? 1) : void 0;
+  uploadFloat(gl, locs.u_time, timeVal);
+  uploadFloat(gl, locs.u_strength, opt.strength);
+  uploadFloat(gl, locs.u_frequency, opt.frequency);
+  uploadFloat(gl, locs.u_chromatic, opt.chromatic);
+  uploadFloat(gl, locs.u_iridescence, opt.iridescence);
+  uploadFloat(gl, locs.u_progress, opt.progress ?? -1);
+  uploadFloat(gl, locs.u_audio, opt.audio ?? 0);
+  uploadCoordUniforms(gl, locs, opt);
+  uploadMaskUniforms(gl, locs, opt);
+  uploadFieldUniforms(gl, locs, opt);
+}
+function uploadDuotoneUniforms(gl, locs, opt) {
+  if (!opt.isDuotone) return;
+  if (locs.u_color1 && opt.c1Rgba) gl.uniform4fv(locs.u_color1, opt.c1Rgba);
+  if (locs.u_color2 && opt.c2Rgba) gl.uniform4fv(locs.u_color2, opt.c2Rgba);
+}
+function uploadColorUniforms(gl, progInfo, opt) {
+  const locs = resolveLocations(gl, progInfo);
+  if (!locs) return;
+  if (locs.u_tint && opt.tintRgba) gl.uniform4fv(locs.u_tint, opt.tintRgba);
+  if (locs.u_blend && opt.blendMode !== void 0) gl.uniform1i(locs.u_blend, opt.blendMode);
+  if (locs.u_duotone) gl.uniform1f(locs.u_duotone, opt.isDuotone ? 1 : 0);
+  uploadDuotoneUniforms(gl, locs, opt);
+  if (locs.u_colors && opt.palette) gl.uniform4fv(locs.u_colors, opt.palette);
+  uploadInt(gl, locs.u_colorCount, opt.colorCount);
+}
+function isRectVisible(rect, winHeight) {
+  if (rect.width <= 0 || rect.height <= 0) return false;
+  return rect.bottom >= 0 && rect.top <= winHeight;
+}
+function getScissorEnv(win) {
+  return {
+    height: win?.innerHeight ?? 800,
+    dpr: Math.min(win?.devicePixelRatio ?? 1, 2)
+  };
+}
+function numOr(raw, fallback = 0) {
+  const val = parseFloat(raw ?? "");
+  return Number.isFinite(val) ? val : fallback;
+}
+function cssStyleOf(el, win) {
+  const gcs = win?.getComputedStyle;
+  if (typeof gcs !== "function") return null;
+  try {
+    return gcs.call(win, el);
+  } catch {
+    return null;
+  }
+}
+function boxOf(rect) {
+  return { left: rect.left, top: rect.top, right: rect.left + rect.width, bottom: rect.top + rect.height };
+}
+function intersectBox(a, b) {
+  return {
+    left: Math.max(a.left, b.left),
+    top: Math.max(a.top, b.top),
+    right: Math.min(a.right, b.right),
+    bottom: Math.min(a.bottom, b.bottom)
+  };
+}
+function insetBox(box, by) {
+  return {
+    left: box.left + by.left,
+    top: box.top + by.top,
+    right: box.right - by.right,
+    bottom: box.bottom - by.bottom
+  };
+}
+function borderWidthsOf(cs) {
+  return {
+    left: numOr(cs.borderLeftWidth),
+    top: numOr(cs.borderTopWidth),
+    right: numOr(cs.borderRightWidth),
+    bottom: numOr(cs.borderBottomWidth)
+  };
+}
+function contentBoxOf(rect, cs) {
+  const border = boxOf(rect);
+  if (!cs) return border;
+  const edges = borderWidthsOf(cs);
+  return insetBox(border, {
+    left: edges.left + numOr(cs.paddingLeft),
+    top: edges.top + numOr(cs.paddingTop),
+    right: edges.right + numOr(cs.paddingRight),
+    bottom: edges.bottom + numOr(cs.paddingBottom)
+  });
+}
+function fittedSize(fit, bw, bh, natural) {
+  const [iw, ih] = natural;
+  if (fit === "cover") {
+    const s = Math.max(bw / iw, bh / ih);
+    return [iw * s, ih * s];
+  }
+  if (fit === "none") return [iw, ih];
+  if (fit === "contain" || fit === "scale-down") {
+    const s = Math.min(bw / iw, bh / ih, fit === "scale-down" ? 1 : Infinity);
+    return [iw * s, ih * s];
+  }
+  return [bw, bh];
+}
+var POSITION_KEYWORDS = { left: 0, top: 0, center: 0.5, right: 1, bottom: 1 };
+function positionOffset(token, free) {
+  const keyword = POSITION_KEYWORDS[token];
+  if (keyword !== void 0) return free * keyword;
+  if (token.endsWith("%")) return free * (numOr(token) / 100);
+  return numOr(token, free * 0.5);
+}
+function paintBoxOf(content, natural, cs) {
+  if (!natural || !cs) return content;
+  const bw = content.right - content.left;
+  const bh = content.bottom - content.top;
+  if (bw <= 0 || bh <= 0) return content;
+  const [dw, dh] = fittedSize(cs.objectFit || "fill", bw, bh, natural);
+  const tokens = (cs.objectPosition || "50% 50%").trim().split(/\s+/);
+  const left = content.left + positionOffset(tokens[0] ?? "50%", bw - dw);
+  const top = content.top + positionOffset(tokens[1] ?? "50%", bh - dh);
+  return { left, top, right: left + dw, bottom: top + dh };
+}
+function radiusPart(token, basis) {
+  if (!token) return 0;
+  return token.endsWith("%") ? Math.max(0, basis * (numOr(token) / 100)) : Math.max(0, numOr(token));
+}
+function cornerRadius(raw, bw, bh) {
+  const parts = (raw ?? "").trim().split(/\s+/);
+  return [radiusPart(parts[0], bw), radiusPart(parts[1] ?? parts[0], bh)];
+}
+function radiiOf(cs, rect) {
+  if (!cs) return [0, 0, 0, 0, 0, 0, 0, 0];
+  const w = rect.width, h = rect.height;
+  const tl = cornerRadius(cs.borderTopLeftRadius, w, h);
+  const tr = cornerRadius(cs.borderTopRightRadius, w, h);
+  const br = cornerRadius(cs.borderBottomRightRadius, w, h);
+  const bl = cornerRadius(cs.borderBottomLeftRadius, w, h);
+  return [tl[0], tl[1], tr[0], tr[1], br[0], br[1], bl[0], bl[1]];
+}
+function naturalSizeOf(el) {
+  const { naturalWidth: w, naturalHeight: h } = el;
+  if (typeof w !== "number" || typeof h !== "number" || w <= 0 || h <= 0) return null;
+  return [w, h];
+}
+function isClipping(cs) {
+  for (const overflow of [cs.overflowX, cs.overflowY]) {
+    if (overflow && overflow !== "visible") return true;
+  }
+  return false;
+}
+var ANCESTOR_WALK_LIMIT = 12;
+function isContainingBlock(cs) {
+  if (cs.position && cs.position !== "static") return true;
+  return [cs.transform, cs.filter, cs.perspective].some((v) => v && v !== "none");
+}
+function clipsSubject(subject, cs) {
+  if (subject === "fixed") return false;
+  if (subject === "absolute") return isContainingBlock(cs);
+  return true;
+}
+function narrowByAncestor(acc, node, win) {
+  const cs = cssStyleOf(node, win);
+  if (!cs) return;
+  const opacity = numOr(cs.opacity, 1);
+  if (opacity < 1) acc.alpha *= Math.max(0, opacity);
+  if (clipsSubject(acc.subject, cs)) {
+    const rect = isClipping(cs) ? node.getBoundingClientRect?.() : null;
+    if (rect) acc.clip = intersectBox(acc.clip, insetBox(boxOf(rect), borderWidthsOf(cs)));
+    acc.subject = cs.position || "static";
+  }
+}
+function walkAncestors(el, win, start, subject) {
+  const acc = { clip: start, alpha: 1, subject };
+  let node = el.parentElement ?? null;
+  for (let depth = 0; node && depth < ANCESTOR_WALK_LIMIT; depth++) {
+    narrowByAncestor(acc, node, win);
+    node = node.parentElement ?? null;
+  }
+  return acc;
+}
+function measureElementGeometry(el, win, fullBox = false, hostAlpha) {
+  const rect = el.getBoundingClientRect();
+  const { height } = getScissorEnv(win);
+  if (!isRectVisible(rect, height)) return null;
+  const view = win ?? null;
+  const cs = cssStyleOf(el, view);
+  const border = boxOf(rect);
+  const content = fullBox ? border : contentBoxOf(rect, cs);
+  const walked = walkAncestors(el, view, content, cs?.position || "static");
+  const own = Math.max(0, Math.min(1, hostAlpha ?? numOr(cs?.opacity, 1)));
+  return {
+    border,
+    paint: fullBox ? border : paintBoxOf(content, naturalSizeOf(el), cs),
+    clip: walked.clip,
+    radii: radiiOf(cs, rect),
+    alpha: walked.alpha * own,
+    hostAlpha: own
+  };
+}
+function maskUniformsOf(geom, canvasHeight, dpr) {
+  const b = geom.border;
+  const r = geom.radii;
+  return {
+    maskBox: [
+      (b.left + b.right) * 0.5 * dpr,
+      canvasHeight - (b.top + b.bottom) * 0.5 * dpr,
+      (b.right - b.left) * 0.5 * dpr,
+      (b.bottom - b.top) * 0.5 * dpr
+    ],
+    maskRx: [r[0] * dpr, r[2] * dpr, r[4] * dpr, r[6] * dpr],
+    maskRy: [r[1] * dpr, r[3] * dpr, r[5] * dpr, r[7] * dpr]
+  };
+}
+function resolveDrawBox(geom, canvas, dpr) {
+  const paintW = geom.paint.right - geom.paint.left;
+  const paintH = geom.paint.bottom - geom.paint.top;
+  if (paintW <= 0 || paintH <= 0) return null;
+  const view = { left: 0, top: 0, right: canvas.width / dpr, bottom: canvas.height / dpr };
+  const draw = intersectBox(intersectBox(geom.paint, geom.clip), view);
+  const drawW = draw.right - draw.left;
+  const drawH = draw.bottom - draw.top;
+  if (drawW <= 0 || drawH <= 0) return null;
+  const sx = Math.round(draw.left * dpr);
+  const sy = Math.round(canvas.height - draw.bottom * dpr);
+  const sw = Math.min(canvas.width - sx, Math.round(drawW * dpr));
+  const sh = Math.min(canvas.height - sy, Math.round(drawH * dpr));
+  if (sw <= 0 || sh <= 0) return null;
+  const b = geom.border;
+  return {
+    sx,
+    sy,
+    sw,
+    sh,
+    rect: { left: b.left, top: b.top, width: b.right - b.left, height: b.bottom - b.top },
+    uvOrigin: [(draw.left - geom.paint.left) / paintW, (draw.top - geom.paint.top) / paintH],
+    uvScale: [drawW / paintW, drawH / paintH],
+    alpha: geom.alpha,
+    ...maskUniformsOf(geom, canvas.height, dpr)
+  };
+}
+function applyDrawBox(gl, canvas, geom, dpr) {
+  const box = resolveDrawBox(geom, canvas, dpr);
+  if (!box) return null;
+  gl.enable(gl.SCISSOR_TEST);
+  gl.viewport(box.sx, box.sy, box.sw, box.sh);
+  gl.scissor(box.sx, box.sy, box.sw, box.sh);
+  return box;
+}
+function bindShaderTexture(gl, progInfo, texture, toTexture) {
+  if (!texture) return;
+  const locs = resolveLocations(gl, progInfo);
+  gl.activeTexture(gl.TEXTURE0);
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  if (locs?.u_image) gl.uniform1i(locs.u_image, 0);
+  if (locs?.u_image_to) {
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, toTexture || texture);
+    gl.uniform1i(locs.u_image_to, 1);
+  }
+}
+function getProgram(info) {
+  if (!info) return null;
+  return "program" in info && info.program ? info.program : info;
+}
+function computeMousePos(renderer, rect) {
+  if (renderer.hasPointer === false) return { x: 0.5, y: 0.5 };
+  const mx = renderer.mouse.x - rect.left;
+  const my = renderer.mouse.y - rect.top;
+  return {
+    x: clamp(mx / rect.width, 0, 1),
+    y: clamp(my / rect.height, 0, 1)
+  };
+}
+function bindQuadAttrib(gl, quadBuffer, info) {
+  gl.bindBuffer(gl.ARRAY_BUFFER, quadBuffer);
+  const locs = info;
+  if (locs?.a_position !== void 0 && locs.a_position !== -1) {
+    gl.enableVertexAttribArray(locs.a_position);
+    gl.vertexAttribPointer(locs.a_position, 2, gl.FLOAT, false, 0, 0);
+  }
+}
+function drawTargets(renderer) {
+  const { gl, canvas, quadBuffer } = renderer;
+  return gl && canvas && quadBuffer ? { gl, canvas } : null;
+}
+function drawElementQuad(renderer, el, opt = {}) {
+  const target = drawTargets(renderer);
+  if (!target) return false;
+  const { gl, canvas } = target;
+  const mode = opt.mode ?? "displace";
+  const info = renderer.programs[mode];
+  if (info === void 0) return false;
+  const program = getProgram(info);
+  if (!program) return false;
+  const geom = opt.geometry !== void 0 ? opt.geometry : measureElementGeometry(el, renderer.window, GENERATIVE_MODES.has(mode));
+  if (!geom) return false;
+  const scissor = applyDrawBox(gl, canvas, geom, getScissorEnv(renderer.window).dpr);
+  if (!scissor) return false;
+  const localMouse = computeMousePos(renderer, scissor.rect);
+  gl.useProgram(program);
+  bindShaderTexture(gl, info, opt.texture, opt.toTexture);
+  uploadUniforms(gl, info, {
+    ...opt,
+    localMouse,
+    uvOrigin: scissor.uvOrigin,
+    uvScale: scissor.uvScale,
+    maskBox: scissor.maskBox,
+    maskRx: scissor.maskRx,
+    maskRy: scissor.maskRy,
+    maskAlpha: scissor.alpha
+  });
+  uploadColorUniforms(gl, info, opt);
+  bindQuadAttrib(gl, renderer.quadBuffer, info);
+  gl.drawArrays(gl.TRIANGLES, 0, 6);
+  return true;
+}
+var GENERATIVE_MODES = /* @__PURE__ */ new Set(["gradient"]);
+var SHADER_MODES = ["displace", "fluid", "liquid", "particles", "morph", "gradient", "logo"];
+var PROGRAM_SOURCES = [
+  [["displace"], DISPLACE_FS],
+  [["fluid"], FLUID_FS],
+  [["liquid"], LIQUID_FS],
+  [["particles"], PARTICLES_FS],
+  [["morph"], MORPH_FS],
+  [["gradient", "logo"], GRADIENT_FS]
+];
+var MASK_MODES = { alpha: 1, luma: 2, "luma-invert": 3 };
+var HOVER_MODES = { none: 0, stir: 1, light: 2, both: 3 };
+var MOTION_MODES = { evolve: 0, drift: 1, swirl: 2 };
+function readShaderMode(params) {
+  return "keyword" in params && typeof params.keyword === "function" ? params.keyword("mode") : params.text("mode", "displace");
+}
+function readMaskMode(params, mode) {
+  return mode === "logo" ? MASK_MODES[params.text("mask", "alpha")] ?? MASK_MODES.alpha : 0;
+}
+function readDuotoneColors(c1Text, c2Text, createCanvas) {
+  return {
+    isDuotone: Boolean(c1Text && c2Text),
+    c1Rgba: parseColor(c1Text || "#000000", createCanvas),
+    c2Rgba: parseColor(c2Text || "#ffffff", createCanvas)
+  };
+}
+function extractShaderOptions(params, createCanvas) {
+  const mode = readShaderMode(params);
+  const c1Text = params.text("color1", "");
+  const c2Text = params.text("color2", "");
+  const backdropText = params.text("backdrop", "").trim();
+  const blendMap = { normal: 0, screen: 1, multiply: 2, add: 3 };
+  const { palette, colorCount } = buildPalette([
+    c1Text,
+    c2Text,
+    params.text("color3", ""),
+    params.text("color4", ""),
+    params.text("color5", "")
+  ], createCanvas);
+  return {
+    mode,
+    seed: params.num("seed", 0),
+    scale: params.num("scale", 1),
+    warp: params.num("warp", 0),
+    noise: params.num("noise", 0),
+    grain: params.num("grain", 0),
+    hue: parseAngleRadians(params.text("hue", "0deg")),
+    detail: params.num("detail", 3),
+    bands: params.num("bands", 0),
+    palette,
+    colorCount,
+    maskMode: readMaskMode(params, mode),
+    hover: HOVER_MODES[params.text("hover", "none")] ?? 0,
+    angle: parseAngleRadians(params.text("angle", "0deg")),
+    motion: MOTION_MODES[params.text("motion", "evolve")] ?? 0,
+    // Read through the raw string rather than straight into `parseColor`, which answers opaque
+    // white for an empty input — the fallback that makes an unset `color1` harmless would make an
+    // unset `backdrop` a white plate behind every logo on the page.
+    backdropRgba: backdropText ? parseColor(backdropText, createCanvas) : [0, 0, 0, 0],
+    strength: params.num("strength", 0.5),
+    speed: params.num("speed", 1),
+    frequency: params.num("frequency", 10),
+    chromatic: params.num("chromatic", 0),
+    iridescence: params.num("iridescence", 0),
+    tintRgba: parseColor(params.text("tint", "#ffffff"), createCanvas),
+    ...readDuotoneColors(c1Text, c2Text, createCanvas),
+    blendMode: blendMap[params.text("blend", "normal")] ?? 0,
+    to: params.text("to", ""),
+    progress: params.num ? params.num("progress", -1) : -1,
+    // Compared against the one enabling word rather than "not `off`", so — exactly as with
+    // `audioBand` below — a caller passing an unvalidated accessor, or an author who typed
+    // `scrub: scrol`, cannot turn the bridge on by accident.
+    scrubsFromScroll: params.text("scrub", "off") === "scroll",
+    // `parseAudioBand` answers `null` for `off`, for an empty string, and for any word that is not
+    // a band, so a caller passing an unvalidated accessor cannot turn the feature on by accident.
+    audioBand: parseAudioBand(params.text("audio", "off"))
+  };
+}
+function parseProgressValue(raw) {
+  if (!raw) return null;
+  const val = parseFloat(raw);
+  return Number.isFinite(val) ? clamp(val, 0, 1) : null;
+}
+function readElementProgress(el) {
+  const fromInline = parseProgressValue(el.style?.getPropertyValue?.("--kui-progress"));
+  if (fromInline !== null) return fromInline;
+  const view = el.ownerDocument?.defaultView;
+  const fromComputed = parseProgressValue(view?.getComputedStyle?.(el).getPropertyValue("--kui-progress"));
+  return fromComputed !== null ? fromComputed : -1;
+}
+var nextShaderId = 0;
+function invokeIsolated(fn) {
+  try {
+    fn();
+  } catch {
+    return;
+  }
+}
+function syncCanvasDimensions(canvas, win, dpr) {
+  const vw = win?.innerWidth ?? 1e3;
+  const vh = win?.innerHeight ?? 800;
+  const cw = Math.round(vw * dpr);
+  const ch = Math.round(vh * dpr);
+  if (canvas.width !== cw || canvas.height !== ch) {
+    canvas.width = cw;
+    canvas.height = ch;
+  }
+  const style = canvas.style;
+  if (!style) return;
+  const cssW = `${vw}px`;
+  const cssH = `${vh}px`;
+  if (style.width !== cssW) style.width = cssW;
+  if (style.height !== cssH) style.height = cssH;
+}
+var DEFAULT_SHADER_Z_INDEX = 1;
+var SHADER_Z_PROPERTY = "--kui-shader-z";
+function readShaderZIndex(doc, win) {
+  const root = doc?.documentElement;
+  if (!root) return DEFAULT_SHADER_Z_INDEX;
+  const inline = parseZIndexValue(root.style?.getPropertyValue?.(SHADER_Z_PROPERTY));
+  return inline ?? readComputedZIndex(root, win) ?? DEFAULT_SHADER_Z_INDEX;
+}
+function readComputedZIndex(root, win) {
+  return parseZIndexValue(win?.getComputedStyle?.(root)?.getPropertyValue?.(SHADER_Z_PROPERTY));
+}
+function parseZIndexValue(raw) {
+  const trimmed = raw?.trim();
+  if (!trimmed) return null;
+  const n = Number(trimmed);
+  return Number.isFinite(n) ? Math.trunc(n) : null;
+}
+var SharedShaderRenderer = class {
+  env;
+  window;
+  document;
+  createCanvas;
+  raf;
+  caf;
+  canvas = null;
+  gl = null;
+  quadBuffer = null;
+  rafId = null;
+  drawCalls = /* @__PURE__ */ new Map();
+  contextCallbacks = /* @__PURE__ */ new Map();
+  /**
+   * One style-reading pass per registered instance — scroll progress and, when the author asked
+   * for one, an audio band — run in full before any instance's draw call this frame. See
+   * `renderFrame` for why the ordering, not just the reads themselves, is the point.
+   */
+  inputReaders = /* @__PURE__ */ new Map();
+  programs = {};
+  refCount = 0;
+  mouse = { x: 0, y: 0 };
+  /** Cleared until a real `pointermove` lands. See {@link computeMousePos}. */
+  hasPointer = false;
+  isContextLost = false;
+  /**
+   * Bumped every time this renderer's GL objects stop being valid, i.e. on each context loss.
+   *
+   * It exists because "is this handle still real?" has no other answer. A `WebGLTexture` from a lost
+   * context is an ordinary live JavaScript object — binding it raises `INVALID_OPERATION` and
+   * samples nothing, and neither the draw nor `drawElementQuad`'s return value can tell.
+   *
+   * The hole it closes: `cancel()`/`finish()` unregister an instance, which takes its entry out of
+   * `contextCallbacks` with it, so an *inactive* instance is never told the context went away. Its
+   * texture holders kept answering with pre-loss handles, and `acquireRenderer` short-circuits on
+   * re-activation because the renderer itself was never destroyed — so a hover, a hover-out, a
+   * context loss and a second hover drew a blank replica over a hidden image, permanently.
+   *
+   * Stamping the holders rather than keeping every acquired instance registered for context events:
+   * the stamp is checked where the stale handle is actually read, so it holds however the instance
+   * came to miss the event, and it costs two compares per holder per frame. See
+   * {@link initTextureHolder}.
+   */
+  contextGeneration = 0;
+  mapKey;
+  onPointer;
+  onContextLost;
+  onContextRestored;
+  constructor(env = {}) {
+    this.env = env;
+    const r = resolveEnv(null, env);
+    this.window = r.window;
+    this.document = r.document;
+    this.createCanvas = r.createCanvas;
+    this.raf = r.raf;
+    this.caf = r.caf;
+    this.mapKey = r.document ?? r.window ?? fallbackShaderKey;
+  }
+  /**
+   * Whether `destroy()` has run. A destroyed renderer never comes back to life.
+   *
+   * `destroy()` un-maps itself, so the object an already-prepared instance is still holding is no
+   * longer the one `getSharedShaderRenderer` hands out. Letting `acquire()` re-`init()` that object
+   * therefore built a *second* full-viewport canvas and WebGL2 context in one document — and then
+   * a third, because the next element to be prepared found nothing in the map and made its own,
+   * and whichever of them tore down next deleted the shared document key from under the live one.
+   * Cycling shader elements on an SPA route walked straight into the browser's 8-16 context cap.
+   *
+   * So a teardown is final, and `RendererRef` is what gets an orphaned instance back onto the live
+   * renderer.
+   */
+  isDestroyed = false;
+  acquire() {
+    if (this.isDestroyed) return false;
+    if (this.canvas && this.isContextLost) {
+      this.refCount++;
+      return true;
+    }
+    if (this.gl && !this.isContextLost) {
+      this.refCount++;
+      return true;
+    }
+    const ok = this.init();
+    if (ok) this.refCount++;
+    return ok;
+  }
+  release() {
+    if (this.refCount > 0) this.refCount--;
+    if (this.refCount === 0) this.destroy();
+  }
+  init() {
+    if (!this.document?.body?.appendChild) return false;
+    this.canvas = this.createCanvas();
+    if (!this.canvas) return false;
+    this.canvas.className = "kui-shader-canvas";
+    this.canvas.style.cssText = `position:fixed;top:0;left:0;pointer-events:none;z-index:${readShaderZIndex(this.document, this.window)};`;
+    this.gl = this.canvas.getContext ? this.canvas.getContext("webgl2", { alpha: true, premultipliedAlpha: true }) : null;
+    if (!this.gl) return false;
+    syncCanvasDimensions(this.canvas, this.window, getScissorEnv(this.window).dpr);
+    this.document.body.appendChild(this.canvas);
+    if (!this.initQuad()) return this.abandonInit();
+    this.initPrograms();
+    this.bindEvents();
+    this.startLoop();
+    return true;
+  }
+  /**
+   * Undo a half-built `init()` and report it as a failure.
+   *
+   * Not `destroy()`: nothing has acquired this renderer yet, so there is no teardown to broadcast,
+   * and marking it `isDestroyed` would retire an object that is free to try again the next time
+   * something acquires it. Under transient memory pressure that retry is the whole point — the
+   * alternative is a permanently dead renderer for a `createBuffer` that would succeed a second
+   * later. The canvas goes because it is already in the document by this point; leaving it would
+   * stack one invisible full-viewport canvas per attempt.
+   */
+  abandonInit() {
+    disposeGLResources(this.gl, this.quadBuffer, this.programs);
+    this.canvas?.remove();
+    this.canvas = null;
+    this.gl = null;
+    this.quadBuffer = null;
+    this.programs = {};
+    return false;
+  }
+  /**
+   * Allocate and fill the one static buffer every draw in this module reads its vertices from.
+   *
+   * Returns whether it worked, and the caller has to care. `gl.createBuffer()` returns `null` under
+   * memory pressure rather than throwing, and so does nothing else downstream: `vertexAttribPointer`
+   * and `drawArrays` against a null binding only *set* a GL error, and `drawElementQuad` used to
+   * return `true` regardless. The visible result was the worst possible one — every affected
+   * element's `opacity` driven to 0 by `hideBehindRenderer` with nothing drawn over it, so the page
+   * lost its images rather than losing an effect. A renderer that cannot allocate this is not a
+   * renderer, so it fails here instead.
+   *
+   * `bufferData` is guarded too, and only for a host that throws rather than raising `OUT_OF_MEMORY`
+   * through the error queue. Reading the queue is deliberately not done: `getError` is a
+   * synchronous round-trip to the GPU process, and the allocation failure it would catch is already
+   * caught by the null above.
+   */
+  initQuad() {
+    const gl = this.gl;
+    if (!gl) return false;
+    this.quadBuffer = gl.createBuffer();
+    if (!this.quadBuffer) return false;
+    try {
+      gl.bindBuffer(gl.ARRAY_BUFFER, this.quadBuffer);
+      gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]), gl.STATIC_DRAW);
+    } catch {
+      if (gl.deleteBuffer) gl.deleteBuffer(this.quadBuffer);
+      this.quadBuffer = null;
+      return false;
+    }
+    return true;
+  }
+  initPrograms() {
+    const gl = this.gl;
+    if (!gl) return;
+    this.programs = {};
+    for (const [modes, fs] of PROGRAM_SOURCES) {
+      const prog = createProgram(gl, FULLSCREEN_QUAD_VS, fs);
+      if (!prog) continue;
+      const locs = extractLocations(gl, prog);
+      for (const mode of modes) this.programs[mode] = locs;
+    }
+  }
+  bindEvents() {
+    this.onPointer = (e) => {
+      this.mouse.x = e.clientX;
+      this.mouse.y = e.clientY;
+      this.hasPointer = true;
+    };
+    this.window?.addEventListener?.("pointermove", this.onPointer, { passive: true });
+    if (this.canvas) {
+      this.onContextLost = (e) => {
+        if (e && typeof e.preventDefault === "function") e.preventDefault();
+        this.isContextLost = true;
+        this.contextGeneration++;
+        this.stopLoop();
+        for (const cb of this.contextCallbacks.values()) invokeIsolated(() => cb.onLost());
+      };
+      this.onContextRestored = () => {
+        this.isContextLost = false;
+        const ok = this.initQuad();
+        this.initPrograms();
+        for (const cb of this.contextCallbacks.values()) invokeIsolated(() => cb.onRestored());
+        if (ok) this.startLoop();
+      };
+      this.canvas.addEventListener("webglcontextlost", this.onContextLost, false);
+      this.canvas.addEventListener("webglcontextrestored", this.onContextRestored, false);
+    }
+  }
+  createTexture(source) {
+    return this.gl ? createGLTexture(this.gl, source) : null;
+  }
+  register(id, fn, callbacks, readInputs) {
+    this.drawCalls.set(id, fn);
+    if (callbacks) this.contextCallbacks.set(id, callbacks);
+    if (readInputs) this.inputReaders.set(id, readInputs);
+    if (!this.isContextLost) this.startLoop();
+  }
+  unregister(id) {
+    this.drawCalls.delete(id);
+    this.contextCallbacks.delete(id);
+    this.inputReaders.delete(id);
+  }
+  startLoop() {
+    if (this.rafId || this.isContextLost) return;
+    const tick = (ts) => {
+      this.renderFrame(ts * 1e-3);
+      if (this.drawCalls.size > 0 && !this.isContextLost) {
+        this.rafId = this.raf(tick);
+      } else {
+        this.rafId = null;
+      }
+    };
+    this.rafId = this.raf(tick);
+  }
+  stopLoop() {
+    if (this.rafId) {
+      this.caf(this.rafId);
+      this.rafId = null;
+    }
+  }
+  renderFrame(timeSeconds) {
+    const gl = this.gl;
+    if (!gl || !this.canvas || this.isContextLost) return;
+    const dpr = Math.min(this.window?.devicePixelRatio ?? 1, 2);
+    syncCanvasDimensions(this.canvas, this.window, dpr);
+    gl.disable(gl.SCISSOR_TEST);
+    gl.clearColor(0, 0, 0, 0);
+    gl.clear(gl.COLOR_BUFFER_BIT);
+    for (const readInputs of this.inputReaders.values()) invokeIsolated(readInputs);
+    this.runDrawCalls(timeSeconds);
+  }
+  /**
+   * Every registered instance's draw, in registration order, each one isolated from its neighbours.
+   *
+   * The snapshot is here because a draw call may unregister itself — the `catch` below does — and
+   * mutating `drawCalls` under a live iterator would skip its neighbour. But a snapshot of the
+   * *entries* must not become a snapshot of the *context*, which is why the `gl` is re-read per
+   * iteration rather than taken from `renderFrame`'s. `destroy()` nulls `gl` and deletes the
+   * programs, so a draw call that dropped the last reference mid-frame left every remaining entry
+   * in the snapshot drawing through a disposed context, on a renderer already `isDestroyed` with
+   * its `drawCalls` cleared. The same re-read covers a context lost mid-frame, where `gl` survives
+   * but the programs and buffers do not.
+   *
+   * @param timeSeconds - This frame's timestamp, passed to every draw call.
+   * @complexity O(n) in registered instances.
+   */
+  runDrawCalls(timeSeconds) {
+    for (const [id, drawCall] of Array.from(this.drawCalls.entries())) {
+      const live = this.gl;
+      if (!live || this.isContextLost) return;
+      try {
+        drawCall(live, timeSeconds);
+      } catch {
+        const callbacks = this.contextCallbacks.get(id);
+        if (callbacks) invokeIsolated(() => callbacks.onLost());
+        this.unregister(id);
+      }
+    }
+  }
+  destroy() {
+    if (this.isDestroyed) return;
+    this.isDestroyed = true;
+    this.stopLoop();
+    if (this.window?.removeEventListener && this.onPointer) {
+      this.window.removeEventListener("pointermove", this.onPointer);
+    }
+    if (this.canvas) {
+      if (this.onContextLost) this.canvas.removeEventListener("webglcontextlost", this.onContextLost);
+      if (this.onContextRestored) this.canvas.removeEventListener("webglcontextrestored", this.onContextRestored);
+      this.canvas.remove();
+      this.canvas = null;
+    }
+    disposeGLResources(this.gl, this.quadBuffer, this.programs);
+    this.gl = null;
+    this.quadBuffer = null;
+    this.isContextLost = false;
+    this.drawCalls.clear();
+    this.contextCallbacks.clear();
+    this.inputReaders.clear();
+    this.programs = {};
+    this.refCount = 0;
+    if (shaderRenderers.get(this.mapKey) === this) shaderRenderers.delete(this.mapKey);
+  }
+};
+var shaderRenderers = /* @__PURE__ */ new WeakMap();
+var fallbackShaderKey = {};
+function getSharedShaderRenderer(env) {
+  const resolved = resolveEnv(null, env);
+  const key = resolved.document ?? resolved.window ?? fallbackShaderKey;
+  let renderer = shaderRenderers.get(key);
+  if (!renderer || renderer.isDestroyed) {
+    renderer = new SharedShaderRenderer(env);
+    shaderRenderers.set(key, renderer);
+  }
+  return renderer;
+}
+function createRendererRef(env) {
+  let current = getSharedShaderRenderer(env);
+  return {
+    get() {
+      if (current.isDestroyed) current = getSharedShaderRenderer(env);
+      return current;
+    }
+  };
+}
+function initTextureHolder(getSource, host) {
+  let tex = null;
+  let owner = null;
+  let generation = -1;
+  const dropIfStale = (renderer) => {
+    if (tex && (owner !== renderer || generation !== renderer.contextGeneration)) tex = null;
+  };
+  return {
+    get() {
+      const renderer = host.renderer;
+      dropIfStale(renderer);
+      if (!tex && !renderer.isContextLost) {
+        const src = getSource();
+        if (src) {
+          tex = renderer.createTexture(src);
+          owner = renderer;
+          generation = renderer.contextGeneration;
+        }
+      }
+      return tex;
+    },
+    peek() {
+      dropIfStale(host.renderer);
+      return tex;
+    },
+    reset() {
+      tex = null;
+    }
+  };
+}
+function createShaderTextureHolders(htmlEl, options, host) {
+  const isImg = (t) => t instanceof HTMLImageElement && t.complete && t.naturalWidth > 0;
+  const texHolder = initTextureHolder(() => isImg(htmlEl) ? htmlEl : null, host);
+  const toHolder = initTextureHolder(() => {
+    const doc = host.renderer.document;
+    if (!options.to || !doc) return null;
+    try {
+      const toEl = doc.querySelector?.(options.to);
+      return isImg(toEl) ? toEl : null;
+    } catch {
+      return null;
+    }
+  }, host);
+  return { texHolder, toHolder };
+}
+function cleanupShaderTextures(texHolder, toHolder, renderer) {
+  const tex = texHolder.peek(), toTex = toHolder.peek();
+  if (tex && renderer.gl) renderer.gl.deleteTexture(tex);
+  if (toTex && toTex !== tex && renderer.gl) renderer.gl.deleteTexture(toTex);
+  texHolder.reset();
+  toHolder.reset();
+  renderer.release();
+}
+function hideBehindRenderer(el, state) {
+  if (state.hiddenByRenderer) return;
+  const style = styleOf(state.ledgers, el);
+  if (!style) return;
+  style.set("opacity", "0");
+  state.hiddenByRenderer = true;
+}
+function restoreInstanceOpacity(el, state) {
+  if (!state.hiddenByRenderer) return;
+  state.hiddenByRenderer = false;
+  const style = styleOf(state.ledgers, el);
+  if (style) style.set("opacity", style.peek("opacity") ?? "");
+}
+var SHADER_TEXTURE_GRACE_MS = 5e3;
+function acquireRenderer(info, held) {
+  if (held && !info.renderer.isDestroyed) return true;
+  const live = info.ref.get();
+  if (!live.acquire()) return false;
+  info.renderer = live;
+  info.tex.reset();
+  info.to.reset();
+  return true;
+}
+function instanceProgress(info) {
+  const authored = info.opt.progress;
+  if (authored !== void 0 && authored >= 0) return authored;
+  return info.opt.scrubsFromScroll ? readElementProgress(info.el) : -1;
+}
+function createShaderDrawCall(info, state, isGenerative, onFailure) {
+  return (_gl, time) => {
+    let drew = false;
+    try {
+      const texture = info.tex.get();
+      drew = (!!texture || isGenerative) && drawElementQuad(info.renderer, info.el, {
+        ...info.opt,
+        texture,
+        toTexture: info.to.get(),
+        time,
+        progress: state.progress,
+        audio: state.audio,
+        geometry: state.geometry
+      });
+    } catch {
+      onFailure();
+      restoreInstanceOpacity(info.el, state);
+      info.renderer.unregister(info.id);
+      return;
+    }
+    if (drew && !isGenerative) hideBehindRenderer(info.el, state);
+    else if (!isGenerative) restoreInstanceOpacity(info.el, state);
+  };
+}
+function createGraceTransition(grace, deactivate, isAcquired) {
+  return () => {
+    deactivate();
+    if (isAcquired()) grace.arm();
+  };
+}
+function createGraceTimer(info, onExpire, isBusy) {
+  let handle = null;
+  let generation = 0;
+  const cancel = () => {
+    generation += 1;
+    const cancelled = handle;
+    handle = null;
+    if (cancelled !== null) info.clearTimer(cancelled);
+  };
+  return {
+    cancel,
+    arm() {
+      cancel();
+      const armedGeneration = generation;
+      const armedHandle = info.setTimer(() => {
+        if (generation !== armedGeneration) return;
+        generation += 1;
+        handle = null;
+        if (!isBusy()) onExpire();
+      }, SHADER_TEXTURE_GRACE_MS);
+      if (generation === armedGeneration) handle = armedHandle;
+    }
+  };
+}
+function createShaderInstance(info) {
+  const state = {
+    // Shared per element with every other writer, advanced or core — see `createAdvancedLedgers`.
+    // A private `createLedgerSet` here captured whatever a CSS effect on the same element had
+    // already written to `opacity` as the author's own value, and handed it back on teardown.
+    ledgers: createAdvancedLedgers(info.el),
+    hiddenByRenderer: false,
+    progress: -1,
+    audio: 0,
+    geometry: null,
+    hostAlpha: 1
+  };
+  let isActive = false, isAcquired = false;
+  const isGenerative = GENERATIVE_MODES.has(info.opt.mode);
+  const readInputs = () => {
+    state.progress = instanceProgress(info);
+    state.audio = info.opt.audioBand ? readAudioBand(info.el, info.opt.audioBand) : 0;
+    const cached = state.hiddenByRenderer ? state.hostAlpha : void 0;
+    state.geometry = measureElementGeometry(info.el, info.renderer.window, isGenerative, cached);
+    if (state.geometry?.hostAlpha !== void 0) state.hostAlpha = state.geometry.hostAlpha;
+  };
+  const restoreState = () => {
+    if (!isActive) return;
+    isActive = false;
+    info.renderer.unregister(info.id);
+    restoreInstanceOpacity(info.el, state);
+  };
+  const releaseResources = () => {
+    if (!isAcquired) return;
+    isAcquired = false;
+    cleanupShaderTextures(info.tex, info.to, info.renderer);
+  };
+  const grace = createGraceTimer(info, releaseResources, () => isActive);
+  const enterGrace = createGraceTransition(grace, () => {
+    isActive = false;
+  }, () => isAcquired);
+  const drawCall = createShaderDrawCall(info, state, isGenerative, enterGrace);
+  const suspend = () => {
+    if (!isActive) return;
+    try {
+      restoreState();
+    } finally {
+      enterGrace();
+    }
+  };
+  return createEffectInstance({
+    continuous: true,
+    activate() {
+      if (isActive) return;
+      if (!acquireRenderer(info, isAcquired)) return;
+      grace.cancel();
+      isAcquired = true;
+      isActive = true;
+      info.renderer.register(info.id, drawCall, {
+        onLost() {
+          info.tex.reset();
+          info.to.reset();
+          restoreInstanceOpacity(info.el, state);
+        },
+        onRestored() {
+        }
+      }, readInputs);
+      info.renderer.startLoop();
+    },
+    // Unregister and un-hide, then hold the textures and the renderer reference for
+    // {@link SHADER_TEXTURE_GRACE_MS} before giving them up.
+    //
+    // This is the grace-timer half of the trade `e49d517` set up and left open, taken deliberately
+    // rather than closed as a tidy-up. That commit chose to retain until `destroy()` because
+    // `release()` tears down the canvas, the context and all six linked programs, so dropping
+    // `refCount` to zero on every hover-out makes the next hover pay a rebuild and six recompiles —
+    // a stall worse, on a hover effect, than holding a texture roughly the size of the decoded
+    // image the browser already has. It named a grace timer as the way to get the memory back
+    // without the stall, and this is it. A give-back inside the window costs nothing: the instance
+    // never let go, so `acquireRenderer` short-circuits and the texture holders still have their
+    // handles. Past it the memory goes back, and a later `activate()` rebuilds against a live
+    // renderer — `RendererRef.get()` re-resolves once the old one reports `isDestroyed`.
+    //
+    // A later audit read the original retention as an oversight and an agent "fixed" it; that was
+    // reverted in `eccb8e5`, because releasing on *every* give-back with no window is the stall,
+    // not the fix. The window is the whole difference.
+    cancel: suspend,
+    finish: suspend,
+    destroy() {
+      restoreState();
+      grace.cancel();
+      releaseResources();
+      state.ledgers.restore();
+    }
+  });
+}
+var STATIC_BAKE_MAX = 640;
+function bakeExtent(rect, canvas, dpr) {
+  if (!Number.isFinite(rect.width) || !Number.isFinite(rect.height)) return null;
+  if (rect.width <= 0 || rect.height <= 0) return null;
+  const longest = Math.max(rect.width, rect.height) * dpr;
+  const budget = Math.min(STATIC_BAKE_MAX, canvas.width, canvas.height);
+  const factor = longest > budget ? budget / longest : dpr;
+  const w = Math.max(1, Math.round(rect.width * factor));
+  const h = Math.max(1, Math.round(rect.height * factor));
+  return w <= canvas.width && h <= canvas.height ? [w, h] : null;
+}
+function readCanvasCorner(canvas, w, h, createCanvas) {
+  const out = createCanvas();
+  const out2d = out?.getContext?.("2d");
+  if (!out || !out2d) return null;
+  out.width = w;
+  out.height = h;
+  try {
+    out2d.drawImage(canvas, 0, 0, w, h, 0, 0, w, h);
+    return out.toDataURL("image/png");
+  } catch {
+    return null;
+  }
+}
+function bakeStaticFrame(renderer, el, options, createCanvas) {
+  const gl = renderer.gl;
+  const canvas = renderer.canvas;
+  if (!gl || !canvas || typeof el.getBoundingClientRect !== "function") return null;
+  const dpr = getScissorEnv(renderer.window).dpr;
+  const extent = bakeExtent(el.getBoundingClientRect(), canvas, dpr);
+  if (!extent) return null;
+  const [w, h] = extent;
+  const box = { left: 0, top: 0, right: w / dpr, bottom: h / dpr };
+  const drew = drawElementQuad(renderer, el, {
+    ...options,
+    time: 0,
+    audio: 0,
+    texture: null,
+    geometry: { border: box, paint: box, clip: box, radii: [0, 0, 0, 0, 0, 0, 0, 0], alpha: 1 }
+  });
+  if (!drew) return null;
+  const url = readCanvasCorner(canvas, w, h, createCanvas);
+  gl.enable(gl.SCISSOR_TEST);
+  gl.scissor(0, canvas.height - h, w, h);
+  gl.clearColor(0, 0, 0, 0);
+  gl.clear(gl.COLOR_BUFFER_BIT);
+  return url;
+}
+function prepareReducedMotion(el, options, ctx) {
+  if (!GENERATIVE_MODES.has(options.mode)) return createInertInstance();
+  const hostDoc = el?.ownerDocument;
+  const env = resolveEnv(ctx, hostDoc ? { document: hostDoc, window: hostDoc.defaultView } : void 0);
+  const renderer = getSharedShaderRenderer(env);
+  if (!renderer.acquire()) return createInertInstance();
+  const ledgers = createAdvancedLedgers(el);
+  nextShaderId += 1;
+  const id = `kui-shader-static-${nextShaderId}`;
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    renderer.unregister(id);
+    renderer.release();
+  };
+  renderer.register(id, () => {
+    const url = bakeStaticFrame(renderer, el, options, env.createCanvas);
+    if (!url) return;
+    const style = styleOf(ledgers, el);
+    if (style) {
+      style.set("background-image", `url("${url}")`);
+      style.set("background-size", "100% 100%");
+      style.set("background-repeat", "no-repeat");
+    }
+    release();
+  });
+  renderer.startLoop();
+  return createInertInstance(() => {
+    release();
+    ledgers.restore();
+  });
+}
+function prepareShaders(el, params, ctx) {
+  const hostDoc = el?.ownerDocument;
+  const resolvedEnv = resolveEnv(ctx, hostDoc ? { document: hostDoc, window: hostDoc.defaultView } : void 0);
+  const options = extractShaderOptions(params, resolvedEnv.createCanvas);
+  if (!SHADER_MODES.includes(options.mode)) return createInertInstance();
+  if (isReducedMotion(ctx)) return prepareReducedMotion(el, options, ctx);
+  const ref = createRendererRef(resolvedEnv);
+  nextShaderId += 1;
+  const id = `kui-shader-instance-${nextShaderId}`;
+  const info = {
+    id,
+    el,
+    opt: options,
+    renderer: ref.get(),
+    ref,
+    setTimer: resolvedEnv.setTimer,
+    clearTimer: resolvedEnv.clearTimer
+  };
+  const holders = createShaderTextureHolders(el, options, info);
+  info.tex = holders.texHolder;
+  info.to = holders.toHolder;
+  return createShaderInstance(info);
+}
+var SHADER_PARAMETERS = {
+  mode: { type: "keyword", default: "displace", keywords: [...SHADER_MODES], cssProperty: "--kui-shader-mode" },
+  strength: { type: "number", default: "0.5", minimum: 0, maximum: 10, cssProperty: "--kui-shader-strength" },
+  speed: { type: "number", default: "1.0", minimum: 0, maximum: 10, cssProperty: "--kui-shader-speed" },
+  frequency: { type: "number", default: "10.0", minimum: 0.1, maximum: 50, cssProperty: "--kui-shader-frequency" },
+  chromatic: { type: "number", default: "0.0", minimum: 0, maximum: 1, cssProperty: "--kui-shader-chromatic" },
+  /**
+   * How far the colour ramp is wrapped back on itself — the shimmer count.
+   *
+   * Ranged 0..8 rather than the 0..1 it carried before `mode: gradient` existed. The old bound was
+   * right for a mix amount and wrong for a wrap count, and it cost nothing to police because **no
+   * fragment program declared `u_iridescence` at all** — the value was extracted and uploaded to a
+   * location that was `null` in all five programs. It reaches a shader for the first time here.
+   */
+  iridescence: { type: "number", default: "0.0", minimum: 0, maximum: 8, cssProperty: "--kui-shader-iridescence" },
+  tint: { type: "color", default: "#ffffff", cssProperty: "--kui-shader-tint" },
+  /*
+   * `color1`/`color2` keep their original meaning — the duotone pair `mode: displace` remaps a
+   * photo through — and `mode: gradient` reads the same two as the first stops of its palette.
+   * `color3`..`color5` extend that palette without touching the duotone contract.
+   *
+   * Five separate `color` parameters rather than one comma-separated list: the attribute grammar
+   * splits effect segments on top-level commas, so a list would have to be quoted, and the only
+   * type that could carry it (`text`) validates nothing — a mistyped stop would silently become
+   * white through `parseColor`'s fallback, which is the worst failure a colour input can have.
+   */
+  color1: { type: "color", default: "", cssProperty: "--kui-shader-color1" },
+  color2: { type: "color", default: "", cssProperty: "--kui-shader-color2" },
+  color3: { type: "color", default: "", cssProperty: "--kui-shader-color3" },
+  color4: { type: "color", default: "", cssProperty: "--kui-shader-color4" },
+  color5: { type: "color", default: "", cssProperty: "--kui-shader-color5" },
+  /*
+   * The generative field's own controls. Every one of these is read by this module's JavaScript and
+   * by no stylesheet, so — as `ParamSpecBase.cssProperty` warns — setting the custom property
+   * directly does nothing at all. Widening one means widening it here.
+   */
+  /** Which pattern. The same seed gives the same image on every load, which is the point of it. */
+  seed: { type: "number", default: "0", minimum: 0, maximum: 9999, integer: true, cssProperty: "--kui-shader-seed" },
+  /** How zoomed the field is. Larger means smaller, more numerous shapes. */
+  scale: { type: "number", default: "1", minimum: 0.05, maximum: 20, cssProperty: "--kui-shader-scale" },
+  /**
+   * How many octaves of detail ride on the base shapes.
+   *
+   * Named `detail` rather than the reference tools' "definition" — the plainer word for the same
+   * idea. Capped at 6, which is `KUI_MAX_OCTAVES` in the shader; a seventh would be accepted here
+   * and silently ignored there.
+   */
+  detail: { type: "number", default: "3", minimum: 1, maximum: 6, integer: true, cssProperty: "--kui-shader-detail" },
+  /** How far a second field distorts the first. The difference between contour rings and liquid. */
+  warp: { type: "number", default: "0", minimum: 0, maximum: 2, cssProperty: "--kui-shader-warp" },
+  /**
+   * How much of `fluid`, `liquid`, `particles` and `morph`'s motion comes from real noise.
+   *
+   * Those four shipped with a single trigonometric term standing in for noise, which bands and
+   * repeats visibly. This crossfades that term into the same `kuiFbm` field `mode: gradient`
+   * generates from — `0` is the shipped picture exactly, `1` is the field on its own, and the
+   * values between are a genuine dial rather than a rounded switch.
+   *
+   * **It is off by default and must stay that way.** Four modes are already in use; turning this
+   * on for them without being asked would restyle live pages. See `FILTER_NOISE_GLSL` in
+   * `glsl.ts` for why it is a parameter of its own rather than `warp` doing double duty.
+   *
+   * Above `0` it is also what gives `seed`, `scale`, `warp` and `detail` a meaning on these four
+   * modes; below it they are read and uploaded but nothing samples them. `mode: displace`'s ripple
+   * is a deliberate radial wave rather than fake noise, and `gradient`/`logo` are already nothing
+   * but the noise core, so all three ignore this.
+   */
+  noise: { type: "number", default: "0", minimum: 0, maximum: 1, cssProperty: "--kui-shader-noise" },
+  /** Posterise the ramp into this many steps. `0` is off, as with `chromatic` and `iridescence`. */
+  bands: { type: "number", default: "0", minimum: 0, maximum: 32, integer: true, cssProperty: "--kui-shader-bands" },
+  /** Film grain amount. */
+  grain: { type: "number", default: "0", minimum: 0, maximum: 1, cssProperty: "--kui-shader-grain" },
+  /**
+   * Hue rotation, as a real angle (`hue: 30deg`, `hue: 0.25turn`).
+   *
+   * An `angle` rather than a normalised scalar, matching `carousel`'s `tilt:` and this repository's
+   * standing rejection of normalised ranges where a CSS unit exists. A bare `hue: 30` is accepted
+   * too — `core/params.ts` normalises it to `30deg`.
+   */
+  hue: { type: "angle", default: "0deg", cssProperty: "--kui-shader-hue" },
+  /**
+   * Which part of `mode: logo`'s host image is the mark. Ignored by every other mode.
+   *
+   * `alpha` for the usual transparent-ground SVG or PNG. `luma` and `luma-invert` are for a format
+   * that has no alpha to read — a JPEG under `alpha` gives an all-opaque stencil and fills the
+   * whole rectangle. `luma` takes the bright pixels as the mark, `luma-invert` the dark ones; both
+   * directions are spelled out because guessing produces a perfect negative of the mark, which
+   * looks deliberate and is exactly wrong.
+   */
+  mask: { type: "keyword", default: "alpha", keywords: ["alpha", "luma", "luma-invert"], cssProperty: "--kui-shader-mask" },
+  /**
+   * How `mode: gradient` and `mode: logo` answer the pointer. Ignored by the five filter modes.
+   *
+   * Being *responsive to the pointer* is the one thing a shader background does that a video of a
+   * shader cannot, and these two modes — the two built to stand in for a video background — were
+   * the only ones in the tier with no pointer response at all. `displace` and `fluid` have read
+   * `u_mouse` since they were written.
+   *
+   * - `stir` — the cursor drags the colour flow around it, like stirring thick paint. It moves the
+   *   field's *sample point*, so on `mode: logo` the mark's edges do not move: `glyphMask()` reads
+   *   the host image at the undistorted coordinate and multiplies the finished colour, which means
+   *   the fill swirls inside a stencil that stays exactly where it was.
+   * - `light` — the cursor is a torch held over the surface. Nothing moves; the colour under the
+   *   pointer is multiplied up, which raises its saturation rather than washing it toward white.
+   * - `both` — the two together. They compose cleanly because they act at different stages, one on
+   *   the coordinate and one on the colour that coordinate produced.
+   *
+   * `none` by default, and `none` means the shader never reads `u_mouse` at all — not that it
+   * reads it and multiplies by zero. Every page already running these modes renders what it always
+   * rendered, byte for byte.
+   *
+   * With no pointer yet — the state of every page on load, every phone, and every screenshot —
+   * `computeMousePos` answers the element's centre, so `light` rests as a centred glow and `stir`
+   * as a centred swirl. Both are compositions someone might have authored on purpose, which is the
+   * bar a resting state has to clear.
+   */
+  hover: { type: "keyword", default: "none", keywords: ["none", "stir", "light", "both"], cssProperty: "--kui-shader-hover" },
+  /**
+   * A colour painted behind the generative field, inside the element's own shape.
+   *
+   * What it is for is `mode: logo`: outside the mark the field has no coverage, so this is the
+   * plate the mark sits on instead of the page showing through.
+   *
+   * On a bare `mode: gradient` it is **invisible**, and that is arithmetic rather than an
+   * oversight — the field is opaque, so there is nothing behind it to see. It becomes visible
+   * there through a `tint` whose alpha is below 1, which is how a field is made to sit *on* a page
+   * colour rather than replace it. Unset by default, and read through the raw parameter string
+   * rather than `parseColor`, whose empty-input fallback is opaque white.
+   */
+  backdrop: { type: "color", default: "", cssProperty: "--kui-shader-backdrop" },
+  /**
+   * The generative field's orientation: the axis it runs along.
+   *
+   * `transform: rotate()`'s convention — clockwise-positive, `0deg` pointing right — because that
+   * is the one an author already has. It turns the field's whole domain, so it is visible at the
+   * library defaults rather than only in company with another parameter, and it is the axis
+   * `motion: drift` travels along. One idea with two consequences, not two behaviours: the field
+   * has an axis, this names it, and `drift` slides along the thing it named.
+   *
+   * An `angle` rather than a normalised scalar, matching `hue` above and this repository's
+   * standing rejection of 0..1 ranges where a CSS unit exists. A bare `angle: 30` is accepted —
+   * `core/params.ts` normalises it to `30deg`.
+   */
+  angle: { type: "angle", default: "0deg", cssProperty: "--kui-shader-angle" },
+  /**
+   * How the generative field moves. Ignored by the five filter modes.
+   *
+   * - `evolve` — the field changes *in place*. Time is the noise function's third axis rather than
+   *   a translation of a 2D field, which is why it reads as the pattern genuinely evolving instead
+   *   of sliding past. See `NOISE_GLSL` in `glsl.ts`.
+   * - `drift` — it also travels along `angle`, at a rate proportional to `scale` so the visual
+   *   speed is the same at any zoom.
+   * - `swirl` — it also turns about the element's centre.
+   *
+   * **`evolve` exists so that the default can be inert.** `drift` would have been the natural
+   * default name, and it is what this parameter's brief asked for — but `drift` is a new look, and
+   * defaulting to it would restyle every page already running `gradient` or `logo` on the next
+   * release. That is the same trap `noise:` above is written around, and the reason `hover:`
+   * defaults to `none`. So the shipped behaviour keeps the default and gets an accurate name, and
+   * the two new ones are opt-in. `drift` and `swirl` add to `evolve` rather than replacing it, so
+   * a travelling field is still changing as it goes rather than one frozen picture towed across
+   * the box.
+   */
+  motion: { type: "keyword", default: "evolve", keywords: ["evolve", "drift", "swirl"], cssProperty: "--kui-shader-motion" },
+  blend: { type: "keyword", default: "normal", keywords: ["normal", "screen", "multiply", "add"], cssProperty: "--kui-shader-blend" },
+  to: { type: "text", default: "", cssProperty: "--kui-shader-to" },
+  /**
+   * A fixed scrub position, 0..1. `-1` is the unauthored sentinel and means "no scrub".
+   *
+   * `--kui-shader-progress`, **not** `--kui-progress`. Every authored parameter reaches
+   * `element.style` as its custom property — `core/compile.ts`'s `buildPlan` runs `resolveParams`
+   * over JS-rendered entries too — so while this pointed at `--kui-progress` an authored
+   * `progress: 0.4` wrote the scroll primitives' own channel onto the element: it raced
+   * `scroll-progress` when the two were composed, and it inherited down to every descendant
+   * shader and pinned timeline underneath. `test/carousel-3d.test.ts` already carries a
+   * regression test that a primitive must not publish `--kui-progress` meaning something else.
+   * Nothing is lost by renaming — this module reads the authored value from the parameter, never
+   * back off the property.
+   */
+  progress: { type: "number", default: "-1", minimum: -1, maximum: 1, cssProperty: "--kui-shader-progress" },
+  /**
+   * Whether this shader is scrubbed by `--kui-progress` — the property `scroll-progress`,
+   * `timeline: pin` and the rest of the scroll family publish.
+   *
+   * Opt-in, and `off` by default, for the same reason `audio:` below is: the value arrives as a
+   * custom property written by some *other* primitive, and `--kui-progress` is an ordinary
+   * inheriting custom property, so a shader that read one unasked changed its own output the
+   * moment an unrelated `scroll-progress` appeared anywhere above it in the tree. That was not a
+   * subtle drift — at the top of a scroll range the published value is `0`, every program
+   * multiplies its effect by it, and the shader rendered an untouched copy of the source image.
+   * Dead, silently, with no way for the author to decline.
+   *
+   * `keyword`, so the list is closed and a typo warns instead of quietly doing nothing.
+   * `--kui-shader-scrub` is a name read by this module's JavaScript and by no stylesheet, so
+   * setting the custom property directly does nothing; the value itself is read from
+   * `--kui-progress`, which is a different contract entirely.
+   */
+  scrub: { type: "keyword", default: "off", keywords: ["off", "scroll"], cssProperty: "--kui-shader-scrub" },
+  /**
+   * Which `audio-source` band drives this shader, if any.
+   *
+   * Opt-in, and `off` by default: the value arrives as a custom property written by some *other*
+   * primitive, so a shader that read one unasked would change its own output the moment an
+   * unrelated `audio-source` appeared anywhere above it in the tree.
+   *
+   * `keyword`, so the list is closed — and `--kui-shader-audio` is a name, read by this module's
+   * JavaScript and by no stylesheet, so setting the custom property in CSS does nothing. The
+   * band values themselves are read from `--kui-audio-*`, which is a different contract entirely
+   * (`audio.ts`'s `AUDIO_BAND_PROPERTIES`).
+   */
+  audio: { type: "keyword", default: "off", keywords: ["off", ...AUDIO_BANDS], cssProperty: "--kui-shader-audio" }
+};
+var SHADERS_PRIMITIVE = {
+  id: "shaders",
+  renderer: "javascript",
+  channels: ["opacity"],
+  parameters: SHADER_PARAMETERS,
+  supportedTimelines: ["time", "view", "scroll"],
+  supportedActivations: ["load", "enter", "hover", "click"],
+  defaultActivation: "load",
+  perfClass: "continuous",
+  reducedMotion: "disable",
+  prepare: prepareShaders
+};
+var SHADERS_PRESETS = [
+  { name: "shaders", primitive: "shaders" },
+  { name: "shader-displace", primitive: "shaders", params: { mode: "displace" } },
+  { name: "shader-fluid", primitive: "shaders", params: { mode: "fluid" } },
+  { name: "fluid-pointer", primitive: "shaders", params: { mode: "fluid" } },
+  { name: "shader-liquid", primitive: "shaders", params: { mode: "liquid" } },
+  { name: "liquid-distort", primitive: "shaders", params: { mode: "liquid" } },
+  { name: "shader-particles", primitive: "shaders", params: { mode: "particles" } },
+  { name: "particle-field", primitive: "shaders", params: { mode: "particles" } },
+  { name: "shader-morph", primitive: "shaders", params: { mode: "morph" } },
+  { name: "image-morph", primitive: "shaders", params: { mode: "morph" } },
+  /*
+   * The generative family. One fragment program, four sets of defaults — a preset here is a
+   * starting point in the same parameter space, not a separate shader.
+   *
+   * These are the only presets in the catalog that work on an element with no image in it, and
+   * their honest surface is still an element nothing overlaps — but for a different reason than it
+   * used to be. The shared canvas now defaults to `z-index: 1`, so a positioned headline laid over
+   * one of these paints on top of it, where before the headline vanished behind it. Better, and
+   * still not composition: `border-radius`, ancestor clipping and ancestor opacity are reproduced
+   * in the fragment shader, but the replica's place in the stacking order is the *canvas's*, not
+   * the element's. `--kui-shader-z` moves that one canvas and every replica on it together. See
+   * `docs/advanced-modules.md`.
+   */
+  { name: "shader-gradient", primitive: "shaders", params: { mode: "gradient" } },
+  { name: "gradient-liquid", primitive: "shaders", params: { mode: "gradient", warp: "1.1", detail: "4", speed: "0.4" } },
+  { name: "gradient-bands", primitive: "shaders", params: { mode: "gradient", bands: "8", warp: "0.6", speed: "0.3" } },
+  // No palette on purpose: with fewer than two colours set the ramp falls back to its default pair,
+  // and the sheen comes from wrapping it rather than from the stops themselves.
+  { name: "gradient-holo", primitive: "shaders", params: { mode: "gradient", iridescence: "3", chromatic: "0.5", warp: "0.4", speed: "0.5" } },
+  /*
+   * `logo` is the one generative mode with no stacking caveat at all. It replaces an `<img>`
+   * exactly as the five filters do — the host image is the stencil, not the picture — so a mark
+   * painting over the page is what an author wants rather than the limitation above.
+   *
+   * `<img src="mark.svg" data-kui="shader-logo">` and nothing else: the asset already carries the
+   * shape, `object-fit` already decides where it sits, and the element is already the right size.
+   */
+  { name: "shader-logo", primitive: "shaders", params: { mode: "logo" } },
+  { name: "logo-gradient", primitive: "shaders", params: { mode: "logo", warp: "0.8", detail: "4", scale: "1.6", speed: "0.4" } }
+];
+function registerShaders(target) {
+  return registerInto(target, SHADERS_PRIMITIVE, SHADERS_PRESETS, "Shaders");
+}
+
+// src/advanced/scenes.ts
+var NUM = String.raw`-?(?:\d+(?:\.\d+)?|\.\d+)`;
+var FROM_REGEX = new RegExp(String.raw`\bfrom:(${NUM})`);
+var TO_REGEX = new RegExp(String.raw`\bto:(${NUM})`);
+var OPACITY_REGEX = /\bopacity:([0-9.]+)->([0-9.]+)/;
+var X_REGEX = /\bx:([+-]?[0-9.]+[a-z%]*)->([+-]?[0-9.]+[a-z%]*)/i;
+var Y_REGEX = /\by:([+-]?[0-9.]+[a-z%]*)->([+-]?[0-9.]+[a-z%]*)/i;
+var SCALE_REGEX = /\bscale:([0-9.]+)->([0-9.]+)/;
+function parseWindow(kui) {
+  return [readEnd(FROM_REGEX, kui, 0), readEnd(TO_REGEX, kui, 1)];
+}
+function readEnd(pattern, kui, fallback) {
+  const match = pattern.exec(kui);
+  if (!match) return fallback;
+  const value = parseFloat(match[1]);
+  return value >= 0 && value <= 1 ? value : fallback;
+}
+function extractUnit(str) {
+  let i = str.length - 1;
+  while (i >= 0 && (str[i] >= "a" && str[i] <= "z" || str[i] >= "A" && str[i] <= "Z" || str[i] === "%")) {
+    i--;
+  }
+  return str.slice(i + 1);
+}
+function parseTransitionValue(str) {
+  if (!str) return null;
+  const arrowIdx = str.indexOf("->");
+  if (arrowIdx === -1) return null;
+  const fromStr = str.slice(0, arrowIdx).trim();
+  const toStr = str.slice(arrowIdx + 2).trim();
+  const fromNum = parseFloat(fromStr);
+  const toNum = parseFloat(toStr);
+  if (Number.isNaN(fromNum) || Number.isNaN(toNum)) return null;
+  const unit = extractUnit(fromStr) || extractUnit(toStr);
+  return { from: fromNum, to: toNum, unit };
+}
+function parseChildStep(child) {
+  const kui = child?.getAttribute ? child.getAttribute("data-kui") || "" : "";
+  const range = parseWindow(kui);
+  const opMatch = OPACITY_REGEX.exec(kui);
+  const opacity = opMatch ? parseTransitionValue(`${opMatch[1]}->${opMatch[2]}`) : null;
+  const xMatch = X_REGEX.exec(kui);
+  const x = xMatch ? parseTransitionValue(`${xMatch[1]}->${xMatch[2]}`) : null;
+  const yMatch = Y_REGEX.exec(kui);
+  const y = yMatch ? parseTransitionValue(`${yMatch[1]}->${yMatch[2]}`) : null;
+  const scMatch = SCALE_REGEX.exec(kui);
+  const scale = scMatch ? parseTransitionValue(`${scMatch[1]}->${scMatch[2]}`) : null;
+  return { range, opacity, x, y, scale };
+}
+function buildStepTransforms(cfg, localT) {
+  const transforms = [];
+  if (cfg.x) {
+    transforms.push(`translateX(${lerp(cfg.x.from, cfg.x.to, localT)}${cfg.x.unit})`);
+  }
+  if (cfg.y) {
+    transforms.push(`translateY(${lerp(cfg.y.from, cfg.y.to, localT)}${cfg.y.unit})`);
+  }
+  if (cfg.scale) {
+    transforms.push(`scale(${lerp(cfg.scale.from, cfg.scale.to, localT)})`);
+  }
+  return transforms.join(" ");
+}
+var FALLBACK_VIEWPORT_HEIGHT = 800;
+var SceneController = class {
+  container;
+  options;
+  env;
+  window;
+  raf;
+  caf;
+  steps = [];
+  progress = 0;
+  rafId = null;
+  isListening = false;
+  timeStart = 0;
+  /**
+   * One ledger per step element, each opened at that step's first write and shared with every
+   * other controller writing to the same element — see `createAdvancedLedgers`.
+   *
+   * Steps are collected during `prepare`, which can be a long way before the scene ever scrolls
+   * into view. Recording opacity and transform *there* meant destroy restored the markup as it
+   * looked at preparation time, discarding anything the author wrote in between.
+   *
+   * Sharing is also what keeps two *legitimate* owners of one element honest. A nested `scene` is
+   * no longer one of them — `prepareScene` scopes its scan with {@link ownedDescendants}, so an
+   * outer scene stops at an inner one instead of claiming its steps — but an element authored as
+   * both a `scene-step` and a `camera-layer` still has two, because those are different kinds of
+   * host, and so does any controller constructed directly rather than through `prepare`.
+   */
+  ledgers;
+  constructor(container, options = {}, env = {}) {
+    this.container = container;
+    this.options = options;
+    this.env = env;
+    const resolved = resolveEnv(null, env);
+    this.window = resolved.window;
+    this.raf = resolved.raf;
+    this.caf = resolved.caf;
+    this.ledgers = createAdvancedLedgers(container);
+    this.onScroll = this.onScroll.bind(this);
+  }
+  addStep(element, config) {
+    this.steps.push({ element, config });
+  }
+  start(onComplete) {
+    if (this.isListening) return;
+    if (!this.window && this.options.progress !== "time") return;
+    this.isListening = true;
+    if (this.options.progress === "time") {
+      this.startTimeLoop(onComplete);
+    } else {
+      if (this.window?.addEventListener) {
+        this.window.addEventListener("scroll", this.onScroll, { passive: true });
+        this.window.addEventListener("resize", this.onScroll, { passive: true });
+      }
+      this.onScroll();
+    }
+  }
+  stop() {
+    if (!this.isListening) return;
+    if (this.window?.removeEventListener) {
+      this.window.removeEventListener("scroll", this.onScroll);
+      this.window.removeEventListener("resize", this.onScroll);
+    }
+    if (this.rafId) this.caf(this.rafId);
+    this.rafId = null;
+    this.isListening = false;
+  }
+  startTimeLoop(onComplete) {
+    const duration = this.options.duration || 1e3;
+    const now = () => this.window?.performance?.now ? this.window.performance.now() : Date.now();
+    this.timeStart = now();
+    const tick = () => {
+      if (!this.isListening) {
+        this.rafId = null;
+        return;
+      }
+      const elapsed = now() - this.timeStart;
+      this.progress = clamp(elapsed / duration, 0, 1);
+      this.updateAll();
+      if (this.progress < 1) {
+        this.rafId = this.raf(tick);
+        return;
+      }
+      this.rafId = null;
+      this.isListening = false;
+      if (onComplete) onComplete();
+    };
+    this.rafId = this.raf(tick);
+  }
+  onScroll() {
+    if (this.rafId) return;
+    this.rafId = this.raf(() => {
+      this.rafId = null;
+      this.calculateProgress();
+      this.updateAll();
+    });
+  }
+  calculateProgress() {
+    if (!this.container?.getBoundingClientRect) {
+      this.progress = 0;
+      return;
+    }
+    const winHeight = this.window?.innerHeight ?? FALLBACK_VIEWPORT_HEIGHT;
+    const rect = this.container.getBoundingClientRect();
+    const totalDist = winHeight + rect.height;
+    const currentDist = winHeight - rect.top;
+    this.progress = totalDist > 0 ? clamp(currentDist / totalDist, 0, 1) : 0;
+  }
+  updateAll() {
+    for (const step of this.steps) {
+      this.updateElement(step.element, step.config, this.progress);
+    }
+  }
+  updateElement(el, cfg, globalProgress) {
+    const [start, end] = cfg.range;
+    if (start >= end) return;
+    const style = styleOf(this.ledgers, el);
+    if (!style) return;
+    const localT = clamp((globalProgress - start) / (end - start), 0, 1);
+    if (cfg.opacity) {
+      style.set("opacity", String(lerp(cfg.opacity.from, cfg.opacity.to, localT)));
+    }
+    const t = buildStepTransforms(cfg, localT);
+    if (t) style.set("transform", t);
+  }
+  /** `try`/`finally` for the reason `camera-3d.ts`'s `destroy()` documents. */
+  destroy() {
+    try {
+      this.stop();
+    } finally {
+      this.ledgers.restore();
+      this.steps = [];
+    }
+  }
+};
+function prepareScene(el, params, ctx) {
+  const resolvedEnv = resolveEnv(ctx);
+  const authoredProgress = params.text ? params.text("progress", "scroll") : "scroll";
+  const progressMode = authoredProgress === "time" ? "time" : "scroll";
+  const duration = clamp(params.num ? params.num("duration", 1e3) : 1e3, 100, 6e4);
+  const htmlEl = el;
+  const controller = new SceneController(
+    htmlEl,
+    { progress: progressMode, duration },
+    resolvedEnv
+  );
+  const childSteps = ownedDescendants(htmlEl, "scene", "scene-step");
+  for (const child of childSteps) {
+    const config = parseChildStep(child);
+    const [start, end] = config.range;
+    if (start >= end) {
+      ctx?.warn(
+        `scene-step from:${start} to:${end} is an empty window \u2014 from: must be less than to:, so this step never animates`
+      );
+    }
+    controller.addStep(child, config);
+  }
+  if (isReducedMotion(ctx)) {
+    controller.progress = 1;
+    controller.updateAll();
+    return createInertInstance(() => controller.destroy());
+  }
+  const inst = createEffectInstance({
+    continuous: progressMode === "scroll",
+    activate() {
+      if (progressMode === "time") {
+        controller.start(() => inst.finish());
+      } else {
+        controller.start();
+      }
+    },
+    cancel() {
+      controller.stop();
+    },
+    finish() {
+      controller.progress = 1;
+      controller.updateAll();
+      controller.stop();
+    },
+    destroy() {
+      controller.destroy();
+    }
+  });
+  return inst;
+}
+var SCENE_PARAMETERS = {
+  progress: {
+    type: "keyword",
+    default: "scroll",
+    keywords: ["scroll", "time"],
+    cssProperty: "--kui-scene-progress"
+  },
+  duration: {
+    type: "number",
+    default: "1000",
+    minimum: 100,
+    maximum: 6e4,
+    cssProperty: "--kui-scene-duration"
+  }
+};
+var SCENE_STEP_PARAMETERS = {
+  from: { type: "number", default: "0", minimum: 0, maximum: 1, cssProperty: "--kui-scene-step-from" },
+  to: { type: "number", default: "1", minimum: 0, maximum: 1, cssProperty: "--kui-scene-step-to" },
+  opacity: { type: "text", default: "", cssProperty: "--kui-scene-step-opacity" },
+  x: { type: "text", default: "", cssProperty: "--kui-scene-step-x" },
+  y: { type: "text", default: "", cssProperty: "--kui-scene-step-y" },
+  scale: { type: "text", default: "", cssProperty: "--kui-scene-step-scale" }
+};
+function prepareSceneStep() {
+  return createInertInstance();
+}
+var SCENE_PRIMITIVES = [
+  {
+    id: "scene",
+    renderer: "javascript",
+    channels: ["opacity", "skew"],
+    parameters: SCENE_PARAMETERS,
+    supportedTimelines: ["scroll", "time"],
+    supportedActivations: ["load", "enter"],
+    defaultActivation: "load",
+    perfClass: "continuous",
+    // Still `disable`: it is what stops `openGate` activating the instance, which is precisely
+    // what makes the held last keyframe in `prepareScene` the only thing that runs.
+    reducedMotion: "disable",
+    prepare: prepareScene
+  },
+  {
+    id: "scene-step",
+    renderer: "javascript",
+    // The same pair the parent declares, and for the same reason: `updateElement` writes `opacity`
+    // and the `transform` *shorthand*, and per `core/types.ts`'s `CHANNEL` note anything writing
+    // the shorthand is on the `skew` channel whatever the transform is for. Not `translate`/`scale`
+    // — those are the independent transform properties, which this module never writes.
+    channels: ["opacity", "skew"],
+    parameters: SCENE_STEP_PARAMETERS,
+    supportedTimelines: ["scroll", "time"],
+    supportedActivations: ["load", "enter"],
+    defaultActivation: "load",
+    perfClass: "dom-transform",
+    reducedMotion: "disable",
+    prepare: prepareSceneStep
+  }
+];
+var SCENE_PRESETS = [
+  { name: "scene", primitive: "scene" },
+  { name: "scene-step", primitive: "scene-step" }
+];
+function registerScenes(target) {
+  return registerInto(target, SCENE_PRIMITIVES, SCENE_PRESETS, "Scenes");
+}
+
+// src/advanced/camera-3d.ts
+var AUDIO_PUSH_RATIO = 0.1;
+function parseDepth(str) {
+  if (!str) return 0;
+  const num = parseFloat(str);
+  return Number.isNaN(num) ? 0 : num;
+}
+function computeLayerTransform(depthZ, cameraZ, tiltX = 0, tiltY = 0) {
+  const zOffset = depthZ + cameraZ * 0.5;
+  if (tiltX || tiltY) {
+    return `translate3d(0, 0, ${zOffset}px) rotateX(${tiltX}deg) rotateY(${tiltY}deg)`;
+  }
+  return `translate3d(0, 0, ${zOffset}px)`;
+}
+var CameraController = class {
+  container;
+  options;
+  env;
+  window;
+  raf;
+  caf;
+  layers = [];
+  cameraZ = 0;
+  mouse = { x: 0, y: 0, targetX: 0, targetY: 0 };
+  rafId = null;
+  scrollRafId = null;
+  audioRafId = null;
+  /** Last value read for the selected band, 0..1. Stays 0 for a scene with no `audio:`. */
+  audioLevel = 0;
+  isListening = false;
+  /**
+   * Container and every depth layer, each ledger opened at that element's first write and shared
+   * with every other controller writing to the same element — see `createAdvancedLedgers`.
+   *
+   * This used to say "an inner scene claims the outer scene's layers", which is backwards: an
+   * inner `querySelectorAll` only ever sees its own descendants, so it is the **outer** scene that
+   * over-reaches into the inner one. `prepareCameraScene` now scopes the scan with
+   * {@link ownedDescendants}, so an outer camera stops at a nested `camera-scene` and the two no
+   * longer write one layer's `transform` on alternate frames.
+   *
+   * Sharing still matters after that fix, and not only for the controllers built directly by the
+   * suites: a `camera-layer` that is *also* a `scene-step` has two owners by design, because they
+   * are different kinds of host. The ledger is what keeps that case honest.
+   */
+  ledgers;
+  constructor(container, options = {}, env = {}) {
+    this.container = container;
+    this.options = options;
+    this.env = env;
+    const resolved = resolveEnv(null, env);
+    this.window = resolved.window;
+    this.raf = resolved.raf;
+    this.caf = resolved.caf;
+    this.ledgers = createAdvancedLedgers(container);
+    this.onScroll = this.onScroll.bind(this);
+    this.onMouseMove = this.onMouseMove.bind(this);
+  }
+  addLayer(element, depthZ) {
+    this.layers.push({ element, depthZ });
+  }
+  applyLayer3D() {
+    for (const layer of this.layers) {
+      styleOf(this.ledgers, layer.element)?.set("transform-style", "preserve-3d");
+    }
+  }
+  bindEvents() {
+    if (this.window?.addEventListener) {
+      this.window.addEventListener("scroll", this.onScroll, { passive: true });
+      if (this.options.mouseTilt) {
+        this.window.addEventListener("pointermove", this.onMouseMove, { passive: true });
+      }
+    }
+  }
+  /**
+   * The 3D space itself: the container's perspective and every layer's `preserve-3d`.
+   *
+   * Separated from {@link start} because the reduced-motion path needs exactly this and none of
+   * the listeners or loops below it — see {@link renderStatic}.
+   */
+  applyStage() {
+    const stage = styleOf(this.ledgers, this.container);
+    stage?.set("perspective", `${this.options.depth || 1e3}px`);
+    stage?.set("transform-style", "preserve-3d");
+    this.applyLayer3D();
+  }
+  /**
+   * The scene composed once, with the camera parked where its travel begins.
+   *
+   * What a visitor who asked for reduced motion gets instead of nothing, following the decision
+   * `shaders.ts` records: a static frame where one genuinely exists. Here it does, and it is most
+   * of the effect — `depth` and each layer's `z:` *are* the composition, and the scroll only moves
+   * a camera through an arrangement the author already described. One `render()` at `cameraZ = 0`
+   * puts every layer at its authored depth through the container's perspective, so the scene keeps
+   * its real scale hierarchy and simply does not travel. Without it the layers are written nothing
+   * at all and the whole scene collapses flat — the same bug `start()`'s own `render()` call fixed
+   * for the live path.
+   *
+   * Deliberately *not* the scene's end state, which is where the animator leaves a CSS effect under
+   * this policy (`openGate`, `core/animator.ts`). "The end" here is `cameraZ = depth`, i.e. the
+   * camera pushed all the way through: a layer then sits at `z = depthZ + depth / 2`, which against
+   * a `perspective` of `depth` is a 2x blow-up at `z:0` and 10x at `z:400px` of a 1000px scene, with
+   * nearer layers passing the viewer entirely. An end state nobody can see is not a still frame.
+   *
+   * Runs during `prepare`, because it has to — under reduced motion `openGate` marks the element
+   * finished and never activates any instance. See `prepareReducedMotion` in `shaders.ts`.
+   */
+  renderStatic() {
+    if (!this.container) return;
+    this.applyStage();
+    this.render();
+  }
+  start() {
+    if (this.isListening || !this.container) return;
+    this.applyStage();
+    this.bindEvents();
+    this.isListening = true;
+    this.updateScroll();
+    this.readAudio();
+    this.render();
+    this.startAudioLoop();
+    this.startLoop();
+  }
+  stop() {
+    if (!this.isListening) return;
+    if (this.window?.removeEventListener) {
+      this.window.removeEventListener("scroll", this.onScroll);
+      this.window.removeEventListener("pointermove", this.onMouseMove);
+    }
+    if (this.rafId) this.caf(this.rafId);
+    this.rafId = null;
+    if (this.scrollRafId) this.caf(this.scrollRafId);
+    this.scrollRafId = null;
+    if (this.audioRafId) this.caf(this.audioRafId);
+    this.audioRafId = null;
+    this.isListening = false;
+  }
+  updateScroll() {
+    if (!this.container?.getBoundingClientRect) return;
+    const winHeight = this.window?.innerHeight ?? 800;
+    const rect = this.container.getBoundingClientRect();
+    const travel = winHeight + rect.height;
+    const dist = winHeight - rect.top;
+    const progress = travel > 0 ? clamp(dist / travel, 0, 1) : 0;
+    this.cameraZ = progress * (this.options.depth || 1e3);
+  }
+  /** The selected band's current value, or 0 for a scene that asked for none. */
+  readAudio() {
+    this.audioLevel = this.options.audio ? readAudioBand(this.container, this.options.audio) : 0;
+  }
+  /**
+   * The one frame loop an audio-driven scene runs, doing every read before every write.
+   *
+   * An audio band changes on its own, without a scroll or a pointer move to hang a frame on, so
+   * this scene needs a loop of its own — and then it needs to be the *only* loop, which is why
+   * `onScroll` and `startLoop` both stand down while it is running. Three callbacks each reading
+   * geometry (`getBoundingClientRect`) or style (`readAudioBand`'s computed fallback) and then
+   * writing transforms would force a layout or style recalculation per callback per frame; one
+   * pass that reads scroll position, reads the band, steps the pointer spring and only then
+   * renders forces at most one.
+   */
+  startAudioLoop() {
+    if (this.audioRafId || !this.options.audio) return;
+    const tick = () => {
+      this.updateScroll();
+      this.readAudio();
+      if (this.options.mouseTilt) this.stepMouse();
+      this.render();
+      this.audioRafId = this.isListening ? this.raf(tick) : null;
+    };
+    this.audioRafId = this.raf(tick);
+  }
+  onScroll() {
+    if (this.scrollRafId || this.audioRafId) return;
+    const id = this.raf(() => {
+      this.scrollRafId = null;
+      this.updateScroll();
+      this.render();
+    });
+    if (id == null) {
+      this.updateScroll();
+      this.render();
+    } else {
+      this.scrollRafId = id;
+    }
+  }
+  onMouseMove(e) {
+    if (!this.options.mouseTilt) return;
+    const winWidth = this.window?.innerWidth ?? 1e3;
+    const winHeight = this.window?.innerHeight ?? 800;
+    const cx = winWidth * 0.5;
+    const cy = winHeight * 0.5;
+    this.mouse.targetX = (e.clientX - cx) / cx;
+    this.mouse.targetY = (e.clientY - cy) / cy;
+    this.startLoop();
+  }
+  stepMouse() {
+    const dx = this.mouse.targetX - this.mouse.x;
+    const dy = this.mouse.targetY - this.mouse.y;
+    this.mouse.x += dx * 0.08;
+    this.mouse.y += dy * 0.08;
+    if (Math.abs(dx) < 1e-3 && Math.abs(dy) < 1e-3) {
+      this.mouse.x = this.mouse.targetX;
+      this.mouse.y = this.mouse.targetY;
+      return false;
+    }
+    return true;
+  }
+  startLoop() {
+    if (this.rafId || this.audioRafId || !this.options.mouseTilt) return;
+    const tick = () => {
+      const moving = this.stepMouse();
+      this.render();
+      if (this.isListening && moving) {
+        this.rafId = this.raf(tick);
+      } else {
+        this.rafId = null;
+      }
+    };
+    this.rafId = this.raf(tick);
+  }
+  /**
+   * Tilt the whole stage toward the pointer.
+   *
+   * The author's own transform is read here, at the first frame that overwrites it, rather than
+   * when the effect activated. Between those two moments sits at least one frame in which the
+   * page's own code can write a transform, and a capture taken at activation would both overwrite
+   * that write and hand the older value back on destroy as if it had never happened.
+   *
+   * `claim()` is what makes that true without a private snapshot field: it remembers `transform`'s
+   * current value the first time this runs and is a no-op on every call after, so `peek()` always
+   * answers with whatever was there just before this method's first write — the ledger already
+   * tracks that for `restore()`; `peek()` is just asking it without writing.
+   */
+  renderStageTilt(tiltX, tiltY) {
+    const stage = styleOf(this.ledgers, this.container);
+    if (!stage) return;
+    stage.claim("transform");
+    if (tiltX !== 0 || tiltY !== 0) {
+      stage.set("transform", `rotateX(${tiltX.toFixed(2)}deg) rotateY(${tiltY.toFixed(2)}deg)`);
+      return;
+    }
+    this.restStageTransform(stage);
+  }
+  /**
+   * Hand `transform` back when the tilt settles at exactly zero.
+   *
+   * `peek()` reports only what `restore()` would put back, which is the **inline** capture and
+   * nothing else — by design (`owned-styles.ts`, and `test/owned-styles.test.ts` asserts it). So
+   * `peek() || 'rotateX(0deg) rotateY(0deg)'` was right only for an author who had written the
+   * transform inline. For the ordinary case — `.hero { transform: translateY(-20px) }` in a
+   * stylesheet — `peek()` answers `''` and the fallback wrote a *fabricated* identity inline,
+   * which outranks the class and switches the author's own transform off the moment the effect
+   * activates. `start()` renders immediately with the pointer at the synthetic centre, so that is
+   * activation, not some edge case.
+   *
+   * Removing the declaration instead is what actually lands on "the author's own transform": their
+   * inline value if they had one, their stylesheet's if they did not, and nothing at all if
+   * neither. The `removeProperty` is not a ledger bypass — `claim()` above has already recorded
+   * the property, `peek()` answering `''` *is* the ledger saying it found no inline declaration
+   * here, and removal is precisely what its own `restore()` does for that capture.
+   *
+   * Not fixed here: an inline `transform: scale(1.2) !important` comes back through `peek()`
+   * without its priority, so while the effect is live at rest a competing `!important` rule the
+   * author had deliberately beaten wins again. `restore()` puts the priority back, so it ends at
+   * the right value. Closing that needs a per-property give-back on `StyleLedger` (core).
+   *
+   * @complexity O(1).
+   */
+  restStageTransform(stage) {
+    const authored = stage.peek("transform");
+    if (authored) {
+      stage.set("transform", authored);
+      return;
+    }
+    this.container.style.removeProperty("transform");
+  }
+  render() {
+    if (this.options.mouseTilt) {
+      this.renderStageTilt(this.mouse.y * -8, this.mouse.x * 8);
+    }
+    const cameraZ = this.cameraZ + this.audioLevel * (this.options.depth || 1e3) * AUDIO_PUSH_RATIO;
+    for (const layer of this.layers) {
+      styleOf(this.ledgers, layer.element)?.set(
+        "transform",
+        computeLayerTransform(layer.depthZ, cameraZ)
+      );
+    }
+  }
+  /**
+   * `try`/`finally` because the restore must not be hostage to the listener teardown.
+   *
+   * The animator swallows a throwing instance teardown (`runQuietly(() => instance.destroy())`),
+   * and every element this controller reached on its own — the layers — is in no ledger core will
+   * ever restore. A `removeEventListener` the page has replaced, or a window torn down under a
+   * detached document, would otherwise leave `transform` on each layer permanently.
+   */
+  destroy() {
+    try {
+      this.stop();
+    } finally {
+      this.ledgers.restore();
+      this.layers = [];
+    }
+  }
+};
+function parseMouseTilt(params) {
+  if (params.is) return params.is("mouse-tilt", "on");
+  if (params.text) return params.text("mouse-tilt", "on") === "on";
+  return true;
+}
+function prepareCameraScene(el, params, ctx) {
+  const resolvedEnv = resolveEnv(ctx);
+  const depth = clamp(params.num ? params.num("depth", 1e3) : 1e3, 100, 5e3);
+  const mouseTilt = parseMouseTilt(params);
+  const audio = parseAudioBand(params.text ? params.text("audio", "off") : "off");
+  const reduced = isReducedMotion(ctx);
+  const options = reduced ? { depth, mouseTilt: false, audio: null } : { depth, mouseTilt, audio };
+  const htmlEl = el;
+  const controller = new CameraController(htmlEl, options, resolvedEnv);
+  const layerEls = ownedDescendants(htmlEl, "camera-scene", "camera-layer");
+  for (const layer of layerEls) {
+    const kui = layer.getAttribute("data-kui") || "";
+    const zMatch = /z:([+-]?[0-9.]+)(?:px)?/.exec(kui);
+    const depthZ = zMatch ? parseDepth(zMatch[1]) : 0;
+    controller.addLayer(layer, depthZ);
+  }
+  if (reduced) {
+    controller.renderStatic();
+    return createInertInstance(() => controller.destroy());
+  }
+  return createEffectInstance({
+    continuous: true,
+    activate() {
+      controller.start();
+    },
+    cancel() {
+      controller.stop();
+    },
+    finish() {
+      controller.stop();
+    },
+    destroy() {
+      controller.destroy();
+    }
+  });
+}
+var CAMERA_PARAMETERS = {
+  depth: { type: "number", default: "1000", minimum: 100, maximum: 5e3, cssProperty: "--kui-camera-depth" },
+  "mouse-tilt": {
+    type: "keyword",
+    default: "on",
+    keywords: ["on", "off"],
+    cssProperty: "--kui-camera-tilt"
+  },
+  /**
+   * Which `audio-source` band pushes the camera forward, if any.
+   *
+   * Same name, same words and the same `off` default as the `shaders` primitive's: one spelling
+   * for "follow this band" across this directory rather than a second word per consumer. Opt-in
+   * for the reason that one is — the value is written by another primitive, and a scene that read
+   * it unasked would start pulsing the moment an unrelated `audio-source` appeared above it.
+   *
+   * Turning it on also changes *how* the scene renders: see `startAudioLoop`, which becomes the
+   * scene's only frame loop.
+   */
+  audio: {
+    type: "keyword",
+    default: "off",
+    keywords: ["off", ...AUDIO_BANDS],
+    cssProperty: "--kui-camera-audio"
+  }
+};
+var CAMERA_LAYER_PARAMETERS = {
+  z: { type: "number", default: "0", minimum: -5e3, maximum: 5e3, cssProperty: "--kui-camera-layer-z" }
+};
+function prepareCameraLayer() {
+  return createInertInstance();
+}
+var CAMERA_PRIMITIVES = [
+  {
+    id: "camera-scene",
+    renderer: "javascript",
+    channels: ["skew", "perspective", "transform-style"],
+    parameters: CAMERA_PARAMETERS,
+    supportedTimelines: ["scroll", "time"],
+    supportedActivations: ["load", "enter"],
+    defaultActivation: "load",
+    perfClass: "continuous",
+    // Still `disable`, and it has to be: it is what makes `openGate` refuse to activate this
+    // instance, and the still frame is baked in `prepare` precisely because nothing else runs.
+    // `shaders.ts` keeps its own for the same reason.
+    reducedMotion: "disable",
+    prepare: prepareCameraScene
+  },
+  {
+    id: "camera-layer",
+    renderer: "javascript",
+    channels: ["translate", "rotate", "transform-style"],
+    parameters: CAMERA_LAYER_PARAMETERS,
+    supportedTimelines: ["scroll", "time"],
+    supportedActivations: ["load", "enter"],
+    defaultActivation: "load",
+    perfClass: "dom-transform",
+    // Nothing to reconsider here when `camera-scene` gained a still frame: this primitive animates
+    // nothing in either mode. The scene above writes every layer's transform, including the static
+    // one, so a layer is already covered by whatever its scene decided.
+    reducedMotion: "disable",
+    prepare: prepareCameraLayer
+  }
+];
+var CAMERA_PRESETS = [
+  { name: "camera-scene", primitive: "camera-scene" },
+  { name: "camera-layer", primitive: "camera-layer" }
+];
+function registerCamera(target) {
+  return registerInto(target, CAMERA_PRIMITIVES, CAMERA_PRESETS, "Camera");
+}
+
+// src/advanced/particles.ts
+function stepParticle(p, mouseX, mouseY, repelRadius) {
+  const dx = mouseX - p.x;
+  const dy = mouseY - p.y;
+  const dist = Math.hypot(dx, dy);
+  if (dist < repelRadius && dist > 0) {
+    const force = (repelRadius - dist) / repelRadius;
+    p.vx -= dx / dist * force * 5;
+    p.vy -= dy / dist * force * 5;
+  }
+  const ox = p.originX - p.x;
+  const oy = p.originY - p.y;
+  p.vx += ox * 0.05;
+  p.vy += oy * 0.05;
+  p.vx *= 0.88;
+  p.vy *= 0.88;
+  p.x += p.vx;
+  p.y += p.vy;
+}
+function spawnParticlesGrid(count, color, width, height) {
+  const cols = Math.max(1, Math.round(Math.sqrt(count * (width / Math.max(height, 1)))));
+  const rows = Math.max(1, Math.ceil(count / cols));
+  const particles = [];
+  for (let i = 0; i < count; i++) {
+    const originX = i % cols * (width / cols) + width / (cols * 2);
+    const originY = Math.floor(i / cols) * (height / rows) + height / (rows * 2);
+    particles.push({
+      x: originX,
+      y: originY,
+      originX,
+      originY,
+      vx: 0,
+      vy: 0,
+      radius: i % 3 + 1.5,
+      color
+    });
+  }
+  return particles;
+}
+function isParticleMoving(p) {
+  if (Math.abs(p.vx) > 0.02 || Math.abs(p.vy) > 0.02) return true;
+  return Math.abs(p.x - p.originX) > 0.5 || Math.abs(p.y - p.originY) > 0.5;
+}
+var ParticleEmitter = class {
+  element;
+  options;
+  env;
+  window;
+  document;
+  createCanvas;
+  raf;
+  caf;
+  canvas = null;
+  ctx = null;
+  particles = [];
+  mouse = { x: -999, y: -999 };
+  rafId = null;
+  isListening = false;
+  dpr = 1;
+  /**
+   * The host's `position`, and what it was before this module needed a positioning context.
+   *
+   * The hand-rolled pair this replaced read back only the value, never the priority, so an
+   * author's `position: relative !important` came back as a plain declaration on teardown. The
+   * canvas's own `cssText` needs no ledger — that element is created and removed here.
+   *
+   * Shared with every other controller writing to this element — see `createAdvancedLedgers`.
+   */
+  ledgers;
+  constructor(element, options = {}, env = {}) {
+    this.element = element;
+    this.options = options;
+    this.env = env;
+    this.ledgers = createAdvancedLedgers(element);
+    const resolved = resolveEnv(null, env);
+    this.window = resolved.window;
+    this.document = resolved.document;
+    this.createCanvas = resolved.createCanvas;
+    this.raf = resolved.raf;
+    this.caf = resolved.caf;
+    this.onMouseMove = this.onMouseMove.bind(this);
+    this.onMouseLeave = this.onMouseLeave.bind(this);
+    this.onResize = this.onResize.bind(this);
+  }
+  syncDimensions() {
+    if (!this.canvas || !this.element?.getBoundingClientRect) return 1;
+    const rect = this.element.getBoundingClientRect();
+    this.dpr = Math.min(this.window?.devicePixelRatio ?? 1, 2);
+    const cw = Math.round(rect.width * this.dpr);
+    const ch = Math.round(rect.height * this.dpr);
+    if (this.canvas.width !== cw || this.canvas.height !== ch) {
+      this.canvas.width = cw;
+      this.canvas.height = ch;
+      this.canvas.style.width = `${rect.width}px`;
+      this.canvas.style.height = `${rect.height}px`;
+    }
+    return this.dpr;
+  }
+  setupPosition() {
+    if (!this.window?.getComputedStyle) return;
+    if (this.window.getComputedStyle(this.element).position !== "static") return;
+    styleOf(this.ledgers, this.element)?.set("position", "relative");
+  }
+  init() {
+    if (!this.document || !this.element?.getBoundingClientRect) return false;
+    this.canvas = this.createCanvas();
+    if (!this.canvas) return false;
+    this.canvas.className = "kui-particle-canvas";
+    this.canvas.style.cssText = "position:absolute;top:0;left:0;pointer-events:none;z-index:10;";
+    this.ctx = this.canvas.getContext ? this.canvas.getContext("2d") : null;
+    if (!this.ctx) return false;
+    this.setupPosition();
+    this.element.appendChild(this.canvas);
+    this.syncDimensions();
+    const rect = this.element.getBoundingClientRect();
+    this.spawnParticles(rect.width, rect.height);
+    this.bindEvents();
+    return true;
+  }
+  spawnParticles(width, height) {
+    const count = this.options.count || 60;
+    const color = this.options.color || "#e4f222";
+    this.particles = spawnParticlesGrid(count, color, width, height);
+  }
+  resizeObserver = null;
+  bindEvents() {
+    if (this.isListening) return;
+    this.element.addEventListener("pointermove", this.onMouseMove, { passive: true });
+    this.element.addEventListener("pointerleave", this.onMouseLeave, { passive: true });
+    if (typeof ResizeObserver !== "undefined") {
+      this.resizeObserver = new ResizeObserver(() => this.onResize());
+      this.resizeObserver.observe(this.element);
+    } else if (this.window?.addEventListener) {
+      this.window.addEventListener("resize", this.onResize, { passive: true });
+    }
+    this.isListening = true;
+  }
+  unbindEvents() {
+    if (!this.isListening) return;
+    if (this.element?.removeEventListener) {
+      this.element.removeEventListener("pointermove", this.onMouseMove);
+      this.element.removeEventListener("pointerleave", this.onMouseLeave);
+    }
+    if (this.resizeObserver) {
+      this.resizeObserver.disconnect();
+      this.resizeObserver = null;
+    }
+    if (this.window?.removeEventListener) {
+      this.window.removeEventListener("resize", this.onResize);
+    }
+    this.isListening = false;
+  }
+  onResize() {
+    this.syncDimensions();
+    if (this.element?.getBoundingClientRect) {
+      const rect = this.element.getBoundingClientRect();
+      if (rect.width > 0 && rect.height > 0) {
+        this.spawnParticles(rect.width, rect.height);
+      }
+    }
+    this.draw();
+  }
+  onMouseMove(e) {
+    if (!this.canvas?.getBoundingClientRect) return;
+    const rect = this.canvas.getBoundingClientRect();
+    this.mouse.x = e.clientX - rect.left;
+    this.mouse.y = e.clientY - rect.top;
+    this.startLoop();
+  }
+  onMouseLeave() {
+    this.mouse.x = -999;
+    this.mouse.y = -999;
+  }
+  startLoop() {
+    if (this.rafId) return;
+    const tick = () => {
+      const moving = this.update();
+      this.draw();
+      if (this.isListening && (moving || this.mouse.x !== -999)) {
+        this.rafId = this.raf(tick);
+      } else {
+        this.rafId = null;
+      }
+    };
+    this.rafId = this.raf(tick);
+  }
+  stopLoop() {
+    if (this.rafId) {
+      this.caf(this.rafId);
+      this.rafId = null;
+    }
+  }
+  update() {
+    const repelRadius = this.options.radius || 80;
+    let anyMoving = false;
+    for (const p of this.particles) {
+      stepParticle(p, this.mouse.x, this.mouse.y, repelRadius);
+      if (isParticleMoving(p)) {
+        anyMoving = true;
+      }
+    }
+    return anyMoving;
+  }
+  draw() {
+    if (!this.ctx || !this.canvas) return;
+    const dpr = this.dpr || 1;
+    this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+    for (const p of this.particles) {
+      this.ctx.beginPath();
+      this.ctx.arc(p.x * dpr, p.y * dpr, p.radius * dpr, 0, Math.PI * 2);
+      this.ctx.fillStyle = p.color;
+      this.ctx.fill();
+    }
+  }
+  /** `try`/`finally` for the reason `camera-3d.ts`'s `destroy()` documents. */
+  destroy() {
+    try {
+      this.stopLoop();
+      this.unbindEvents();
+    } finally {
+      this.ledgers.restore();
+      this.removeCanvas();
+    }
+  }
+  removeCanvas() {
+    this.canvas?.remove();
+    this.canvas = null;
+    this.ctx = null;
+    this.particles = [];
+  }
+};
+function prepareParticles(el, params, ctx) {
+  if (isReducedMotion(ctx)) return createInertInstance();
+  const resolvedEnv = resolveEnv(ctx);
+  const count = clamp(params.num ? params.num("count", 60) : 60, 10, 300);
+  const radius = clamp(params.num ? params.num("radius", 80) : 80, 20, 300);
+  const color = params.text ? params.text("color", "#e4f222") : "#e4f222";
+  const htmlEl = el;
+  const emitter = new ParticleEmitter(htmlEl, { count, radius, color }, resolvedEnv);
+  let isMounted = false;
+  return createEffectInstance({
+    continuous: true,
+    activate() {
+      if (!isMounted) {
+        isMounted = emitter.init();
+      } else if (!emitter.isListening) {
+        emitter.bindEvents();
+      }
+      if (isMounted) {
+        emitter.startLoop();
+      }
+    },
+    cancel() {
+      emitter.stopLoop();
+      emitter.unbindEvents();
+    },
+    finish() {
+      emitter.stopLoop();
+      emitter.unbindEvents();
+    },
+    destroy() {
+      if (isMounted) {
+        emitter.destroy();
+        isMounted = false;
+      }
+    }
+  });
+}
+var PARTICLE_PARAMETERS = {
+  count: { type: "number", default: "60", minimum: 10, maximum: 300, cssProperty: "--kui-particle-count" },
+  radius: { type: "number", default: "80", minimum: 20, maximum: 300, cssProperty: "--kui-particle-radius" },
+  color: { type: "color", default: "#e4f222", cssProperty: "--kui-particle-color" }
+};
+var PARTICLE_PRIMITIVES = [
+  {
+    id: "particle-dissolve",
+    renderer: "javascript",
+    channels: ["position"],
+    parameters: PARTICLE_PARAMETERS,
+    supportedTimelines: ["time"],
+    supportedActivations: ["hover", "load"],
+    defaultActivation: "hover",
+    perfClass: "continuous",
+    reducedMotion: "disable",
+    prepare: prepareParticles
+  }
+];
+var PARTICLE_PRESETS = [
+  { name: "particle-dissolve", primitive: "particle-dissolve" }
+];
+function registerParticles(target) {
+  return registerInto(target, PARTICLE_PRIMITIVES, PARTICLE_PRESETS, "Particles");
+}
+
+// src/advanced/fluid-cursor.ts
+function stepFluidDrop(drop, friction) {
+  drop.x += drop.vx;
+  drop.y += drop.vy;
+  drop.vx *= friction;
+  drop.vy *= friction;
+  drop.alpha *= 0.94;
+  return drop.alpha < 0.02;
+}
+function syncCanvasStyleBox(canvas, vw, vh) {
+  const style = canvas.style;
+  if (!style) return;
+  const cssW = `${vw}px`;
+  const cssH = `${vh}px`;
+  if (style.width !== cssW) style.width = cssW;
+  if (style.height !== cssH) style.height = cssH;
+}
+function syncCanvasSize(canvas, win) {
+  if (!canvas) return 1;
+  const dpr = Math.min(win?.devicePixelRatio ?? 1, 2);
+  const vw = win?.innerWidth ?? 1e3;
+  const vh = win?.innerHeight ?? 800;
+  const w = Math.round(vw * dpr);
+  const h = Math.round(vh * dpr);
+  if (canvas.width !== w || canvas.height !== h) {
+    canvas.width = w;
+    canvas.height = h;
+  }
+  syncCanvasStyleBox(canvas, vw, vh);
+  return dpr;
+}
+var FluidTrail = class {
+  options;
+  env;
+  window;
+  document;
+  createCanvas;
+  raf;
+  caf;
+  drops = [];
+  canvas = null;
+  ctx = null;
+  rafId = null;
+  isListening = false;
+  lastMouse = { x: 0, y: 0 };
+  hasLastMouse = false;
+  wasOutside = false;
+  refCount = 0;
+  clients = /* @__PURE__ */ new Map();
+  activeClients = /* @__PURE__ */ new Map();
+  nextClientId = 1;
+  onResize;
+  onPointerMove;
+  mapKey;
+  constructor(options = {}, env = {}) {
+    this.options = options;
+    this.env = env;
+    const resolved = resolveEnv(null, env);
+    this.window = resolved.window;
+    this.document = resolved.document;
+    this.createCanvas = resolved.createCanvas;
+    this.raf = resolved.raf;
+    this.caf = resolved.caf;
+    this.mapKey = resolved.document ?? resolved.window ?? fallbackFluidKey;
+  }
+  acquire() {
+    if (this.ctx) {
+      this.refCount++;
+      return true;
+    }
+    const ok = this.init();
+    if (ok) this.refCount++;
+    return ok;
+  }
+  release() {
+    if (this.refCount > 0) this.refCount--;
+    if (this.refCount === 0 && this.clients.size === 0) this.destroy();
+  }
+  registerClient(options, el) {
+    const id = this.nextClientId++;
+    this.clients.set(id, { options, el });
+    return id;
+  }
+  activateClient(id) {
+    const client = this.clients.get(id);
+    if (!client) return false;
+    this.activeClients.set(id, client);
+    if (!this.canvas && !this.setupCanvas()) return false;
+    this.attachListeners();
+    this.startLoop();
+    return true;
+  }
+  deactivateClient(id) {
+    this.activeClients.delete(id);
+    if (this.activeClients.size > 0 || this.refCount > 0) return;
+    this.detachListeners();
+    this.stopLoop();
+    this.clearOverlay();
+  }
+  /**
+   * Wipe the overlay when the last client stands down.
+   *
+   * `draw()` clears the canvas at the *start* of a frame, so stopping the loop leaves whatever was
+   * in flight painted. The overlay is `position: fixed` at `z-index: 9998` across the whole
+   * viewport, so a `fluid-trail` on `on:pointerenter`/`pointerleave` — or an author's
+   * `control.cancel()` mid-move — left a frozen blob of drops over the entire page until something
+   * reactivated it or the element was destroyed.
+   *
+   * The canvas itself stays mounted on purpose: registration happens at prepare, so the last
+   * *unregister* owns the teardown and no client can have the canvas pulled from under it.
+   *
+   * @complexity O(1).
+   */
+  clearOverlay() {
+    this.drops = [];
+    const canvas = this.canvas;
+    if (!canvas || typeof this.ctx?.clearRect !== "function") return;
+    this.ctx.clearRect(0, 0, canvas.width, canvas.height);
+  }
+  unregisterClient(id) {
+    this.deactivateClient(id);
+    this.clients.delete(id);
+    if (this.clients.size === 0 && this.refCount === 0) {
+      this.destroy();
+    }
+  }
+  setupCanvas() {
+    if (this.canvas && this.ctx) return true;
+    if (!this.document?.body?.appendChild) return false;
+    this.canvas = this.createCanvas();
+    if (!this.canvas) return false;
+    this.canvas.className = "kui-fluid-canvas";
+    this.canvas.style.cssText = "position:fixed;top:0;left:0;pointer-events:none;z-index:9998;";
+    this.ctx = this.canvas.getContext ? this.canvas.getContext("2d") : null;
+    if (!this.ctx) {
+      this.canvas = null;
+      return false;
+    }
+    this.document.body.appendChild(this.canvas);
+    syncCanvasSize(this.canvas, this.window);
+    return true;
+  }
+  attachListeners() {
+    if (this.isListening) return;
+    this.onResize = () => syncCanvasSize(this.canvas, this.window);
+    this.onPointerMove = (e) => {
+      const client = this.resolveClientOwner(e);
+      if (!client) {
+        this.lastMouse.x = e.clientX;
+        this.lastMouse.y = e.clientY;
+        this.wasOutside = true;
+        return;
+      }
+      const isEntry = this.wasOutside;
+      const dx = isEntry ? 0 : e.clientX - this.lastMouse.x;
+      const dy = isEntry ? 0 : e.clientY - this.lastMouse.y;
+      this.wasOutside = false;
+      if (Math.hypot(dx, dy) > 2 || isEntry || !this.hasLastMouse) {
+        this.hasLastMouse = true;
+        const vx = Math.max(-20, Math.min(20, dx * 0.2));
+        const vy = Math.max(-20, Math.min(20, dy * 0.2));
+        this.spawnDrop(e.clientX, e.clientY, vx, vy, client.options);
+        this.startLoop();
+      }
+      this.lastMouse.x = e.clientX;
+      this.lastMouse.y = e.clientY;
+    };
+    if (this.window?.addEventListener) {
+      this.window.addEventListener("resize", this.onResize, { passive: true });
+      this.window.addEventListener("pointermove", this.onPointerMove, { passive: true });
+      this.isListening = true;
+    }
+  }
+  detachListeners() {
+    if (this.window?.removeEventListener && this.isListening) {
+      if (this.onResize) this.window.removeEventListener("resize", this.onResize);
+      if (this.onPointerMove) this.window.removeEventListener("pointermove", this.onPointerMove);
+      this.isListening = false;
+      this.hasLastMouse = false;
+      this.wasOutside = false;
+    }
+  }
+  init() {
+    if (!this.setupCanvas()) return false;
+    this.attachListeners();
+    return true;
+  }
+  findClientByTarget(target) {
+    let curr = target && typeof target.nodeType === "number" ? target : null;
+    while (curr) {
+      for (const client of this.activeClients.values()) {
+        if (client.el && client.el === curr) return client;
+      }
+      curr = curr.parentNode;
+    }
+    return null;
+  }
+  findClientByCoords(x, y) {
+    for (const client of this.activeClients.values()) {
+      const rect = client.el?.getBoundingClientRect?.();
+      if (rect && x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom) return client;
+    }
+    return null;
+  }
+  resolveClientOwner(e) {
+    if (this.activeClients.size === 0) return { options: this.options, el: void 0 };
+    return this.findClientByTarget(e.target) ?? this.findClientByCoords(e.clientX, e.clientY);
+  }
+  getOptionsAt(x, y) {
+    return this.findClientByCoords(x, y)?.options ?? null;
+  }
+  // eslint-disable-next-line max-params -- (x, y, vx, vy, customOpts) is the established drop coordinate and velocity signature
+  spawnDrop(x, y, vx, vy, customOpts) {
+    const activeOpts = customOpts ?? (this.activeClients.size === 0 ? this.options : this.getOptionsAt(x, y));
+    if (!activeOpts) return;
+    this.drops.push({
+      x,
+      y,
+      vx,
+      vy,
+      size: activeOpts.size ?? this.options.size ?? 28,
+      alpha: 0.8,
+      color: activeOpts.color ?? this.options.color ?? "#e4f222",
+      viscosity: activeOpts.viscosity ?? this.options.viscosity ?? 0.88
+    });
+  }
+  startLoop() {
+    if (this.rafId) return;
+    const tick = () => {
+      this.update();
+      this.draw();
+      if (this.drops.length > 0 && this.ctx) {
+        this.rafId = this.raf(tick);
+      } else {
+        this.rafId = null;
+      }
+    };
+    this.rafId = this.raf(tick);
+  }
+  stopLoop() {
+    if (this.rafId) {
+      this.caf(this.rafId);
+      this.rafId = null;
+    }
+  }
+  update() {
+    for (let i = this.drops.length - 1; i >= 0; i--) {
+      const drop = this.drops[i];
+      if (drop && stepFluidDrop(drop, drop.viscosity ?? 0.88)) {
+        this.drops.splice(i, 1);
+      }
+    }
+  }
+  draw() {
+    const ctx = this.ctx;
+    if (!ctx || !this.canvas) return;
+    const dpr = syncCanvasSize(this.canvas, this.window);
+    ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+    for (const drop of this.drops) {
+      if (typeof ctx.save === "function") ctx.save();
+      ctx.globalAlpha = drop.alpha;
+      ctx.fillStyle = drop.color;
+      ctx.beginPath();
+      ctx.arc(drop.x * dpr, drop.y * dpr, drop.size * dpr * 0.5, 0, Math.PI * 2);
+      ctx.fill();
+      if (typeof ctx.restore === "function") ctx.restore();
+    }
+  }
+  destroy() {
+    this.stopLoop();
+    this.detachListeners();
+    if (this.canvas) {
+      this.canvas.remove();
+      this.canvas = null;
+    }
+    this.ctx = null;
+    this.drops = [];
+    this.refCount = 0;
+    this.clients.clear();
+    this.activeClients.clear();
+    fluidTrails.delete(this.mapKey);
+  }
+};
+var fluidTrails = /* @__PURE__ */ new WeakMap();
+var fallbackFluidKey = {};
+function getSharedFluidTrail(env) {
+  const resolved = resolveEnv(null, env);
+  const key = resolved.document ?? resolved.window ?? fallbackFluidKey;
+  let trail = fluidTrails.get(key);
+  if (!trail) {
+    trail = new FluidTrail({}, env);
+    fluidTrails.set(key, trail);
+  }
+  return trail;
+}
+function prepareFluidCursor(el, params, ctx) {
+  if (isReducedMotion(ctx)) return createInertInstance();
+  const hostDoc = el?.ownerDocument;
+  const resolvedEnv = resolveEnv(ctx, hostDoc ? { document: hostDoc, window: hostDoc.defaultView } : void 0);
+  if (!resolvedEnv.document?.body) {
+    return createInertInstance();
+  }
+  const size = clamp(params.num ? params.num("size", 28) : 28, 4, 120);
+  const viscosity = clamp(params.num ? params.num("viscosity", 0.88) : 0.88, 0.1, 0.99);
+  const color = params.text ? params.text("color", "#e4f222") : "#e4f222";
+  const trail = getSharedFluidTrail(resolvedEnv);
+  const clientId = trail.registerClient({ size, viscosity, color }, el);
+  return createEffectInstance({
+    continuous: true,
+    activate() {
+      trail.activateClient(clientId);
+    },
+    cancel() {
+      trail.deactivateClient(clientId);
+    },
+    finish() {
+      trail.deactivateClient(clientId);
+    },
+    destroy() {
+      trail.unregisterClient(clientId);
+    }
+  });
+}
+var FLUID_PARAMETERS = {
+  size: { type: "number", default: "28", minimum: 4, maximum: 120, cssProperty: "--kui-fluid-size" },
+  viscosity: { type: "number", default: "0.88", minimum: 0.1, maximum: 0.99, cssProperty: "--kui-fluid-viscosity" },
+  color: { type: "color", default: "#e4f222", cssProperty: "--kui-fluid-color" }
+};
+var FLUID_PRIMITIVES = [
+  {
+    id: "fluid-trail",
+    renderer: "javascript",
+    channels: [],
+    parameters: FLUID_PARAMETERS,
+    supportedTimelines: ["time"],
+    supportedActivations: ["load", "hover"],
+    defaultActivation: "load",
+    perfClass: "continuous",
+    reducedMotion: "disable",
+    prepare: prepareFluidCursor
+  }
+];
+var FLUID_PRESETS = [
+  { name: "fluid-trail", primitive: "fluid-trail" },
+  { name: "cursor-fluid", primitive: "fluid-trail" },
+  { name: "fluid-cursor", primitive: "fluid-trail" }
+];
+function registerFluidCursor(target) {
+  return registerInto(target, FLUID_PRIMITIVES[0], FLUID_PRESETS, "FluidCursor");
+}
+
+// src/advanced/index.ts
+function registerAdvanced(target) {
+  registerShaders(target);
+  registerScenes(target);
+  registerCamera(target);
+  registerParticles(target);
+  registerFluidCursor(target);
+  registerAudio(target);
+  const t = target;
+  return t?.registry || target;
+}
+export {
+  AUDIO_PARAMETERS,
+  AUDIO_PRESETS,
+  AUDIO_PRIMITIVES,
+  AudioSourceController,
+  CAMERA_PARAMETERS,
+  CAMERA_PRESETS,
+  CAMERA_PRIMITIVES,
+  FLUID_PARAMETERS,
+  FLUID_PRESETS,
+  FLUID_PRIMITIVES,
+  PARTICLE_PARAMETERS,
+  PARTICLE_PRESETS,
+  PARTICLE_PRIMITIVES,
+  SCENE_PARAMETERS,
+  SCENE_PRESETS,
+  SCENE_PRIMITIVES,
+  SHADERS_PRESETS,
+  SHADERS_PRIMITIVE,
+  SHADER_PARAMETERS,
+  prepareAudioSource,
+  prepareCameraScene,
+  prepareFluidCursor,
+  prepareParticles,
+  prepareScene,
+  prepareShaders,
+  registerAdvanced,
+  registerAudio,
+  registerCamera,
+  registerFluidCursor,
+  registerParticles,
+  registerScenes,
+  registerShaders
+};