@mt-gloss/motion

Centralized motion-spec architecture for @mt-gloss/* consumers.

• specs.ts — single source of truth for all transition tokens (springs, easings, durations, staggers). Components import named tokens; inline transition props are blocked by ESLint (rule: motion-tokens-only).
• debug.ts — dev-only probe registry + window.__motionDebug bus for Playwright matchers and Chrome MCP exploration.
• MotionDebugHUD.tsx — Ctrl+Shift+M dev overlay showing live probe values.

Usage

import {
  SPRING_CARD_DRAG,
  SPRING_CARD_DROP,
  useMotionProbe,
  MotionDebugHUD,
} from '@mt-gloss/motion';
import { motion, useMotionValue } from 'framer-motion';

function Card({ id }: { id: string }) {
  const x = useMotionValue(0);
  const y = useMotionValue(0);
  const [state, setState] = useState<'idle' | 'dragging' | 'dropping'>('idle');

  useMotionProbe(`card-${id}`, () => ({
    values: { x: x.get(), y: y.get() },
    spec: state === 'dragging' ? SPRING_CARD_DRAG : SPRING_CARD_DROP,
    state,
    t: performance.now(),
  }));

  return (
    <motion.div
      style={{ x, y }}
      transition={state === 'dragging' ? SPRING_CARD_DRAG : SPRING_CARD_DROP}
    />
  );
}

// Mount HUD once at app root (dev-only):
// <MotionDebugHUD />

Key conventions

• Probe IDs are stable. Use card-${item.id}, never card-${index}.
• Reader functions read MotionValues fresh via .get(); never subscribe via React state.
• Never inline transitions. Adding a new motion behavior means adding a token here, not an inline transition={{...}}.
• Production builds tree-shake the registry; window.__motionDebug is dev-only.

See workspace CONVENTIONS.md for the full motion conventions and the Playwright matchers that consume the probe data.