@cruxgarden/plasma-ui 0.2.4 → 0.5.0

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/PlasmaProvider.tsx
-import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 
 // src/shaders.ts
 var DEFAULT_MAX_SHAPES = 16;
@@ -9,7 +9,7 @@ in vec2 p; void main(){ gl_Position = vec4(p, 0., 1.); }`;
 function makeShaders(MAX_SHAPES) {
   const common = `
 precision highp float;
-uniform vec2 uRes; uniform vec4 uView; uniform float uScale, uTime, uGoo, uEnergy, uLight, uMouseAmt, uDropR, uAmbient, uScroll, uVisc, uFlow;
+uniform vec2 uRes; uniform vec4 uView; uniform float uScale, uTime, uGoo, uEnergy, uLight, uMouseAmt, uDropR, uAmbient, uScroll, uVisc, uFlow, uTension, uThick;
 uniform vec2 uMouse;
 uniform vec4 uP[${MAX_SHAPES}]; uniform vec4 uR[${MAX_SHAPES}]; uniform float uF[${MAX_SHAPES}]; uniform vec4 uT[${MAX_SHAPES}]; uniform float uFr[${MAX_SHAPES}]; uniform float uEl[${MAX_SHAPES}]; uniform float uSolo[${MAX_SHAPES}];
 uniform int uCount;
@@ -128,6 +128,7 @@ uniform vec2 uImgRes;
 uniform float uHasImg;
 uniform vec3 uBgColor;
 uniform float uBgSolid;
+uniform float uClear;
 out vec4 o;
 vec3 bg(vec2 p){
   p.y += uScroll;
@@ -161,6 +162,15 @@ void main(){
     o = vec4(uBgColor * (1. + shade), 1.);
     return;
   }
+  if (uHasImg > .5 && uClear > .5) {
+    // a clear ground samples what is beneath it exactly - no swirl, no warp -
+    // so a refraction of it lines up with the page it sits on
+    float sc = max(uView.z / uImgRes.x, uView.w / uImgRes.y);
+    vec2 uv = (p - uView.xy - .5*uView.zw) / (uImgRes * sc) + .5;
+    o = vec4(texture(uImg, clamp(uv, 0., 1.)).rgb, 1.);
+    return;
+  }
+  if (uClear > .5) { o = vec4(0., 0., 0., 1.); return; }
   if (uHasImg > .5) {
     // image background: slow swirl plus the pulse warp above
     vec2 q = bp;
@@ -178,13 +188,39 @@ void main(){
   const compFrag = `#version 300 es
 ${common}
 uniform sampler2D uH, uS, uTint, uBg, uBgM, uBgH, uFrost;
-uniform float uRefract, uDisp, uRim, uRimMode, uRimWidth, uSpec, uHair;
+uniform float uRefract, uDisp, uRim, uRimMode, uRimWidth, uSpec, uHair, uShim, uGlow, uWash, uGrain;
+// Which material the surfaces are made of, and the one light every opaque one
+// reads. Glass fakes its lighting off the pointer because you see through it;
+// the moment anything is opaque, two materials disagreeing about where the sun
+// is looks broken in a way no single shader can fix. So there is one light.
+uniform float uMat;
+// 1 when the ground is clear: alpha is the surface's coverage (and its
+// shadow's darkness), so the canvas can sit above other content.
+uniform float uClear;
+uniform vec3 uLightDir;
+// Surface finish, shared by every material that has one: 0 is a mirror, 1 is
+// chalk. Anisotropy stretches the highlight along the grain \u2014 brushed metal
+// and varnished wood both need it, and neither reads right without it.
+uniform float uRough, uAniso;
+// How thick a panel is, in CSS px, and how much the material rounds itself
+// against that. Mercury has enormous surface tension, so a bead pulls toward
+// a sphere; tension drives both the corner radius and how eagerly two beads
+// merge into one body.
+// The edge treatment. A rounded rectangle is right for a liquid, and wrong for
+// almost everything else: stone chips, cloud billows, metal is cut. These
+// displace the silhouette itself \u2014 amplitude in CSS px, scale in cycles \u2014
+// before anything decides what is inside, so the outline, the rim, the shadow
+// and the material all agree about where the panel ends.
+uniform float uEdge, uEdgeScale, uEdgeSharp;
 uniform vec3 uRimColor;
 out vec4 o;
 
 vec3 pal(float t){ return .5 + .5*cos(6.2831*(t + vec3(0., .33, .67))); }
 float H(vec2 uv){ return texture(uH, uv).r; }
-vec2 uvAt(vec2 q){ return vec2(q.x, uRes.y - q.y) / uRes; }
+// Clamped, because a reflection offset is far larger than a refraction one:
+// metal sweeps up to 150px and walks straight off the texture, where
+// CLAMP_TO_EDGE smears the last row of pixels into arcs across the panel.
+vec2 uvAt(vec2 q){ return clamp(vec2(q.x, uRes.y - q.y) / uRes, vec2(.001), vec2(.999)); }
 // background seen through plasma with frost f: sharp, then medium, then heavy blur
 vec3 seen(vec2 q, float f){
   vec2 u = uvAt(q);
@@ -193,6 +229,248 @@ vec3 seen(vec2 q, float f){
   vec3 soft = mix(texture(uBgM, u).rgb, texture(uBgH, u).rgb, smoothstep(.45, 1., f));
   return mix(sharp, soft, smoothstep(0., .45, f));
 }
+// \u2500\u2500 Shading kit \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// A real microfacet BRDF, not pow(ndl, n). GGX + height-correlated Smith +
+// Schlick is what every modern renderer uses, and it is the single biggest
+// difference between a material that reads as itself and one that reads as
+// coloured plastic.
+float D_GGX(float ndh, float a){ float a2 = a*a; float d = ndh*ndh*(a2-1.)+1.; return a2/(3.14159265*d*d + 1e-7); }
+// Anisotropic GGX: the highlight stretches along a direction. This is the tell
+// for wood and for brushed metal \u2014 an isotropic highlight on wood looks wrong
+// even when nothing else does.
+float D_GGXaniso(float ndh, float tdh, float bdh, float ax, float ay){
+  float d = tdh*tdh/(ax*ax) + bdh*bdh/(ay*ay) + ndh*ndh;
+  return 1./(3.14159265*ax*ay*d*d + 1e-7);
+}
+float V_SmithGGX(float ndv, float ndl, float a){
+  float a2 = a*a;
+  float gv = ndl*sqrt(ndv*ndv*(1.-a2)+a2);
+  float gl = ndv*sqrt(ndl*ndl*(1.-a2)+a2);
+  return .5/max(gv+gl, 1e-5);
+}
+vec3 F_Schlick(vec3 f0, float u){ return f0 + (1.-f0)*pow(clamp(1.-u,0.,1.), 5.); }
+
+// Lighting has to happen in linear light. Doing it in gamma space is the
+// oldest way to make a render look cheap: highlights clip early and midtones
+// go chalky. sqrt/square is the standard cheap sRGB pair.
+vec3 toLinear(vec3 c){ return c*c; }
+vec3 toSrgb(vec3 c){ return sqrt(max(c, 0.)); }
+// ACES filmic, fitted. Keeps a bright specular from flattening into white.
+vec3 tonemap(vec3 x){ return clamp((x*(2.51*x+.03))/(x*(2.43*x+.59)+.14), 0., 1.); }
+
+// Plain fbm reads as fractal mush. Warping the domain by another fbm is what
+// makes grain and rock look grown rather than generated \u2014 the background
+// shader already leans on this.
+vec2 warp(vec2 q, float k){
+  return q + k*vec2(fbm(q + vec2(1.7, 9.2)), fbm(q + vec2(5.3, 2.8)));
+}
+
+// Metal only reads as metal when it reflects something with structure, and a
+// page background is nearly uniform \u2014 reflect it alone and you get grey paint
+// with a shiny rim. So reflective materials also see a small studio: a sky
+// gradient, a horizon, and a sun in the same direction as the light. Roughness
+// widens the sun and flattens the band, which is what a prefiltered
+// environment map does for real.
+vec3 envmap(vec3 R, float rough){
+  float h = clamp(R.y * .5 + .5, 0., 1.);
+  vec3 sky = mix(vec3(.62, .70, .84), vec3(.10, .13, .19), pow(1. - h, 1.5));
+  vec3 ground = vec3(.055, .05, .048);
+  vec3 c = mix(ground, sky, smoothstep(.40, .60, h));
+  vec3 L = normalize(uLightDir);
+  float sun = pow(max(dot(R, L), 0.), mix(260., 5., rough));
+  c += vec3(1., .96, .88) * sun * (1. - rough * .7) * 2.2;
+  // the horizon band is what gives a curved metal edge its sweep
+  c += vec3(.75, .82, .95) * (1. - smoothstep(.0, .22, abs(h - .54))) * .45 * (1. - rough * .55);
+  return c;
+}
+
+// \u2500\u2500 The scene as a solid \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// Everything above shades a flat card: a 2D silhouette, a perturbed normal,
+// a texture lookup. That is skinning, and it is why wood came out looking
+// like a wood-effect laminate. A material reads as a material when there is a
+// body to light \u2014 so the same shapes are extruded into a slab and the view ray
+// is marched through it, the way a game would.
+//
+// The 2D mask is a free conservative bound: outside it there is nothing to
+// hit, so the march never starts.
+float map3(vec3 q, float tension, float thick){
+  float d = 1e5;
+  for (int i = 0; i < uCount; i++) {
+    float f = uF[i];
+    if (f < .005) continue;
+    vec2 c = uP[i].xy;
+    vec2 h = uP[i].zw * f;
+    float rmax = max(max(uR[i].x, uR[i].y), max(uR[i].z, uR[i].w));
+    // The footprint is the element's, exactly as plasma's is. Mercury is not
+    // a blob that swallows the layout \u2014 it is a panel, poured. Tension belongs
+    // to the edge and to the merge, not to the shape: pulling the whole
+    // footprint toward a disc threw the panel away and left content floating
+    // over nothing.
+    float d2 = sdBoxG(q.xy - c, h, min(uR[i], vec4(min(h.x, h.y))), rmax).x;
+    // Extrude, with the rim rolled over so the slab has a shoulder rather than
+    // a cut edge. Tension fattens that roll \u2014 where a bead of mercury reads as
+    // poured is its edge, not its outline.
+    float roll = thick * (.22 + .50 * tension);
+    vec2 w = vec2(d2 + roll, abs(q.z) - (thick - roll));
+    float de = min(max(w.x, w.y), 0.) + length(max(w, 0.)) - roll;
+    d = (i == 0) ? de : smin(d, de, uGoo * (.6 + 1.8 * tension));
+  }
+  // Two slow swells across the whole body, displacing the surface itself
+  // rather than tilting a normal \u2014 the march finds a moving surface, so the
+  // reflection travels over real waves. This is what separates water from a
+  // picture of water.
+  // Displacing a distance field costs it the property the march depends on:
+  // d is no longer a safe distance, so a full step overshoots the surface and
+  // the ray lands inside, which is the mottled crust this produced at first.
+  // The amplitude is kept small and the march below steps at a fraction, which
+  // is the standard price of displacement.
+  if (tension > .01) {
+    float wv = (fbm(q.xy * .0075 + vec2(uTime * .11, uTime * .06)) - .5) * 1.6
+             + (fbm(q.xy * .019 - vec2(uTime * .08, uTime * .13)) - .5) * .6;
+    d -= wv * thick * .07 * tension;
+  }
+  return d;
+}
+
+/**
+ * A crystalline crown: the panel's face is a regular triangular lattice, and
+ * every triangle is a flat facet with its own plane.
+ *
+ * Regular, not random \u2014 a Delaunay scatter reads as shattered safety glass,
+ * and a lattice reads as something cut. The heights at the lattice corners are
+ * hashed, so the facets tilt differently while the pattern stays symmetric.
+ *
+ * The normal comes out exact rather than differenced, which is what makes the
+ * faces crisp: a facet is a plane, so its normal is constant across it, and
+ * there is nothing for a march to stipple.
+ */
+vec3 facetPlane(vec2 uv, float amp, out float height){
+  vec2 c = floor(uv), f = fract(uv);
+  float h00 = hash(c) * amp;
+  float h10 = hash(c + vec2(1., 0.)) * amp;
+  float h01 = hash(c + vec2(0., 1.)) * amp;
+  float h11 = hash(c + vec2(1., 1.)) * amp;
+  float dx, dy;
+  // Which way the cell's diagonal runs is decided per cell. One diagonal
+  // everywhere reads as corduroy; alternating reads as cut.
+  bool flip = hash(c + 91.7) > .5;
+  bool lower = flip ? (f.x + f.y < 1.) : (f.x > f.y);
+  if (lower) {
+    height = h00 + (h10 - h00) * f.x + (h01 - h00) * f.y;
+    dx = h10 - h00; dy = h01 - h00;
+  } else {
+    height = h11 + (h01 - h11) * (1. - f.x) + (h10 - h11) * (1. - f.y);
+    dx = h11 - h01; dy = h11 - h10;
+  }
+  return normalize(vec3(-dx, -dy, 1.));
+}
+
+/**
+ * The crystal's top surface, as a height in page px, plus the exact plane
+ * normal of whichever facet the point lies on. This is a real surface: the
+ * march below has to find where the ray crosses it, so the facets occlude one
+ * another, break the silhouette, and shadow each other. A normal returned
+ * without an intersection would be a normal map, which is what the version
+ * before this was.
+ */
+float crownZ(vec2 xy, float gcut, float amp, float thick, out vec3 nrm){
+  float h;
+  nrm = facetPlane(xy / gcut, amp / gcut, h);
+  return thick + h * gcut;
+}
+
+// \u2500\u2500 The gem \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// Facet directions, spread over a hemisphere and mirrored, standing in for a
+// cut stone's crown and pavilion. Generated rather than tabulated so the count
+// is a constant to change, not a table to rewrite.
+vec3 facetN(int i){
+  float fi = float(i);
+  float a = fi * 2.3999632;                       // golden angle, so they do not band
+  float z = mix(.22, .92, fract(fi * .6180339));
+  float r = sqrt(max(0., 1. - z * z));
+  return normalize(vec3(cos(a) * r, sin(a) * r, z));
+}
+
+/**
+ * The panel as a piece of gem. The slab is the element's own footprint,
+ * extruded; the facets are half-spaces cut through it.
+ *
+ * The cuts are anchored in PAGE space, not the panel's, which is the whole
+ * trick: a facet plane runs on across the gap and slices the next panel too,
+ * so the panels read as pieces carved out of one stone rather than as
+ * separate gems that happen to match.
+ */
+float mapGem(vec3 q, float thick, float cut){
+  float d = 1e5;
+  for (int i = 0; i < uCount; i++) {
+    float f = uF[i];
+    if (f < .005) continue;
+    vec2 c = uP[i].xy;
+    vec2 h = uP[i].zw * f;
+    float rmax = max(max(uR[i].x, uR[i].y), max(uR[i].z, uR[i].w));
+    float d2 = sdBoxG(q.xy - c, h, min(uR[i], vec4(min(h.x, h.y))), rmax).x;
+    vec2 w = vec2(d2, abs(q.z) - thick);
+    float de = min(max(w.x, w.y), 0.) + length(max(w, 0.)) - 1.5;
+    d = (i == 0) ? de : min(d, de);
+  }
+  // Cut the stone. Each plane repeats on a lattice so the whole page is one
+  // crystal the panels are taken out of. Six directions, and the lattice is
+  // wide \u2014 a few facets across a panel, not hundreds. Cut it finely and a gem
+  // stops being a gem and becomes gravel, which is exactly what nine planes at
+  // 34px produced on the first try.
+  for (int i = 0; i < 6; i++) {
+    vec3 nn = facetN(i);
+    if (fract(float(i) * .5) > .25) nn.z = -nn.z;   // mirror half of them below
+    // The plane sits near the far end of its lattice cell, so a cut trims a
+    // corner instead of slicing the body in half. Six planes at 70% of the
+    // cell removed most of the volume and left the panels as floating shards.
+    // A gem is faceted, not shattered.
+    float hgt = dot(q, nn);
+    float plane = floor(hgt / cut) * cut + cut * .965;
+    d = max(d, hgt - plane);
+  }
+  return d;
+}
+
+vec3 gemNormal(vec3 q, float thick, float cut){
+  vec2 e = vec2(.4, 0.);
+  return normalize(vec3(
+    mapGem(q + e.xyy, thick, cut) - mapGem(q - e.xyy, thick, cut),
+    mapGem(q + e.yxy, thick, cut) - mapGem(q - e.yxy, thick, cut),
+    mapGem(q + e.yyx, thick, cut) - mapGem(q - e.yyx, thick, cut)
+  ));
+}
+
+vec3 normal3(vec3 q, float tension, float thick){
+  vec2 e = vec2(.75, 0.);
+  return normalize(vec3(
+    map3(q + e.xyy, tension, thick) - map3(q - e.xyy, tension, thick),
+    map3(q + e.yxy, tension, thick) - map3(q - e.yxy, tension, thick),
+    map3(q + e.yyx, tension, thick) - map3(q - e.yyx, tension, thick)
+  ));
+}
+
+// Worley/Voronoi: nearest cell, second nearest, and the cell's id. The gap
+// between the two is the distance to a cell wall, which is what draws the
+// seams of a crystal without any geometry.
+vec4 voronoi(vec2 q){
+  vec2 ip = floor(q), fp = fract(q);
+  float d1 = 8., d2 = 8.;
+  vec2 id = vec2(0.);
+  for (int j = -1; j <= 1; j++) {
+    for (int i = -1; i <= 1; i++) {
+      vec2 g = vec2(float(i), float(j));
+      vec2 cell = ip + g;
+      vec2 o = vec2(hash(cell), hash(cell + 31.7));
+      vec2 r = g + o - fp;
+      float d = dot(r, r);
+      if (d < d1) { d2 = d1; d1 = d; id = cell; }
+      else if (d < d2) { d2 = d; }
+    }
+  }
+  return vec4(sqrt(d1), sqrt(d2), id);
+}
+
 // B-spline bicubic from four bilinear taps keeps curved outlines round.
 float S(vec2 uv){
   vec2 ts = vec2(textureSize(uS, 0));
@@ -219,9 +497,23 @@ void main(){
   float s = S(uv);
   vec2 gs = vec2(S(uv+vec2(tx.x,0.)) - S(uv-vec2(tx.x,0.)), S(uv+vec2(0.,tx.y)) - S(uv-vec2(0.,tx.y))) / (2.*cssPerTexel);
   float sd = clamp((s - .5) / max(length(gs), 1e-3), -60., 60.);
+  if (uEdge > .01) {
+    // Two octaves: the first gives the large shape (billows, chips), the
+    // second the fine break-up. Warping keeps it from reading as a sine wave
+    // stamped around the outline.
+    vec2 ep = warp(p * uEdgeScale, .7);
+    float e1 = fbm(ep) - .5;
+    float e2 = fbm(ep * 3.3 + 17.) - .5;
+    float disp = e1 * 1.5 + e2 * .55;
+    // uEdgeSharp 0 leaves it rolling; 1 pushes it toward flats and points,
+    // which is what reads as chipped rather than melted.
+    disp = mix(disp, sign(disp) * pow(abs(disp) * 2., .55) * .5, clamp(uEdgeSharp, 0., 1.));
+    sd += disp * uEdge;
+  }
 
   vec3 back = texture(uBg, uv).rgb;
   float grain = 1.;
+  float cover = 0.;
 
   // shadow: offset and strength follow the surface's elevation
   float msk = max(texture(uS, uv).r, 1e-3);
@@ -235,7 +527,7 @@ void main(){
   // Palette phases run on viewport position, like the grain: a frame drawn for
   // a taller region must colour its viewport band exactly as the live frame does.
   vec2 vp = p - uView.xy;
-  col += pal(uTime*.03 + vp.x/1400.) * .06 * smoothstep(.0, .45, hHere) * (1.+uEnergy);
+  col += pal(uTime*.03 + vp.x/1400.) * .06 * smoothstep(.0, .45, hHere) * (1.+uEnergy) * uGlow;
 
   if(sd > -2.){
     vec2 th = 2. / vec2(textureSize(uH, 0));
@@ -255,7 +547,12 @@ void main(){
       seen(p + off, fr).g,
       seen(p + off*(1.-disp), fr).b
     );
+    // uWash 0 hands the background through untouched - glass with no cast of
+    // its own. 1 is the original desaturate-and-lift that gives the material
+    // its body.
+    vec3 clearRefr = refr;
     refr = mix(refr, vec3(dot(refr, vec3(.333))), .18) * mix(1.08, .9, uLight) + .03*(1.-uLight);
+    refr = mix(clearRefr, refr, uWash);
     // frosted: milkier and a little brighter
     refr = mix(refr, mix(refr, vec3(dot(refr, vec3(.333))), .25) * mix(1.12, .97, uLight) + mix(.05, .03, uLight), fr);
     float hl = 1. - .55*uLight;
@@ -276,21 +573,321 @@ void main(){
     if (uRimMode > .5 && uRimMode < 1.5) rimCol = uRimColor * facing * 1.4;
     else if (uRimMode > 1.5) rimCol = tcol * facing * 1.4;
 
+    // A 3D normal from the 2D height gradient: flat in the middle, turning
+    // outward and down across the bevel. Every material shades from this, and
+    // the opaque ones perturb it further with their own detail.
+    vec3 Nb = normalize(vec3(n * (.30 + .70 * bevel), max(.20, 1. - bevel)));
+    vec3 Ldir = normalize(uLightDir);
+    vec3 V = vec3(0., 0., 1.);            // orthographic view, straight on
     vec3 plasma = refr;
-    plasma += rimCol * fres * .45 * hl * uRim;
-    plasma += vec3(1.) * spec * .75 * hl * uSpec;
-    // faint shimmer across the body; fades out as the tint becomes opaque
-    plasma += pal(uTime*.04 + vp.y/900. + uEnergy*.3) * .05 * lift * (1.+uEnergy*2.) * hl * (1. - talpha);
-    vec3 hairCol = uRimMode > .5 ? mix(vec3(1.), rimCol / 1.4, .6) : vec3(.9,.95,1.);
-    plasma += hairCol * (1.-smoothstep(0., 1.6, abs(sd - .7))) * .4 * hl * uHair;
-
     float a = smoothstep(-.8, .8, sd);
+
+    if (uMat < .5) {
+      // \u2500\u2500 plasma \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+      plasma += rimCol * fres * .45 * hl * uRim;
+      plasma += vec3(1.) * spec * .75 * hl * uSpec;
+      // faint shimmer across the body; fades out as the tint becomes opaque
+      plasma += pal(uTime*.04 + vp.y/900. + uEnergy*.3) * .05 * lift * (1.+uEnergy*2.) * hl * (1. - talpha) * uShim;
+      vec3 hairCol = uRimMode > .5 ? mix(vec3(1.), rimCol / 1.4, .6) : vec3(.9,.95,1.);
+      plasma += hairCol * (1.-smoothstep(0., 1.6, abs(sd - .7))) * .4 * hl * uHair;
+    } else if (uMat < 1.5) {
+      // \u2500\u2500 crystal \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+      // Actual 3D. The panel is a solid whose top is a cut crown \u2014 a lattice
+      // of flat facets, anchored in PAGE space so a facet runs on across the
+      // gap into the next panel. The view ray is marched until it crosses that
+      // surface, so the facets genuinely occlude each other, break the
+      // silhouette where they rise and fall, and shadow one another.
+      //
+      // A height field is marched by stepping and testing which side of the
+      // surface you are on, then bisecting \u2014 not by sphere tracing, which a
+      // piecewise-planar field is hostile to.
+      float gcut = max(uThick * 2.4, 52.);
+      float amp = gcut * .45;
+      float gthick = max(uThick, 10.);
+
+      vec3 gro = vec3(p, gthick + amp * 1.6 + 4.);
+      vec3 grd = normalize(vec3((p - uMouse) * .00055, -1.));
+
+      float tPrev = 0., tHit = -1.;
+      vec3 nHit = vec3(0., 0., 1.);
+      float stepLen = max(amp * .16, 1.2);
+      for (int i = 0; i < 64; i++) {
+        float t = float(i) * stepLen;
+        vec3 q = gro + grd * t;
+        // Outside the panel's footprint there is no stone to hit.
+        if (scene(q.xy) > 0.) { tPrev = t; continue; }
+        vec3 nn;
+        float sz = crownZ(q.xy, gcut, amp, gthick, nn);
+        if (q.z <= sz) {
+          // Crossed it. Bisect for the exact facet plane.
+          float lo = tPrev, hi = t;
+          for (int k = 0; k < 6; k++) {
+            float mid = (lo + hi) * .5;
+            vec3 qm = gro + grd * mid;
+            vec3 nm;
+            float szm = crownZ(qm.xy, gcut, amp, gthick, nm);
+            if (qm.z <= szm) { hi = mid; nHit = nm; } else { lo = mid; }
+          }
+          tHit = hi;
+          break;
+        }
+        tPrev = t;
+      }
+
+      if (tHit < 0.) {
+        a = 0.;                       // the ray passed over the stone
+      } else {
+        vec3 q0 = gro + grd * tHit;
+        vec3 Nf = nHit;
+        float ndv = max(dot(Nf, -grd), 1e-3);
+        float ndl = max(dot(Nf, Ldir), 0.);
+        vec3 H = normalize(Ldir - grd);
+
+        // Shadow: march back toward the light across the crown. This is the
+        // thing a normal map can never do \u2014 one facet standing in another's
+        // light.
+        float shade = 1.;
+        for (int i = 1; i <= 10; i++) {
+          vec3 qs = q0 + Ldir * (float(i) * amp * .30);
+          vec3 nn;
+          float sz = crownZ(qs.xy, gcut, amp, gthick, nn);
+          if (qs.z < sz - .5 && scene(qs.xy) < 0.) { shade = .25; break; }
+        }
+
+        // Through the stone: refract in, cross the body, refract out at the
+        // underside.
+        float ior = 1.85;
+        vec3 rin = refract(grd, Nf, 1. / ior);
+        vec3 nn2;
+        float h2;
+        vec3 Nb2 = facetPlane((q0.xy + rin.xy * gthick * 2.) / gcut + 23.7, amp / gcut, h2);
+        vec3 rout = refract(rin, -Nb2, ior);
+        if (dot(rout, rout) < 1e-6) rout = reflect(rin, -Nb2);
+
+        float disp = .06 * max(uDisp, .001) * 6.;
+        vec2 off2 = rout.xy * gthick * 4.;
+        vec3 thru = toLinear(vec3(
+          seen(p + off2 * (1. + disp), fr).r,
+          seen(p + off2, fr).g,
+          seen(p + off2 * (1. - disp), fr).b
+        ));
+
+        vec3 body = toLinear(mix(vec3(.62, .48, .92), tcol, talpha));
+        vec3 lit = body * (.10 + 1.15 * ndl * shade);
+        lit += thru * body * 1.2 * (.25 + .75 * ndv);
+
+        vec3 F0 = vec3(.13);
+        float fres = pow(1. - ndv, 4.);
+        lit = mix(lit, envmap(reflect(grd, Nf), .02), F0.x + (1. - F0.x) * fres * .9);
+
+        float aa = .018 * .018;
+        lit += F_Schlick(F0, max(dot(H, -grd), 0.))
+             * D_GGX(max(dot(Nf, H), 0.), aa) * V_SmithGGX(ndv, ndl, aa) * ndl * 26. * uSpec * shade;
+        plasma = toSrgb(tonemap(lit));
+        a = 1.;
+      }
+    } else if (uMat < 3.5) {
+      bool merc = uMat > 2.5;
+      if (merc) {
+        // \u2500\u2500 mercury \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+        // Marched, not painted. The ray enters the slab, and every normal
+        // below comes from the solid's own gradient \u2014 which is what makes a
+        // bead read as a bead instead of a rectangle with a chrome gradient
+        // on it. Surface tension does the rest: the footprint rounds toward a
+        // disc, and two panels within reach pull into one body with a neck.
+        float thick = max(uThick, 8.);
+        float tension = clamp(uTension, 0., 1.);
+        vec3 ro = vec3(p, thick * 3.5);
+        vec3 rd = normalize(vec3((p - uMouse) * .00035, -1.));   // a hair of perspective
+        float t = 0., hit = -1.;
+        for (int i = 0; i < 96; i++) {
+          vec3 q = ro + rd * t;
+          float dd = map3(q, tension, thick);
+          if (dd < .35) { hit = t; break; }
+          t += max(dd * .30, .25);
+          if (t > thick * 8.) break;
+        }
+        if (hit < 0.) {
+          a = 0.;                       // the march missed: leave the ground
+        } else {
+          vec3 q = ro + rd * hit;
+          vec3 Nm = normal3(q, tension, thick);
+          float ndv = max(dot(Nm, -rd), 1e-3);
+          float ndl = max(dot(Nm, Ldir), 0.);
+          vec3 H = normalize(Ldir - rd);
+          vec3 R = reflect(rd, Nm);
+
+          float rough = .04;
+          // A real reflection off a real normal, of the studio and of what is
+          // actually behind the bead.
+          vec2 roff = R.xy * 210.;
+          vec3 env = mix(envmap(R, rough), toLinear(seen(p - roff, rough)), .30);
+          vec3 F0 = mix(vec3(.86, .87, .90), toLinear(tcol), talpha);
+          vec3 Fr = F_Schlick(F0, ndv);
+          float aa = max(rough * rough, 1e-4);
+          vec3 sun = F_Schlick(F0, max(dot(H, -rd), 0.))
+                   * D_GGX(max(dot(Nm, H), 0.), aa)
+                   * V_SmithGGX(ndv, ndl, aa) * ndl;
+          vec3 me = env * Fr + sun * 16. * uSpec;
+          me += F0 * .03;
+          // Shimmer comes from the modelled swell moving under a sharp
+          // highlight, not from a noise field tinting the surface. The only
+          // colour added is thin-film interference, which is a function of the
+          // angle the geometry presents \u2014 no texture in it.
+          me += toLinear(pal(pow(1. - ndv, 1.6) * 1.4)) * .12 * uShim * pow(1. - ndv, .9);
+          plasma = toSrgb(tonemap(me));
+          // The silhouette is the march's, so a bead that has pulled away from
+          // the rectangle actually looks pulled away.
+          a = 1.;
+        }
+      } else {
+        // \u2500\u2500 metal \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+        // Milled, not poured: flat stock with a cut edge. Still the screen
+        // space path, which is honest for a flat sheet.
+        float rough = clamp(uRough, .04, .95);
+        vec3 Nm = Nb;
+        float aniso = uAniso;
+        if (aniso > .01) {
+          float brush = fbm(vec2(p.x * .9, p.y * 22.)) - .5;
+          Nm = normalize(Nm + vec3(0., brush * aniso * .55, 0.));
+        }
+        float mr = fbm(p * .035) - .5;
+        Nm = normalize(Nm + vec3(mr * .16, (fbm(p * .035 + 11.) - .5) * .16, 0.));
+        float ndv = max(dot(Nm, V), 1e-3);
+        float ndl = max(dot(Nm, Ldir), 0.);
+        vec3 H = normalize(Ldir + V);
+        vec3 R = reflect(-V, Nm);
+        vec2 roff = R.xy * pow(bevel, .9) * 150. * (1. - rough * .5);
+        vec3 env = mix(envmap(R, rough), toLinear(seen(p - roff, rough)), .22);
+        vec3 F0 = mix(vec3(.95, .93, .88), toLinear(tcol), talpha);
+        vec3 Fr = F_Schlick(F0, ndv);
+        float aa = max(rough * rough, 1e-3);
+        float D = aniso > .01
+          ? D_GGXaniso(max(dot(Nm, H), 0.), dot(vec3(1.,0.,0.), H), dot(vec3(0.,1.,0.), H), aa * (1. + aniso * 3.), aa)
+          : D_GGX(max(dot(Nm, H), 0.), aa);
+        vec3 sun = F_Schlick(F0, max(dot(H, V), 0.)) * D * V_SmithGGX(ndv, ndl, aa) * ndl;
+        vec3 me = env * Fr + sun * 14. * uSpec;
+        me += F0 * .035;
+        plasma = toSrgb(tonemap(me));
+      }
+    } else if (uMat < 4.5) {
+      // \u2500\u2500 wood \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+      // Grain lives in page coordinates, so a panel that resizes keeps its
+      // grain instead of stretching it \u2014 the first thing an opaque natural
+      // material asks for that glass never did.
+      vec2 wp = p * .0021;
+      // Rings are warped, then squeezed across one axis: straight fbm reads as
+      // camouflage, warped fbm reads as a board cut from a trunk.
+      vec2 wq = warp(vec2(wp.x * .40, wp.y * 4.2), .55);
+      float ring = fract(fbm(wq) * 2.05);
+      float band = abs(ring - .5) * 2.;
+      float pore = fbm(vec2(p.x * .18, p.y * .022));
+      float h0 = band * .7 + pore * .3;
+      // Detail normal by finite difference of that height, so the grain
+      // actually catches the light instead of being painted on.
+      vec2 e = vec2(1.4, 0.);
+      float hx = fract(fbm(warp(vec2((wp.x + e.x*.0021) * .40, wp.y * 4.2), .55)) * 2.05);
+      float hy = fract(fbm(warp(vec2(wp.x * .40, (wp.y + e.x*.0021) * 4.2), .55)) * 2.05);
+      hx = abs(hx - .5) * 2.; hy = abs(hy - .5) * 2.;
+      vec3 Nw = normalize(Nb + vec3((hx - band) * .85, (hy - band) * .85, 0.));
+
+      // Real boards are lower contrast than the first instinct: a wide dark-to
+      // -light sweep reads as charring, not as timber.
+      vec3 lightWood = toLinear(vec3(.62, .45, .28));
+      vec3 darkWood  = toLinear(vec3(.40, .26, .145));
+      // A board is mostly one tone with the grain reading as a whisper over it.
+      vec3 alb = mix(darkWood, lightWood, smoothstep(.30, .70, band) * .55 + .22);
+      alb *= .95 + .09 * pore;
+      alb = mix(alb, toLinear(tcol), talpha * .6);
+
+      float ndv = max(dot(Nw, V), 1e-3);
+      float ndl = max(dot(Nw, Ldir), 0.);
+      vec3 H = normalize(Ldir + V);
+      // Anisotropic along the grain: a varnished board's highlight is a streak.
+      float aa = .34 * .34;
+      float D = D_GGXaniso(max(dot(Nw, H), 0.), dot(vec3(1.,0.,0.), H), dot(vec3(0.,1.,0.), H), aa * 4., aa);
+      vec3 F = F_Schlick(vec3(.045), max(dot(H, V), 0.));
+      vec3 wo = alb * (.16 + .95 * ndl);
+      wo += F * D * V_SmithGGX(ndv, ndl, aa) * ndl * 5.5 * uSpec;
+      wo += alb * pow(1. - ndv, 3.5) * .35;
+      plasma = toSrgb(tonemap(wo));
+    } else if (uMat < 5.5) {
+      // \u2500\u2500 stone \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+      vec2 sq = warp(p * .022, .9);
+      float body = fbm(sq) * .62 + fbm(sq * 3.7) * .26 + fbm(sq * 11.) * .12;
+      float fleck = hash(floor(p * 2.2));
+      float vein = smoothstep(.52, .58, fbm(sq * .55 + 7.1));
+      float h0 = body + (fleck - .5) * .35;
+      float hx = fbm(warp((p + vec2(1.6, 0.)) * .022, .9)) + (hash(floor((p + vec2(1.6,0.)) * 2.2)) - .5) * .35;
+      float hy = fbm(warp((p + vec2(0., 1.6)) * .022, .9)) + (hash(floor((p + vec2(0.,1.6)) * 2.2)) - .5) * .35;
+      vec3 Ns = normalize(Nb + vec3((hx - h0) * 3.4, (hy - h0) * 3.4, 0.));
+
+      vec3 alb = mix(toLinear(vec3(.24, .235, .25)), toLinear(vec3(.55, .545, .55)), body);
+      alb = mix(alb, toLinear(vec3(.70, .69, .67)), vein * .5);
+      alb *= .92 + (fleck - .5) * .18;
+      alb = mix(alb, toLinear(tcol), talpha * .6);
+
+      float ndv = max(dot(Ns, V), 1e-3);
+      float ndl = max(dot(Ns, Ldir), 0.);
+      vec3 H = normalize(Ldir + V);
+      float aa = .72 * .72;                             // stone is rough
+      vec3 F = F_Schlick(vec3(.035), max(dot(H, V), 0.));
+      vec3 st = alb * (.20 + .95 * ndl);
+      st += F * D_GGX(max(dot(Ns, H), 0.), aa) * V_SmithGGX(ndv, ndl, aa) * ndl * 3.2 * uSpec;
+      st += alb * pow(1. - ndv, 4.) * .25;              // dusty edge
+      plasma = toSrgb(tonemap(st));
+    } else {
+      // \u2500\u2500 cloud \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+      // The one volume. The SDF is the boundary, density is noise inside it,
+      // and the light is marched rather than dotted: transmittance by
+      // Beer-Lambert, scattering by Henyey-Greenstein. A lambert cloud looks
+      // painted; a marched one looks lit from a direction.
+      // Bounded tight to the silhouette, which the edge displacement has
+      // already made billowy \u2014 the panel's outline is the cloud's outline. The
+      // interior is dense, so it reads as a thing made of cloud rather than as
+      // haze lying over a rectangle.
+      float inside = smoothstep(-1., 9., sd);
+      vec2 dq = warp(p * .0058 + vec2(uTime * .010, uTime * .004), 1.15);
+      float base = fbm(dq) * .58 + fbm(dq * 2.7) * .28 + fbm(dq * 6.9) * .14;
+      float dens = clamp(inside * (.55 + base * 1.15) - .12, 0., 1.);
+
+      // March toward the light and accumulate what it has to pass through.
+      float shadow = 0.;
+      vec2 step2 = normalize(Ldir.xy + vec2(1e-4)) * 16.;
+      for (int i = 1; i <= 5; i++) {
+        vec2 sp3 = p + step2 * float(i);
+        float ins = smoothstep(-1., 9., sd + float(i) * 5.);
+        vec2 q3 = warp(sp3 * .0058 + vec2(uTime * .010, uTime * .004), 1.15);
+        shadow += clamp(ins * (.55 + fbm(q3) * 1.15) - .12, 0., 1.);
+      }
+      float transmit = exp(-shadow * .55);
+      float cosT = dot(normalize(vec3(n, .6)), Ldir);
+      float g = .45;
+      float hg = (1. - g*g) / pow(1. + g*g - 2.*g*cosT, 1.5) * .0796;
+      vec3 sunCol = toLinear(vec3(1., .96, .89));
+      vec3 skyCol = toLinear(vec3(.42, .50, .64));
+      vec3 cl = skyCol * (.35 + .65 * dens) + sunCol * transmit * (.55 + 5.5 * hg);
+      cl = mix(cl, toLinear(tcol), talpha * .45);
+      plasma = toSrgb(tonemap(cl));
+      a = smoothstep(.04, .42, dens);   // density is the coverage, not the outline
+    }
+
     col = mix(col, plasma, a);
     grain = 1. - a;   // grain is background-only; panels stay clean
+    cover = a;
+  }
+  if (uClear > .5) {
+    // Outside a surface only its shadow lands on the page: black at the
+    // shadow's darkness. Inside, the surface itself. The edge blends the two
+    // by coverage, un-premultiplied for a non-premultiplied canvas.
+    float shade = clamp(shStr * smoothstep(.02, .55, hs) * (1. - uLight*.6), 0., 1.);
+    float alpha = max(cover, shade);
+    o = vec4(col * (cover / max(alpha, 1e-4)), alpha);
+    return;
   }
   // Keyed on viewport position, so a frame drawn for a taller region has the
   // same grain in its viewport band as the live frame that replaces it.
-  col += (hash(p - uView.xy + uTime) - .5) * .025 * grain;
+  col += (hash(p - uView.xy + uTime) - .5) * .025 * grain * uGrain;
   o = vec4(col, 1.);
 }`;
   return { maskFrag, tintFrag, blurFrag, bgFrag, compFrag };
@@ -312,6 +909,14 @@ function hexToRgb(hex) {
 }
 
 // src/renderer.ts
+var MATERIALS = ["plasma", "crystal", "metal", "mercury", "wood", "stone", "cloud"];
+var FORMING_ATTR = "data-plasma-forming";
+var FORMING_EVENT = "plasmaforming";
+var FORMED_EVENT = "plasmaformed";
+function dispatch(el, name, id) {
+  if (typeof CustomEvent === "undefined" || typeof el.dispatchEvent !== "function") return;
+  el.dispatchEvent(new CustomEvent(name, { bubbles: true, detail: { id } }));
+}
 var UNIFORMS = [
   "uRes",
   "uView",
@@ -361,7 +966,21 @@ var UNIFORMS = [
   "uRimColor",
   "uRimWidth",
   "uSpec",
-  "uHair"
+  "uHair",
+  "uShim",
+  "uGlow",
+  "uWash",
+  "uGrain",
+  "uClear",
+  "uMat",
+  "uLightDir",
+  "uRough",
+  "uAniso",
+  "uEdge",
+  "uEdgeScale",
+  "uEdgeSharp",
+  "uThick",
+  "uTension"
 ];
 var MASK_SCALE = 0.5;
 var MAX_PIXELS = 26e5;
@@ -423,6 +1042,13 @@ var _PlasmaRenderer = class _PlasmaRenderer {
     this.floatOK = false;
     /** True between webglcontextlost and webglcontextrestored: draw nothing. */
     this.lost = false;
+    this.warnedOverflow = false;
+    /**
+     * Set by destroy(). The canvas and its context outlive this renderer, so an
+     * async callback that lands afterwards would happily allocate on a context
+     * nothing can free it from.
+     */
+    this.destroyed = false;
     /** Everything initGL() created, so destroy() can free it by hand. */
     this.owned = { tex: [], fb: [], prog: [], buf: [] };
     this.recs = /* @__PURE__ */ new Map();
@@ -471,8 +1097,13 @@ var _PlasmaRenderer = class _PlasmaRenderer {
     this.onContextRestored = () => {
       this.lost = false;
       this.initGL();
-      this.applyResize();
       this.last = 0;
+      if (this.frozen) {
+        clearTimeout(this.scrollIdle);
+        this.thaw();
+        return;
+      }
+      this.applyResize();
       if (!document.hidden && !this.raf) this.raf = requestAnimationFrame(this.frame);
     };
     /**
@@ -608,6 +1239,11 @@ var _PlasmaRenderer = class _PlasmaRenderer {
           r.formV += (170 * (1 - r.form) - 26 * r.formV) * dt;
           r.form += r.formV * dt;
         } else r.form = 1;
+        if (r.forming && r.form > 0.985) {
+          r.forming = false;
+          r.el.removeAttribute(FORMING_ATTR);
+          dispatch(r.el, FORMED_EVENT, r.id);
+        }
         const b = elementBox(r.el);
         r.box = b;
         if (b.w === 0 || b.l > right || b.t > bottom || b.l + b.w < left || b.t + b.h < top) {
@@ -704,6 +1340,10 @@ var _PlasmaRenderer = class _PlasmaRenderer {
         r.drawn = { l, t, w: rgt - l, h: btm - t };
       });
       this.drawnScroll = [scrollX, scrollY];
+      if (list.length > this.max && !this.warnedOverflow) {
+        this.warnedOverflow = true;
+        console.warn(`[plasma-ui] ${list.length} plasma surfaces are on screen but maxSurfaces is ${this.max}; the rest are not drawn. Raise maxSurfaces on <PlasmaProvider>.`);
+      }
       this.lastList = list.slice(0, this.max);
       this.draw(this.lastList);
     };
@@ -714,13 +1354,7 @@ var _PlasmaRenderer = class _PlasmaRenderer {
     this.gl = gl;
     this.settings = settings;
     this.max = Math.max(1, Math.round(settings.maxSurfaces || DEFAULT_MAX_SHAPES));
-    this.P = new Float32Array(this.max * 4);
-    this.R = new Float32Array(this.max * 4);
-    this.F = new Float32Array(this.max);
-    this.T = new Float32Array(this.max * 4);
-    this.FR = new Float32Array(this.max);
-    this.EL = new Float32Array(this.max);
-    this.SOLO = new Float32Array(this.max);
+    this.allocUniformArrays();
     this.initGL();
     this.mouse.x = this.mouse.tx = innerWidth / 2;
     this.mouse.y = this.mouse.ty = innerHeight / 2;
@@ -736,7 +1370,11 @@ var _PlasmaRenderer = class _PlasmaRenderer {
   }
   /** Returns null when WebGL2 is unavailable. */
   static create(canvas, settings) {
-    const gl = canvas.getContext("webgl2", { antialias: false, premultipliedAlpha: false });
+    const gl = canvas.getContext("webgl2", {
+      antialias: false,
+      premultipliedAlpha: false,
+      preserveDrawingBuffer: !!settings.preserveDrawingBuffer
+    });
     if (!gl) return null;
     try {
       return new _PlasmaRenderer(canvas, gl, settings);
@@ -771,7 +1409,7 @@ var _PlasmaRenderer = class _PlasmaRenderer {
       gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
       this.imgTex = tex;
       const up = (source, w, h) => {
-        if (!w || !h) return;
+        if (this.destroyed || !w || !h) return;
         gl.bindTexture(gl.TEXTURE_2D, this.imgTex);
         gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
         gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, gl.RGBA, gl.UNSIGNED_BYTE, source);
@@ -786,7 +1424,7 @@ var _PlasmaRenderer = class _PlasmaRenderer {
         const img2 = src;
         if (img2.complete && img2.naturalWidth) up(img2, img2.naturalWidth, img2.naturalHeight);
         else img2.addEventListener("load", () => {
-          if (this.imgSrc === src) up(img2, img2.naturalWidth, img2.naturalHeight);
+          if (!this.destroyed && this.imgSrc === src) up(img2, img2.naturalWidth, img2.naturalHeight);
         }, { once: true });
       }
       return;
@@ -800,7 +1438,7 @@ var _PlasmaRenderer = class _PlasmaRenderer {
     const img = new Image();
     img.crossOrigin = "anonymous";
     img.onload = () => {
-      if (this.imgSrc !== src) return;
+      if (this.destroyed || this.imgSrc !== src) return;
       const tex = gl.createTexture();
       gl.bindTexture(gl.TEXTURE_2D, tex);
       gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
@@ -818,7 +1456,12 @@ var _PlasmaRenderer = class _PlasmaRenderer {
   }
   configure(s, immediate = false) {
     const qualityChanged = s.quality !== this.settings.quality;
+    const max = Math.max(1, Math.round(s.maxSurfaces || DEFAULT_MAX_SHAPES));
     this.settings = s;
+    if (max !== this.max) {
+      this.setMax(max);
+      return;
+    }
     this.loadBackground(s.background ?? null);
     this.colorTarget = s.colors.map(hexToRgb);
     if (immediate) {
@@ -836,6 +1479,7 @@ var _PlasmaRenderer = class _PlasmaRenderer {
       form: this.settings.reducedMotion ? 1 : 0,
       formV: 0,
       removing: false,
+      forming: false,
       lx: 0,
       ly: 0,
       leanCss: "",
@@ -853,6 +1497,11 @@ var _PlasmaRenderer = class _PlasmaRenderer {
       drawn: null,
       elevNow: -1
     };
+    if (!this.settings.reducedMotion && typeof el.setAttribute === "function") {
+      rec.forming = true;
+      el.setAttribute(FORMING_ATTR, "");
+      dispatch(el, FORMING_EVENT, id);
+    } else dispatch(el, FORMED_EVENT, id);
     this.recs.set(id, rec);
     return {
       id,
@@ -868,16 +1517,22 @@ var _PlasmaRenderer = class _PlasmaRenderer {
       remove: () => {
         el.style.translate = "";
         el.style.scale = "";
+        if (rec.forming) el.removeAttribute(FORMING_ATTR);
         this.recs.delete(id);
       }
     };
   }
-  /** Layout boxes of all shapes (lean removed; animating draggables report their destination). */
-  layoutBoxes(excludeId, fusingOnly = false) {
+  /**
+   * Layout boxes of all shapes (lean removed; animating draggables report
+   * their destination). Pass `group` to see only the surfaces in that group;
+   * omit it - as any caller written before groups existed does - to see them all.
+   */
+  layoutBoxes(excludeId, fusingOnly = false, group) {
     const out = [];
     this.recs.forEach((r) => {
       if (r.id === excludeId) return;
       if (fusingOnly && r.fuse === false) return;
+      if (group !== void 0 && (r.group ?? null) !== group) return;
       out.push(this.layoutBoxOf(r));
     });
     return out;
@@ -903,6 +1558,39 @@ var _PlasmaRenderer = class _PlasmaRenderer {
   bump(e) {
     this.energy = Math.max(this.energy, Math.min(e, 1));
   }
+  /** Rebuild the shaders and uniform arrays for a new surface budget. */
+  setMax(max) {
+    this.max = max;
+    this.allocUniformArrays();
+    this.releaseGL();
+    this.initGL();
+    this.applyResize();
+    this.warnedOverflow = false;
+  }
+  allocUniformArrays() {
+    this.P = new Float32Array(this.max * 4);
+    this.R = new Float32Array(this.max * 4);
+    this.F = new Float32Array(this.max);
+    this.T = new Float32Array(this.max * 4);
+    this.FR = new Float32Array(this.max);
+    this.EL = new Float32Array(this.max);
+    this.SOLO = new Float32Array(this.max);
+  }
+  /** Delete every GL object this renderer created, leaving the canvas usable. */
+  releaseGL() {
+    const gl = this.gl;
+    if (!gl.isContextLost()) {
+      this.owned.tex.forEach((t) => gl.deleteTexture(t));
+      this.owned.fb.forEach((f) => gl.deleteFramebuffer(f));
+      this.owned.prog.forEach((pr) => gl.deleteProgram(pr));
+      this.owned.buf.forEach((b) => gl.deleteBuffer(b));
+      if (this.imgTex) gl.deleteTexture(this.imgTex);
+    }
+    this.imgTex = null;
+    this.imgSrc = null;
+    this.srcEl = null;
+    this.owned = { tex: [], fb: [], prog: [], buf: [] };
+  }
   /**
    * Every GL object this renderer owns. A lost context invalidates all of
    * them, so creation lives here rather than in the constructor: the restore
@@ -911,6 +1599,9 @@ var _PlasmaRenderer = class _PlasmaRenderer {
   initGL() {
     const gl = this.gl;
     this.owned = { tex: [], fb: [], prog: [], buf: [] };
+    this.imgTex = null;
+    this.imgSrc = null;
+    this.srcEl = null;
     this.floatOK = !!gl.getExtension("EXT_color_buffer_float");
     const sh = makeShaders(this.max);
     this.progs = { bg: this.program(sh.bgFrag), mask: this.program(sh.maskFrag), tint: this.program(sh.tintFrag), blur: this.program(sh.blurFrag), comp: this.program(sh.compFrag) };
@@ -934,6 +1625,7 @@ var _PlasmaRenderer = class _PlasmaRenderer {
     this.canvas.width = this.canvas.height = 0;
   }
   destroy() {
+    this.destroyed = true;
     cancelAnimationFrame(this.raf);
     clearTimeout(this.resizeSettle);
     this.canvas.removeEventListener("webglcontextlost", this.onContextLost);
@@ -949,14 +1641,7 @@ var _PlasmaRenderer = class _PlasmaRenderer {
       r.el.style.scale = "";
     });
     this.recs.clear();
-    const gl = this.gl;
-    if (!gl.isContextLost()) {
-      this.owned.tex.forEach((t) => gl.deleteTexture(t));
-      this.owned.fb.forEach((f) => gl.deleteFramebuffer(f));
-      this.owned.prog.forEach((pr) => gl.deleteProgram(pr));
-      this.owned.buf.forEach((b) => gl.deleteBuffer(b));
-    }
-    this.owned = { tex: [], fb: [], prog: [], buf: [] };
+    this.releaseGL();
   }
   freeze() {
     const c = this.canvas;
@@ -1033,6 +1718,8 @@ var _PlasmaRenderer = class _PlasmaRenderer {
       gl.uniform3fv(u.uA, this.colors[0]);
       gl.uniform3fv(u.uB, this.colors[1]);
       gl.uniform3fv(u.uC, this.colors[2]);
+      gl.uniform1f(u.uTension, s.tension);
+      gl.uniform1f(u.uThick, s.thickness);
     };
     const bl = this.progs.blur;
     const pass = (src, dst, dx, dy) => {
@@ -1068,12 +1755,25 @@ var _PlasmaRenderer = class _PlasmaRenderer {
     const bc = this.bgColor;
     gl.uniform3f(this.progs.bg.u.uBgColor, bc?.[0] ?? 0, bc?.[1] ?? 0, bc?.[2] ?? 0);
     gl.uniform1f(this.progs.bg.u.uBgSolid, bc ? 1 : 0);
+    gl.uniform1f(this.progs.bg.u.uClear, s.ground === "clear" ? 1 : 0);
     gl.drawArrays(gl.TRIANGLES, 0, 3);
     gl.activeTexture(gl.TEXTURE0);
     gl.viewport(0, 0, this.rtA.w, this.rtA.h);
     gl.useProgram(bl.pr);
     gl.uniform1i(bl.u.uTex, 0);
     gl.activeTexture(gl.TEXTURE0);
+    const bgBlur = Math.min(40, Math.max(0, s.backgroundBlur || 0));
+    if (bgBlur > 0) {
+      const step = bgBlur * this.dpr * MASK_SCALE / 4;
+      pass(this.rtBg, this.rtBgM, 0, 0);
+      for (let i = 0; i < 3; i++) {
+        pass(this.rtBgM, this.rtB, step, 0);
+        pass(this.rtB, this.rtBgM, 0, step);
+      }
+      gl.viewport(0, 0, this.rtBg.w, this.rtBg.h);
+      pass(this.rtBgM, this.rtBg, 0, 0);
+      gl.viewport(0, 0, this.rtA.w, this.rtA.h);
+    }
     const n = list.length;
     let hasFrost = false, hasTint = false, hasElev = false;
     for (let i = 0; i < n; i++) {
@@ -1081,7 +1781,8 @@ var _PlasmaRenderer = class _PlasmaRenderer {
       if (this.T[i * 4 + 3] > 2e-3) hasTint = true;
       if (this.EL[i] > 2e-3) hasElev = true;
     }
-    if (hasFrost) {
+    const reflective = s.material === "metal" || s.material === "crystal";
+    if (hasFrost || reflective) {
       pass(this.rtBg, this.rtB, 1.5 * k, 0);
       pass(this.rtB, this.rtBgM, 0, 2.5 * k);
       pass(this.rtBgM, this.rtB, 2.5 * k, 0);
@@ -1140,6 +1841,20 @@ var _PlasmaRenderer = class _PlasmaRenderer {
     gl.uniform1f(c.u.uRimWidth, s.rimWidth);
     gl.uniform1f(c.u.uSpec, s.highlight);
     gl.uniform1f(c.u.uHair, s.edgeLine);
+    gl.uniform1f(c.u.uShim, s.shimmer);
+    gl.uniform1f(c.u.uGlow, s.glow);
+    gl.uniform1f(c.u.uWash, s.wash);
+    gl.uniform1f(c.u.uGrain, s.grain);
+    gl.uniform1f(c.u.uClear, s.ground === "clear" ? 1 : 0);
+    gl.uniform1f(c.u.uMat, Math.max(0, MATERIALS.indexOf(s.material)));
+    gl.uniform3f(c.u.uLightDir, s.lightDir[0], s.lightDir[1], s.lightDir[2]);
+    gl.uniform1f(c.u.uRough, s.roughness);
+    gl.uniform1f(c.u.uAniso, s.anisotropy);
+    gl.uniform1f(c.u.uEdge, s.edge);
+    gl.uniform1f(c.u.uEdgeScale, s.edgeScale);
+    gl.uniform1f(c.u.uEdgeSharp, s.edgeSharpness);
+    gl.uniform1f(c.u.uThick, s.thickness);
+    gl.uniform1f(c.u.uTension, s.tension);
     gl.activeTexture(gl.TEXTURE0);
     gl.bindTexture(gl.TEXTURE_2D, this.rtC.tex);
     gl.activeTexture(gl.TEXTURE1);
@@ -1186,15 +1901,40 @@ var _PlasmaRenderer = class _PlasmaRenderer {
       const sh = gl.createShader(type);
       gl.shaderSource(sh, src);
       gl.compileShader(sh);
-      if (!gl.getShaderParameter(sh, gl.COMPILE_STATUS)) throw new Error(gl.getShaderInfoLog(sh) || "shader compile failed");
+      if (!gl.getShaderParameter(sh, gl.COMPILE_STATUS)) {
+        const log = gl.getShaderInfoLog(sh);
+        gl.deleteShader(sh);
+        throw new Error(log || "shader compile failed");
+      }
       return sh;
     };
     const pr = gl.createProgram();
-    gl.attachShader(pr, compile(gl.VERTEX_SHADER, vert));
-    gl.attachShader(pr, compile(gl.FRAGMENT_SHADER, fsrc));
-    gl.bindAttribLocation(pr, 0, "p");
-    gl.linkProgram(pr);
-    if (!gl.getProgramParameter(pr, gl.LINK_STATUS)) throw new Error(gl.getProgramInfoLog(pr) || "program link failed");
+    const attached = [];
+    try {
+      const vs = compile(gl.VERTEX_SHADER, vert);
+      let fs;
+      try {
+        fs = compile(gl.FRAGMENT_SHADER, fsrc);
+      } catch (e) {
+        gl.deleteShader(vs);
+        throw e;
+      }
+      gl.attachShader(pr, vs);
+      attached.push(vs);
+      gl.attachShader(pr, fs);
+      attached.push(fs);
+      gl.bindAttribLocation(pr, 0, "p");
+      gl.linkProgram(pr);
+      if (!gl.getProgramParameter(pr, gl.LINK_STATUS)) throw new Error(gl.getProgramInfoLog(pr) || "program link failed");
+    } catch (e) {
+      gl.deleteProgram(pr);
+      throw e;
+    } finally {
+      attached.forEach((sh) => {
+        gl.detachShader(pr, sh);
+        gl.deleteShader(sh);
+      });
+    }
     const u = {};
     UNIFORMS.forEach((n) => {
       u[n] = gl.getUniformLocation(pr, n);
@@ -1223,21 +1963,35 @@ var PlasmaRenderer = _PlasmaRenderer;
 import { jsx, jsxs } from "react/jsx-runtime";
 var noop = () => {
 };
-var PlasmaContext = createContext({
-  renderer: null,
+var DEFAULT_RUNTIME = { renderer: null, supported: false, reducedMotion: false, pulse: noop, bump: noop };
+var DEFAULT_DEFAULTS = {
   tint: "#ffffff",
   opacity: 0,
   frost: 0,
   radius: 26,
-  supported: false,
   grid: 24,
   magnet: 40,
-  spring: { stiffness: 170, damping: 16 },
-  reducedMotion: false,
-  pulse: noop,
-  bump: noop
-});
-var usePlasma = () => useContext(PlasmaContext);
+  spring: { stiffness: 170, damping: 16 }
+};
+var RuntimeContext = createContext(DEFAULT_RUNTIME);
+var DefaultsContext = createContext(DEFAULT_DEFAULTS);
+var AttachContext = createContext(null);
+var usePlasmaRuntime = () => useContext(RuntimeContext);
+var usePlasmaDefaults = () => useContext(DefaultsContext);
+function usePlasma() {
+  const runtime = usePlasmaRuntime();
+  const defaults = usePlasmaDefaults();
+  return useMemo(() => ({ ...runtime, ...defaults }), [runtime, defaults]);
+}
+var DEV = typeof process !== "undefined" && true;
+var useIsoLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
+function useLatest(value) {
+  const ref = useRef(value);
+  useIsoLayoutEffect(() => {
+    ref.current = value;
+  });
+  return ref;
+}
 var FALLBACK_CSS = `
 .plasma-panel{box-sizing:border-box}
 .plasma-fallback{
@@ -1260,6 +2014,31 @@ function useReducedMotion() {
   }, []);
   return reduced;
 }
+function PlasmaCanvas({ className, style, zIndex = -1 }) {
+  const attach = useContext(AttachContext);
+  const { supported } = usePlasmaRuntime();
+  useEffect(() => {
+    if (DEV && !attach) console.warn("[plasma-ui] <PlasmaCanvas> must be rendered inside a <PlasmaProvider>.");
+  }, [attach]);
+  return /* @__PURE__ */ jsx(
+    "canvas",
+    {
+      ref: attach ?? void 0,
+      "aria-hidden": "true",
+      className,
+      style: {
+        position: "fixed",
+        inset: 0,
+        width: "100%",
+        height: "100%",
+        zIndex,
+        pointerEvents: "none",
+        display: supported ? "block" : "none",
+        ...style
+      }
+    }
+  );
+}
 function PlasmaProvider({
   children,
   mood = "tidal",
@@ -1282,6 +2061,22 @@ function PlasmaProvider({
   rimWidth = 1,
   highlight = 1,
   edgeLine = 1,
+  shimmer = 1,
+  glow = 1,
+  wash = 1,
+  grain = 1,
+  backgroundBlur = 0,
+  ground = "field",
+  preserveDrawingBuffer = false,
+  material = "plasma",
+  lightDir = [-0.42, -0.62, 0.66],
+  roughness = 0.28,
+  anisotropy = 0,
+  edge = 0,
+  edgeScale = 0.01,
+  edgeSharpness = 0,
+  thickness = 18,
+  tension = 0,
   pointerDrop = true,
   ambientDrops = false,
   grid = 24,
@@ -1289,9 +2084,10 @@ function PlasmaProvider({
   quality = 1.25,
   maxSurfaces = 16,
   zIndex = -1,
-  freezeOnScroll = false
+  freezeOnScroll = false,
+  canvas = true
 }) {
-  const canvasRef = useRef(null);
+  const [canvasEl, setCanvasEl] = useState(null);
   const [renderer, setRenderer] = useState(null);
   const [supported, setSupported] = useState(true);
   const reducedMotion = useReducedMotion();
@@ -1315,6 +2111,22 @@ function PlasmaProvider({
     rimWidth,
     highlight,
     edgeLine,
+    shimmer,
+    glow,
+    wash,
+    grain,
+    backgroundBlur,
+    ground,
+    preserveDrawingBuffer,
+    material,
+    lightDir,
+    roughness,
+    anisotropy,
+    edge,
+    edgeScale,
+    edgeSharpness,
+    thickness,
+    tension,
     viscosity,
     stretch,
     flow,
@@ -1323,91 +2135,55 @@ function PlasmaProvider({
     maxSurfaces,
     background: background ?? null
   };
-  const settingsRef = useRef(settings);
-  settingsRef.current = settings;
-  useLayoutEffect(() => {
-    const r = PlasmaRenderer.create(canvasRef.current, settingsRef.current);
+  const settingsRef = useLatest(settings);
+  useIsoLayoutEffect(() => {
+    if (!canvasEl) return;
+    const r = PlasmaRenderer.create(canvasEl, settingsRef.current);
     if (!r) {
       setSupported(false);
       return;
     }
+    setSupported(true);
     setRenderer(r);
     return () => {
       r.destroy();
       setRenderer(null);
     };
-  }, []);
+  }, [canvasEl]);
+  useEffect(() => {
+    if (!DEV || canvasEl) return;
+    const t = setTimeout(() => console.warn("[plasma-ui] PlasmaProvider has no canvas. Either leave `canvas` on, or render a <PlasmaCanvas /> inside the provider."), 0);
+    return () => clearTimeout(t);
+  }, [canvasEl]);
+  const settingsDeps = Object.values(settings).map((v) => Array.isArray(v) ? v.join() : v);
   useEffect(() => {
     renderer?.configure(settings);
-  }, [
-    renderer,
-    m.colors.join(),
-    settings.blend,
-    refraction,
-    dispersion,
-    rim,
-    smoothness,
-    settings.pointerDrop,
-    ambientDrops,
-    theme,
-    quality,
-    reducedMotion,
-    freezeOnScroll,
-    tint,
-    opacity,
-    rimColor,
-    rimWidth,
-    highlight,
-    edgeLine,
-    viscosity,
-    stretch,
-    flow,
-    frost,
-    elevation,
-    background
-  ]);
+  }, [renderer, ...settingsDeps]);
   const vis = Math.min(Math.max(viscosity, 0), 1);
   const stiffK = vis < 0.5 ? 1.6 - 1.2 * vis : 1 - 1.1 * (vis - 0.5);
   const dampK = vis < 0.5 ? 0.6 + 0.8 * vis : 1 + 1.6 * (vis - 0.5);
-  const spring = { stiffness: m.spring.stiffness * stiffK, damping: m.spring.damping * dampK * Math.sqrt(stiffK) };
-  const value = useMemo(() => ({
-    renderer,
-    tint,
-    opacity,
-    frost,
-    radius,
-    supported,
-    grid,
-    magnet,
-    spring,
-    reducedMotion,
-    pulse: (x, y, s) => renderer?.pulse(x, y, s),
-    bump: (e) => renderer?.bump(e)
-  }), [renderer, tint, opacity, frost, radius, supported, grid, magnet, spring.stiffness, spring.damping, reducedMotion]);
-  return /* @__PURE__ */ jsxs(PlasmaContext.Provider, { value, children: [
+  const stiffness = m.spring.stiffness * stiffK;
+  const damping = m.spring.damping * dampK * Math.sqrt(stiffK);
+  const rendererRef = useLatest(renderer);
+  const pulse = useCallback((x, y, s) => rendererRef.current?.pulse(x, y, s), []);
+  const bump = useCallback((e) => rendererRef.current?.bump(e), []);
+  const runtime = useMemo(
+    () => ({ renderer, supported, reducedMotion, pulse, bump }),
+    [renderer, supported, reducedMotion, pulse, bump]
+  );
+  const defaults = useMemo(
+    () => ({ tint, opacity, frost, radius, grid, magnet, spring: { stiffness, damping } }),
+    [tint, opacity, frost, radius, grid, magnet, stiffness, damping]
+  );
+  return /* @__PURE__ */ jsx(RuntimeContext.Provider, { value: runtime, children: /* @__PURE__ */ jsx(DefaultsContext.Provider, { value: defaults, children: /* @__PURE__ */ jsxs(AttachContext.Provider, { value: setCanvasEl, children: [
     /* @__PURE__ */ jsx("style", { children: FALLBACK_CSS }),
-    /* @__PURE__ */ jsx(
-      "canvas",
-      {
-        ref: canvasRef,
-        "aria-hidden": "true",
-        style: {
-          position: "fixed",
-          inset: 0,
-          width: "100%",
-          height: "100%",
-          zIndex,
-          pointerEvents: "none",
-          display: supported ? "block" : "none"
-        }
-      }
-    ),
+    canvas && /* @__PURE__ */ jsx(PlasmaCanvas, { zIndex }),
     children
-  ] });
+  ] }) }) });
 }
 
 // src/Plasma.tsx
-import { forwardRef, useCallback, useEffect as useEffect2, useLayoutEffect as useLayoutEffect2, useRef as useRef2, useState as useState2 } from "react";
+import { forwardRef, useCallback as useCallback2, useEffect as useEffect2, useRef as useRef2, useState as useState2, useSyncExternalStore } from "react";
 
 // src/spring.ts
 var now = () => typeof performance !== "undefined" ? performance.now() : Date.now();
@@ -1518,6 +2294,25 @@ function boxGap(a, b) {
 // src/Plasma.tsx
 import { jsx as jsx2 } from "react/jsx-runtime";
 var NO_DRAG = "button,a,input,textarea,select,label,[contenteditable],[data-plasma-nodrag]";
+var NO_SIDES = { top: false, right: false, bottom: false, left: false };
+var noSides = () => NO_SIDES;
+function createSidesStore() {
+  let value = NO_SIDES;
+  const subs = /* @__PURE__ */ new Set();
+  return {
+    subscribe(fn) {
+      subs.add(fn);
+      return () => {
+        subs.delete(fn);
+      };
+    },
+    get: () => value,
+    set(next) {
+      value = next;
+      subs.forEach((fn) => fn());
+    }
+  };
+}
 function fallbackTint(hex, a) {
   if (!(a > 0) || !/^#([0-9a-f]{6})$/i.test(hex)) return null;
   const n = parseInt(hex.slice(1), 16);
@@ -1527,7 +2322,12 @@ function assignRef(ref, v) {
   if (typeof ref === "function") ref(v);
   else if (ref) ref.current = v;
 }
-var Plasma = forwardRef(function Plasma2({
+function useConst(make) {
+  const ref = useRef2(null);
+  if (ref.current === null) ref.current = make();
+  return ref.current;
+}
+var PlasmaInner = forwardRef(function Plasma({
   as: Comp = "div",
   radius,
   lean = 10,
@@ -1539,12 +2339,15 @@ var Plasma = forwardRef(function Plasma2({
   padding,
   draggable = false,
   snap = true,
+  group,
   bounds,
   offset,
   defaultOffset,
   onDragStart,
   onDragEnd,
   onJoinChange,
+  onForming,
+  onFormed,
   className,
   style,
   children,
@@ -1553,29 +2356,51 @@ var Plasma = forwardRef(function Plasma2({
   tabIndex,
   ...rest
 }, ref) {
-  const plasma = usePlasma();
-  const r = radius ?? plasma.radius;
+  const runtime = usePlasmaRuntime();
+  const defaults = usePlasmaDefaults();
+  const r = radius ?? defaults.radius;
   const el = useRef2(null);
   const handle = useRef2(null);
-  const [x] = useState2(() => springValue(offset?.x ?? defaultOffset?.x ?? 0));
-  const [y] = useState2(() => springValue(offset?.y ?? defaultOffset?.y ?? 0));
+  const x = useConst(() => springValue(offset?.x ?? defaultOffset?.x ?? 0));
+  const y = useConst(() => springValue(offset?.y ?? defaultOffset?.y ?? 0));
   const dest = useRef2({ x: x.get(), y: y.get() });
   const anims = useRef2([]);
   const [dragging, setDragging] = useState2(false);
   const positioned = draggable || !!offset || !!defaultOffset;
-  const joinCb = useRef2(onJoinChange);
-  joinCb.current = onJoinChange;
-  const [sides, setSides] = useState2({ top: false, right: false, bottom: false, left: false });
-  const plasmaRef = useRef2(plasma);
-  plasmaRef.current = plasma;
-  const setRef = useCallback((node) => {
+  const joinCb = useLatest(onJoinChange);
+  const formingCb = useLatest(onForming);
+  const formedCb = useLatest(onFormed);
+  const sidesStore = useConst(createSidesStore);
+  const sides = useSyncExternalStore(sidesStore.subscribe, sidesStore.get, noSides);
+  const runtimeRef = useLatest(runtime);
+  const defaultsRef = useLatest(defaults);
+  const boundsRef = useLatest(bounds);
+  const snapRef = useLatest(snap);
+  const onDragEndRef = useLatest(onDragEnd);
+  const onDragStartRef = useLatest(onDragStart);
+  const opts = {
+    radius: r,
+    lean: lean || 0,
+    tint: tint ?? null,
+    opacity: opacity ?? null,
+    frost: frost ?? null,
+    elevation: elevation ?? null,
+    fuse,
+    group: group ?? null
+  };
+  const optsRef = useLatest(opts);
+  const setRef = useCallback2((node) => {
     el.current = node;
     assignRef(ref, node);
   }, [ref]);
-  useLayoutEffect2(() => {
-    const node = el.current, ren = plasma.renderer;
+  useIsoLayoutEffect(() => {
+    const node = el.current, ren = runtime.renderer;
     if (!node || !ren) return;
-    const h = ren.register(node, { radius: r, lean: lean || 0, tint: tint ?? null, opacity: opacity ?? null, frost: frost ?? null, elevation: elevation ?? null, fuse }, (j) => joinCb.current?.(j), setSides);
+    const onForming2 = () => formingCb.current?.();
+    const onFormed2 = () => formedCb.current?.();
+    node.addEventListener(FORMING_EVENT, onForming2);
+    node.addEventListener(FORMED_EVENT, onFormed2);
+    const h = ren.register(node, optsRef.current, (j) => joinCb.current?.(j), sidesStore.set);
     if (positioned) {
       h.setLayoutBox(() => {
         const rect = node.getBoundingClientRect();
@@ -1593,12 +2418,14 @@ var Plasma = forwardRef(function Plasma2({
     return () => {
       h.remove();
       handle.current = null;
+      node.removeEventListener(FORMING_EVENT, onForming2);
+      node.removeEventListener(FORMED_EVENT, onFormed2);
     };
-  }, [plasma.renderer, positioned]);
-  useEffect2(() => {
-    handle.current?.update({ radius: r, lean: lean || 0, tint: tint ?? null, opacity: opacity ?? null, frost: frost ?? null, elevation: elevation ?? null, fuse });
-  }, [r, lean, tint, opacity, frost, elevation, fuse]);
-  useLayoutEffect2(() => {
+  }, [runtime.renderer, positioned]);
+  useIsoLayoutEffect(() => {
+    handle.current?.update(opts);
+  }, [r, lean, tint, opacity, frost, elevation, fuse, group]);
+  useIsoLayoutEffect(() => {
     const node = el.current;
     if (!node || !positioned) return;
     const apply = () => {
@@ -1611,18 +2438,18 @@ var Plasma = forwardRef(function Plasma2({
       b();
     };
   }, [positioned]);
-  const springTo = useCallback((tx, ty, vx = 0, vy = 0) => {
+  const springTo = useCallback2((tx, ty, vx = 0, vy = 0) => {
     dest.current = { x: tx, y: ty };
     anims.current.forEach((a) => a.stop());
-    const { spring, reducedMotion } = plasmaRef.current;
-    if (reducedMotion) {
+    const { spring } = defaultsRef.current;
+    if (runtimeRef.current.reducedMotion) {
       x.set(tx);
       y.set(ty);
       anims.current = [];
       return;
     }
-    const opts = { stiffness: spring.stiffness, damping: spring.damping };
-    anims.current = [animateSpring(x, tx, { ...opts, velocity: vx }), animateSpring(y, ty, { ...opts, velocity: vy })];
+    const o = { stiffness: spring.stiffness, damping: spring.damping };
+    anims.current = [animateSpring(x, tx, { ...o, velocity: vx }), animateSpring(y, ty, { ...o, velocity: vy })];
   }, []);
   useEffect2(() => {
     if (!offset) return;
@@ -1630,15 +2457,26 @@ var Plasma = forwardRef(function Plasma2({
     springTo(offset.x, offset.y);
   }, [offset?.x, offset?.y]);
   useEffect2(() => () => anims.current.forEach((a) => a.stop()), []);
-  const boundsBox = () => {
-    const b = bounds?.current?.getBoundingClientRect();
+  useEffect2(() => {
+    if (!DEV) return;
+    if (!runtime.renderer && runtime.supported) {
+      console.warn("[plasma-ui] <Plasma> rendered outside a <PlasmaProvider>: it will draw as the plain CSS fallback.");
+    }
+    const s = style;
+    if (positioned && s && ("transform" in s || "translate" in s || "scale" in s)) {
+      console.warn("[plasma-ui] <Plasma> owns transform, translate and scale on its element. A `style` that sets any of them will fight the drag and lean animations.");
+    }
+  }, [runtime.renderer, runtime.supported, positioned, style]);
+  const boundsBox = useCallback2(() => {
+    const b = boundsRef.current?.current?.getBoundingClientRect();
     return b ? { l: b.left, t: b.top, w: b.width, h: b.height } : { l: 0, t: 0, w: innerWidth, h: innerHeight };
-  };
-  const settle = (proposed, vx = 0, vy = 0) => {
+  }, []);
+  const settle = useCallback2((proposed, vx = 0, vy = 0) => {
     const node = el.current, h = handle.current;
-    const { grid, magnet, renderer } = plasmaRef.current;
+    const { grid, magnet } = defaultsRef.current;
+    const { renderer } = runtimeRef.current;
     let target = proposed;
-    if (snap && h && renderer) {
+    if (snapRef.current && h && renderer) {
       const rect = node.getBoundingClientRect();
       const w = node.offsetWidth, hh = node.offsetHeight;
       const lo = h.leanOffset();
@@ -1646,15 +2484,15 @@ var Plasma = forwardRef(function Plasma2({
       const baseT = rect.top + (rect.height - hh) / 2 - lo.y - y.get();
       const s = snapBox(
         { l: baseL + proposed.x, t: baseT + proposed.y, w, h: hh },
-        renderer.layoutBoxes(h.id, true),
-        { grid, magnet, bounds: boundsBox(), inset: bounds ? 0 : 8 }
+        renderer.layoutBoxes(h.id, true, optsRef.current.group ?? null),
+        { grid, magnet, bounds: boundsBox(), inset: boundsRef.current ? 0 : 8 }
       );
       target = { x: s.l - baseL, y: s.t - baseT };
     }
     springTo(target.x, target.y, vx, vy);
-    onDragEnd?.(target);
-  };
-  const handlePointerDown = (e) => {
+    onDragEndRef.current?.(target);
+  }, []);
+  const handlePointerDown = useCallback2((e) => {
     onPointerDown?.(e);
     if (!draggable || e.defaultPrevented || e.button !== 0) return;
     if (e.target.closest(NO_DRAG)) return;
@@ -1672,12 +2510,12 @@ var Plasma = forwardRef(function Plasma2({
     const clamp = (v, a, b) => Math.min(Math.max(v, a), Math.max(a, b));
     handle.current?.setDragging(true);
     setDragging(true);
-    onDragStart?.();
+    onDragStartRef.current?.();
     const move = (ev) => {
       x.set(clamp(start.x + ev.clientX - start.px, minX - 40, maxX + 40));
       y.set(clamp(start.y + ev.clientY - start.py, minY - 40, maxY + 40));
       dest.current = { x: x.get(), y: y.get() };
-      plasmaRef.current.bump(Math.hypot(x.getVelocity(), y.getVelocity()) / 1800);
+      runtimeRef.current.bump(Math.hypot(x.getVelocity(), y.getVelocity()) / 1800);
     };
     const up = () => {
       node.removeEventListener("pointermove", move);
@@ -1691,17 +2529,17 @@ var Plasma = forwardRef(function Plasma2({
     node.addEventListener("pointermove", move);
     node.addEventListener("pointerup", up);
     node.addEventListener("pointercancel", up);
-  };
-  const handleKeyDown = (e) => {
+  }, [draggable, onPointerDown]);
+  const handleKeyDown = useCallback2((e) => {
     onKeyDown?.(e);
     if (!draggable || e.defaultPrevented || e.target !== el.current) return;
-    const step = plasmaRef.current.grid || 24;
+    const step = defaultsRef.current.grid || 24;
     const d = { ArrowLeft: [-step, 0], ArrowRight: [step, 0], ArrowUp: [0, -step], ArrowDown: [0, step] }[e.key];
     if (!d) return;
     e.preventDefault();
     settle({ x: dest.current.x + d[0], y: dest.current.y + d[1] });
-  };
-  const classes = ["plasma-panel", plasma.supported ? "" : "plasma-fallback", className].filter(Boolean).join(" ");
+  }, [draggable, onKeyDown]);
+  const classes = ["plasma-panel", runtime.supported ? "" : "plasma-fallback", className].filter(Boolean).join(" ");
   return /* @__PURE__ */ jsx2(
     Comp,
     {
@@ -1713,7 +2551,7 @@ var Plasma = forwardRef(function Plasma2({
           padding: `${sides.top ? padding / 2 : padding}px ${sides.right ? padding / 2 : padding}px ${sides.bottom ? padding / 2 : padding}px ${sides.left ? padding / 2 : padding}px`,
           transition: "padding 250ms ease"
         },
-        ...plasma.supported ? null : fallbackTint(tint ?? plasma.tint, opacity ?? plasma.opacity),
+        ...runtime.supported ? null : fallbackTint(tint ?? defaults.tint, opacity ?? defaults.opacity),
         ...style
       },
       "data-plasma-draggable": draggable || void 0,
@@ -1726,9 +2564,15 @@ var Plasma = forwardRef(function Plasma2({
     }
   );
 });
+var Plasma2 = PlasmaInner;
 export {
   DEFAULT_MAX_SHAPES,
-  Plasma,
+  FORMED_EVENT,
+  FORMING_ATTR,
+  FORMING_EVENT,
+  MATERIALS,
+  Plasma2 as Plasma,
+  PlasmaCanvas,
   PlasmaProvider,
   PlasmaRenderer,
   boxGap,
@@ -1736,5 +2580,7 @@ export {
   moods,
   resolveMood,
   snapBox,
-  usePlasma
+  usePlasma,
+  usePlasmaDefaults,
+  usePlasmaRuntime
 };