liquid-gl 2.1.1 → 2.2.1

package/README.md

@@ -1,8 +1,8 @@
-# liquidGL – Liquid Glass - Powered by WebGL
+# liquidGL – Liquid Glass - Powered by WebGPU/WebGL
 
 <a href="https://liquidgl.naughtyduk.com"><img src="https://raw.githubusercontent.com/naughtyduk/liquidGL/main/assets/liquidGL-npm-preview.gif" alt="liquidGL" width="100%" height="auto"/></a>
 
-### v2.1.1
+### v2.2.1
 
 > [!NOTE]
 > `liquidGL` is free to use for both non-commercial and commercial purposes.
@@ -16,10 +16,8 @@
 > | `html2canvas` | 86.3 ms | 85.3 ms | 134.8 ms | 16.2 ms            |
 >
 > Measured over 7 alternating runs of the full home page at `resolution: 2` (2880×10036 output), Chrome 150.
->
-> **v2.0.0 changed tilt behaviour.** The tilt interaction now eases symmetrically over the new `tiltEase` option (default `400`ms) in both directions, replacing the previous hard-coded `0.12s` ease-in and `0.4s` ease-out. If you depended on the old timing, set `tiltEase` explicitly. All other defaults are unchanged and existing configurations render identically.
 
-`liquidGL` turns any fixed or sticky-positioned element into a perfectly refracted, glossy "glass pane" rendered in WebGL.
+`liquidGL` turns any fixed or sticky-positioned element into a perfectly refracted, glossy "glass pane" rendered in WebGPU (with automatic fallback to WebGL).
 
 <a href="https://liquidgl.naughtyduk.com" target="_blank" rel="noopener noreferrer"><img src="https://raw.githubusercontent.com/naughtyduk/liquidGL/main/assets/try-it-out-npm.png" alt="Try It Out" width="120"></a>
 
@@ -31,6 +29,10 @@
 
 **Features**
 
+- **2.2.0 - WebGPU rendering** — `liquidGL` now renders with WebGPU where available, with an automatic fallback chain of WebGPU → WebGL2 → WebGL1 → CSS `backdrop-filter`. Nothing to configure, the chain is fully automatic. Choose where the chain starts with the new `engine` option (`'auto'`, `'webgpu'`, `'webgl2'`, `'webgl'`), or test quickly via the URL parameter `?liquidGL-engine=webgl2`.
+
+- **2.2.0 - Helper GUI is now a separate file** — the dev GUI no longer ships in the main bundle. Import `liquid-gl/liquidGL-helper.js` in development to keep using `helper: true`. If the module is missing you'll get a console error and everything else works as normal.
+
 - **2.1.0 - Helper GUI** — A helper GUI is now available to adjust the liquidGL options in real-time during development, helping you to achieve the perfect aesthetic. To enable it, set `helper: true` in the options object when calling `liquidGL()`.
 
 - **Sticky positioning support** — `position: sticky` elements can now be glassified. Sticky lenses are measured every animation frame, so the glass pane tracks the element through its flowing and stuck phases, then releases with it at the end of its containing block — inside nested scroll containers as well as the main document.
@@ -78,18 +80,29 @@ const glassEffect = liquidGL({
 });
 ```
 
-> `liquidGL` renders with raw WebGL and snapshots the page with its own built-in rasteriser, so it has no runtime dependencies.
+Optional dev helper GUI (only needed when using `helper: true`):
+
+```js
+// Vite / modern bundlers – tree-shaken out of production builds
+if (import.meta.env.DEV) await import("liquid-gl/liquidGL-helper.js");
+
+// or webpack flavour:
+// if (process.env.NODE_ENV !== "production") await import("liquid-gl/liquidGL-helper.js");
+```
+
+> `liquidGL` renders with WebGPU (falling back automatically to WebGL2 → WebGL1) and snapshots the page with its own built-in rasteriser, so it has no runtime dependencies.
 
 ---
 
 ## Overview
 
-`liquidGL` recreates Apple's "Liquid Glass" aesthetic in the browser with an ultra-light WebGL shader. It turns any DOM element into a beautiful, refracting glass pane. To overcome WebGL's security limitations on reading live screen pixels, `liquidGL` uses an innovative offscreen rendering technique. This allows it to refract dynamic content like videos, text animations, and more in real-time, delivering a smooth and interactive experience.
+`liquidGL` recreates Apple's "Liquid Glass" aesthetic in the browser with an ultra-light WebGPU/WebGL shader. It turns any DOM element into a beautiful, refracting glass pane. To overcome WebGL's security limitations on reading live screen pixels, `liquidGL` uses an innovative offscreen rendering technique. This allows it to refract dynamic content like videos, text animations, and more in real-time, delivering a smooth and interactive experience.
 
 ### Key Features
 
 | Feature                                | Supported | Feature                          | Supported |
 | :------------------------------------- | :-------: | :------------------------------- | :-------: |
+| WebGPU Rendering `[NEW]`               |    ✅     | Helper GUI `[NEW]`               |    ✅     |
 | Real-time Refraction (static content)  |    ✅     | Magnification Control            |    ✅     |
 | Real-time Refraction (video)           |    ✅     | Dynamic Element Support          |    ✅     |
 | Real-time Refraction (text animations) |    ✅     | GSAP-Ready Animations            |    ✅     |
@@ -126,23 +139,30 @@ Next, initialise the library with the selector for your target element.
 import liquidGL from "liquid-gl";
 
 const glassEffect = liquidGL({
-  snapshot: "body",
-  target: ".liquidGL",
-  resolution: 2.0,
-  refraction: 0.01,
-  aberration: 0,
-  bevelDepth: 0.08,
-  bevelWidth: 0.15,
-  frost: 0,
-  shadow: true,
-  specular: true,
-  reveal: "fade",
-  tilt: false,
-  tiltFactor: 5,
-  tiltEase: 400,
-  magnify: 1,
+  engine: "auto", // Renderer chain: "auto" tries WebGPU then WebGL; force with "webgpu", "webgl2" or "webgl"
+  snapshot: "body", // The area used for refraction, <body> recommended and default
+  target: ".liquidGL", // CSS selector for the element(s) to glass-ify
+  resolution: 2.0, // The quality of the snapshot
+  refraction: 0.01, // Base refraction strength (0–1)
+  aberration: 0, // Chromatic aberration strength (0–1). 0 = off
+  bevelDepth: 0.08, // Intensity of the edge bevel (0–1)
+  bevelWidth: 0.15, // Width of the bevel as a proportion of the element (0–1)
+  frost: 0, // Subtle blur radius in px. 0 = crystal clear
+  shadow: true, // Adds a soft drop-shadow under the pane
+  specular: true, // Animated light highlights (slightly more GPU)
+  reveal: "fade", // Reveal animation
+  tilt: false, // Whether tilt on hover is enabled
+  tiltFactor: 5, // If tilt is enabled, how much tilt
+  tiltEase: 400, // Tilt settle duration in ms, on hover in and out
+  magnify: 1, // Magnification of lens content
+  helper: false, // Show debug helper - note requires liquidGL-helper.js module
   on: {
     init(instance) {
+      // The `init` callback fires once liquidGL has taken its snapshot
+      // and rendered the first frame. It's the ideal place to hide or
+      // prepare elements for reveal animations (e.g. with GSAP, ScrollTrigger)
+      // because it ensures the content is visible to the snapshot before
+      // you hide it from the user.
       console.log("liquidGL ready!", instance);
     },
   },
@@ -217,6 +237,7 @@ Passing `gsap` lets `liquidGL` drive its render loop from the GSAP ticker and ke
 | `target`     | string   | `'.liquidGL'` | **Required.** CSS selector for the element(s) to glassify.                                                                                                            |
 | `snapshot`   | string   | `'body'`      | CSS selector for the element to snapshot.                                                                                                                             |
 | `resolution` | number   | `2.0`         | Resolution of the background snapshot (clamped 0.1–3.0). Higher is sharper but uses more memory.                                                                      |
+| `engine`     | string   | `'auto'`      | Render backend chain: `'auto'` (WebGPU → WebGL2 → WebGL1 → CSS), `'webgpu'` (WebGPU → CSS), `'webgl2'` (WebGL2 → WebGL1 → CSS) or `'webgl'` (WebGL1 → CSS).           |
 | `refraction` | number   | `0.01`        | Base refraction offset applied across the pane (0–1).                                                                                                                 |
 | `aberration` | number   | `0`           | Chromatic aberration strength (0–1). Scales with the refraction offset, so dispersion is strongest at the bevel. `0` disables it and skips the extra texture samples. |
 | `bevelDepth` | number   | `0.08`        | Additional refraction on the edge to simulate depth (0–1).                                                                                                            |
@@ -229,7 +250,7 @@ Passing `gsap` lets `liquidGL` drive its render loop from the GSAP ticker and ke
 | `tiltFactor` | number   | `5`           | Depth of the tilt in degrees (0–25 recommended).                                                                                                                      |
 | `tiltEase`   | number   | `400`         | Duration in ms for the tilt to settle, applied symmetrically on hover-in and hover-out. `0` applies the tilt instantly.                                               |
 | `magnify`    | number   | `1`           | Magnification factor of the lens (clamped 0.001–3.0). `1` is no magnification.                                                                                        |
-| `helper`     | boolean  | `false`       | Loads the helper GUI for live tweaking of the liquidGL options.                                                                                                       |
+| `helper`     | boolean  | `false`       | Loads the helper GUI for live tweaking of the liquidGL options. Requires `liquid-gl/liquidGL-helper.js` to be imported; logs a console error if missing.              |
 | `on.init`    | function | `—`           | Callback that runs once the first render completes. Receives the lens instance.                                                                                       |
 
 > The `target` parameter is required; all others are optional.
@@ -253,7 +274,7 @@ Passing `gsap` lets `liquidGL` drive its render loop from the GSAP ticker and ke
 | Question                                                                 | Answer                                                                                                                                                                                                                                                                                                                                                                                                         |
 | :----------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Is there a resize handler?                                               | Yes resize is handled in the library and debounced to 250ms for performance.                                                                                                                                                                                                                                                                                                                                   |
-| Does the effect work on mobile?                                          | Yes the library handles all 3 versions of WebGL and provides a frosted CSS `backdrop-filter` as a backup for older devices.                                                                                                                                                                                                                                                                                    |
+| Does the effect work on mobile?                                          | Yes the library uses WebGPU where available, falls back through WebGL2 and WebGL1, and provides a frosted CSS `backdrop-filter` as a backup for older devices.                                                                                                                                                                                                                                                 |
 | I have a preloader, how should I initialise `liquidGL()`?                | Add the `data-liquid-ignore` attribute to your preloader's top-level container to exclude it from the snapshot. You can then call `liquidGL()` inside a `DOMContentLoaded` listener as you normally would.                                                                                                                                                                                                     |
 | What is the correct way to use `liquidGL` with page animations?          | Lets say you have a preloader, above the fold intro animations and scroll animations on your page. You would:<br><br>1) set the `data-liquid-ignore` attribute on your preloader<br>2) animate your preloader and set up your initial animation states<br>3) then call `liquidGL();`<br>4) optionally, in the `on.init();` callback, you can run post snapshot scripts, such as animating the `target` element |
 | Can I use `liquidGL` on multiple elements?                               | Yes, any element which has the class declared as your `target` will be glassified. Note **all elements must use the same `z-index`** due to shared canvas optimisations, if you use different `z-index` values for multiple targets, the highest value will be used by `liquidGL`.                                                                                                                             |

package/liquidGL-helper.js

@@ -0,0 +1,362 @@
+/*
+ * liquidGL Helper – Dev/debug GUI for liquidGL
+ * -----------------------------------------------------------------------------
+ *
+ * Author: NaughtyDuk© – https://liquidgl.naughtyduk.com
+ * Licence: MIT
+ * Version: v2.2.1
+ */
+
+(() => {
+  "use strict";
+
+  /* --------------------------------------------------
+   *  Helper GUI System
+   * ------------------------------------------------*/
+  let helperGUIs = [];
+  let lilGuiLoaded = false;
+  let lilGuiLoadPromise = null;
+
+  function loadLilGui() {
+    if (lilGuiLoaded) {
+      return Promise.resolve();
+    }
+    if (lilGuiLoadPromise) {
+      return lilGuiLoadPromise;
+    }
+
+    lilGuiLoadPromise = new Promise((resolve, reject) => {
+      if (typeof lil !== "undefined") {
+        lilGuiLoaded = true;
+        injectHelperStyles();
+        resolve();
+        return;
+      }
+
+      const script = document.createElement("script");
+      script.src =
+        "https://cdn.jsdelivr.net/npm/lil-gui@0.19.1/dist/lil-gui.umd.min.js";
+      script.integrity =
+        "sha384-2eNPNc7Cms+nVcpmQPotBpthLWCwjAGbkp0Y+3MUQqwPbmTpMFmbh2a230Gkns0x";
+      script.crossOrigin = "anonymous";
+      script.onload = () => {
+        lilGuiLoaded = true;
+        injectHelperStyles();
+        resolve();
+      };
+      script.onerror = () => {
+        reject(new Error("Failed to load lil-gui"));
+      };
+      document.head.appendChild(script);
+    });
+
+    return lilGuiLoadPromise;
+  }
+
+  function injectHelperStyles() {
+    if (document.getElementById("liquidgl-helper-styles")) return;
+
+    const style = document.createElement("style");
+    style.id = "liquidgl-helper-styles";
+    style.textContent = `
+      @media screen and (max-width: 768px) {
+        .lil-gui.root.liquidgl-helper {
+          width: 61vw;
+        }
+      }
+
+      .lil-gui.root.liquidgl-helper,
+      .lil-gui.liquidgl-helper .lil-gui {
+        --background-color: rgb(9 9 11 / 85%);
+        --widget-color: rgb(39 39 42 / 50%);
+        --hover-color: rgb(39 39 42 / 70%);
+        --focus-color: rgb(39 39 42 / 90%);
+        --number-color: #fafafa;
+        --string-color: #fafafa;
+        --font-size: 13px;
+        --input-font-size: 13px;
+        --font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+        --font-family-mono: monospace;
+        --padding: 10px;
+        --spacing: 10px;
+        --widget-height: 28px;
+        --title-height: 28px;
+        --name-width: 45%;
+        --slider-knob-width: 4px;
+        --slider-input-width: 27%;
+        --color-input-width: 27%;
+        --slider-input-min-width: 45px;
+        --color-input-min-width: 45px;
+        --folder-indent: 8px;
+        --widget-padding: 0 10px;
+        --widget-border-radius: 4px;
+        --checkbox-size: 16px;
+        --scrollbar-width: 6px;
+      }
+
+      .lil-gui.root.liquidgl-helper {
+        border-radius: 12px !important;
+        border: 0.5px solid #1e1e20 !important;
+        backdrop-filter: blur(16px);
+        box-shadow: 0 4px 16px rgb(0 0 0 / 20%) !important;
+        position: fixed !important;
+        top: 1rem !important;
+        right: 1rem !important;
+        left: auto !important;
+        z-index: 999999999 !important;
+      }
+
+      .lil-gui.liquidgl-helper .title {
+        background: transparent;
+        border-bottom: 0.5px solid #1e1e20;
+        border-radius: 12px 12px 0 0 !important;
+      }
+
+      .lil-gui.liquidgl-helper .title button {
+        padding: 12px 16px !important;
+      }
+
+      .lil-gui.liquidgl-helper.closed .title {
+        border-radius: 12px !important;
+        border-bottom: none;
+      }
+
+      .lil-gui.liquidgl-helper .children {
+        border-top: 0.5px solid #1e1e20;
+      }
+
+      @media (max-width: 768px) {
+        .lil-gui.root.liquidgl-helper {
+          top: 1rem !important;
+          right: 1rem !important;
+        }
+      }
+    `;
+    document.head.appendChild(style);
+  }
+
+  function createHelperGUI(lenses, options, instanceIndex) {
+    if (typeof lil === "undefined") return;
+
+    const lensList = (Array.isArray(lenses) ? lenses : [lenses]).filter(
+      Boolean,
+    );
+    if (!lensList.length) return;
+
+    const gui = new lil.GUI({
+      title: "liquidGL Helper",
+      closeFolders: true,
+    });
+    gui.domElement.classList.add("liquidgl-helper");
+    gui.$title.style.cursor = "default";
+
+    const topOffset = 1 + instanceIndex * 3;
+    gui.domElement.style.top = `${topOffset}rem`;
+
+    const state = lensList[0].options;
+
+    const applyToLenses = (key, value) => {
+      lensList.forEach((ln) => {
+        if (!ln) return;
+        ln.options[key] = value;
+        if (key === "shadow") ln.setShadow(value);
+        if (key === "tilt") ln.setTilt(value);
+      });
+    };
+
+    const refractionFolder = gui.addFolder("Refraction");
+    refractionFolder
+      .add(state, "refraction", 0, 0.1, 0.001)
+      .name("Refraction")
+      .onChange((v) => applyToLenses("refraction", v));
+    refractionFolder
+      .add(state, "aberration", 0, 1, 0.01)
+      .name("Aberration")
+      .onChange((v) => applyToLenses("aberration", v));
+    refractionFolder
+      .add(state, "bevelDepth", 0, 0.2, 0.001)
+      .name("Bevel Depth")
+      .onChange((v) => applyToLenses("bevelDepth", v));
+    refractionFolder
+      .add(state, "bevelWidth", 0, 0.5, 0.001)
+      .name("Bevel Width")
+      .onChange((v) => applyToLenses("bevelWidth", v));
+    refractionFolder
+      .add(state, "magnify", 1, 5, 0.1)
+      .name("Magnify")
+      .onChange((v) => applyToLenses("magnify", v));
+
+    const surfaceFolder = gui.addFolder("Surface");
+    surfaceFolder
+      .add(state, "frost", 0, 10, 0.1)
+      .name("Frost")
+      .onChange((v) => applyToLenses("frost", v));
+    surfaceFolder
+      .add(state, "specular")
+      .name("Specular")
+      .onChange((v) => applyToLenses("specular", v));
+    surfaceFolder
+      .add(state, "shadow")
+      .name("Shadow")
+      .onChange((v) => applyToLenses("shadow", v));
+
+    const tiltFolder = gui.addFolder("Tilt");
+    tiltFolder
+      .add(state, "tilt")
+      .name("Tilt")
+      .onChange((v) => applyToLenses("tilt", v));
+    tiltFolder
+      .add(state, "tiltFactor", 0, 25, 0.1)
+      .name("Tilt Factor")
+      .onChange((v) => applyToLenses("tiltFactor", v));
+    tiltFolder
+      .add(state, "tiltEase", 0, 1000, 10)
+      .name("Tilt Ease")
+      .onChange((v) => applyToLenses("tiltEase", v));
+
+    const initFolder = gui.addFolder("Initialisation");
+    const reinitState = {
+      reveal: options.reveal,
+      resolution: options.resolution,
+    };
+
+    initFolder
+      .add(reinitState, "reveal", ["none", "fade"])
+      .name("Reveal")
+      .onFinishChange((value) => {
+        if (
+          confirm(
+            "Changing reveal applies on the next initialisation. Continue?",
+          )
+        ) {
+          applyToLenses("reveal", value);
+        } else {
+          reinitState.reveal = options.reveal;
+          gui.controllersRecursive().forEach((c) => c.updateDisplay());
+        }
+      });
+
+    initFolder
+      .add(reinitState, "resolution", 0.5, 3, 0.25)
+      .name("Resolution")
+      .onFinishChange((value) => {
+        if (
+          confirm(
+            "Changing resolution re-captures the page snapshot. Continue?",
+          )
+        ) {
+          applyToLenses("resolution", value);
+          const renderer = window.__liquidGLRenderer__;
+          if (renderer) {
+            renderer._snapshotResolution = Math.max(0.1, Math.min(3.0, value));
+            renderer.captureSnapshot();
+          }
+        } else {
+          reinitState.resolution = options.resolution;
+          gui.controllersRecursive().forEach((c) => c.updateDisplay());
+        }
+      });
+
+    const copyButton = {
+      copySettings: () => {
+        const code = generateInitCode(options);
+        const controller = gui.controllers.find(
+          (c) => c.property === "copySettings",
+        );
+
+        if (!controller) return;
+
+        const originalName = controller._name;
+        controller.disable();
+        controller.name("✓ Copied");
+
+        const copySuccess = () => {
+          setTimeout(() => {
+            controller.name(originalName);
+            controller.enable();
+          }, 1500);
+        };
+
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+          navigator.clipboard
+            .writeText(code)
+            .then(() => {
+              copySuccess();
+            })
+            .catch((err) => {
+              console.error("Clipboard error:", err);
+              fallbackCopy(code);
+            });
+        } else {
+          fallbackCopy(code);
+        }
+
+        function fallbackCopy(text) {
+          const textarea = document.createElement("textarea");
+          textarea.value = text;
+          textarea.style.position = "fixed";
+          textarea.style.opacity = "0";
+          document.body.appendChild(textarea);
+          textarea.select();
+          try {
+            document.execCommand("copy");
+            copySuccess();
+          } catch (err) {
+            console.error("Copy failed:", err);
+            controller.name(originalName);
+            controller.enable();
+            prompt("Copy this code manually:", text);
+          }
+          document.body.removeChild(textarea);
+        }
+      },
+    };
+    gui.add(copyButton, "copySettings").name("Copy settings");
+
+    refractionFolder.close();
+    surfaceFolder.close();
+    tiltFolder.close();
+    initFolder.close();
+
+    helperGUIs.push({ gui, lenses: lensList });
+    return gui;
+  }
+
+  function generateInitCode(options) {
+    const lines = ["liquidGL({"];
+
+    lines.push(`  target: "${options.target}",`);
+    lines.push(`  snapshot: "${options.snapshot}",`);
+    lines.push(`  resolution: ${options.resolution},`);
+    lines.push(`  refraction: ${options.refraction},`);
+    lines.push(`  aberration: ${options.aberration},`);
+    lines.push(`  bevelDepth: ${options.bevelDepth},`);
+    lines.push(`  bevelWidth: ${options.bevelWidth},`);
+    lines.push(`  frost: ${options.frost},`);
+    lines.push(`  shadow: ${options.shadow},`);
+    lines.push(`  specular: ${options.specular},`);
+    lines.push(`  reveal: "${options.reveal}",`);
+    lines.push(`  tilt: ${options.tilt},`);
+    lines.push(`  tiltFactor: ${options.tiltFactor},`);
+    lines.push(`  tiltEase: ${options.tiltEase},`);
+    lines.push(`  magnify: ${options.magnify},`);
+    lines.push(`  helper: false,`);
+    lines.push(`});`);
+
+    return lines.join("\n");
+  }
+
+  /* --------------------------------------------------
+   *  Registration
+   * ------------------------------------------------*/
+  window.__liquidGLHelper__ = (lenses, options) => {
+    loadLilGui()
+      .then(() => {
+        const instanceIndex = helperGUIs.length;
+        createHelperGUI(lenses, options, instanceIndex);
+      })
+      .catch((err) => {
+        console.error("liquidGL: Failed to load helper GUI:", err);
+      });
+  };
+})();