@pariharshyamu/morph 2.0.0

package/README.md

@@ -0,0 +1,147 @@
+# @pariharshyamu/morph
+
+> Interrupt-safe DOM morphing with spring physics, FLIP animations, and auto-animate.
+
+**morph.js v2** patches your DOM like `morphdom`, but adds silky smooth animations — spring physics, FLIP transitions, choreographed enter/exit/move, and mid-animation interruption handling.
+
+## Features
+
+- ✦ **Interrupted animation handling** — morphs from current visual position, never snaps
+- ✦ **Scroll-aware FLIP** — corrects `getBoundingClientRect` across scrolled containers
+- ✦ **Stacking-context correction** — handles CSS transform ancestors
+- ✦ **Hungarian algorithm matching** — optimal global assignment, not greedy
+- ✦ **Spring physics engine** — position/velocity integrator, replaces cubic-bezier
+- ✦ **Simultaneous move + content morph** — FLIP + crossfade in one animation track
+- ✦ **Choreography model** — sequence exits, moves, enters independently
+- ✦ **MorphObserver** — auto-animate any DOM mutations on a container
+- ✦ **htmx extension** — hooks into htmx:beforeSwap / htmx:afterSwap
+- ✦ **Confidence-gated matching** — low-confidence pairs become enter/exit instead
+
+## Install
+
+```bash
+npm install @pariharshyamu/morph
+```
+
+Or use a CDN:
+
+```html
+<script type="module">
+  import morph from 'https://unpkg.com/@pariharshyamu/morph';
+</script>
+```
+
+## Quick Start
+
+```js
+import morph from '@pariharshyamu/morph';
+
+// Morph an element to new HTML
+const result = morph(element, '<div class="card">New content</div>');
+
+// Wait for all animations to complete
+await result.finished;
+```
+
+## API
+
+### `morph(fromEl, toElOrHTML, options?)`
+
+Patches `fromEl` to match `toElOrHTML` (a DOM element or HTML string), animating the transition.
+
+**Returns:** `{ animations, finished, debug, cancel() }`
+
+### Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `duration` | `400` | Base duration in ms |
+| `easing` | `'spring'` | `'spring'` or any CSS easing string |
+| `spring` | `{ stiffness: 280, damping: 24, mass: 1 }` | Spring physics parameters |
+| `stagger` | `25` | Stagger delay between elements (ms) |
+| `keyAttribute` | `'data-morph-key'` | Attribute for explicit element matching |
+| `matchConfidenceThreshold` | `1.5` | Below this → treat as enter/exit |
+| `respectReducedMotion` | `true` | Skip animation if user prefers reduced motion |
+| `morphContent` | `true` | Cross-fade content changes during move |
+| `debug` | `false` | Log matching info to console |
+
+### `morph.text(el, newText, options?)`
+
+Cross-fade text content change with a fade-out → swap → fade-in sequence.
+
+```js
+await morph.text(heading, 'New Title').finished;
+```
+
+### `morph.prepare(fromEl, toEl, options?)`
+
+Create a controllable transition that can be triggered later.
+
+```js
+const transition = morph.prepare(el, newEl, { duration: 500 });
+transition.play(); // triggers when ready
+```
+
+### `MorphObserver`
+
+Auto-animate any DOM mutations on a container:
+
+```js
+import { MorphObserver } from '@pariharshyamu/morph';
+
+const observer = new MorphObserver(container, { duration: 350 });
+observer.observe();
+
+// Now any mutation to container's children will auto-animate
+container.innerHTML = '<div>New content</div>'; // animated!
+
+observer.disconnect();
+```
+
+### htmx Extension
+
+```html
+<script src="https://unpkg.com/htmx.org"></script>
+<script type="module">
+  import morph from '@pariharshyamu/morph';
+  morph.htmx({ duration: 350 });
+</script>
+
+<div hx-ext="morph" hx-get="/api/items" hx-swap="innerHTML">
+  <!-- content swaps are now animated -->
+</div>
+```
+
+### Choreography
+
+Control the timing of exit, move, and enter phases:
+
+```js
+morph(el, newHTML, {
+  choreography: {
+    exit:  { at: 0,    duration: 0.5  },  // fractions of total duration
+    move:  { at: 0.15, duration: 0.85 },
+    enter: { at: 0.4,  duration: 0.6  },
+  }
+});
+```
+
+### Custom Hooks
+
+```js
+morph(el, newHTML, {
+  onEnter: (el) => [
+    { opacity: 0, transform: 'translateX(-20px)' },
+    { opacity: 1, transform: 'translateX(0)' },
+  ],
+  onLeave: (el) => [
+    { opacity: 1 },
+    { opacity: 0, transform: 'scale(0.8)' },
+  ],
+  onMove: (el, fromRect, toRect) => null, // return keyframes or null
+});
+```
+
+## License
+
+MIT

package/morph.js

@@ -0,0 +1,1133 @@
+/**
+ * morph.js v2
+ *
+ * What's new vs v1:
+ *   ✦ Interrupted animation handling — morphs from current visual position, never snaps
+ *   ✦ Scroll-aware FLIP — corrects getBoundingClientRect across scrolled containers
+ *   ✦ Stacking-context correction — handles CSS transform ancestors
+ *   ✦ Hungarian algorithm matching — optimal global assignment, not greedy
+ *   ✦ Spring physics engine — position/velocity integrator, replaces cubic-bezier
+ *   ✦ Simultaneous move + content morph — FLIP + crossfade in one animation track
+ *   ✦ Choreography model — sequence exits, moves, enters independently
+ *   ✦ MorphObserver — auto-animate any DOM mutations on a container
+ *   ✦ htmx extension — hooks into htmx:beforeSwap / htmx:afterSwap
+ *   ✦ Confidence-gated matching — low-confidence pairs become enter/exit instead
+ */
+
+// ═══════════════════════════════════════════════════════════════
+// § 1 — Constants & Defaults
+// ═══════════════════════════════════════════════════════════════
+
+const VERSION = '2.0.0';
+
+const DEFAULTS = {
+    // Timing
+    duration: 400,
+    easing: 'spring',          // 'spring' | any CSS easing string
+    spring: { stiffness: 280, damping: 24, mass: 1 },
+    stagger: 25,
+
+    // Matching
+    keyAttribute: 'data-morph-key',
+    matchConfidenceThreshold: 1.5, // below this → treat as enter/exit
+
+    // Hooks
+    onEnter: null,   // (el) => keyframes[]
+    onLeave: null,   // (el) => keyframes[]
+    onMove: null,   // (el, fromRect, toRect) => keyframes[] | null
+
+    // Choreography
+    choreography: {
+        exit: { at: 0, duration: 0.5 },  // fractions of total duration
+        move: { at: 0.15, duration: 0.85 },
+        enter: { at: 0.4, duration: 0.6 },
+    },
+
+    // Behaviour
+    respectReducedMotion: true,
+    morphContent: true, // cross-fade content changes during move
+
+    // Debug
+    debug: false,
+};
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 2 — Spring Physics Engine
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Runs a spring simulation and returns an array of {t, value} samples
+ * that approximate the spring curve as a custom easing.
+ */
+function solveSpring(stiffness, damping, mass, precision = 0.001) {
+    // Analytical solution for under-damped spring
+    const w0 = Math.sqrt(stiffness / mass);       // natural frequency
+    const zeta = damping / (2 * Math.sqrt(stiffness * mass)); // damping ratio
+
+    if (zeta >= 1) {
+        // Over/critically damped — simple ease-out fallback with correct {t, value} shape
+        return {
+            samples: [
+                { t: 0, value: 0 },
+                { t: 0.4, value: 0.72 },
+                { t: 0.7, value: 0.92 },
+                { t: 1, value: 1 },
+            ],
+            settleTime: 1,
+        };
+    }
+
+    const wd = w0 * Math.sqrt(1 - zeta * zeta);  // damped frequency
+
+    // Returns displacement [0→1] at time t (seconds)
+    const displacement = (t) =>
+        1 - Math.exp(-zeta * w0 * t) * (Math.cos(wd * t) + (zeta * w0 / wd) * Math.sin(wd * t));
+
+    // Find settling time (where |1 - displacement| < precision)
+    let settleTime = 0.1;
+    while (settleTime < 10) {
+        if (Math.abs(1 - displacement(settleTime)) < precision &&
+            Math.abs(1 - displacement(settleTime + 0.016)) < precision) break;
+        settleTime += 0.016;
+    }
+
+    // Sample the curve into keyframes for WAAPI
+    const samples = [];
+    const steps = 60;
+    for (let i = 0; i <= steps; i++) {
+        const t = i / steps;
+        const value = displacement(t * settleTime);
+        samples.push({ t, value: Math.max(0, Math.min(2, value)) }); // clamp overshoot
+    }
+
+    return { samples, settleTime };
+}
+
+/**
+ * Generate WAAPI keyframes for a spring-animated FLIP move.
+ * Instead of a 2-keyframe from/to, we emit N keyframes tracing the spring curve.
+ */
+function springFLIPKeyframes(dx, dy, scaleX, scaleY, springOpts) {
+    const { stiffness, damping, mass } = springOpts;
+    const { samples } = solveSpring(stiffness, damping, mass);
+
+    return samples.map(({ t, value }) => {
+        // value goes 0→1, so at start we're at full offset, at end we're at 0
+        const progress = value;
+        const curDx = dx * (1 - progress);
+        const curDy = dy * (1 - progress);
+        const curScaleX = scaleX + (1 - scaleX) * progress;
+        const curScaleY = scaleY + (1 - scaleY) * progress;
+
+        return {
+            offset: t,
+            transform: `translate(${curDx}px, ${curDy}px) scale(${curScaleX}, ${curScaleY})`,
+            transformOrigin: 'top left',
+            easing: 'linear',
+        };
+    });
+}
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 3 — Coordinate System & Scroll Correction
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Get the "offset root" — the nearest positioned/transformed ancestor
+ * that will be the coordinate origin for our FLIP transform.
+ */
+function getOffsetRoot(el) {
+    let parent = el.parentElement;
+    while (parent && parent !== document.body) {
+        const style = getComputedStyle(parent);
+        const pos = style.position;
+        const transform = style.transform;
+        const willChange = style.willChange;
+
+        if (pos !== 'static' ||
+            (transform && transform !== 'none') ||
+            (willChange && willChange !== 'auto')) {
+            return parent;
+        }
+        parent = parent.parentElement;
+    }
+    return document.documentElement;
+}
+
+/**
+ * Get the rect of an element corrected for:
+ *   1. The scroll position of all ancestor scroll containers
+ *   2. Any CSS transforms on ancestor elements
+ *
+ * Returns coordinates relative to the viewport, but with scroll offsets
+ * factored out so that FLIP math is correct even inside scrolled containers.
+ */
+function getCorrectedRect(el) {
+    const rect = el.getBoundingClientRect();
+
+    // Walk ancestors to accumulate scroll offsets
+    let scrollX = 0, scrollY = 0;
+    let ancestor = el.parentElement;
+
+    while (ancestor && ancestor !== document.documentElement) {
+        const style = getComputedStyle(ancestor);
+        const overflow = style.overflow + style.overflowX + style.overflowY;
+
+        if (overflow.includes('scroll') || overflow.includes('auto') || overflow.includes('hidden')) {
+            scrollX += ancestor.scrollLeft;
+            scrollY += ancestor.scrollTop;
+        }
+        ancestor = ancestor.parentElement;
+    }
+
+    return {
+        left: rect.left + scrollX,
+        top: rect.top + scrollY,
+        right: rect.right + scrollX,
+        bottom: rect.bottom + scrollY,
+        width: rect.width,
+        height: rect.height,
+        // Keep raw viewport rect for ghost positioning
+        viewportRect: rect,
+    };
+}
+
+/**
+ * Snapshot visual state of an element MID-ANIMATION.
+ * This is the key to interrupted animation handling.
+ *
+ * We temporarily pause all running animations, read the computed style
+ * (which reflects the current visual position), then resume.
+ */
+function snapshotVisualState(el) {
+    const runningAnims = el.getAnimations ? el.getAnimations() : [];
+
+    // Pause all to freeze the visual state
+    runningAnims.forEach(a => a.pause());
+
+    const rect = getCorrectedRect(el);
+    const style = getComputedStyle(el);
+    const opacity = parseFloat(style.opacity);
+    const transform = style.transform;
+
+    // Resume animations (we've read what we need)
+    runningAnims.forEach(a => a.play());
+
+    return { rect, opacity, transform, animations: runningAnims };
+}
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 4 — Hungarian Algorithm (Optimal Matching)
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Build a cost matrix between from-elements and to-elements.
+ * Lower cost = better match.
+ */
+function buildCostMatrix(fromEls, toEls, keyAttr) {
+    const n = Math.max(fromEls.length, toEls.length);
+    // Square matrix, padded with Infinity for dummy assignments
+    const matrix = Array.from({ length: n }, () => Array(n).fill(Infinity));
+
+    for (let i = 0; i < fromEls.length; i++) {
+        for (let j = 0; j < toEls.length; j++) {
+            const from = fromEls[i];
+            const to = toEls[j];
+
+            // Explicit key match = 0 cost (perfect)
+            const fromKey = from.getAttribute?.(keyAttr);
+            const toKey = to.getAttribute?.(keyAttr);
+            if (fromKey && toKey && fromKey === toKey) {
+                matrix[i][j] = 0;
+                continue;
+            }
+            // Key mismatch (both have keys but different) = infinite
+            if (fromKey && toKey && fromKey !== toKey) {
+                matrix[i][j] = Infinity;
+                continue;
+            }
+
+            // Similarity-based cost
+            matrix[i][j] = similarityCost(from, to);
+        }
+    }
+
+    return matrix;
+}
+
+function fingerprint(el) {
+    if (!el || el.nodeType !== 1) return '';
+    const tag = el.tagName;
+    const id = el.id ? `#${el.id}` : '';
+    const cls = Array.from(el.classList).sort().join('.');
+    const text = (el.textContent || '').trim().slice(0, 48);
+    const src = el.getAttribute?.('src') || '';
+    const href = el.getAttribute?.('href') || '';
+    return `${tag}${id}|${cls}|${text}|${src}|${href}`;
+}
+
+function similarityCost(a, b) {
+    if (a.tagName !== b.tagName) return Infinity;
+
+    let score = 0;
+
+    // ID match
+    if (a.id && a.id === b.id) score += 20;
+
+    // Class overlap
+    const aClasses = new Set(a.classList);
+    const bClasses = new Set(b.classList);
+    const union = new Set([...aClasses, ...bClasses]).size;
+    const intersect = [...aClasses].filter(c => bClasses.has(c)).length;
+    if (union > 0) score += 10 * (intersect / union); // Jaccard
+
+    // Text similarity (rough)
+    const aText = (a.textContent || '').trim().slice(0, 64);
+    const bText = (b.textContent || '').trim().slice(0, 64);
+    if (aText && aText === bText) score += 15;
+    else if (aText && bText) {
+        // Rough char overlap
+        const shorter = aText.length < bText.length ? aText : bText;
+        let matches = 0;
+        for (const char of shorter) { if (bText.includes(char)) matches++; }
+        score += 5 * (matches / Math.max(aText.length, bText.length));
+    }
+
+    // Structural depth similarity
+    const aDepth = a.querySelectorAll('*').length;
+    const bDepth = b.querySelectorAll('*').length;
+    const depthDiff = Math.abs(aDepth - bDepth);
+    score += Math.max(0, 5 - depthDiff);
+
+    // Full fingerprint match bonus
+    if (fingerprint(a) === fingerprint(b)) score += 30;
+
+    // Convert score to cost (invert, since Hungarian minimizes)
+    return Math.max(0, 80 - score);
+}
+
+/**
+ * Hungarian algorithm (Munkres) for minimum cost assignment.
+ * O(n³) — fast enough for n < 200.
+ */
+function hungarian(costMatrix) {
+    const n = costMatrix.length;
+    const INF = 1e9;
+
+    // Pad infinite entries to a large finite number for the algorithm
+    const C = costMatrix.map(row => row.map(v => (v === Infinity ? INF : v)));
+
+    const u = Array(n + 1).fill(0);
+    const v = Array(n + 1).fill(0);
+    const p = Array(n + 1).fill(0);  // assignment: column j → row
+    const way = Array(n + 1).fill(0);
+
+    for (let i = 1; i <= n; i++) {
+        p[0] = i;
+        let j0 = 0;
+        const minVal = Array(n + 1).fill(INF);
+        const used = Array(n + 1).fill(false);
+
+        do {
+            used[j0] = true;
+            let i0 = p[j0], delta = INF, j1 = -1;
+
+            for (let j = 1; j <= n; j++) {
+                if (!used[j]) {
+                    const cur = C[i0 - 1][j - 1] - u[i0] - v[j];
+                    if (cur < minVal[j]) { minVal[j] = cur; way[j] = j0; }
+                    if (minVal[j] < delta) { delta = minVal[j]; j1 = j; }
+                }
+            }
+
+            for (let j = 0; j <= n; j++) {
+                if (used[j]) { u[p[j]] += delta; v[j] -= delta; }
+                else minVal[j] -= delta;
+            }
+
+            j0 = j1;
+        } while (p[j0] !== 0);
+
+        do {
+            const j1 = way[j0];
+            p[j0] = p[j1];
+            j0 = j1;
+        } while (j0);
+    }
+
+    // Extract assignment: ans[i] = j means fromEl[i] → toEl[j]
+    const assignment = Array(n).fill(-1);
+    for (let j = 1; j <= n; j++) {
+        if (p[j] !== 0) assignment[p[j] - 1] = j - 1;
+    }
+    return assignment;
+}
+
+/**
+ * Full tree matching using Hungarian algorithm.
+ * Returns Map<fromEl, toEl> and a parallel Map<fromEl, cost> for confidence gating.
+ */
+function buildMatchMap(fromChildren, toChildren, keyAttr, confidenceThreshold) {
+    if (fromChildren.length === 0 || toChildren.length === 0) {
+        return { matches: new Map(), costs: new Map() };
+    }
+
+    const costMatrix = buildCostMatrix(fromChildren, toChildren, keyAttr);
+    const assignment = hungarian(costMatrix);
+
+    const matches = new Map();
+    const costs = new Map();
+    const n = Math.min(fromChildren.length, toChildren.length);
+
+    for (let i = 0; i < fromChildren.length; i++) {
+        const j = assignment[i];
+        if (j == null || j < 0 || j >= toChildren.length) continue;
+
+        const cost = costMatrix[i]?.[j] ?? Infinity;
+
+        // Confidence gate: very high cost → no match, treat as enter/exit
+        if (cost === Infinity || cost > (80 - confidenceThreshold * 10)) continue;
+
+        matches.set(fromChildren[i], toChildren[j]);
+        costs.set(fromChildren[i], cost);
+    }
+
+    return { matches, costs };
+}
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 5 — DOM Patcher
+// ═══════════════════════════════════════════════════════════════
+
+function patchDOM(fromEl, toEl) {
+    // Sync attributes
+    const toAttrs = Array.from(toEl.attributes);
+    const fromAttrs = Array.from(fromEl.attributes);
+
+    for (const { name } of fromAttrs) {
+        if (!toEl.hasAttribute(name)) fromEl.removeAttribute(name);
+    }
+    for (const { name, value } of toAttrs) {
+        if (fromEl.getAttribute(name) !== value) fromEl.setAttribute(name, value);
+    }
+
+    // Snapshot both node lists as static arrays before any DOM mutation.
+    const fN = Array.from(fromEl.childNodes);
+    const tN = Array.from(toEl.childNodes);
+
+    // Walk to-nodes. For each, find the next compatible from-node to reuse.
+    // Skip and remove unmatched from-nodes as we go.
+    let fi = 0;
+    for (let ti = 0; ti < tN.length; ti++) {
+        const tn = tN[ti];
+
+        // Find the next compatible from-node at or after fi
+        let matchIdx = -1;
+        for (let k = fi; k < fN.length; k++) {
+            const fn = fN[k];
+            const compatible =
+                (tn.nodeType === Node.TEXT_NODE && fn.nodeType === Node.TEXT_NODE) ||
+                (tn.nodeType === Node.ELEMENT_NODE && fn.nodeType === Node.ELEMENT_NODE && fn.tagName === tn.tagName);
+            if (compatible) { matchIdx = k; break; }
+        }
+
+        if (matchIdx === -1) {
+            // No compatible from-node — insert a fresh clone before current fi position
+            fromEl.insertBefore(tn.cloneNode(true), fN[fi] || null);
+        } else {
+            // Remove any skipped from-nodes (they have no to-node counterpart)
+            for (let k = fi; k < matchIdx; k++) {
+                if (fN[k].parentNode === fromEl) fromEl.removeChild(fN[k]);
+            }
+            fi = matchIdx;
+
+            const fn = fN[fi];
+            if (tn.nodeType === Node.TEXT_NODE) {
+                if (fn.textContent !== tn.textContent) fn.textContent = tn.textContent;
+            } else {
+                patchDOM(fn, tn);
+            }
+            fi++;
+        }
+    }
+
+    // Remove any remaining from-nodes with no to-node
+    for (let k = fi; k < fN.length; k++) {
+        if (fN[k].parentNode === fromEl) fromEl.removeChild(fN[k]);
+    }
+}
+
+/**
+ * Check whether an element's text/src content actually changed
+ * so we know to run a cross-fade alongside the FLIP.
+ */
+function hasContentChanged(fromEl, toEl) {
+    if (!toEl) return false;
+    const aText = (fromEl.textContent || '').trim();
+    const bText = (toEl.textContent || '').trim();
+    if (aText !== bText) return true;
+    const attrs = ['src', 'href', 'value', 'placeholder'];
+    return attrs.some(a => fromEl.getAttribute(a) !== toEl.getAttribute(a));
+}
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 6 — Interrupted Animation State Store
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Per-element store tracking:
+ *   - active animations
+ *   - last visual snapshot (position when interrupted)
+ *
+ * This is what allows morph() to be called again mid-flight
+ * and start from exactly where things visually are.
+ */
+const _elementState = new WeakMap();
+
+function getElementState(el) {
+    if (!_elementState.has(el)) {
+        _elementState.set(el, { animations: [], lastSnapshot: null });
+    }
+    return _elementState.get(el);
+}
+
+/**
+ * Cancel any in-flight animations on el, capturing visual state first.
+ * Returns the snapshot so the new animation can start from there.
+ */
+function cancelAndSnapshot(el) {
+    const state = getElementState(el);
+
+    // Read current visual state (mid-animation position)
+    const snapshot = snapshotVisualState(el);
+
+    // Now cancel all running animations
+    const anims = el.getAnimations ? el.getAnimations() : [];
+    anims.forEach(a => {
+        try { a.cancel(); } catch (_) { }
+    });
+
+    state.animations = [];
+    state.lastSnapshot = snapshot;
+
+    return snapshot;
+}
+
+function registerAnimation(el, anim) {
+    const state = getElementState(el);
+    state.animations.push(anim);
+    anim.finished
+        .then(() => {
+            state.animations = state.animations.filter(a => a !== anim);
+        })
+        .catch(() => { });
+}
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 7 — FLIP Animator (Interrupt-Safe + Spring-Aware)
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Core FLIP animation for a single element.
+ *
+ * Interrupt-safe: if the element is mid-animation, we read its
+ * current visual position and animate FROM there (not from the
+ * original pre-patch position).
+ */
+function animateFLIP(el, fromRect, toRect, opts, delay, contentChanged, toSnapshot) {
+    if (!fromRect || !toRect) return null;
+
+    // If element has running animations, snapshot visual position and cancel
+    const hasRunning = (el.getAnimations?.() ?? []).some(a => a.playState === 'running');
+    let effectiveFromRect = fromRect;
+
+    if (hasRunning) {
+        const snapshot = cancelAndSnapshot(el);
+        // Use the visual snapshot rect instead of the pre-patch rect
+        effectiveFromRect = snapshot.rect;
+    }
+
+    const dx = effectiveFromRect.left - toRect.left;
+    const dy = effectiveFromRect.top - toRect.top;
+    const scaleX = effectiveFromRect.width / (toRect.width || 1);
+    const scaleY = effectiveFromRect.height / (toRect.height || 1);
+
+    const noTranslate = Math.abs(dx) < 0.5 && Math.abs(dy) < 0.5;
+    const noScale = Math.abs(scaleX - 1) < 0.01 && Math.abs(scaleY - 1) < 0.01;
+
+    if (noTranslate && noScale && !contentChanged) return null;
+
+    // Custom onMove hook
+    if (opts.onMove) {
+        const custom = opts.onMove(el, effectiveFromRect, toRect);
+        if (custom) {
+            const anim = el.animate(custom, {
+                duration: opts.duration,
+                easing: opts.easing === 'spring' ? 'ease-out' : opts.easing,
+                delay,
+                fill: 'none',
+            });
+            registerAnimation(el, anim);
+            return anim;
+        }
+    }
+
+    // Build keyframes
+    let moveKeyframes;
+    const isSpring = opts.easing === 'spring';
+
+    if (!noTranslate || !noScale) {
+        moveKeyframes = isSpring
+            ? springFLIPKeyframes(dx, dy, scaleX, scaleY, opts.spring)
+            : [
+                { transform: `translate(${dx}px, ${dy}px) scale(${scaleX}, ${scaleY})`, transformOrigin: 'top left' },
+                { transform: 'translate(0, 0) scale(1, 1)', transformOrigin: 'top left' },
+            ];
+    }
+
+    // If content also changed, overlay a crossfade
+    if (contentChanged && opts.morphContent) {
+        // Clone the old visual into an overlay, fade it out while the element fades in
+        const ghost = el.cloneNode(true);
+        const rect = toRect.viewportRect || toRect;
+
+        ghost.style.cssText = [
+            `position:fixed`,
+            `left:${effectiveFromRect.viewportRect?.left ?? effectiveFromRect.left}px`,
+            `top:${effectiveFromRect.viewportRect?.top ?? effectiveFromRect.top}px`,
+            `width:${effectiveFromRect.width}px`,
+            `height:${effectiveFromRect.height}px`,
+            `margin:0`,
+            `pointer-events:none`,
+            `z-index:9999`,
+        ].join(';');
+
+        document.body.appendChild(ghost);
+
+        ghost.animate(
+            [{ opacity: 1 }, { opacity: 0 }],
+            { duration: opts.duration * 0.5, delay, easing: 'ease', fill: 'forwards' }
+        ).finished.then(() => ghost.remove()).catch(() => ghost.remove());
+
+        el.animate(
+            [{ opacity: 0 }, { opacity: 1 }],
+            { duration: opts.duration * 0.5, delay: delay + opts.duration * 0.3, easing: 'ease', fill: 'backwards' }
+        );
+    }
+
+    if (!moveKeyframes) return null;
+
+    let springDuration = opts.duration;
+    if (isSpring) {
+        const { settleTime } = solveSpring(opts.spring.stiffness, opts.spring.damping, opts.spring.mass);
+        springDuration = settleTime * 1000; // seconds → ms
+    }
+    const timing = isSpring
+        ? { duration: springDuration, easing: 'linear', delay, fill: 'none' }
+        : { duration: opts.duration, easing: opts.easing, delay, fill: 'none' };
+
+    const anim = el.animate(moveKeyframes, timing);
+    registerAnimation(el, anim);
+    return anim;
+}
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 8 — Enter / Exit Animators
+// ═══════════════════════════════════════════════════════════════
+
+function animateEnter(el, opts, delay) {
+    const keyframes = opts.onEnter?.(el) || [
+        { opacity: 0, transform: 'scale(0.88) translateY(10px)' },
+        { opacity: 1, transform: 'scale(1) translateY(0)' },
+    ];
+
+    const anim = el.animate(keyframes, {
+        duration: opts.duration * opts.choreography.enter.duration,
+        easing: opts.easing === 'spring' ? 'cubic-bezier(0.34,1.56,0.64,1)' : opts.easing,
+        delay,
+        fill: 'backwards',
+    });
+
+    registerAnimation(el, anim);
+    return anim;
+}
+
+function animateLeaveGhost(el, rect, opts, delay) {
+    const ghost = el.cloneNode(true);
+    const vr = rect.viewportRect || rect;
+
+    ghost.style.cssText = [
+        'position:fixed',
+        `left:${vr.left}px`,
+        `top:${vr.top}px`,
+        `width:${rect.width}px`,
+        `height:${rect.height}px`,
+        'margin:0',
+        'pointer-events:none',
+        'z-index:9998',
+        'will-change:transform,opacity',
+    ].join(';');
+
+    document.body.appendChild(ghost);
+
+    const keyframes = opts.onLeave?.(ghost, rect) || [
+        { opacity: 1, transform: 'scale(1) translateY(0)' },
+        { opacity: 0, transform: 'scale(0.88) translateY(-6px)' },
+    ];
+
+    const anim = ghost.animate(keyframes, {
+        duration: opts.duration * opts.choreography.exit.duration,
+        easing: opts.easing === 'spring' ? 'ease-in' : opts.easing,
+        delay,
+        fill: 'forwards',
+    });
+
+    anim.finished
+        .then(() => ghost.remove())
+        .catch(() => ghost.remove());
+
+    return anim;
+}
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 9 — Layout Capture
+// ═══════════════════════════════════════════════════════════════
+
+function captureLayout(root) {
+    const map = new Map();
+    map.set(root, getCorrectedRect(root));
+    for (const el of root.querySelectorAll('*')) {
+        map.set(el, getCorrectedRect(el));
+    }
+    return map;
+}
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 10 — Debug Logger
+// ═══════════════════════════════════════════════════════════════
+
+function createDebugLog(opts) {
+    if (!opts.debug) return { log: () => { }, data: null };
+
+    const data = {
+        timestamp: Date.now(),
+        matches: [],
+        entering: [],
+        leaving: [],
+        spring: opts.easing === 'spring' ? opts.spring : null,
+    };
+
+    const log = (type, payload) => {
+        if (type === 'match') data.matches.push(payload);
+        if (type === 'enter') data.entering.push(payload);
+        if (type === 'leave') data.leaving.push(payload);
+        if (type === 'summary') {
+            console.group(`[morph.js v${VERSION}]`);
+            console.log(`Matches: ${data.matches.length} | Entering: ${data.entering.length} | Leaving: ${data.leaving.length}`);
+            data.matches.forEach(m =>
+                console.log(`  MOVE  "${m.key || m.from}" → confidence ${(100 - m.cost).toFixed(0)}%  Δ(${m.dx?.toFixed(1)}, ${m.dy?.toFixed(1)})`)
+            );
+            data.entering.forEach(e => console.log(`  ENTER "${e.key || e.tag}"`));
+            data.leaving.forEach(l => console.log(`  LEAVE "${l.key || l.tag}"`));
+            console.groupEnd();
+        }
+    };
+
+    return { log, data };
+}
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 11 — morph() — Main Entry Point
+// ═══════════════════════════════════════════════════════════════
+
+function morph(fromEl, toElOrHTML, userOpts = {}) {
+    const opts = deepMerge(DEFAULTS, userOpts);
+
+    // Parse input
+    let toEl;
+    if (typeof toElOrHTML === 'string') {
+        toEl = document.createElement(fromEl.tagName);
+        toEl.innerHTML = toElOrHTML;
+    } else {
+        toEl = toElOrHTML;
+    }
+
+    // Reduced motion: instant patch, no animation
+    if (opts.respectReducedMotion && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches) {
+        patchDOM(fromEl, toEl);
+        return { animations: [], finished: Promise.resolve(), debug: null };
+    }
+
+    const debug = createDebugLog(opts);
+    const animations = [];
+    const dur = opts.duration;
+    const choreo = opts.choreography;
+
+    // ── 1. FIRST: capture layout before any DOM changes ──────────
+
+    const beforeLayout = captureLayout(fromEl);
+
+    // Snapshot visual state of all current children (for interruption handling)
+    const fromChildren = Array.from(fromEl.children);
+    const toChildren = Array.from(toEl.children);
+
+    // Per-child visual snapshots (captures mid-animation state)
+    const snapshots = new Map();
+    for (const child of fromChildren) {
+        snapshots.set(child, snapshotVisualState(child));
+    }
+
+    // ── 2. Match from-children to to-children (Hungarian) ────────
+
+    const { matches, costs } = buildMatchMap(
+        fromChildren, toChildren,
+        opts.keyAttribute,
+        opts.matchConfidenceThreshold
+    );
+
+    const matchedFrom = new Set(matches.keys());
+    const matchedTo = new Set(matches.values());
+
+    const leaving = fromChildren.filter(el => !matchedFrom.has(el));
+    const entering = toChildren.filter(el => !matchedTo.has(el));
+
+    // ── 3. Animate LEAVING elements (ghost overlay strategy) ─────
+
+    const exitDelay = choreo.exit.at * dur;
+
+    leaving.forEach((el, i) => {
+        const rect = beforeLayout.get(el) || getCorrectedRect(el);
+        debug.log('leave', { key: el.getAttribute(opts.keyAttribute), tag: el.tagName });
+
+        const anim = animateLeaveGhost(el, rect, opts, exitDelay + i * opts.stagger * 0.4);
+        if (anim) animations.push(anim);
+    });
+
+    // ── 4. LAST: patch the DOM ───────────────────────────────────
+
+    patchDOM(fromEl, toEl);
+
+    // ── 5. INVERT + PLAY: animate moved elements ─────────────────
+
+    const moveDelay = choreo.move.at * dur;
+    const afterLayout = captureLayout(fromEl);
+
+    Array.from(matches.entries()).forEach(([fromChild, toChild], i) => {
+        // Use visual snapshot (handles mid-animation interruption)
+        const snapshot = snapshots.get(fromChild);
+        const beforeRect = snapshot?.rect || beforeLayout.get(fromChild);
+
+        // After patchDOM, fromChild may be stale. Find the corresponding
+        // element in the live DOM by key attribute or fall back to fromChild.
+        const key = toChild.getAttribute(opts.keyAttribute);
+        let liveEl = fromChild;
+        if (key) {
+            liveEl = fromEl.querySelector(`[${opts.keyAttribute}="${CSS.escape(key)}"]`) || fromChild;
+        }
+        const afterRect = afterLayout.get(liveEl) || getCorrectedRect(liveEl);
+
+        const cost = costs.get(fromChild) ?? 0;
+        const changed = hasContentChanged(fromChild, toChild);
+        const delay = moveDelay + i * opts.stagger;
+
+        debug.log('match', {
+            key: fromChild.getAttribute(opts.keyAttribute),
+            from: fromChild.tagName,
+            cost,
+            dx: (beforeRect?.left ?? 0) - (afterRect?.left ?? 0),
+            dy: (beforeRect?.top ?? 0) - (afterRect?.top ?? 0),
+        });
+
+        const anim = animateFLIP(liveEl, beforeRect, afterRect, opts, delay, changed, toChild);
+        if (anim) animations.push(anim);
+    });
+
+    // ── 6. Animate ENTERING elements ─────────────────────────────
+
+    const enterDelay = choreo.enter.at * dur;
+    let enterIdx = 0;
+
+    for (const child of fromEl.children) {
+        if (!beforeLayout.has(child)) {
+            debug.log('enter', { key: child.getAttribute(opts.keyAttribute), tag: child.tagName });
+            const anim = animateEnter(child, opts, enterDelay + enterIdx * opts.stagger);
+            if (anim) animations.push(anim);
+            enterIdx++;
+        }
+    }
+
+    // ── 7. Debug summary ─────────────────────────────────────────
+
+    if (opts.debug) debug.log('summary');
+
+    const finished = Promise.all(animations.map(a => a.finished)).catch(() => { });
+
+    return {
+        animations,
+        finished,
+        debug: debug.data,
+        cancel() { animations.forEach(a => { try { a.cancel(); } catch (_) { } }); },
+    };
+}
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 12 — morph.text() — Cross-Fade Text Changes
+// ═══════════════════════════════════════════════════════════════
+
+morph.text = function (el, newText, opts = {}) {
+    const duration = opts.duration || 250;
+    const easing = opts.easing || 'ease';
+
+    // Cancel any running text morph on this element
+    cancelAndSnapshot(el);
+
+    const anim = el.animate([{ opacity: 1 }, { opacity: 0 }], {
+        duration: duration * 0.45, easing, fill: 'forwards',
+    });
+
+    const done = anim.finished.then(() => {
+        el.textContent = newText;
+        const anim2 = el.animate([{ opacity: 0 }, { opacity: 1 }], {
+            duration: duration * 0.55, easing, fill: 'forwards',
+        });
+        registerAnimation(el, anim2);
+        return anim2.finished;
+    }).catch(() => { });
+
+    registerAnimation(el, anim);
+
+    return { finished: done, cancel: () => anim.cancel() };
+};
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 13 — morph.prepare() — Controllable Transition
+// ═══════════════════════════════════════════════════════════════
+
+morph.prepare = function (fromEl, toEl, opts = {}) {
+    let result = null;
+    let played = false;
+
+    return {
+        play() {
+            if (!played) { played = true; result = morph(fromEl, toEl, opts); }
+            return result;
+        },
+        cancel() { result?.cancel(); },
+        get animations() { return result?.animations || []; },
+        get finished() { return result?.finished || Promise.resolve(); },
+        get debug() { return result?.debug || null; },
+    };
+};
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 14 — MorphObserver — Auto-Animate DOM Mutations
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Watches a container for DOM mutations (innerHTML swaps, appendChild,
+ * removeChild, etc.) and automatically runs morph() on each change.
+ *
+ * Works with any DOM-mutating approach: htmx, Alpine.js, Turbo,
+ * vanilla innerHTML, React portals, etc.
+ *
+ * Usage:
+ *   const obs = new MorphObserver(container, { duration: 350 });
+ *   obs.observe();
+ *   // Now any mutation to container's children will auto-animate
+ *   obs.disconnect();
+ */
+class MorphObserver {
+    constructor(container, opts = {}) {
+        this._container = container;
+        this._opts = deepMerge(DEFAULTS, opts);
+        this._observer = null;
+        this._pending = null;
+        this._snapshot = null;
+        this._debounce = opts.debounce ?? 16; // ms — coalesce rapid mutations
+    }
+
+    observe() {
+        if (this._observer) return;
+
+        this._snapshot = this._captureSnapshot();
+        this._paused = false;
+
+        this._observer = new MutationObserver((mutations) => {
+            if (this._paused) return; // ignore mutations we triggered ourselves
+            this._onMutations(mutations);
+        });
+
+        this._observer.observe(this._container, {
+            childList: true,
+            subtree: false,
+            attributes: true,
+            characterData: true,
+            attributeOldValue: true,
+        });
+
+        return this;
+    }
+
+    disconnect() {
+        this._observer?.disconnect();
+        this._observer = null;
+        if (this._pending) { clearTimeout(this._pending); this._pending = null; }
+        return this;
+    }
+
+    /**
+     * Manually trigger a morph to a new HTML string or element.
+     * Useful when you know a change is about to happen and want
+     * to control timing.
+     */
+    morph(toHTML, opts = {}) {
+        return morph(this._container, toHTML, { ...this._opts, ...opts });
+    }
+
+    _captureSnapshot() {
+        return {
+            html: this._container.innerHTML,
+            layout: captureLayout(this._container),
+            children: Array.from(this._container.children).map(el => ({
+                el,
+                key: el.getAttribute(this._opts.keyAttribute),
+                rect: getCorrectedRect(el),
+            })),
+        };
+    }
+
+    _onMutations(mutations) {
+        const prevSnapshot = this._snapshot;
+
+        // Capture current (post-mutation) state immediately and synchronously
+        const newHTML = this._container.innerHTML;
+        this._snapshot = this._captureSnapshot();
+
+        if (this._pending) clearTimeout(this._pending);
+
+        this._pending = setTimeout(() => {
+            this._pending = null;
+
+            // Pause observer so our restore write doesn't re-trigger _onMutations
+            this._paused = true;
+            this._container.innerHTML = prevSnapshot.html;
+            this._paused = false;
+
+            // morph() snapshots layout from the restored state, patches to newHTML
+            const result = morph(this._container, newHTML, this._opts);
+
+            // Sync snapshot to actual DOM state after morph patch
+            this._snapshot = this._captureSnapshot();
+
+            this._opts.onMorph?.(result);
+        }, this._debounce);
+    }
+}
+
+morph.Observer = MorphObserver;
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 15 — htmx Extension
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Registers a morph.js htmx extension.
+ *
+ * Usage:
+ *   <div hx-ext="morph" hx-swap="innerHTML">...</div>
+ *
+ *   morph.htmx({ duration: 350, stagger: 30 });
+ *
+ * How it works:
+ *   - On htmx:beforeSwap: capture current layout + snapshot
+ *   - On htmx:afterSettle: run morph from captured state to new state
+ */
+morph.htmx = function (opts = {}) {
+    if (typeof htmx === 'undefined') {
+        console.warn('[morph.js] htmx not found. Call morph.htmx() after htmx loads.');
+        return;
+    }
+
+    const snapshots = new WeakMap();
+
+    htmx.defineExtension('morph', {
+        onEvent(name, evt) {
+            const el = evt.detail?.elt || evt.target;
+            if (!el) return;
+
+            if (name === 'htmx:beforeSwap') {
+                // Snapshot layout before htmx swaps the DOM
+                snapshots.set(el, {
+                    layout: captureLayout(el),
+                    children: Array.from(el.children),
+                    html: el.innerHTML,
+                });
+            }
+
+            if (name === 'htmx:afterSettle') {
+                const snap = snapshots.get(el);
+                if (!snap) return;
+
+                // Save the new (post-swap) HTML, restore old DOM, then morph forward
+                const newHTML = el.innerHTML;
+                el.innerHTML = snap.html;
+
+                morph(el, newHTML, {
+                    ...DEFAULTS,
+                    ...opts,
+                });
+
+                snapshots.delete(el);
+            }
+        }
+    });
+};
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 16 — Utilities
+// ═══════════════════════════════════════════════════════════════
+
+function deepMerge(defaults, overrides) {
+    const result = { ...defaults };
+    for (const key of Object.keys(overrides)) {
+        if (
+            overrides[key] !== null &&
+            typeof overrides[key] === 'object' &&
+            !Array.isArray(overrides[key]) &&
+            defaults[key] !== null &&
+            typeof defaults[key] === 'object' &&
+            !Array.isArray(defaults[key])
+        ) {
+            result[key] = deepMerge(defaults[key], overrides[key]);
+        } else {
+            result[key] = overrides[key];
+        }
+    }
+    return result;
+}
+
+
+// ═══════════════════════════════════════════════════════════════
+// § 17 — Exports
+// ═══════════════════════════════════════════════════════════════
+
+morph.version = VERSION;
+morph.defaults = DEFAULTS;
+
+export { morph, MorphObserver };
+export default morph;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@pariharshyamu/morph",
+  "version": "2.0.0",
+  "description": "Interrupt-safe DOM morphing with spring physics, FLIP animations, Hungarian algorithm matching, and auto-animate via MutationObserver. Works with htmx, Alpine.js, Turbo, or vanilla JS.",
+  "main": "morph.js",
+  "module": "morph.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./morph.js",
+      "default": "./morph.js"
+    }
+  },
+  "files": [
+    "morph.js",
+    "README.md"
+  ],
+  "keywords": [
+    "morph",
+    "dom",
+    "flip",
+    "animation",
+    "spring",
+    "transition",
+    "htmx",
+    "mutation-observer",
+    "morphdom",
+    "crossfade",
+    "waapi"
+  ],
+  "author": "pariharshyamu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "homepage": "",
+  "bugs": {
+    "url": ""
+  }
+}