@cruxgarden/plasma-ui 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.2.1
+
+Fixes for the reports that came in after 0.2.0, and one new option.
+
+- **Fixed:** the spring integrator diverged at small `stretch` with low
+  `viscosity` - stiffness grows as 1/stretch², and at the fixed substep
+  explicit Euler blew up, so the surface oscillated instead of settling. The
+  substep now follows the spring. Reachable from the playground: `stretch`
+  0.1 or 0.2 hit it.
+- **Fixed:** lean rewrote `translate` on every panel every frame, forcing a
+  layout each frame. It now settles and writes only on change.
+- **Fixed:** every `resize` event reallocated all render targets; a mobile
+  URL bar collapsing fired dozens per second. Coalesced to one per frame and
+  skipped when the pixel size is unchanged.
+- **New:** `freezeOnScroll` on `PlasmaProvider` (off by default). On touch
+  devices, a fling pins a three-viewport frame to the page and pauses, so the
+  compositor scrolls it with the content; rendering resumes when the scroll
+  stops. Pinned frames match live ones to within one level.
+- Passes that have nothing to do are skipped: the tint blur when no surface
+  has opacity, the frost blur when nothing is frosted or elevated, a copy
+  pass in the background chain. The loop pauses in a hidden tab. The
+  background target is 8-bit. Together, 20-40% fewer passes on clear looks;
+  pixel-identical output.
+- The canvas is capped at 2.6M pixels, trading resolution rather than frame
+  rate on 4K displays and dense phones.
+
 ## 0.2.0
 
 **Breaking:** the CSS class on every surface is `.plasma-panel`, was `.plasma-glass`.

package/README.md

@@ -1,18 +1,18 @@
 # Plasma UI
 
-Liquid panels for React. Every `<Plasma>` panel joins one shared plasma: surfaces fuse on contact, refract what's behind them, and snap to a grid when dragged. Built for workspace and canvas UIs - tool panels, dashboards, launchers - by [Crux Garden](https://github.com/cruxgarden).
+Liquid panels for React, rendered in WebGL on canvas, inspired by Apple's Liquid Glass design. The `<Plasma>` panel looks and behaves like liquid, with surface tension that fuses on contact with other panels. Anything visible behind the panel is refracted. And for layout convenience, the panels ultimately snap to a grid layout. The library is a work in progress, extracted from the [Crux Garden](https://github.com/cruxgarden) project, but it seemed useful enough to share in its current form.
 
-![Dragging a panel: it tears off its group, travels as liquid, fuses with another panel, and snaps to the grid](docs/demo.gif)
+![Five panels in a workspace: one is dragged out of its group and travels as liquid, another is dropped against a neighbour and fuses into it, and each snaps to the 24px grid](docs/demo.gif)
 
-[**Try it**](https://cruxgarden.github.io/plasma-ui/) · [workspace example](https://cruxgarden.github.io/plasma-ui/examples/workspace/)
+[Playground and Docs](https://cruxgarden.github.io/plasma-ui/) · [Workspace example](https://cruxgarden.github.io/plasma-ui/examples/workspace/)
 
-**Status: 0.1.0.** The core material is stable and tested; the API may change between minor versions before 1.0.
+**Status: 0.2.0.** Core is stable and tested, but the API may change.
 
 ```bash
 npm install @cruxgarden/plasma-ui
 ```
 
-Zero dependencies beyond React.
+Zero dependencies, except for React.
 
 ```tsx
 import { PlasmaProvider, Plasma } from "@cruxgarden/plasma-ui";
@@ -33,31 +33,7 @@ export function App() {
 
 ## Example
 
-[`examples/workspace`](examples/workspace) is a small working app - inbox, reader, tasks, and a player as draggable fused panels, with focus-driven elevation and layout persisted to localStorage. `node examples/workspace/build.mjs` builds it to a single html file.
-
-## Not yet
-
-Plasma UI 0.1 is a workspace library, not a full UI system. Know these before adopting:
-
-- **No layers.** Overlapping surfaces fuse. Dialogs, menus, toasts, and fixed bars must be plain CSS for now (the docs site's own nav shows the pattern).
-- **No clipping in scroll containers.** Plasma inside a scrollable list draws past its edges. Scrolling _inside_ one panel is fine.
-- **No drag or resize handles.** `draggable` moves the whole surface; mark interactive children `data-plasma-nodrag`.
-- **Draws its own background.** Browsers don't let WebGL read the rendered page, so the plasma refracts its background layer - the procedural mood field, or any color, image, canvas, or video you pass via `background` - rather than your live DOM. Custom background shaders aren't supported yet.
-- **Rounded rectangles only.** No rotation or arbitrary shapes.
-
-All of these are on the roadmap below.
-
-## How it works
-
-Markup stays ordinary HTML. `PlasmaProvider` renders one fixed canvas behind the page. Each frame:
-
-1. **Silhouette.** Every registered element reports its box; one shader draws them as a single shape. Corners against a neighbor square off, and blending applies only where surfaces face different ways, so flush panels share a clean outline while gaps and steps get rounded fillets.
-2. **Smoothing.** The silhouette is blurred and traced at its halfway contour, evening out curvature.
-3. **Height.** A heavier blur becomes a height map; its slope drives refraction, so joined panels act as one lens.
-4. **Tint and frost.** Color and translucency spread across the material with the same blur, so different values flow into each other across joins. The background renders once to a texture; two blurred copies serve the frosted plasma.
-5. **Light.** The final pass refracts the background, splits color at the edges, and adds a rim and a pointer highlight.
-
-Without WebGL2, `Plasma` falls back to a CSS frosted panel.
+[`examples/workspace`](examples/workspace) demonstrates how the library can be used for a real-world dashboard layout.
 
 ## `<PlasmaProvider>`
 
@@ -91,7 +67,7 @@ Without WebGL2, `Plasma` falls back to a CSS frosted panel.
 
 ## `<Plasma>`
 
-Accepts all HTML attributes plus:
+Accepts all HTML attributes, plus the following:
 
 | Prop                                    | Type                     | Default  | Description                                                                                                         |
 | --------------------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
@@ -126,19 +102,19 @@ const dusk: Mood = {
 };
 ```
 
-## Motion feel
+## Motion
 
-Each surface is a spring chasing its element, and the drawn plasma always covers the element. Moving panels leave a trailing stretch; stopping ones overshoot before settling. Scrolling doesn't count as motion.
+Each panel undulates like a Slinky when moving. Three properties control this movement: viscosity, stretch, and flow.
 
 ```tsx
 <PlasmaProvider viscosity={0.1} stretch={1.3} flow={0.6} />  // water
-<PlasmaProvider viscosity={0.85} stretch={1.8} />             // honey
-<PlasmaProvider stretch={0} />                                // the plasma tracks panels exactly
+<PlasmaProvider viscosity={0.85} stretch={1.8} />            // honey
+<PlasmaProvider stretch={0} />                               // the plasma tracks panels exactly
 ```
 
-`flow` ripples the outline, so leave it at `0` where flush edges should stay perfectly straight.
+NOTE: `flow` ripples the outline, so leave it at `0` whenever flush edges should stay perfectly straight.
 
-## Styling the rim
+## Styling the rim (fancy outline)
 
 ```tsx
 // solid cyan rim, a bit wider, no pointer highlight
@@ -155,27 +131,27 @@ Each surface is a spring chasing its element, and the drawn plasma always covers
 
 ## Guidelines
 
-- Use plasma for containers: panels, docks, cards, dialogs. Small controls read better as regular HTML on top.
-- Place surfaces either flush (they become one piece) or further apart than the blend distance. Smaller gaps render as liquid bridging.
-- Up to `maxSurfaces` (default 16) draw at once; offscreen ones are skipped first. Two render passes loop over every slot per pixel, so raise it only as far as you need.
-- Lean and pulses use the CSS `translate` and `scale` properties, and drag uses `transform`, so they compose with each other. Avoid setting those on `Plasma` elements yourself.
-- `prefers-reduced-motion` disables lean, pulses, the pointer drop, and springs.
+- Use Plasma for container components: panels, docks, cards, dialogs. Components should be nested inside.
+- Place surfaces together or further apart than the Blend distance. Smaller gaps render as liquid bridging them.
+- Up to `maxSurfaces` (default 16) draw at once; offscreen panels are skipped first. Two render passes loop over every slot per pixel, so set this value only as high as you need.
+- Lean and Pulse use the CSS `translate` and `scale` properties, and Drag uses `transform`. Avoid setting these properties on `Plasma` elements yourself.
+- `prefers-reduced-motion` disables Lean, Pulse, the pointer Drop, and Spring.
 
 ## Roadmap
 
-In priority order. Not a schedule.
+Ordered by priority:
 
-1. **Layers** - independent materials that stack instead of fusing, for dialogs, menus, and fixed chrome over plasma.
-2. **Drag handles and resize** - `handle` prop so panel content stays fully interactive; edge resize with grid snapping.
+1. **Layers** - panels that will stack instead of fusing. For use with dialogs, menus, and such.
+2. **Drag handles and resize** - will add a `handle` prop for dragging, so panel content can be fully interactive. Also, edge resizing with grid snapping.
 3. **Scroll clipping** - plasma confined to scrollable containers.
-4. **Pluggable backgrounds** - colors, images, and live canvas/video shipped in 0.1 (`background` prop); custom shaders next.
-5. **Shapes** - rotation and non-rectangular outlines.
+4. **Pluggable Backgrounds** - colors, images, and live canvas/video shipped in 0.1 (`background` prop); custom shaders are next.
+5. **Shapes and Orientation** - non-rectangular outlines, rotation...etc.
 
-Contributions welcome on any of these - see [CONTRIBUTING.md](CONTRIBUTING.md).
+Contributions welcome for any of these - see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Browser support
 
-Chrome, Edge, Firefox, and Safari 16.4+ (WebGL2). Elsewhere, `Plasma` renders as a CSS frosted panel and all layout, drag, and snap behavior still works.
+Chrome, Edge, Firefox, and Safari 16.4+ (WebGL2). In non-supported browsers, `Plasma` renders as a CSS frosted panel and all layout, drag, and snap behavior still works.
 
 ## Development
 
@@ -202,7 +178,7 @@ does — see [PUBLISH.md](PUBLISH.md).
 
 ## Used by
 
-- [Crux Garden](https://github.com/cruxgarden) - the workspace Plasma UI was built for.
+- [Crux Garden](https://github.com/cruxgarden) - the project Plasma UI was originally built for.
 
 Using it in something? Add yours in a PR.
 

package/dist/PlasmaProvider.d.ts

@@ -53,6 +53,13 @@ export interface PlasmaProviderProps {
     magnet?: number;
     /** Maximum device pixel ratio for the canvas. Default 1.25. */
     quality?: number;
+    /**
+     * Touch devices only: during a fling, pin the last drawn frame to the page
+     * and pause, so the compositor scrolls it with the content; resume when the
+     * scrolling stops. Off by default. Needs the canvas's positioned ancestor,
+     * if any, to scroll with the page.
+     */
+    freezeOnScroll?: boolean;
     /** Maximum visible plasma surfaces. Compiled into the shaders, so it is fixed for the provider's lifetime; more surfaces cost GPU time. Default 16. */
     maxSurfaces?: number;
     /** z-index of the fixed canvas. Default -1 (behind content). */
@@ -76,4 +83,4 @@ export interface PlasmaContextValue {
     bump: (energy: number) => void;
 }
 export declare const usePlasma: () => PlasmaContextValue;
-export declare function PlasmaProvider({ children, mood, theme, blend, refraction, dispersion, rim, smoothness, background, radius, tint, opacity, frost, elevation, viscosity, stretch, flow, rimColor, rimWidth, highlight, edgeLine, pointerDrop, ambientDrops, grid, magnet, quality, maxSurfaces, zIndex, }: PlasmaProviderProps): React.JSX.Element;
+export declare function PlasmaProvider({ children, mood, theme, blend, refraction, dispersion, rim, smoothness, background, radius, tint, opacity, frost, elevation, viscosity, stretch, flow, rimColor, rimWidth, highlight, edgeLine, pointerDrop, ambientDrops, grid, magnet, quality, maxSurfaces, zIndex, freezeOnScroll, }: PlasmaProviderProps): React.JSX.Element;

package/dist/index.js

@@ -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 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;
 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;
@@ -61,7 +61,7 @@ float scene(vec2 p){
   d = min(d, ds);
   if(uAmbient > .5){
     float t = uTime*.4;
-    vec2 home = vec2(uRes.x*.88, uRes.y*.74);
+    vec2 home = uView.xy + vec2(uView.z*.88, uView.w*.74);
     d = smin(d, length(p - home - vec2(cos(t),sin(t*1.3))*70.) - 38., uGoo);
     d = smin(d, length(p - home - vec2(cos(t*1.7+2.),sin(t*.9+1.))*90.) - 26., uGoo);
     d = smin(d, length(p - home - vec2(sin(t*.7),cos(t*1.1))*40.) - 20., uGoo);
@@ -139,7 +139,7 @@ vec3 bg(vec2 p){
   col = mix(col, uC, smoothstep(.55,.9, w.x*n*1.6));
   float lines = abs(fract(n*14.)-.5);
   col += (1.-smoothstep(0.,.06,lines)) * .07 * (0.6+uEnergy);
-  vec2 v = (p - vec2(0., uScroll))/uRes - .5;
+  vec2 v = (p - vec2(0., uScroll) - uView.xy)/uView.zw - .5;
   col *= .55 + .45*smoothstep(1.2,.2,length(v));
   return mix(col, mix(vec3(.90,.93,.95), col, .42), uLight);
 }
@@ -168,8 +168,8 @@ void main(){
         + vec2(fbm(q*.004 + uTime*.05) - .5, fbm(q*.004 + 31.7 - uTime*.04) - .5) * 22.)
         * (.5 + uFlow*.5);
     // cover-fit the image to the canvas
-    float sc = max(uRes.x / uImgRes.x, uRes.y / uImgRes.y);
-    vec2 uv = (q - .5*uRes) / (uImgRes * sc) + .5;
+    float sc = max(uView.z / uImgRes.x, uView.w / uImgRes.y);
+    vec2 uv = (q - uView.xy - .5*uView.zw) / (uImgRes * sc) + .5;
     o = vec4(texture(uImg, clamp(uv, 0., 1.)).rgb, 1.);
     return;
   }
@@ -232,7 +232,10 @@ void main(){
   float shStr = .5 * smoothstep(0., .12, el) * clamp(el + .35, 0., 1.);
   vec3 col = back * (1. - shStr*smoothstep(.02, .55, hs)*(1.-uLight*.6));
   float hHere = H(uv);
-  col += pal(uTime*.03 + p.x/1400.) * .06 * smoothstep(.0, .45, hHere) * (1.+uEnergy);
+  // 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);
 
   if(sd > -2.){
     vec2 th = 2. / vec2(textureSize(uH, 0));
@@ -277,7 +280,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 + p.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);
     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;
 
@@ -285,7 +288,9 @@ void main(){
     col = mix(col, plasma, a);
     grain = 1. - a;   // grain is background-only; panels stay clean
   }
-  col += (hash(p + uTime) - .5) * .025 * grain;
+  // 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;
   o = vec4(col, 1.);
 }`;
   return { maskFrag, tintFrag, blurFrag, bgFrag, compFrag };
@@ -309,6 +314,7 @@ function hexToRgb(hex) {
 // src/renderer.ts
 var UNIFORMS = [
   "uRes",
+  "uView",
   "uScale",
   "uTime",
   "uGoo",
@@ -358,6 +364,7 @@ var UNIFORMS = [
   "uHair"
 ];
 var MASK_SCALE = 0.5;
+var MAX_PIXELS = 26e5;
 function elementBox(el) {
   const r = el.getBoundingClientRect();
   const w = el.offsetWidth, h = el.offsetHeight;
@@ -405,7 +412,7 @@ function parseCssColor(src) {
   if (r) return [+r[1] / 255, +r[2] / 255, +r[3] / 255];
   return null;
 }
-var PlasmaRenderer = class _PlasmaRenderer {
+var _PlasmaRenderer = class _PlasmaRenderer {
   constructor(canvas, gl, settings) {
     this.imgTex = null;
     this.imgRes = [1, 1];
@@ -418,6 +425,21 @@ var PlasmaRenderer = class _PlasmaRenderer {
     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;
+    this.resizeWhileFrozen = false;
+    /** Scroll offset the last frame was drawn for: where the pinned image belongs on the page. */
+    this.drawnScroll = [0, 0];
+    /**
+     * The region a frame covers, in CSS px: origin is where the viewport's
+     * top-left sits inside it, size is the whole region. Normally the viewport
+     * exactly. When pinning for a fling it is three viewports tall, so the
+     * scroll has a viewport of runway above and below before it runs out.
+     */
+    this.region = { ox: 0, oy: 0, w: 0, h: 0 };
+    // viewports of runway above and below when pinned
     this.energy = 0;
     this.mouse = { x: 0, y: 0, tx: 0, ty: 0, amt: 0, target: 0 };
     this.pulses = Array.from({ length: MAX_PULSES }, () => [0, 0, -99, 0]);
@@ -428,6 +450,53 @@ 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 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
+     * left off - `last` is reset so the first frame back does not see a
+     * minute-long dt.
+     */
+    this.onVisibility = () => {
+      if (document.hidden) {
+        cancelAnimationFrame(this.raf);
+        this.raf = 0;
+      } else if (!this.raf && !this.frozen) {
+        this.last = 0;
+        this.raf = requestAnimationFrame(this.frame);
+      }
+    };
+    /**
+     * A fling on a touch device is driven by the compositor, and rAF is deferred
+     * while it runs, so anything JS repositions arrives late: the plasma trails
+     * the panels it belongs to. Instead of chasing, the canvas is pinned to the
+     * page for the duration - the last drawn frame becomes a texture that
+     * scrolls with the content, moved by the compositor with no JS in the path -
+     * and the loop resumes once the scroll events stop.
+     *
+     * The field's scroll parallax is 1:1 on these devices (see draw), so the
+     * pinned image and the first live frame after it line up.
+     */
+    this.onScroll = () => {
+      if (!this.settings.freezeOnScroll) return;
+      if (!this.frozen) this.freeze();
+      clearTimeout(this.scrollIdle);
+      this.scrollIdle = setTimeout(this.thaw, 120);
+    };
+    this.thaw = () => {
+      if (!this.frozen) return;
+      const c = this.canvas;
+      c.style.top = "";
+      c.style.left = "";
+      c.style.width = "100%";
+      c.style.height = "100%";
+      c.style.position = "fixed";
+      c.style.inset = "0";
+      this.frozen = false;
+      this.resizeWhileFrozen = false;
+      this.applyResize();
+      this.last = 0;
+      if (!document.hidden && !this.raf) this.raf = requestAnimationFrame(this.frame);
+    };
     this.onPointer = (e) => {
       this.mouse.tx = e.clientX;
       this.mouse.ty = e.clientY;
@@ -436,24 +505,53 @@ var PlasmaRenderer = class _PlasmaRenderer {
     this.onLeave = () => {
       this.mouse.target = 0;
     };
+    /**
+     * Resizing reallocates eight render targets, so it must not run per event.
+     * Mobile fires `resize` continuously while the URL bar collapses, which
+     * otherwise reallocated every texture repeatedly mid-scroll.
+     */
     this.resize = () => {
+      if (this.resizeQueued) return;
+      this.resizeQueued = true;
+      requestAnimationFrame(() => {
+        this.resizeQueued = false;
+        this.applyResize();
+      });
+    };
+    this.applyResize = () => {
+      if (this.frozen) {
+        this.resizeWhileFrozen = true;
+        return;
+      }
+      this.region = { ox: 0, oy: 0, w: innerWidth, h: innerHeight };
+      this.allocate();
+    };
+    /** Size the canvas and every target for the current region. */
+    this.allocate = () => {
       const gl = this.gl;
-      this.dpr = Math.min(devicePixelRatio || 1, this.settings.quality);
-      this.canvas.width = Math.max(1, Math.round(innerWidth * this.dpr));
-      this.canvas.height = Math.max(1, Math.round(innerHeight * this.dpr));
+      const { w: rw, h: rh } = this.region;
+      let dpr = Math.min(devicePixelRatio || 1, this.settings.quality);
+      const pixels = rw * rh * dpr * dpr;
+      if (pixels > MAX_PIXELS) dpr *= Math.sqrt(MAX_PIXELS / pixels);
+      this.dpr = dpr;
+      const cw = Math.max(1, Math.round(rw * this.dpr));
+      const ch = Math.max(1, Math.round(rh * this.dpr));
+      if (cw === this.canvas.width && ch === this.canvas.height) return;
+      this.canvas.width = cw;
+      this.canvas.height = ch;
       const w = Math.max(1, Math.round(this.canvas.width * MASK_SCALE));
       const h = Math.max(1, Math.round(this.canvas.height * MASK_SCALE));
-      const size = (t, tw, th) => {
+      const size = (t, tw, th, color = false) => {
         t.w = tw;
         t.h = th;
         gl.bindTexture(gl.TEXTURE_2D, t.tex);
-        if (this.floatOK) gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16F, tw, th, 0, gl.RGBA, gl.HALF_FLOAT, null);
+        if (this.floatOK && !color) gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16F, tw, th, 0, gl.RGBA, gl.HALF_FLOAT, null);
         else gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, tw, th, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
         gl.bindFramebuffer(gl.FRAMEBUFFER, t.fb);
         gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, t.tex, 0);
       };
       [this.rtA, this.rtB, this.rtC, this.rtT, this.rtFr, this.rtBgM, this.rtBgH].forEach((t) => size(t, w, h));
-      size(this.rtBg, this.canvas.width, this.canvas.height);
+      size(this.rtBg, this.canvas.width, this.canvas.height, true);
       gl.bindFramebuffer(gl.FRAMEBUFFER, this.mrtFb);
       gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.rtT.tex, 0);
       gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT1, gl.TEXTURE_2D, this.rtFr.tex, 0);
@@ -461,7 +559,7 @@ var PlasmaRenderer = class _PlasmaRenderer {
       gl.bindFramebuffer(gl.FRAMEBUFFER, null);
     };
     this.frame = (now2) => {
-      this.raf = requestAnimationFrame(this.frame);
+      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;
       const s = this.settings;
@@ -476,7 +574,8 @@ var PlasmaRenderer = class _PlasmaRenderer {
       }));
       this.blend += (s.blend - this.blend) * ce;
       this.energy *= Math.exp(-dt * 1.2);
-      const vw = innerWidth, vh = innerHeight;
+      const rg = this.region;
+      const top = -rg.oy - 80, bottom = rg.h - rg.oy + 80, left = -rg.ox - 80, right = rg.w - rg.ox + 80;
       const list = [];
       this.recs.forEach((r) => {
         if (!r.el.isConnected) return;
@@ -486,7 +585,7 @@ var PlasmaRenderer = class _PlasmaRenderer {
         } else r.form = 1;
         const b = elementBox(r.el);
         r.box = b;
-        if (b.w === 0 || b.l > vw + 80 || b.t > vh + 80 || b.l + b.w < -80 || b.t + b.h < -80) {
+        if (b.w === 0 || b.l > right || b.t > bottom || b.l + b.w < left || b.t + b.h < top) {
           r.sp.live = false;
           return;
         }
@@ -532,10 +631,21 @@ var PlasmaRenderer = class _PlasmaRenderer {
         const le = 1 - Math.exp(-dt * 3);
         r.lx += (tx - r.lx) * le;
         r.ly += (ty - r.ly) * le;
-        r.el.style.translate = `${r.lx.toFixed(2)}px ${r.ly.toFixed(2)}px`;
+        if (Math.abs(tx - r.lx) < 0.05 && Math.abs(ty - r.ly) < 0.05) {
+          r.lx = tx;
+          r.ly = ty;
+        }
+        const lean = tx === 0 && ty === 0 && r.lx === 0 && r.ly === 0 ? "" : `${r.lx.toFixed(2)}px ${r.ly.toFixed(2)}px`;
+        if (lean !== r.leanCss) {
+          r.leanCss = lean;
+          r.el.style.translate = lean;
+        }
         const u = (this.time - r.pulseAt) / 0.36;
-        if (r.pulseAt >= 0 && u >= 0 && u <= 1 && !s.reducedMotion) r.el.style.scale = String(1 + 0.04 * r.pulseS * Math.sin(Math.PI * u));
-        else if (r.el.style.scale) r.el.style.scale = "";
+        const scale = r.pulseAt >= 0 && u >= 0 && u <= 1 && !s.reducedMotion ? String(1 + 0.04 * r.pulseS * Math.sin(Math.PI * u)) : "";
+        if (scale !== r.scaleCss) {
+          r.scaleCss = scale;
+          r.el.style.scale = scale;
+        }
       });
       const v = Math.min(Math.max(s.viscosity, 0), 1);
       const st = Math.max(s.stretch, 0);
@@ -543,7 +653,8 @@ var PlasmaRenderer = class _PlasmaRenderer {
       const zeta = 0.28 + 0.87 * v;
       const damp = 2 * zeta * Math.sqrt(stiff);
       const sx = scrollX, sy = scrollY;
-      const steps = Math.max(1, Math.ceil(dt * 120));
+      const hMax = 0.2 / Math.sqrt(Math.max(stiff, 1e-6));
+      const steps = Math.min(240, Math.max(Math.ceil(dt * 120), Math.ceil(dt / hMax), 1));
       const h = dt / steps;
       list.forEach((r) => {
         const rr = r.el.getBoundingClientRect();
@@ -567,8 +678,13 @@ var PlasmaRenderer = class _PlasmaRenderer {
         const rgt = Math.max(tgt[2], sp.e[2]) - sx, btm = Math.max(tgt[3], sp.e[3]) - sy;
         r.drawn = { l, t, w: rgt - l, h: btm - t };
       });
-      this.draw(list.slice(0, this.max));
+      this.drawnScroll = [scrollX, scrollY];
+      this.lastList = list.slice(0, this.max);
+      this.draw(this.lastList);
     };
+    this.lastList = [];
+    this.oneShot = false;
+    this.rgbCache = /* @__PURE__ */ new Map();
     this.canvas = canvas;
     this.gl = gl;
     this.settings = settings;
@@ -601,9 +717,11 @@ var PlasmaRenderer = class _PlasmaRenderer {
     this.mouse.x = this.mouse.tx = innerWidth / 2;
     this.mouse.y = this.mouse.ty = innerHeight / 2;
     addEventListener("resize", this.resize);
+    document.addEventListener("visibilitychange", this.onVisibility);
+    if (this.coarse) addEventListener("scroll", this.onScroll, { passive: true });
     addEventListener("pointermove", this.onPointer, { passive: true });
     document.addEventListener("pointerleave", this.onLeave);
-    this.resize();
+    this.applyResize();
     this.raf = requestAnimationFrame(this.frame);
   }
   /** Returns null when WebGL2 is unavailable. */
@@ -710,6 +828,8 @@ var PlasmaRenderer = class _PlasmaRenderer {
       removing: false,
       lx: 0,
       ly: 0,
+      leanCss: "",
+      scaleCss: "",
       joined: false,
       dragging: false,
       layoutBox: null,
@@ -754,7 +874,7 @@ var PlasmaRenderer = class _PlasmaRenderer {
   }
   layoutBoxOf(r) {
     if (r.layoutBox) return r.layoutBox();
-    const b = elementBox(r.el);
+    const b = r.box ?? elementBox(r.el);
     return { l: b.l - r.lx, t: b.t - r.ly, w: b.w, h: b.h };
   }
   /** Send a pulse through the material from a viewport point. */
@@ -776,6 +896,9 @@ var PlasmaRenderer = class _PlasmaRenderer {
   destroy() {
     cancelAnimationFrame(this.raf);
     removeEventListener("resize", this.resize);
+    document.removeEventListener("visibilitychange", this.onVisibility);
+    removeEventListener("scroll", this.onScroll);
+    clearTimeout(this.scrollIdle);
     removeEventListener("pointermove", this.onPointer);
     document.removeEventListener("pointerleave", this.onLeave);
     this.recs.forEach((r) => {
@@ -785,6 +908,27 @@ var PlasmaRenderer = class _PlasmaRenderer {
     this.recs.clear();
     this.gl.getExtension("WEBGL_lose_context")?.loseContext();
   }
+  freeze() {
+    const c = this.canvas;
+    cancelAnimationFrame(this.raf);
+    this.raf = 0;
+    const vw = innerWidth, vh = innerHeight, runway = Math.round(vh * _PlasmaRenderer.RUNWAY);
+    this.region = { ox: 0, oy: runway, w: vw, h: vh + 2 * runway };
+    this.allocate();
+    this.oneShot = true;
+    this.frame(performance.now());
+    this.oneShot = false;
+    c.style.inset = "";
+    c.style.width = `${this.region.w}px`;
+    c.style.height = `${this.region.h}px`;
+    c.style.position = "absolute";
+    c.style.top = "0px";
+    c.style.left = "0px";
+    const r = c.getBoundingClientRect();
+    c.style.top = `${-r.top - (scrollY - this.drawnScroll[1]) - runway}px`;
+    c.style.left = `${-r.left - (scrollX - this.drawnScroll[0])}px`;
+    this.frozen = true;
+  }
   isLight() {
     const t = this.settings.theme;
     if (t !== "auto") return t === "light";
@@ -793,11 +937,11 @@ var PlasmaRenderer = class _PlasmaRenderer {
     return !!this.lightQuery?.matches;
   }
   draw(list) {
-    const gl = this.gl, s = this.settings;
+    const gl = this.gl, s = this.settings, rg = this.region;
     const drawn = list.map((r) => r.drawn ?? elementBox(r.el));
     list.forEach((r, i) => {
       const b = drawn[i];
-      this.P.set([b.l + b.w / 2, b.t + b.h / 2, b.w / 2, b.h / 2], i * 4);
+      this.P.set([b.l + b.w / 2 + rg.ox, b.t + b.h / 2 + rg.oy, b.w / 2, b.h / 2], i * 4);
       const squareAgainst = r.fuse === false ? [] : drawn.filter((_, j) => j !== i && list[j].fuse !== false);
       this.R.set(cornerRadii(b, r.radius, squareAgainst, -1), i * 4);
       this.F[i] = Math.max(0, r.form);
@@ -810,10 +954,11 @@ var PlasmaRenderer = class _PlasmaRenderer {
       this.EL[i] = r.elevNow;
       this.SOLO[i] = r.fuse === false ? 1 : 0;
     });
-    this.pulses.forEach((p, i) => this.RP.set(p, i * 4));
+    this.pulses.forEach((p, i) => this.RP.set([p[0] + rg.ox, p[1] + rg.oy, p[2], p[3]], i * 4));
     const light = this.isLight() ? 1 : 0;
     const setCommon = (u, scale) => {
-      gl.uniform2f(u.uRes, innerWidth, innerHeight);
+      gl.uniform2f(u.uRes, rg.w, rg.h);
+      gl.uniform4f(u.uView, rg.ox, rg.oy, innerWidth, innerHeight);
       gl.uniform1f(u.uScale, scale);
       gl.uniform1f(u.uTime, this.time);
       gl.uniform1f(u.uGoo, this.blend);
@@ -822,10 +967,10 @@ var PlasmaRenderer = class _PlasmaRenderer {
       gl.uniform1f(u.uMouseAmt, this.mouse.amt);
       gl.uniform1f(u.uDropR, s.pointerDrop ? 15 : 0);
       gl.uniform1f(u.uAmbient, s.ambientDrops ? 1 : 0);
-      gl.uniform1f(u.uScroll, scrollY * 0.25);
+      gl.uniform1f(u.uScroll, this.coarse && s.freezeOnScroll ? scrollY - rg.oy : scrollY * 0.25);
       gl.uniform1f(u.uVisc, Math.min(Math.max(s.viscosity, 0), 1));
       gl.uniform1f(u.uFlow, Math.max(s.flow, 0));
-      gl.uniform2f(u.uMouse, this.mouse.x, this.mouse.y);
+      gl.uniform2f(u.uMouse, this.mouse.x + rg.ox, this.mouse.y + rg.oy);
       gl.uniform4fv(u.uP, this.P);
       gl.uniform4fv(u.uR, this.R);
       gl.uniform1fv(u.uF, this.F);
@@ -879,14 +1024,20 @@ var PlasmaRenderer = class _PlasmaRenderer {
     gl.useProgram(bl.pr);
     gl.uniform1i(bl.u.uTex, 0);
     gl.activeTexture(gl.TEXTURE0);
-    if (list.some((_, i) => this.FR[i] > 2e-3)) {
-      pass(this.rtBg, this.rtBgM, 1.5 * k, 0);
-      pass(this.rtBgM, this.rtB, 0, 2.5 * k);
-      pass(this.rtB, this.rtBgM, 2.5 * k, 0);
-      pass(this.rtBgM, this.rtB, 0, 2.5 * k);
-      pass(this.rtB, this.rtBgM, 2.5 * k, 0);
-      pass(this.rtBgM, this.rtB, 0, 2.5 * k);
-      pass(this.rtB, this.rtBgM, 0, 0);
+    const n = list.length;
+    let hasFrost = false, hasTint = false, hasElev = false;
+    for (let i = 0; i < n; i++) {
+      if (this.FR[i] > 2e-3) hasFrost = true;
+      if (this.T[i * 4 + 3] > 2e-3) hasTint = true;
+      if (this.EL[i] > 2e-3) hasElev = true;
+    }
+    if (hasFrost) {
+      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);
+      pass(this.rtB, this.rtBgM, 0, 2.5 * k);
+      pass(this.rtBgM, this.rtB, 2.5 * k, 0);
+      pass(this.rtB, this.rtBgM, 0, 2.5 * k);
       pass(this.rtBgM, this.rtB, 5 * k, 0);
       pass(this.rtB, this.rtBgH, 0, 5 * k);
       pass(this.rtBgH, this.rtB, 5 * k, 0);
@@ -907,21 +1058,21 @@ var PlasmaRenderer = class _PlasmaRenderer {
     gl.uniform1i(bl.u.uTex, 0);
     gl.activeTexture(gl.TEXTURE0);
     const so = 1.4 * k * s.smoothness;
-    for (let n = 0; n < 3; n++) {
+    for (let i = 0; i < 3; i++) {
       pass(this.rtA, this.rtB, so, 0);
       pass(this.rtB, this.rtA, 0, so);
     }
-    for (let n = 0; n < 3; n++) {
+    if (hasTint) for (let i = 0; i < 3; i++) {
       pass(this.rtT, this.rtB, so, 0);
       pass(this.rtB, this.rtT, 0, so);
     }
-    for (let n = 0; n < 3; n++) {
+    if (hasFrost || hasElev) for (let i = 0; i < 3; i++) {
       pass(this.rtFr, this.rtB, so, 0);
       pass(this.rtB, this.rtFr, 0, so);
     }
     pass(this.rtA, this.rtB, 2 * k, 0);
     pass(this.rtB, this.rtC, 0, 2 * k);
-    for (let n = 0; n < 3; n++) {
+    for (let i = 0; i < 3; i++) {
       pass(this.rtC, this.rtB, 2 * k, 0);
       pass(this.rtB, this.rtC, 0, 2 * k);
     }
@@ -964,6 +1115,14 @@ var PlasmaRenderer = class _PlasmaRenderer {
     gl.activeTexture(gl.TEXTURE0);
   }
   rgb(hex) {
+    let v = this.rgbCache.get(hex);
+    if (!v) {
+      v = this.rgbParse(hex);
+      this.rgbCache.set(hex, v);
+    }
+    return v;
+  }
+  rgbParse(hex) {
     let c = this.tintCache.get(hex);
     if (!c) {
       c = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(hex) ? hexToRgb(hex) : [1, 1, 1];
@@ -1003,6 +1162,8 @@ var PlasmaRenderer = class _PlasmaRenderer {
     return { tex, fb: gl.createFramebuffer(), w: 0, h: 0 };
   }
 };
+_PlasmaRenderer.RUNWAY = 1;
+var PlasmaRenderer = _PlasmaRenderer;
 
 // src/PlasmaProvider.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -1073,7 +1234,8 @@ function PlasmaProvider({
   magnet = 40,
   quality = 1.25,
   maxSurfaces = 16,
-  zIndex = -1
+  zIndex = -1,
+  freezeOnScroll = false
 }) {
   const canvasRef = useRef(null);
   const [renderer, setRenderer] = useState(null);
@@ -1092,6 +1254,7 @@ function PlasmaProvider({
     theme,
     quality,
     reducedMotion,
+    freezeOnScroll,
     tint,
     opacity,
     rimColor,
@@ -1135,6 +1298,7 @@ function PlasmaProvider({
     theme,
     quality,
     reducedMotion,
+    freezeOnScroll,
     tint,
     opacity,
     rimColor,

package/dist/renderer.d.ts

@@ -11,6 +11,8 @@ export interface RendererSettings {
     theme: "auto" | "light" | "dark";
     quality: number;
     reducedMotion: boolean;
+    /** Touch devices: pin the last frame to the page during a fling and resume when it stops. */
+    freezeOnScroll: boolean;
     /** Rim color: "iridescent", "tint" (each surface's tint), or a hex color. */
     rimColor: string;
     /** Rim width multiplier. */
@@ -98,6 +100,22 @@ export declare class PlasmaRenderer {
     private last;
     private time;
     private dpr;
+    private resizeQueued;
+    /** Coarse pointer = touch. Only there does a fling run on the compositor with rAF deferred. */
+    private coarse;
+    private frozen;
+    private scrollIdle;
+    private resizeWhileFrozen;
+    /** Scroll offset the last frame was drawn for: where the pinned image belongs on the page. */
+    private drawnScroll;
+    /**
+     * The region a frame covers, in CSS px: origin is where the viewport's
+     * top-left sits inside it, size is the whole region. Normally the viewport
+     * exactly. When pinning for a fling it is three viewports tall, so the
+     * scroll has a viewport of runway above and below before it runs out.
+     */
+    private region;
+    private static readonly RUNWAY;
     private energy;
     private mouse;
     private pulses;
@@ -131,13 +149,46 @@ export declare class PlasmaRenderer {
     /** Raise the material's energy (brightens contours and color); it decays on its own. */
     bump(e: number): void;
     destroy(): void;
+    /**
+     * 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
+     * left off - `last` is reset so the first frame back does not see a
+     * minute-long dt.
+     */
+    private onVisibility;
+    /**
+     * A fling on a touch device is driven by the compositor, and rAF is deferred
+     * while it runs, so anything JS repositions arrives late: the plasma trails
+     * the panels it belongs to. Instead of chasing, the canvas is pinned to the
+     * page for the duration - the last drawn frame becomes a texture that
+     * scrolls with the content, moved by the compositor with no JS in the path -
+     * and the loop resumes once the scroll events stop.
+     *
+     * The field's scroll parallax is 1:1 on these devices (see draw), so the
+     * pinned image and the first live frame after it line up.
+     */
+    private onScroll;
+    private freeze;
+    private thaw;
     private onPointer;
     private onLeave;
+    /**
+     * Resizing reallocates eight render targets, so it must not run per event.
+     * Mobile fires `resize` continuously while the URL bar collapses, which
+     * otherwise reallocated every texture repeatedly mid-scroll.
+     */
     private resize;
+    private applyResize;
+    /** Size the canvas and every target for the current region. */
+    private allocate;
     private isLight;
     private frame;
+    private lastList;
+    private oneShot;
     private draw;
+    private rgbCache;
     private rgb;
+    private rgbParse;
     private program;
     private target;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cruxgarden/plasma-ui",
-  "version": "0.2.0",
-  "description": "Liquid panels for React: every panel is one shared plasma - they fuse on contact, refract, and snap to a grid.",
+  "version": "0.2.2",
+  "description": "Liquid panels for React, rendered in WebGL on canvas: every panel is one shared plasma - they fuse on contact, refract, and snap to a grid.",
   "main": "dist/index.js",
   "scripts": {
     "build": "esbuild src/index.ts --bundle --format=esm --jsx=automatic --target=es2020 --external:react --external:react-dom --outfile=dist/index.js && tsc",