@aeres/farol-web 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
+# @aeres/farol-web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK de observabilidade **somente para desenvolvimento** de aplicações React, Next.js e outros portais web. A instalação isolada não ativa nenhum interceptor. `enabled: true`, ambiente de navegador e token do coletor local são obrigatórios.
+
+## Instalação
+
+O nome reservado para distribuição no npm é `@aeres/farol-web`, versão `0.2.0`.
+Use o modo **npm** em **Conectar projeto** somente quando o Studio indicar que
+essa versão foi verificada no registro. Nesse caso:
+
+```sh
+npm install --save-dev --save-exact @aeres/farol-web@0.2.0
+```
+
+Enquanto a publicação não estiver confirmada, exporte o SDK pelo Studio e instale
+o arquivo local. A geração do `.tgz` não publica o pacote:
+
+```bash
+npm install --save-dev /caminho/aeres-farol-web-0.2.0.tgz
+```
+
+## Integração Vite / React
+
+Crie `.env.local` com `VITE_FAROL_TOKEN` igual ao token exibido pelo coletor local. Inicialize antes de montar a aplicação:
+
+```ts
+if (import.meta.env.DEV) {
+  const { initFarol } = await import('@aeres/farol-web');
+  const farol = initFarol({
+    appName: 'Meu portal',
+    enabled: true,
+    token: import.meta.env.VITE_FAROL_TOKEN,
+    endpoint: 'ws://127.0.0.1:43218/ws',
+    captureBodies: false,
+  });
+  import.meta.hot?.dispose(() => farol.destroy());
+}
+```
+
+O token de pareamento é uma credencial do ambiente local. Não publique o arquivo `.env.local`. Mantenha a importação e os componentes de diagnóstico sob o guard de desenvolvimento; isso permite ao bundler remover o SDK do build de produção.
+
+O exemplo usa a porta padrão do aplicativo macOS. Copie o endpoint efetivamente
+exibido em **Conectar projeto**; o broker separado normalmente usa a porta `4318`.
+
+## Next.js
+
+No arquivo client de bootstrap, use um efeito de desenvolvimento e encerre no cleanup. O SDK não instrumenta SSR nem código de servidor.
+
+```tsx
+'use client';
+import { useEffect } from 'react';
+
+export function FarolBootstrap() {
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'development') return;
+    let disposed = false;
+    let cleanup: (() => void) | undefined;
+    void import('@aeres/farol-web').then(({ initFarol }) => {
+      if (disposed) return;
+      const farol = initFarol({
+        appName: 'Portal Next', enabled: true,
+        token: process.env.NEXT_PUBLIC_FAROL_TOKEN,
+        endpoint: 'ws://127.0.0.1:43218/ws',
+      });
+      cleanup = () => farol.destroy();
+    });
+    return () => { disposed = true; cleanup?.(); };
+  }, []);
+  return null;
+}
+```
+
+## React Profiler e Error Boundary
+
+O entrypoint React é separado para manter o SDK principal sem dependência de React em runtime.
+
+```tsx
+import { FarolProfiler, FarolErrorBoundary } from '@aeres/farol-web/react';
+
+<FarolErrorBoundary client={farol} fallback={(error, reset) => (
+  <div role="alert">Falha no exemplo. <button onClick={reset}>Tentar novamente</button></div>
+)}>
+  <FarolProfiler client={farol} id="Checkout">
+    <Checkout />
+  </FarolProfiler>
+</FarolErrorBoundary>
+```
+
+`createProfilerCallback(farol)` também funciona como `onRender` de um `<Profiler>` existente. React pode não emitir medições de Profiler em builds de produção. Error boundaries capturam falhas de renderização em descendentes; erros globais e rejeições não tratadas são capturados pelos listeners do SDK.
+
+## Zustand, Redux e TanStack Query
+
+```ts
+// Zustand: getState / subscribe / setState do store vanilla ou store hook.
+const stop = farol.watchStore('cart', {
+  getState: cartStore.getState,
+  subscribe: cartStore.subscribe,
+  setState: (value) => cartStore.setState(value),
+});
+
+// Redux: inspeção e assinatura. Não existe mutação arbitrária sem adapter explícito.
+farol.watchStore('redux', {
+  getState: store.getState,
+  subscribe: store.subscribe,
+});
+
+const stopQueries = farol.observeQueryClient(queryClient);
+farol.track('checkout.completed', { orderId: 'demo-123', items: 3 });
+stop();
+stopQueries();
+```
+
+Adapters são estruturais e não exigem dependências Zustand/Redux/TanStack no SDK. `state.set` só funciona quando você fornece `setState`. Invalidação usa a API `invalidateQueries({queryKey})` do cliente registrado.
+
+## Capturas e controles
+
+- Console, erros globais, rejeições e erros React com contexto e stack disponível.
+- Fetch e XMLHttpRequest: método, URL, status, duração, headers e falhas. Bodies ficam desativados por padrão, são limitados a 8 KiB quando ativados e excluem streams/binários/multipart.
+- Local/session storage: snapshot inicial, alterações e comandos de edição/remoção.
+- Histórico de navegação, `popstate`, `hashchange` e navegação restrita à mesma origem.
+- PerformanceObserver: navegação, paint, long tasks, LCP e CLS quando suportados pelo navegador. As medições não substituem um tracing completo do Chrome.
+- Snapshots de stores, cache de queries, renders e eventos personalizados.
+- Mocks por URL completa ou pathname, wildcard `*`, método, status, corpo e atraso; simulação de offline e latência em fetch/XHR.
+- Snapshot DOM limitado a 150 elementos com tags, ids, texto direto e retângulos; nenhum valor de campo é coletado. Marque blocos sensíveis com `data-farol-private`. Highlight temporário de seletor CSS.
+
+Mocks interceptam somente chamadas da página instrumentada. Não afetam WebSockets, service workers, iframes, workers ou tráfego nativo React Native. XHR simulado reproduz status/corpo/eventos finais; não pretende simular streaming, progress de upload ou cada transição intermediária do navegador. SDK/browser não oferecem inspeção de heap, debugger de breakpoints ou árvore Fiber; continue usando DevTools para essas tarefas.
+
+## Segurança e ciclo de vida
+
+- Sem `enabled: true` explícito, sem token, em SSR, ou com endpoint externo: retorna client inativo sem abrir conexão nem instalar patches.
+- Conecta somente a `localhost`, `127.0.0.1` ou `[::1]`. O coletor recebe autenticação antes de sessão/eventos, e comandos exigem conexão pareada e o id da sessão atual.
+- Páginas HTTPS podem exigir endpoint local `wss://` com certificado confiável e permissão CSP `connect-src`; configure isso no ambiente de desenvolvimento.
+- Redige profundamente campos de tokens, senhas, cookies, Authorization, chaves de API, URLs com credenciais/query sensível e strings JSON reconhecidas. Getters não são executados. Protege contra ciclos, profundidade excessiva e volume ilimitado.
+- A redação é heurística: dados pessoais em chaves genéricas e segredos sem contexto podem permanecer visíveis. Use dados de teste; habilite bodies apenas quando necessário.
+- Eventos são redigidos antes de entrar na fila. Fila padrão: 400 eventos; máximo configurável: 2.000. Payloads excessivos são substituídos por um aviso. A captura não garante entrega durante fechamento da página/desconexões prolongadas.
+- Reconexão com backoff limitado; erro de autenticação encerra tentativas. Inicialização repetida encerra o client anterior (HMR).
+- `farol.destroy()` remove subscriptions/listeners/observers, fecha transporte e restaura wrappers que ainda pertencem ao SDK. Não desfaz alterações deliberadas feitas no estado/storage por comandos.
+- Não existe execução de JavaScript remoto nem comando `eval`.
+- `state.set` e `storage.set` recusam valores com marcadores de redação/serialização (por exemplo `[REDACTED]`, `[Max depth]`, `[Circular]`, `[Function …]`, `[truncated]`, omissão de entradas e descrições de dados binários). A recusa ocorre antes de chamar setters. O helper público `containsSerializationMarkers(value)` permite ao painel bloquear a edição/restauração de snapshots incompletos com o mesmo critério.
+- Resultados de comandos acima de 64 KiB retornam `ok: false` com erro explícito de limite. Escritas em storage retornam confirmação curta; consulte `storage.list` separadamente para atualizar o painel.
+- `network.get` retorna `{ offline, latency, mocks }` da sessão atual, permitindo recuperar simulações existentes ao reconectar ou trocar de sessão.
+
+O comando de reload não pode preservar o estado em memória. Valores completos continuam no app original; redação afeta a cópia enviada ao painel.
+
+## API resumida
+
+```ts
+initFarol({ appName, enabled?, endpoint?, token?, captureBodies?, maxBodyBytes?, maxQueueSize? })
+// => enabled, connected, session, getSession(), track(), record(),
+//    watchStore(), observeQueryClient(), destroy()
+```
+
+Protocolo de comandos: `storage.list`, `storage.set`, `storage.remove`, `state.set`, `query.invalidate`, `network.get`, `network.configure`, `mock.set`, `mock.remove`, `dom.snapshot`, `dom.highlight`, `page.reload`, `nav.go`. Respostas usam `command.result`, id original, sessionId, `ok` e `data` ou `error`.
+
+## Desenvolvimento do pacote
+
+```bash
+npm run build -w @aeres/farol-web
+npm run test -w @aeres/farol-web
+npm pack -w @aeres/farol-web
+```
+
+O pacote distribui ESM, CommonJS, sourcemaps e declarações TypeScript. O protocolo de tipos é autocontido, sem import runtime de pacotes internos do workspace.
+
+`prepublishOnly` executa build e testes antes de uma publicação a partir do
+checkout. Os consumidores não executam esse hook ao instalar o pacote. O pacote
+mantém a declaração **UNLICENSED**; acesso público no npm não concede uma licença
+de código aberto nem altera os direitos de uso.