Vecta

Runtime de animacao vetorial para Flutter, otimizado para geracao por agentes de IA.

Vecta anima arquivos SVG diretamente em apps Flutter usando uma API declarativa em Dart. Sem editor visual, sem ferramentas proprietarias -- toda animacao e descrita em codigo ou JSON e pode ser gerada, inspecionada e modificada por LLMs.

Como funciona

SVG  ->  VectaParser  ->  VectaScene (IR)  ->  VectaRuntime  ->  VectaPainter  ->  Canvas Flutter

1. O SVG e a fonte de verdade (exportado do Figma, Illustrator ou escrito a mao)
2. O parser converte para uma Intermediate Representation (IR)
3. O runtime aplica bones, keyframes e state machines
4. O painter renderiza no Canvas nativo do Flutter (Skia/Impeller)

Estrutura

vecta/
  packages/
    vecta_parser/     # SVG -> IR (Dart puro)
    vecta_state/      # State machine engine (Dart puro)
    vecta_bones/      # Bone/rigging + FK (Dart puro)
    vecta_core/       # Runtime principal (Dart puro)
    vecta_flutter/    # Widget, Controller, Painter (Flutter)
  tools/
    vecta_cli/        # CLI: inspect, validate
  examples/
    character_demo/   # Demo Dart puro (console)
    vecta_demo/       # Demo Flutter app
    web_demo/         # Demo HTML/JS standalone
  docs/
    format-spec.md    # JSON Schema do formato .vecta
    ai-guide.md       # Guia para agentes de IA

Quick start

Setup

git clone https://github.com/seu-usuario/vecta
cd vecta
dart pub global activate melos
melos bootstrap

Uso no Flutter

# pubspec.yaml
dependencies:
  vecta_flutter:
    path: packages/vecta_flutter

import 'package:vecta_flutter/vecta_flutter.dart';

class MyPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return VectaWidget(
      svgString: mySvgString,
      width: 300,
      height: 300,
      onReady: (controller) {
        // Montar rig
        controller.runtime!.rig(bones: [
          BoneDef(name: 'root', bindTo: ['body']),
          BoneDef(name: 'armLeft', parent: 'root', bindTo: ['armLeft']),
        ]);

        // Adicionar animacao
        controller.runtime!.addAnimation(AnimationDef(
          name: 'wave',
          duration: const Duration(milliseconds: 1000),
          loop: true,
          keyframes: [
            Keyframe(time: 0,    bone: 'armLeft', rotation: 0),
            Keyframe(time: 500,  bone: 'armLeft', rotation: 45, easing: Easing.easeInOut),
            Keyframe(time: 1000, bone: 'armLeft', rotation: 0,  easing: Easing.easeInOut),
          ],
        ));

        // Adicionar state machine
        controller.runtime!.addStateMachine(StateMachineDef(
          name: 'main',
          initialState: 'idle',
          states: {
            'idle':   StateDef(animation: null),
            'waving': StateDef(animation: 'wave'),
          },
          transitions: [
            TransitionDef(from: 'idle', to: 'waving', on: 'wave'),
            TransitionDef(from: 'waving', to: 'idle', on: 'stop'),
          ],
        ));

        // Disparar evento
        controller.send('main', 'wave');
      },
    );
  }
}

Uso programatico (Dart puro)

import 'package:vecta_core/vecta_core.dart';

final runtime = VectaRuntime.fromSvg(svgString);

// Inspecionar nodes disponiveis
print(runtime.namedNodes); // ['body', 'armLeft', 'armRight', ...]

// Criar rig, animacoes e state machine
runtime.rig(bones: [...]);
runtime.addAnimation(AnimationDef(...));
runtime.addStateMachine(StateMachineDef(...));

// Simular frames
runtime.send('main', 'walk');
runtime.update(const Duration(milliseconds: 16));

CLI

dart run tools/vecta_cli/bin/vecta_cli.dart inspect arquivo.svg
dart run tools/vecta_cli/bin/vecta_cli.dart validate arquivo.vecta

Exemplos

Exemplo	Descricao	Como rodar
examples/character_demo	Demo console com walk/jump/idle	cd examples/character_demo && dart run bin/main.dart
examples/vecta_demo	App Flutter com controles interativos	cd examples/vecta_demo && flutter run
examples/web_demo	Preview web standalone (HTML/JS)	Abrir examples/web_demo/index.html no navegador

Testes

# Todos os pacotes Dart puros
melos run test

# Pacote Flutter
cd packages/vecta_flutter && flutter test

# Pacote individual
cd packages/vecta_parser && dart test

Stack

Camada	Tecnologia
Linguagem	Dart (SDK >= 3.3)
Pacotes puros	vecta_parser, vecta_state, vecta_bones, vecta_core
Flutter	vecta_flutter (Canvas API, CustomPainter)
Monorepo	melos
Renderizacao	Skia / Impeller

Principios

• AI-first -- toda animacao descrita com nomes e valores relativos, sem coordenadas brutas
• Dart puro no core -- logica testavel sem Flutter SDK
• JSON e a verdade -- tudo serializavel e inspecionavel
• Canvas nativo -- zero dependencias de renderizacao de terceiros
• Erros descritivos -- nome nao encontrado lista os nomes disponiveis

Licenca

MIT