@bearmenu/ui 0.8.12 → 0.8.14

package/src/components/motion-icon-set.stories.tsx

@@ -1,7 +1,35 @@
 import * as React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 
-import { MotionHouse, MotionUtensils, MotionMapPin, MotionCalendar } from "./motion-icon-set";
+import {
+  MotionHouse,
+  MotionUtensils,
+  MotionMapPin,
+  MotionCalendar,
+  MotionLayoutGrid,
+  MotionWine,
+  MotionMap,
+  MotionFlame,
+  MotionCalendarClock,
+  MotionList,
+} from "./motion-icon-set";
+import {
+  MotionArrow,
+  MotionCaret,
+  MotionX,
+  MotionCircleX,
+  MotionExternalLink,
+  MotionSend,
+  MotionNavigation,
+  MotionLocate,
+  MotionMaximize,
+  MotionPhone,
+  MotionMail,
+  MotionFlag,
+  MotionLogIn,
+  MotionLogOut,
+  MotionSettings,
+} from "./motion-icon-actions";
 import {
   MotionHeart,
   MotionBookmark,
@@ -36,6 +64,35 @@ const OBJECTS: Glyph[] = [
   { name: "Utensils", Icon: MotionUtensils, gesture: "uncrosses into a place setting · holds" },
   { name: "MapPin", Icon: MotionMapPin, gesture: "jumps, fills on the descent · holds" },
   { name: "Calendar", Icon: MotionCalendar, gesture: "rolls four pages" },
+  { name: "LayoutGrid", Icon: MotionLayoutGrid, gesture: "tiles shuffle one slot round the board" },
+  { name: "Wine", Icon: MotionWine, gesture: "pours, sloshes past the line · holds" },
+  { name: "Map", Icon: MotionMap, gesture: "folds shut, snaps open" },
+  { name: "Flame", Icon: MotionFlame, gesture: "gathers, flares, fills at the peak" },
+  { name: "CalendarClock", Icon: MotionCalendarClock, gesture: "hand whips a turn, a wedge sweeps · holds" },
+  { name: "List", Icon: MotionList, gesture: "bottom row lifts to the top" },
+];
+
+const ArrowLeft = (p: MotionIconProps) => <MotionArrow direction="left" {...p} />;
+const CaretLeft = (p: MotionIconProps) => <MotionCaret direction="left" {...p} />;
+
+const ACTIONS: Glyph[] = [
+  { name: "Arrow", Icon: MotionArrow, gesture: "head fires ahead, shaft chases" },
+  { name: "Arrow ←", Icon: ArrowLeft, gesture: "the mirror, for back" },
+  { name: "Caret", Icon: MotionCaret, gesture: "coils, darts folded, springs open" },
+  { name: "Caret ←", Icon: CaretLeft, gesture: "the mirror, for carousel prev" },
+  { name: "X", Icon: MotionX, gesture: "blades shut to a bar, reopen" },
+  { name: "CircleX", Icon: MotionCircleX, gesture: "pressed, ejects its X, reloads" },
+  { name: "ExternalLink", Icon: MotionExternalLink, gesture: "arrow leaves, the next one loads" },
+  { name: "Send", Icon: MotionSend, gesture: "arrow fires out, stop block drops in · holds" },
+  { name: "Navigation", Icon: MotionNavigation, gesture: "needle hunts for its bearing" },
+  { name: "Locate", Icon: MotionLocate, gesture: "reticle skids off, locks on the dot" },
+  { name: "Maximize", Icon: MotionMaximize, gesture: "corners shove apart, snap back" },
+  { name: "Phone", Icon: MotionPhone, gesture: "lifted to the ear, dropped on the hook" },
+  { name: "Mail", Icon: MotionMail, gesture: "flap flips open, slaps shut" },
+  { name: "Flag", Icon: MotionFlag, gesture: "raised, planted, cloth whips" },
+  { name: "LogIn", Icon: MotionLogIn, gesture: "arrow goes through the door" },
+  { name: "LogOut", Icon: MotionLogOut, gesture: "arrow leaves, the next comes out" },
+  { name: "Settings", Icon: MotionSettings, gesture: "gear turns two teeth, hub seats" },
 ];
 
 const CONTROLS: Glyph[] = [
@@ -49,13 +106,13 @@ const CONTROLS: Glyph[] = [
   { name: "Theme", Icon: MotionTheme, gesture: "rays retract, crescent swings in · holds" },
   { name: "Chevron", Icon: MotionChevron, gesture: "turns over, tips past, settles · holds" },
   { name: "PlayPause", Icon: MotionPlayPause, gesture: "triangle folds into two bars · holds" },
-  { name: "Eye", Icon: MotionEye, gesture: "lid narrows, slash draws across · holds" },
+  { name: "Eye", Icon: MotionEye, gesture: "blinks, reopens onto the slash · holds" },
   { name: "Star", Icon: MotionStar, gesture: "pulls in, springs its points out · holds" },
   { name: "Copy", Icon: MotionCopy, gesture: "sheet peels off, check lands · holds" },
   { name: "Refresh", Icon: MotionRefresh, gesture: "one full turn, overshoots, settles" },
 ];
 
-const ALL = [...OBJECTS, ...CONTROLS];
+const ALL = [...OBJECTS, ...ACTIONS, ...CONTROLS];
 
 const meta = {
   title: "Motion/Animated icons",
@@ -160,6 +217,8 @@ export const Family: Story = {
 
 /** The objects and the controls separately, when tuning one group at a time. */
 export const Objects: Story = { render: () => <Gallery glyphs={OBJECTS} size={28} /> };
+/** The action vocabulary (`lib/icon-registry`) — most of these render at 16px in a `Button`, so check them at that size too. */
+export const Actions: Story = { render: () => <Gallery glyphs={ACTIONS} size={28} /> };
 export const Controls: Story = { render: () => <Gallery glyphs={CONTROLS} size={28} /> };
 
 /**

package/src/components/motion-icon-set.tsx

@@ -20,6 +20,7 @@ import {
   beats,
   pivot,
   returnTransition,
+  useSvgId,
   type MotionIconProps,
 } from "./motion-icon";
 
@@ -221,8 +222,7 @@ const reel: Variants = {
  * still, which is what sells the contents moving.
  */
 export function MotionCalendar(props: MotionIconProps) {
-  // React's useId contains colons, which are not safe in an SVG id / url(#…).
-  const clipId = `cal-body-${React.useId().replace(/:/g, "")}`;
+  const clipId = useSvgId("cal-body");
 
   return (
     <MotionIcon {...props}>
@@ -245,3 +245,350 @@ export function MotionCalendar(props: MotionIconProps) {
     </MotionIcon>
   );
 }
+
+// ─── Layout grid — the tiles shuffle one slot around the board (cycle content) ─
+
+/**
+ * Lucide's `layout-grid`: four 7-unit tiles on an 11-unit pitch. Each tile
+ * slides along the outer edge to the next corner clockwise, in a chase — the
+ * top-left tile leads and each following one starts a beat behind. Mid-flight
+ * the four sit on the edge midpoints, so the outline goes square → plus →
+ * square; that is the silhouette change. Nothing rotates: they slide, which is
+ * what makes it a shuffle rather than "turn the icon 90°".
+ *
+ * Travel is the full 11-unit pitch (46% of the box), above the 25–40% band.
+ * That is the geometry's own step — a half-slot shuffle ends on the edge
+ * midpoints, which is not a rest pose — and the band exists to guarantee
+ * visibility, not to cap it. Nothing leaves the box: the overshoot puts a
+ * tile's far edge at 22.5 + stroke.
+ *
+ * `play` ends with every tile one slot from its `rest` values although the
+ * picture is identical; `useIconGesture` snaps the values back once the
+ * gesture resolves, so leaving never slides them counter-clockwise.
+ */
+const GRID_TIMES = [0, 0.14, 0.6, 0.8, 1];
+const GRID_PITCH = 11;
+/** Per-tile delay in the chase, seconds. */
+const GRID_CHASE = 0.03;
+
+/** Anticipation against the travel, the edge, a 1.5 overshoot, a 0.4 rebound, the corner. */
+const slide = (direction: 1 | -1) =>
+  [0, -1.5, GRID_PITCH + 1.5, GRID_PITCH - 0.4, GRID_PITCH].map((v) => v * direction);
+
+const chase = (order: number) => ({ ...beats(GRID_TIMES, 0.58), delay: order * GRID_CHASE });
+
+function tileAlongX(direction: 1 | -1, order: number): Variants {
+  return {
+    rest: { x: 0, transition: returnTransition },
+    active: { x: 0, transition: returnTransition },
+    play: { x: slide(direction), transition: chase(order) },
+  };
+}
+
+function tileAlongY(direction: 1 | -1, order: number): Variants {
+  return {
+    rest: { y: 0, transition: returnTransition },
+    active: { y: 0, transition: returnTransition },
+    play: { y: slide(direction), transition: chase(order) },
+  };
+}
+
+// Clockwise from the top-left: TL → TR (x+), TR → BR (y+), BR → BL (x−), BL → TL (y−).
+const tileTopLeft = tileAlongX(1, 0);
+const tileTopRight = tileAlongY(1, 1);
+const tileBottomRight = tileAlongX(-1, 2);
+const tileBottomLeft = tileAlongY(-1, 3);
+
+export function MotionLayoutGrid(props: MotionIconProps) {
+  return (
+    <MotionIcon {...props}>
+      <motion.rect variants={tileTopLeft} width="7" height="7" x="3" y="3" rx="1" />
+      <motion.rect variants={tileTopRight} width="7" height="7" x="14" y="3" rx="1" />
+      <motion.rect variants={tileBottomRight} width="7" height="7" x="14" y="14" rx="1" />
+      <motion.rect variants={tileBottomLeft} width="7" height="7" x="3" y="14" rx="1" />
+    </MotionIcon>
+  );
+}
+
+// ─── Wine — pours, sloshes past the line, holds full (fall and land) ──────────
+
+const WINE_TIMES = [0, 0.16, 0.6, 0.78, 1];
+
+/**
+ * The bowl's bottom (empty), the line lucide already draws at the widest
+ * chord (`M7 10h10`, the "pour to here" mark), and the slosh two units above it.
+ */
+const WINE_EMPTY = 15;
+const WINE_LINE = 10;
+const WINE_SLOSH = 8;
+
+/**
+ * The liquid is a filled rect under a clip of the bowl, so its top edge IS the
+ * level. `attrY` moves the attribute rather than a transform so the rect's
+ * geometry itself changes under the `scaleY` the whole glass carries — the
+ * level then scales with the glass instead of fighting it. And the level has
+ * to rise, not fade: a rising solid is what sells a pour, which is why this
+ * does not reuse the pin's `fillOpacity` trick.
+ */
+const liquid: Variants = {
+  rest: { attrY: WINE_EMPTY, transition: returnTransition },
+  active: { attrY: WINE_LINE, transition: returnTransition },
+  play: {
+    // Sits empty through the squat, rises past the line at the apex, drops
+    // back, settles on the line.
+    attrY: [WINE_EMPTY, WINE_EMPTY, WINE_SLOSH, WINE_LINE + 0.5, WINE_LINE],
+    transition: beats(WINE_TIMES),
+  },
+};
+
+/** The glass squats on its foot as the pour lands, stretches with the rise, settles. */
+const glass: Variants = {
+  rest: { scaleY: 1, transition: returnTransition },
+  active: { scaleY: 1, transition: returnTransition },
+  play: { scaleY: [1, 0.9, 1.03, 0.98, 1], transition: beats(WINE_TIMES) },
+};
+
+const BOWL = "M12 15a5 5 0 0 0 5-5c0-2-.5-4-2-8H9c-1.5 4-2 6-2 8a5 5 0 0 0 5 5Z";
+
+/**
+ * The one gesture that HOLDS on the drinks side: rest is the exact lucide
+ * glyph (empty, line visible), active is the bowl filled to the line. Outline
+ * → solid mass is the largest silhouette change in the set, and at the
+ * segmented control's 16px that is still ~4.7px of rising liquid.
+ */
+export function MotionWine(props: MotionIconProps) {
+  const clipId = useSvgId("wine-bowl");
+
+  return (
+    <MotionIcon {...props}>
+      <defs>
+        <clipPath id={clipId}>
+          <path d={BOWL} />
+        </clipPath>
+      </defs>
+
+      <motion.g variants={glass} style={pivot(12, 22)}>
+        <g clipPath={`url(#${clipId})`}>
+          <motion.rect
+            variants={liquid}
+            fill="currentColor"
+            stroke="none"
+            x="6"
+            y={WINE_EMPTY}
+            width="12"
+            height="12"
+          />
+        </g>
+        <path d="M8 22h8" />
+        <path d="M7 10h10" />
+        <path d="M12 15v7" />
+        <path d={BOWL} />
+      </motion.g>
+    </MotionIcon>
+  );
+}
+
+// ─── Map — a tri-fold map is folded shut and snapped open (articulate) ────────
+
+const MAP_TIMES = [0, 0.2, 0.5, 0.66, 0.84, 1];
+const FOLD = [1, 0.2, 1.18, 0.94, 1.03, 1];
+
+/**
+ * The two outer panels fold in against the middle one (right first, left a
+ * beat behind), then flap open past flat and settle — what you do with a
+ * paper map before reading it. Width 18 → ~8.4 → ~20 → 18.
+ *
+ * `scaleX` around the fold is a 2D stand-in for a hinge (SVG child 3D
+ * transforms are unreliable on iOS Safari); at 22px it reads as "closes, pops
+ * open", which is the intent, not as a true fold.
+ *
+ * Lucide's outline is one closed path; it is cut at the two fold lines,
+ * exactly where the glyph already draws `M9 3.236v15` and `M15 5.764v15`.
+ * Each fold stroke is drawn on the panel that folds around it, so the seams
+ * sit under strokes that are already there at rest.
+ */
+const panelRight: Variants = {
+  rest: { scaleX: 1, transition: returnTransition },
+  active: { scaleX: 1, transition: returnTransition },
+  play: { scaleX: FOLD, transition: beats(MAP_TIMES, 0.62) },
+};
+const panelLeft: Variants = {
+  rest: { scaleX: 1, transition: returnTransition },
+  active: { scaleX: 1, transition: returnTransition },
+  play: { scaleX: FOLD, transition: { ...beats(MAP_TIMES, 0.62), delay: 0.06 } },
+};
+
+export function MotionMap(props: MotionIconProps) {
+  return (
+    <MotionIcon {...props}>
+      {/* Middle panel — the one in your hand — holds still: the two top/bottom runs and the bumps at the x=15 fold. */}
+      <path d="M14.106 5.553a2 2 0 0 0 1.788 0" />
+      <path d="M15.894 20.554a2 2 0 0 1-1.788 0l-4.212-2.106" />
+      <path d="M9.894 3.447 14.106 5.553" />
+      <motion.g variants={panelRight} style={pivot(15, 12)}>
+        <path d="M15.894 5.553l3.659-1.83A1 1 0 0 1 21 4.619v12.764a1 1 0 0 1-.553.894l-4.553 2.277" />
+        <path d="M15 5.764v15" />
+      </motion.g>
+      <motion.g variants={panelLeft} style={pivot(9, 12)}>
+        <path d="M9.894 18.448a2 2 0 0 0-1.788 0l-3.659 1.83A1 1 0 0 1 3 19.381V6.618a1 1 0 0 1 .553-.894l4.553-2.277a2 2 0 0 1 1.788 0" />
+        <path d="M9 3.236v15" />
+      </motion.g>
+    </MotionIcon>
+  );
+}
+
+// ─── Flame — gathers low, flares tall, fills at the peak (deform) ─────────────
+
+const FLAME_TIMES = [0, 0.16, 0.42, 0.58, 0.78, 1];
+
+/**
+ * The trending badge's tap — a gesture, not the loop the badge already runs.
+ * The flame crouches low and wide, bursts up tall and thin with its tip
+ * whipping sideways, fills solid at the peak of the flare, and settles back
+ * to an outline. `skewX` rather than `rotate`: a flame bends in a draft, it
+ * does not tilt rigidly. Pivot at the base (lucide's bottom arc is radius 7,
+ * so the base is y 22, not 15). The inner tongue shares both endpoints with
+ * the outer edge — splitting it would break the closed outline.
+ */
+const flame: Variants = {
+  rest: { scaleY: 1, scaleX: 1, skewX: 0, fillOpacity: 0, transition: returnTransition },
+  active: { scaleY: 1, scaleX: 1, skewX: 0, fillOpacity: 0, transition: returnTransition },
+  play: {
+    scaleY: [1, 0.8, 1.38, 1.18, 0.96, 1],
+    scaleX: [1, 1.15, 0.82, 0.95, 1.03, 1],
+    skewX: [0, 0, -8, 7, -2, 0],
+    fillOpacity: [0, 0, 1, 1, 0.35, 0],
+    transition: beats(FLAME_TIMES),
+  },
+};
+
+export function MotionFlame(props: MotionIconProps) {
+  return (
+    <MotionIcon {...props}>
+      <motion.path
+        variants={flame}
+        style={pivot(12, 22)}
+        fill="currentColor"
+        fillOpacity={0}
+        d="M12 3q1 4 4 6.5t3 5.5a1 1 0 0 1-14 0 5 5 0 0 1 1-3 1 1 0 0 0 5 0c0-2-1.5-3-1.5-5q0-2 2.5-4"
+      />
+    </MotionIcon>
+  );
+}
+
+// ─── Calendar-clock — time runs on the face, and a wedge of it holds ──────────
+
+const CLOCK_TIMES = [0, 0.14, 0.62, 0.8, 1];
+
+/**
+ * The events timeline segment — sibling of `MotionCalendar` (same frame, same
+ * posts) with its own behaviour on the face. The minute hand winds back and
+ * whips a full turn, and behind it a solid wedge of elapsed time sweeps
+ * clockwise from 12, overshoots the hour hand, and settles on it (~4 o'clock,
+ * the 122° the lucide hour hand already points at). HOLDS: the wedge stays
+ * while the timeline is the active view.
+ *
+ * Lucide's hands are 2.2 and 1.9 units long — 1.5px at 16px — so the hand's
+ * whip is the cause and near-invisible on its own; the wedge is load-bearing.
+ * It is a circle of radius 2 stroked 4 wide with butt caps (a stroke as wide
+ * as its radius is a pie), rotated so `pathLength` starts at 12 o'clock — the
+ * set's way of drawing progress without a `d` morph. Outer radius 4 leaves a
+ * ring between wedge and rim so the face still reads as a face.
+ */
+const minuteHand: Variants = {
+  rest: { rotate: 0, transition: returnTransition },
+  active: { rotate: 0, transition: returnTransition },
+  play: { rotate: [0, -14, 372, 360, 360], transition: beats(CLOCK_TIMES, 0.62) },
+};
+const elapsed: Variants = {
+  rest: { pathLength: 0, transition: returnTransition },
+  active: { pathLength: 0.34, transition: returnTransition },
+  play: { pathLength: [0, 0, 0.42, 0.31, 0.34], transition: beats(CLOCK_TIMES, 0.62) },
+};
+
+export function MotionCalendarClock(props: MotionIconProps) {
+  return (
+    <MotionIcon {...props}>
+      <path d="M21 7.5V6a2 2 0 0 0-2-2H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h3.5" />
+      <path d="M16 2v4" />
+      <path d="M8 2v4" />
+      <path d="M3 10h5" />
+      <circle cx="16" cy="16" r="6" />
+      {/* `pathLength={1}` + `strokeDasharray="0 1"` is exactly what framer
+          writes for `pathLength: 0`; without them the first paint — before the
+          pose effect runs — is an un-dashed circle, i.e. a solid disc on the
+          face for one frame on every mount. Same trap `MotionCheck` guards. */}
+      <g transform="rotate(-90 16 16.2)">
+        <motion.circle
+          variants={elapsed}
+          cx="16"
+          cy="16.2"
+          r="2"
+          strokeWidth={4}
+          strokeLinecap="butt"
+          pathLength={1}
+          strokeDasharray="0 1"
+        />
+      </g>
+      <motion.path variants={minuteHand} style={pivot(16, 16.2)} d="M16 14v2.2" />
+      <path d="M16 16.2l1.6 1" />
+    </MotionIcon>
+  );
+}
+
+// ─── List — a row is picked up and reinserted at the top (articulate) ─────────
+
+const LIST_TIMES = [0, 0.14, 0.62, 0.8, 1];
+
+/**
+ * The events list segment. The bottom row is pressed, lifts off the page
+ * toward the reader, travels up past the other two — which drop a slot each
+ * to make way, row 2 first so it clears the mover's path — and lands in the
+ * top slot. The end picture is the same three-row list; the values are one
+ * slot on, and `useIconGesture` snaps them. Active = rest, like the grid:
+ * no held pose survives 16px on this geometry (ragged line lengths, bigger
+ * bullets, a shifted row all fall under the floor and read as a defect), so
+ * colour and stroke weight carry selection.
+ */
+const mover: Variants = {
+  rest: { y: 0, x: 0, scale: 1, transition: returnTransition },
+  active: { y: 0, x: 0, scale: 1, transition: returnTransition },
+  play: {
+    y: [0, 1.5, -15.2, -13.6, -14],
+    x: [0, 0, 2.5, 0.6, 0],
+    scale: [1, 1, 1.06, 1.02, 1],
+    transition: beats(LIST_TIMES, 0.6),
+  },
+};
+const dropSlot = (delay: number): Variants => ({
+  rest: { y: 0, transition: returnTransition },
+  active: { y: 0, transition: returnTransition },
+  play: { y: [0, 0, 7.6, 6.7, 7], transition: { ...beats([0, 0.22, 0.62, 0.8, 1], 0.6), delay } },
+});
+const rowFirst = dropSlot(0.07);
+const rowSecond = dropSlot(0);
+
+function ListRow({ y }: { y: number }) {
+  return (
+    <>
+      <path d={`M3 ${y}h.01`} />
+      <path d={`M8 ${y}h13`} />
+    </>
+  );
+}
+
+export function MotionList(props: MotionIconProps) {
+  return (
+    <MotionIcon {...props}>
+      <motion.g variants={rowFirst}>
+        <ListRow y={5} />
+      </motion.g>
+      <motion.g variants={rowSecond}>
+        <ListRow y={12} />
+      </motion.g>
+      <motion.g variants={mover} style={pivot(3, 19)}>
+        <ListRow y={19} />
+      </motion.g>
+    </MotionIcon>
+  );
+}

package/src/components/motion-icon.test.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render } from "@testing-library/react";
+import { act, render } from "@testing-library/react";
 import * as React from "react";
 
 import { MotionIcon, pivot } from "./motion-icon";
@@ -13,8 +13,10 @@ import { MotionIcon, pivot } from "./motion-icon";
  */
 const variantsSet: string[] = [];
 const variantsStarted: string[] = [];
+let prefersReducedMotion = false;
 
 vi.mock("framer-motion", () => ({
+  useReducedMotion: () => prefersReducedMotion,
   useAnimationControls: () => ({
     set: (v: string) => variantsSet.push(v),
     start: (v: string) => {
@@ -33,6 +35,7 @@ vi.mock("framer-motion", () => ({
 beforeEach(() => {
   variantsSet.length = 0;
   variantsStarted.length = 0;
+  prefersReducedMotion = false;
 });
 
 describe("MotionIcon", () => {
@@ -156,6 +159,182 @@ describe("MotionIcon", () => {
 
     expect(variantsStarted).toEqual(["play"]);
   });
+
+  it("snaps to the pose the gesture depicts once the performance resolves", async () => {
+    const { rerender } = render(
+      <MotionIcon active={false} replayToken={0}>
+        <path />
+      </MotionIcon>
+    );
+    variantsSet.length = 0;
+
+    // Pointer down, and the navigation it causes flips `active` before the
+    // ~600ms gesture finishes.
+    rerender(
+      <MotionIcon active={false} replayToken={1}>
+        <path />
+      </MotionIcon>
+    );
+    rerender(
+      <MotionIcon active replayToken={1}>
+        <path />
+      </MotionIcon>
+    );
+    await act(async () => {});
+
+    // The grid's tiles end one slot around the board, the calendar's reel four
+    // rows up: same picture, different values. Without this snap the next
+    // `rest` would tween them back and perform the gesture in reverse.
+    expect(variantsStarted).toEqual(["play"]);
+    expect(variantsSet).toEqual(["active"]);
+  });
+
+  it("holds the end pose for a grace period, then snaps to rest when the state never arrives", async () => {
+    vi.useFakeTimers();
+    try {
+      const { rerender } = render(
+        <MotionIcon active={false} replayToken={0}>
+          <path />
+        </MotionIcon>
+      );
+      variantsSet.length = 0;
+
+      rerender(
+        <MotionIcon active={false} replayToken={1}>
+          <path />
+        </MotionIcon>
+      );
+      await act(async () => {});
+      // Resolved, but a route may still be confirming: nothing yet.
+      expect(variantsSet).toEqual([]);
+
+      await act(async () => {
+        vi.advanceTimersByTime(900);
+      });
+      expect(variantsSet).toEqual(["rest"]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("takes the held pose without a second performance when `active` arrives late", async () => {
+    vi.useFakeTimers();
+    try {
+      const { rerender } = render(
+        <MotionIcon active={false} replayToken={0}>
+          <path />
+        </MotionIcon>
+      );
+      variantsSet.length = 0;
+      variantsStarted.length = 0;
+
+      rerender(
+        <MotionIcon active={false} replayToken={1}>
+          <path />
+        </MotionIcon>
+      );
+      await act(async () => {});
+      // A slow route: the gesture has landed, the state lands 850ms after the tap.
+      await act(async () => {
+        vi.advanceTimersByTime(850);
+      });
+      rerender(
+        <MotionIcon active replayToken={1}>
+          <path />
+        </MotionIcon>
+      );
+      await act(async () => {
+        vi.advanceTimersByTime(2000);
+      });
+
+      // One play, one snap to active — no cut to rest in between, no replay.
+      expect(variantsStarted).toEqual(["play"]);
+      expect(variantsSet).toEqual(["active"]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("lets an in-flight gesture land before returning, instead of springing it back mid-slide", async () => {
+    vi.useFakeTimers();
+    try {
+      const { rerender } = render(
+        <MotionIcon active replayToken={0}>
+          <path />
+        </MotionIcon>
+      );
+      variantsSet.length = 0;
+      variantsStarted.length = 0;
+
+      // Tap the current tab (replay), then leave for another within 600ms.
+      rerender(
+        <MotionIcon active replayToken={1}>
+          <path />
+        </MotionIcon>
+      );
+      rerender(
+        <MotionIcon active={false} replayToken={1}>
+          <path />
+        </MotionIcon>
+      );
+      await act(async () => {});
+      await act(async () => {
+        vi.advanceTimersByTime(900);
+      });
+
+      // No `rest` tween was STARTED (that would reverse the grid's tiles);
+      // the settle snapped the values instead.
+      expect(variantsStarted).toEqual(["play"]);
+      expect(variantsSet).toEqual(["rest"]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("under reduced motion skips the performance but still changes state", async () => {
+    prefersReducedMotion = true;
+    const { rerender } = render(
+      <MotionIcon active={false} replayToken={0}>
+        <path />
+      </MotionIcon>
+    );
+    variantsSet.length = 0;
+
+    rerender(
+      <MotionIcon active replayToken={1}>
+        <path />
+      </MotionIcon>
+    );
+    await act(async () => {});
+
+    // Less movement, not less feedback: no `play`, straight to the held pose.
+    expect(variantsStarted).toEqual([]);
+    expect(variantsSet).toEqual(["active"]);
+  });
+
+  it("only the latest of two overlapping performances gets to settle", async () => {
+    const { rerender } = render(
+      <MotionIcon active={false} replayToken={0}>
+        <path />
+      </MotionIcon>
+    );
+    variantsSet.length = 0;
+
+    rerender(
+      <MotionIcon active={false} replayToken={1}>
+        <path />
+      </MotionIcon>
+    );
+    rerender(
+      <MotionIcon active replayToken={2}>
+        <path />
+      </MotionIcon>
+    );
+    await act(async () => {});
+
+    expect(variantsStarted).toEqual(["play", "play"]);
+    expect(variantsSet).toEqual(["active"]);
+  });
 });
 
 /**