vireglass 3.0.0 → 3.1.0

package/README.md

@@ -153,6 +153,36 @@ glass.setMorph({ smoothing: 34, shape: { offsetX: 150, offsetY: -78, width: 170,
 Two shapes joined through the smooth union — §5's merging and splitting. What the shapes mean is
 your choreography; the material only knows how two silhouettes join.
 
+### Morphing elements
+
+```ts
+import { attachGlass, renderStats, resetRenderStats } from 'vireglass/dom';
+
+glass.setInterim(true);   // before a morph, a drag or a growth
+// ...animate the element's box, and `setMorph` shapes if it flows into others...
+glass.setInterim(false);  // when it lands
+```
+
+A glass element that changes shape every frame used to re-run the whole pipeline every frame: a
+backdrop probe, a full-resolution displacement map (and spectral map) and a new filter element.
+That is the difference between 60 fps and 10 to 20. While interim, the element does none of it: it
+reuses its last sample, keeps its filter, and the browser stretches the existing map over the live
+box. The body, rim, shadow and custom properties still update every frame. A change of the morph
+shapes passed to `setMorph`, of `setAppear` or of the system accessibility settings rebuilds the map
+at reduced resolution and shows it in place, where the browser decodes lazily only once it has been
+decoded. `setInterim(false)` does one full-resolution rebuild and one probe (with a supplied
+`sample` it does not probe). Repeating a call is a no-op.
+
+Always pair `setInterim(true)` with `setInterim(false)`. As a safety net an element that gets no call
+at all for 2 seconds (no resize, morph, appear or update) leaves interim by itself, exactly as
+`setInterim(false)` would, so a morph that never reported landing cannot leave the glass on a
+stretched map. A pause longer than that in the middle of a morph ends interim early.
+
+`renderStats()` returns `{ probes, fullBakes, reducedBakes, filterSwaps }`, counted since the last
+`resetRenderStats()`. Every map counts: a rebuild with a spectral edge is two full bakes, one for
+each map; a cache hit is none. It is the hook for a performance gate that counts work instead of
+timing it: drive a morph, then assert the counters stayed at zero.
+
 `attachGlass` writes CSS custom properties you can use directly:
 
 | | |

package/dist/dom.cjs

@@ -1024,6 +1024,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(blur2, ior, iorSpread2, hasHue) {
+  return `${blur2}|${ior}|${iorSpread2 > 1e-4 ? iorSpread2 : 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;
@@ -1338,9 +1387,11 @@ function rimGradientCss(optics, ambient, light, appear = 1) {
   return `conic-gradient(from ${start.toFixed(1)}deg, ${line.join(", ")}), conic-gradient(${dark} 0deg, ${dark} 360deg)`;
 }
 var RIM_WIDTH_PX = RIM.widthPx;
-function contrastRimCss(bodyLuma, rimLuma) {
+function contrastRimCss(bodyLuma, rimLuma, appear = 1) {
   const v = to2552(rimLuma);
-  return `conic-gradient(rgb(${v},${v},${v}) 0deg, rgb(${v},${v},${v}) 360deg)`;
+  const present = clamp016(appear);
+  const colour = present >= 1 ? `rgb(${v},${v},${v})` : `rgba(${v},${v},${v},${present.toFixed(3)})`;
+  return `conic-gradient(${colour} 0deg, ${colour} 360deg)`;
 }
 
 // src/dom/nesting.ts
@@ -1685,7 +1736,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) {
@@ -1696,7 +1747,7 @@ function createGlassGroup(members, opts = {}) {
         String(index),
         rect.left + rect.width / 2,
         rect.top + rect.height / 2,
-        probe(el),
+        probe2(el),
         legibility ?? 0
       );
     });
@@ -1860,6 +1911,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)})`;
@@ -1886,6 +1949,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;
@@ -1897,6 +1967,7 @@ function attachGlass(el, opts = {}) {
     mapKey = "";
     deform.setElastic(elasticAllowed(opts.accessibility ?? a11y));
     apply();
+    if (interim) requestInterimMap();
   });
   warnIfNested(el);
   const host = hostFor(el);
@@ -1922,24 +1993,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})`);
@@ -1963,7 +2121,7 @@ function attachGlass(el, opts = {}) {
     const pole = withPresence(resolveBody(opticsNow, sample, light ? 1 : 0), opticsNow).tintLuma;
     el.style.setProperty(
       "--vireglass-rim",
-      (opts.accessibility ?? a11y).increaseContrast ? contrastRimCss(pole, contrastRimLuma(pole)) : rimGradientCss(opticsNow, [tr, tg, tb], opts.light ?? REST_LIGHT, appear)
+      (opts.accessibility ?? a11y).increaseContrast ? contrastRimCss(pole, contrastRimLuma(pole), appear) : rimGradientCss(opticsNow, [tr, tg, tb], opts.light ?? REST_LIGHT, appear)
     );
     el.style.setProperty("--vireglass-rim-width", `${RIM_WIDTH_PX}px`);
     el.style.setProperty("--vireglass-radius", `${geometry.cornerRadius}px`);
@@ -1986,7 +2144,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,
@@ -1999,6 +2159,7 @@ function attachGlass(el, opts = {}) {
         wavePhase: sampleOut.wavePhase
       }
     });
+    invalidate();
     if (filterEl) {
       const feImage = filterEl.querySelector("feImage");
       feImage?.setAttribute("href", map.url);
@@ -2021,7 +2182,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;
@@ -2045,7 +2206,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);
@@ -2093,6 +2256,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);
@@ -2134,6 +2300,7 @@ function attachGlass(el, opts = {}) {
       if (next === appear) return;
       appear = next;
       apply();
+      if (interim) requestInterimMap();
     },
     setAccent(next) {
       accent = next ?? void 0;
@@ -2156,9 +2323,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();
@@ -2190,6 +2371,8 @@ exports.parseColor = parseColor;
 exports.probeBackdrop = probeBackdrop;
 exports.renderDisplacementPixels = renderDisplacementPixels;
 exports.renderSpectralPixels = renderSpectralPixels;
+exports.renderStats = renderStats;
+exports.resetRenderStats = resetRenderStats;
 exports.resetSupportCache = resetSupportCache;
 exports.resolveBody = resolveBody;
 exports.rimGradientCss = rimGradientCss;