MotionWorks

AIコーディングエージェントで構築されたプロジェクトのための、直接操作型モーション設計レイヤー。

MotionWorksはローカルアプリ上で動作し、実際の要素を選択して、モーションを感覚で調整し、再生して、元の状態と比較し、結果を適用できます。調整可能な値はCSSカスタムプロパティに格納されるため、ブラウザですぐにプレビューでき、ローカルデーモンが正確な変更をソースに書き戻せます。

記述して作成。操作して洗練。

クイックスタート

単一のパッケージをインストールして、プロジェクトを初期化します:

npm install -D motionworks
npx motionworks init

init は .motionworks/ を .gitignore に追加し、古いMotionWorks MCPエントリが存在すれば削除し、生成された MOTIONWORKS.md ガイドと、Claude CodeおよびCodex用の短い参照スタンザを書き込みます。Reactプロジェクトでは、必要に応じてパッケージのインストールも確認します。

アプリとMotionWorksデーモンを別々のターミナルで起動します:

npm run dev
npx motionworks

Reactの場合は、生成されたガイドに従って、開発時のみの独立したReactルートに MotionWorksProvider を一度マウントします。その他のページでは、</body> の前にスタンドアロンオーバーレイを読み込みます:

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

MotionWorksは静的ディレクトリを提供し、オーバーレイを自動的に注入することもできます:

npx motionworks serve .

Related MCP server: convey

CSS契約

各調整可能な値には、登録された要素のルール内の実際のスタイルシートに、正規の宣言が1つあります:

.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 を使用できます。

Applyで起こること

Applyは自動化される前に、まず永続化されます:

1. オーバーレイが .motionworks/changes.json にエントリを追加します。

2. デーモンが一致する一意のCSS宣言を直接編集します。

3. 宣言が曖昧な場合、デーモンは利用可能な場合はClaudeまたはCodexを実行します。

4. エージェントが完了できない場合、エントリはCopy promptと npx motionworks changes のために保留のままになります。

エージェントはリストされた宣言のみを正確に変更し、npx motionworks ack <id> で手動の書き戻しを確認します。npx motionworks status は、デザイナーが「これ」と言及したときに、現在選択されているエフェクトを報告します。

パッケージエクスポート

このリポジトリには、公開可能なパッケージが1つ、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 の下に1つのパッケージがあります。tsupでビルドし、Vitestでテストします。

npm install
npm run build
npm run typecheck
npm test

完了した0.5.0ブリッジ再構築は docs/plans/bridge-rebuild.md に記録されています。維持されているアーキテクチャと契約は docs/ にあります。

ライセンス

MIT © John Kim