@cruxgarden/plasma-ui 0.2.3 → 0.3.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;
@@ -178,7 +178,7 @@ 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;
 uniform vec3 uRimColor;
 out vec4 o;
 
@@ -235,7 +235,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 +255,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;
@@ -280,7 +285,7 @@ void main(){
     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);
+    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;
 
@@ -290,7 +295,7 @@ void main(){
   }
   // 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 };
@@ -361,7 +366,11 @@ var UNIFORMS = [
   "uRimColor",
   "uRimWidth",
   "uSpec",
-  "uHair"
+  "uHair",
+  "uShim",
+  "uGlow",
+  "uWash",
+  "uGrain"
 ];
 var MASK_SCALE = 0.5;
 var MAX_PIXELS = 26e5;
@@ -419,13 +428,25 @@ var _PlasmaRenderer = class _PlasmaRenderer {
     this.imgSrc = null;
     this.bgColor = null;
     this.srcEl = null;
+    // re-uploaded each frame
+    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();
     this.nextId = 1;
     this.raf = 0;
     this.last = 0;
     this.time = 0;
     this.dpr = 1;
-    this.resizeQueued = false;
     /** Coarse pointer = touch. Only there does a fling run on the compositor with rAF deferred. */
     this.coarse = typeof matchMedia === "function" && matchMedia("(pointer: coarse)").matches;
     this.frozen = false;
@@ -450,6 +471,31 @@ var _PlasmaRenderer = class _PlasmaRenderer {
     this.lightQuery = typeof matchMedia !== "undefined" ? matchMedia("(prefers-color-scheme: light)") : null;
     this.tintCache = /* @__PURE__ */ new Map();
     this.RP = new Float32Array(MAX_PULSES * 4);
+    /**
+     * A drag-resize reallocates eight render targets per distinct size, and the
+     * driver can drop the context under that. Without these two handlers the
+     * field simply stopped: the frame loop kept running against a dead context
+     * and nothing ever brought it back. preventDefault is what asks the browser
+     * to attempt a restore at all.
+     */
+    this.onContextLost = (e) => {
+      e.preventDefault();
+      this.lost = true;
+      cancelAnimationFrame(this.raf);
+      this.raf = 0;
+    };
+    this.onContextRestored = () => {
+      this.lost = false;
+      this.initGL();
+      this.last = 0;
+      if (this.frozen) {
+        clearTimeout(this.scrollIdle);
+        this.thaw();
+        return;
+      }
+      this.applyResize();
+      if (!document.hidden && !this.raf) this.raf = requestAnimationFrame(this.frame);
+    };
     /**
      * A hidden tab draws nothing anyone can see. Browsers throttle rAF there
      * but do not all stop it, so the loop stops itself and picks up where it
@@ -511,12 +557,8 @@ var _PlasmaRenderer = class _PlasmaRenderer {
      * otherwise reallocated every texture repeatedly mid-scroll.
      */
     this.resize = () => {
-      if (this.resizeQueued) return;
-      this.resizeQueued = true;
-      requestAnimationFrame(() => {
-        this.resizeQueued = false;
-        this.applyResize();
-      });
+      clearTimeout(this.resizeSettle);
+      this.resizeSettle = setTimeout(this.applyResize, 120);
     };
     this.applyResize = () => {
       if (this.frozen) {
@@ -559,6 +601,10 @@ var _PlasmaRenderer = class _PlasmaRenderer {
       gl.bindFramebuffer(gl.FRAMEBUFFER, null);
     };
     this.frame = (now2) => {
+      if (this.lost) {
+        this.raf = 0;
+        return;
+      }
       if (!this.oneShot) this.raf = requestAnimationFrame(this.frame);
       const dt = this.last ? Math.min((now2 - this.last) / 1e3, 0.05) : 0.016;
       this.last = now2;
@@ -679,6 +725,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);
     };
@@ -689,33 +739,12 @@ 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.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) };
-    const buf = gl.createBuffer();
-    gl.bindBuffer(gl.ARRAY_BUFFER, buf);
-    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
-    gl.enableVertexAttribArray(0);
-    gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
-    this.rtA = this.target();
-    this.rtB = this.target();
-    this.rtC = this.target();
-    this.rtT = this.target();
-    this.rtFr = this.target();
-    this.rtBg = this.target();
-    this.rtBgM = this.target();
-    this.rtBgH = this.target();
-    this.mrtFb = gl.createFramebuffer();
-    this.configure(settings, true);
+    this.allocUniformArrays();
+    this.initGL();
     this.mouse.x = this.mouse.tx = innerWidth / 2;
     this.mouse.y = this.mouse.ty = innerHeight / 2;
+    canvas.addEventListener("webglcontextlost", this.onContextLost);
+    canvas.addEventListener("webglcontextrestored", this.onContextRestored);
     addEventListener("resize", this.resize);
     document.addEventListener("visibilitychange", this.onVisibility);
     if (this.coarse) addEventListener("scroll", this.onScroll, { passive: true });
@@ -761,7 +790,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);
@@ -776,7 +805,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;
@@ -790,7 +819,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);
@@ -808,7 +837,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) {
@@ -862,12 +896,17 @@ var _PlasmaRenderer = class _PlasmaRenderer {
       }
     };
   }
-  /** 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;
@@ -893,8 +932,78 @@ 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
+   * handler runs exactly the same path.
+   */
+  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) };
+    const buf = gl.createBuffer();
+    if (buf) this.owned.buf.push(buf);
+    gl.bindBuffer(gl.ARRAY_BUFFER, buf);
+    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
+    gl.enableVertexAttribArray(0);
+    gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
+    this.rtA = this.target();
+    this.rtB = this.target();
+    this.rtC = this.target();
+    this.rtT = this.target();
+    this.rtFr = this.target();
+    this.rtBg = this.target();
+    this.rtBgM = this.target();
+    this.rtBgH = this.target();
+    this.mrtFb = gl.createFramebuffer();
+    this.owned.fb.push(this.mrtFb);
+    this.configure(this.settings, true);
+    this.canvas.width = this.canvas.height = 0;
+  }
   destroy() {
+    this.destroyed = true;
     cancelAnimationFrame(this.raf);
+    clearTimeout(this.resizeSettle);
+    this.canvas.removeEventListener("webglcontextlost", this.onContextLost);
+    this.canvas.removeEventListener("webglcontextrestored", this.onContextRestored);
     removeEventListener("resize", this.resize);
     document.removeEventListener("visibilitychange", this.onVisibility);
     removeEventListener("scroll", this.onScroll);
@@ -906,7 +1015,7 @@ var _PlasmaRenderer = class _PlasmaRenderer {
       r.el.style.scale = "";
     });
     this.recs.clear();
-    this.gl.getExtension("WEBGL_lose_context")?.loseContext();
+    this.releaseGL();
   }
   freeze() {
     const c = this.canvas;
@@ -1024,6 +1133,18 @@ var _PlasmaRenderer = class _PlasmaRenderer {
     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++) {
@@ -1090,6 +1211,10 @@ 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.activeTexture(gl.TEXTURE0);
     gl.bindTexture(gl.TEXTURE_2D, this.rtC.tex);
     gl.activeTexture(gl.TEXTURE1);
@@ -1136,19 +1261,45 @@ 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);
     });
+    this.owned.prog.push(pr);
     return { pr, u };
   }
   target() {
@@ -1159,7 +1310,10 @@ var _PlasmaRenderer = class _PlasmaRenderer {
     gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
     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);
-    return { tex, fb: gl.createFramebuffer(), w: 0, h: 0 };
+    const fb = gl.createFramebuffer();
+    this.owned.tex.push(tex);
+    this.owned.fb.push(fb);
+    return { tex, fb, w: 0, h: 0 };
   }
 };
 _PlasmaRenderer.RUNWAY = 1;
@@ -1169,21 +1323,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{
@@ -1206,6 +1374,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",
@@ -1228,6 +1421,11 @@ function PlasmaProvider({
   rimWidth = 1,
   highlight = 1,
   edgeLine = 1,
+  shimmer = 1,
+  glow = 1,
+  wash = 1,
+  grain = 1,
+  backgroundBlur = 0,
   pointerDrop = true,
   ambientDrops = false,
   grid = 24,
@@ -1235,9 +1433,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();
@@ -1261,6 +1460,11 @@ function PlasmaProvider({
     rimWidth,
     highlight,
     edgeLine,
+    shimmer,
+    glow,
+    wash,
+    grain,
+    backgroundBlur,
     viscosity,
     stretch,
     flow,
@@ -1269,91 +1473,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();
@@ -1464,6 +1632,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);
@@ -1473,7 +1660,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,
@@ -1485,6 +1677,7 @@ var Plasma = forwardRef(function Plasma2({
   padding,
   draggable = false,
   snap = true,
+  group,
   bounds,
   offset,
   defaultOffset,
@@ -1499,29 +1692,45 @@ 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 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 h = ren.register(node, optsRef.current, (j) => joinCb.current?.(j), sidesStore.set);
     if (positioned) {
       h.setLayoutBox(() => {
         const rect = node.getBoundingClientRect();
@@ -1540,11 +1749,11 @@ var Plasma = forwardRef(function Plasma2({
       h.remove();
       handle.current = null;
     };
-  }, [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 = () => {
@@ -1557,18 +1766,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;
@@ -1576,15 +1785,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();
@@ -1592,15 +1812,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;
@@ -1618,12 +1838,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);
@@ -1637,17 +1857,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,
     {
@@ -1659,7 +1879,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,
@@ -1672,9 +1892,11 @@ var Plasma = forwardRef(function Plasma2({
     }
   );
 });
+var Plasma2 = PlasmaInner;
 export {
   DEFAULT_MAX_SHAPES,
-  Plasma,
+  Plasma2 as Plasma,
+  PlasmaCanvas,
   PlasmaProvider,
   PlasmaRenderer,
   boxGap,
@@ -1682,5 +1904,7 @@ export {
   moods,
   resolveMood,
   snapBox,
-  usePlasma
+  usePlasma,
+  usePlasmaDefaults,
+  usePlasmaRuntime
 };