morphico 0.3.0 → 0.5.0

package/README.md

@@ -11,64 +11,85 @@ npm install morphico
 ```
 
 ```ts
-import { icon, text } from 'morphico';
+import { icon, text, clip, face } from 'morphico';
+import { digitsRound } from 'morphico/sets/round';     // every set is its own import
+import { iconsWeather } from 'morphico/sets/weather';
 ```
 
-Or from a CDN, as a classic script with the global `morphico`:
+Every set is a separate file, so a bundler (Vite, webpack, esbuild, Rollup …) only ships the sets and functions a
+page uses — e.g. `icon()` with one icon set is about 13–21 KB gzipped, everything about 63 KB. `clip()` and `face()`
+bring their own shapes / expressions. To pick sets by name at run time, `import { iconSets } from 'morphico/all'`
+(`iconSets.weather` …; this imports every set).
+
+Or from a CDN, as a classic script with the global `morphico` — one file with everything, sets by name in
+`morphico.iconSets`:
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/morphico"></script>
 <script>
-  const { icon, text, clip } = morphico;
+  const { icon, text, clip, face, iconSets } = morphico;
+  icon(document.querySelector('#weather'), 'sunny', { set: iconSets.weather });
 </script>
 ```
 
-## One icon: `icon(element, options)`
+Every layer is created the same way — `layer(element, init, options)`: the element to draw into, what it shows
+first, and the settings — and changes with `to()`, which returns a promise. `destroy()` removes it.
+
+## One icon: `icon(element, init, options)`
 
 ```ts
-const digit = icon(document.querySelector('#digit'), { state: '4' });
+import { icon } from 'morphico';
+import { digitsRound } from 'morphico/sets/round';
+
+const digit = icon(document.querySelector('#digit'), '4', { set: digitsRound });
 
 await digit.to('7');                          // the promise resolves when the morph ends
 digit.to('8', { onEnd: (result) => {} });     // or pass a callback
 digit.destroy();                              // stops and removes it (e.g. when a component unmounts)
 ```
 
-States of the digit sets: `'0'`…`'9'`, `'-'` `'/'` `'.'` `','` `':'`, and `' '` (empty: nothing drawn, shapes grow
+Digit sets: `digitsRound` (`morphico/sets/round`), `digitsSquare` (`/square`), `digitsCondensed` (`/condensed`),
+`digitsSlim` (`/slim`), `digitsHandwritten` (`/handwritten`). Their states: `'0'`…`'9'`, `'-'` `'/'` `'.'` `','` `':'`, and `' '` (empty: nothing drawn, shapes grow
 out of it and fade). A digit morphing into `-` `/` `.` `,` is pressed flat onto it; into `:` it splits into the two dots.
 
 Icon sets (based on [Lucide](https://lucide.dev)):
 
-| Set | States |
+| Import from `morphico/sets/…` | States |
 | --- | --- |
-| `media` | `play`, `pause`, `stop` |
-| `menu` | `menu` (☰), `close` (✕), `back` (←) |
-| `checkbox` | `unchecked` (☐), `checked` (☑), `checked-big` (✓ breaking out of the box) |
-| `radio` | `unchecked` (○), `checked` (✓ in a circle), `checked-big` (✓ breaking out of the circle) |
-| `folder` | `closed`, `open` |
-| `theme` | `light` (sun), `dark` (moon) |
-| `weather` | `sunny`, `frosty`, `partly-cloudy`, `showers`, `cloudy`, `thunder`, `rain`, `snow`, `drizzle` |
-| `eye` | `visible`, `hidden` (slashed) |
-| `volume` | `muted` (✕), `low` (no waves), `medium`, `high` |
-| `toggle` | `plus`, `minus`, `close` (✕), `check` |
-| `lock` | `locked`, `unlocked` |
-| `bell` | `on`, `off` (slashed) |
-| `mic` | `on`, `off` (slashed) |
-| `chevron` | `up`, `right`, `down`, `left` |
-| `copy` | `copy`, `copied` (✓) |
-| `wifi` | `none`, `low`, `medium`, `high` |
-| `battery` | `empty`, `low`, `medium`, `full` |
+| `media` → `iconsMedia` | `play`, `pause`, `stop` |
+| `menu` → `iconsMenu` | `menu` (☰), `close` (✕), `back` (←) |
+| `checkbox` → `iconsCheckbox` | `unchecked` (☐), `checked` (☑), `checked-big` (✓ breaking out of the box) |
+| `radio` → `iconsRadio` | `unchecked` (○), `checked` (✓ in a circle), `checked-big` (✓ breaking out of the circle) |
+| `folder` → `iconsFolder` | `closed`, `open` |
+| `theme` → `iconsTheme` | `light` (sun), `dark` (moon) |
+| `weather` → `iconsWeather` | `sunny`, `frosty`, `partly-cloudy`, `showers`, `cloudy`, `thunder`, `rain`, `snow`, `drizzle` |
+| `eye` → `iconsEye` | `visible`, `hidden` (slashed) |
+| `volume` → `iconsVolume` | `muted` (✕), `low` (no waves), `medium`, `high` |
+| `toggle` → `iconsToggle` | `plus`, `minus`, `close` (✕), `check` |
+| `lock` → `iconsLock` | `locked`, `unlocked` |
+| `bell` → `iconsBell` | `on`, `off` (slashed) |
+| `mic` → `iconsMic` | `on`, `off` (slashed) |
+| `chevron` → `iconsChevron` | `up`, `right`, `down`, `left` |
+| `copy` → `iconsCopy` | `copy`, `copied` (✓) |
+| `wifi` → `iconsWifi` | `none`, `low`, `medium`, `high` |
+| `battery` → `iconsBattery` | `empty`, `low`, `medium`, `full` |
 
 ```ts
-const player = icon(button, { set: 'media', state: 'play' });
+import { iconsMedia } from 'morphico/sets/media';
+
+const player = icon(button, 'play', { set: iconsMedia });
 player.to('pause');
 ```
 
-## A line of characters: `text(element, options)`
+## A line of characters: `text(element, init, options)`
 
 ```ts
-const clock = text(document.querySelector('#clock'), { value: '04:59' });
+import { text } from 'morphico';
+import { digitsRound } from 'morphico/sets/round';
+
+const clock = text(document.querySelector('#clock'), '04:59', { set: digitsRound });
 
-clock.set('05:00');   // only the digits that changed morph
+await clock.to('05:00');   // only the digits that changed morph
 clock.destroy();
 ```
 
@@ -76,49 +97,85 @@ clock.destroy();
   **Any other character is removed** (with the regex `/[^0-9 :.,\/-]/g`): `'12:09 AM'` shows `12:09 `.
 - Cells: digits, space and `-` have one width, `:` `.` `,` half of it, `/` 0.7 of it. A change morphs when the length
   and every cell's width stay the same (`5` ↔ `-`, `.` ↔ `,`); otherwise the line is rebuilt without animation
-  (`5` ↔ `:`). Pad counters with spaces to keep them morphing: `counter.set(String(count).padStart(3, ' '))`.
+  (`5` ↔ `:`). Pad counters with spaces to keep them morphing: `counter.to(String(count).padStart(3, ' '))`.
 - Digits sit on the text baseline, and every cell has the same width, so clocks don't jiggle.
 
-## A cut-out: `clip(element, options)`
+## A cut-out: `clip(element, init, options)`
 
 Cuts any element (an `<img>`, a `<div>`, a `<main>` …) out by a shape, and morphs, moves, resizes and turns it.
 
 ```ts
-const photo = clip(document.querySelector('#photo'), { state: 'star', x: 50, y: 50, size: '80%' });
+const photo = clip(document.querySelector('#photo'), 'star', { x: 50, y: 50, size: '80%' });
 
 await photo.to('heart');                                  // morph
 photo.to('shield', { rotation: 360, x: 30, size: '120px' }); // morph + turn + move together
 photo.to({ x: 70, y: '150px' });                          // move only, the shape stays
-photo.set({ rotation: 15 });                              // jump, no animation (e.g. while dragging a slider)
-photo.set({ outline: { width: 16 } });                    // only a 16 px band along the edge shows
+photo.to({ rotation: 15, duration: 0 });                  // jump, no animation (e.g. while dragging a slider)
+photo.to({ outline: { width: 16 } });                     // only a 16 px band along the edge shows
+photo.to({ inverted: true });                             // the other way round: the shape is a hole
 photo.destroy();                                          // the element is whole again
 ```
 
 Shapes (based on [Lucide](https://lucide.dev)): `circle`, `ellipse`, `heart`, `sparkle`, `astroid`, `bookmark`,
 `shield`, `moon`, `tag`, `square`, `badge`, `triangle`, `droplet`, `pentagon`, `hexagon`, `octagon`, `squircle`,
-`star`, `rectangle-horizontal`, `rectangle-vertical`, `message-circle`, `message-square`, `diamond`, `cloud`, `puzzle`.
+`star`, `rectangle-horizontal`, `message-circle`, `message-square`, `cloud`, `puzzle`, `club`. A diamond is the `square`
+turned 45°, a portrait rectangle `rectangle-horizontal` turned 90° (`rotation`).
 
 | Option | Default | |
 | --- | --- | --- |
-| `state` | `'circle'` | The shape |
 | `x`, `y` | `50` | The shape's **centre**. A number is %, or a string `'40%'` / `'120px'` (% of the element's width for `x`, height for `y`) |
 | `size` | fits | The side of the shape's square (% of the element's width, or px). The shape keeps its own proportions inside that square. Default: the largest square that fits the element |
 | `rotation` | `0` | Degrees, clockwise, **absolute**: `rotation: 360` ends one full turn from 0. The shape turns rigidly, also in a wide or tall element |
 | `roundness` | `1` | Corners: `0` = sharp … `1` = the shape's own (the maximum) |
 | `outline` | `false` | `{ width, band }`: only a band of `width` px along the edge shows; `band`: `'inside'` (default), `'centre'` or `'outside'` the edge. Not animated |
+| `inverted` | `false` | `true`: the other way round — the shape (or band) is a hole, the rest of the element shows. Not animated |
 | `duration`, `easing` | `400`, `'easeInOutCubic'` | As for icons; also per `to()` call |
 
-Everything except `outline` animates together in `to()`. How it works: a filled shape uses CSS `clip-path: url(#…)`,
+Everything except `outline` and `inverted` (they switch at once) animates together in `to()`; `duration: 0` jumps. How it works: a filled shape uses CSS `clip-path: url(#…)`,
 an outlined one `mask: url(#…)` (clip-path has no line width); the `<clipPath>` / `<mask>` sit in a small hidden
 `<svg>` that `clip()` adds to the page. It follows the element's size (`ResizeObserver`). Overflow beyond the element is
 cut off, as with any clip-path.
 
+## A face: `face(element, init, options)`
+
+A face of 7 soft pieces — 2 brows, 2 eyes, 2 pupils and a mouth — that morphs between feelings and blinks.
+
+```html
+<div id="robot" style="width: 160px; height: 160px; border-radius: 50%; background: #e4e2d6; color: #8b8e8e"></div>
+```
+
+```ts
+import { face } from 'morphico';
+
+const robot = face(document.querySelector('#robot'), 'normal');
+
+await robot.to('smiling');                    // morph
+robot.to('angry', { duration: 300 });
+robot.blink();                                // close and open the eyes once, on top of any expression
+robot.destroy();                              // removes the face, stops blinking
+```
+
+Expressions: `normal`, `smiling`, `pleading`, `wonder`, `focused`, `fright`, `angry`, `asleep`, `sad`,
+`surprised`, `laughing`, `tired`, `wink-left`, `wink-right`, `suspicious`, `confused`, `smug`, `irritated`,
+`bored`, `curious`, `empathetic`, `guilty`, `worried`, `disappointed`, `ashamed`, `embarrassed`, `yearning`,
+`triumphant`, `proud`, `excited`, `scornful`, `disgusted` (also exported as `faceExpressionNames`). Any one
+morphs into any other. `wink-left` / `wink-right` = the eye that closes, as seen.
+
+| Option | Default | |
+| --- | --- | --- |
+| `pupilColor` | `'white'` | Colour of the pupils. Brows, eyes and mouth take the CSS `color` |
+| `blink` | `true` | Blink by itself every few seconds |
+| `size` | `'100%'` | CSS width and height of the face (by default it fills the element) |
+| `duration`, `easing` | `500`, `'easeInOutCubic'` | As for icons; also per `to()` call |
+
+The face draws no background: a disc, card or anything else behind it is the element's own CSS. The pupils only show
+inside the eyes (an eyelid covers them). With reduced motion the face changes without animation and doesn't blink.
+
 ## Options
 
 | Option | For | Default | |
 | --- | --- | --- | --- |
-| `set` | both | `'round'` | digits: `'round'`, `'square'`, `'condensed'`, `'slim'`, `'handwritten'`; icons (`icon()` only): `'media'`, `'menu'`, `'checkbox'`, `'radio'`, `'folder'`, `'theme'`, `'weather'`, `'eye'`, `'volume'`, `'toggle'`, `'lock'`, `'bell'`, `'mic'`, `'chevron'`, `'copy'`, `'wifi'`, `'battery'` |
-| `state` / `value` | icon / text | empty | What is shown first |
+| `set` | both | **required** | A set object: a digit set (`digitsRound` …) for `text()`, any set for `icon()` — see above |
 | `size` | both | `'1em'` | CSS size (icon: width and height; text: height). `1em` follows the font size |
 | `duration` | both | `400` | Milliseconds |
 | `easing` | both | `'easeInOutCubic'` | `'linear'`, `'easeInOutCubic'`, `'easeOutBack'`, `'easeOutElastic'`, or a function `(progress) => easedProgress` |
@@ -130,17 +187,17 @@ cut off, as with any clip-path.
 | `cellWidth` | text | per set | Width of a digit cell in grid units (a digit is 16 high) |
 | `spacing` | text | per set | Gap between cells in grid units |
 
-`duration` and `easing` can also be passed to a single `to()` / `set()` call.
+`duration` and `easing` can also be passed to a single `to()` call.
 
 ## Behaviour
 
 - **Colour** comes from the CSS `color` (`currentColor`).
 - **Spacing** can be set in CSS too: `--morphico-spacing: 0.15em`.
-- **Interrupting:** calling `to()` / `set()` during a morph starts the new morph from the shape on screen.
+- **Interrupting:** calling `to()` during a morph starts the new morph from the shape on screen.
   The earlier promise resolves with `{ interrupted: true }`; promises never stay pending.
 - **Reduced motion:** when the user's system asks for reduced motion, shapes change without animation.
 - **Accessibility:** the icon / line has `role="img"` and an `aria-label` with the current value.
-- **Server-side rendering:** importing does not touch the DOM; only `icon()` / `text()` / `clip()` do.
+- **Server-side rendering:** importing does not touch the DOM; only `icon()` / `text()` / `clip()` / `face()` do.
 
 ## Development
 

package/dist/esm/all.js

@@ -0,0 +1,50 @@
+/*! morphico v0.5.0 | MIT License, Copyright (c) 2026 Raycho Ivanov (see LICENSE) */
+// Every built-in set by name — `import { iconSets } from 'morphico/all'` (and `morphico.iconSets` in the classic script).
+// Imports every set: for pages that pick sets at run time. Others import single sets (`morphico/sets/<name>`), so a
+// bundler only keeps those.
+import { iconsCheckbox } from './sets/checkbox.js';
+import { digitsCondensed } from './sets/condensed.js';
+import { iconsFolder } from './sets/folder.js';
+import { digitsHandwritten } from './sets/handwritten.js';
+import { iconsMedia } from './sets/media.js';
+import { iconsRadio } from './sets/radio.js';
+import { iconsMenu } from './sets/menu.js';
+import { digitsRound } from './sets/round.js';
+import { digitsSlim } from './sets/slim.js';
+import { digitsSquare } from './sets/square.js';
+import { iconsTheme } from './sets/theme.js';
+import { iconsWeather } from './sets/weather.js';
+import { iconsEye } from './sets/eye.js';
+import { iconsVolume } from './sets/volume.js';
+import { iconsToggle } from './sets/toggle.js';
+import { iconsLock } from './sets/lock.js';
+import { iconsBell } from './sets/bell.js';
+import { iconsMic } from './sets/mic.js';
+import { iconsChevron } from './sets/chevron.js';
+import { iconsCopy } from './sets/copy.js';
+import { iconsWifi } from './sets/wifi.js';
+import { iconsBattery } from './sets/battery.js';
+export const iconSets = {
+    round: digitsRound,
+    square: digitsSquare,
+    condensed: digitsCondensed,
+    slim: digitsSlim,
+    handwritten: digitsHandwritten,
+    media: iconsMedia,
+    menu: iconsMenu,
+    checkbox: iconsCheckbox,
+    radio: iconsRadio,
+    folder: iconsFolder,
+    theme: iconsTheme,
+    weather: iconsWeather,
+    eye: iconsEye,
+    volume: iconsVolume,
+    toggle: iconsToggle,
+    lock: iconsLock,
+    bell: iconsBell,
+    mic: iconsMic,
+    chevron: iconsChevron,
+    copy: iconsCopy,
+    wifi: iconsWifi,
+    battery: iconsBattery,
+};

package/dist/esm/clip.js

@@ -0,0 +1,283 @@
+/*! morphico v0.5.0 | MIT License, Copyright (c) 2026 Raycho Ivanov (see LICENSE) */
+// Layer 3: an element cut out by a morphing shape (a star, a heart, a speech bubble …), e.g. a photo or a card.
+// The shape is square (1:1), placed by its centre (x, y) and size in % or px of the element, can be turned and
+// outlined (only a band along its edge shows). Filled → CSS `clip-path: url(#id)`; outlined → `mask: url(#id)`
+// (clip-path ignores line width). The <clipPath> / <mask> live in one hidden <svg> per clip.
+import { animate, easings } from './engine.js';
+import { interpolate, pieceLengthOf, shapeForPair, toPathData } from './geometry.js';
+import { checkedInit, resolveIconSet } from './roundness.js';
+import { clampToUnit, DEFAULT_DURATION, prefersReducedMotion, shapesOf } from './morph.js';
+import { clipShapes } from './sets/shapes.js';
+import { createSvgElement } from './svg.js';
+const GRID_SIZE = 24;
+const GRID_CENTER = 12;
+const DEGREE = Math.PI / 180;
+/** Masks and their clip regions reach far past the element, so bands and turned shapes are never cut by them. */
+const FAR = 100000;
+/** In objectBoundingBox units (1 = the element's width / height): far around the element. */
+const INVERTED_SURROUNDING = 'M-1000 -1000H1001V1001H-1000Z';
+let clipCount = 0;
+const lengthToPixels = (length, reference, name) => {
+    if (typeof length === 'number' && Number.isFinite(length))
+        return (length / 100) * reference;
+    const match = typeof length === 'string' ? /^\s*(-?[\d.]+(?:e[-+]?\d+)?)\s*(px|%)\s*$/i.exec(length) : null;
+    if (!match)
+        throw new Error(`morphico: ${name} "${length}" is not a length — use a number (= %), '40%' or '120px'`);
+    const value = Number(match[1]);
+    return match[2] === 'px' ? value : (value / 100) * reference;
+};
+const checkedOutline = (outline) => {
+    if (!outline)
+        return false;
+    if (!(outline.width > 0))
+        throw new Error('morphico: outline.width must be a number of px above 0');
+    if (outline.band && !['inside', 'centre', 'outside'].includes(outline.band)) {
+        throw new Error(`morphico: outline.band "${outline.band}" — use 'inside', 'centre' or 'outside'`);
+    }
+    return outline;
+};
+/** Cuts `element` out by a morphing shape, `init` first. */
+export const clip = (element, init, options = {}) => {
+    const { set = clipShapes, x = 50, y = 50, size, rotation = 0, roundness = 1, outline = false, inverted = false, ...defaultMorphOptions } = options;
+    const checkedState = (shapeSet, state) => {
+        if (!(state in shapeSet.strokes)) {
+            throw new Error(`morphico: unknown shape "${state}" (known: ${Object.keys(shapeSet.strokes).join(', ')})`);
+        }
+        return state;
+    };
+    for (const [name, length] of [['x', x], ['y', y], ['size', size]]) {
+        if (length !== undefined)
+            lengthToPixels(length, 1, name);
+    }
+    /** Where the change goes (or what shows when nothing moves). */
+    const target = {
+        state: checkedState(set, checkedInit(init, 'clip')), set: resolveIconSet(set, roundness), roundness,
+        x, y, size, rotation, outline: checkedOutline(outline), inverted,
+    };
+    const pieceLength = pieceLengthOf(set);
+    let frame = null; // null = resting at the target
+    let running = null;
+    let elementWidth = 0, elementHeight = 0;
+    // ---- the hidden <svg> with the <clipPath> (filled) and the <mask> (outlined) ----
+    const id = `morphico-clip-${++clipCount}`;
+    const svg = createSvgElement('svg', { width: 0, height: 0, 'aria-hidden': 'true', focusable: 'false' });
+    svg.style.position = 'absolute';
+    svg.style.pointerEvents = 'none';
+    const clipPathElement = svg.appendChild(createSvgElement('clipPath', { id: `${id}-shape`, clipPathUnits: 'objectBoundingBox' }));
+    const clipShape = clipPathElement.appendChild(createSvgElement('path'));
+    const farRegion = { maskUnits: 'userSpaceOnUse', x: -FAR, y: -FAR, width: 2 * FAR, height: 2 * FAR };
+    const maskElement = svg.appendChild(createSvgElement('mask', { id: `${id}-band`, ...farRegion }));
+    /** Every path drawn in element pixels for the outlined band (the band itself and its helpers). */
+    let bandPaths = [];
+    const buildBand = () => {
+        for (const helper of svg.querySelectorAll('.morphico-band-helper'))
+            helper.remove();
+        maskElement.replaceChildren();
+        bandPaths = [];
+        clipShape.setAttribute('clip-rule', target.inverted ? 'evenodd' : 'nonzero');
+        if (!target.outline)
+            return;
+        const { width, band = 'inside' } = target.outline;
+        // inverted: everything shows (white), the band is the hole (black)
+        const bandColor = target.inverted ? 'black' : 'white';
+        if (target.inverted) {
+            maskElement.append(createSvgElement('rect', { x: -FAR, y: -FAR, width: 2 * FAR, height: 2 * FAR, fill: 'white' }));
+        }
+        const pixelPath = (attributes) => {
+            const path = createSvgElement('path', attributes);
+            bandPaths.push(path);
+            return path;
+        };
+        // inside = a line twice as wide, clipped to the shape; outside = a line twice as wide, the shape cut out of it
+        const edgeLine = (lineWidth) => pixelPath({ fill: 'none', stroke: bandColor, 'stroke-width': lineWidth, 'stroke-linejoin': 'miter' });
+        if (band === 'centre') {
+            maskElement.append(edgeLine(width));
+        }
+        else if (band === 'inside') {
+            const insideClip = createSvgElement('clipPath', { id: `${id}-inside`, class: 'morphico-band-helper' });
+            insideClip.append(pixelPath({}));
+            svg.append(insideClip);
+            const line = edgeLine(2 * width);
+            line.setAttribute('clip-path', `url(#${id}-inside)`);
+            maskElement.append(line);
+        }
+        else {
+            // painting black over the inside would only work for luminance masks; a mask cut out of the line works for both
+            const outsideMask = createSvgElement('mask', { id: `${id}-outside`, class: 'morphico-band-helper', ...farRegion });
+            outsideMask.append(createSvgElement('rect', { x: -FAR, y: -FAR, width: 2 * FAR, height: 2 * FAR, fill: 'white' }), pixelPath({ fill: 'black' }));
+            svg.append(outsideMask);
+            const line = edgeLine(2 * width);
+            line.setAttribute('mask', `url(#${id}-outside)`);
+            maskElement.append(line);
+        }
+    };
+    const ownClipPath = element.style.clipPath;
+    const ownMask = element.style.mask;
+    const applyStyle = () => {
+        const mask = target.outline ? `url(#${id}-band)` : ownMask;
+        element.style.clipPath = target.outline ? ownClipPath : `url(#${id}-shape)`;
+        element.style.mask = mask;
+        element.style.setProperty('-webkit-mask', mask);
+    };
+    // ---- placement and drawing ----
+    const restingPlacement = () => ({
+        centerX: lengthToPixels(target.x, elementWidth, 'x'),
+        centerY: lengthToPixels(target.y, elementHeight, 'y'),
+        side: target.size === undefined ? Math.min(elementWidth, elementHeight) : lengthToPixels(target.size, elementWidth, 'size'),
+    });
+    const restingFrame = () => ({ shape: shapesOf(target.set)[target.state], rotation: target.rotation, placement: restingPlacement() });
+    /** The shape in element pixels: scaled to its square, turned around the square's centre, moved into place. */
+    const toElementPixels = ({ shape, rotation: angle, placement: { centerX, centerY, side } }) => {
+        const scale = side / GRID_SIZE;
+        const cos = Math.cos(angle * DEGREE), sin = Math.sin(angle * DEGREE);
+        const pixels = [];
+        for (let index = 0; index < shape.length; index += 2) {
+            const offsetX = (shape[index] - GRID_CENTER) * scale, offsetY = (shape[index + 1] - GRID_CENTER) * scale;
+            pixels.push(centerX + offsetX * cos - offsetY * sin, centerY + offsetX * sin + offsetY * cos);
+        }
+        return pixels;
+    };
+    const render = () => {
+        if (!elementWidth || !elementHeight)
+            return;
+        const pixels = toElementPixels(frame ?? restingFrame());
+        if (target.outline) {
+            const pathData = toPathData(pixels, pieceLength);
+            for (const path of bandPaths)
+                path.setAttribute('d', pathData);
+        }
+        else {
+            // objectBoundingBox: 0…1 of the element's width / height
+            const boxUnits = pixels.map((value, index) => value / (index % 2 ? elementHeight : elementWidth));
+            // inverted: a rectangle far around the element with the shape as a hole in it (clip-rule evenodd)
+            const surrounding = target.inverted ? INVERTED_SURROUNDING : '';
+            clipShape.setAttribute('d', surrounding + toPathData(boxUnits, pieceLength));
+        }
+    };
+    const measure = (width, height) => {
+        elementWidth = width;
+        elementHeight = height;
+        render();
+    };
+    // ---- changes ----
+    /** Ends the running change and resolves everyone waiting for it. */
+    const finish = (interrupted) => {
+        if (!running)
+            return;
+        const { stopAnimation, resolvers } = running;
+        running = null;
+        stopAnimation();
+        for (const resolve of resolvers)
+            resolve({ state: target.state, interrupted });
+    };
+    /** Updates the target (checked first, so a wrong value throws right away, not in an animation frame). */
+    const applyChanges = (changes) => {
+        for (const name of ['x', 'y', 'size']) {
+            if (changes[name] !== undefined)
+                lengthToPixels(changes[name], 1, name);
+        }
+        if (changes.state !== undefined)
+            target.state = checkedState(target.set, changes.state);
+        if (changes.roundness !== undefined && changes.roundness !== target.roundness) {
+            target.roundness = changes.roundness;
+            target.set = resolveIconSet(set, changes.roundness);
+        }
+        if (changes.x !== undefined)
+            target.x = changes.x;
+        if (changes.y !== undefined)
+            target.y = changes.y;
+        if (changes.size !== undefined)
+            target.size = changes.size;
+        if (changes.rotation !== undefined)
+            target.rotation = changes.rotation;
+        if (changes.outline !== undefined || changes.inverted !== undefined) {
+            if (changes.outline !== undefined)
+                target.outline = checkedOutline(changes.outline);
+            if (changes.inverted !== undefined)
+                target.inverted = changes.inverted;
+            buildBand();
+            applyStyle();
+        }
+    };
+    const change = (changes, morphOptions) => {
+        const settled = !running;
+        finish(true);
+        const previous = { state: target.state, set: target.set };
+        const from = frame ?? restingFrame();
+        applyChanges(changes);
+        const { duration = DEFAULT_DURATION, easing = 'easeInOutCubic' } = morphOptions;
+        if (duration <= 0 || prefersReducedMotion() || !elementWidth || !elementHeight) {
+            frame = null;
+            render();
+            return Promise.resolve({ state: target.state, interrupted: false });
+        }
+        // settled: both sides use the pair's layouts; interrupted: start from the shape on screen
+        const fromShape = settled
+            ? shapeForPair(previous.set, shapesOf(previous.set), previous.state, target.state) : from.shape;
+        const toShape = shapeForPair(target.set, shapesOf(target.set), target.state, previous.state);
+        const to = restingPlacement();
+        const ease = typeof easing === 'function' ? easing : easings[easing];
+        const startTime = performance.now();
+        return new Promise((resolve) => {
+            const stopAnimation = animate((frameTime) => {
+                const progress = clampToUnit((frameTime - startTime) / duration);
+                if (progress >= 1) {
+                    frame = null;
+                    render();
+                    finish(false);
+                    return false;
+                }
+                const easedProgress = ease(progress);
+                const between = (start, end) => start + (end - start) * easedProgress;
+                frame = {
+                    shape: interpolate(fromShape, toShape, easedProgress),
+                    rotation: between(from.rotation, target.rotation),
+                    placement: {
+                        centerX: between(from.placement.centerX, to.centerX),
+                        centerY: between(from.placement.centerY, to.centerY),
+                        side: between(from.placement.side, to.side),
+                    },
+                };
+                render();
+                return true;
+            });
+            running = { stopAnimation, resolvers: [resolve] };
+        });
+    };
+    // ---- start ----
+    const root = element.getRootNode();
+    // inside a shadow root, url(#id) only finds ids of that root
+    (root instanceof ShadowRoot ? root : document.body).append(svg);
+    buildBand();
+    applyStyle();
+    const box = element.getBoundingClientRect();
+    measure(box.width, box.height);
+    const resizeObserver = typeof ResizeObserver === 'function'
+        ? new ResizeObserver(([entry]) => {
+            const borderBox = entry.borderBoxSize?.[0];
+            if (borderBox)
+                measure(borderBox.inlineSize, borderBox.blockSize);
+            else
+                measure(entry.contentRect.width, entry.contentRect.height);
+        })
+        : null;
+    resizeObserver?.observe(element);
+    return {
+        to(stateOrChanges, options = {}) {
+            const { onEnd, duration, easing, ...changes } = typeof stateOrChanges === 'string'
+                ? { ...options, state: stateOrChanges } : stateOrChanges;
+            const result = change(changes, { ...defaultMorphOptions, ...(duration !== undefined && { duration }), ...(easing && { easing }) });
+            if (onEnd)
+                result.then(onEnd);
+            return result;
+        },
+        destroy() {
+            finish(true);
+            resizeObserver?.disconnect();
+            svg.remove();
+            element.style.clipPath = ownClipPath;
+            element.style.mask = ownMask;
+            element.style.setProperty('-webkit-mask', ownMask);
+        },
+    };
+};

package/dist/esm/engine.js

@@ -0,0 +1,25 @@
+/*! morphico v0.5.0 | MIT License, Copyright (c) 2026 Raycho Ivanov (see LICENSE) */
+// Animation engine: easings and one shared requestAnimationFrame loop for every running morph.
+// The loop only runs while something moves; nothing touches the DOM at import time (SSR-safe).
+export const easings = {
+    linear: (progress) => progress,
+    easeInOutCubic: (progress) => (progress < 0.5 ? 4 * progress ** 3 : 1 - (-2 * progress + 2) ** 3 / 2),
+    easeOutBack: (progress) => 1 + 2.70158 * (progress - 1) ** 3 + 1.70158 * (progress - 1) ** 2,
+    easeOutElastic: (progress) => (progress === 0 || progress === 1
+        ? progress
+        : 2 ** (-10 * progress) * Math.sin((progress * 10 - 0.75) * ((2 * Math.PI) / 3)) + 1),
+};
+const frameCallbacks = new Set();
+let animationFrameId = 0;
+const runFrame = (frameTime) => {
+    for (const callback of frameCallbacks)
+        if (!callback(frameTime))
+            frameCallbacks.delete(callback);
+    animationFrameId = frameCallbacks.size ? requestAnimationFrame(runFrame) : 0;
+};
+/** Adds a callback to the shared loop. Returns a function that removes it again. */
+export const animate = (onFrame) => {
+    frameCallbacks.add(onFrame);
+    animationFrameId ||= requestAnimationFrame(runFrame);
+    return () => { frameCallbacks.delete(onFrame); };
+};