morphico 0.3.0 → 0.4.0

package/dist/morphico.js

@@ -1,4 +1,4 @@
-/*! morphico v0.3.0 | code: MIT License, Copyright (c) 2026 Raycho Ivanov (see LICENSE)
+/*! morphico v0.4.0 | code: MIT License, Copyright (c) 2026 Raycho Ivanov (see LICENSE)
  * Icons based on Lucide (https://lucide.dev), some of them from Feather (https://feathericons.com):
  *
  * ISC License
@@ -3128,7 +3128,7 @@ return { EMPTY_STATE, DEFAULT_DURATION, shapesOf, hasState, prefersReducedMotion
 // sets/shapes.ts
 const { lucideShapeOutlines, clipShapes } = (() => {
 // Shapes for clip(): closed outlines that cut out an element. From Lucide 1.61.0 (ISC, see LICENSE-lucide), imported
-// by `node tools/import-lucide.ts <name>`; tag without its dot. The states are the Lucide outlines made comparable for
+// by `node tools/import-lucide.ts <name>`; tag without its dot, club without its stem. The states are the Lucide outlines made comparable for
 // morphing: clockwise, starting where the outline crosses the vertical middle at the top, scaled evenly to fill the
 // 24×24 box and centred (computed on first use, not at import). Roundness 1 = Lucide's own corners … 0 = sharp.
 const DEGREE = Math.PI / 180;
@@ -3339,16 +3339,6 @@ const lucideShapeOutlines = {
         line(2, 16, 2, 8),
         arc(4, 8, 2, 180, 270),
     ],
-    'rectangle-vertical': [
-        line(8, 2, 16, 2),
-        arc(16, 4, 2, -90, 0),
-        line(18, 4, 18, 20),
-        arc(16, 20, 2, 0, 90),
-        line(16, 22, 8, 22),
-        arc(8, 20, 2, 90, 180),
-        line(6, 20, 6, 4),
-        arc(8, 4, 2, 180, 270),
-    ],
     'message-circle': [
         arc(1.1328, 17.079, 2, -21.6245, 12.4142),
         line(3.086, 17.509, 2.021, 20.799),
@@ -3369,16 +3359,6 @@ const lucideShapeOutlines = {
         arc(20, 5, 2, -90, 0),
         line(22, 5, 22, 17),
     ],
-    diamond: [
-        arc(4.4033, 12.005, 2.41, -134.9707, -225.0293),
-        line(2.7, 13.71, 10.29, 21.3),
-        arc(11.995, 19.5967, 2.41, 135.0293, 44.9707),
-        line(13.7, 21.3, 21.29, 13.71),
-        arc(19.5867, 12.005, 2.41, 45.0293, -45.0293),
-        line(21.29, 10.3, 13.7, 2.71),
-        arc(11.995, 4.4133, 2.41, -44.9707, -135.0293),
-        line(10.29, 2.71, 2.7, 10.3),
-    ],
     cloud: [
         line(17.5, 19, 9, 19),
         arc(9.0018, 12, 7, 90.0147, 343.3984),
@@ -3411,6 +3391,13 @@ const lucideShapeOutlines = {
         arc(12, 4.4139, 2.414, -135.0015, -44.9985),
         line(13.707, 2.707, 15.39, 4.39),
     ],
+    // without its stem line (Lucide's second piece)
+    club: [
+        arc(12, 7.51, 5.5, 16.2602, -196.2602),
+        arc(7.5026, 14.494, 5.5, -98.1803, -324.8563),
+        arc(16.5052, 14.5052, 5.5, 144.9978, -81.9018),
+        line(17.28, 9.06, 17.28, 9.05),
+    ],
 };
 // ---- making the outlines comparable ----
 const pointOnStroke = (stroke, progress) => strokePiece(stroke, 0, progress)[3];
@@ -3602,6 +3589,8 @@ 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))
@@ -3624,7 +3613,7 @@ const checkedOutline = (outline) => {
 };
 /** Cuts `element` out by a morphing shape. */
 const clip = (element, options = {}) => {
-    const { set = clipShapes, state: initialState = 'circle', x = 50, y = 50, size, rotation = 0, roundness = 1, outline = false, ...defaultMorphOptions } = options;
+    const { set = clipShapes, state: initialState = 'circle', 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(', ')})`);
@@ -3638,7 +3627,7 @@ const clip = (element, options = {}) => {
     /** Where the change goes (or what shows when nothing moves). */
     const target = {
         state: checkedState(set, initialState), set: resolveIconSet(set, roundness), roundness,
-        x, y, size, rotation, outline: checkedOutline(outline),
+        x, y, size, rotation, outline: checkedOutline(outline), inverted,
     };
     const pieceLength = pieceLengthOf(set);
     let frame = null; // null = resting at the target
@@ -3660,16 +3649,22 @@ const clip = (element, options = {}) => {
             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: 'white', 'stroke-width': lineWidth, 'stroke-linejoin': 'miter' });
+        const edgeLine = (lineWidth) => pixelPath({ fill: 'none', stroke: bandColor, 'stroke-width': lineWidth, 'stroke-linejoin': 'miter' });
         if (band === 'centre') {
             maskElement.append(edgeLine(width));
         }
@@ -3729,7 +3724,9 @@ const clip = (element, options = {}) => {
         else {
             // objectBoundingBox: 0…1 of the element's width / height
             const boxUnits = pixels.map((value, index) => value / (index % 2 ? elementHeight : elementWidth));
-            clipShape.setAttribute('d', toPathData(boxUnits, pieceLength));
+            // 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) => {
@@ -3768,8 +3765,11 @@ const clip = (element, options = {}) => {
             target.size = changes.size;
         if (changes.rotation !== undefined)
             target.rotation = changes.rotation;
-        if (changes.outline !== undefined) {
-            target.outline = checkedOutline(changes.outline);
+        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();
         }
@@ -3866,6 +3866,645 @@ const clip = (element, options = {}) => {
 return { clip };
 })();
 
+// sets/faces.ts
+const { OUTLINE_POINTS, PIECE_NAMES, faceExpressionNames, faceExpressionPieces, interpolateFace, blinked, smoothClosedPath, facePaths } = (() => {
+const OUTLINE_POINTS = 24;
+const PIECE_NAMES = ['leftBrow', 'rightBrow', 'leftEye', 'rightEye', 'leftPupil', 'rightPupil', 'mouth'];
+const DENSE_SAMPLES = 360;
+const toRadians = (degrees) => (degrees * Math.PI) / 180;
+const rotatePoint = ([x, y], degrees) => {
+    const angle = toRadians(degrees);
+    return [x * Math.cos(angle) - y * Math.sin(angle), x * Math.sin(angle) + y * Math.cos(angle)];
+};
+const denseBlobOutline = (options) => {
+    const { centre, width, height, rotation = 0, squareness = 0, topScale = 1 } = options;
+    const exponent = 2 + squareness * 6;
+    const halfWidth = width / 2;
+    const halfHeight = height / 2;
+    const outline = [];
+    for (let index = 0; index < DENSE_SAMPLES; index++) {
+        const angle = toRadians(-90 + (360 * index) / DENSE_SAMPLES);
+        const cosine = Math.cos(angle);
+        const sine = Math.sin(angle);
+        const y = halfHeight * Math.sign(sine) * Math.abs(sine) ** (2 / exponent);
+        const widthScale = 1 + ((topScale - 1) * (halfHeight - y)) / (2 * halfHeight);
+        const x = halfWidth * widthScale * Math.sign(cosine) * Math.abs(cosine) ** (2 / exponent);
+        const [turnedX, turnedY] = rotatePoint([x, y], rotation);
+        outline.push([centre[0] + turnedX, centre[1] + turnedY]);
+    }
+    const xs = outline.map(([x]) => x);
+    const left = Math.min(...xs);
+    const right = Math.max(...xs);
+    const lineY = ([leftY, rightY], x) => leftY + ((rightY - leftY) * (x - left)) / (right - left);
+    return outline.map(([x, y]) => {
+        let cutY = y;
+        if (options.cutTop)
+            cutY = Math.max(cutY, lineY(options.cutTop, x));
+        if (options.cutBottom)
+            cutY = Math.min(cutY, lineY(options.cutBottom, x));
+        return [x, cutY];
+    });
+};
+/** OUTLINE_POINTS points of a star-shaped outline, on rays at even angles from its box's centre (measured in the box
+ * stretched to a square, so a long flat shape still gets points on its round ends). */
+const resampleByAngle = (outline) => {
+    const xs = outline.map(([x]) => x);
+    const ys = outline.map(([, y]) => y);
+    const centreX = (Math.min(...xs) + Math.max(...xs)) / 2;
+    const centreY = (Math.min(...ys) + Math.max(...ys)) / 2;
+    const halfX = Math.max((Math.max(...xs) - Math.min(...xs)) / 2, 1e-9);
+    const halfY = Math.max((Math.max(...ys) - Math.min(...ys)) / 2, 1e-9);
+    const normalized = outline.map(([x, y]) => [(x - centreX) / halfX, (y - centreY) / halfY]);
+    const points = [];
+    for (let index = 0; index < OUTLINE_POINTS; index++) {
+        const angle = toRadians(-90 + (360 * index) / OUTLINE_POINTS);
+        const directionX = Math.cos(angle);
+        const directionY = Math.sin(angle);
+        let farthest = 0;
+        normalized.forEach((start, edgeIndex) => {
+            const end = normalized[(edgeIndex + 1) % normalized.length];
+            const edgeX = end[0] - start[0];
+            const edgeY = end[1] - start[1];
+            const denominator = directionX * edgeY - directionY * edgeX;
+            if (Math.abs(denominator) < 1e-12)
+                return;
+            const distance = (start[0] * edgeY - start[1] * edgeX) / denominator;
+            const along = (start[0] * directionY - start[1] * directionX) / denominator;
+            // a little slack: a ray passing exactly through a corner of the dense outline must still hit one of its edges
+            if (along >= -1e-9 && along <= 1 + 1e-9 && distance > farthest)
+                farthest = distance;
+        });
+        points.push([centreX + directionX * farthest * halfX, centreY + directionY * farthest * halfY]);
+    }
+    return points;
+};
+const blob = (options) => resampleByAngle(denseBlobOutline(options));
+const band = (options) => {
+    const { from, to, bend, thickness, endShare = 1 } = options;
+    const chordX = to[0] - from[0];
+    const chordY = to[1] - from[1];
+    const chordLength = Math.hypot(chordX, chordY);
+    // the quadratic's control point sits twice as far out as the curve's middle
+    const control = [
+        (from[0] + to[0]) / 2 + ((2 * bend * chordY) / chordLength),
+        (from[1] + to[1]) / 2 - ((2 * bend * chordX) / chordLength),
+    ];
+    const pointAt = (along) => {
+        const rest = 1 - along;
+        return [
+            rest * rest * from[0] + 2 * rest * along * control[0] + along * along * to[0],
+            rest * rest * from[1] + 2 * rest * along * control[1] + along * along * to[1],
+        ];
+    };
+    const tangentAt = (along) => {
+        const tangentX = 2 * (1 - along) * (control[0] - from[0]) + 2 * along * (to[0] - control[0]);
+        const tangentY = 2 * (1 - along) * (control[1] - from[1]) + 2 * along * (to[1] - control[1]);
+        const length = Math.hypot(tangentX, tangentY);
+        return [tangentX / length, tangentY / length];
+    };
+    const thicknessAt = (along) => thickness * (endShare + (1 - endShare) * Math.sin(Math.PI * along));
+    // side 1 = the upper edge (the left normal of a rightward curve), -1 = the lower edge
+    const edge = (along, side) => {
+        const [x, y] = pointAt(along);
+        const [tangentX, tangentY] = tangentAt(along);
+        const offset = (side * thicknessAt(along)) / 2;
+        return [x + tangentY * offset, y - tangentX * offset];
+    };
+    // a point on the half circle around an end: turn -90° = on the upper edge, 0 = the tip, 90° = on the lower edge
+    const capPoint = (along, turn) => {
+        const [x, y] = pointAt(along);
+        const [tangentX, tangentY] = tangentAt(along);
+        const radius = thicknessAt(along) / 2;
+        const outward = along === 1 ? 1 : -1;
+        const alongTangent = outward * Math.cos(turn) * radius;
+        const towardsLower = outward * Math.sin(turn) * radius;
+        return [x + tangentX * alongTangent - tangentY * towardsLower, y + tangentY * alongTangent + tangentX * towardsLower];
+    };
+    // clockwise from the top middle at the same angles as a blob's points (a quarter = the right end, half = the bottom
+    // middle, three quarters = the left end); the points within 30° of an end lie on its half circle, the rest along the
+    // edges
+    const capShare = Math.sin(Math.PI / 3);
+    return Array.from({ length: OUTLINE_POINTS }, (_, index) => {
+        const angle = (2 * Math.PI * index) / OUTLINE_POINTS;
+        const sine = Math.sin(angle);
+        if (Math.abs(sine) < capShare - 1e-9)
+            return edge(0.5 + (0.5 * sine) / capShare, Math.cos(angle) > 0 ? 1 : -1);
+        // the angle's distance past the cap's start, stretched from ±30° around the end to ±90° around the half circle
+        const endAngle = sine > 0 ? Math.PI / 2 : (3 * Math.PI) / 2;
+        return capPoint(sine > 0 ? 1 : 0, (angle - endAngle) * 3);
+    });
+};
+/** A piece that isn't there: every point on one spot (draws nothing). */
+const hidden = (at) => Array.from({ length: OUTLINE_POINTS }, () => [at[0], at[1]]);
+/** The piece mirrored onto the other half of the face, still clockwise from the top. */
+const mirrored = (points) => points.map((_, index) => {
+    const [x, y] = points[(OUTLINE_POINTS - index) % OUTLINE_POINTS];
+    return [24 - x, y];
+});
+/** A face from its left half (as seen) + the mouth. */
+const symmetricFace = ({ brow, eye, pupil, mouth }) => ({
+    leftBrow: brow,
+    rightBrow: mirrored(brow),
+    leftEye: eye,
+    rightEye: mirrored(eye),
+    leftPupil: pupil,
+    rightPupil: mirrored(pupil),
+    mouth,
+});
+/** The whole face mirrored: left and right pieces swap sides. */
+const mirroredFace = (face) => ({
+    leftBrow: mirrored(face.rightBrow),
+    rightBrow: mirrored(face.leftBrow),
+    leftEye: mirrored(face.rightEye),
+    rightEye: mirrored(face.leftEye),
+    leftPupil: mirrored(face.rightPupil),
+    rightPupil: mirrored(face.leftPupil),
+    mouth: mirrored(face.mouth),
+});
+// ---- the expressions (names from the user's pictures) ----
+const faceExpressionNames = [
+    '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',
+];
+const buildFaceExpressions = () => {
+    const winkRight = {
+        ...symmetricFace({
+            brow: blob({ centre: [6.2, 4.4], width: 5.2, height: 1.9, squareness: 0.5, rotation: -6 }),
+            eye: blob({ centre: [6.4, 12], width: 8.4, height: 8.4 }),
+            pupil: blob({ centre: [7, 11.4], width: 3.2, height: 3.2 }),
+            mouth: band({ from: [9.6, 18.4], to: [14.8, 18], bend: -0.9, thickness: 1.2, endShare: 0.7 }),
+        }),
+        rightBrow: mirrored(blob({ centre: [6.2, 6], width: 5, height: 1.8, squareness: 0.5, rotation: 8 })),
+        rightEye: mirrored(band({ from: [3.2, 12.8], to: [9.6, 12.8], bend: 1.4, thickness: 1.6, endShare: 0.7 })),
+        rightPupil: hidden([17.6, 12]),
+    };
+    return {
+        normal: symmetricFace({
+            brow: blob({ centre: [6.2, 4.6], width: 5.2, height: 1.9, squareness: 0.5, rotation: -6 }),
+            eye: blob({ centre: [6.4, 12], width: 8.4, height: 8.4 }),
+            pupil: blob({ centre: [7, 10.7], width: 3.2, height: 3.2 }),
+            mouth: blob({ centre: [12, 18.8], width: 4.4, height: 1.8, squareness: 0.6 }),
+        }),
+        smiling: symmetricFace({
+            brow: blob({ centre: [6, 5.4], width: 5, height: 4.4, squareness: 0.2, cutBottom: [5.4, 5.4] }),
+            eye: blob({ centre: [6, 13], width: 9.2, height: 7.6 }),
+            pupil: blob({ centre: [6.8, 13.6], width: 3.6, height: 2.4 }),
+            mouth: band({ from: [9, 18.4], to: [15, 18.4], bend: -1, thickness: 1.3, endShare: 0.7 }),
+        }),
+        pleading: symmetricFace({
+            brow: blob({ centre: [6.6, 3.7], width: 4.6, height: 2, squareness: 0.5, rotation: -16 }),
+            eye: blob({ centre: [6.8, 12.4], width: 8.6, height: 9.6, topScale: 0.75, rotation: 12 }),
+            pupil: blob({ centre: [7.6, 10.7], width: 4, height: 4 }),
+            mouth: blob({ centre: [12, 17.6], width: 4.3, height: 4.8, squareness: 0.3, cutTop: [17.6, 17.6] }),
+        }),
+        wonder: symmetricFace({
+            brow: band({ from: [3.4, 4.8], to: [8.6, 3.3], bend: 0.7, thickness: 1.7 }),
+            eye: blob({ centre: [6.4, 12], width: 7.8, height: 9.6 }),
+            pupil: blob({ centre: [6.8, 11.2], width: 3.2, height: 4.2 }),
+            mouth: blob({ centre: [12, 18.6], width: 3.8, height: 1, squareness: 0.6 }),
+        }),
+        focused: symmetricFace({
+            brow: blob({ centre: [6, 4.4], width: 5.6, height: 2.2, squareness: 0.55, rotation: 3 }),
+            eye: blob({ centre: [6.2, 12.8], width: 9, height: 8, cutTop: [10, 11] }),
+            pupil: blob({ centre: [6.8, 13.2], width: 3.8, height: 2.8 }),
+            mouth: blob({ centre: [12, 18.8], width: 4.2, height: 1, squareness: 0.6 }),
+        }),
+        fright: symmetricFace({
+            brow: blob({ centre: [5.7, 3.5], width: 4.8, height: 2.2, squareness: 0.45, rotation: -8 }),
+            eye: blob({ centre: [6.2, 12.4], width: 8.4, height: 9.8, topScale: 0.7, rotation: 8 }),
+            pupil: blob({ centre: [7.2, 12], width: 3.6, height: 4.2 }),
+            mouth: blob({ centre: [12, 18.6], width: 3.8, height: 1.4, squareness: 0.5 }),
+        }),
+        angry: symmetricFace({
+            brow: blob({ centre: [6.4, 5.4], width: 5.2, height: 2, squareness: 0.5, rotation: 12 }),
+            eye: blob({ centre: [6.2, 12.6], width: 8.6, height: 8, cutTop: [9.2, 12] }),
+            pupil: blob({ centre: [7.4, 12.8], width: 3.4, height: 3.4 }),
+            mouth: blob({ centre: [12, 17.8], width: 4.2, height: 4, squareness: 0.3, cutTop: [17.8, 17.8] }),
+        }),
+        asleep: symmetricFace({
+            brow: blob({ centre: [6, 5.4], width: 4, height: 1.7, squareness: 0.4, rotation: 4 }),
+            eye: band({ from: [3, 12.4], to: [9.6, 12.4], bend: -1.2, thickness: 1.5, endShare: 0.6 }),
+            pupil: hidden([6.3, 13.4]),
+            mouth: blob({ centre: [12, 18.8], width: 2.6, height: 1.8 }),
+        }),
+        // more feelings, Claude's drafts (no pictures); the one-sided ones replace pieces of the right half — written in place
+        // (a blob or band is already clockwise from its top) or drawn on the left and mirrored
+        sad: symmetricFace({
+            brow: blob({ centre: [6.4, 5.2], width: 4.8, height: 1.9, squareness: 0.5, rotation: -18 }),
+            eye: blob({ centre: [6.4, 12.6], width: 8.4, height: 8, cutTop: [11.2, 9.6] }),
+            pupil: blob({ centre: [6.8, 13.8], width: 3.2, height: 3.4 }),
+            mouth: band({ from: [9.4, 19.2], to: [14.6, 19.2], bend: 0.9, thickness: 1.2, endShare: 0.7 }),
+        }),
+        surprised: symmetricFace({
+            brow: band({ from: [3.6, 3.6], to: [8.6, 2.8], bend: 0.6, thickness: 1.6 }),
+            eye: blob({ centre: [6.4, 12], width: 8.6, height: 9 }),
+            pupil: blob({ centre: [6.4, 12], width: 2.4, height: 2.4 }),
+            mouth: blob({ centre: [12, 19], width: 2.8, height: 3.4 }),
+        }),
+        laughing: symmetricFace({
+            brow: blob({ centre: [6, 4.6], width: 5, height: 4.4, squareness: 0.2, cutBottom: [4.6, 4.6] }),
+            eye: band({ from: [3.2, 13], to: [9.6, 13], bend: 1.6, thickness: 1.6, endShare: 0.7 }),
+            pupil: hidden([6.4, 12]),
+            mouth: blob({ centre: [12, 17], width: 6, height: 6, squareness: 0.2, cutTop: [17, 17] }),
+        }),
+        tired: symmetricFace({
+            brow: blob({ centre: [6, 6], width: 5, height: 1.7, squareness: 0.5, rotation: -4 }),
+            eye: blob({ centre: [6.4, 12.6], width: 8.4, height: 7.6, cutTop: [11.6, 11.6] }),
+            pupil: blob({ centre: [6.6, 13.6], width: 3.2, height: 3.2 }),
+            mouth: blob({ centre: [12, 19], width: 3.2, height: 0.9, squareness: 0.6 }),
+        }),
+        // wink-left / wink-right = the eye that closes, as seen; one is the other mirrored
+        'wink-left': mirroredFace(winkRight),
+        'wink-right': winkRight,
+        suspicious: {
+            ...symmetricFace({
+                brow: band({ from: [3.4, 4], to: [8.8, 3], bend: 0.8, thickness: 1.6 }),
+                eye: blob({ centre: [6.4, 12.6], width: 8.6, height: 7.6, cutTop: [10.8, 10.8] }),
+                pupil: blob({ centre: [4.6, 13.2], width: 3.2, height: 3 }),
+                mouth: blob({ centre: [12.6, 18.8], width: 3.6, height: 1, squareness: 0.6, rotation: -10 }),
+            }),
+            rightBrow: mirrored(blob({ centre: [6.4, 6.4], width: 5.2, height: 1.8, squareness: 0.5, rotation: 10 })),
+            rightEye: mirrored(blob({ centre: [6.4, 12.8], width: 8.6, height: 7.2, cutTop: [11.8, 11.8] })),
+            rightPupil: blob({ centre: [16.2, 13.4], width: 3.2, height: 3 }),
+        },
+        confused: {
+            ...symmetricFace({
+                brow: band({ from: [3.4, 3.8], to: [8.6, 2.6], bend: 0.7, thickness: 1.6 }),
+                eye: blob({ centre: [6.4, 12], width: 8.6, height: 9 }),
+                pupil: blob({ centre: [7.6, 10.6], width: 3, height: 3 }),
+                mouth: blob({ centre: [12.4, 19], width: 3.8, height: 1.1, squareness: 0.5, rotation: 12 }),
+            }),
+            rightBrow: mirrored(blob({ centre: [6.2, 5.8], width: 5, height: 1.8, squareness: 0.5, rotation: 10 })),
+            rightEye: mirrored(blob({ centre: [6.4, 12.6], width: 7.4, height: 7.4 })),
+            rightPupil: blob({ centre: [18.4, 11.4], width: 2.8, height: 2.8 }),
+        },
+        // the user's list of feelings (2026-11-01), Claude's drafts; the ones the set had already are skipped
+        smug: {
+            ...symmetricFace({
+                brow: blob({ centre: [6.2, 5], width: 5, height: 1.8, squareness: 0.5, rotation: -4 }),
+                eye: blob({ centre: [6.4, 12.6], width: 8.4, height: 7.6, cutTop: [11.4, 11.4] }),
+                pupil: blob({ centre: [8, 13.4], width: 3, height: 3 }),
+                mouth: band({ from: [10.2, 18.8], to: [15.2, 17.6], bend: -0.6, thickness: 1.2, endShare: 0.6 }),
+            }),
+            rightBrow: mirrored(band({ from: [3.6, 4.2], to: [8.6, 3.4], bend: 0.6, thickness: 1.6 })),
+            rightPupil: blob({ centre: [19.4, 13.4], width: 3, height: 3 }),
+        },
+        irritated: symmetricFace({
+            brow: blob({ centre: [6.4, 5.8], width: 5.4, height: 1.8, squareness: 0.55, rotation: 6 }),
+            eye: blob({ centre: [6.4, 12.8], width: 8.6, height: 7.6, cutTop: [11.2, 11.8], cutBottom: [15.8, 15.8] }),
+            pupil: blob({ centre: [6.8, 13.6], width: 3.2, height: 3 }),
+            mouth: blob({ centre: [12.4, 18.8], width: 3.6, height: 0.9, squareness: 0.6, rotation: -8 }),
+        }),
+        bored: {
+            ...symmetricFace({
+                brow: blob({ centre: [6, 6.2], width: 5, height: 1.7, squareness: 0.5 }),
+                eye: blob({ centre: [6.4, 12.6], width: 8.4, height: 7.6, cutTop: [11.8, 11.8] }),
+                pupil: blob({ centre: [8, 12.8], width: 3, height: 3 }),
+                mouth: blob({ centre: [13.4, 19], width: 3, height: 0.9, squareness: 0.6 }),
+            }),
+            rightPupil: blob({ centre: [19.4, 12.8], width: 3, height: 3 }),
+        },
+        curious: {
+            ...symmetricFace({
+                brow: band({ from: [3.4, 3.6], to: [8.6, 2.6], bend: 0.7, thickness: 1.6 }),
+                eye: blob({ centre: [6.4, 12], width: 8.6, height: 8.8 }),
+                pupil: blob({ centre: [7.8, 10.8], width: 3.2, height: 3.2 }),
+                mouth: blob({ centre: [12.6, 18.8], width: 2, height: 2.2 }),
+            }),
+            rightBrow: mirrored(blob({ centre: [6.2, 5.2], width: 5, height: 1.8, squareness: 0.5, rotation: 4 })),
+            rightPupil: blob({ centre: [19, 10.8], width: 3.2, height: 3.2 }),
+        },
+        empathetic: symmetricFace({
+            brow: blob({ centre: [6.4, 4.8], width: 5, height: 1.9, squareness: 0.5, rotation: -10 }),
+            eye: blob({ centre: [6.4, 12.4], width: 8.4, height: 8, cutTop: [10, 9.2] }),
+            pupil: blob({ centre: [6.8, 13], width: 3.4, height: 3.4 }),
+            mouth: band({ from: [10, 18.6], to: [14, 18.6], bend: -0.5, thickness: 1.1, endShare: 0.7 }),
+        }),
+        guilty: {
+            ...symmetricFace({
+                brow: blob({ centre: [6.4, 5], width: 4.6, height: 1.8, squareness: 0.5, rotation: -14 }),
+                eye: blob({ centre: [6.4, 12.6], width: 8.2, height: 8, cutTop: [10.6, 10.2] }),
+                pupil: blob({ centre: [5, 14.4], width: 3, height: 3 }),
+                mouth: blob({ centre: [11.4, 19], width: 2.8, height: 0.9, squareness: 0.6, rotation: 6 }),
+            }),
+            rightPupil: blob({ centre: [16.2, 14.4], width: 3, height: 3 }),
+        },
+        worried: symmetricFace({
+            brow: blob({ centre: [6.6, 4.2], width: 4.8, height: 1.9, squareness: 0.5, rotation: -20 }),
+            eye: blob({ centre: [6.4, 12.2], width: 8, height: 8.8, topScale: 0.85, rotation: 6 }),
+            pupil: blob({ centre: [6.8, 12.4], width: 2.6, height: 2.8 }),
+            mouth: band({ from: [10.2, 19], to: [13.8, 19], bend: 0.6, thickness: 1.1, endShare: 0.7 }),
+        }),
+        disappointed: symmetricFace({
+            brow: blob({ centre: [6.2, 5.6], width: 5, height: 1.8, squareness: 0.5, rotation: -8 }),
+            eye: blob({ centre: [6.4, 12.8], width: 8.4, height: 7.6, cutTop: [11.8, 11] }),
+            pupil: blob({ centre: [6.6, 14.4], width: 3, height: 3 }),
+            mouth: band({ from: [9.6, 19.2], to: [14.4, 19.2], bend: 0.4, thickness: 1.1, endShare: 0.8 }),
+        }),
+        ashamed: symmetricFace({
+            brow: blob({ centre: [6.4, 5.6], width: 4.6, height: 1.8, squareness: 0.5, rotation: -16 }),
+            eye: blob({ centre: [6.4, 13], width: 8.2, height: 7.6, cutTop: [12.2, 12.2] }),
+            pupil: blob({ centre: [6.4, 15], width: 3, height: 2.6 }),
+            mouth: blob({ centre: [12, 19.4], width: 2.4, height: 0.9, squareness: 0.6 }),
+        }),
+        embarrassed: {
+            ...symmetricFace({
+                brow: blob({ centre: [6.2, 4.8], width: 4.8, height: 1.8, squareness: 0.5, rotation: -12 }),
+                eye: blob({ centre: [6.4, 12.4], width: 8.2, height: 8.2 }),
+                pupil: blob({ centre: [4.4, 13.6], width: 3, height: 3 }),
+                mouth: band({ from: [9.8, 18.8], to: [14.2, 18.6], bend: -0.5, thickness: 1.1, endShare: 0.7 }),
+            }),
+            rightPupil: blob({ centre: [15.8, 13.6], width: 3, height: 3 }),
+        },
+        yearning: symmetricFace({
+            brow: blob({ centre: [6.2, 4], width: 4.8, height: 1.8, squareness: 0.5, rotation: -10 }),
+            eye: blob({ centre: [6.4, 12.6], width: 8.6, height: 8, cutTop: [11, 11] }),
+            pupil: blob({ centre: [6.8, 13.6], width: 4.2, height: 4.2 }),
+            mouth: blob({ centre: [12, 18.8], width: 2.6, height: 1.6 }),
+        }),
+        triumphant: symmetricFace({
+            brow: blob({ centre: [6.2, 4], width: 5.2, height: 2, squareness: 0.5, rotation: 8 }),
+            eye: blob({ centre: [6.4, 11.8], width: 8.6, height: 8.6, cutBottom: [14, 14] }),
+            pupil: blob({ centre: [6.8, 11.6], width: 3.4, height: 3.4 }),
+            mouth: blob({ centre: [12, 16.8], width: 7, height: 6.4, squareness: 0.3, cutTop: [16.8, 16.8] }),
+        }),
+        proud: symmetricFace({
+            brow: blob({ centre: [6.2, 3.8], width: 5, height: 1.9, squareness: 0.5, rotation: -4 }),
+            eye: blob({ centre: [6.4, 12.4], width: 8.6, height: 8, cutTop: [11, 11] }),
+            pupil: blob({ centre: [6.6, 13.6], width: 3.2, height: 3 }),
+            mouth: band({ from: [8.8, 18], to: [15.2, 18], bend: -1.2, thickness: 1.3, endShare: 0.7 }),
+        }),
+        excited: symmetricFace({
+            brow: band({ from: [3.4, 3.6], to: [8.6, 2.8], bend: 0.8, thickness: 1.6 }),
+            eye: blob({ centre: [6.4, 12], width: 9, height: 9.2 }),
+            pupil: blob({ centre: [7, 11], width: 4, height: 4 }),
+            mouth: blob({ centre: [12, 16.8], width: 6, height: 6, squareness: 0.2, cutTop: [16.8, 16.8] }),
+        }),
+        scornful: {
+            ...symmetricFace({
+                brow: blob({ centre: [6.2, 5.4], width: 5, height: 1.8, squareness: 0.5, rotation: 2 }),
+                eye: blob({ centre: [6.4, 12.6], width: 8.4, height: 7.6, cutTop: [11.4, 11.4] }),
+                pupil: blob({ centre: [5.4, 14], width: 3, height: 3 }),
+                mouth: band({ from: [9.2, 18.8], to: [14.6, 18], bend: -0.2, thickness: 1.1, endShare: 0.7 }),
+            }),
+            rightBrow: mirrored(band({ from: [3.6, 4], to: [8.6, 3.2], bend: 0.6, thickness: 1.6 })),
+            rightPupil: blob({ centre: [16.6, 14], width: 3, height: 3 }),
+        },
+        disgusted: symmetricFace({
+            brow: blob({ centre: [6.6, 6], width: 5, height: 1.8, squareness: 0.5, rotation: 14 }),
+            eye: blob({ centre: [6.4, 12.6], width: 8.4, height: 7.6, cutTop: [11.4, 12.2], cutBottom: [14.8, 14.8] }),
+            pupil: blob({ centre: [6.8, 13.2], width: 3, height: 2.8 }),
+            // an upside-down "D": open, corners pulled down
+            mouth: blob({ centre: [12, 19.6], width: 5, height: 4.8, squareness: 0.2, cutBottom: [19.6, 19.6] }),
+        }),
+    };
+};
+let builtExpressions = null;
+/** Every expression's pieces, built on first use (nothing runs at import). */
+const faceExpressionPieces = () => (builtExpressions ??= buildFaceExpressions());
+// ---- morphing and drawing ----
+const interpolatePoints = (from, to, progress) => from.map(([fromX, fromY], index) => [fromX + (to[index][0] - fromX) * progress, fromY + (to[index][1] - fromY) * progress]);
+const interpolateFace = (from, to, progress) => Object.fromEntries(PIECE_NAMES.map((name) => [name, interpolatePoints(from[name], to[name], progress)]));
+const boxCentre = (points) => {
+    const xs = points.map(([x]) => x);
+    const ys = points.map(([, y]) => y);
+    return [(Math.min(...xs) + Math.max(...xs)) / 2, (Math.min(...ys) + Math.max(...ys)) / 2];
+};
+/** The face with its eyes partly closed: openness 1 = as drawn, 0 = shut to a flat slit (pupils gone). */
+const blinked = (face, openness) => {
+    if (openness >= 1)
+        return face;
+    const eyeScale = 0.25 + 0.75 * openness;
+    const squash = (points, middleY) => points.map(([x, y]) => [x, middleY + (y - middleY) * eyeScale]);
+    const shrink = (points, [centreX, centreY]) => points.map(([x, y]) => [centreX + (x - centreX) * openness, centreY + (y - centreY) * openness]);
+    const leftMiddle = boxCentre(face.leftEye)[1];
+    const rightMiddle = boxCentre(face.rightEye)[1];
+    return {
+        ...face,
+        leftEye: squash(face.leftEye, leftMiddle),
+        rightEye: squash(face.rightEye, rightMiddle),
+        leftPupil: squash(shrink(face.leftPupil, boxCentre(face.leftPupil)), leftMiddle),
+        rightPupil: squash(shrink(face.rightPupil, boxCentre(face.rightPupil)), rightMiddle),
+    };
+};
+const formatNumber = (value) => String(Math.round(value * 1000) / 1000);
+/** A smooth closed curve through the points: each handle points along the neighbours' chord and is a third of its own
+ * segment long (no loops where points sit close together, as at a band's round end). Empty for a hidden piece. */
+const smoothClosedPath = (points) => {
+    const [firstX, firstY] = points[0];
+    if (points.every(([x, y]) => Math.abs(x - firstX) < 1e-6 && Math.abs(y - firstY) < 1e-6))
+        return '';
+    const count = points.length;
+    const directionAt = (index) => {
+        const previous = points[(index - 1 + count) % count];
+        const next = points[(index + 1) % count];
+        const length = Math.hypot(next[0] - previous[0], next[1] - previous[1]) || 1;
+        return [(next[0] - previous[0]) / length, (next[1] - previous[1]) / length];
+    };
+    let path = `M${formatNumber(firstX)} ${formatNumber(firstY)}`;
+    for (let index = 0; index < count; index++) {
+        const start = points[index];
+        const end = points[(index + 1) % count];
+        const handleLength = Math.hypot(end[0] - start[0], end[1] - start[1]) / 3;
+        const startDirection = directionAt(index);
+        const endDirection = directionAt(index + 1);
+        const control1 = [start[0] + startDirection[0] * handleLength, start[1] + startDirection[1] * handleLength];
+        const control2 = [end[0] - endDirection[0] * handleLength, end[1] - endDirection[1] * handleLength];
+        path += `C${[...control1, ...control2, ...end].map(formatNumber).join(' ')}`;
+    }
+    return `${path}Z`;
+};
+const facePaths = (face) => ({
+    features: [face.leftBrow, face.rightBrow, face.leftEye, face.rightEye, face.mouth].map(smoothClosedPath).join(''),
+    eyes: [face.leftEye, face.rightEye].map(smoothClosedPath).join(''),
+    pupils: [face.leftPupil, face.rightPupil].map(smoothClosedPath).join(''),
+});
+return { OUTLINE_POINTS, PIECE_NAMES, faceExpressionNames, faceExpressionPieces, interpolateFace, blinked, smoothClosedPath, facePaths };
+})();
+
+// face.ts
+const { face } = (() => {
+// Layer 4: a face that morphs between feelings. 7 soft filled pieces (sets/faces.ts) — brows, eyes and mouth in the
+// CSS color, the pupils in their own color and clipped to the eyes. Blinking runs on top of any expression, by itself
+// every few seconds (option) or on blink().
+const BLINK_CLOSING = 90;
+const BLINK_SHUT = 50;
+const BLINK_OPENING = 150;
+const AUTO_BLINK_MIN_PAUSE = 2500;
+const AUTO_BLINK_EXTRA_PAUSE = 3500;
+const DEFAULT_FACE_DURATION = DEFAULT_DURATION + 100;
+/** Expressions whose eyes are already shut: blinking does nothing. */
+const EYES_SHUT = ['asleep', 'laughing'];
+let faceCount = 0;
+const checkedExpression = (state) => {
+    if (!faceExpressionNames.includes(state))
+        throw new Error(`morphico: face() has no expression "${state}"`);
+    return state;
+};
+const resolveEasing = (easing) => (typeof easing === 'function' ? easing : easings[easing ?? 'easeInOutCubic']);
+/** Adds a morphing face (an <svg>) to `element`. */
+const face = (element, options = {}) => {
+    const { state: firstState = 'normal', pupilColor = 'white', blink: blinksByItself = true, size = '100%', ...defaultMorphOptions } = options;
+    const expressions = faceExpressionPieces();
+    let state = checkedExpression(firstState);
+    let shownPieces = expressions[state];
+    let openness = 1;
+    const clipId = `morphico-face-${++faceCount}`;
+    const svg = createSvgElement('svg', { viewBox: '0 0 24 24', fill: 'currentColor', role: 'img' });
+    svg.style.width = size;
+    svg.style.height = size;
+    svg.style.overflow = 'visible';
+    const clipPath = svg.appendChild(createSvgElement('clipPath', { id: clipId }));
+    const eyesPath = clipPath.appendChild(createSvgElement('path'));
+    const featuresPath = svg.appendChild(createSvgElement('path'));
+    const pupilsPath = svg.appendChild(createSvgElement('path', { fill: pupilColor, 'clip-path': `url(#${clipId})` }));
+    const render = () => {
+        const paths = facePaths(blinked(shownPieces, openness));
+        featuresPath.setAttribute('d', paths.features);
+        eyesPath.setAttribute('d', paths.eyes);
+        pupilsPath.setAttribute('d', paths.pupils);
+    };
+    const updateLabel = () => svg.setAttribute('aria-label', state);
+    render();
+    updateLabel();
+    element.appendChild(svg);
+    // ---- morphing ----
+    let morph = null;
+    const endMorph = (interrupted) => {
+        if (!morph)
+            return;
+        const { stopAnimation, resolve, state: morphState } = morph;
+        morph = null;
+        stopAnimation();
+        resolve({ state: morphState, interrupted });
+    };
+    const morphTo = (nextState, morphOptions) => {
+        endMorph(true);
+        state = nextState;
+        updateLabel();
+        const fromPieces = shownPieces;
+        const toPieces = expressions[nextState];
+        const duration = morphOptions.duration ?? DEFAULT_FACE_DURATION;
+        if (prefersReducedMotion() || duration <= 0) {
+            shownPieces = toPieces;
+            render();
+            return Promise.resolve({ state: nextState, interrupted: false });
+        }
+        const easing = resolveEasing(morphOptions.easing);
+        let startTime = null;
+        return new Promise((resolve) => {
+            const stopAnimation = animate((frameTime) => {
+                startTime ??= frameTime;
+                const progress = Math.min((frameTime - startTime) / duration, 1);
+                shownPieces = interpolateFace(fromPieces, toPieces, easing(progress));
+                render();
+                if (progress < 1)
+                    return true;
+                endMorph(false);
+                return false;
+            });
+            morph = { stopAnimation, resolve, state: nextState };
+        });
+    };
+    // ---- blinking ----
+    let stopBlink = null;
+    let finishBlink = null;
+    const endBlink = () => {
+        stopBlink?.();
+        stopBlink = null;
+        if (openness < 1) {
+            openness = 1;
+            render();
+        }
+        finishBlink?.();
+        finishBlink = null;
+    };
+    const blink = () => {
+        if (EYES_SHUT.includes(state) || prefersReducedMotion())
+            return Promise.resolve();
+        endBlink();
+        let startTime = null;
+        return new Promise((resolve) => {
+            finishBlink = resolve;
+            stopBlink = animate((frameTime) => {
+                startTime ??= frameTime;
+                const elapsed = frameTime - startTime;
+                if (elapsed < BLINK_CLOSING)
+                    openness = 1 - elapsed / BLINK_CLOSING;
+                else if (elapsed < BLINK_CLOSING + BLINK_SHUT)
+                    openness = 0;
+                else
+                    openness = Math.min((elapsed - BLINK_CLOSING - BLINK_SHUT) / BLINK_OPENING, 1);
+                render();
+                if (openness < 1 || elapsed < BLINK_CLOSING)
+                    return true;
+                stopBlink = null;
+                finishBlink = null;
+                resolve();
+                return false;
+            });
+        });
+    };
+    let autoBlinkTimer;
+    const scheduleAutoBlink = () => {
+        autoBlinkTimer = setTimeout(() => {
+            if (typeof document === 'undefined' || !document.hidden)
+                void blink();
+            scheduleAutoBlink();
+        }, AUTO_BLINK_MIN_PAUSE + Math.random() * AUTO_BLINK_EXTRA_PAUSE);
+    };
+    if (blinksByItself && !prefersReducedMotion())
+        scheduleAutoBlink();
+    return {
+        get state() { return state; },
+        to(nextState, { onEnd, ...morphOptions } = {}) {
+            const result = morphTo(checkedExpression(nextState), { ...defaultMorphOptions, ...morphOptions });
+            if (onEnd)
+                result.then(onEnd);
+            return result;
+        },
+        blink,
+        destroy() {
+            clearTimeout(autoBlinkTimer);
+            endMorph(true);
+            endBlink();
+            svg.remove();
+        },
+    };
+};
+return { face };
+})();
+
 // icon.ts
 const { icon } = (() => {
 // Layer 1: one icon that morphs between the states of a set, e.g. a single digit.
@@ -4000,7 +4639,7 @@ return { text };
 // index.ts
 // morphico public API.
 /** Package version, e.g. "0.1.0" (tools/build.ts replaces 'dev'). */
-const version = '0.3.0';
+const version = '0.4.0';
 
-return { clip, easings, icon, iconSets, text, version };
+return { clip, easings, face, icon, iconSets, faceExpressionNames, text, version };
 })();