MotionWorks

Una capa de diseño de movimiento de manipulación directa para proyectos creados con agentes de codificación con IA.

MotionWorks se ejecuta sobre tu aplicación local para que puedas seleccionar un elemento real, ajustar el movimiento de forma intuitiva, reproducirlo, compararlo con el original y aplicar el resultado. Los valores ajustables residen en propiedades personalizadas de CSS, de modo que el navegador puede previsualizarlos de inmediato y el demonio local puede volver a escribir cambios precisos en el código fuente.

Describe para crear. Manipula para refinar.

Inicio rápido

Instala el paquete único e inicializa el proyecto:

npm install -D motionworks
npx motionworks init

init añade .motionworks/ a .gitignore, elimina una entrada MCP obsoleta de MotionWorks si existe, y escribe una guía generada MOTIONWORKS.md además de un breve bloque de referencia para Claude Code y Codex. En proyectos React también confirma la instalación del paquete cuando es necesario.

Inicia tu aplicación y el demonio de MotionWorks en terminales separadas:

npm run dev
npx motionworks

Para React, sigue la guía generada para montar MotionWorksProvider una vez en una raíz de React independiente y solo para desarrollo. Para cualquier otra página, carga la superposición independiente antes de </body>:

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

MotionWorks también puede servir un directorio estático e inyectar la superposición automáticamente:

npx motionworks serve .

Related MCP server: pincushion-mcp

El contrato CSS

Cada valor ajustable tiene una declaración canónica en una hoja de estilos real, en la regla del elemento registrado:

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

Los efectos de React registran solo el esquema. El hook lee las líneas base desde CSS; el código del efecto las consume con readParams y responde a motionworks:change mediante 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" />;
}

El HTML plano puede registrar el mismo esquema con data-motionworks y usar window.MotionWorks.readParams / window.MotionWorks.onParamsChange.

Qué ocurre al aplicar

Aplicar es persistente antes que automático:

1. La superposición añade una entrada a .motionworks/changes.json.

2. El demonio edita directamente la declaración CSS única que coincide.

3. Si la declaración es ambigua, el demonio ejecuta Claude o Codex cuando están disponibles.

4. Si ningún agente puede completarla, la entrada permanece pendiente para Copiar prompt y npx motionworks changes.

El agente cambia exactamente las declaraciones listadas y confirma una escritura manual con npx motionworks ack <id>. npx motionworks status informa del efecto seleccionado actualmente cuando un diseñador se refiere a «este».

Exportaciones del paquete

El repositorio tiene un paquete publicable, motionworks:

React y ReactDOM son dependencias opcionales; las páginas no React utilizan el paquete independiente.

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

La ejecución automática de agentes se habilita cuando se encuentra claude o codex. Usa --no-agent para una transferencia manual o --agent=claude|codex|off para elegir explícitamente. El demonio se vincula a 127.0.0.1:52340; MOTIONWORKS_PORT o --port cambia el puerto.

Desarrollo

El repositorio es un workspace de npm con un paquete en packages/motionworks. Se compila con tsup y se prueba con Vitest.

npm install
npm run build
npm run typecheck
npm test

La reconstrucción completada del puente 0.5.0 está documentada en docs/plans/bridge-rebuild.md; la arquitectura y los contratos vigentes se encuentran en docs/.

Licencia

MIT © John Kim