morphicons 1.4.1 → 1.5.0

package/README.md

@@ -45,6 +45,8 @@ bun add morphicons        # or npm install / pnpm add
 
 ESM only. `react` (>= 18), `vue` (>= 3.3), `svelte` (>= 5) and `react-native` (>= 0.71) + `react-native-svg` (>= 14) are optional peers — only needed for `morphicons/react`, `morphicons/vue`, `morphicons/svelte` and `morphicons/react-native`.
 
+**Icons come from a data package, not a component package.** morphicons consumes icon *data* (an `IconNode` or a raw `d` string). For Lucide that means the vanilla `lucide` package: `import { Menu, X } from "lucide"` gives you `IconNode`s, which is why every snippet below says "data, not components". The framework packages (`lucide-react`, `lucide-vue-next`, `@lucide/svelte`, `lucide-react-native`) export components, and `MorphIcon` can't consume those. If your app already renders static icons with one of them, keep it: the data and component packages coexist by design and both tree-shake cleanly, so you only pay for the icons you import. Just keep their versions aligned, so the icons you morph match the ones you render statically.
+
 ## Usage
 
 ### React — three modes
@@ -65,7 +67,7 @@ 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.
+Drop-in replacement for lucide-react (the props surface: the `icon` prop takes Lucide *data*, not lucide-react components, see [Install](#install)): `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. Morphs play regardless of the OS reduce-motion setting by default; opt into honoring it with `reducedMotion="user"` (see [Reduced motion](#reduced-motion-all-four-bindings)).
 
 ### Vue — same three modes
 
@@ -118,7 +120,7 @@ Same surface as the React binding: presentation props (`size`, `strokeWidth`, `a
 <MorphIcon bind:this={morph} icon={Menu} />
 ```
 
-Same surface again: presentation props, `class`/`style`/rest-attr fall-through — fully typed via `svelte/elements`, so SVG attrs, events and ARIA autocomplete and typos fail the build, like lucide-svelte — the same accessibility defaults and the same clean SSR — works with SvelteKit out of the box. Svelte 5 (runes); the component ships as `.svelte` source and your bundler compiles it via the `svelte` export condition, like every Svelte library.
+Same surface again: presentation props, `class`/`style`/rest-attr fall-through — fully typed via `svelte/elements`, so SVG attrs, events and ARIA autocomplete and typos fail the build, like lucide-svelte — the same accessibility defaults and the same clean SSR — works with SvelteKit out of the box. Svelte 5 (runes); the component ships as `.svelte` source and your bundler compiles it via the `svelte` export condition, like every Svelte library. If you followed Lucide's official Svelte guide you already have `@lucide/svelte`: keep it for your static icons; `MorphIcon` takes the data exports from the vanilla `lucide` package (see [Install](#install)).
 
 ### React Native — same three modes
 
@@ -139,7 +141,7 @@ ref.current?.morphTo(Check); // animates
 ref.current?.set(X);         // jumps without animating
 ```
 
-The DOM-free core beyond the browser: the dom driver is reused verbatim as the engine (React Native has a global `requestAnimationFrame`, and `PathEl` is structural), so the whole platform difference is a shim that forwards the per-frame `d` write to `Path.setNativeProps` of react-native-svg — outside the React render, exactly like the web mutation. Same surface as the React binding (`size`, `strokeWidth`, `absoluteStrokeWidth`, `color`, plus the native `Svg` props: `testID`, touch handlers…), same accessibility defaults (`aria-hidden` unless you pass `label` → `role="img"` + `aria-label`). Reduced motion comes from `AccessibilityInfo` (best-effort: the query is async; a `reduceMotionChanged` subscription keeps it exact from then on). Requires Metro with package `exports` resolution — default since React Native 0.79; on older versions enable `unstable_enablePackageExports`.
+The DOM-free core beyond the browser: the dom driver is reused verbatim as the engine (React Native has a global `requestAnimationFrame`, and `PathEl` is structural), so the whole platform difference is a shim that forwards the per-frame `d` write to `Path.setNativeProps` of react-native-svg — outside the React render, exactly like the web mutation. Same surface as the React binding (`size`, `strokeWidth`, `absoluteStrokeWidth`, `color`, plus the native `Svg` props: `testID`, touch handlers…), same accessibility defaults (`aria-hidden` unless you pass `label` → `role="img"` + `aria-label`). With `reducedMotion="user"`, the OS setting comes from `AccessibilityInfo` (best-effort: the query is async; a `reduceMotionChanged` subscription keeps it exact from then on). Requires Metro with package `exports` resolution — default since React Native 0.79; on older versions enable `unstable_enablePackageExports`.
 
 ### Lifecycle contract (all four bindings)
 
@@ -149,6 +151,20 @@ The four components share one contract, pinned by mirrored client-mount tests:
 - **Controlled wins.** While `from` AND `to` are both present, the pair owns the path: `icon` changes are ignored, no spring fires. Drop the pair and the current `icon` takes over (animated). Mixing the modes is not an error — the precedence is just explicit.
 - **Clean re-entry.** Any exit from controlled mode (an imperative call or an icon takeover) invalidates the frozen pair, so returning to the same `from`/`to` re-bases on `from` and renders exactly like a clean mount at that `progress`.
 
+### Reduced motion (all four bindings)
+
+Icon morphs are small, short, communicative micro-transitions: the kind of motion the reduce-motion guidance considers generally acceptable, unlike parallax or full-screen movement. Auto-degrading them made the library look broken to every user with the OS setting on, so since 1.4.2 they play by default and the policy is an explicit prop (the same default Motion, formerly Framer Motion, ships):
+
+```tsx
+<MorphIcon icon={open ? X : Menu} reducedMotion="user" />
+```
+
+- `"never"` (default): morphs always animate; the OS setting is ignored.
+- `"user"`: while the OS reduce-motion setting is on, every `morphTo` degrades to an instant swap (the pre-1.4.2 behavior). The web bindings read `prefers-reduced-motion`; React Native reads `AccessibilityInfo`, and only touches the accessibility bridge when some instance opts in.
+- `"always"`: every `morphTo` jumps without animating (tests, screenshots).
+
+The prop is live: changing it governs the next morph. The vanilla driver takes the same policy as an option, `createMorph(el, icon, { reducedMotion: "user" })`, and exposes it as a mutable `morph.reducedMotion`. Apps that must strictly follow the user's system preference should pass `reducedMotion="user"` across the board.
+
 ### Vanilla (no React)
 
 ```ts
@@ -159,6 +175,7 @@ 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.reducedMotion = "user";            // live policy: "never" (default) | "user" | "always"
 m.destroy();
 ```
 
@@ -177,6 +194,42 @@ 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. Tabler, Heroicons, Iconoir and custom paths work the same.
 
+## Format adapters — `morphicons/adapters`
+
+The core has exactly two structural contracts: `IconInput` on the way in (an `IconNode` or a `d` string) and `PathEl` on the way out (anything with `setAttribute` — the same contract that lets the React Native binding drive `setNativeProps`). A **format adapter** converts a foreign icon representation into one of those two contracts. All of them live in one opt-in entry, so the unit of payment is the import: core, driver and bindings never grow for a capability you didn't ask for, and inside the entry each adapter is an independent module — a named import tree-shakes to just that adapter, pinned by per-export size gates in CI. Adapters are per *format*, never per vendor: there is no `/iconify` and never will be.
+
+### `svgToIcon` — SVG markup in
+
+For icons that exist as markup rather than data: an Iconify body from `@iconify-json/*` (what UnoCSS `presetIcons` and the Tailwind icon plugins consume), a full `<svg>` copied from a website, a `<path>` from the shadcn registry. One call turns it into an `IconInput` any entry accepts:
+
+```ts
+import { svgToIcon } from "morphicons/adapters";
+
+// Parse ONCE, at module scope — reuse the reference so the plan cache holds.
+const MENU = svgToIcon(menuBody); // '<path stroke="currentColor" d="M4 5h16…"/>'
+const X = svgToIcon(xBody);       // works in createMorph and all four bindings
+```
+
+Everything else happens under the hood: non-rendered containers (`<defs>`, `<mask>`, `<clipPath>`, `<symbol>`) are stripped, the morphability scan rejects what can't honestly morph (a fill-drawn icon with no stroke — Material Symbols style — a `transform`, an element outside the seven stroke primitives) with a clear error at parse time, and when the markup carries a `viewBox` the geometry is re-gridded onto 24 via [`fitIcon`](#icon-library-compatibility) automatically, so off-grid collections just work.
+
+### `maskTarget` — CSS-mask elements out
+
+For apps that render icons as CSS masks — UnoCSS `presetIcons`, `@iconify/tailwind`, `@egoist/tailwindcss-icons` (`i-lucide-*`, `icon-[lucide-x]`): the icon is a `mask-image` data URI on a `<span>`/`<div>`, with **no `<path>` in the DOM** to write to. `maskTarget` creates a hidden pair of referenced `<svg><mask><path>` buffers once, points the element's mask at them, and hands the driver a `PathEl` whose `d` writes land on that real geometry — so the element morphs in place, keeping your `size-*`/`text-*` classes. Two engine traps shaped this mechanism (see `docs/adr/0002`): a data-URI mask swapped per frame never decodes in time in Chromium (blank flight), and WebKit doesn't repaint when a referenced mask's *content* mutates (frozen flight) — hence the pair: each write flips `mask-image` between the two buffers, which forces re-resolution everywhere.
+
+```ts
+import { maskTarget } from "morphicons/adapters";
+import { createMorph } from "morphicons/dom";
+
+const target = maskTarget(spanEl);     // spanEl: class="size-5 text-current"
+const m = createMorph(target, MENU);
+m.morphTo(X, "snappy");                // full Morph handle: set/seek/progress/destroy
+// on unmount: m.destroy(); target.dispose();
+```
+
+It *is* `createMorph` — only the write target differs — so springs, reduced motion and mid-flight interruption behave identically. On setup it sets `background-color: currentColor`, so a bare `<span>` works with no icon class (`{ paint: false }` keeps an existing `bg-*`; `strokeWidth` and `viewBox` are options). The returned target adds `dispose()` — call it after `morph.destroy()` when the element unmounts, so the hidden mask nodes go with it.
+
+**Cost.** A live inline `<path>` gets the cheapest possible write; a mask element additionally makes the browser re-rasterize the mask and repaint the masked box every frame (main thread, no compositor-only path). Great for toggles and short lists (menu↔close, chevrons, play↔pause); for icon-heavy views, the inline-SVG bindings remain the leanest option — same styling, one less indirection.
+
 ## Icon library compatibility
 
 morphicons has no per-library adapters — any icon set that meets these requirements works out of the box:
@@ -353,12 +406,17 @@ CI budget (size-limit, gzip) as an anti-regression tripwire — gates carry ~10%
 | entry | measured | gate |
 |---|---|---|
 | `morphicons` (core) | 6.60 KB | 7 KB |
-| `morphicons/dom` (core + driver) | 7.04 KB | 7.5 KB |
-| `morphicons/react` (all, react external) | 7.89 KB | 8.5 KB |
-| `morphicons/react-native` (all, react/rn/rnsvg external) | 8.25 KB | 9 KB |
-| `morphicons/vue` (all, vue external) | 7.93 KB | 8.5 KB |
-| `morphicons/svelte` TS half (all, svelte external) | 7.54 KB | 8 KB |
-| `MorphIcon.svelte` (ships as source, consumer-compiled) | 1.25 KB | 1.4 KB |
+| `morphicons/dom` (core + driver) | 7.12 KB | 7.5 KB |
+| `morphicons/adapters` (aggregate — grows by design) | 4.03 KB | 4.4 KB |
+| `adapters` › `{ svgToIcon }` alone | 3.34 KB | 3.7 KB |
+| `adapters` › `{ maskTarget }` alone | 0.70 KB | 0.8 KB |
+| `morphicons/react` (all, react external) | 8.01 KB | 8.5 KB |
+| `morphicons/react-native` (all, react/rn/rnsvg external) | 8.37 KB | 9 KB |
+| `morphicons/vue` (all, vue external) | 8.04 KB | 8.5 KB |
+| `morphicons/svelte` TS half (all, svelte external) | 7.66 KB | 8 KB |
+| `MorphIcon.svelte` (ships as source, consumer-compiled) | 1.26 KB | 1.4 KB |
+
+The adapters entry carries **two kinds of gate**: the aggregate (allowed to grow as adapters are added) and one per named export, which pins each adapter as independently tree-shakeable — if two adapters ever couple, the per-export gate trips in CI. Standalone, `{ svgToIcon }` measures 3.34 KB because auto-fit drags the core's lowering machinery; an app that already imports the core shares that chunk and pays ~0.4 KB incremental.
 
 ## Playground
 

package/dist/MorphIcon.svelte

@@ -25,6 +25,7 @@ let {
   to,
   progress,
   spring,
+  reducedMotion,
   size = 24,
   color = "currentColor",
   strokeWidth = 2,
@@ -40,17 +41,17 @@ const initialD = computeInitialD({ icon, from, to, progress });
 let pathEl: SVGPathElement | undefined = $state();
 // svelte-ignore state_referenced_locally — init-time values on purpose: they
 // seed the controller's watch baselines so the first $effect run is a no-op.
-const ctrl = createController({ icon, from, to, progress });
+const ctrl = createController({ icon, from, to, progress, reducedMotion });
 
 onMount(() => {
-  if (pathEl) ctrl.mount(pathEl, { icon, from, to, progress });
+  if (pathEl) ctrl.mount(pathEl, { icon, from, to, progress, reducedMotion });
   return () => ctrl.destroy();
 });
 
 // Prop changes: one watcher owns the mode logic (controlled wins — change
 // detection and precedence live in shared.ts).
 $effect(() => {
-  const next = { icon, from, to, progress, spring };
+  const next = { icon, from, to, progress, spring, reducedMotion };
   untrack(() => ctrl.watch(next));
 });
 

package/dist/adapters.d.ts

@@ -0,0 +1,55 @@
+import { n as IconInput } from "./types-JAF3s76Y.js";
+import { i as PathEl } from "./index-DXp5b6BU.js";
+//#region src/adapters/mask.d.ts
+/** The subset of an element's inline style the mask target writes — structural
+ *  so a real HTMLElement's `.style` satisfies it (and a test fake supplies
+ *  just these). */
+interface MaskStyle {
+  maskImage: string;
+  webkitMaskImage: string;
+  backgroundColor: string;
+}
+/** An element the mask target can drive (an HTMLElement, or a fake in tests). */
+interface MaskEl {
+  style: MaskStyle;
+}
+interface MaskTargetOptions {
+  /** Stroke width of the mask geometry (Lucide's default is 2). */
+  strokeWidth?: number;
+  /** Grid the icon's coordinates live on (Lucide/Iconify default: "0 0 24 24").
+   *  Used to map the geometry onto the element's box. */
+  viewBox?: string;
+  /** Set `background-color: currentColor` on first setup so the element shows
+   *  through the mask in the current text color, standalone (no icon class).
+   *  Turn off to keep an existing paint (e.g. a `bg-*` utility). Default true. */
+  paint?: boolean;
+}
+/** What `maskTarget` returns: the driver's write contract plus a `dispose`
+ *  that removes the hidden mask node (call it after `morph.destroy()` when
+ *  the element unmounts). */
+interface MaskPathEl extends PathEl {
+  dispose(): void;
+}
+/** Adapts an element into a `PathEl` whose writes drive a referenced SVG
+ *  mask, so `createMorph(maskTarget(el), icon)` animates a mask-styled
+ *  element instead of an inline `<svg><path>`.
+ *
+ *  DOUBLE BUFFER, on purpose: WebKit does not reliably repaint a masked
+ *  element when the CONTENT of its referenced `<mask>` mutates — a lone mask
+ *  whose inner path `d` changes per frame renders frozen in Safari until the
+ *  flight ends. So the target keeps TWO masks and every `d` write lands on
+ *  the back buffer and re-points `mask-image` at it: the property VALUE flips
+ *  (`url(#a)` ↔ `url(#b)`) each frame, which forces reference re-resolution
+ *  in every engine. Chromium/Gecko pay nothing extra for it. */
+declare function maskTarget(el: MaskEl, opts?: MaskTargetOptions): MaskPathEl;
+//#endregion
+//#region src/adapters/svg.d.ts
+/** SVG markup → an IconInput the pipeline can lower. Strips non-rendered
+ *  containers, rejects what can't be honestly morphed (a fill-drawn icon with
+ *  no stroke, a transform, an unsupported element), and re-grids onto 24 via
+ *  the viewBox when one is present — so an off-grid collection lands on the
+ *  shared grid automatically. Returns a `d` (when a viewBox forced a fit) or
+ *  an IconNode. */
+declare function svgToIcon(markup: string): IconInput;
+//#endregion
+export { type MaskEl, type MaskPathEl, type MaskStyle, type MaskTargetOptions, maskTarget, svgToIcon };

package/dist/adapters.js

@@ -0,0 +1,139 @@
+import { t as fitIcon } from "./normalize-CYnN3Npw.js";
+//#region src/adapters/mask.ts
+const SVG_NS = "http://www.w3.org/2000/svg";
+let seq = 0;
+let host = null;
+/** Adapts an element into a `PathEl` whose writes drive a referenced SVG
+*  mask, so `createMorph(maskTarget(el), icon)` animates a mask-styled
+*  element instead of an inline `<svg><path>`.
+*
+*  DOUBLE BUFFER, on purpose: WebKit does not reliably repaint a masked
+*  element when the CONTENT of its referenced `<mask>` mutates — a lone mask
+*  whose inner path `d` changes per frame renders frozen in Safari until the
+*  flight ends. So the target keeps TWO masks and every `d` write lands on
+*  the back buffer and re-points `mask-image` at it: the property VALUE flips
+*  (`url(#a)` ↔ `url(#b)`) each frame, which forces reference re-resolution
+*  in every engine. Chromium/Gecko pay nothing extra for it. */
+function maskTarget(el, opts = {}) {
+	if (typeof document === "undefined") throw new Error("morphicons: maskTarget needs a DOM (client-side only)");
+	const doc = document;
+	if (!host) {
+		host = doc.createElementNS(SVG_NS, "svg");
+		host.setAttribute("width", "0");
+		host.setAttribute("height", "0");
+		host.setAttribute("aria-hidden", "true");
+		host.setAttribute("style", "position:absolute");
+		doc.body.appendChild(host);
+	}
+	const vb = (opts.viewBox ?? "0 0 24 24").trim().split(/[\s,]+/).map(Number);
+	const [mx, my, w, h] = [
+		vb[0] || 0,
+		vb[1] || 0,
+		vb[2] || 24,
+		vb[3] || vb[2] || 24
+	];
+	const makeLayer = () => {
+		const id = `morphicons-mask-${++seq}`;
+		const mask = doc.createElementNS(SVG_NS, "mask");
+		mask.setAttribute("id", id);
+		mask.setAttribute("maskContentUnits", "objectBoundingBox");
+		const g = doc.createElementNS(SVG_NS, "g");
+		g.setAttribute("transform", `scale(${1 / w} ${1 / h}) translate(${-mx} ${-my})`);
+		const path = doc.createElementNS(SVG_NS, "path");
+		path.setAttribute("fill", "none");
+		path.setAttribute("stroke", "#fff");
+		path.setAttribute("stroke-width", String(opts.strokeWidth ?? 2));
+		path.setAttribute("stroke-linecap", "round");
+		path.setAttribute("stroke-linejoin", "round");
+		g.appendChild(path);
+		mask.appendChild(g);
+		if (host) host.appendChild(mask);
+		return {
+			url: `url(#${id})`,
+			mask,
+			path
+		};
+	};
+	const layers = [makeLayer(), makeLayer()];
+	let front = 0;
+	const s = el.style;
+	s.maskImage = s.webkitMaskImage = layers[0].url;
+	if (opts.paint !== false) s.backgroundColor = "currentColor";
+	return {
+		setAttribute(name, d) {
+			if (name !== "d") return;
+			front = 1 - front;
+			const layer = layers[front];
+			layer.path.setAttribute("d", d);
+			s.maskImage = s.webkitMaskImage = layer.url;
+		},
+		dispose() {
+			layers[0].mask.remove();
+			layers[1].mask.remove();
+		}
+	};
+}
+//#endregion
+//#region src/adapters/svg.ts
+const SVG_CONTAINER = /<(defs|mask|clipPath|symbol)\b[^>]*>[\s\S]*?<\/\1>/gi;
+const SVG_ELEMENT = /<([a-zA-Z][\w:-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)\/?>/g;
+const SVG_ATTR = /([\w:-]+)\s*=\s*"([^"]*)"|([\w:-]+)\s*=\s*'([^']*)'/g;
+const SVG_VIEWBOX = /<svg\b[^>]*\bviewBox\s*=\s*["']([^"']+)["']/i;
+const SVG_GEOMETRY = /* @__PURE__ */ new Set([
+	"path",
+	"line",
+	"circle",
+	"ellipse",
+	"rect",
+	"polyline",
+	"polygon"
+]);
+const SVG_SKIP = /* @__PURE__ */ new Set([
+	"svg",
+	"g",
+	"title",
+	"desc",
+	"defs",
+	"mask",
+	"clippath",
+	"symbol"
+]);
+function readSvgAttrs(raw) {
+	const attrs = {};
+	SVG_ATTR.lastIndex = 0;
+	let m;
+	while ((m = SVG_ATTR.exec(raw)) !== null) {
+		const name = m[1] ?? m[3];
+		if (name) attrs[name] = m[2] ?? m[4] ?? "";
+	}
+	return attrs;
+}
+/** SVG markup → an IconInput the pipeline can lower. Strips non-rendered
+*  containers, rejects what can't be honestly morphed (a fill-drawn icon with
+*  no stroke, a transform, an unsupported element), and re-grids onto 24 via
+*  the viewBox when one is present — so an off-grid collection lands on the
+*  shared grid automatically. Returns a `d` (when a viewBox forced a fit) or
+*  an IconNode. */
+function svgToIcon(markup) {
+	if (markup.trimStart().charCodeAt(0) !== 60) throw new Error("morphicons: svgToIcon expects SVG markup — a d string or IconNode is already an IconInput");
+	const body = markup.replace(SVG_CONTAINER, "");
+	const hasStroke = /stroke\s*=\s*["'](?!\s*none\s*["'])/i.test(body);
+	const fillNone = /fill\s*=\s*["']\s*none\s*["']/i.test(body);
+	if (!hasStroke && !fillNone) throw new Error("morphicons: SVG looks fill-drawn (no stroke) — only stroke-centerline icons morph");
+	const node = [];
+	SVG_ELEMENT.lastIndex = 0;
+	let m;
+	while ((m = SVG_ELEMENT.exec(body)) !== null) {
+		const tag = m[1].toLowerCase();
+		if (SVG_SKIP.has(tag)) continue;
+		if (!SVG_GEOMETRY.has(tag)) throw new Error(`morphicons: unsupported SVG element <${tag}>`);
+		const attrs = readSvgAttrs(m[2]);
+		if ("transform" in attrs) throw new Error(`morphicons: <${tag}> has a transform (unsupported)`);
+		node.push([tag, attrs]);
+	}
+	if (node.length === 0) throw new Error("morphicons: no morphable geometry in SVG");
+	const vb = SVG_VIEWBOX.exec(markup);
+	return vb ? fitIcon(node, vb[1]) : node;
+}
+//#endregion
+export { maskTarget, svgToIcon };

package/dist/dom.d.ts

@@ -1,37 +1,2 @@
-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
- *  quantized to 4 decimals (the at-rest snap; engine-stable bytes so SSR
- *  hydration matches, see fmtCanon in core/serialize). 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 };
+import { a as ReducedMotionMode, i as PathEl, n as Morph, o as canonicalD, r as MorphOptions, s as createMorph, t as CreateMorphOptions } from "./index-DXp5b6BU.js";
+export { CreateMorphOptions, Morph, MorphOptions, PathEl, ReducedMotionMode, canonicalD, createMorph };

package/dist/dom.js

@@ -1,4 +1,5 @@
-import { a as buildPlan, c as cubicsToPathD, f as interpPolar, l as serialize, n as Spring, r as resampleIcon, s as iconToCubics, t as SPRING_PRESETS, u as allocOutputs } from "./spring-CBynweFS.js";
+import { a as buildPlan, c as interpPolar, n as Spring, o as allocOutputs, r as resampleIcon, t as SPRING_PRESETS } from "./spring-CFHloqPP.js";
+import { i as serialize, n as iconToCubics, r as cubicsToPathD } from "./normalize-CYnN3Npw.js";
 //#region src/dom/index.ts
 const tickers = /* @__PURE__ */ new Set();
 let rafId = 0;
@@ -76,8 +77,9 @@ function resolveSpring(s) {
 	};
 }
 /** Creates the morph instance over a `<path>` and paints the initial icon. */
-function createMorph(el, icon) {
+function createMorph(el, icon, options) {
 	const spring = new Spring();
+	let reducedMotion = options?.reducedMotion ?? "never";
 	let target = icon;
 	let rest = true;
 	let plan = null;
@@ -142,6 +144,13 @@ function createMorph(el, icon) {
 		target = icon;
 		settle();
 	};
+	/** True when the policy says this morphTo must jump instead of flying. */
+	const motionOff = () => {
+		if (reducedMotion === "always") return true;
+		if (reducedMotion !== "user") return false;
+		if (typeof matchMedia === "undefined") return false;
+		return matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+	};
 	const seek = (icon, tt) => {
 		if (dead) return;
 		const reuse = !rest && plan !== null && icon === target;
@@ -154,11 +163,9 @@ function createMorph(el, icon) {
 		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;
-				}
+			if (motionOff()) {
+				setNow(icon);
+				return;
 			}
 			const { k, c } = resolveSpring(sp);
 			spring.config(k, c);
@@ -180,6 +187,12 @@ function createMorph(el, icon) {
 		set progress(v) {
 			if (!dead) seek(target, v);
 		},
+		get reducedMotion() {
+			return reducedMotion;
+		},
+		set reducedMotion(v) {
+			reducedMotion = v;
+		},
 		destroy() {
 			stop();
 			dead = true;

package/dist/index-DXp5b6BU.d.ts

@@ -0,0 +1,48 @@
+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;
+}
+/** Reduced-motion policy. `"never"` (default): morphs always animate,
+ *  ignoring the OS setting. `"user"`: while the OS reduce-motion setting is
+ *  on, `morphTo` degrades to an instant `set`. `"always"`: every `morphTo`
+ *  jumps (tests, screenshots). */
+type ReducedMotionMode = "never" | "user" | "always";
+interface CreateMorphOptions {
+  /** Reduced-motion policy; also live via the `reducedMotion` property. */
+  reducedMotion?: ReducedMotionMode;
+}
+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;
+  /** Reduced-motion policy, live: assigning it applies to the next morphTo. */
+  reducedMotion: ReducedMotionMode;
+  /** Unregisters the instance; later calls are no-ops. */
+  destroy(): void;
+}
+/** Canonical `d` of an icon: the input string verbatim, or the real cubics
+ *  quantized to 4 decimals (the at-rest snap; engine-stable bytes so SSR
+ *  hydration matches, see fmtCanon in core/serialize). 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, options?: CreateMorphOptions): Morph;
+//#endregion
+export { ReducedMotionMode as a, PathEl as i, Morph as n, canonicalD as o, MorphOptions as r, createMorph as s, CreateMorphOptions as t };

package/dist/index.js

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