morphicons 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guillermo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+<p align="center">
+  <a href="https://www.morphicons.com">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
+      <img src="assets/logo-light.svg" alt="morphicons" width="96">
+    </picture>
+  </a>
+</p>
+
+<h1 align="center">morphicons</h1>
+
+<p align="center">
+  <a href="https://www.morphicons.com"><strong>morphicons.com</strong></a> — live playground
+</p>
+
+Universal morphing for stroke-based icons (Lucide, Feather, Tabler, or your own paths): **any icon morphs into any other** with spring physics. Rotations are never declared by hand — they emerge from the math (2D Procrustes + polar interpolation). Zero runtime dependencies.
+
+```tsx
+import { MorphIcon } from "morphicons/react";
+import { Menu, X } from "lucide"; // data, not components
+
+<button onClick={() => setOpen(o => !o)} aria-expanded={open}>
+  <MorphIcon icon={open ? X : Menu} />
+</button>
+```
+
+That's the whole thing. No wrappers, no `AnimatePresence`, no keys, no from/to pairs, no configuration. State lives outside; the animation is an implementation detail the component picks up when the prop changes.
+
+## Why
+
+The usual icon morphs either interpolate raw coordinates (shapes shrink and shear in transit) or require hand-declaring "rotation groups" per icon pair. morphicons solves the optimal similarity between shapes in closed form and interpolates it in its natural space: if a pair is congruent under rotation, it **rotates**; if not, it morphs in the aligned frame. arrow-right → arrow-down yields θ = 90° on its own, without anyone declaring it.
+
+## Install
+
+```bash
+bun add morphicons        # or npm install / pnpm add
+```
+
+ESM only. `react` is an optional peer (>= 18) — only needed for `morphicons/react`.
+
+## Usage
+
+### React — three modes
+
+```tsx
+import { MorphIcon, type MorphHandle } from "morphicons/react";
+
+// 1. Uncontrolled (90% of uses): change the prop and morphicons animates
+<MorphIcon icon={open ? X : Menu} spring="snappy" />
+
+// 2. Controlled (gestures, scroll): explicit progress, no spring
+<MorphIcon from={Menu} to={X} progress={dragProgress} />
+
+// 3. Imperative (sequences)
+const ref = useRef<MorphHandle>(null);
+<MorphIcon ref={ref} icon={Menu} />
+ref.current?.morphTo(Check); // animates
+ref.current?.set(X);         // jumps without animating
+```
+
+Drop-in replacement for lucide-react: `size`, `strokeWidth`, `absoluteStrokeWidth`, `color`, `className` and the rest of the `<svg>` props pass straight through. Correct accessibility by default: `aria-hidden` unless you pass `label` (→ `role="img"` + `<title>`). Clean SSR: the server emits the exact static SVG (zero flash, zero layout shift); the runtime is born on hydration. `prefers-reduced-motion` degrades to an instant swap.
+
+### Vanilla (no React)
+
+```ts
+import { createMorph } from "morphicons/dom";
+
+const m = createMorph(pathEl, Menu); // pathEl: any object with setAttribute
+m.morphTo(X, "snappy");              // preset or { stiffness, damping }
+m.set(Check);                        // jump without animating (canonical d)
+m.seek(X, 0.4);                      // morph frozen at t — scrubbing, gestures
+m.progress = 0.4;                    // sugar: seek on the active target
+m.destroy();
+```
+
+Truly interruptible: a `morphTo` mid-flight re-plans from the current intermediate shape while preserving the spring's velocity — click spam never jumps. A single global `requestAnimationFrame` drives all instances.
+
+### Pure core (no DOM)
+
+```ts
+import { resampleIcon, buildPlan, interpPolar, allocOutputs, serialize } from "morphicons";
+
+const plan = buildPlan(resampleIcon(Menu), resampleIcon(X)); // cacheable
+const out = allocOutputs(plan);
+interpPolar(plan, 0.5, out);                                 // t ∈ [0, 1]
+const d = serialize(out, plan.items.map(it => it.closed));   // `d` attribute
+```
+
+Accepts `IconNode` (Lucide's data format, structurally typed — Lucide is neither a dependency nor a peer) or a raw `d` attribute. Feather, Tabler and custom paths work the same.
+
+## Icon library compatibility
+
+morphicons has no per-library adapters — any icon set that meets these requirements works out of the box:
+
+1. **Stroke-drawn icons.** The geometry must be the stroked centerline (`fill="none"`, color via `stroke`). The whole pipeline — resampling, correspondence, in-flight polylines — assumes strokes; filled or outlined-fill glyphs (Material Symbols, Bootstrap Icons, Remix Icon, Phosphor, Heroicons *solid*) parse fine but won't read correctly in transit.
+2. **Geometry available as data.** Either a raw `d` attribute per icon, or a `[tag, attrs][]` node list (Lucide's IconNode shape) using only `path`, `line`, `circle`, `ellipse`, `rect`, `polyline`, `polygon`. No `<g>` wrappers and no `transform` attributes — coordinates must be literal. Any other tag throws a clear error.
+3. **A shared coordinate space per pair.** Both endpoints of a morph must live on the same grid. Lucide, Feather and Tabler all draw on 24×24 — that's why cross-library morphs just work. The React binding defaults to `viewBox="0 0 24 24"`, overridable via props.
+4. **Uniform stroke.** Cosmetic rather than structural: a consistent stroke width and round caps/joins make in-flight shapes look native. These live on the `<svg>`, not in morphicons.
+
+Beyond the three libraries in the playground, sets known to qualify: **Heroicons** (outline style, 24×24), **Iconoir** (24×24, 1.5px stroke), **Akar Icons** (24×24), **Untitled UI** (24×24) and **Hugeicons** (stroke style, 24×24). **Teenyicons** qualifies too but draws on a 15×15 grid — keep both endpoints on that grid and pass the matching `viewBox`.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│  bindings   react                           │  thin: ref + createMorph
+├─────────────────────────────────────────────┤
+│  drivers    dom (setAttribute + rAF)        │  singleton scheduler
+├─────────────────────────────────────────────┤
+│  core       parse → normalize → resample    │  pure functions,
+│             → match → align → plan          │  NO DOM, produce
+│             → interpolate → serialize       │  `d` strings and numbers
+│             + spring                        │
+└─────────────────────────────────────────────┘
+```
+
+The hard rule: **the core never touches the DOM**. Pure functions consume icon data and produce `d` strings. Direct consequence: a React Native driver over `react-native-svg` + Reanimated is just another adapter, not a rewrite. One package with subpath exports (`.` core, `./dom`, `./react`), ESM only, `sideEffects: false`.
+
+The plan is the central artifact:
+
+```
+icon A ─┐
+        ├→ normalize → resample → match → align → PLAN ─→ interpolate(t) → serialize → d
+icon B ─┘                                           ↑
+                                        cacheable, serializable
+```
+
+`plan()` accepts any list of sampled subpaths — not just canonical icons — which is what makes interruptions free: the currently rendered buffers are a valid morph source.
+
+## How the math works
+
+### 1. Normalization — everything to cubic Béziers
+
+Every SVG primitive is reduced to cubic segments:
+
+- **Line** → cubic with collinear controls: `C₁ = P₀ + ⅓(P₃−P₀)`, `C₂ = P₀ + ⅔(P₃−P₀)`.
+- **Quadratic** → exact degree elevation: `C₁ = Q₀ + ⅔(Q₁−Q₀)`, `C₂ = Q₂ + ⅔(Q₁−Q₂)`.
+- **Circle** → 4 cubics with offset `k = r·(4/3)·tan(π/8) ≈ 0.5523·r`.
+- **Arc `A`** → center parametrization (SVG spec, appendix F.6), sliced into arcs ≤ 90°, each slice to a cubic with `α = (4/3)·tan(Δθ/4)`.
+- **rect/polyline/polygon** → lines (rounded rects: lines + quarter ellipses).
+
+The `d` parser handles absolute/relative commands, H/V/S/T shorthands, packed arc flags and scientific notation. Result: icon = list of subpaths; subpath = chain of cubics + closed/open flag.
+
+### 2. Resampling — arc length with anchored corners
+
+Instead of fighting Bézier structures of different cardinality, every subpath is sampled at **N points equidistant by arc length** (N = 64). Every subpath becomes a `Float64Array(2N)` and the structural problem disappears: correspondence is index to index.
+
+The arc length of a cubic has no closed form; `|B′(t)|` is integrated with 8-point Gauss-Legendre quadrature per segment.
+
+The refinement that drives quality: **corner detection** (tangent discontinuity above an angular threshold) with corners anchored as exact sample points. Remaining points are apportioned by arc length between corners — integer apportionment by largest remainder, minimum 1 interval per run, summing exactly to N−1. Effects:
+
+- At rest the shape is **exact** (a check's vertex is a sample, not an approximation).
+- In transit, source corners flatten smoothly and target corners sharpen — the desired behavior. Without anchoring, a morphing check visibly rounds its corners.
+
+Closed paths anchor **only corners**, not the arbitrary `M` start point — sampling is intrinsic to the shape, so two congruent loops with different start points produce the same sample set (modulo index rotation, resolved by the circular correspondence below).
+
+### 3. Correspondence
+
+Three subproblems:
+
+- **Orientation.** Both traversal directions of B are tried and scored (see the tie-break below). A hamburger line folding to the correct diagonal depends on this.
+- **Start point (closed paths).** A closed contour has a circular degree of freedom: which index is "first". The N circular offsets × 2 directions are tried and the best post-alignment score wins. O(N²) brute force with N = 64 is ~4K operations per pair — negligible.
+- **Subpath matching.** With p subpaths in A and q in B, pairing cost is `dist(centroids) + 0.35·|ΔL|` (arc lengths). Equal counts use the minimum-cost permutation (exhaustive with pruning up to 8 subpaths, greedy above); unequal counts use a **surjective** assignment from the large side to the small one, so no subpath ever appears or disappears out of nowhere. Leftovers are **not collapsed to a point**: the nearest subpath is **duplicated** in place and the copies separate in flight — it reads as cell division, far more natural than growing from nothing. At rest, overlapping duplicates with the same solid stroke are invisible, and the canonical snap on settle resets the count.
+
+### 4. Alignment — 2D Procrustes
+
+Before interpolating, the **optimal similarity** (rotation θ, scale σ, translation) mapping A onto B is computed by minimizing `Σ|σ·R(θ)·(aᵢ−c_A) − (bᵢ−c_B)|²`. In 2D it has a closed form, no SVD:
+
+```
+S_xx = Σ aₓbₓ    S_xy = Σ aₓbᵧ    (centered clouds)
+S_yx = Σ aᵧbₓ    S_yy = Σ aᵧbᵧ
+
+θ* = atan2(S_xy − S_yx,  S_xx + S_yy)
+σ* = [cos θ*·(S_xx+S_yy) + sin θ*·(S_xy−S_yx)] / Σ‖aᵢ‖²
+```
+
+The normalized RMS **residual** after alignment (`res = √(Σ|σRa−b|² / Σ‖b‖²)`) is the shape metric: ≈ 0 means A and B are the same shape rotated/scaled. This turns rotation groups into an **emergent property**: arrow-right → arrow-down gives residual ~0 with θ = 90° and the system chooses pure rotation on its own.
+
+Procrustes runs **per subpath** (each piece rotates around its own centroid, which translates independently) — this gives local, organic motion: a hamburger *folds* instead of spinning as a block. A **global hybrid** pass then runs Procrustes over the concatenated clouds: if the global residual is ≈ 0 (< 5e-3) the whole icon is congruent and every subpath shares the same (θ, σ), so e.g. both subpaths of an arrow spin the same way.
+
+#### Minimal-rotation tie-break
+
+For shapes symmetric under inversion (a straight line), both traversal orientations give residual 0 — indistinguishable to Procrustes — but produce different rotations. Naive tie-breaking can pick θ = 135° when the inverted orientation gives θ = −45° with the same end result. Each orientation is scored with:
+
+```
+score = res + λ·|θ|/π      (λ = 0.05)
+```
+
+Deformation is minimized first and, at comparable residuals, the shortest rotation wins. λ is small enough that a notably worse shape never wins just by rotating less. This is the kind of detail the math doesn't see but the eye does.
+
+### 5. Polar interpolation
+
+Raw coordinate lerp **collapses rotations**: points take the chord, the shape shrinks and shears in transit. The fix: decompose the motion into similarity + residual and interpolate each part in its natural space.
+
+Let `aᶜᵢ = aᵢ − c_A` and `b̃ᵢ = R(−θ*)·(bᵢ − c_B)/σ*` (B brought into A's frame). Then:
+
+```
+P(t) = c(t) + σ*ᵗ · R(t·θ*) · [(1−t)·aᶜᵢ + t·b̃ᵢ]
+
+  c(t)  = lerp(c_A, c_B, t)        linear translation
+  t·θ*  = linear angle             (θ* is already in (−π, π], short path)
+  σ*ᵗ   = exp(t·ln σ*)             log-linear scale (geodesic in ℝ⁺)
+```
+
+Exact at both endpoints (max error ~3.6e-15 in tests). Properties:
+
+- If B is A rotated (residual 0), the bracket is constant and the motion is **pure rotation**.
+- If there is no rotation, it's a clean coordinate morph.
+- Mixed cases do both simultaneously and continuously.
+- With spring overshoot (t > 1) the formula **extrapolates** naturally: rotation and scale overshoot slightly and come back — free juice.
+
+### 6. Serialization and canonical snap
+
+In flight, each subpath is emitted as `M x y L x y …` (+ `Z` if the pair is closed↔closed; closed→open flies open, the loop opening at the cut chosen by the circular correspondence) with 2 decimals — invisible at 24px, and the frame's only allocation. On settle, the driver **snaps to the canonical `d`** of the target icon: exact fidelity at rest (real curves, not polylines), subpath count reset after duplications, and the DOM ends up identical to a static icon's. The jump is < 0.02px — imperceptible.
+
+### 7. The spring
+
+Damped harmonic oscillator over progress `x: 0 → 1`:
+
+```
+ẍ = k·(1 − x) − c·ẋ
+```
+
+Integrated with **semi-implicit Euler** at h = 1/240 s substeps (stable up to ω·h ≈ 2; with k = 420, ω ≈ 20.5 — ample margin). ~25 lines, no animation library needed.
+
+| preset | k | c | ζ = c/(2√k) | character |
+|--------|-----|-----|------|-----------|
+| smooth | 170 | 26 | 1.00 | critically damped, no overshoot |
+| snappy | 420 | 30 | 0.73 | fast, subtle overshoot |
+| bouncy | 300 | 14 | 0.40 | playful |
+
+**Interruptions**: when a `morphTo` arrives mid-flight, the plan is rebuilt from the current intermediate shape (the rendered buffers are already N points per subpath — they serve directly as source), `x` resets to 0 and **velocity is preserved** (clamped to ±14). Perceived motion is continuous; tap spam feels alive, never jumps. The spring settles and the rAF stops when `|1−x| < 0.001 ∧ |v| < 0.02`.
+
+## Performance
+
+- `plan(A, B)` complete (resample + match + Procrustes × orientations): **sub-millisecond** with N = 64 — measured 0.01 ms (open paths) to 0.06 ms (closed, with circular search); 0.42 ms for a pathological 12-loops case.
+- **Zero numeric allocation per frame**: interpolators write into the plan's preallocated `Float64Array`s. Only the `d` string is allocated.
+- **Caches by reference**: `normalize(icon)` in a WeakMap keyed by the IconNode (Lucide imports are stable references → no string keys, GC-friendly). `plan(A, B)` in a nested WeakMap; plans from interruptions are never cached.
+- **One global rAF** (singleton scheduler): active instances are iterated, settled ones unregister. A hundred icons morphing at once = one loop.
+
+## Size
+
+CI budget (size-limit, gzip) as an anti-regression tripwire — gates carry ~10% headroom over what's measured; if a real capability needs more, the number is renegotiated, but growing unnoticed is not accepted:
+
+| entry | measured | gate |
+|---|---|---|
+| `morphicons` (core) | 6.32 KB | 7 KB |
+| `morphicons/dom` (core + driver) | 6.92 KB | 7.5 KB |
+| `morphicons/react` (all, react external) | 7.65 KB | 8.5 KB |
+
+## Playground
+
+```bash
+bun run play   # → http://localhost:3000
+```
+
+38 real icons from Lucide (IconNode imported from the package), Feather and Tabler; per-pair readout of the detected similarity (θ, σ, residual), polar/linear modes for comparison, spring presets and a t scrubber. Feather/Tabler data is extracted from the npm packages with `bun playground/extract-vendor-icons.mjs`.
+
+## Development
+
+```bash
+bun test          # 74 tests / ~13,400 asserts
+bun run typecheck # strict ×3: core+dom without lib DOM, playground, react
+bun run format    # biome
+bun run build     # tsdown → dist/ (entries index, dom, react)
+bun run size      # size gates
+```
+
+Icons shown in the playground belong to their authors: [Lucide](https://lucide.dev) (ISC), [Feather](https://feathericons.com) (MIT), [Tabler](https://tabler.io/icons) (MIT).
+
+---
+
+MIT © [Guillermo](https://guillermolg.com) — made by [guillermolg.com](https://guillermolg.com)

package/dist/dom.d.ts

@@ -0,0 +1,36 @@
+import { c as SpringPreset, n as IconInput } from "./types-JAF3s76Y.js";
+//#region src/dom/index.d.ts
+/** Target element, structurally typed: any object with setAttribute works
+ *  (a real SVGPathElement, or a fake in tests). */
+interface PathEl {
+  setAttribute(name: string, value: string): void;
+}
+/** Morph physics: named preset or custom spring. */
+interface MorphOptions {
+  stiffness?: number;
+  damping?: number;
+}
+interface Morph {
+  /** Animates toward the icon with spring physics. Interruptible: mid-flight
+   *  it re-plans from the intermediate shape while preserving velocity. */
+  morphTo(icon: IconInput, spring?: SpringPreset | MorphOptions): void;
+  /** Jumps to the icon without animating (canonical d, no frames). */
+  set(icon: IconInput): void;
+  /** Renders the morph toward `icon` frozen at t (no spring) — the
+   *  controlled-mode primitive: scrubbing, gestures, scroll. A later
+   *  morphTo takes off from that intermediate shape. */
+  seek(icon: IconInput, t: number): void;
+  /** Current progress (t of the last frame; 1 at rest). Assigning it is
+   *  equivalent to seek(target, t) on the active target. */
+  progress: number;
+  /** Unregisters the instance; later calls are no-ops. */
+  destroy(): void;
+}
+/** Canonical `d` of an icon: the input string verbatim, or the real cubics
+ *  at full precision (the at-rest snap). Exported because it is what a
+ *  binding renders at SSR/rest before any runtime exists. */
+declare function canonicalD(icon: IconInput): string;
+/** Creates the morph instance over a `<path>` and paints the initial icon. */
+declare function createMorph(el: PathEl, icon: IconInput): Morph;
+//#endregion
+export { Morph, MorphOptions, PathEl, canonicalD, createMorph };

package/dist/dom.js

@@ -0,0 +1,192 @@
+import { a as resampleIcon, c as iconToCubics, d as interpPolar, i as serialize, l as allocOutputs, n as Spring, r as cubicsToPathD, s as buildPlan, t as SPRING_PRESETS } from "./spring-Dbj7NCw2.js";
+//#region src/dom/index.ts
+const tickers = /* @__PURE__ */ new Set();
+let rafId = 0;
+let last = -1;
+function loop(ts) {
+	const dt = last < 0 ? 0 : Math.min(Math.max((ts - last) / 1e3, 0), .1);
+	last = ts;
+	for (const tick of [...tickers]) tick(dt);
+	if (tickers.size > 0) rafId = requestAnimationFrame(loop);
+	else {
+		rafId = 0;
+		last = -1;
+	}
+}
+function addTicker(tick) {
+	tickers.add(tick);
+	if (rafId === 0) {
+		last = -1;
+		rafId = requestAnimationFrame(loop);
+	}
+}
+function removeTicker(tick) {
+	tickers.delete(tick);
+	if (tickers.size === 0 && rafId !== 0) {
+		cancelAnimationFrame(rafId);
+		rafId = 0;
+		last = -1;
+	}
+}
+const samples = /* @__PURE__ */ new WeakMap();
+const canon = /* @__PURE__ */ new WeakMap();
+const plans = /* @__PURE__ */ new WeakMap();
+function sampledOf(icon) {
+	if (typeof icon === "string") return resampleIcon(icon);
+	let s = samples.get(icon);
+	if (!s) {
+		s = resampleIcon(icon);
+		samples.set(icon, s);
+	}
+	return s;
+}
+/** Canonical `d` of an icon: the input string verbatim, or the real cubics
+*  at full precision (the at-rest snap). Exported because it is what a
+*  binding renders at SSR/rest before any runtime exists. */
+function canonicalD(icon) {
+	if (typeof icon === "string") return icon;
+	let d = canon.get(icon);
+	if (!d) {
+		d = cubicsToPathD(iconToCubics(icon));
+		canon.set(icon, d);
+	}
+	return d;
+}
+function planBetween(src, dst) {
+	if (typeof src === "string" || typeof dst === "string") return buildPlan(sampledOf(src), sampledOf(dst));
+	let inner = plans.get(src);
+	if (!inner) {
+		inner = /* @__PURE__ */ new WeakMap();
+		plans.set(src, inner);
+	}
+	let p = inner.get(dst);
+	if (!p) {
+		p = buildPlan(sampledOf(src), sampledOf(dst));
+		inner.set(dst, p);
+	}
+	return p;
+}
+function resolveSpring(s) {
+	if (typeof s === "string") return SPRING_PRESETS[s];
+	const d = SPRING_PRESETS.snappy;
+	return {
+		k: s?.stiffness ?? d.k,
+		c: s?.damping ?? d.c
+	};
+}
+/** Creates the morph instance over a `<path>` and paints the initial icon. */
+function createMorph(el, icon) {
+	const spring = new Spring();
+	let target = icon;
+	let rest = true;
+	let plan = null;
+	let out = null;
+	let closed = null;
+	let t = 1;
+	let flying = false;
+	let dead = false;
+	el.setAttribute("d", canonicalD(icon));
+	const render = (tt) => {
+		const p = plan;
+		const o = out;
+		const cl = closed;
+		if (!p || !o || !cl) return;
+		t = tt;
+		interpPolar(p, tt, o);
+		el.setAttribute("d", serialize(o, cl));
+	};
+	const stop = () => {
+		if (!flying) return;
+		flying = false;
+		removeTicker(tick);
+	};
+	const tick = (dt) => {
+		const settled = spring.step(dt);
+		render(spring.x);
+		if (settled) {
+			stop();
+			settle();
+		}
+	};
+	const settle = () => {
+		rest = true;
+		plan = null;
+		out = null;
+		closed = null;
+		t = 1;
+		spring.x = 1;
+		spring.v = 0;
+		el.setAttribute("d", canonicalD(target));
+	};
+	/** The current shape as plan source: the at-rest icon, or the rendered
+	*  buffers (already N points per subpath). */
+	const snapshot = () => {
+		const p = plan;
+		const o = out;
+		if (rest || !p || !o) return sampledOf(target);
+		return o.map((buf, k) => ({
+			pts: Float64Array.from(buf),
+			closed: p.items[k].closed
+		}));
+	};
+	const retarget = (icon) => {
+		plan = rest ? planBetween(target, icon) : buildPlan(snapshot(), sampledOf(icon));
+		out = allocOutputs(plan);
+		closed = plan.items.map((it) => it.closed);
+		target = icon;
+		rest = false;
+	};
+	const setNow = (icon) => {
+		stop();
+		target = icon;
+		settle();
+	};
+	const seek = (icon, tt) => {
+		if (dead) return;
+		const reuse = !rest && plan !== null && icon === target;
+		stop();
+		spring.v = 0;
+		if (!reuse) retarget(icon);
+		render(tt);
+	};
+	return {
+		morphTo(icon, sp) {
+			if (dead) return;
+			if (icon === target && (rest || flying)) return;
+			if (typeof matchMedia !== "undefined") {
+				if (matchMedia?.("(prefers-reduced-motion: reduce)").matches) {
+					setNow(icon);
+					return;
+				}
+			}
+			const { k, c } = resolveSpring(sp);
+			spring.config(k, c);
+			retarget(icon);
+			spring.start();
+			if (!flying) {
+				flying = true;
+				addTicker(tick);
+			}
+		},
+		set(icon) {
+			if (dead) return;
+			setNow(icon);
+		},
+		seek,
+		get progress() {
+			return rest ? 1 : t;
+		},
+		set progress(v) {
+			if (!dead) seek(target, v);
+		},
+		destroy() {
+			stop();
+			dead = true;
+			plan = null;
+			out = null;
+			closed = null;
+		}
+	};
+}
+//#endregion
+export { canonicalD, createMorph };

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+import { a as Sampled, c as SpringPreset, i as IconNodeAttrs, n as IconInput, o as SPRING_PRESETS, r as IconNode, s as Spring, t as CubicPath } from "./types-JAF3s76Y.js";
+//#region src/core/plan.d.ts
+interface PlanItem {
+  /** Points of A with the chosen correspondence (if A is a closed loop it
+   *  may come circularly re-indexed: same points, different cut). */
+  a: Float64Array;
+  /** A centered on its centroid. */
+  aC: Float64Array;
+  /** B brought into A's frame: R(−θ)·(b − c_B)/σ. */
+  bT: Float64Array;
+  /** B oriented, raw (for linear mode and for exact t=1). */
+  bO: Float64Array;
+  ca: readonly [number, number];
+  cb: readonly [number, number];
+  theta: number;
+  lnSigma: number;
+  res: number;
+  /** true if both endpoints are closed loops: the subpath flies with Z.
+   *  Closed → open flies open: the loop opens at the chosen cut. */
+  closed: boolean;
+}
+interface MorphPlan {
+  items: PlanItem[];
+  n: number;
+}
+/** Builds the morph plan between two lists of sampled subpaths. The plan is
+ *  cacheable and serializable; it accepts any list — including intermediate
+ *  shapes (interruptions). */
+declare function buildPlan(srcSubs: readonly Sampled[], dstSubs: readonly Sampled[]): MorphPlan;
+//#endregion
+//#region src/core/interpolate.d.ts
+/** Preallocated output buffers for a plan (zero allocation per frame). */
+declare function allocOutputs(plan: MorphPlan): Float64Array[];
+declare function interpPolar(plan: MorphPlan, t: number, out: Float64Array[]): void;
+/** Raw coordinate lerp (same correspondence, no decomposition). */
+declare function interpLinear(plan: MorphPlan, t: number, out: Float64Array[]): void;
+//#endregion
+//#region src/core/normalize.d.ts
+/** Icon (IconNode or `d` string) → list of cubic subpaths. */
+declare function iconToCubics(input: IconInput): CubicPath[];
+//#endregion
+//#region src/core/resample.d.ts
+/** Samples a cubic subpath at N points equidistant by arc length, anchoring
+ *  corners and endpoints as exact samples. Returns Float64Array(2N). Closed
+ *  paths distribute N intervals around the loop (without duplicating the
+ *  first point); the circular start-point freedom is resolved by the plan's
+ *  circular correspondence. */
+declare function resamplePath(path: CubicPath, N?: number, cornerThreshold?: number): Float64Array;
+/** Full input pipeline: icon → cubics → sampled subpaths with their
+ *  topology (the plan needs to know which subpaths are closed loops). */
+declare function resampleIcon(input: IconInput, N?: number): Sampled[];
+//#endregion
+//#region src/core/serialize.d.ts
+/** Sampled subpaths → polyline `d` attribute. `closed[k]` appends Z to
+ *  subpath k (closed loops in flight); without flags everything is open. */
+declare function serialize(subs: readonly Float64Array[], closed?: readonly boolean[]): string;
+/** Cubic subpaths → canonical `d` at full precision (round-trip). */
+declare function cubicsToPathD(paths: readonly CubicPath[]): string;
+//#endregion
+export { type CubicPath, type IconInput, type IconNode, type IconNodeAttrs, type MorphPlan, type PlanItem, SPRING_PRESETS, type Sampled, Spring, type SpringPreset, allocOutputs, buildPlan, cubicsToPathD, iconToCubics, interpLinear, interpPolar, resampleIcon, resamplePath, serialize };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as resampleIcon, c as iconToCubics, d as interpPolar, i as serialize, l as allocOutputs, n as Spring, o as resamplePath, r as cubicsToPathD, s as buildPlan, t as SPRING_PRESETS, u as interpLinear } from "./spring-Dbj7NCw2.js";
+export { SPRING_PRESETS, Spring, allocOutputs, buildPlan, cubicsToPathD, iconToCubics, interpLinear, interpPolar, resampleIcon, resamplePath, serialize };

package/dist/react.d.ts

@@ -0,0 +1,31 @@
+import { a as Sampled, c as SpringPreset, n as IconInput, r as IconNode } from "./types-JAF3s76Y.js";
+import { Morph, MorphOptions, PathEl } from "./dom.js";
+import { SVGProps } from "react";
+//#region src/react/index.d.ts
+/** Imperative surface exposed via ref. */
+interface MorphHandle {
+  morphTo(icon: IconInput, spring?: SpringPreset | MorphOptions): void;
+  set(icon: IconInput): void;
+}
+interface MorphIconProps extends Omit<SVGProps<SVGSVGElement>, "from" | "to" | "ref"> {
+  /** Uncontrolled mode: the current icon; changing the prop animates. */
+  icon?: IconInput;
+  /** Controlled mode: source endpoint of the pair. */
+  from?: IconInput;
+  /** Controlled mode: target endpoint of the pair. */
+  to?: IconInput;
+  /** Controlled mode: 0..1 progress of the frozen morph (no spring). */
+  progress?: number;
+  /** Physics for uncontrolled/imperative mode: preset or custom spring. */
+  spring?: SpringPreset | MorphOptions;
+  size?: number | string;
+  color?: string;
+  strokeWidth?: number | string;
+  /** Like lucide-react: stroke width does not scale with `size`. */
+  absoluteStrokeWidth?: boolean;
+  /** Accessibility: with label → role="img" + <title>; without → aria-hidden. */
+  label?: string;
+}
+declare const MorphIcon: import("react").ForwardRefExoticComponent<MorphIconProps & import("react").RefAttributes<MorphHandle>>;
+//#endregion
+export { type IconInput, type IconNode, type Morph, MorphHandle, MorphIcon, MorphIconProps, type MorphOptions, type PathEl, type Sampled, type SpringPreset };