@shulya/liquid-glass 1.0.3 → 1.0.5

package/dist/core.cjs

@@ -13,14 +13,16 @@ const OPTICAL_DEFAULTS = exports.OPTICAL_DEFAULTS = Object.freeze({
   ior: 1.46,
   height: 18,
   frosted: 0,
-  fusion: true
+  fusion: true,
+  dpr: 0
 });
 
 const OPTICAL_LIMITS = exports.OPTICAL_LIMITS = Object.freeze({
   rim: Object.freeze({ min: 4, max: 48 }),
   ior: Object.freeze({ min: 1.05, max: 2.20 }),
   height: Object.freeze({ min: 2, max: 50 }),
-  frosted: Object.freeze({ min: 0, max: 32 })
+  frosted: Object.freeze({ min: 0, max: 32 }),
+  dpr: Object.freeze({ min: 0.5, max: 3.0 })
 });
 
 function clampNumber(val, fallback, min, max) {
@@ -57,7 +59,11 @@ exports.normalizeOptions = function normalizeOptions(options = {}) {
       OPTICAL_LIMITS.frosted.min,
       OPTICAL_LIMITS.frosted.max
     ),
-    fusion: options.fusion !== undefined ? Boolean(options.fusion) : OPTICAL_DEFAULTS.fusion
+    fusion: options.fusion !== undefined ? Boolean(options.fusion) : OPTICAL_DEFAULTS.fusion,
+    dpr:
+      typeof options.dpr === 'number' && options.dpr > 0
+        ? clampNumber(options.dpr, 1, OPTICAL_LIMITS.dpr.min, OPTICAL_LIMITS.dpr.max)
+        : 0
   };
 }
 
@@ -221,7 +227,7 @@ exports.buildOpticalMapURI = function buildOpticalMapURI(width, height, borderRa
  */
 exports.renderFusedCluster = function renderFusedCluster(ctx, sourceCtx, elements, rawOptions = {}, dpr = 1) {
   const options = normalizeOptions(rawOptions);
-  const fusionSpan = options.fusion ? (rawOptions.fusionDistance ?? 44) * dpr : 0;
+  const fusionSpan = options.fusion ? (rawOptions.fusionDistance ?? 24) * dpr : 0;
   const rimPx = Math.max(1, options.rim * dpr);
   const ior = options.ior;
   const heightPx = options.height * dpr;
@@ -259,19 +265,26 @@ exports.renderFusedCluster = function renderFusedCluster(ctx, sourceCtx, element
   const dstData = dstImg.data;
 
   const distGrid = new Float32Array(boxW * boxH);
-  const prep = elements.map((b) => ({
-    cx: (b.x + b.w * 0.5) * dpr,
-    cy: (b.y + b.h * 0.5) * dpr,
-    halfW: b.w * 0.5 * dpr,
-    halfH: b.h * 0.5 * dpr,
-    r: Math.min((b.borderRadius ?? 0) * dpr, b.w * 0.5 * dpr, b.h * 0.5 * dpr),
-    isCircle: b.shape === 'circle',
-    fusion: b.fusion !== undefined ? Boolean(b.fusion) : options.fusion,
-    tintR: b.tint ? b.tint[0] : 15,
-    tintG: b.tint ? b.tint[1] : 23,
-    tintB: b.tint ? b.tint[2] : 42,
-    tintA: b.tint ? b.tint[3] : 0.35
-  }));
+  const prep = elements.map((b) => {
+    const halfW = b.w * 0.5 * dpr;
+    const halfH = b.h * 0.5 * dpr;
+    const rad = (b.borderRadius ?? 0) * dpr;
+    const r = Math.min(rad, halfW, halfH);
+    const isCircle = b.shape === 'circle' || (Math.abs(halfW - halfH) < 1.0 && Math.abs(r - halfW) < 1.0);
+    return {
+      cx: (b.x + b.w * 0.5) * dpr,
+      cy: (b.y + b.h * 0.5) * dpr,
+      halfW,
+      halfH,
+      r,
+      isCircle,
+      fusion: b.fusion !== undefined ? Boolean(b.fusion) : options.fusion,
+      tintR: b.tint ? b.tint[0] : 15,
+      tintG: b.tint ? b.tint[1] : 23,
+      tintB: b.tint ? b.tint[2] : 42,
+      tintA: b.tint ? b.tint[3] : 0.35
+    };
+  });
 
   const primary = prep[0];
   const tR = primary.tintR;
@@ -279,8 +292,10 @@ exports.renderFusedCluster = function renderFusedCluster(ctx, sourceCtx, element
   const tB = primary.tintB;
   const tA = primary.tintA;
   const invTA = 1.0 - tA;
+  const span = fusionSpan;
+  const invSpan = span > 0.001 ? 1.0 / span : 0;
 
-  // Pass 1: Boundary evaluation across cluster bounding box
+  // Pass 1: Boundary evaluation across cluster bounding box (Inlined fast LUT math)
   for (let y = 0; y < boxH; y++) {
     const py = cMinY + y;
     const row = y * boxW;
@@ -289,22 +304,36 @@ exports.renderFusedCluster = function renderFusedCluster(ctx, sourceCtx, element
       let dCluster = Infinity;
       for (let i = 0; i < prep.length; i++) {
         const b = prep[i];
-        const dShape = b.isCircle
-          ? evalCircle(px - b.cx, py - b.cy, b.halfW)
-          : evalRoundedRect(px - b.cx, py - b.cy, b.halfW, b.halfH, b.r);
+        let dShape;
+        if (b.isCircle) {
+          dShape = Math.hypot(px - b.cx, py - b.cy) - b.halfW;
+        } else {
+          const qx = Math.abs(px - b.cx) - b.halfW + b.r;
+          const qy = Math.abs(py - b.cy) - b.halfH + b.r;
+          dShape = Math.min(Math.max(qx, qy), 0.0) + Math.hypot(Math.max(qx, 0.0), Math.max(qy, 0.0)) - b.r;
+        }
+
         if (i === 0) {
           dCluster = dShape;
-        } else if (b.fusion && fusionSpan > 0) {
-          dCluster = blendSurfaces(dCluster, dShape, fusionSpan);
-        } else {
-          dCluster = Math.min(dCluster, dShape);
+        } else if (b.fusion && span > 0.001) {
+          const diff = dCluster > dShape ? dCluster - dShape : dShape - dCluster;
+          if (diff < span) {
+            const pos = diff * invSpan * 255.0;
+            const pIdx = Math.min(254, pos | 0);
+            const wWeight = _T3[pIdx] + (_T3[pIdx + 1] - _T3[pIdx]) * (pos - pIdx);
+            dCluster = (dCluster < dShape ? dCluster : dShape) - wWeight * span;
+          } else if (dShape < dCluster) {
+            dCluster = dShape;
+          }
+        } else if (dShape < dCluster) {
+          dCluster = dShape;
         }
       }
       distGrid[row + x] = dCluster;
     }
   }
 
-  // Pass 2: O(1) lookup from distGrid + tabular chromatic shift (_T4)
+  // Pass 2: Fast vectorized lookup from distGrid + tabular chromatic shift (_T4)
   for (let y = 1; y < boxH - 1; y++) {
     const row = y * boxW;
     for (let x = 1; x < boxW - 1; x++) {
@@ -325,8 +354,11 @@ exports.renderFusedCluster = function renderFusedCluster(ctx, sourceCtx, element
         const innerDist = -d;
         if (innerDist < rimPx) {
           const u = innerDist / rimPx;
-          const gain = sampleTable(_T0, u);
-          disp = sampleTable(_T4, u);
+          const posU = u * 255.0;
+          const uIdx = Math.min(254, posU | 0);
+          const uFrac = posU - uIdx;
+          const gain = _T0[uIdx] + (_T0[uIdx + 1] - _T0[uIdx]) * uFrac;
+          disp = _T4[uIdx] + (_T4[uIdx + 1] - _T4[uIdx]) * uFrac;
 
           const dx = distGrid[row + x + 1] - distGrid[row + x - 1];
           const dy = distGrid[(y + 1) * boxW + x] - distGrid[(y - 1) * boxW + x];
@@ -339,7 +371,8 @@ exports.renderFusedCluster = function renderFusedCluster(ctx, sourceCtx, element
           offY = Math.round(-gy * shift);
 
           if (gy < -0.2) {
-            sheen = Math.round(sampleTable(_T2, u) * (-gy) * 0.78);
+            const sVal = _T2[uIdx] + (_T2[uIdx + 1] - _T2[uIdx]) * uFrac;
+            sheen = Math.round(sVal * (-gy) * 0.78);
           }
         } else {
           // Fast interior path: zero displacement inside flat region (-d >= rimPx)
@@ -354,7 +387,9 @@ exports.renderFusedCluster = function renderFusedCluster(ctx, sourceCtx, element
 
       const absD = Math.abs(d);
       if (absD < 3.0) {
-        glint = Math.round(sampleTable(_T1, absD * 0.33) * 0.65);
+        const posG = Math.min(254, absD * 0.33 * 255.0);
+        const gIdx = posG | 0;
+        glint = Math.round((_T1[gIdx] + (_T1[gIdx + 1] - _T1[gIdx]) * (posG - gIdx)) * 0.65);
       }
 
       const sxG = Math.max(0, Math.min(boxW - 1, x + offX));
@@ -448,11 +483,27 @@ function getReadableStrokeColor(borderCol, fallback = 'rgba(148, 163, 184, 0.55)
   return fallback;
 }
 
+function getDevicePixelRatio(customDpr = 0, elementWidth = 0) {
+  if (typeof customDpr === 'number' && customDpr > 0) {
+    return Math.max(0.5, Math.min(3.0, customDpr));
+  }
+  if (typeof window === 'undefined') return 1;
+  const sysDpr = window.devicePixelRatio || 1;
+  // Automatically use 1.0 for wide elements (headers, banners >= 700px) to guarantee 120 FPS
+  if (elementWidth >= 700) {
+    return 1;
+  }
+  return Math.min(sysDpr, 1.5);
+}
+
 function ensureStageBuffers() {
   if (typeof document === 'undefined') return false;
+  const dpr = getDevicePixelRatio();
   const docEl = document.documentElement;
   const vw = Math.max(1, window.innerWidth, docEl ? docEl.clientWidth : 0);
   const vh = Math.max(1, window.innerHeight, docEl ? docEl.clientHeight : 0);
+  const bufW = Math.round(vw * dpr);
+  const bufH = Math.round(vh * dpr);
 
   if (!stageCanvas) {
     stageCanvas = document.createElement('canvas');
@@ -461,11 +512,11 @@ function ensureStageBuffers() {
     blurCtx = blurCanvas.getContext('2d', { willReadFrequently: true });
   }
 
-  if (stageCanvas.width !== vw || stageCanvas.height !== vh) {
-    stageCanvas.width = vw;
-    stageCanvas.height = vh;
-    blurCanvas.width = vw;
-    blurCanvas.height = vh;
+  if (stageCanvas.width !== bufW || stageCanvas.height !== bufH) {
+    stageCanvas.width = bufW;
+    stageCanvas.height = bufH;
+    blurCanvas.width = bufW;
+    blurCanvas.height = bufH;
   }
 
   if (!clusterOverlayCanvas) {
@@ -492,14 +543,20 @@ function ensureStageBuffers() {
  */
 function captureViewportStage(neededBlur) {
   if (!ensureStageBuffers()) return;
-  const vw = stageCanvas.width;
-  const vh = stageCanvas.height;
+  const dpr = getDevicePixelRatio();
+  const bw = stageCanvas.width;
+  const bh = stageCanvas.height;
+  const vw = Math.round(bw / dpr);
+  const vh = Math.round(bh / dpr);
 
-  // 1. Base page background
-  stageCtx.fillStyle = '#040814';
-  stageCtx.fillRect(0, 0, vw, vh);
+  stageCtx.save();
 
-  // 2. Copy any background 2D canvas using its exact getBoundingClientRect() viewport box
+  // 1. Base page background (detect light/dark body background)
+  const bodyBg = typeof document !== 'undefined' ? window.getComputedStyle(document.body).backgroundColor : '';
+  stageCtx.fillStyle = bodyBg && bodyBg !== 'transparent' && bodyBg !== 'rgba(0, 0, 0, 0)' ? bodyBg : '#040814';
+  stageCtx.fillRect(0, 0, bw, bh);
+
+  // 2. Copy any background 2D canvas using physical buffer pixels
   const bgCanvases = document.querySelectorAll('canvas:not(.lg-lens-canvas):not(.lg-cluster-canvas)');
   for (let i = 0; i < bgCanvases.length; i++) {
     const c = bgCanvases[i];
@@ -507,7 +564,13 @@ function captureViewportStage(neededBlur) {
       try {
         const cr = c.getBoundingClientRect();
         if (cr.width > 0 && cr.height > 0) {
-          stageCtx.drawImage(c, cr.left, cr.top, cr.width, cr.height);
+          stageCtx.drawImage(
+            c,
+            Math.round(cr.left * dpr),
+            Math.round(cr.top * dpr),
+            Math.round(cr.width * dpr),
+            Math.round(cr.height * dpr)
+          );
         }
       } catch {
         // Ignore cross-origin canvas if any
@@ -515,6 +578,9 @@ function captureViewportStage(neededBlur) {
     }
   }
 
+  // Scale context for DOM elements rendered in CSS pixels
+  stageCtx.scale(dpr, dpr);
+
   // 3. Draw visible block surfaces (cards, buttons, pills, inputs) inside <main> and <footer>
   const surfaceEls = document.querySelectorAll(
     'main div.rounded-2xl, main div.rounded-xl, main a.rounded-2xl, main a.rounded-xl, main button, main a.inline-flex, main input, main textarea, main span.rounded-lg, main span.rounded-full'
@@ -668,13 +734,53 @@ function captureViewportStage(neededBlur) {
     stageCtx.restore();
   }
 
-  // 5. Blur buffer for frosted glass
+  stageCtx.restore();
+
+let supportsCanvasFilterBlur = null;
+function checkCanvasFilterBlur() {
+  if (supportsCanvasFilterBlur !== null) return supportsCanvasFilterBlur;
+  if (typeof document === 'undefined') return false;
+  try {
+    const testC = document.createElement('canvas');
+    testC.width = 4;
+    testC.height = 4;
+    const testCtx = testC.getContext('2d');
+    if (!testCtx || typeof testCtx.filter !== 'string') {
+      return (supportsCanvasFilterBlur = false);
+    }
+    testCtx.fillStyle = '#000';
+    testCtx.fillRect(0, 0, 4, 4);
+    testCtx.filter = 'blur(2px)';
+    testCtx.fillStyle = '#fff';
+    testCtx.fillRect(0, 0, 2, 2);
+    testCtx.filter = 'none';
+    const imgData = testCtx.getImageData(0, 0, 4, 4).data;
+    supportsCanvasFilterBlur = imgData[15 * 4] > 0 || imgData[14 * 4] > 0 || imgData[11 * 4] > 0;
+    return supportsCanvasFilterBlur;
+  } catch {
+    return (supportsCanvasFilterBlur = false);
+  }
+}
+
+  // 5. Blur buffer for frosted glass (Robust across all mobile WebKit & Blink engines)
   if (neededBlur > 0) {
     lastFrostedRadius = neededBlur;
-    blurCtx.clearRect(0, 0, vw, vh);
-    blurCtx.filter = `blur(${neededBlur}px) saturate(135%)`;
-    blurCtx.drawImage(stageCanvas, 0, 0);
-    blurCtx.filter = 'none';
+    blurCtx.clearRect(0, 0, bw, bh);
+
+    if (checkCanvasFilterBlur()) {
+      blurCtx.filter = `blur(${Math.round(neededBlur * dpr)}px)`;
+      blurCtx.drawImage(stageCanvas, 0, 0);
+      blurCtx.filter = 'none';
+    } else {
+      // Hardware-accelerated multi-step pyramid downscale/upscale blur for iOS Safari and mobile WebKit
+      const factor = Math.max(0.04, 1.0 / (1.0 + neededBlur * 0.45));
+      const pw = Math.max(4, Math.round(bw * factor));
+      const ph = Math.max(4, Math.round(bh * factor));
+      blurCtx.imageSmoothingEnabled = true;
+      blurCtx.imageSmoothingQuality = 'high';
+      blurCtx.drawImage(stageCanvas, 0, 0, pw, ph);
+      blurCtx.drawImage(blurCanvas, 0, 0, pw, ph, 0, 0, bw, bh);
+    }
   }
 }
 
@@ -682,17 +788,19 @@ function captureViewportStage(neededBlur) {
  * Fast Isolated Lens Renderer (Takes ~0.12 ms using precomputed TypedArray LUT!)
  */
 function renderIsolatedController(ctrl, rect) {
-  const w = Math.max(16, Math.round(rect.width));
-  const h = Math.max(16, Math.round(rect.height));
+  const dpr = getDevicePixelRatio(ctrl.options.dpr, rect.width);
+  const w = Math.max(16, Math.round(rect.width * dpr));
+  const h = Math.max(16, Math.round(rect.height * dpr));
   const rad = ctrl._getRadius();
+  const radPx = Math.min(rad * dpr, w * 0.5, h * 0.5);
 
   if (
     !ctrl._lut ||
     ctrl._lut.w !== w ||
     ctrl._lut.h !== h ||
-    Math.abs(ctrl._lut.rad - Math.min(rad, w * 0.5, h * 0.5)) > 1.0
+    Math.abs(ctrl._lut.rad - radPx) > 1.0
   ) {
-    ctrl._lut = buildElementLUT(w, h, rad, ctrl.options, 1);
+    ctrl._lut = buildElementLUT(w, h, rad, ctrl.options, dpr);
   }
 
   const lut = ctrl._lut;
@@ -701,9 +809,9 @@ function renderIsolatedController(ctrl, rect) {
     ctrl._canvas.height = h;
   }
 
-  // Use exact un-clamped element position so dragging near/past mobile viewport edges never shifts the image
-  const dx = Math.round(rect.left);
-  const dy = Math.round(rect.top);
+  // Use exact un-clamped element position in physical canvas pixels
+  const dx = Math.round(rect.left * dpr);
+  const dy = Math.round(rect.top * dpr);
 
   const sourceCtx = ctrl.options.frosted > 0 ? blurCtx : stageCtx;
   const srcImg = sourceCtx.getImageData(dx, dy, w, h);
@@ -773,7 +881,7 @@ function renderIsolatedController(ctrl, rect) {
   ctrl._canvas.style.opacity = '1';
 }
 
-function areRectsTouching(r1, r2, threshold = 42) {
+function areRectsTouching(r1, r2, threshold = 24) {
   const dx = Math.max(
     0,
     Math.abs(r1.left + r1.width * 0.5 - (r2.left + r2.width * 0.5)) -
@@ -843,7 +951,7 @@ function renderAllActiveLenses() {
     if (!visible[i].ctrl.options.fusion) continue;
     for (let j = i + 1; j < n; j++) {
       if (!visible[j].ctrl.options.fusion) continue;
-      if (areRectsTouching(visible[i].rect, visible[j].rect, 54)) {
+      if (areRectsTouching(visible[i].rect, visible[j].rect, 24)) {
         union(i, j);
       }
     }
@@ -861,21 +969,13 @@ function renderAllActiveLenses() {
   for (const group of clusters.values()) {
     if (group.length === 1) {
       const { ctrl, rect } = group[0];
-      if (ctrl._savedShadow && ctrl.element.style.boxShadow === 'none') {
-        ctrl.element.style.boxShadow = ctrl._savedInlineShadow || '';
-      }
       if (rect.bottom > 1 && rect.top < vh) {
         renderIsolatedController(ctrl, rect);
       }
     } else {
       hasFusedCluster = true;
-      let anyHasShadow = false;
       for (const item of group) {
         item.ctrl._canvas.style.opacity = '0';
-        if (item.ctrl._savedShadow) {
-          anyHasShadow = true;
-          item.ctrl.element.style.boxShadow = 'none';
-        }
       }
       const primaryCtrl = group[group.length - 1].ctrl;
       const sourceCtx = primaryCtrl.options.frosted > 0 ? blurCtx : stageCtx;
@@ -886,28 +986,40 @@ function renderAllActiveLenses() {
         h: rect.height,
         borderRadius: ctrl._getRadius(),
         fusion: true,
-        tint: ctrl._tint
+        tint: ctrl._tint,
+        dpr: ctrl.options.dpr
       }));
 
+      const maxClusterWidth = Math.max(...group.map(g => g.rect.width));
+      const dpr = getDevicePixelRatio(primaryCtrl.options.dpr, maxClusterWidth);
       const box = renderFusedCluster(
         clusterOverlayCtx,
         sourceCtx,
         elements,
         {
           ...primaryCtrl.options,
-          fusionDistance: 64
+          fusionDistance: 24
         },
-        1
+        dpr
       );
 
       if (box && clusterOverlayCanvas) {
         clusterOverlayCanvas.style.display = 'block';
-        clusterOverlayCanvas.style.filter = anyHasShadow
-          ? 'drop-shadow(3px 14px 18px rgba(0, 0, 0, 0.16))'
-          : 'none';
-        clusterOverlayCanvas.style.transform = `translate3d(${box.cMinX}px, ${box.cMinY}px, 0)`;
-        clusterOverlayCanvas.style.width = `${box.boxW}px`;
-        clusterOverlayCanvas.style.height = `${box.boxH}px`;
+        clusterOverlayCanvas.style.filter = 'none';
+
+        // Match z-index to highest element in the cluster so it never pops above floating menus/controls
+        let maxZ = 20;
+        for (const item of group) {
+          if (item.ctrl && item.ctrl.element) {
+            const z = parseInt(window.getComputedStyle(item.ctrl.element).zIndex, 10);
+            if (!Number.isNaN(z) && z > maxZ) maxZ = z;
+          }
+        }
+        clusterOverlayCanvas.style.zIndex = String(maxZ);
+
+        clusterOverlayCanvas.style.transform = `translate3d(${box.cMinX / dpr}px, ${box.cMinY / dpr}px, 0)`;
+        clusterOverlayCanvas.style.width = `${box.boxW / dpr}px`;
+        clusterOverlayCanvas.style.height = `${box.boxH / dpr}px`;
       }
     }
   }
@@ -1077,11 +1189,11 @@ const LiquidGlassController = exports.LiquidGlassController = class LiquidGlassC
       changed = true;
     }
 
-    for (const key of ['rim', 'ior', 'height', 'frosted', 'fusion']) {
+    for (const key of ['rim', 'ior', 'height', 'frosted', 'fusion', 'dpr']) {
       if (merged[key] !== this.options[key]) {
         this.options[key] = merged[key];
         changed = true;
-        if (key === 'rim' || key === 'ior' || key === 'height') {
+        if (key === 'rim' || key === 'ior' || key === 'height' || key === 'dpr') {
           lutChanged = true;
         }
       }

package/dist/core.mjs

@@ -13,14 +13,16 @@ export const OPTICAL_DEFAULTS = Object.freeze({
   ior: 1.46,
   height: 18,
   frosted: 0,
-  fusion: true
+  fusion: true,
+  dpr: 0
 });
 
 export const OPTICAL_LIMITS = Object.freeze({
   rim: Object.freeze({ min: 4, max: 48 }),
   ior: Object.freeze({ min: 1.05, max: 2.20 }),
   height: Object.freeze({ min: 2, max: 50 }),
-  frosted: Object.freeze({ min: 0, max: 32 })
+  frosted: Object.freeze({ min: 0, max: 32 }),
+  dpr: Object.freeze({ min: 0.5, max: 3.0 })
 });
 
 function clampNumber(val, fallback, min, max) {
@@ -57,7 +59,11 @@ export function normalizeOptions(options = {}) {
       OPTICAL_LIMITS.frosted.min,
       OPTICAL_LIMITS.frosted.max
     ),
-    fusion: options.fusion !== undefined ? Boolean(options.fusion) : OPTICAL_DEFAULTS.fusion
+    fusion: options.fusion !== undefined ? Boolean(options.fusion) : OPTICAL_DEFAULTS.fusion,
+    dpr:
+      typeof options.dpr === 'number' && options.dpr > 0
+        ? clampNumber(options.dpr, 1, OPTICAL_LIMITS.dpr.min, OPTICAL_LIMITS.dpr.max)
+        : 0
   };
 }
 
@@ -221,7 +227,7 @@ export function buildOpticalMapURI(width, height, borderRadius, rawOptions = {})
  */
 export function renderFusedCluster(ctx, sourceCtx, elements, rawOptions = {}, dpr = 1) {
   const options = normalizeOptions(rawOptions);
-  const fusionSpan = options.fusion ? (rawOptions.fusionDistance ?? 44) * dpr : 0;
+  const fusionSpan = options.fusion ? (rawOptions.fusionDistance ?? 24) * dpr : 0;
   const rimPx = Math.max(1, options.rim * dpr);
   const ior = options.ior;
   const heightPx = options.height * dpr;
@@ -259,19 +265,26 @@ export function renderFusedCluster(ctx, sourceCtx, elements, rawOptions = {}, dp
   const dstData = dstImg.data;
 
   const distGrid = new Float32Array(boxW * boxH);
-  const prep = elements.map((b) => ({
-    cx: (b.x + b.w * 0.5) * dpr,
-    cy: (b.y + b.h * 0.5) * dpr,
-    halfW: b.w * 0.5 * dpr,
-    halfH: b.h * 0.5 * dpr,
-    r: Math.min((b.borderRadius ?? 0) * dpr, b.w * 0.5 * dpr, b.h * 0.5 * dpr),
-    isCircle: b.shape === 'circle',
-    fusion: b.fusion !== undefined ? Boolean(b.fusion) : options.fusion,
-    tintR: b.tint ? b.tint[0] : 15,
-    tintG: b.tint ? b.tint[1] : 23,
-    tintB: b.tint ? b.tint[2] : 42,
-    tintA: b.tint ? b.tint[3] : 0.35
-  }));
+  const prep = elements.map((b) => {
+    const halfW = b.w * 0.5 * dpr;
+    const halfH = b.h * 0.5 * dpr;
+    const rad = (b.borderRadius ?? 0) * dpr;
+    const r = Math.min(rad, halfW, halfH);
+    const isCircle = b.shape === 'circle' || (Math.abs(halfW - halfH) < 1.0 && Math.abs(r - halfW) < 1.0);
+    return {
+      cx: (b.x + b.w * 0.5) * dpr,
+      cy: (b.y + b.h * 0.5) * dpr,
+      halfW,
+      halfH,
+      r,
+      isCircle,
+      fusion: b.fusion !== undefined ? Boolean(b.fusion) : options.fusion,
+      tintR: b.tint ? b.tint[0] : 15,
+      tintG: b.tint ? b.tint[1] : 23,
+      tintB: b.tint ? b.tint[2] : 42,
+      tintA: b.tint ? b.tint[3] : 0.35
+    };
+  });
 
   const primary = prep[0];
   const tR = primary.tintR;
@@ -279,8 +292,10 @@ export function renderFusedCluster(ctx, sourceCtx, elements, rawOptions = {}, dp
   const tB = primary.tintB;
   const tA = primary.tintA;
   const invTA = 1.0 - tA;
+  const span = fusionSpan;
+  const invSpan = span > 0.001 ? 1.0 / span : 0;
 
-  // Pass 1: Boundary evaluation across cluster bounding box
+  // Pass 1: Boundary evaluation across cluster bounding box (Inlined fast LUT math)
   for (let y = 0; y < boxH; y++) {
     const py = cMinY + y;
     const row = y * boxW;
@@ -289,22 +304,36 @@ export function renderFusedCluster(ctx, sourceCtx, elements, rawOptions = {}, dp
       let dCluster = Infinity;
       for (let i = 0; i < prep.length; i++) {
         const b = prep[i];
-        const dShape = b.isCircle
-          ? evalCircle(px - b.cx, py - b.cy, b.halfW)
-          : evalRoundedRect(px - b.cx, py - b.cy, b.halfW, b.halfH, b.r);
+        let dShape;
+        if (b.isCircle) {
+          dShape = Math.hypot(px - b.cx, py - b.cy) - b.halfW;
+        } else {
+          const qx = Math.abs(px - b.cx) - b.halfW + b.r;
+          const qy = Math.abs(py - b.cy) - b.halfH + b.r;
+          dShape = Math.min(Math.max(qx, qy), 0.0) + Math.hypot(Math.max(qx, 0.0), Math.max(qy, 0.0)) - b.r;
+        }
+
         if (i === 0) {
           dCluster = dShape;
-        } else if (b.fusion && fusionSpan > 0) {
-          dCluster = blendSurfaces(dCluster, dShape, fusionSpan);
-        } else {
-          dCluster = Math.min(dCluster, dShape);
+        } else if (b.fusion && span > 0.001) {
+          const diff = dCluster > dShape ? dCluster - dShape : dShape - dCluster;
+          if (diff < span) {
+            const pos = diff * invSpan * 255.0;
+            const pIdx = Math.min(254, pos | 0);
+            const wWeight = _T3[pIdx] + (_T3[pIdx + 1] - _T3[pIdx]) * (pos - pIdx);
+            dCluster = (dCluster < dShape ? dCluster : dShape) - wWeight * span;
+          } else if (dShape < dCluster) {
+            dCluster = dShape;
+          }
+        } else if (dShape < dCluster) {
+          dCluster = dShape;
         }
       }
       distGrid[row + x] = dCluster;
     }
   }
 
-  // Pass 2: O(1) lookup from distGrid + tabular chromatic shift (_T4)
+  // Pass 2: Fast vectorized lookup from distGrid + tabular chromatic shift (_T4)
   for (let y = 1; y < boxH - 1; y++) {
     const row = y * boxW;
     for (let x = 1; x < boxW - 1; x++) {
@@ -325,8 +354,11 @@ export function renderFusedCluster(ctx, sourceCtx, elements, rawOptions = {}, dp
         const innerDist = -d;
         if (innerDist < rimPx) {
           const u = innerDist / rimPx;
-          const gain = sampleTable(_T0, u);
-          disp = sampleTable(_T4, u);
+          const posU = u * 255.0;
+          const uIdx = Math.min(254, posU | 0);
+          const uFrac = posU - uIdx;
+          const gain = _T0[uIdx] + (_T0[uIdx + 1] - _T0[uIdx]) * uFrac;
+          disp = _T4[uIdx] + (_T4[uIdx + 1] - _T4[uIdx]) * uFrac;
 
           const dx = distGrid[row + x + 1] - distGrid[row + x - 1];
           const dy = distGrid[(y + 1) * boxW + x] - distGrid[(y - 1) * boxW + x];
@@ -339,7 +371,8 @@ export function renderFusedCluster(ctx, sourceCtx, elements, rawOptions = {}, dp
           offY = Math.round(-gy * shift);
 
           if (gy < -0.2) {
-            sheen = Math.round(sampleTable(_T2, u) * (-gy) * 0.78);
+            const sVal = _T2[uIdx] + (_T2[uIdx + 1] - _T2[uIdx]) * uFrac;
+            sheen = Math.round(sVal * (-gy) * 0.78);
           }
         } else {
           // Fast interior path: zero displacement inside flat region (-d >= rimPx)
@@ -354,7 +387,9 @@ export function renderFusedCluster(ctx, sourceCtx, elements, rawOptions = {}, dp
 
       const absD = Math.abs(d);
       if (absD < 3.0) {
-        glint = Math.round(sampleTable(_T1, absD * 0.33) * 0.65);
+        const posG = Math.min(254, absD * 0.33 * 255.0);
+        const gIdx = posG | 0;
+        glint = Math.round((_T1[gIdx] + (_T1[gIdx + 1] - _T1[gIdx]) * (posG - gIdx)) * 0.65);
       }
 
       const sxG = Math.max(0, Math.min(boxW - 1, x + offX));
@@ -448,11 +483,27 @@ function getReadableStrokeColor(borderCol, fallback = 'rgba(148, 163, 184, 0.55)
   return fallback;
 }
 
+function getDevicePixelRatio(customDpr = 0, elementWidth = 0) {
+  if (typeof customDpr === 'number' && customDpr > 0) {
+    return Math.max(0.5, Math.min(3.0, customDpr));
+  }
+  if (typeof window === 'undefined') return 1;
+  const sysDpr = window.devicePixelRatio || 1;
+  // Automatically use 1.0 for wide elements (headers, banners >= 700px) to guarantee 120 FPS
+  if (elementWidth >= 700) {
+    return 1;
+  }
+  return Math.min(sysDpr, 1.5);
+}
+
 function ensureStageBuffers() {
   if (typeof document === 'undefined') return false;
+  const dpr = getDevicePixelRatio();
   const docEl = document.documentElement;
   const vw = Math.max(1, window.innerWidth, docEl ? docEl.clientWidth : 0);
   const vh = Math.max(1, window.innerHeight, docEl ? docEl.clientHeight : 0);
+  const bufW = Math.round(vw * dpr);
+  const bufH = Math.round(vh * dpr);
 
   if (!stageCanvas) {
     stageCanvas = document.createElement('canvas');
@@ -461,11 +512,11 @@ function ensureStageBuffers() {
     blurCtx = blurCanvas.getContext('2d', { willReadFrequently: true });
   }
 
-  if (stageCanvas.width !== vw || stageCanvas.height !== vh) {
-    stageCanvas.width = vw;
-    stageCanvas.height = vh;
-    blurCanvas.width = vw;
-    blurCanvas.height = vh;
+  if (stageCanvas.width !== bufW || stageCanvas.height !== bufH) {
+    stageCanvas.width = bufW;
+    stageCanvas.height = bufH;
+    blurCanvas.width = bufW;
+    blurCanvas.height = bufH;
   }
 
   if (!clusterOverlayCanvas) {
@@ -492,14 +543,20 @@ function ensureStageBuffers() {
  */
 function captureViewportStage(neededBlur) {
   if (!ensureStageBuffers()) return;
-  const vw = stageCanvas.width;
-  const vh = stageCanvas.height;
+  const dpr = getDevicePixelRatio();
+  const bw = stageCanvas.width;
+  const bh = stageCanvas.height;
+  const vw = Math.round(bw / dpr);
+  const vh = Math.round(bh / dpr);
 
-  // 1. Base page background
-  stageCtx.fillStyle = '#040814';
-  stageCtx.fillRect(0, 0, vw, vh);
+  stageCtx.save();
 
-  // 2. Copy any background 2D canvas using its exact getBoundingClientRect() viewport box
+  // 1. Base page background (detect light/dark body background)
+  const bodyBg = typeof document !== 'undefined' ? window.getComputedStyle(document.body).backgroundColor : '';
+  stageCtx.fillStyle = bodyBg && bodyBg !== 'transparent' && bodyBg !== 'rgba(0, 0, 0, 0)' ? bodyBg : '#040814';
+  stageCtx.fillRect(0, 0, bw, bh);
+
+  // 2. Copy any background 2D canvas using physical buffer pixels
   const bgCanvases = document.querySelectorAll('canvas:not(.lg-lens-canvas):not(.lg-cluster-canvas)');
   for (let i = 0; i < bgCanvases.length; i++) {
     const c = bgCanvases[i];
@@ -507,7 +564,13 @@ function captureViewportStage(neededBlur) {
       try {
         const cr = c.getBoundingClientRect();
         if (cr.width > 0 && cr.height > 0) {
-          stageCtx.drawImage(c, cr.left, cr.top, cr.width, cr.height);
+          stageCtx.drawImage(
+            c,
+            Math.round(cr.left * dpr),
+            Math.round(cr.top * dpr),
+            Math.round(cr.width * dpr),
+            Math.round(cr.height * dpr)
+          );
         }
       } catch {
         // Ignore cross-origin canvas if any
@@ -515,6 +578,9 @@ function captureViewportStage(neededBlur) {
     }
   }
 
+  // Scale context for DOM elements rendered in CSS pixels
+  stageCtx.scale(dpr, dpr);
+
   // 3. Draw visible block surfaces (cards, buttons, pills, inputs) inside <main> and <footer>
   const surfaceEls = document.querySelectorAll(
     'main div.rounded-2xl, main div.rounded-xl, main a.rounded-2xl, main a.rounded-xl, main button, main a.inline-flex, main input, main textarea, main span.rounded-lg, main span.rounded-full'
@@ -668,13 +734,53 @@ function captureViewportStage(neededBlur) {
     stageCtx.restore();
   }
 
-  // 5. Blur buffer for frosted glass
+  stageCtx.restore();
+
+let supportsCanvasFilterBlur = null;
+function checkCanvasFilterBlur() {
+  if (supportsCanvasFilterBlur !== null) return supportsCanvasFilterBlur;
+  if (typeof document === 'undefined') return false;
+  try {
+    const testC = document.createElement('canvas');
+    testC.width = 4;
+    testC.height = 4;
+    const testCtx = testC.getContext('2d');
+    if (!testCtx || typeof testCtx.filter !== 'string') {
+      return (supportsCanvasFilterBlur = false);
+    }
+    testCtx.fillStyle = '#000';
+    testCtx.fillRect(0, 0, 4, 4);
+    testCtx.filter = 'blur(2px)';
+    testCtx.fillStyle = '#fff';
+    testCtx.fillRect(0, 0, 2, 2);
+    testCtx.filter = 'none';
+    const imgData = testCtx.getImageData(0, 0, 4, 4).data;
+    supportsCanvasFilterBlur = imgData[15 * 4] > 0 || imgData[14 * 4] > 0 || imgData[11 * 4] > 0;
+    return supportsCanvasFilterBlur;
+  } catch {
+    return (supportsCanvasFilterBlur = false);
+  }
+}
+
+  // 5. Blur buffer for frosted glass (Robust across all mobile WebKit & Blink engines)
   if (neededBlur > 0) {
     lastFrostedRadius = neededBlur;
-    blurCtx.clearRect(0, 0, vw, vh);
-    blurCtx.filter = `blur(${neededBlur}px) saturate(135%)`;
-    blurCtx.drawImage(stageCanvas, 0, 0);
-    blurCtx.filter = 'none';
+    blurCtx.clearRect(0, 0, bw, bh);
+
+    if (checkCanvasFilterBlur()) {
+      blurCtx.filter = `blur(${Math.round(neededBlur * dpr)}px)`;
+      blurCtx.drawImage(stageCanvas, 0, 0);
+      blurCtx.filter = 'none';
+    } else {
+      // Hardware-accelerated multi-step pyramid downscale/upscale blur for iOS Safari and mobile WebKit
+      const factor = Math.max(0.04, 1.0 / (1.0 + neededBlur * 0.45));
+      const pw = Math.max(4, Math.round(bw * factor));
+      const ph = Math.max(4, Math.round(bh * factor));
+      blurCtx.imageSmoothingEnabled = true;
+      blurCtx.imageSmoothingQuality = 'high';
+      blurCtx.drawImage(stageCanvas, 0, 0, pw, ph);
+      blurCtx.drawImage(blurCanvas, 0, 0, pw, ph, 0, 0, bw, bh);
+    }
   }
 }
 
@@ -682,17 +788,19 @@ function captureViewportStage(neededBlur) {
  * Fast Isolated Lens Renderer (Takes ~0.12 ms using precomputed TypedArray LUT!)
  */
 function renderIsolatedController(ctrl, rect) {
-  const w = Math.max(16, Math.round(rect.width));
-  const h = Math.max(16, Math.round(rect.height));
+  const dpr = getDevicePixelRatio(ctrl.options.dpr, rect.width);
+  const w = Math.max(16, Math.round(rect.width * dpr));
+  const h = Math.max(16, Math.round(rect.height * dpr));
   const rad = ctrl._getRadius();
+  const radPx = Math.min(rad * dpr, w * 0.5, h * 0.5);
 
   if (
     !ctrl._lut ||
     ctrl._lut.w !== w ||
     ctrl._lut.h !== h ||
-    Math.abs(ctrl._lut.rad - Math.min(rad, w * 0.5, h * 0.5)) > 1.0
+    Math.abs(ctrl._lut.rad - radPx) > 1.0
   ) {
-    ctrl._lut = buildElementLUT(w, h, rad, ctrl.options, 1);
+    ctrl._lut = buildElementLUT(w, h, rad, ctrl.options, dpr);
   }
 
   const lut = ctrl._lut;
@@ -701,9 +809,9 @@ function renderIsolatedController(ctrl, rect) {
     ctrl._canvas.height = h;
   }
 
-  // Use exact un-clamped element position so dragging near/past mobile viewport edges never shifts the image
-  const dx = Math.round(rect.left);
-  const dy = Math.round(rect.top);
+  // Use exact un-clamped element position in physical canvas pixels
+  const dx = Math.round(rect.left * dpr);
+  const dy = Math.round(rect.top * dpr);
 
   const sourceCtx = ctrl.options.frosted > 0 ? blurCtx : stageCtx;
   const srcImg = sourceCtx.getImageData(dx, dy, w, h);
@@ -773,7 +881,7 @@ function renderIsolatedController(ctrl, rect) {
   ctrl._canvas.style.opacity = '1';
 }
 
-function areRectsTouching(r1, r2, threshold = 42) {
+function areRectsTouching(r1, r2, threshold = 24) {
   const dx = Math.max(
     0,
     Math.abs(r1.left + r1.width * 0.5 - (r2.left + r2.width * 0.5)) -
@@ -843,7 +951,7 @@ function renderAllActiveLenses() {
     if (!visible[i].ctrl.options.fusion) continue;
     for (let j = i + 1; j < n; j++) {
       if (!visible[j].ctrl.options.fusion) continue;
-      if (areRectsTouching(visible[i].rect, visible[j].rect, 54)) {
+      if (areRectsTouching(visible[i].rect, visible[j].rect, 24)) {
         union(i, j);
       }
     }
@@ -861,21 +969,13 @@ function renderAllActiveLenses() {
   for (const group of clusters.values()) {
     if (group.length === 1) {
       const { ctrl, rect } = group[0];
-      if (ctrl._savedShadow && ctrl.element.style.boxShadow === 'none') {
-        ctrl.element.style.boxShadow = ctrl._savedInlineShadow || '';
-      }
       if (rect.bottom > 1 && rect.top < vh) {
         renderIsolatedController(ctrl, rect);
       }
     } else {
       hasFusedCluster = true;
-      let anyHasShadow = false;
       for (const item of group) {
         item.ctrl._canvas.style.opacity = '0';
-        if (item.ctrl._savedShadow) {
-          anyHasShadow = true;
-          item.ctrl.element.style.boxShadow = 'none';
-        }
       }
       const primaryCtrl = group[group.length - 1].ctrl;
       const sourceCtx = primaryCtrl.options.frosted > 0 ? blurCtx : stageCtx;
@@ -886,28 +986,40 @@ function renderAllActiveLenses() {
         h: rect.height,
         borderRadius: ctrl._getRadius(),
         fusion: true,
-        tint: ctrl._tint
+        tint: ctrl._tint,
+        dpr: ctrl.options.dpr
       }));
 
+      const maxClusterWidth = Math.max(...group.map(g => g.rect.width));
+      const dpr = getDevicePixelRatio(primaryCtrl.options.dpr, maxClusterWidth);
       const box = renderFusedCluster(
         clusterOverlayCtx,
         sourceCtx,
         elements,
         {
           ...primaryCtrl.options,
-          fusionDistance: 64
+          fusionDistance: 24
         },
-        1
+        dpr
       );
 
       if (box && clusterOverlayCanvas) {
         clusterOverlayCanvas.style.display = 'block';
-        clusterOverlayCanvas.style.filter = anyHasShadow
-          ? 'drop-shadow(3px 14px 18px rgba(0, 0, 0, 0.16))'
-          : 'none';
-        clusterOverlayCanvas.style.transform = `translate3d(${box.cMinX}px, ${box.cMinY}px, 0)`;
-        clusterOverlayCanvas.style.width = `${box.boxW}px`;
-        clusterOverlayCanvas.style.height = `${box.boxH}px`;
+        clusterOverlayCanvas.style.filter = 'none';
+
+        // Match z-index to highest element in the cluster so it never pops above floating menus/controls
+        let maxZ = 20;
+        for (const item of group) {
+          if (item.ctrl && item.ctrl.element) {
+            const z = parseInt(window.getComputedStyle(item.ctrl.element).zIndex, 10);
+            if (!Number.isNaN(z) && z > maxZ) maxZ = z;
+          }
+        }
+        clusterOverlayCanvas.style.zIndex = String(maxZ);
+
+        clusterOverlayCanvas.style.transform = `translate3d(${box.cMinX / dpr}px, ${box.cMinY / dpr}px, 0)`;
+        clusterOverlayCanvas.style.width = `${box.boxW / dpr}px`;
+        clusterOverlayCanvas.style.height = `${box.boxH / dpr}px`;
       }
     }
   }
@@ -1077,11 +1189,11 @@ export class LiquidGlassController {
       changed = true;
     }
 
-    for (const key of ['rim', 'ior', 'height', 'frosted', 'fusion']) {
+    for (const key of ['rim', 'ior', 'height', 'frosted', 'fusion', 'dpr']) {
       if (merged[key] !== this.options[key]) {
         this.options[key] = merged[key];
         changed = true;
-        if (key === 'rim' || key === 'ior' || key === 'height') {
+        if (key === 'rim' || key === 'ior' || key === 'height' || key === 'dpr') {
           lutChanged = true;
         }
       }

package/dist/react.cjs

@@ -31,7 +31,8 @@ exports.useLiquidGlass = function useLiquidGlass(options = {}) {
         height: options.height,
         frosted: options.frosted,
         fusion: options.fusion,
-        enabled: options.enabled
+        enabled: options.enabled,
+        dpr: options.dpr
       });
     }
   }, [
@@ -40,7 +41,8 @@ exports.useLiquidGlass = function useLiquidGlass(options = {}) {
     options.height,
     options.frosted,
     options.fusion,
-    options.enabled
+    options.enabled,
+    options.dpr
   ]);
 
   return ref;
@@ -57,6 +59,7 @@ const LiquidGlass = exports.LiquidGlass = forwardRef(function LiquidGlass(
     frosted = OPTICAL_DEFAULTS.frosted,
     fusion = OPTICAL_DEFAULTS.fusion,
     enabled = true,
+    dpr = OPTICAL_DEFAULTS.dpr,
     as: Component = 'div',
     style,
     className,
@@ -71,7 +74,8 @@ const LiquidGlass = exports.LiquidGlass = forwardRef(function LiquidGlass(
     height,
     frosted,
     fusion,
-    enabled
+    enabled,
+    dpr
   });
 
   const setRefs = useCallback(

package/dist/react.mjs

@@ -30,7 +30,8 @@ export function useLiquidGlass(options = {}) {
         height: options.height,
         frosted: options.frosted,
         fusion: options.fusion,
-        enabled: options.enabled
+        enabled: options.enabled,
+        dpr: options.dpr
       });
     }
   }, [
@@ -39,7 +40,8 @@ export function useLiquidGlass(options = {}) {
     options.height,
     options.frosted,
     options.fusion,
-    options.enabled
+    options.enabled,
+    options.dpr
   ]);
 
   return ref;
@@ -56,6 +58,7 @@ export const LiquidGlass = forwardRef(function LiquidGlass(
     frosted = OPTICAL_DEFAULTS.frosted,
     fusion = OPTICAL_DEFAULTS.fusion,
     enabled = true,
+    dpr = OPTICAL_DEFAULTS.dpr,
     as: Component = 'div',
     style,
     className,
@@ -70,7 +73,8 @@ export const LiquidGlass = forwardRef(function LiquidGlass(
     height,
     frosted,
     fusion,
-    enabled
+    enabled,
+    dpr
   });
 
   const setRefs = useCallback(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shulya/liquid-glass",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "High-performance, zero-WebGL Liquid Glass optical UI engine with pre-computed empirical lookup tables for React, Vue, Svelte, Angular, SolidJS, and Vanilla JS.",
   "author": "Shulya (https://shulya.tech)",
   "homepage": "https://liquid.shulya.tech",

package/types/index.d.ts

@@ -30,6 +30,12 @@ export interface LiquidGlassOptions {
    */
   enabled?: boolean;
 
+  /**
+   * Optional custom device pixel ratio override (e.g. 1.0 for full-width navbars to maximize FPS, or 1.5–2.0 for high-DPI retina sharpness).
+   * Defaults to 0 (automatic: 1.5 for compact UI elements, 1.0 for elements >= 700px wide).
+   */
+  dpr?: number;
+
   /**
    * Optional border radius override in pixels
    */
@@ -42,6 +48,7 @@ export declare const OPTICAL_DEFAULTS: Readonly<{
   height: 18;
   frosted: 0;
   fusion: true;
+  dpr: 0;
 }>;
 
 export declare const OPTICAL_LIMITS: Readonly<{
@@ -49,6 +56,7 @@ export declare const OPTICAL_LIMITS: Readonly<{
   ior: Readonly<{ min: 1.05; max: 2.2 }>;
   height: Readonly<{ min: 2; max: 50 }>;
   frosted: Readonly<{ min: 0; max: 32 }>;
+  dpr: Readonly<{ min: 0.5; max: 3.0 }>;
 }>;
 
 export declare function normalizeOptions(options?: LiquidGlassOptions): Required<LiquidGlassOptions>;