feedback-collector 0.1.0 → 0.2.0

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

@@ -3,42 +3,38 @@ 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.
+  usuário pedir para instalar, adicionar, configurar, controlar ou remover o
+  feedback-collector. Cobre Next.js (webpack), Vite e sites sem build; inclui
+  ciclo de vida v0.2, migração local, caveat de React 19 e gate de 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:
+O package `feedback-collector` é client-side, vanilla, sem backend e sem
+dependências de runtime. 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.
+1. **Runtime:** picker, painel, fila local e export.
+2. **Source mapping:** plugin de build que injeta `data-inspector-*` no JSX.
 
-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).
+Antes de editar, detecte framework, bundler, versão do React, package manager,
+se o app usa SSR e se o usuário quer uso apenas em dev ou também em produção.
+No Next, confirme se `dev` usa webpack ou `--turbopack`.
 
-## Parte 1 — o script
+## Parte 1 — runtime
 
 ```bash
-npm i -D feedback-collector   # ou pnpm add -D
+npm i -D feedback-collector
 ```
 
-Carregue via componente client montado condicionalmente (React):
+### Modo compatível: auto-mount
+
+O import raiz injeta o picker como side effect, como na v0.1:
 
 ```tsx
-// components/feedback-collector-loader.tsx
-"use client"; // (Next App Router)
+"use client";
 import { useEffect } from "react";
 
-export function FeedbackCollector() {
+export function FeedbackCollectorLoader() {
   useEffect(() => {
     void import("feedback-collector");
   }, []);
@@ -46,39 +42,79 @@ export function FeedbackCollector() {
 }
 ```
 
-**Onde renderizar — decisão de gate (pergunte ao usuário se ambíguo):**
+### Modo controlado: mount/destroy
+
+Use o entry sem auto-inicialização quando o app precisa ativar/desativar o
+collector durante sua vida útil:
+
+```tsx
+"use client";
+import { useEffect } from "react";
+
+export function FeedbackCollectorLoader() {
+  useEffect(() => {
+    let dispose: (() => void) | undefined;
+    void import("feedback-collector/api").then(({ mount, destroy }) => {
+      mount();
+      dispose = destroy;
+    });
+    return () => dispose?.();
+  }, []);
+  return null;
+}
+```
 
-- **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.
+`mount()` é idempotente e devolve o controller ativo. `destroy()` remove DOM e
+listeners, mas mantém a fila no storage. O entry raiz também exporta os métodos,
+porém auto-monta; para controle explícito prefira `feedback-collector/api`.
 
-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.
+### Gate de ambiente/usuário
 
-## Parte 2 — source mapping (arquivo:linha)
+- **Só dev (padrão seguro):** renderize o loader apenas quando
+  `NODE_ENV === "development"`.
+- **Produção com dados reais:** renderize server-side apenas para papel
+  autorizado (owner/admin). Usuários comuns não devem baixar o chunk nem ver o
+  painel. O gate do runtime não protege os paths injetados pelo plugin: esses
+  podem ficar em chunks públicos.
 
-**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.
+### Site sem build
 
-### Next.js (webpack) — receita validada (Next 15, React 19)
+Copie `node_modules/feedback-collector/dist/feedback-collector.js` para os
+assets e carregue como `<script>`. O export `feedback-collector/script` aponta
+para esse IIFE e a API fica em `window.FeedbackCollector`.
+
+`node_modules/feedback-collector/src/feedback-collector.js` continua publicado
+temporariamente para instalações v0.1 que acessavam o arquivo direto, mas não
+deve ser usado em novas integrações.
+
+## Persistência v0.2
+
+A fila atual usa `__fbc_state_v2` (`{ version: 2, items: [...] }`). Na primeira
+montagem, o runtime migra o array `__fbc_items_v1` sem alterar os itens e sem
+apagar a chave antiga. Não crie scripts de migração no projeto consumidor e não
+limpe essas chaves durante upgrade ou remoção, salvo pedido explícito do usuário.
+
+## Parte 2 — source mapping
+
+**React 19 removeu `_debugSource` do fiber.** Sem plugin, os itens não terão
+arquivo:linha; seletor, styles, HTML e export continuam funcionando. Em React
+18 ou anterior há fallback legado, mas os atributos ainda são mais confiáveis.
+
+O runtime lê `data-inspector-relative-path`, `data-inspector-line`,
+`data-inspector-column` e a alternativa `data-source="arquivo:linha:coluna"`.
+
+### Next.js com webpack (validado em 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`:
+Não crie `.babelrc`: isso desliga o SWC do projeto inteiro. Adicione apenas um
+pre-pass no `next.config.ts`:
 
 ```ts
 webpack: (config, { dev }) => {
-  if (dev) { // ver "Em produção?" abaixo antes de remover este gate
+  if (dev) {
     config.module.rules.unshift({
       test: /\.(jsx|tsx)$/,
       exclude: /node_modules/,
@@ -86,10 +122,14 @@ webpack: (config, { dev }) => {
       use: [{
         loader: "babel-loader",
         options: {
-          babelrc: false, configFile: false, sourceMaps: false,
+          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"],
+          plugins: [
+            "@babel/plugin-syntax-jsx",
+            "@react-dev-inspector/babel-plugin",
+          ],
         },
       }],
     });
@@ -98,66 +138,69 @@ webpack: (config, { dev }) => {
 },
 ```
 
-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).
+Não passe `isTSX`/`allExtensions`: foram removidos no Babel 8. O loader deve
+rodar em server e client para evitar hydration mismatch. Se o script `dev` usa
+`--turbopack`, o hook `webpack()` não roda; remova a flag ou pare e discuta uma
+alternativa com o usuário.
+
+### Next em produção
 
-Se o `dev` script usa `--turbopack`: o hook `webpack()` não roda. Opções:
-remover a flag em dev, ou usar `experimental.swcPlugins` (abaixo).
+Remover `if (dev)` é decisão explícita do usuário:
 
-### Next.js — em produção?
+- paths de `src/` entram nos chunks JS públicos;
+- o pre-pass Babel também roda no build e aumenta seu tempo.
 
-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.
+Se aprovado, documente esse trade-off ao lado do config. O gate por papel do
+loader não remove os atributos dos chunks públicos.
 
-### Vite (React)
+### 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)
+Registre o plugin antes de `@vitejs/plugin-react`. Como alternativa, configure
+`@react-dev-inspector/babel-plugin` na opção `babel` do plugin React.
+
+### Alternativa SWC atual
 
-`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.
+`experimental.swcPlugins` + `swc-plugin-react-source-string` injeta
+`data-source`. Continua experimental e sensível à versão de `swc_core`; só use
+se o custo do Babel for uma dor explícita e após aprovação do usuário.
 
 ### Vue / Svelte
 
-`vue-inspector` / inspector do Svelte injetam atributos análogos; hoje exige
-adaptar `getSourceInfo()` no script (não suportado out-of-the-box).
+O runtime é agnóstico, mas uma integração de compiler validada ainda não faz
+parte do package. Não adicione adapters novos automaticamente nesta etapa.
 
-## Verificação (sempre faça)
+## Verificação obrigatória
 
-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.
+1. Rode typecheck, lint e build do projeto consumidor.
+2. Confirme no HTML/DOM que existem paths reais:
+   `grep -o 'data-inspector-relative-path="[^"]*"' | sort -u`.
+3. Se habilitou em produção, procure `data-inspector` nos chunks gerados.
+4. No navegador, confirme o log `[feedback-collector] ativo`, ALT+hover com
+   source, ALT+clique, edição e “Copiar backlog”.
+5. Se atualizou da v0.1 com itens, confirme que o painel restaurou a fila e que
+   `__fbc_state_v2` foi criado; não apague `__fbc_items_v1`.
 
 ## Remoção
 
-Três níveis — pergunte qual o usuário quer:
+Alinhe o nível antes de agir:
+
+1. **Desmontar em runtime:** chame `destroy()` ou remova o loader.
+2. **Desligar o painel:** remova o loader; o plugin pode continuar injetando
+   atributos.
+3. **Limpar o build:** reponha o gate `if (dev)` ou remova o pre-pass/plugin.
+4. **Remoção total:** remova loader, config e dependências relacionadas.
+
+Não apague `__fbc_state_v2` nem `__fbc_items_v1` durante remoção sem autorização
+explícita. Não há banco, backend ou serviço externo a limpar.
 
-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.
+## Integração própria futura
 
-Os itens capturados vivem em `localStorage` (chave por origem); remover o
-script não apaga nada sensível.
+Não implemente plugin próprio de Next/Vite durante setup de consumidor. O
+desenho futuro deve preservar atributos existentes, ser opt-in, ter builds dev
+e prod explícitos e provar compatibilidade/métricas antes de substituir as
+receitas atuais. A proposta vive em `docs/integracao-compiler-futura.md` no repo
+do package.