distortion-wave 0.0.0-stage → 0.1.0

package/src/core.js

@@ -0,0 +1,169 @@
+// core.js — pure, DOM-free: config, scaling, timeline, particles (unit-tested in Node)
+// Part of distortion-wave · MIT © Lucas Bonomi
+
+// ═══ Math ════════════════════════════════════════════════════════════════════
+export const TAU = Math.PI * 2;
+export const clamp = (x, a = 0, b = 1) => Math.min(Math.max(x, a), b);
+export const lerp = (a, b, t) => a + (b - a) * t;
+export const fract = (x) => x - Math.floor(x);
+export const smooth = (e0, e1, x) => { const t = clamp((x - e0) / ((e1 - e0) || 1e-6)); return t * t * (3 - 2 * t); };
+export function cubicBezier(x1, y1, x2, y2) {
+  const b = (t, p1, p2) => { const u = 1 - t; return 3 * u * u * t * p1 + 3 * u * t * t * p2 + t * t * t; };
+  return (x) => {
+    if (x <= 0) return 0; if (x >= 1) return 1;
+    let lo = 0, hi = 1;
+    for (let i = 0; i < 22; i++) { const m = (lo + hi) / 2; if (b(m, x1, x2) < x) lo = m; else hi = m; }
+    return b((lo + hi) / 2, y1, y2);
+  };
+}
+const easeLaunch = cubicBezier(0.2, 1, 0.3, 1);
+const easeClear = cubicBezier(0.45, 0, 0.55, 1);
+export function hexToOklab(hex) {
+  const n = parseInt(hex.replace('#', ''), 16);
+  const [r, g, b] = [n >> 16 & 255, n >> 8 & 255, n & 255].map((v) => { v /= 255; return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; });
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  return [0.2104542553 * l + 0.7936177850 * m - 0.0040720468 * s, 1.9779984951 * l - 2.4285922050 * m + 0.4505937099 * s, 0.0259040371 * l + 0.7827717662 * m - 0.8086757660 * s];
+}
+
+// ═══ Config ══════════════════════════════════════════════════════════════════
+export const PALETTES = {
+  aurora: ['#FF4FD8', '#A35BFF', '#5B7CFF', '#38D9FF', '#FFD36B', '#FF7A5C'],
+  ocean: ['#3A7BFF', '#2EE6D6', '#7C5CFF', '#1FB6FF', '#B8F2FF'],
+  mint: ['#2BD67B', '#B6FF5C', '#1FC8A9', '#E8FFB0', '#3CE0C0'],
+  ember: ['#FF5A3C', '#FFB23C', '#FF3C8E', '#FFE07A', '#FF7F50'],
+};
+// Reference values for a ~360×740 px screen (k = 1). scaleConfig() adapts them to the target.
+export const BASE = {
+  type: 'vertical', speed: 1,
+  anticipation: 0.45, travel: 2.2, linger: -0.3, rimFade: 2.8, hairDelay: 0.45, hairFade: 2.8,
+  pull: 22, inhale: 50, gatherGlow: 0.35, gatherDots: 1,
+  amplitude: 32, lensWidth: 140, aberration: 0.75, swell: 20,
+  blur: 18, blurNear: 6, blurAhead: 90, blurBehind: 230,
+  lead: 120, tail: 280, band: 0.9,
+  rimWidth: 14, rimSoftness: 320, rimStrength: 0.85, uneven: 1, hairWidth: 1.5,
+  lean: 0.9, margin: 60, seam: 48,
+  particles: 64, particleSize: 1.8, particleLife: 2.1, reach: 140, spread: 1,
+  palette: 'aurora',
+};
+export const PRESETS = {
+  vertical: BASE,
+  horizontal: { ...BASE, type: 'horizontal' },
+  center: { ...BASE, type: 'center', anticipation: 0.25, travel: 3.2, linger: -0.2, rimFade: 2.4, hairDelay: 0.9,
+    pull: 14, inhale: 32, gatherGlow: 0.2, gatherDots: 0, amplitude: 20, lensWidth: 90, aberration: 0.35, swell: 13,
+    blur: 11, blurAhead: 54, blurBehind: 140, lead: 80, tail: 180, band: 0.75, rimStrength: 0.7, rimSoftness: 200,
+    particles: 90, particleLife: 3.0, reach: 90, spread: 0.65 },
+};
+const PX_KEYS = ['pull', 'inhale', 'amplitude', 'lensWidth', 'swell', 'blur', 'blurNear', 'blurAhead', 'blurBehind',
+  'lead', 'tail', 'rimWidth', 'rimSoftness', 'reach', 'margin', 'seam'];
+const T_KEYS = ['anticipation', 'travel', 'linger', 'rimFade', 'hairDelay', 'hairFade', 'particleLife'];
+
+/** Scales px & seconds to the target size: a button is not a screen. Pure. */
+export function scaleConfig(c, w, h) {
+  const k = clamp(Math.sqrt(w * h) / 516, 0.12, 1.8);                  // 516 ≈ √(360×740)
+  const ts = clamp(0.45 + 0.55 * Math.sqrt(k), 0.6, 1.15) / (c.speed || 1);
+  const o = { ...c, k };
+  for (const key of PX_KEYS) o[key] = c[key] * k;
+  for (const key of T_KEYS) o[key] = c[key] * ts;
+  o.blurNear = Math.max(o.blurNear, 1.2); o.blur = Math.max(o.blur, o.blurNear);
+  o.rimWidth = Math.max(o.rimWidth, 2.5); o.seam = Math.max(o.seam, 4);
+  o.anticipation = Math.max(o.anticipation, 0.2 / (c.speed || 1));
+  o.particles = Math.round(c.particles * clamp(k, 0.3, 1.5));
+  o.particleSize = c.particleSize * clamp(0.6 + 0.4 * k, 0.7, 1.3);
+  return o;
+}
+export const totalDuration = (c) => c.anticipation + Math.max(c.travel * 0.6, c.linger + c.rimFade, c.linger + c.hairDelay + c.hairFade, c.particleLife);
+
+// ═══ Pure timeline: (t, config, geometry) → frame state ══════════════════════
+function farthestCorner(ox, oy, tilt, squash, w, h) {
+  const c = Math.cos(tilt), s = Math.sin(tilt);
+  let best = 0;
+  for (const [x, y] of [[0, 0], [w, 0], [0, h], [w, h]]) {
+    const dx = x - ox, dy = y - oy;
+    best = Math.max(best, Math.hypot((c * dx + s * dy) * squash, -s * dx + c * dy));
+  }
+  return best;
+}
+/**
+ * @param g { w, h, src:{x,y,w,h}, touch:{x,y}|null, hold:boolean } — CSS px, canvas space.
+ *          The source may sit outside the target: the wave then enters from that edge.
+ */
+export function frameState(t, c, g) {
+  const ring = c.type === 'center', horiz = c.type === 'horizontal';
+  const T = totalDuration(c), time = clamp(t, 0, T);
+  const fly = time - c.anticipation, pre = smooth(0, c.anticipation, time);
+  const prog = clamp(fly / c.travel), e = easeLaunch(prog);
+  const s = g.src, cx = s.x + s.w / 2, cy = s.y + s.h / 2;
+  const r0 = Math.max(Math.min(s.w, s.h) / 2, 1);
+  const half = (horiz ? s.h : s.w) / 2, perp = (horiz ? s.w : s.h) / 2;
+  const base = horiz ? Math.PI / 2 : 0, ax = Math.cos(base), ay = Math.sin(base);
+  // "forward" = the side where most of the target lies (the wave travels inward)
+  const dir = (g.w / 2 - cx) * Math.sin(base) + (g.h / 2 - cy) * -Math.cos(base) >= 0 ? 1 : -1;
+  let lean = 0;
+  if (!ring && g.touch) lean = clamp(((g.touch.x - cx) * ax + (g.touch.y - cy) * ay) / Math.max(half, 1), -1, 1) * c.lean;
+  const settle = smooth(0, 0.45, e);
+  const ox = cx + ax * lean * half * settle, oy = cy + ay * lean * half * settle;
+  const tilt = base + dir * lean * 0.45 * settle;
+  const squashMax = ring ? 1 : 1.4;
+  const reach = farthestCorner(ox, oy, tilt, squashMax, g.w, g.h) + c.swell * squashMax + c.margin;
+  const radius = fly < 0 ? r0 + c.inhale * (1 - pre) : r0 + (reach + c.margin * 1.6 - r0) * e;
+  const fade = 1 - smooth(0.2, 0.55, prog);
+  const lift = c.gatherGlow * 0.5;
+  const energy = smooth(0, 0.05, prog) * fade;
+  const covered = fly > 0 && radius - c.swell > reach;
+  return {
+    time, fly, pre, prog, moved: e, ring, dir, r0, half, perp, cx, cy,
+    ox, oy, tilt, squash: lerp(1, squashMax, smooth(0, 0.5, e)),
+    spine: ring ? 0 : Math.max(0, half - r0) * (1 - settle),
+    lx: Math.cos(tilt), ly: Math.sin(tilt), fx: dir * Math.sin(tilt), fy: -dir * Math.cos(tilt),
+    radius, swell: c.swell * smooth(0, 0.3, e), energy,
+    pull: c.pull * pre * (1 - smooth(0, 0.22, fly)),
+    glow: fly < 0 ? lift * pre : lerp(lift, 1, smooth(0, 0.07, prog)) * fade,
+    clear: lerp(r0 - c.rimSoftness, reach + c.rimSoftness, easeClear((fly - c.linger) / c.rimFade)),
+    hairClear: lerp(r0 - c.rimSoftness, reach + c.rimSoftness, easeClear((fly - c.linger - c.hairDelay) / c.hairFade)),
+    rim: c.rimStrength * smooth(0, 0.1, prog) * (1 - smooth(0.9, 1, time / T)),
+    hold: ring && g.hold ? r0 : 0,
+    launched: fly > 0, covered,
+    settled: covered && prog >= 0.55,                                   // no more lens or blur → the live DOM can take over
+  };
+}
+
+// ═══ Deterministic particles ═════════════════════════════════════════════════
+export function makeParticles(n, c) {
+  return Array.from({ length: n }, (_, i) => {
+    const h = (k) => fract((i + 1) * k);
+    return {
+      col: h(0.6180339887) * 2 - 1, gy: h(0.7071067812), head: h(0.1618033989) * TAU,
+      pace: 0.4 + 0.65 * Math.sqrt(h(0.7548776662)), drift: 12 + 45 * h(0.5698402910),
+      sway: 3 + 10 * h(0.4142135624), swayHz: 2 + 3 * h(0.7320508076), tw: 7 + 10 * h(0.2360679775),
+      ph: h(0.3819660113) * TAU, hop: h(0.5497004779), life: c.particleLife * (0.45 + 0.55 * h(0.6457513111)),
+      size: c.particleSize * (0.55 + 0.45 * h(0.8774) ** 2), bright: 0.35 + 0.65 * h(0.6055512755),
+    };
+  });
+}
+export function particleAt(P, s, c) {
+  const tw = 0.75 + 0.25 * Math.sin(s.time * P.tw + P.ph), k = c.k;
+  if (!s.launched) {
+    if (!c.gatherDots) return null;
+    const cyc = s.time / 0.32 + P.hop, f = fract(cyc);
+    const a = smooth(0, 0.3, f) * (1 - smooth(0.6, 1, f)) * P.bright * tw
+      * smooth(0, c.anticipation * 0.35, s.time) * (1 - smooth(c.anticipation * 0.75, c.anticipation, s.time));
+    const fall = c.reach * (1 - f * f);
+    if (s.ring) { const ang = P.head + Math.floor(cyc) * 2.399963; const rr = s.r0 + 12 * k + fall; return { x: s.cx + Math.cos(ang) * rr, y: s.cy + Math.sin(ang) * rr, a }; }
+    const lat = P.col * (s.half + 16 * k) * (1 - 0.35 * (1 - f)), fwd = s.perp + 10 * k + fall * (0.45 + 0.55 * P.gy);
+    return { x: s.cx + s.lx * lat + s.fx * fwd, y: s.cy + s.ly * lat + s.fy * fwd, a };
+  }
+  const fly = s.fly;
+  const a = (1 - smooth(P.life * 0.55, P.life, fly)) * P.bright * tw * smooth(0, 0.08, fly);
+  const sway = P.sway * Math.max(k, 0.3) * Math.sin(P.swayHz * fly + P.ph) * Math.min(fly / 0.25, 1);
+  const travel = (s.radius - s.r0) * P.pace * c.spread;
+  if (s.ring) {
+    const rr = s.r0 + travel + P.drift * k * fly, co = Math.cos(P.head), si = Math.sin(P.head);
+    return { x: s.ox + co * rr - si * sway, y: s.oy + si * rr + co * sway, a };
+  }
+  const lat = P.col * s.half * (1 + 0.25 * s.moved * P.pace) + sway;
+  const fwd = (s.r0 + travel) * (1 - 0.3 * P.col * P.col) + P.drift * k * fly;
+  return { x: s.ox + s.lx * lat + s.fx * fwd, y: s.oy + s.ly * lat + s.fy * fwd, a };
+}
+

package/src/focus.js

@@ -0,0 +1,34 @@
+// focus.js — keep keyboard focus on the equivalent control when an update replaces it
+// Part of distortion-wave · MIT © Lucas Bonomi
+
+// Keyboard focus
+// The wave never touches focus (the target only goes opacity:0, so it stays focusable and
+// in the accessibility tree). But if update() REPLACES the focused node (innerHTML, re-render),
+// the browser drops focus to <body>. We then move it to the equivalent control:
+// same id → same data-focus-key/name → same place in the tree → same rank among
+// focusable elements → the target itself.
+const FOCUSABLE = 'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),summary,[contenteditable="true"],[tabindex]:not([tabindex="-1"])';
+export function captureFocus(root) {
+  const el = document.activeElement;
+  if (!el || el === document.body || !root.contains(el)) return null;
+  const path = [];
+  for (let n = el; n && n !== root; n = n.parentElement) path.unshift([...n.parentElement.children].indexOf(n));
+  const sel = 'selectionStart' in el ? (() => { try { return [el.selectionStart, el.selectionEnd]; } catch { return null; } })() : null;
+  return { el, id: el.id, key: el.getAttribute('data-focus-key') || el.getAttribute('name'), tag: el.localName, path,
+    order: [...root.querySelectorAll(FOCUSABLE)].indexOf(el), sel };
+}
+export function restoreFocus(info, root) {
+  if (!info || info.el.isConnected) return;                              // node kept: focus never moved
+  const now = document.activeElement;
+  if (now && now !== document.body && now !== document.documentElement) return;   // the app moved focus itself: leave it
+  let c = null;
+  if (info.id) c = root.querySelector('#' + CSS.escape(info.id));
+  if (!c && info.key) c = root.querySelector(`[data-focus-key="${CSS.escape(info.key)}"],[name="${CSS.escape(info.key)}"]`);
+  if (!c) { let n = root; for (const i of info.path) n = n?.children[i]; if (n && n !== root && n.localName === info.tag && n.matches(FOCUSABLE)) c = n; }
+  if (!c && info.order >= 0) { const f = root.querySelectorAll(FOCUSABLE); c = f[Math.min(info.order, f.length - 1)] || null; }
+  if (!c && root.matches(FOCUSABLE)) c = root;
+  if (!c) return;
+  c.focus({ preventScroll: true });
+  if (info.sel && typeof c.setSelectionRange === 'function') try { c.setSelectionRange(info.sel[0], info.sel[1]); } catch {}
+}
+

package/src/index.js

@@ -0,0 +1,281 @@
+// distortion-wave — a distortion-wave transition for ANY DOM element (button, card, section, page).
+// WebGL2, zero dependencies. MIT © Lucas Bonomi
+//
+//   const t = distortionWave(target, () => { /* mutate the DOM */ }, {
+//     source: buttonEl | DOMRect | {x,y} | null,   // where the wave starts
+//     focus:  pointerEvent | {x,y} | null,         // touch point (sets the lean)
+//     variant: 'auto' | 'vertical' | 'horizontal' | 'center',
+//     palette: 'aurora' | ['#hex', …],
+//   });
+//   await t.ready; await t.updateCallbackDone; await t.covered; await t.finished; t.skip();
+//
+// Same model as document.startViewTransition(): capture "before", update the DOM,
+// capture "after", animate on top, then hand back to the real DOM (interactive as
+// soon as the wave has passed).
+
+import { snapshotElement } from './capture.js';
+import { BASE, PRESETS, PALETTES, scaleConfig, totalDuration, frameState, makeParticles, particleAt, clamp, lerp } from './core.js';
+import { acquire, release, warmupWave } from './renderer.js';
+import { captureFocus, restoreFocus } from './focus.js';
+
+// ═══ Measuring & DOM helpers ═════════════════════════════════════════════════
+function parseRadii(cs, w, h) {
+  const one = (v, side) => { const t = String(v).trim().split(/\s+/)[0]; const n = parseFloat(t) || 0; return t.endsWith('%') ? n / 100 * side : n; };
+  let tl = one(cs.borderTopLeftRadius, w), tr = one(cs.borderTopRightRadius, w), br = one(cs.borderBottomRightRadius, w), bl = one(cs.borderBottomLeftRadius, w);
+  const f = Math.min(1, w / ((tl + tr) || 1e9), w / ((bl + br) || 1e9), h / ((tl + bl) || 1e9), h / ((tr + br) || 1e9));   // CSS overlapping-radii rule
+  return { tl: tl * f, tr: tr * f, br: br * f, bl: bl * f };
+}
+function isFixed(el) { for (let n = el; n && n !== document.documentElement; n = n.parentElement) if (getComputedStyle(n).position === 'fixed') return true; return false; }
+function measure(el) {
+  const rect = el.getBoundingClientRect(), cs = getComputedStyle(el);
+  const w = el.offsetWidth ?? rect.width, h = el.offsetHeight ?? rect.height;
+  const x0 = Math.max(rect.left, 0), y0 = Math.max(rect.top, 0), x1 = Math.min(rect.right, innerWidth), y1 = Math.min(rect.bottom, innerHeight);
+  const fixed = isFixed(el), sx = fixed ? 0 : scrollX, sy = fixed ? 0 : scrollY;
+  return {
+    w, h, fixed, opacity: cs.opacity, radii: parseRadii(cs, w, h), visible: x1 > x0 && y1 > y0,
+    clip: { x: x0 - rect.left, y: y0 - rect.top, w: x1 - x0, h: y1 - y0 },          // visible part, element space
+    page: { x: x0 + sx, y: y0 + sy, w: x1 - x0, h: y1 - y0 },                   // same, page space (scroll-stable)
+    el: { x: rect.left + sx, y: rect.top + sy, w: rect.width, h: rect.height },
+  };
+}
+const union = (a, b) => { const x = Math.min(a.x, b.x), y = Math.min(a.y, b.y); return { x, y, w: Math.max(a.x + a.w, b.x + b.w) - x, h: Math.max(a.y + a.h, b.y + b.h) - y }; };
+const rel = (r, o) => ({ x: r.x - o.x, y: r.y - o.y, w: r.w, h: r.h });
+const nextFrame = () => new Promise((r) => requestAnimationFrame(() => r()));
+function deferred() { let res, rej; const p = new Promise((a, b) => { res = a; rej = b; }); p.catch(() => {}); return { p, res, rej }; }
+function pickDpr(m, maxTex) {
+  const area = Math.max(m.clip.w * m.clip.h, 1);
+  return Math.max(0.5, Math.min(window.devicePixelRatio || 1, 2, Math.sqrt(4.2e6 / area), maxTex / Math.max(m.clip.w, m.clip.h, 1)));
+}
+
+// Optional pre-capture (on trigger hover/focus): hides the latency of the "before" capture.
+const prepared = new WeakMap();
+export function prepareWave(target) {
+  if (prepared.get(target)?.pending) return prepared.get(target).pending;
+  const m = measure(target);
+  if (!m.visible) return Promise.resolve(null);
+  const entry = { dirty: false, m, dpr: pickDpr(m, 8192), at: performance.now() };
+  entry.mo = new MutationObserver(() => { entry.dirty = true; });
+  entry.mo.observe(target, { subtree: true, childList: true, attributes: true, characterData: true });
+  entry.pending = snapshotElement(target, { dpr: entry.dpr, clip: m.clip }).then((s) => (entry.shot = s), () => null);
+  prepared.set(target, entry);
+  return entry.pending;
+}
+function takePrepared(target, m) {
+  const e = prepared.get(target);
+  if (!e) return null;
+  prepared.delete(target); e.mo.disconnect();
+  const same = (a, b) => Math.abs(a.x - b.x) < 0.5 && Math.abs(a.y - b.y) < 0.5 && Math.abs(a.w - b.w) < 0.5 && Math.abs(a.h - b.h) < 0.5;
+  if (e.dirty || !e.shot || performance.now() - e.at > 8000 || !same(e.m.page, m.page)) return null;
+  return e.shot;
+}
+
+// ═══ Orchestration ═══════════════════════════════════════════════════════════
+const ACTIVE = new WeakMap();
+const DEFAULTS = { variant: 'auto', palette: 'aurora', speed: 1, particles: true, reducedMotion: null, timeout: 3000, preserveFocus: true };
+
+class WaveTransition {
+  constructor(target, update, opts) {
+    this.target = target; this.update = update || (() => {}); this.o = { ...DEFAULTS, ...opts };
+    this._d = { ready: deferred(), update: deferred(), covered: deferred(), finished: deferred() };
+    this.ready = this._d.ready.p; this.updateCallbackDone = this._d.update.p; this.covered = this._d.covered.p; this.finished = this._d.finished.p;
+    this.metrics = {};
+    this._updated = false; this._skipped = false; this._done = false;
+    this._run().catch((err) => this._abort(err));
+  }
+  skip() { this._skipped = true; if (this._loopStarted) this._finish(); }
+
+  async _runUpdate() {
+    if (this._updated) return this._updatePromise;
+    this._updated = true;
+    const focus = this.o.preserveFocus === false ? null : captureFocus(this.target);
+    this._updatePromise = (async () => { await this.update(); restoreFocus(focus, this.target); })();
+    this._updatePromise.then(() => this._d.update.res(), (e) => this._d.update.rej(e));
+    return this._updatePromise;
+  }
+  async _run() {
+    const prev = ACTIVE.get(this.target);
+    ACTIVE.set(this.target, this);
+    if (prev) { prev.skip(); await prev.finished; }
+    const o = this.o, target = this.target;
+    const reduced = o.reducedMotion ?? matchMedia('(prefers-reduced-motion: reduce)').matches;
+    const before = measure(target);
+    const r = before.visible && target !== document.body && target !== document.documentElement ? acquire() : null;
+    this.r = r;
+    if (!r || this._skipped) return this._plain();
+
+    // 1 · "before" capture (or a still-valid pre-capture)
+    const dpr = pickDpr(before, r.maxTex);
+    let t0 = performance.now();
+    const oldShot = takePrepared(target, before) || await snapshotElement(target, { dpr: Math.min(dpr, 2), clip: before.clip });
+    this.metrics.captureBefore = Math.round(performance.now() - t0);
+    if (this._skipped) return this._plain();
+
+    // 2 · config scaled to the target + initial geometry
+    const base = { ...(PRESETS[this._variant(before)] || BASE) };
+    for (const k of Object.keys(o)) if (k in BASE && k !== 'type' && k !== 'particles') base[k] = o[k];
+    if (o.particles === false) base.particles = 0; else if (typeof o.particles === 'number') base.particles = o.particles;
+    const cfg = scaleConfig(base, before.clip.w, before.clip.h);
+    this.cfg = cfg; this.before = before; this.dpr = oldShot.dpr;
+    this.particles = makeParticles(cfg.particles, cfg); this.dots = new Float32Array(Math.max(this.particles.length, 1) * 4);
+    this.origin = this._originPage(before);                               // source/touch in page coordinates
+    this.canvasPage = before.page;
+    this.rects = { old: rel(before.page, before.page), new: null, shape: rel(before.el, before.page), radii: before.radii };
+    t0 = performance.now();
+    r.setLayer('old', oldShot.canvas, cfg.blurNear * this.dpr, cfg.blur * this.dpr);
+    this.metrics.upload = Math.round(performance.now() - t0);
+    this._mount(); this._hide();
+    this.mode = reduced ? 0 : 1; this.fadeOnly = reduced;
+    this._d.ready.res();
+    this._startLoop();
+
+    // 3 · DOM update during the anticipation, then "after" capture
+    await this._runUpdate();
+    await nextFrame();
+    await Promise.all([...target.querySelectorAll('img')].map((i) => i.decode?.().catch(() => {})));
+    if (this._done) return;
+    const after = measure(target);
+    t0 = performance.now();
+    const newShot = after.visible
+      ? await snapshotElement(target, { dpr: this.dpr, clip: after.clip, rootOpacity: before.opacity })
+      : null;
+    this.metrics.captureAfter = Math.round(performance.now() - t0);
+    if (this._done) return;
+    if (!newShot) { this._finish(); return; }
+    r.setLayer('new', newShot.canvas, cfg.blurNear * this.dpr, cfg.blur * this.dpr);
+    // 4 · open the gate: the canvas covers the union of before/after
+    this.after = after;
+    this.canvasPage = union(before.page, after.page);
+    this.rects = { old: rel(before.page, this.canvasPage), new: rel(after.page, this.canvasPage), shape: rel(before.el, this.canvasPage), radii: before.radii };
+    this.shapes = { from: rel(before.el, this.canvasPage), to: rel(after.el, this.canvasPage), r0: before.radii, r1: after.radii };
+    this._resizeCanvas();
+    this.gateOpen = true;
+    if (this.fadeOnly) { this.mode = 3; this.fadeStart = this.now; }
+  }
+  _variant(m) {
+    if (this.o.variant !== 'auto') return this.o.variant;
+    const s = this.o.source;
+    if (!(s instanceof Element) || s === this.target) return 'center';
+    const r = s.getBoundingClientRect();
+    return r.width >= r.height * 1.4 ? 'vertical' : r.height >= r.width * 1.4 ? 'horizontal' : 'center';
+  }
+  _originPage(m) {
+    const sx = m.fixed ? 0 : scrollX, sy = m.fixed ? 0 : scrollY, o = this.o;
+    const pt = (v) => (v && 'clientX' in v ? { x: v.clientX, y: v.clientY } : v && 'x' in v ? { x: v.x, y: v.y } : null);
+    let touch = pt(o.focus);
+    if (o.focus instanceof KeyboardEvent || (o.focus && o.focus.detail === 0 && o.focus.type === 'click')) touch = null;   // keyboard: no touch point, no lean
+    let src;
+    if (o.source instanceof Element && o.source !== this.target) { const r = o.source.getBoundingClientRect(); src = { x: r.left, y: r.top, w: r.width, h: r.height }; }
+    else if (o.source && 'width' in o.source) src = { x: o.source.x, y: o.source.y, w: o.source.width, h: o.source.height };
+    else {
+      const p = (!(o.source instanceof Element) && pt(o.source)) || touch || { x: m.el.x - sx + m.w / 2, y: m.el.y - sy + m.h / 2 };
+      const d = Math.max(8, Math.min(m.w, m.h) * 0.08);
+      src = { x: p.x - d, y: p.y - d, w: 2 * d, h: 2 * d };
+    }
+    return { src: { x: src.x + sx, y: src.y + sy, w: src.w, h: src.h }, touch: touch && { x: touch.x + sx, y: touch.y + sy },
+      hold: o.source instanceof Element && o.source !== this.target && this.target.contains(o.source) };
+  }
+  _mount() {
+    const c = this.r.canvas;
+    document.body.appendChild(c);
+    this._resizeCanvas();
+  }
+  _resizeCanvas() {
+    const c = this.r.canvas, p = this.canvasPage;
+    c.width = Math.max(1, Math.round(p.w * this.dpr)); c.height = Math.max(1, Math.round(p.h * this.dpr));
+    c.style.width = p.w + 'px'; c.style.height = p.h + 'px';
+    this._place();
+  }
+  _place() {
+    const p = this.canvasPage, f = this.before.fixed;
+    this.r.canvas.style.transform = `translate3d(${p.x - (f ? 0 : scrollX)}px,${p.y - (f ? 0 : scrollY)}px,0)`;
+  }
+  _hide() {
+    const s = this.target.style;
+    this._saved = ['opacity', 'transition'].map((k) => [k, s.getPropertyValue(k), s.getPropertyPriority(k)]);
+    s.setProperty('transition', 'none', 'important'); s.setProperty('opacity', '0', 'important');
+  }
+  _show() {
+    if (!this._saved) return;
+    for (const [k, v, pr] of this._saved) { if (v) this.target.style.setProperty(k, v, pr); else this.target.style.removeProperty(k); }
+    this._saved = null;
+  }
+  _startLoop() {
+    this._loopStarted = true; this.held = 0; this.start = performance.now(); this.now = this.start; this.last = this.start;
+    const tick = (now) => {
+      if (this._done) return;
+      const dt = Math.min(now - this.last, 100); this.last = now; this.now = now;
+      this.metrics.worstFrame = Math.max(this.metrics.worstFrame || 0, dt);
+      this._place();
+      let t = (now - this.start - this.held) / 1000;
+      const gateAt = this.cfg.anticipation - 1e-3;
+      if (!this.gateOpen && t >= gateAt) {                                 // "after" capture not ready: hold the anticipation
+        this.held += t * 1000 - gateAt * 1000; t = gateAt;
+        if (now - this.start > this.o.timeout) { this._finish(); return; }
+      }
+      this.t = t;
+      if (this.mode === 3) {                                               // reduced motion: plain crossfade
+        const k = clamp((now - this.fadeStart) / 220);
+        this.r.render({ mode: 3, fade: k, w: this.canvasPage.w, h: this.canvasPage.h, rects: this.rects, dpr: this.dpr, dotCount: 0 });
+        if (k >= 1) { this._finish(); return; }
+      } else if (this.mode === 0) {
+        this.r.render({ mode: 0, w: this.canvasPage.w, h: this.canvasPage.h, rects: this.rects, dpr: this.dpr, dotCount: 0 });
+      } else {
+        const g = { w: this.canvasPage.w, h: this.canvasPage.h, src: rel(this.origin.src, this.canvasPage),
+          touch: this.origin.touch && rel({ ...this.origin.touch, w: 0, h: 0 }, this.canvasPage), hold: this.origin.hold };
+        const s = frameState(t, this.cfg, g);
+        if (this.shapes) {                                                 // the silhouette follows the wave when the size changes
+          const k = s.moved, A = this.shapes.from, B = this.shapes.to, ra = this.shapes.r0, rb = this.shapes.r1;
+          this.rects.shape = { x: lerp(A.x, B.x, k), y: lerp(A.y, B.y, k), w: lerp(A.w, B.w, k), h: lerp(A.h, B.h, k) };
+          this.rects.radii = { tl: lerp(ra.tl, rb.tl, k), tr: lerp(ra.tr, rb.tr, k), br: lerp(ra.br, rb.br, k), bl: lerp(ra.bl, rb.bl, k) };
+        }
+        if (s.launched && !this._launched) { this._launched = true; this.o.onLaunch?.(); }
+        if (s.covered && !this._covered) { this._covered = true; this._d.covered.res(); this.o.onCovered?.(); }
+        if (s.settled && this.mode === 1) { this.mode = 4; this._show(); this.o.onSettled?.(); }   // the real DOM takes over
+        let n = 0;
+        for (const P of this.particles) {
+          const q = particleAt(P, s, this.cfg);
+          if (!q || q.a <= 0.002) continue;
+          this.dots[n * 4] = q.x; this.dots[n * 4 + 1] = q.y; this.dots[n * 4 + 2] = P.size; this.dots[n * 4 + 3] = Math.min(q.a, 1); n++;
+        }
+        this.r.render({ mode: this.mode, s, cfg: this.cfg, w: this.canvasPage.w, h: this.canvasPage.h, rects: this.rects, dpr: this.dpr, dots: this.dots, dotCount: n });
+        if (t >= totalDuration(this.cfg)) { this._finish(); return; }
+      }
+      if (this._skipped) { this._finish(); return; }
+      requestAnimationFrame(tick);
+    };
+    requestAnimationFrame(tick);
+  }
+  async _plain() {                                                         // no WebGL / offscreen / skipped: just run the update
+    try { await this._runUpdate(); } finally { this._done = true; this._release(); this._d.ready.res(); this._d.covered.res(); this._d.finished.res(); }
+  }
+  async _finish() {
+    if (this._done) return;
+    this._done = true;
+    try { await this._runUpdate(); } catch {}                             // returns the in-flight promise if already started
+    this._show(); this._release();
+    if (!this._covered) this._d.covered.res();
+    this._d.finished.res();
+    this.o.onEnd?.(this.metrics);
+  }
+  _release() { if (this.r) { release(this.r); this.r = null; } if (ACTIVE.get(this.target) === this) ACTIVE.delete(this.target); }
+  _abort(err) {
+    console.warn('[distortion-wave] repli sans animation :', err);
+    this._done = true; this._show(); this._release();
+    (this._updated ? Promise.resolve() : this._runUpdate()).catch(() => {}).finally(() => {
+      this._d.ready.res(); this._d.covered.res(); this._d.finished.res();
+    });
+  }
+}
+
+/** Entry point. Always runs `update` (even without WebGL, offscreen or with reduced motion). */
+export function distortionWave(target, update, options = {}) {
+  return new WaveTransition(target, update, options);
+}
+/** Helper: plays a wave on `target` when `trigger` is clicked (source = trigger, focus = pointer). */
+export function waveOnClick(trigger, target, update, options = {}) {
+  const prep = () => prepareWave(target);
+  trigger.addEventListener('pointerenter', prep);
+  trigger.addEventListener('focus', prep);
+  trigger.addEventListener('click', (e) => distortionWave(target, () => update(e), { source: trigger, focus: e, ...options }));
+}
+export { snapshotElement, warmupWave, PALETTES, PRESETS, scaleConfig, totalDuration, frameState };