vireglass 3.0.1 → 3.1.0

package/dist/dom.d.cts

@@ -309,6 +309,20 @@ declare function cached<T>(key: string, build: () => T): T;
 declare function clearMapCache(): void;
 declare function mapCacheSize(): number;
 
+type RenderStats = {
+    /** `elementsFromPoint` backdrop probes. */
+    probes: number;
+    /** Displacement maps baked at full device resolution (cache hits are not bakes). */
+    fullBakes: number;
+    /** Displacement maps baked at reduced resolution: interim morphs and the finger path. */
+    reducedBakes: number;
+    /** Filter elements put into the shared `<defs>`, replacing or adding. */
+    filterSwaps: number;
+};
+/** The work the renderer has done since the last reset; the hook for a consumer's performance gate. */
+declare function renderStats(): RenderStats;
+declare function resetRenderStats(): void;
+
 type AttachGlassOptions = {
     material?: Partial<VireGlassMaterial>;
     /** Defaults to the element's measured box (size + `border-radius`). */
@@ -405,6 +419,14 @@ type GlassHandle = {
         strength: number;
     } | null): void;
     setMorph(morph: GlassMorph | null): void;
+    /**
+     * While on, the element is changing shape every frame (a morph, a drag, a growth). It stops
+     * probing the backdrop, stops rebuilding its maps and keeps its filter: the existing map is
+     * stretched over the live box. A change of `setMorph` shapes still updates the map, at reduced
+     * resolution and only once the new image has decoded. Turning it off does one full-resolution
+     * rebuild and one probe. Repeated calls with the same value do nothing.
+     */
+    setInterim(on: boolean): void;
     /**
      * Replaces the backdrop the glass adapts to, without re-attaching, and repaints. The same
      * object as `sample` in the options; `null` goes back to probing declared backgrounds.
@@ -414,4 +436,4 @@ type GlassHandle = {
 };
 declare function attachGlass(el: HTMLElement, opts?: AttachGlassOptions): GlassHandle;
 
-export { type AttachGlassOptions, type BodyBackdrop, type BodyLayer, type DisplacementMap, type DisplacementState, type EdgePaint, type GlassBody, type GlassGroupHandle, type GlassGroupOptions, type GlassHandle, type GlassMorph, type GroupEntry, type ProbeOptions, RIM_WIDTH_PX, type RgbColor, type RimAmbient, type ScrollEdgeHandle, type ScrollEdgeOptions, type SpectralMap, ambientLuma, attachGlass, attachScrollEdge, bodyLayer, boxShadowCss, buildDisplacementMap, buildSpectralMap, cached, clearMapCache, compositeLayers, contrastRimCss, createGlassGroup, hasSpectralEdge, lightConicAngle, mapCacheSize, paintFor, parseColor, probeBackdrop, renderDisplacementPixels, renderSpectralPixels, resetSupportCache, resolveBody, rimGradientCss, rimLineAlpha, rimLobe, rimStrength, shadowAlphaFrom, statsFromSamples, supportsBackdropFilter, supportsSvgBackdropFilter, systemAccessibility, watchAccessibility, withPresence };
+export { type AttachGlassOptions, type BodyBackdrop, type BodyLayer, type DisplacementMap, type DisplacementState, type EdgePaint, type GlassBody, type GlassGroupHandle, type GlassGroupOptions, type GlassHandle, type GlassMorph, type GroupEntry, type ProbeOptions, RIM_WIDTH_PX, type RenderStats, type RgbColor, type RimAmbient, type ScrollEdgeHandle, type ScrollEdgeOptions, type SpectralMap, ambientLuma, attachGlass, attachScrollEdge, bodyLayer, boxShadowCss, buildDisplacementMap, buildSpectralMap, cached, clearMapCache, compositeLayers, contrastRimCss, createGlassGroup, hasSpectralEdge, lightConicAngle, mapCacheSize, paintFor, parseColor, probeBackdrop, renderDisplacementPixels, renderSpectralPixels, renderStats, resetRenderStats, resetSupportCache, resolveBody, rimGradientCss, rimLineAlpha, rimLobe, rimStrength, shadowAlphaFrom, statsFromSamples, supportsBackdropFilter, supportsSvgBackdropFilter, systemAccessibility, watchAccessibility, withPresence };

package/dist/dom.d.ts

@@ -309,6 +309,20 @@ declare function cached<T>(key: string, build: () => T): T;
 declare function clearMapCache(): void;
 declare function mapCacheSize(): number;
 
+type RenderStats = {
+    /** `elementsFromPoint` backdrop probes. */
+    probes: number;
+    /** Displacement maps baked at full device resolution (cache hits are not bakes). */
+    fullBakes: number;
+    /** Displacement maps baked at reduced resolution: interim morphs and the finger path. */
+    reducedBakes: number;
+    /** Filter elements put into the shared `<defs>`, replacing or adding. */
+    filterSwaps: number;
+};
+/** The work the renderer has done since the last reset; the hook for a consumer's performance gate. */
+declare function renderStats(): RenderStats;
+declare function resetRenderStats(): void;
+
 type AttachGlassOptions = {
     material?: Partial<VireGlassMaterial>;
     /** Defaults to the element's measured box (size + `border-radius`). */
@@ -405,6 +419,14 @@ type GlassHandle = {
         strength: number;
     } | null): void;
     setMorph(morph: GlassMorph | null): void;
+    /**
+     * While on, the element is changing shape every frame (a morph, a drag, a growth). It stops
+     * probing the backdrop, stops rebuilding its maps and keeps its filter: the existing map is
+     * stretched over the live box. A change of `setMorph` shapes still updates the map, at reduced
+     * resolution and only once the new image has decoded. Turning it off does one full-resolution
+     * rebuild and one probe. Repeated calls with the same value do nothing.
+     */
+    setInterim(on: boolean): void;
     /**
      * Replaces the backdrop the glass adapts to, without re-attaching, and repaints. The same
      * object as `sample` in the options; `null` goes back to probing declared backgrounds.
@@ -414,4 +436,4 @@ type GlassHandle = {
 };
 declare function attachGlass(el: HTMLElement, opts?: AttachGlassOptions): GlassHandle;
 
-export { type AttachGlassOptions, type BodyBackdrop, type BodyLayer, type DisplacementMap, type DisplacementState, type EdgePaint, type GlassBody, type GlassGroupHandle, type GlassGroupOptions, type GlassHandle, type GlassMorph, type GroupEntry, type ProbeOptions, RIM_WIDTH_PX, type RgbColor, type RimAmbient, type ScrollEdgeHandle, type ScrollEdgeOptions, type SpectralMap, ambientLuma, attachGlass, attachScrollEdge, bodyLayer, boxShadowCss, buildDisplacementMap, buildSpectralMap, cached, clearMapCache, compositeLayers, contrastRimCss, createGlassGroup, hasSpectralEdge, lightConicAngle, mapCacheSize, paintFor, parseColor, probeBackdrop, renderDisplacementPixels, renderSpectralPixels, resetSupportCache, resolveBody, rimGradientCss, rimLineAlpha, rimLobe, rimStrength, shadowAlphaFrom, statsFromSamples, supportsBackdropFilter, supportsSvgBackdropFilter, systemAccessibility, watchAccessibility, withPresence };
+export { type AttachGlassOptions, type BodyBackdrop, type BodyLayer, type DisplacementMap, type DisplacementState, type EdgePaint, type GlassBody, type GlassGroupHandle, type GlassGroupOptions, type GlassHandle, type GlassMorph, type GroupEntry, type ProbeOptions, RIM_WIDTH_PX, type RenderStats, type RgbColor, type RimAmbient, type ScrollEdgeHandle, type ScrollEdgeOptions, type SpectralMap, ambientLuma, attachGlass, attachScrollEdge, bodyLayer, boxShadowCss, buildDisplacementMap, buildSpectralMap, cached, clearMapCache, compositeLayers, contrastRimCss, createGlassGroup, hasSpectralEdge, lightConicAngle, mapCacheSize, paintFor, parseColor, probeBackdrop, renderDisplacementPixels, renderSpectralPixels, renderStats, resetRenderStats, resetSupportCache, resolveBody, rimGradientCss, rimLineAlpha, rimLobe, rimStrength, shadowAlphaFrom, statsFromSamples, supportsBackdropFilter, supportsSvgBackdropFilter, systemAccessibility, watchAccessibility, withPresence };

package/dist/dom.js

@@ -340,6 +340,55 @@ function probeBackdrop(el, opts = {}) {
   return statsFromSamples(samples);
 }
 
+// src/dom/stats.ts
+var counts = { probes: 0, fullBakes: 0, reducedBakes: 0, filterSwaps: 0 };
+function renderStats() {
+  return { ...counts };
+}
+function resetRenderStats() {
+  counts.probes = 0;
+  counts.fullBakes = 0;
+  counts.reducedBakes = 0;
+  counts.filterSwaps = 0;
+}
+function bump(key) {
+  counts[key] += 1;
+}
+
+// src/dom/interim.ts
+function quantise(value, step = 2) {
+  return Math.round(value / step) * step;
+}
+function interimKey(width, height, cornerRadius, morph, extra) {
+  return `i|${quantise(width)}x${quantise(height)}r${quantise(cornerRadius)}|${morph}|${extra}`;
+}
+function filterSignature(blur, ior, iorSpread, hasHue) {
+  return `${blur}|${ior}|${iorSpread > 1e-4 ? iorSpread : 0}|${hasHue ? "h" : "-"}`;
+}
+function createLru(limit) {
+  const store2 = /* @__PURE__ */ new Map();
+  return {
+    get(key) {
+      const hit = store2.get(key);
+      if (hit === void 0) return void 0;
+      store2.delete(key);
+      store2.set(key, hit);
+      return hit;
+    },
+    set(key, value) {
+      store2.delete(key);
+      store2.set(key, value);
+      if (store2.size > limit) {
+        const oldest = store2.keys().next();
+        if (!oldest.done) store2.delete(oldest.value);
+      }
+    },
+    get size() {
+      return store2.size;
+    }
+  };
+}
+
 // src/dom/support.ts
 var backdropFilterSupport = null;
 var svgBackdropFilterSupport = null;
@@ -679,7 +728,7 @@ function createGlassGroup(members, opts = {}) {
   }
   function update() {
     if (destroyed) return;
-    const probe = opts.probe ?? probeBackdrop;
+    const probe2 = opts.probe ?? probeBackdrop;
     members.forEach(({ el, legibility }, index) => {
       const rect = el.getBoundingClientRect();
       if (rect.width <= 0 || rect.height <= 0) {
@@ -690,7 +739,7 @@ function createGlassGroup(members, opts = {}) {
         String(index),
         rect.left + rect.width / 2,
         rect.top + rect.height / 2,
-        probe(el),
+        probe2(el),
         legibility ?? 0
       );
     });
@@ -854,6 +903,18 @@ function fallbackFilterCss(optics) {
   const saturate = 1 + optics.colorPickup;
   return `blur(${blurPx}px) saturate(${saturate})`;
 }
+function probe(el) {
+  bump("probes");
+  return probeBackdrop(el);
+}
+function decoded(url) {
+  if (typeof Image === "undefined") return Promise.resolve();
+  const img = new Image();
+  img.src = url;
+  return typeof img.decode === "function" ? img.decode().catch(() => void 0) : Promise.resolve();
+}
+var INTERIM_IDLE_MS = 2e3;
+var isEmpty = (g) => quantise(g.width) < 1 || quantise(g.height) < 1;
 var to2553 = (v) => Math.round(Math.min(Math.max(v, 0), 1) * 255);
 function rgbCss(r, g, b) {
   return `rgb(${to2553(r)} ${to2553(g)} ${to2553(b)})`;
@@ -880,6 +941,13 @@ function attachGlass(el, opts = {}) {
   let filterEl = null;
   let destroyed = false;
   let mapKey = "";
+  let interim = false;
+  let settling = false;
+  let lastSample = null;
+  let seq = 0;
+  let shownSeq = 0;
+  let idleTimer = null;
+  const interimMaps = createLru(8);
   let morph = null;
   const onlyWhenTouched = opts.variant === "interactive";
   let appear = onlyWhenTouched ? 0 : opts.appear ?? 1;
@@ -891,6 +959,7 @@ function attachGlass(el, opts = {}) {
     mapKey = "";
     deform.setElastic(elasticAllowed(opts.accessibility ?? a11y));
     apply();
+    if (interim) requestInterimMap();
   });
   warnIfNested(el);
   const host = hostFor(el);
@@ -916,24 +985,111 @@ function attachGlass(el, opts = {}) {
     const part = (s) => s ? `${s.offsetX},${s.offsetY},${s.width},${s.height},${s.cornerRadius}` : "-";
     return `${morph.smoothing}/${part(morph.shape)}/${part(morph.shape2)}`;
   }
+  function invalidate() {
+    seq += 1;
+    shownSeq = seq;
+  }
+  function keepInterim() {
+    if (idleTimer !== null) clearTimeout(idleTimer);
+    idleTimer = setTimeout(leaveInterim, INTERIM_IDLE_MS);
+  }
+  function leaveInterim() {
+    if (idleTimer !== null) clearTimeout(idleTimer);
+    idleTimer = null;
+    if (destroyed || !interim) return;
+    interim = false;
+    invalidate();
+    mapKey = "";
+    settling = true;
+    apply();
+  }
+  function retarget(f, map, hue) {
+    const images = f.querySelectorAll("feImage");
+    images[0]?.setAttribute("href", map.url);
+    if (hue) images[1]?.setAttribute("href", hue.url);
+    for (const pass of f.querySelectorAll("feDisplacementMap")) {
+      const ratio = Number(pass.getAttribute("data-vireglass-ratio") ?? 1);
+      pass.setAttribute("scale", String(map.scale * (Number.isFinite(ratio) ? ratio : 1)));
+    }
+  }
+  function requestInterimMap() {
+    if (!svgSupported || !filterEl || destroyed) return;
+    const geometry = opts.geometry ?? measureGeometry(el);
+    if (isEmpty(geometry)) return;
+    const opticsNow = optics();
+    const key = interimKey(
+      geometry.width,
+      geometry.height,
+      geometry.cornerRadius,
+      JSON.stringify([morph?.smoothing, morph?.shape, morph?.shape2, morph?.shapes]),
+      `a${appear.toFixed(3)}:${opticsNow.refraction}:${opticsNow.refractionScale}:${opticsNow.bevelDp}`
+    );
+    let rec = interimMaps.get(key);
+    if (!rec) {
+      bump("reducedBakes");
+      rec = { map: buildDisplacementMap(opticsNow, geometry, Math.min(1, devicePixelRatio()), morphState()), ready: false };
+      interimMaps.set(key, rec);
+    }
+    const mine = seq += 1;
+    const record = rec;
+    const forFilter = filterEl;
+    const show = () => {
+      if (destroyed || filterEl !== forFilter || mine <= shownSeq) return;
+      shownSeq = mine;
+      retarget(forFilter, record.map, null);
+    };
+    if (record.ready) {
+      show();
+      return;
+    }
+    void decoded(record.map.url).then(() => {
+      record.ready = true;
+      show();
+    });
+  }
   function apply() {
     if (destroyed) return;
+    if (interim) keepInterim();
     const geometry = opts.geometry ?? measureGeometry(el);
     const opticsNow = optics();
-    const sample = supplied ?? probeBackdrop(el);
+    const sample = supplied ?? (interim && lastSample ? lastSample : probe(el));
+    lastSample = sample;
     const light = shouldInkBeLight(sample, wasLight);
     wasLight = light;
     const body = opts.body === false ? null : bodyCss(settledOptics(), sample, light ? 1 : 0, accent, appear);
     if (svgSupported) {
       const key = `a${appear.toFixed(3)}|m${morphKey()}|${geometry.width}x${geometry.height}r${geometry.cornerRadius}@${devicePixelRatio()}:${opticsNow.refraction}:${opticsNow.refractionScale}:${opticsNow.bevelDp}:${opticsNow.blur}`;
-      if (key !== mapKey || !filterEl) {
-        const map = cached(`d|${key}`, () => buildDisplacementMap(opticsNow, geometry, devicePixelRatio(), morphState()));
-        const defs = getFilterHost(host).querySelector("defs");
-        const hue = hasSpectralEdge(opticsNow) ? cached(`h|${key}`, () => buildSpectralMap(opticsNow, geometry, devicePixelRatio())) : null;
-        const next = buildFilterElement(id, map.url, opticsNow, map.scale, hue);
-        if (filterEl?.parentNode) defs.replaceChild(next, filterEl);
-        else defs.appendChild(next);
-        filterEl = next;
+      if (interim && filterEl) ; else if (isEmpty(geometry)) ; else if (key !== mapKey || !filterEl) {
+        const map = cached(`d|${key}`, () => {
+          bump("fullBakes");
+          return buildDisplacementMap(opticsNow, geometry, devicePixelRatio(), morphState());
+        });
+        const hue = hasSpectralEdge(opticsNow) ? cached(`h|${key}`, () => {
+          bump("fullBakes");
+          return buildSpectralMap(opticsNow, geometry, devicePixelRatio());
+        }) : null;
+        const signature = filterSignature(opticsNow.blur, opticsNow.ior, opticsNow.iorSpread, !!hue);
+        if (settling && filterEl?.getAttribute("data-vireglass-signature") === signature) {
+          settling = false;
+          const mine = seq += 1;
+          const forFilter = filterEl;
+          const forKey = key;
+          void Promise.all([decoded(map.url), hue ? decoded(hue.url) : void 0]).then(() => {
+            if (destroyed || filterEl !== forFilter || mapKey !== forKey || mine <= shownSeq) return;
+            shownSeq = mine;
+            retarget(forFilter, map, hue);
+          });
+        } else {
+          settling = false;
+          invalidate();
+          const defs = getFilterHost(host).querySelector("defs");
+          const next = buildFilterElement(id, map.url, opticsNow, map.scale, hue);
+          next.setAttribute("data-vireglass-signature", signature);
+          if (filterEl?.parentNode) defs.replaceChild(next, filterEl);
+          else defs.appendChild(next);
+          bump("filterSwaps");
+          filterEl = next;
+        }
         mapKey = key;
       }
       el.style.setProperty("backdrop-filter", `url(#${id})`);
@@ -980,7 +1136,9 @@ function attachGlass(el, opts = {}) {
     const base = optics();
     const rise = raiseIntoGlass(sampleOut.press);
     const risen = optics({ ...opts.material, roughness: (opts.material?.roughness ?? VIREGLASS_MATERIAL.roughness) * rise.solid });
-    const map = buildDisplacementMap(risen, geometry, interacting ? 1 : devicePixelRatio(), {
+    if (interim) keepInterim();
+    bump("reducedBakes");
+    const map = buildDisplacementMap(risen, geometry, 1, {
       ...morphState(),
       touch: {
         x: sampleOut.touchX,
@@ -993,6 +1151,7 @@ function attachGlass(el, opts = {}) {
         wavePhase: sampleOut.wavePhase
       }
     });
+    invalidate();
     if (filterEl) {
       const feImage = filterEl.querySelector("feImage");
       feImage?.setAttribute("href", map.url);
@@ -1015,7 +1174,7 @@ function attachGlass(el, opts = {}) {
       el.style.setProperty("--vireglass-glow-opacity", "0");
       return;
     }
-    const [gr, gg, gb] = ambientFrom(supplied ?? probeBackdrop(el));
+    const [gr, gg, gb] = ambientFrom(supplied ?? (interim && lastSample ? lastSample : probe(el)));
     const cx = (x + geometry.width / 2) / geometry.width * 100;
     const cy = (y + geometry.height / 2) / geometry.height * 100;
     const reach = halfMinDp(geometry) * TOUCH_RADIUS_FRACTION;
@@ -1039,7 +1198,9 @@ function attachGlass(el, opts = {}) {
       lastFrameAt = 0;
       el.style.setProperty("--vireglass-glow-opacity", "0");
       opts.onGlow?.(null);
+      settling = !interim;
       apply();
+      if (interim) requestInterimMap();
       return;
     }
     frame = requestAnimationFrame(tick);
@@ -1087,6 +1248,9 @@ function attachGlass(el, opts = {}) {
   }
   function destroy() {
     destroyed = true;
+    invalidate();
+    if (idleTimer !== null) clearTimeout(idleTimer);
+    idleTimer = null;
     stopWatchingA11y();
     if (attached.get(el) === handle) attached.delete(el);
     if (frame !== null) cancelAnimationFrame(frame);
@@ -1128,6 +1292,7 @@ function attachGlass(el, opts = {}) {
       if (next === appear) return;
       appear = next;
       apply();
+      if (interim) requestInterimMap();
     },
     setAccent(next) {
       accent = next ?? void 0;
@@ -1150,9 +1315,23 @@ function attachGlass(el, opts = {}) {
     },
     setMorph(next) {
       morph = next && next.smoothing > 0 ? next : null;
+      if (interim) {
+        apply();
+        requestInterimMap();
+        return;
+      }
       mapKey = "";
       apply();
     },
+    setInterim(on) {
+      if (destroyed || on === interim) return;
+      if (on) {
+        interim = true;
+        keepInterim();
+        return;
+      }
+      leaveInterim();
+    },
     setSample(next) {
       supplied = next ?? void 0;
       apply();
@@ -1163,6 +1342,6 @@ function attachGlass(el, opts = {}) {
   return handle;
 }
 
-export { RIM_WIDTH_PX, ambientLuma, attachGlass, attachScrollEdge, bodyLayer, boxShadowCss, buildDisplacementMap, buildSpectralMap, cached, clearMapCache, compositeLayers, contrastRimCss, createGlassGroup, hasSpectralEdge, lightConicAngle, mapCacheSize, paintFor, parseColor, probeBackdrop, renderDisplacementPixels, renderSpectralPixels, resetSupportCache, resolveBody, rimGradientCss, rimLineAlpha, rimLobe, rimStrength, shadowAlphaFrom, statsFromSamples, supportsBackdropFilter, supportsSvgBackdropFilter, systemAccessibility, watchAccessibility, withPresence };
+export { RIM_WIDTH_PX, ambientLuma, attachGlass, attachScrollEdge, bodyLayer, boxShadowCss, buildDisplacementMap, buildSpectralMap, cached, clearMapCache, compositeLayers, contrastRimCss, createGlassGroup, hasSpectralEdge, lightConicAngle, mapCacheSize, paintFor, parseColor, probeBackdrop, renderDisplacementPixels, renderSpectralPixels, renderStats, resetRenderStats, resetSupportCache, resolveBody, rimGradientCss, rimLineAlpha, rimLobe, rimStrength, shadowAlphaFrom, statsFromSamples, supportsBackdropFilter, supportsSvgBackdropFilter, systemAccessibility, watchAccessibility, withPresence };
 //# sourceMappingURL=dom.js.map
 //# sourceMappingURL=dom.js.map