MotionWorks

Слой моушн-дизайна с прямым манипулированием для проектов, создаваемых ИИ-агентами кодирования.

MotionWorks работает поверх вашего локального приложения, позволяя выбрать реальный элемент, настроить движение «на ощупь», воспроизвести его, сравнить с оригиналом и применить результат. Настраиваемые значения хранятся в CSS-кастомных свойствах, поэтому браузер может сразу показать предпросмотр, а локальный демон — записать точные изменения обратно в исходный код.

Опиши, чтобы создать. Манипулируй, чтобы уточнить.

Быстрый старт

Установите единственный пакет и инициализируйте проект:

npm install -D motionworks
npx motionworks init

init добавляет .motionworks/ в .gitignore, удаляет устаревшую запись MCP для MotionWorks, если она есть, и записывает сгенерированное руководство 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 и реагирует на motionworks:change через onParamsChange:

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.

Что происходит при Apply

Apply — это сначала долговечно, а потом автоматически:

1. Оверлей добавляет запись в .motionworks/changes.json.

2. Демон напрямую редактирует единственное совпадающее объявление CSS.

3. Если объявление неоднозначно, демон запускает Claude или Codex, если они доступны.

4. Если ни один агент не может завершить задачу, запись остаётся в ожидании для Copy prompt и 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 меняет порт.

Разработка

Репозиторий — это npm-воркспейс с одним пакетом в packages/motionworks. Он собирается с помощью tsup и тестируется с помощью Vitest.

npm install
npm run build
npm run typecheck
npm test

Завершённая перестройка моста 0.5.0 задокументирована в docs/plans/bridge-rebuild.md; поддерживаемая архитектура и контракты живут в docs/.

Лицензия

MIT © John Kim