npm i visual-ai-editor v2.3.3 · MIT

// select() → describe() → a IA aplica o patch

Edite HTML com IA,
descrevendo e
selecionando.selecionado

Selecione qualquer elemento, descreva a mudança em linguagem natural, e a IA atualiza o seu código — respeitando o seu Design System. Sem reescrever a página do zero.

Testar no playground Ver no GitHub

$ npx visual-ai-editor start copiar

localhost:3000 · demo/index.html

DEMO AO VIVO

Painel de métricas h2.hero-title

Acompanhe conversão, retenção e receita em tempo real.

Ver relatório

✓ Aplicado diff de 1 linha · backup salvo

Aplicar

Gravações reais

O editor de verdade, rodando.

As duas gravações abaixo são o editor real contra a pasta demo/ — seleções reais, round-trips reais no /api/edit, respostas reais. Só o cursor é desenhado, porque a gravação do navegador não captura o ponteiro do sistema.

basic-edit.gifREC

Seleção do título e mudança da cor para indigo com uma instrução em linguagem natural

Editando um elemento

Escolha Select, clique no título, digite make the heading color indigo e aperte Apply. O título volta em indigo usando o token --primary — a IA reutilizou porque o DESIGN.md estava no system prompt, não porque a instrução pediu.

design-warning.gifREC

O servidor rejeitando uma cor fora da paleta e oferecendo Aplicar mesmo assim

Batendo na guarda de paleta

Mesmo fluxo, mas pedindo change the background to pink. Rosa não está nas 17 cores da paleta, então o servidor rejeita a resposta — não a boa vontade do modelo.

▸Os GIFs não cobrem: seleção por área arrasta um retângulo sobre vários blocos e o lápis laça à mão livre. Com vários elementos selecionados, uma instrução só reescreve todos de uma vez.

Playground

Não acredite. Selecione.

Uma simulação fiel do fluxo real: clique num elemento da página fake, escolha uma instrução, aplique — e veja o diff que seria salvo. Tente o rosa pra conhecer a guarda de paleta. Ctrl+Z funciona.

seu-projeto/index.html

Lance mais rápido

Itere na interface que já existe, sem reescrever nada do zero.

Começar agora

visual-ai-editor · toolbar

Nenhum elemento selecionado — clique em algo na página ao lado.

use a cor primária aumente o padding arredonde as bordas mude para rosa 🚫

⚠ warn: #EC4899 não está na paleta do DESIGN.md. O servidor rejeitou a edição.
Aplicar mesmo assim

diff · /api/save

// selecione um elemento e aplique uma edição…

histórico: 0 ediçõesundo/redo: 0 tokens

O fluxo

Três passos, um round-trip.

O editor manda só o contexto necessário pra IA, valida a resposta e aplica a mudança preservando a estrutura do seu projeto.

01 · Selecione

Clique, arraste ou lasso

Um clique num elemento, um retângulo sobre vários, ou um traço livre em volta de um grupo.

02 · Descreva

Em linguagem natural

"Aumente o padding do botão e use a cor primária." O modelo recebe o seu DESIGN.md junto.

03 · Revise & aplique

Você aprova a mudança

Confira o resultado, aplique — e o save vira um diff de 1 linha no arquivo de origem, com backup automático.

linha de diff por save cirúrgico

tokens gastos no undo / redo

presets de provedor na v2

backups por arquivo em .ai-editor/history/

Recursos

O que vem na caixa.

Feito pra iterar em projetos que já existem — não pra gerar tudo do zero.

Seleção visual

Clique, arraste uma área ou desenhe um laço livre em volta dos elementos.

Edições com IA

Descreva em linguagem natural. Adaptadores nativos pra OpenAI-compat, Claude e OpenCode.

Design System na régua

A IA segue seu DESIGN.md. Uma checagem determinística de paleta pega o que o modelo deixa passar.

Saves cirúrgicos

Aplica um patch no arquivo com diffs de 1 linha. Backup automático antes de cada save.

Undo / Redo

Ctrl+Z / Ctrl+Y — instantâneo e sem gastar nenhum token.

Handoff pra agentes

Páginas React/Vue/Angular exportam um manifesto de mudanças em vez de sobrescrever o render.

Framework-agnostic

HTML estático, React, Angular, Vue — ou qualquer framework.

UI EN / pt-BR

Detectada pelo <html lang>, ou definida explicitamente.

Visualizador do DESIGN.md

Abra a referência do seu design system num modal, dentro do próprio editor.

⚡ novo na v2

Provedores de IA

Traga o seu modelo. Qualquer um.

A v2 traz um sistema de adaptadores que detecta o provedor pela URL do endpoint — incluindo suporte nativo à Messages API da Anthropic e aos tiers do OpenCode. Configure tudo pelo novo comando interativo config.

Anthropic (Claude)

novo

Adaptador nativo pra Messages API — x-api-key, anthropic-version e tudo. Padrão claude-sonnet-4.

OpenCode Zen

novo · grátis

Tier gratuito com modelos como deepseek-v4-flash-free e nemotron-3-ultra-free. Só precisa de um token do opencode.ai.

OpenCode Go

novo · $5/mês

Assinatura com catálogo de ponta — padrão kimi-k2.7-code, além de GPT-5.x, GLM e mais.

Groq

Padrão de fábrica: llama-3.3-70b-versatile, rápido e gratuito pra começar.

OpenAI & compat

Qualquer API de chat-completions compatível funciona — OpenAI (padrão gpt-4o), Gemini e afins caem no adaptador universal.

Ollama · LM Studio

Presets locais sem API key: provider:'ollama' resolve o endpoint sozinho — e o config lista os seus modelos instalados.

novo: config interativo

$ npx visual-ai-editor config

? Provider: › Anthropic (Claude)

? Model: › claude-sonnet-4

? API Key: › ****************

✓ salvo em .ai-editor/config.json

(ou global: ~/.config/visual-ai-editor/)

ou direto por flag

$ npx visual-ai-editor config \

--provider opencode-free \

--model deepseek-v4-flash-free \

--skip-validation

✓ Provider: opencode-free

Config local > global — por projeto ou pra sempre.

Guarda de paleta

A cor errada não passa.

O DESIGN.md entra no system prompt em toda edição. E o servidor confere cada resposta contra a paleta: se a cor não existe no design system, a edição é rejeitada — do lado do servidor, não da boa vontade do modelo.

O botão Aplicar mesmo assim reaproveita o HTML que o modelo já devolveu. Sobrescrever custa zero tokens extras.

POST /api/edit

→"mude o fundo para rosa"

←warn: cor fora da paleta

←#EC4899 não está nas 17 cores

Aplicar mesmo assim Cancelar

Frameworks

Do estático ao SPA.

HTML puro ganha injeção automática da toolbar. React, Vue e Angular ganham o fluxo de handoff — nada de DOM sobrescrevendo seu JSX.

<!-- zero-config: npx visual-ai-editor start injeta sozinho -->
<!-- ou, na mão: -->
<script type="module">
  import { init } from '/__ai-editor/ai-editor.esm.js';
  init({ apiBase: '/api' });
</script>
import { useEffect } from 'react';
import AIEditor from 'visual-ai-editor';
import 'visual-ai-editor/dist/ai-editor.css';

export function AIEditorProvider({ children }) {
  useEffect(() => {
    AIEditor.init({ apiBase: '/api' });
    return () => AIEditor.destroy();
  }, []);
  return <>{children}</>;
}
<script setup>
import { onMounted, onUnmounted } from 'vue';
import AIEditor from 'visual-ai-editor';
import 'visual-ai-editor/dist/ai-editor.css';

onMounted(() => AIEditor.init({ apiBase: '/api' }));
onUnmounted(() => AIEditor.destroy());
</script>
// CORS de localhost:* já liberado — ng serve (:4200) funciona direto
ngOnInit() {
  if (!environment.production) {
    AIEditor.init({ apiBase: 'http://localhost:3000' });
  }
}
// opcional: @ai-editor/angular-plugin injeta data-ai-source
// no ng serve — habilita o handoff igual React/Vue

HTML estático / SSR

Patch cirúrgico

O cliente manda pares { before, after } do trecho exato que mudou. O servidor localiza e substitui só aquilo.

Formatação, comentários e indentação intactos no resto
Diffs de git minúsculos — uma linha, não o arquivo inteiro
Backup com timestamp em .ai-editor/history/ antes de cada save
Se o before não é achado, cai pro snapshot completo — sem susto

React / Vue / Angular

Handoff pra agente

Escrever DOM renderizado por cima de JSX corromperia tudo. Então nada é escrito na origem — a edição vira uma entrada num manifesto.

Cada edição vai pra .ai-editor/pending-changes.md
Local de origem detectado, instrução e HTML antes/depois
Abra com Claude Code, Cursor & cia. e mande aplicar na origem real
Origem vem de _debugSource, __file ou data-ai-source

Linha de comando

Zero-config pra começar.

Um comando sobe o servidor, abre o navegador e injeta a toolbar em toda página .html servida.

bash

[ai-editor] DESIGN.md loaded (6784 chars, 17 cores)

[ai-editor] server at http://localhost:3000

[visual-ai-editor] Editor no ar ✓

[visual-ai-editor] Toolbar injetada ✓

start

Sobe o editor no diretório atual (padrão).

config

Configura provedor, modelo e chave — interativo ou por flags.v2

design:init

Escreve o DESIGN.prompt.md — um roteiro guiado pra gerar seu DESIGN.md.

design:check

Diz quais das 11 seções recomendadas já existem no seu DESIGN.md.

design:lint

Acha cores fora da paleta no CSS/HTML/JS do projeto.

agents:init

Instala ou atualiza o AGENTS.md (normalmente automático).

--port <n>

Porta do servidor (padrão 3000).

--no-inject

Serve sem injetar a toolbar automaticamente.

--no-open

Não abre o navegador sozinho.

--skip-validation

Pula o health check da API key no config — útil pra modelos locais.2.1

Click

Selecionar elemento

Drag

Selecionar área

Freehand

Laço livre

Ctrl + Z

Desfazer

Ctrl + Y

Refazer

Segurança

Ferramenta de dev, por padrão.

Pensada pra desenvolvimento e staging

A API fica sem autenticação a menos que você defina apiToken. O servidor estático bloqueia .git, node_modules e .env*.

Em NODE_ENV=production sem token, o servidor se recusa a iniciar — em vez de expor um editor silenciosamente. Pra produção de verdade, coloque atrás da sua camada de auth (proxy, VPN) e use o apiToken como segunda camada.

Edite HTML com IA,descrevendo eselecionando.selecionado