Feedback Collector

Coletor de feedback visual para desenvolvimento assistido por IA. Você navega pelo seu app em dev, segura ALT, clica nos elementos que quer mudar, escreve uma instrução curta para cada um e, no final, exporta um backlog em markdown — com source mapping (arquivo:linha) — pronto para colar de uma vez no Claude Code ou em outro agente de código.

O problema

O fluxo atual de iteração visual com agentes de código é serial: você aponta um elemento, descreve a mudança, espera o agente executar, e só então aponta o próximo. Para quem trabalha com design e front-end, isso é lento por dois motivos: descrever coisas visuais em texto é impreciso, e o ciclo clica-espera-clica desperdiça o tempo em que você já sabe as próximas cinco mudanças que quer fazer.

A ideia central deste projeto é desacoplar a coleta da execução. Você acumula feedbacks anotados enquanto navega (como faria numa ferramenta de revisão tipo Pastel ou BugHerd), e despeja tudo de uma vez para a IA — mas com um payload técnico que ferramentas de anotação para humanos não capturam: elemento DOM, seletor estável, computed styles e, principalmente, o mapeamento para o arquivo e linha no código-fonte.

Posicionamento (o que já existe e qual é o gap)

| Ferramenta | O que faz | Por que não resolve | |---|---|---| | stagewise | Toolbar que conecta seleção de elementos a agentes no editor | Fluxo orientado a execução imediata, não a backlog em lote; empresa pivotando para browser/IDE próprios | | Pastel / BugHerd | Anotação visual em site vivo, comentários viram tarefas | Output para humanos ("o botão tá grande"); sem acesso ao código, source mapping é arquitetonicamente impossível | | Frontman | Mapeamento DOM → arquivo/linha, BYOK | Sem modelo de fila + flush em lote | | Chrome DevTools MCP | Dá contexto de browser ao agente | Bare-bones, sem coleta acumulada nem anotação |

O gap: fila persistente de feedbacks anotados + payload técnico com source mapping + export em lote otimizado para agentes. É isso que este projeto entrega.

Estado atual: POC empacotada

A POC é um único arquivo (src/feedback-collector.js) em JavaScript vanilla, sem dependências, sem backend, sem build — agora publicado como package npm (feedback-collector) e instalado em um primeiro projeto de produção real (ver docs/decisoes.md). Ela existe para validar a hipótese mais arriscada do projeto:

Um backlog source-mapeado despejado de uma vez faz o Claude Code acertar os arquivos e produzir edits coerentes, de forma mais rápida que o fluxo serial atual.

Deliberadamente fora do escopo da POC: extensão de navegador, screenshots, auth, persistência em servidor, MCP, multi-usuário. Nada disso valida a hipótese; tudo isso é v1 em diante.

Setup

1. Instale o package:

   npm i -D feedback-collector

2. Carregue via import dinâmico (o script é um side effect — injeta o picker ao ser importado):

   // Em um componente raiz (App.tsx, _app.tsx, layout.tsx...)
   if (process.env.NODE_ENV === 'development') {
     import('feedback-collector');
   }

   Em app com auth dá para ir além de dev: renderizar o loader server-side condicionado ao papel do usuário (ex. só owner/admin) e usar o picker em produção, contra dados reais — o script só lê o DOM que o próprio usuário já vê. Sites sem build: use o IIFE cru em feedback-collector/script via <script src>.

3. Configure o source mapping (é ele que injeta arquivo:linha no DOM):

   npm i -D @react-dev-inspector/babel-plugin

   e plugue no bundler — receitas testadas por stack (Next webpack, Vite, prod vs dev, armadilhas do Babel 8) em skills/feedback-collector-setup/SKILL.md, que também serve de skill para agentes de código instalarem/removerem isso sozinhos.

   ⚠️ React 19: o fallback via fiber (_debugSource) foi removido do React 19 — sem o plugin de build não há arquivo:linha (o resto do payload continua funcionando).

Uso

Segure ALT para entrar em modo picker — os elementos ganham highlight com o nome do arquivo no tooltip. ALT + clique captura o elemento e abre um campo para sua instrução ("diminuir o padding", "esse botão deveria ser secundário"). O painel no canto inferior direito acumula os itens; eles persistem em localStorage, então sobrevivem a reload e navegação. Quando terminar a sessão, "Copiar backlog" gera o markdown numerado no clipboard — cole no Claude Code e peça para executar.

O contador "N com source" no header do painel é o termômetro da POC: se a maioria dos itens está sendo capturada sem source mapping, o problema está no setup do plugin, e vale resolver antes de testar o flush.

Como o script funciona por dentro

O script é auto-executável (IIFE) e se protege contra dupla injeção via flag em window. Ele opera em quatro camadas:

1. Picker (interação)

Listeners globais de teclado e mouse em fase de captura (capture: true, para interceptar antes do app). Segurar ALT ativa o modo picker; um div overlay com pointer-events: none segue o cursor usando document.elementFromPoint + getBoundingClientRect, desenhando o highlight. No clique, preventDefault + stopPropagation impedem que a ação real do elemento dispare (um botão não é clicado de verdade), e o elemento é capturado.

2. Extração do payload (a inteligência)

Para cada elemento capturado, o script monta um objeto com:

• Source mapping, em ordem de tentativa: (a) atributos data-inspector-relative-path/-line/-column injetados pelo react-dev-inspector no elemento ou em ancestrais; (b) fallback lendo o fiber interno do React (_debugSource, disponível em dev builds do React < 19), subindo a árvore de owners; (c) se nada disso existir, o item fica sem source, mas ainda carrega o resto do payload.
• Cadeia de componentes: nomes dos ~3 componentes React mais próximos, extraídos do fiber, úteis quando não há arquivo:linha.
• Seletor CSS estável: prioriza id, depois atributos estáveis (data-testid, aria-label, name), depois classes — filtrando classes que parecem geradas por hash/CSS Modules — e por fim nth-of-type. Para de subir na árvore assim que o seletor parcial já é único no documento.
• Computed styles curados: um subconjunto de ~20 propriedades relevantes a layout e aparência, descartando valores default barulhentos (none, auto, 0px...). Isso mantém o payload pequeno sem perder o que importa para ajustes visuais.
• Contexto: rota atual, tag, texto visível (truncado), outerHTML truncado em 600 chars, bounding box e viewport.

3. Fila (estado)

Array em memória espelhado em localStorage a cada mutação. Observação: localStorage é por origem, então localhost:3000 e localhost:5173 têm filas independentes. Não há servidor nem escrita em disco — tudo vive no navegador.

4. Painel e export (saída)

O painel é DOM puro injetado pelo próprio script (re-render por innerHTML a cada mudança — suficiente para a POC). O export concatena os itens em markdown numerado: título com a instrução, rota, arquivo:linha, seletor, styles atuais e o HTML do elemento em bloco de código. O cabeçalho do markdown já instrui o agente a agrupar edits do mesmo arquivo — mitigação barata para o risco de dispersão em backlogs grandes.

Decisão de design: sem screenshot (por enquanto)

Cada screenshot custa ~1 a 1,8k tokens; um backlog de 15 itens com prints estoura contexto rápido. A aposta da POC é que, para ajustes de layout e estilo, source mapping + DOM + styles + instrução textual bastam. Captura visual só entra se o teste mostrar que não basta — e aí no formato econômico: um screenshot de página com pins numerados + crops apertados por elemento.

Compatibilidade

| Camada | React (Next, Vite, CRA) | Vue / Svelte | Site sem build (HTML, CMS) | |---|---|---|---| | Picker, painel, fila, export | ✅ | ✅ | ✅ | | Seletor, styles, HTML | ✅ | ✅ | ✅ | | Source mapping (arquivo:linha) | ✅ via babel-plugin (obrigatório em React 19 — fiber fallback morreu) | 🔧 pequeno ajuste (vue-inspector / Svelte inspector injetam atributos análogos) | ❌ (menos grave: o agente acha via grep no HTML) |

A captura em si é framework-agnostic; só o source mapping é acoplado. Suportar Vue/Svelte é acrescentar os atributos deles na função getSourceInfo (~10 linhas).

Critérios de sucesso da POC

Medir em uma sessão real de trabalho, cronometrada contra o fluxo atual:

1. Precisão: o agente vai direto no arquivo certo, sem caçar?
2. Coerência em lote: um backlog de ~10 itens produz edits coerentes, ou o agente dispersa e mistura contexto? Se degradar, as respostas prováveis são agrupar o export por arquivo/proximidade ou capar em N itens por flush.
3. Velocidade: foi mais rápido que o clica-espera-clica atual?

Se os três derem verde, há produto. Se o item 2 falhar, o valor está no source mapping por clique (não no lote), o que muda o desenho da v1.

Próximos passos

Curto prazo (validação)

• [ ] Rodar a POC em 1–2 projetos reais e medir os três critérios acima
• [ ] Testar o limite do lote: em que N de itens o agente começa a dispersar?
• [ ] Adicionar suporte a atributos do vue-inspector / Svelte inspector no getSourceInfo

v1 (se a POC validar)

• [x] Empacotar como dev-dependency npm (npm i -D feedback-collector), modelo ESLint/Storybook: instalação por projeto
• [x] Skill para agentes de código instalarem/removerem sozinhos (skills/feedback-collector-setup/)
• [ ] Embutir o plugin de source mapping no pacote (Vite/Babel/SWC), eliminando o react-dev-inspector como passo separado
• [ ] Export agrupado por arquivo/proximidade, se o teste de lote indicar necessidade
• [ ] Nível 1 de integração: endpoint dev local que grava .feedback/backlog.md no repo — o agente lê o arquivo em vez de receber colagem
• [ ] Melhorias de UX no painel: reordenar itens, marcar como resolvido, pausar coleta por iteração (padrão Pastel)

v2 (exploração)

• [ ] Captura visual econômica: screenshot de página com pins numerados + crops por elemento, opt-in
• [ ] Integração via MCP para flush direto no agente, sem clipboard
• [ ] Sessões nomeadas / múltiplos backlogs por projeto

Explicitamente fora de escopo por ora: extensão de navegador (perderia o acesso ao build e, com ele, o source mapping — que é o diferencial), auth, backend, multi-usuário.

Estrutura do repo

feedback-collector/
├── README.md                 # este documento
├── package.json              # publicado no npm como `feedback-collector`
├── src/
│   ├── feedback-collector.js # o script (IIFE, side effect)
│   ├── index.js              # entry ESM (import 'feedback-collector')
│   └── index.d.ts            # tipos (package sem API — só side effect)
├── skills/
│   └── feedback-collector-setup/
│       └── SKILL.md          # skill p/ agentes: instalar/remover por stack
└── docs/
    └── decisoes.md           # registro de decisões conforme a POC evolui

Licença

MIT (observar que stagewise é AGPL, o que restringe reuso direto de código deles).