feedback-collector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Santos / Bananas Global
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# 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:
+
+   ```bash
+   npm i -D feedback-collector
+   ```
+
+2. Carregue via import dinâmico (o script é um side effect — injeta o picker ao ser importado):
+
+   ```js
+   // 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):
+
+   ```bash
+   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`](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).

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "feedback-collector",
+  "version": "0.1.0",
+  "description": "Coletor de feedback visual para desenvolvimento assistido por IA: ALT+clique nos elementos, anote instruções e exporte um backlog em markdown com source mapping (arquivo:linha) pronto para colar no Claude Code ou outro agente.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./script": "./src/feedback-collector.js"
+  },
+  "sideEffects": true,
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "feedback",
+    "visual-feedback",
+    "dev-tools",
+    "ai",
+    "claude-code",
+    "code-agent",
+    "source-mapping",
+    "react-dev-inspector",
+    "inspector",
+    "annotation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bananas-global/feedback-collector.git"
+  },
+  "homepage": "https://github.com/bananas-global/feedback-collector#readme",
+  "bugs": {
+    "url": "https://github.com/bananas-global/feedback-collector/issues"
+  },
+  "author": "Bruno Santos (https://github.com/brucesantos)",
+  "license": "MIT"
+}

package/skills/feedback-collector-setup/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: feedback-collector-setup
+description: >
+  Instala, configura ou remove o feedback-collector (picker visual ALT+clique →
+  backlog markdown com arquivo:linha) em um projeto front-end. Use quando o
+  usuário pedir para "instalar o feedback-collector", "adicionar o picker de
+  feedback", "configurar source mapping do feedback", "remover/desativar o
+  feedback-collector", ou equivalentes em inglês (install/remove feedback
+  collector, visual feedback picker). Cobre Next.js (webpack), Vite e sites sem
+  build; inclui o caveat de React 19 e o gate para uso em produção.
+---
+
+# feedback-collector: instalar e remover
+
+O package `feedback-collector` é um script client-side puro (IIFE, sem backend):
+segurando ALT o usuário clica em elementos, anota instruções e exporta um
+backlog markdown com `arquivo:linha` para colar em um agente de código. A
+instalação tem DUAS partes independentes:
+
+1. **O script** (picker/painel) — trivial, funciona em qualquer stack.
+2. **O source mapping** (`arquivo:linha`) — exige um plugin de build que injeta
+   `data-inspector-{relative-path,line,column}` no JSX. É a parte com decisões.
+
+Antes de começar, detecte: framework (Next/Vite/CRA/sem build), bundler do dev
+(Next: webpack ou `--turbopack` no script `dev`?), versão do React, e se o
+projeto tem auth (define o gate de produção).
+
+## Parte 1 — o script
+
+```bash
+npm i -D feedback-collector   # ou pnpm add -D
+```
+
+Carregue via componente client montado condicionalmente (React):
+
+```tsx
+// components/feedback-collector-loader.tsx
+"use client"; // (Next App Router)
+import { useEffect } from "react";
+
+export function FeedbackCollector() {
+  useEffect(() => {
+    void import("feedback-collector");
+  }, []);
+  return null;
+}
+```
+
+**Onde renderizar — decisão de gate (pergunte ao usuário se ambíguo):**
+
+- **Só em dev (padrão seguro):** no layout raiz,
+  `{process.env.NODE_ENV === "development" && <FeedbackCollector />}`.
+- **Em produção, gated por usuário:** se o app tem auth e o usuário quer usar o
+  picker contra dados reais de prod, renderize num layout autenticado
+  condicionado ao papel do usuário (ex.: `{isOwner && <FeedbackCollector />}`).
+  O script só lê o DOM que o próprio usuário já vê (não é vetor de vazamento),
+  mas usuários comuns NÃO devem ver o painel. O gate server-side também evita
+  que o chunk seja baixado por quem não usa.
+
+Sites sem build: `<script src="node_modules/feedback-collector/src/feedback-collector.js">`
+(ou copie o arquivo). O entry `feedback-collector/script` aponta pro IIFE cru.
+
+## Parte 2 — source mapping (arquivo:linha)
+
+**Caveat central: React 19 removeu `_debugSource` do fiber.** O fallback interno
+do script não funciona em React 19 — sem plugin de build, os itens saem SEM
+arquivo:linha (o resto funciona: seletor, styles, HTML). Em React ≤18 o fallback
+existe, mas o plugin ainda é mais confiável.
+
+### Next.js (webpack) — receita validada (Next 15, React 19)
+
+```bash
+npm i -D @react-dev-inspector/babel-plugin babel-loader @babel/core @babel/preset-typescript @babel/plugin-syntax-jsx
+```
+
+NÃO crie `.babelrc` (desligaria o SWC do projeto inteiro). Em vez disso, um
+pre-pass só do loader no `next.config.ts`:
+
+```ts
+webpack: (config, { dev }) => {
+  if (dev) { // ver "Em produção?" abaixo antes de remover este gate
+    config.module.rules.unshift({
+      test: /\.(jsx|tsx)$/,
+      exclude: /node_modules/,
+      enforce: "pre",
+      use: [{
+        loader: "babel-loader",
+        options: {
+          babelrc: false, configFile: false, sourceMaps: false,
+          presets: ["@babel/preset-typescript"],
+          // syntax-jsx só PARSEIA (SWC segue fazendo JSX→JS depois)
+          plugins: ["@babel/plugin-syntax-jsx", "@react-dev-inspector/babel-plugin"],
+        },
+      }],
+    });
+  }
+  return config;
+},
+```
+
+Armadilhas conhecidas (Babel 8): `isTSX`/`allExtensions` foram REMOVIDOS do
+preset-typescript — não os passe; use `@babel/plugin-syntax-jsx` pra habilitar
+JSX. Aplique o loader a server E client (só client causa hydration mismatch).
+
+Se o `dev` script usa `--turbopack`: o hook `webpack()` não roda. Opções:
+remover a flag em dev, ou usar `experimental.swcPlugins` (abaixo).
+
+### Next.js — em produção?
+
+Trade-offs de tirar o `if (dev)` (decisão do usuário, nunca automática):
+- Os paths de `src/` ficam embutidos nos chunks JS **públicos** (servidos sem
+  auth) — vazamento de estrutura, severidade baixa mas permanente.
+- O build de produção passa a rodar o pre-pass Babel (mais lento).
+Validado em produção real (Next 15): funciona; documente o trade-off num
+comentário no config.
+
+### Vite (React)
+
+```bash
+npm i -D vite-plugin-react-dev-inspector
+```
+Registre o plugin no `vite.config.ts` ANTES do plugin react (ver docs do
+pacote). Alternativa: `@react-dev-inspector/babel-plugin` via option `babel`
+do `@vitejs/plugin-react`.
+
+### Alternativa SWC (sem Babel)
+
+`experimental.swcPlugins` no Next + `swc-plugin-react-source-string` injeta
+`data-source="arquivo:linha"`. Mantém o SWC (build rápido), MAS: experimental
+desde Next 12.2 (2022, verificado ainda experimental em 2026) e plugins Wasm
+quebram entre versões do `swc_core` do Next. Exige adaptar `getSourceInfo()` no
+script pra ler `data-source` além de `data-inspector-*` (~5 linhas). Só sugira
+se o custo do build Babel for dor explícita.
+
+### Vue / Svelte
+
+`vue-inspector` / inspector do Svelte injetam atributos análogos; hoje exige
+adaptar `getSourceInfo()` no script (não suportado out-of-the-box).
+
+## Verificação (sempre faça)
+
+1. `typecheck`/`lint`/`build` do projeto passam.
+2. Suba o dev server, faça request numa rota e confirme no HTML SSR/DOM:
+   `grep -o 'data-inspector-relative-path="[^"]*"' | sort -u` deve listar
+   paths reais do projeto. Zero ocorrências = plugin não está rodando.
+3. Se ligou em prod: rode o build e confirme `grep -rl data-inspector .next/static`.
+4. No browser: console mostra `[feedback-collector] ativo`; ALT+hover mostra
+   tooltip com o arquivo.
+
+## Remoção
+
+Três níveis — pergunte qual o usuário quer:
+
+1. **Desligar o painel:** remova o `<FeedbackCollector />` do layout. O babel
+   pre-pass continua (atributos ainda no bundle).
+2. **Limpar o build:** re-gate o pre-pass com `if (dev)` (ou remova o bloco
+   `webpack`) — prod volta a SWC puro, sem paths nos chunks.
+3. **Remoção total:** (1) + (2) + deletar o componente loader +
+   `npm rm feedback-collector @react-dev-inspector/babel-plugin babel-loader @babel/core @babel/preset-typescript @babel/plugin-syntax-jsx`
+   + rebuild. Nada toca banco/auth — é tudo client-side + config de build.
+
+Os itens capturados vivem em `localStorage` (chave por origem); remover o
+script não apaga nada sensível.

package/src/feedback-collector.js

@@ -0,0 +1,461 @@
+/**
+ * feedback-collector.js — POC de coletor de feedback visual para Claude Code
+ * ---------------------------------------------------------------------------
+ * USO
+ *   1. (Recomendado) Instale o react-dev-inspector para source mapping:
+ *        npm i -D react-dev-inspector
+ *      e adicione o plugin ao seu bundler (Babel/SWC/Vite — ver docs do pacote).
+ *      Ele injeta data-inspector-relative-path / -line / -column no DOM em dev.
+ *      Sem ele o script ainda funciona, mas cai pro fallback (fiber _debugSource)
+ *      e, em último caso, só seletor CSS.
+ *
+ *   2. Carregue este arquivo SOMENTE em dev. Exemplos:
+ *      - Vite/Next (em um componente raiz ou _app):
+ *          if (process.env.NODE_ENV === 'development') import('./feedback-collector.js')
+ *      - Ou <script src="/feedback-collector.js"></script> no index.html de dev.
+ *
+ * INTERAÇÃO
+ *   - Segure ALT: entra em modo picker (elementos ganham highlight no hover).
+ *   - ALT + clique: captura o elemento e abre campo pra sua instrução.
+ *   - Painel flutuante (canto inferior direito): lista, edita, remove itens.
+ *   - "Copiar backlog": gera markdown numerado no clipboard, pronto pra colar
+ *     no Claude Code.
+ *   - Itens persistem em localStorage (sobrevivem reload e navegação SPA).
+ *
+ * ESCOPO (POC): sem screenshot, sem extensão, sem backend. Teste primeiro se
+ * source mapping + DOM + instrução bastam — provavelmente sim pra layout/estilo.
+ */
+(function () {
+  'use strict';
+  if (window.__FEEDBACK_COLLECTOR__) return;
+  window.__FEEDBACK_COLLECTOR__ = true;
+
+  var STORAGE_KEY = '__fbc_items_v1';
+
+  /* ------------------------------------------------------------------ */
+  /* Estado                                                              */
+  /* ------------------------------------------------------------------ */
+  var items = load();
+  var pickerActive = false;
+  var hoverEl = null;
+
+  function load() {
+    try { return JSON.parse(localStorage.getItem(STORAGE_KEY)) || []; }
+    catch (e) { return []; }
+  }
+  function save() {
+    try { localStorage.setItem(STORAGE_KEY, JSON.stringify(items)); }
+    catch (e) { /* quota — ignora na POC */ }
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Source mapping                                                      */
+  /* ------------------------------------------------------------------ */
+  function getSourceInfo(el) {
+    // 1) react-dev-inspector (data attrs no próprio elemento ou ancestral)
+    var node = el;
+    while (node && node !== document.body) {
+      var p = node.getAttribute && (
+        node.getAttribute('data-inspector-relative-path') ||
+        node.getAttribute('data-source') // convenção alternativa
+      );
+      if (p) {
+        var line = node.getAttribute('data-inspector-line') || '';
+        var col = node.getAttribute('data-inspector-column') || '';
+        return { file: p, line: line, column: col, via: 'data-attr', ownerHops: node === el ? 0 : 1 };
+      }
+      node = node.parentElement;
+    }
+
+    // 2) Fallback: React fiber _debugSource (funciona em dev builds do React <19)
+    var fiber = getFiber(el);
+    var hops = 0;
+    while (fiber && hops < 20) {
+      var src = fiber._debugSource;
+      if (src && src.fileName) {
+        return {
+          file: relativize(src.fileName),
+          line: src.lineNumber || '',
+          column: src.columnNumber || '',
+          via: 'fiber',
+          componentName: fiberName(fiber)
+        };
+      }
+      fiber = fiber._debugOwner || fiber.return;
+      hops++;
+    }
+    return null;
+  }
+
+  function getFiber(el) {
+    for (var k in el) {
+      if (k.indexOf('__reactFiber$') === 0 || k.indexOf('__reactInternalInstance$') === 0) {
+        return el[k];
+      }
+    }
+    return null;
+  }
+
+  function fiberName(fiber) {
+    var f = fiber;
+    while (f) {
+      var t = f.type;
+      if (typeof t === 'function') return t.displayName || t.name || '';
+      if (t && typeof t === 'object' && t.displayName) return t.displayName;
+      f = f._debugOwner || f.return;
+    }
+    return '';
+  }
+
+  function componentChain(el) {
+    // Nome dos 3 componentes React mais próximos, do mais interno pro externo
+    var fiber = getFiber(el);
+    var names = [];
+    var hops = 0;
+    while (fiber && names.length < 3 && hops < 30) {
+      var t = fiber.type;
+      var name = null;
+      if (typeof t === 'function') name = t.displayName || t.name;
+      else if (t && typeof t === 'object' && t.displayName) name = t.displayName;
+      if (name && names.indexOf(name) === -1) names.push(name);
+      fiber = fiber._debugOwner || fiber.return;
+      hops++;
+    }
+    return names;
+  }
+
+  function relativize(fileName) {
+    // Corta caminho absoluto até algo legível (src/, app/, pages/, components/)
+    var m = fileName.match(/(?:^|\/)((?:src|app|pages|components|lib|features)\/.*)$/);
+    return m ? m[1] : fileName;
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Seletor CSS estável                                                 */
+  /* ------------------------------------------------------------------ */
+  function cssSelector(el) {
+    if (el.id) return '#' + CSS.escape(el.id);
+    var parts = [];
+    var node = el;
+    while (node && node.nodeType === 1 && node !== document.body && parts.length < 5) {
+      var part = node.tagName.toLowerCase();
+      var stableAttrs = ['data-testid', 'data-test', 'aria-label', 'name'];
+      var got = false;
+      for (var i = 0; i < stableAttrs.length; i++) {
+        var v = node.getAttribute(stableAttrs[i]);
+        if (v) { part += '[' + stableAttrs[i] + '="' + v + '"]'; got = true; break; }
+      }
+      if (!got && node.classList.length) {
+        // usa até 2 classes que não pareçam geradas (hash/módulo CSS)
+        var cls = Array.prototype.filter.call(node.classList, function (c) {
+          return !/^[a-z]*[_-][a-zA-Z0-9]{5,}$/.test(c) && !/^\d/.test(c) && c.length < 30;
+        }).slice(0, 2);
+        if (cls.length) { part += '.' + cls.map(function(c){ return CSS.escape(c); }).join('.'); got = true; }
+      }
+      if (!got) {
+        var idx = 1, sib = node;
+        while ((sib = sib.previousElementSibling)) {
+          if (sib.tagName === node.tagName) idx++;
+        }
+        if (idx > 1) part += ':nth-of-type(' + idx + ')';
+      }
+      parts.unshift(part);
+      // se o seletor parcial já é único, para
+      try {
+        if (document.querySelectorAll(parts.join(' > ')).length === 1) break;
+      } catch (e) { /* seletor inválido, segue */ }
+      node = node.parentElement;
+    }
+    return parts.join(' > ');
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Computed styles curados                                             */
+  /* ------------------------------------------------------------------ */
+  var BASE_PROPS = ['display', 'position', 'width', 'height', 'margin', 'padding',
+    'color', 'background-color', 'font-size', 'font-weight', 'line-height',
+    'border', 'border-radius', 'gap', 'flex-direction', 'justify-content',
+    'align-items', 'grid-template-columns', 'overflow', 'z-index', 'opacity',
+    'box-shadow', 'text-align'];
+
+  function curatedStyles(el) {
+    var cs = getComputedStyle(el);
+    var out = {};
+    BASE_PROPS.forEach(function (p) {
+      var v = cs.getPropertyValue(p);
+      if (!v) return;
+      // pula valores default barulhentos
+      if (v === 'none' || v === 'normal' || v === 'auto' || v === 'rgba(0, 0, 0, 0)' ||
+          v === '0px' || v === 'visible' || v === 'static' || v === 'start') return;
+      out[p] = v;
+    });
+    return out;
+  }
+
+  function truncatedHTML(el, max) {
+    var html = el.outerHTML || '';
+    if (html.length <= max) return html;
+    // mantém a tag de abertura inteira + começo do conteúdo
+    return html.slice(0, max) + '… [truncado]';
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Captura                                                             */
+  /* ------------------------------------------------------------------ */
+  function capture(el) {
+    var rect = el.getBoundingClientRect();
+    var source = getSourceInfo(el);
+    var item = {
+      id: Date.now() + '_' + Math.random().toString(36).slice(2, 7),
+      url: location.pathname + location.search + location.hash,
+      tag: el.tagName.toLowerCase(),
+      selector: cssSelector(el),
+      source: source,
+      components: componentChain(el),
+      text: (el.textContent || '').trim().slice(0, 120),
+      html: truncatedHTML(el, 600),
+      styles: curatedStyles(el),
+      rect: {
+        x: Math.round(rect.x), y: Math.round(rect.y),
+        w: Math.round(rect.width), h: Math.round(rect.height)
+      },
+      viewport: window.innerWidth + 'x' + window.innerHeight,
+      instruction: '',
+      ts: new Date().toISOString()
+    };
+    items.push(item);
+    save();
+    renderPanel();
+    // foca o textarea do item recém-criado
+    setTimeout(function () {
+      var ta = panel.querySelector('[data-fbc-ta="' + item.id + '"]');
+      if (ta) ta.focus();
+    }, 50);
+    flashElement(el);
+  }
+
+  function flashElement(el) {
+    var prev = el.style.outline;
+    el.style.outline = '3px solid #16a34a';
+    setTimeout(function () { el.style.outline = prev; }, 400);
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Export markdown                                                     */
+  /* ------------------------------------------------------------------ */
+  function toMarkdown() {
+    var lines = ['# Backlog de feedback visual', '',
+      'Gerado em ' + new Date().toLocaleString() + ' — ' + items.length + ' itens.',
+      'Cada item indica o arquivo:linha quando disponível. Execute na ordem, agrupando edits do mesmo arquivo.', ''];
+    items.forEach(function (it, i) {
+      lines.push('## ' + (i + 1) + '. ' + (it.instruction ? it.instruction.split('\n')[0] : '(sem instrução)'));
+      lines.push('');
+      if (it.instruction && it.instruction.indexOf('\n') !== -1) {
+        lines.push(it.instruction);
+        lines.push('');
+      }
+      lines.push('- **Rota:** `' + it.url + '`');
+      if (it.source) {
+        var loc = it.source.file + (it.source.line ? ':' + it.source.line : '');
+        lines.push('- **Source:** `' + loc + '`' + (it.source.componentName ? ' (componente `' + it.source.componentName + '`)' : ''));
+      } else if (it.components && it.components.length) {
+        lines.push('- **Componentes (do mais interno):** ' + it.components.map(function (c) { return '`' + c + '`'; }).join(' → '));
+      }
+      lines.push('- **Elemento:** `<' + it.tag + '>` — seletor: `' + it.selector + '`');
+      if (it.text) lines.push('- **Texto visível:** "' + it.text + '"');
+      lines.push('- **Posição:** ' + it.rect.w + 'x' + it.rect.h + ' @ (' + it.rect.x + ',' + it.rect.y + '), viewport ' + it.viewport);
+      var styleKeys = Object.keys(it.styles);
+      if (styleKeys.length) {
+        lines.push('- **Styles atuais:** ' + styleKeys.map(function (k) {
+          return '`' + k + ': ' + it.styles[k] + '`';
+        }).join(', '));
+      }
+      lines.push('');
+      lines.push('```html');
+      lines.push(it.html);
+      lines.push('```');
+      lines.push('');
+    });
+    return lines.join('\n');
+  }
+
+  function copyBacklog() {
+    var md = toMarkdown();
+    navigator.clipboard.writeText(md).then(function () {
+      toast('Backlog copiado (' + items.length + ' itens). Cola no Claude Code.');
+    }, function () {
+      // fallback: mostra num prompt
+      window.prompt('Copie manualmente:', md);
+    });
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Picker (highlight + clique)                                         */
+  /* ------------------------------------------------------------------ */
+  var highlight = document.createElement('div');
+  highlight.style.cssText = 'position:fixed;pointer-events:none;z-index:2147483645;' +
+    'border:2px solid #2563eb;background:rgba(37,99,235,.08);border-radius:2px;' +
+    'display:none;transition:all .05s linear;';
+  var highlightLabel = document.createElement('div');
+  highlightLabel.style.cssText = 'position:absolute;top:-22px;left:0;background:#2563eb;' +
+    'color:#fff;font:11px/1.4 ui-monospace,monospace;padding:1px 6px;border-radius:2px;white-space:nowrap;';
+  highlight.appendChild(highlightLabel);
+
+  function onKeyDown(e) {
+    if (e.key === 'Alt' && !pickerActive) {
+      pickerActive = true;
+      document.body.style.cursor = 'crosshair';
+    }
+  }
+  function onKeyUp(e) {
+    if (e.key === 'Alt') deactivatePicker();
+  }
+  function deactivatePicker() {
+    pickerActive = false;
+    hoverEl = null;
+    highlight.style.display = 'none';
+    document.body.style.cursor = '';
+  }
+
+  function onMouseMove(e) {
+    if (!pickerActive) return;
+    var el = document.elementFromPoint(e.clientX, e.clientY);
+    if (!el || panel.contains(el) || el === highlight || highlight.contains(el)) {
+      highlight.style.display = 'none';
+      hoverEl = null;
+      return;
+    }
+    hoverEl = el;
+    var r = el.getBoundingClientRect();
+    highlight.style.display = 'block';
+    highlight.style.left = r.left + 'px';
+    highlight.style.top = r.top + 'px';
+    highlight.style.width = r.width + 'px';
+    highlight.style.height = r.height + 'px';
+    var src = getSourceInfo(el);
+    highlightLabel.textContent = '<' + el.tagName.toLowerCase() + '>' +
+      (src ? ' ' + src.file.split('/').pop() + (src.line ? ':' + src.line : '') : '');
+  }
+
+  function onClick(e) {
+    if (!pickerActive || !hoverEl) return;
+    if (panel.contains(e.target)) return;
+    e.preventDefault();
+    e.stopPropagation();
+    capture(hoverEl);
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Painel                                                              */
+  /* ------------------------------------------------------------------ */
+  var panel = document.createElement('div');
+  panel.style.cssText = 'position:fixed;bottom:16px;right:16px;width:340px;max-height:70vh;' +
+    'z-index:2147483646;background:#1c1c1e;color:#e5e5e7;border-radius:10px;' +
+    'box-shadow:0 8px 30px rgba(0,0,0,.4);font:13px/1.45 system-ui,sans-serif;' +
+    'display:flex;flex-direction:column;overflow:hidden;';
+
+  var toastEl = document.createElement('div');
+  toastEl.style.cssText = 'position:fixed;bottom:16px;left:50%;transform:translateX(-50%);' +
+    'z-index:2147483647;background:#16a34a;color:#fff;padding:8px 16px;border-radius:8px;' +
+    'font:13px system-ui,sans-serif;display:none;box-shadow:0 4px 14px rgba(0,0,0,.3);';
+  function toast(msg) {
+    toastEl.textContent = msg;
+    toastEl.style.display = 'block';
+    clearTimeout(toastEl.__t);
+    toastEl.__t = setTimeout(function () { toastEl.style.display = 'none'; }, 2500);
+  }
+
+  var collapsed = false;
+
+  function renderPanel() {
+    var srcCount = items.filter(function (it) { return it.source; }).length;
+    panel.innerHTML =
+      '<div data-fbc="header" style="display:flex;align-items:center;gap:8px;padding:10px 12px;' +
+        'background:#2c2c2e;cursor:pointer;user-select:none;">' +
+        '<span style="font-weight:600;">Feedback</span>' +
+        '<span style="background:#2563eb;border-radius:10px;padding:0 8px;font-size:11px;">' + items.length + '</span>' +
+        (items.length ? '<span style="font-size:11px;color:#8e8e93;">' + srcCount + ' com source</span>' : '') +
+        '<span style="margin-left:auto;color:#8e8e93;font-size:11px;">segure ALT + clique</span>' +
+        '<span data-fbc="toggle" style="color:#8e8e93;">' + (collapsed ? '▸' : '▾') + '</span>' +
+      '</div>' +
+      (collapsed ? '' :
+        '<div style="overflow-y:auto;flex:1;padding:8px 12px;display:flex;flex-direction:column;gap:8px;">' +
+          (items.length === 0
+            ? '<div style="color:#8e8e93;padding:12px 0;text-align:center;">Nenhum item. Segure ALT e clique num elemento da página.</div>'
+            : items.map(renderItem).join('')) +
+        '</div>' +
+        '<div style="display:flex;gap:8px;padding:10px 12px;background:#2c2c2e;">' +
+          '<button data-fbc="copy" style="flex:1;background:#2563eb;color:#fff;border:0;border-radius:6px;' +
+            'padding:8px;font:600 13px system-ui;cursor:pointer;"' + (items.length ? '' : ' disabled style="flex:1;background:#3a3a3c;color:#8e8e93;border:0;border-radius:6px;padding:8px;font:600 13px system-ui;"') + '>Copiar backlog</button>' +
+          '<button data-fbc="clear" style="background:#3a3a3c;color:#e5e5e7;border:0;border-radius:6px;' +
+            'padding:8px 12px;font:13px system-ui;cursor:pointer;">Limpar</button>' +
+        '</div>');
+  }
+
+  function esc(s) {
+    return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;');
+  }
+
+  function renderItem(it, i) {
+    var loc = it.source
+      ? it.source.file.split('/').slice(-2).join('/') + (it.source.line ? ':' + it.source.line : '')
+      : (it.components && it.components[0] ? '<' + it.components[0] + '>' : it.selector.slice(0, 40));
+    return '<div style="background:#2c2c2e;border-radius:8px;padding:8px;">' +
+      '<div style="display:flex;align-items:baseline;gap:6px;margin-bottom:6px;">' +
+        '<span style="color:#8e8e93;font-size:11px;">#' + (i + 1) + '</span>' +
+        '<span style="font-family:ui-monospace,monospace;font-size:11px;color:#64d2ff;overflow:hidden;' +
+          'text-overflow:ellipsis;white-space:nowrap;flex:1;" title="' + esc(it.selector) + '">' + esc(loc) + '</span>' +
+        '<span data-fbc-del="' + it.id + '" style="cursor:pointer;color:#8e8e93;padding:0 4px;" title="Remover">✕</span>' +
+      '</div>' +
+      '<textarea data-fbc-ta="' + it.id + '" placeholder="O que mudar aqui?" ' +
+        'style="width:100%;box-sizing:border-box;background:#1c1c1e;color:#e5e5e7;border:1px solid #3a3a3c;' +
+        'border-radius:6px;padding:6px;font:13px system-ui;resize:vertical;min-height:40px;">' +
+        esc(it.instruction) + '</textarea>' +
+    '</div>';
+  }
+
+  panel.addEventListener('click', function (e) {
+    var t = e.target;
+    if (t.getAttribute('data-fbc') === 'copy') { copyBacklog(); return; }
+    if (t.getAttribute('data-fbc') === 'clear') {
+      if (confirm('Limpar todos os ' + items.length + ' itens?')) {
+        items = []; save(); renderPanel();
+      }
+      return;
+    }
+    if (t.hasAttribute('data-fbc-del')) {
+      var id = t.getAttribute('data-fbc-del');
+      items = items.filter(function (it) { return it.id !== id; });
+      save(); renderPanel();
+      return;
+    }
+    var header = t.closest('[data-fbc="header"]');
+    if (header) { collapsed = !collapsed; renderPanel(); }
+  });
+
+  panel.addEventListener('input', function (e) {
+    var t = e.target;
+    if (t.hasAttribute('data-fbc-ta')) {
+      var id = t.getAttribute('data-fbc-ta');
+      var it = items.find(function (x) { return x.id === id; });
+      if (it) { it.instruction = t.value; save(); }
+    }
+  });
+
+  /* ------------------------------------------------------------------ */
+  /* Boot                                                                */
+  /* ------------------------------------------------------------------ */
+  document.addEventListener('keydown', onKeyDown, true);
+  document.addEventListener('keyup', onKeyUp, true);
+  window.addEventListener('blur', deactivatePicker);
+  document.addEventListener('mousemove', onMouseMove, true);
+  document.addEventListener('click', onClick, true);
+
+  document.body.appendChild(highlight);
+  document.body.appendChild(panel);
+  document.body.appendChild(toastEl);
+  renderPanel();
+
+  console.log('[feedback-collector] ativo. Segure ALT + clique pra capturar. ' +
+    items.length + ' item(ns) restaurado(s) do localStorage.');
+})();

package/src/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * O package é um side effect puro (injeta o picker no DOM ao ser importado).
+ * Não há API pública — este .d.ts existe só pra TypeScript aceitar
+ * `import('feedback-collector')` sem reclamar de declaração ausente.
+ */
+export {};

package/src/index.js

@@ -0,0 +1,14 @@
+/**
+ * Entry ESM do package. O script em si é um IIFE auto-executável (side effect):
+ * importar este módulo injeta o picker/painel na página. Não há API exportada.
+ *
+ * Guard de SSR: importar este módulo em Node/server (Next SSR, testes) é no-op
+ * — o script só carrega quando há `window`. O feedback-collector.js fica sem
+ * `export` de propósito, pra também funcionar cru via <script src> em páginas
+ * sem bundler (ver "./script" no exports do package.json).
+ */
+if (typeof window !== "undefined") {
+  void import("./feedback-collector.js");
+}
+
+export {};