Feedback Collector

Coletor de feedback visual para desenvolvimento assistido por IA. Segure ALT, clique nos elementos que quer mudar, escreva instruções curtas e exporte um backlog markdown com contexto técnico — incluindo arquivo:linha quando o projeto injeta source mapping no DOM.

O projeto continua deliberadamente pequeno: runtime vanilla, zero dependências de runtime, sem backend, screenshots, imagens ou serviços externos. A v0.2 troca a autoria interna por TypeScript modular, adiciona API de ciclo de vida e builds de biblioteca sem quebrar a instalação v0.1.

O problema

O fluxo de iteração visual com agentes costuma ser serial: apontar um elemento, explicar a mudança, esperar e repetir. O Feedback Collector desacopla coleta e execução. Você acumula feedback enquanto navega e entrega de uma vez um payload com rota, seletor estável, DOM, estilos computados e source mapping.

Instalação

npm i -D feedback-collector

O modo compatível continua igual: importar o package auto-inicializa o picker no navegador e é no-op durante SSR.

if (process.env.NODE_ENV === "development") {
  void import("feedback-collector");
}

Em React, carregue de um componente client montado no layout. Em produção, renderize esse loader apenas para usuários autorizados; os atributos de source mapping podem expor a estrutura de paths nos chunks públicos.

Controle programático

Use o entry sem side effect quando quiser controlar explicitamente o ciclo de vida:

import { mount, destroy } from "feedback-collector/api";

const collector = mount(); // idempotente: devolve a instância ativa
collector.items;
collector.exportMarkdown();

destroy(); // remove listeners e todo DOM injetado; a fila persiste
mount();   // pode montar novamente

O entry raiz também exporta mount() e destroy(), mas mantém o auto-mount por compatibilidade. Para controle total, prefira feedback-collector/api.

Script clássico / site sem bundler

feedback-collector/script aponta para o IIFE compilado em dist/feedback-collector.js. Copie esse arquivo para os assets do site ou sirva-o diretamente:

<script src="/vendor/feedback-collector.js"></script>
<script>
  // O IIFE auto-monta e expõe a API global.
  FeedbackCollector.destroy();
  FeedbackCollector.mount();
</script>

Durante a transição da v0.1, src/feedback-collector.js continua publicado e contém o mesmo IIFE. Esse caminho é compatibilidade temporária; novos consumidores devem usar o export feedback-collector/script ou dist/feedback-collector.js.

Source mapping

O runtime lê os atributos já suportados pela v0.1 no elemento ou em seus ancestrais:

• data-inspector-relative-path
• data-inspector-line
• data-inspector-column
• data-source="arquivo:linha:coluna" como convenção alternativa

Para React, a receita validada usa @react-dev-inspector/babel-plugin. Instruções de Next webpack, Vite, uso em produção e remoção estão em skills/feedback-collector-setup/SKILL.md.

React 19 removeu _debugSource do fiber. Sem plugin de build, a captura continua funcionando, mas o item não terá arquivo:linha.

Uso

1. Segure ALT para ativar o picker.
2. Passe o mouse para ver highlight e source no tooltip.
3. Use ALT + clique para capturar sem disparar a ação real do elemento.
4. Escreva a instrução no painel. Use Enter para concluir e tirar o foco do campo, ou Shift+Enter para inserir uma nova linha.
5. Clique em “Copiar backlog” e cole o markdown no agente de código.

Enquanto ALT está pressionado, o painel fica invisível e deixa o mouse atravessá-lo, permitindo capturar elementos que estavam por baixo. Arraste o cabeçalho para mover o painel; ao soltar, ele se encaixa no canto mais próximo.

A fila e o canto escolhido sobrevivem a reloads e navegação SPA. localStorage é por origem, portanto portas diferentes têm filas e preferências independentes.

Persistência e migração segura

A v0.2 usa a chave __fbc_state_v2 com envelope versionado:

{
  "version": 2,
  "items": []
}

Na primeira montagem, se ainda não houver estado v2 válido, o runtime lê o array legado __fbc_items_v1, preserva os objetos completos e grava o envelope v2. A chave v1 não é apagada, permitindo rollback sem perder a fila existente. Depois da migração, novas mutações são gravadas apenas em v2.

Falhas de parse, indisponibilidade ou quota do storage não derrubam a página; o collector segue com estado em memória quando possível.

Arquitetura v0.2

src/
├── api.ts          # entry controlado, sem auto-mount
├── index.ts        # entry ESM compatível, com auto-mount
├── script.ts       # entry IIFE + API global
├── lifecycle.ts    # singleton mount()/destroy()
├── collector.ts    # interação e painel DOM vanilla
├── extract.ts      # source, seletor, styles e payload
├── storage.ts      # schema v2 e migração v1
├── markdown.ts     # export puro
└── types.ts        # contrato público

O build gera:

• dist/index.js + dist/index.d.ts: ESM com auto-inicialização;
• dist/api.js + dist/api.d.ts: ESM programático sem side effect;
• dist/feedback-collector.js: IIFE/script com global FeedbackCollector;
• src/feedback-collector.js: cópia IIFE temporária para consumidores do path v0.1.

Não há dependências em dependencies; TypeScript, tsup, Vitest e Playwright são somente ferramentas de desenvolvimento.

Desenvolvimento e validação

npm install
npx playwright install chromium # necessário uma vez em máquinas sem browser do Playwright
npm run build
npm test
npm run test:browser
npm run size
npm run check

Os testes puros cobrem migração/persistência, export markdown e helpers. O teste Playwright usa Chromium real para verificar auto-mount, ALT+clique, leitura de data-inspector-*, edição, persistência, clipboard, destroy e remontagem.

O orçamento automatizado limita cada runtime a 30 KB raw e 8 KiB gzip. A v0.2 fica em cerca de 5,2 KB gzip; o arquivo v0.1 de referência tinha aproximadamente 6,3 KB gzip.

Integração futura com compiler/bundler

A base desta versão mantém source mapping separado do runtime. Uma integração própria para Next/Vite só deve avançar depois de validar a coleta e o export em projetos reais. O desenho de extensão, critérios e sequência de protótipo estão em docs/integracao-compiler-futura.md. Nenhum plugin próprio foi implementado nesta versão.

Escopo

Incluído agora: runtime vanilla, fila local, source mapping por atributos/fiber legado, API de ciclo de vida, builds ESM/IIFE/tipos, migração segura, testes e orçamento de bundle.

Fora de escopo por enquanto: backend, screenshots, dashboard, auth própria, múltiplos adapters, extensão de navegador, MCP e ecossistema de packages.

Licença

MIT.