MotionWorks

AI 코딩 에이전트로 구축된 프로젝트를 위한 직접 조작 모션 디자인 레이어입니다.

MotionWorks는 로컬 앱 위에서 실행되어 실제 요소를 선택하고, 느낌으로 모션을 조정하고, 재생하고, 원본과 비교한 뒤 결과를 적용할 수 있게 합니다. 조정 가능한 값은 CSS 사용자 정의 속성에 들어 있으므로 브라우저가 즉시 미리 볼 수 있고 로컬 데몬이 정확한 변경 사항을 소스에 다시 쓸 수 있습니다.

묘사하여 만들고, 조작하여 다듬으세요.

빠른 시작

단일 패키지를 설치하고 프로젝트를 초기화하세요:

npm install -D motionworks
npx motionworks init

init은 .gitignore에 .motionworks/를 추가하고, 기존의 오래된 MotionWorks MCP 항목이 있으면 제거하며, 생성된 MOTIONWORKS.md 가이드와 Claude Code 및 Codex용 짧은 참조 스탠자를 작성합니다. React 프로젝트에서는 필요한 경우 패키지 설치도 확인합니다.

앱과 MotionWorks 데몬을 별도의 터미널에서 시작하세요:

npm run dev
npx motionworks

React의 경우 생성된 가이드에 따라 MotionWorksProvider를 개발 전용 독립 React 루트에 한 번 마운트하세요. 다른 모든 페이지에서는 </body> 앞에 독립 실행형 오버레이를 로드하세요:

<script src="http://127.0.0.1:52340/motionworks.js"></script>

MotionWorks는 정적 디렉터리를 제공하고 오버레이를 자동으로 주입할 수도 있습니다:

npx motionworks serve .

Related MCP server: pincushion-mcp

CSS 계약

각 조정 가능한 값은 등록된 요소의 규칙에 있는 실제 스타일시트에서 하나의 정식 선언을 가집니다:

.card {
  --mw-radius: 120px;
  --mw-response: 0.18;
}

React 효과는 스키마만 등록합니다. 훅은 CSS에서 기준값을 읽고, 효과 코드는 readParams로 이를 사용하며 onParamsChange를 통해 motionworks:change에 응답합니다:

import { useEffect, useRef } from 'react';
import { onParamsChange, readParams, useMotionWorks } from 'motionworks/react';

const schema = {
  name: 'Magnetic card',
  params: {
    radius: { type: 'spatial-radius', label: 'Radius', unit: 'px' },
    response: { type: 'temporal-response', label: 'Response' },
  },
} as const;

function MagneticCard() {
  const ref = useRef<HTMLDivElement>(null);
  useMotionWorks(ref, schema);

  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    const effect = createMagneticEffect(el, readParams(el, schema.params));
    const sync = () => effect.update(readParams(el, schema.params));
    const stop = onParamsChange(el, sync);
    return () => {
      stop();
      effect.destroy();
    };
  }, []);

  return <div ref={ref} className="card" />;
}

일반 HTML은 data-motionworks로 동일한 스키마를 등록하고 window.MotionWorks.readParams / window.MotionWorks.onParamsChange를 사용할 수 있습니다.

적용 시 발생하는 작업

적용은 자동화되기 전에 먼저 영구적으로 기록됩니다.

1. 오버레이는 .motionworks/changes.json에 항목을 추가합니다.

2. 데몬은 일치하는 고유 CSS 선언을 직접 편집합니다.

3. 선언이 모호하면 데몬은 가능한 경우 Claude 또는 Codex를 실행합니다.

4. 어떤 에이전트도 완료할 수 없으면 항목은 복사 프롬프트 및 npx motionworks changes를 위해 대기 상태로 남습니다.

에이전트는 나열된 선언만 정확히 변경하고 npx motionworks ack <id>로 수동 재기록을 확인합니다. npx motionworks status는 디자이너가 '이것'이라고 지칭할 때 현재 선택된 효과를 보고합니다.

패키지 내보내기

저장소에는 게시 가능한 패키지 motionworks가 하나 있습니다:

React와 ReactDOM은 선택적 피어입니다. React가 아닌 페이지는 독립 실행형 번들을 사용합니다.

CLI

npx motionworks                          Start the local daemon
npx motionworks serve <dir>              Serve a static site with the overlay
npx motionworks changes [--json|--brief] Show pending journal entries
npx motionworks ack <id>|--all           Acknowledge manual writebacks
npx motionworks status                   Show daemon and current selection
npx motionworks revert <id>              Revert an applied entry
npx motionworks init                     Set up the project and agent guide

claude 또는 codex가 발견되면 자동 에이전트 실행이 활성화됩니다. 수동으로 넘기려면 --no-agent를 사용하거나 --agent=claude|codex|off로 명시적으로 선택하세요. 데몬은 127.0.0.1:52340에 바인딩되며, MOTIONWORKS_PORT 또는 --port로 포트를 변경할 수 있습니다.

개발

이 저장소는 packages/motionworks 아래에 하나의 패키지를 둔 npm 워크스페이스입니다. tsup으로 빌드하고 Vitest로 테스트합니다.

npm install
npm run build
npm run typecheck
npm test

완료된 0.5.0 브리지 재구축은 docs/plans/bridge-rebuild.md에 기록되어 있으며, 유지 관리되는 아키텍처와 계약은 docs/에 있습니다.

라이선스

MIT © John Kim