MotionWorks

Eine direkte Manipulations-Ebene für Motion Design für Projekte, die mit KI-Codierungsagenten erstellt werden.

MotionWorks läuft über deiner lokalen App, sodass du ein echtes Element auswählen, Bewegung nach Gefühl einstellen, es erneut abspielen, mit dem Original vergleichen und das Ergebnis anwenden kannst. Einstellbare Werte leben in CSS-Custom-Properties, sodass der Browser sie sofort in der Vorschau anzeigen kann und der lokale Daemon präzise Änderungen zurück in den Quellcode schreiben kann.

Erstellen durch Beschreiben. Verfeinern durch Manipulieren.

Schnellstart

Installiere das einzelne Paket und initialisiere das Projekt:

npm install -D motionworks
npx motionworks init

init fügt .motionworks/ zu .gitignore hinzu, entfernt einen veralteten MotionWorks-MCP-Eintrag, falls vorhanden, und schreibt einen generierten MOTIONWORKS.md-Leitfaden sowie eine kurze Referenz für Claude Code und Codex. Bei React-Projekten bestätigt es außerdem die Paketinstallation, wenn nötig.

Starte deine App und den MotionWorks-Daemon in separaten Terminals:

npm run dev
npx motionworks

Befolge für React den generierten Leitfaden, um MotionWorksProvider einmal in einem nur für die Entwicklung vorgesehenen, unabhängigen React-Root zu mounten. Lade für jede andere Seite das eigenständige Overlay vor </body>:

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

MotionWorks kann auch ein statisches Verzeichnis bedienen und das Overlay automatisch injizieren:

npx motionworks serve .

Related MCP server: pincushion-mcp

Der CSS-Vertrag

Jeder einstellbare Wert hat genau eine kanonische Deklaration in einem echten Stylesheet in der Regel des registrierten Elements:

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

React-Effekte registrieren nur das Schema. Der Hook liest die Baselines aus CSS; Effektcode konsumiert sie mit readParams und reagiert auf motionworks:change über 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" />;
}

Reines HTML kann dasselbe Schema mit data-motionworks registrieren und window.MotionWorks.readParams / window.MotionWorks.onParamsChange verwenden.

Was beim Anwenden passiert

Das Anwenden ist dauerhaft, bevor es automatisch erfolgt:

1. Das Overlay hängt einen Eintrag an .motionworks/changes.json an.

2. Der Daemon bearbeitet die eindeutig passende CSS-Deklaration direkt.

3. Wenn die Deklaration mehrdeutig ist, führt der Daemon Claude oder Codex aus, sofern verfügbar.

4. Wenn kein Agent sie vervollständigen kann, bleibt der Eintrag ausstehend für „Prompt kopieren" und npx motionworks changes.

Der Agent ändert genau die aufgeführten Deklarationen und bestätigt einen manuellen Rückschreibevorgang mit npx motionworks ack <id>. npx motionworks status meldet den aktuell ausgewählten Effekt, wenn ein Designer sich auf „diesen hier" bezieht.

Paketexporte

Das Repository enthält ein veröffentlichbares Paket, motionworks:

React und ReactDOM sind optionale Begleitpakete; Nicht-React-Seiten verwenden das eigenständige Bundle.

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

Die automatische Agentenausführung ist aktiviert, wenn claude oder codex gefunden wird. Verwende --no-agent für manuelle Übergabe oder --agent=claude|codex|off, um explizit zu wählen. Der Daemon bindet an 127.0.0.1:52340; MOTIONWORKS_PORT oder --port ändert den Port.

Entwicklung

Das Repository ist ein npm-Workspace mit einem Paket unter packages/motionworks. Es wird mit tsup gebaut und mit Vitest getestet.

npm install
npm run build
npm run typecheck
npm test

Der abgeschlossene 0.5.0-Bridge-Neuaufbau ist in docs/plans/bridge-rebuild.md dokumentiert; die gepflegte Architektur und die Verträge befinden sich in docs/.

Lizenz

MIT © John Kim