@neetru/sdk 3.1.0 → 3.1.1

package/dist/db-react.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/db/react.ts"],"names":["React"],"mappings":"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","file":"db-react.cjs","sourcesContent":["/**\r\n * Bindings React do módulo db (M2) — `@neetru/sdk/react`.\r\n *\r\n * Exporta três hooks de tempo real que se integram com a camada offline do\r\n * `@neetru/sdk/db`:\r\n *\r\n *   - `useDocument(ref, id)` — subscreve ao onSnapshot de um documento.\r\n *   - `useCollection(ref, query?)` — subscreve ao onSnapshot de uma coleção.\r\n *   - `useSyncState(ns)` — observa o SyncState do namespace offline.\r\n *\r\n * ### Design\r\n * Segue o padrão do subpath `/react` existente (cliente/ref passados\r\n * explicitamente, sem Context Provider obrigatório). Alinhado com 02-sdk.md §3.6.\r\n *\r\n * ### React 18/19 StrictMode\r\n * Cada hook usa um ref interno para rastrear se o componente foi desmontado,\r\n * e a função `useEffect` retorna sempre a função de unsubscribe. Em StrictMode,\r\n * o duplo-mount/unmount do React 18 chama cleanup corretamente — não há leak.\r\n *\r\n * ### Dependências\r\n * `react` é peer dependency — não importada como dep direta.\r\n */\r\nimport * as React from 'react';\r\nimport type { DbCollectionRef, DbDoc, DbQuery, DbListResult, DbGetResult } from './collection-ref';\r\nimport type { SyncState, Unsubscribe } from './offline/types';\r\nimport type { NeetruClient } from '../types';\r\n\r\n// ─── Tipos públicos dos hooks ─────────────────────────────────────────────────\r\n\r\n/**\r\n * Resultado de `useDocument`.\r\n *\r\n * - `data` — dados do documento, ou `null` se não existe / ainda carregando.\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local, não do servidor.\r\n * - `stale` — conexão caída ou sincronizando; pode haver dados mais novos.\r\n */\r\nexport interface UseDocumentResult<T> {\r\n  data: T | null;\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n}\r\n\r\n/**\r\n * Resultado de `useCollection`.\r\n *\r\n * - `docs` — documentos da coleção (ou subconjunto via query).\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local.\r\n * - `stale` — conexão caída ou sincronizando.\r\n * - `hasPendingWrites` — ao menos um doc tem escrita local não confirmada.\r\n */\r\nexport interface UseCollectionResult<T> {\r\n  docs: DbDoc<T>[];\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n  hasPendingWrites: boolean;\r\n}\r\n\r\n/**\r\n * Subconjunto mínimo do namespace offline que `useSyncState` precisa.\r\n * Compatível com `NeetruDbDocuments` de `collection-ref.ts`.\r\n *\r\n * Passado explicitamente (sem Context) para alinhar com o padrão do SDK.\r\n * Tipicamente: o namespace retornado por `createOfflineDocumentsNamespace`.\r\n *\r\n * `client.db` (o `NeetruDb` retornado por `createNeetruClient`) também satisfaz\r\n * este contrato — expõe `syncState` + `onSyncStateChanged` reais. Por isso\r\n * `useSyncState` aceita tanto a fonte direta quanto o `NeetruClient` inteiro\r\n * (ver `UseSyncStateInput`).\r\n */\r\nexport interface SyncStateSource {\r\n  readonly syncState: SyncState;\r\n  onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;\r\n}\r\n\r\n/**\r\n * Entrada aceita por `useSyncState`:\r\n *   - `NeetruClient`     → resolve `client.db` automaticamente (forma oficial,\r\n *                          alinhada com 02-sdk.md §3.6 `useSyncState(client)`).\r\n *   - `SyncStateSource`  → fonte direta (`client.db` ou o namespace offline cru).\r\n */\r\nexport type UseSyncStateInput = NeetruClient | SyncStateSource;\r\n\r\n/**\r\n * Type guard — detecta se a entrada é um `NeetruClient` (tem `.db` que é, ele\r\n * próprio, um `SyncStateSource`) e não uma fonte direta. Distinção em runtime\r\n * porque os shapes não se sobrepõem: a fonte direta expõe `syncState` no nível\r\n * de topo; o client expõe via `.db`.\r\n */\r\nfunction isNeetruClient(input: UseSyncStateInput): input is NeetruClient {\r\n  const maybe = input as { db?: unknown; syncState?: unknown };\r\n  // Fonte direta já tem `syncState` no topo → não é o client wrapper.\r\n  if (typeof maybe.syncState !== 'undefined') return false;\r\n  const db = maybe.db as { syncState?: unknown; onSyncStateChanged?: unknown } | undefined;\r\n  return (\r\n    !!db &&\r\n    typeof db.syncState !== 'undefined' &&\r\n    typeof db.onSyncStateChanged === 'function'\r\n  );\r\n}\r\n\r\n/** Normaliza qualquer entrada aceita para a `SyncStateSource` subjacente. */\r\nfunction resolveSyncStateSource(input: UseSyncStateInput): SyncStateSource {\r\n  return isNeetruClient(input) ? (input.db as unknown as SyncStateSource) : input;\r\n}\r\n\r\n// ─── Serialização estável de query ────────────────────────────────────────────\r\n\r\n/**\r\n * Serializa uma DbQuery para string estável, usada como chave de efeito.\r\n *\r\n * `useCollection` re-subscreve somente quando a serialização muda, NÃO por\r\n * identidade de objeto. Isso evita a armadilha clássica de inline-object em\r\n * JSX que causaria re-subscribe em todo render.\r\n */\r\nfunction serializeQuery(query: DbQuery | undefined): string {\r\n  if (!query) return '';\r\n  try {\r\n    return JSON.stringify(query, Object.keys(query).sort());\r\n  } catch {\r\n    return String(query);\r\n  }\r\n}\r\n\r\n// ─── useDocument ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para um documento específico.\r\n *\r\n * Subscreve a `ref.doc(id).onSnapshot` no mount. Re-subscreve quando `ref`\r\n * ou `id` mudam. Cancela a subscrição no unmount.\r\n *\r\n * ```tsx\r\n * const { data, loading, fromCache, stale } = useDocument(ordersRef, orderId);\r\n * if (loading) return <Spinner />;\r\n * if (!data) return <NotFound />;\r\n * return <OrderCard order={data} fromCache={fromCache} />;\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode: a cleanup function do useEffect cancela\r\n * o listener no unmount, e o double-mount do StrictMode não vaza estado.\r\n */\r\nexport function useDocument<T>(\r\n  ref: DbCollectionRef<T>,\r\n  id: string,\r\n): UseDocumentResult<T> {\r\n  const [state, setState] = React.useState<UseDocumentResult<T>>({\r\n    data: null,\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n  });\r\n\r\n  // Ref para detectar unmount e evitar setState após cleanup.\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset para loading quando ref/id muda\r\n    setState({ data: null, loading: true, fromCache: true, stale: false });\r\n\r\n    const docRef = ref.doc(id);\r\n\r\n    const unsubscribe: Unsubscribe = docRef.onSnapshot(\r\n      (snap: DbGetResult<T> | null) => {\r\n        if (!mountedRef.current) return;\r\n        if (snap === null || snap.docs.length === 0) {\r\n          setState({\r\n            data: null,\r\n            loading: false,\r\n            fromCache: snap?.fromCache ?? true,\r\n            stale: snap?.stale ?? false,\r\n          });\r\n        } else {\r\n          setState({\r\n            data: snap.docs[0]?.data ?? null,\r\n            loading: false,\r\n            fromCache: snap.fromCache,\r\n            stale: snap.stale,\r\n          });\r\n        }\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, id]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useCollection ────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para uma coleção (ou subconjunto filtrado).\r\n *\r\n * Subscreve a `ref.onSnapshot(query, cb)` no mount. Re-subscreve quando `ref`\r\n * ou a serialização de `query` muda — NÃO por identidade de objeto, o que\r\n * evita re-subscribe desnecessário em inline objects.\r\n *\r\n * ```tsx\r\n * const { docs, loading, hasPendingWrites } = useCollection(ordersRef, {\r\n *   where: [{ field: 'status', op: '==', value: 'open' }],\r\n * });\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useCollection<T>(\r\n  ref: DbCollectionRef<T>,\r\n  query?: DbQuery,\r\n): UseCollectionResult<T> {\r\n  const [state, setState] = React.useState<UseCollectionResult<T>>({\r\n    docs: [],\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n    hasPendingWrites: false,\r\n  });\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  // Serializamos a query para garantir que mudanças de valor (não de referência)\r\n  // triggam o re-subscribe, mas que objetos iguais não causem loop.\r\n  const queryKey = serializeQuery(query);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset loading ao trocar de query/ref\r\n    setState({\r\n      docs: [],\r\n      loading: true,\r\n      fromCache: true,\r\n      stale: false,\r\n      hasPendingWrites: false,\r\n    });\r\n\r\n    const unsubscribe: Unsubscribe = ref.onSnapshot(\r\n      query,\r\n      (snap: DbListResult<T>) => {\r\n        if (!mountedRef.current) return;\r\n        setState({\r\n          docs: snap.docs,\r\n          loading: false,\r\n          fromCache: snap.fromCache,\r\n          stale: snap.stale,\r\n          hasPendingWrites: snap.hasPendingWrites,\r\n        });\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, queryKey]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useSyncState ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook para observar o `SyncState` da camada offline em tempo real.\r\n *\r\n * Retorna o `SyncState` atual e re-renderiza quando ele muda. Usado para\r\n * renderizar indicadores \"sincronizando…\" / \"offline\" / contadores de escritas\r\n * pendentes na UI.\r\n *\r\n * Aceita duas formas de entrada (SDK-QW-4 — wiring ao client real):\r\n *\r\n * ```tsx\r\n * // Forma oficial — passe o client; o hook resolve client.db internamente.\r\n * const client = createNeetruClient({ apiKey });\r\n * const state = useSyncState(client);\r\n *\r\n * // Forma direta — passe a fonte (client.db ou o namespace offline cru).\r\n * const state = useSyncState(client.db);\r\n *\r\n * if (state.status === 'offline') return <OfflineBanner pending={state.pendingWrites} />;\r\n * ```\r\n *\r\n * Antes desta versão o hook só aceitava a `SyncStateSource` crua, o que levava\r\n * consumers a stub-arem o estado pra sempre `'idle'` em vez de ligar no client.\r\n * Agora `useSyncState(client)` (a forma documentada em 02-sdk.md §3.6) funciona\r\n * de ponta a ponta — `client.db.syncState` / `client.db.onSyncStateChanged` são\r\n * reais.\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useSyncState(input: UseSyncStateInput): SyncState {\r\n  // Resolve uma única vez por render; se a identidade da fonte resolvida mudar,\r\n  // o efeito abaixo re-subscreve (dependência `source`).\r\n  const source = resolveSyncStateSource(input);\r\n\r\n  const [state, setState] = React.useState<SyncState>(() => source.syncState);\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n\r\n    // Snapshot inicial imediato ao montar (pode ter mudado entre render e effect)\r\n    if (mountedRef.current) {\r\n      setState(source.syncState);\r\n    }\r\n\r\n    const unsubscribe: Unsubscribe = source.onSyncStateChanged((s: SyncState) => {\r\n      if (!mountedRef.current) return;\r\n      setState(s);\r\n    });\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [source]);\r\n\r\n  return state;\r\n}\r\n"]}
+{"version":3,"sources":["../src/db/react.ts"],"names":["React"],"mappings":"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","file":"db-react.cjs","sourcesContent":["/**\r\n * Bindings React do módulo db (M2) — `@neetru/sdk/react`.\r\n *\r\n * Exporta três hooks de tempo real que se integram com a camada offline do\r\n * `@neetru/sdk/db`:\r\n *\r\n *   - `useDocument(ref, id)` — subscreve ao onSnapshot de um documento.\r\n *   - `useCollection(ref, query?)` — subscreve ao onSnapshot de uma coleção.\r\n *   - `useSyncState(ns)` — observa o SyncState do namespace offline.\r\n *\r\n * ### Design\r\n * Segue o padrão do subpath `/react` existente (cliente/ref passados\r\n * explicitamente, sem Context Provider obrigatório). Alinhado com 02-sdk.md §3.6.\r\n *\r\n * ### React 18/19 StrictMode\r\n * Cada hook usa um ref interno para rastrear se o componente foi desmontado,\r\n * e a função `useEffect` retorna sempre a função de unsubscribe. Em StrictMode,\r\n * o duplo-mount/unmount do React 18 chama cleanup corretamente — não há leak.\r\n *\r\n * ### Dependências\r\n * `react` é peer dependency — não importada como dep direta.\r\n */\r\nimport * as React from 'react';\r\nimport type { DbCollectionRef, DbDoc, DbQuery, DbListResult, DbGetResult } from './collection-ref';\r\nimport type { SyncState, Unsubscribe } from './offline/types';\r\nimport type { NeetruClient } from '../types';\r\n\r\n// ─── Tipos públicos dos hooks ─────────────────────────────────────────────────\r\n\r\n/**\r\n * Resultado de `useDocument`.\r\n *\r\n * - `data` — dados do documento, ou `null` se não existe / ainda carregando.\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local, não do servidor.\r\n * - `stale` — conexão caída ou sincronizando; pode haver dados mais novos.\r\n */\r\nexport interface UseDocumentResult<T> {\r\n  data: T | null;\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n}\r\n\r\n/**\r\n * Resultado de `useCollection`.\r\n *\r\n * - `docs` — documentos da coleção (ou subconjunto via query).\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local.\r\n * - `stale` — conexão caída ou sincronizando.\r\n * - `hasPendingWrites` — ao menos um doc tem escrita local não confirmada.\r\n */\r\nexport interface UseCollectionResult<T> {\r\n  docs: DbDoc<T>[];\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n  hasPendingWrites: boolean;\r\n}\r\n\r\n/**\r\n * Subconjunto mínimo do namespace offline que `useSyncState` precisa.\r\n * Compatível com `NeetruDbDocuments` de `collection-ref.ts`.\r\n *\r\n * Passado explicitamente (sem Context) para alinhar com o padrão do SDK.\r\n * Tipicamente: o namespace retornado por `createOfflineDocumentsNamespace`.\r\n *\r\n * `client.db` (o `NeetruDb` retornado por `createNeetruClient`) também satisfaz\r\n * este contrato — expõe `syncState` + `onSyncStateChanged` reais. Por isso\r\n * `useSyncState` aceita tanto a fonte direta quanto o `NeetruClient` inteiro\r\n * (ver `UseSyncStateInput`).\r\n */\r\nexport interface SyncStateSource {\r\n  readonly syncState: SyncState;\r\n  onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;\r\n}\r\n\r\n/**\r\n * Entrada aceita por `useSyncState`:\r\n *   - `NeetruClient`     → resolve `client.db` automaticamente (forma oficial,\r\n *                          alinhada com 02-sdk.md §3.6 `useSyncState(client)`).\r\n *   - `SyncStateSource`  → fonte direta (`client.db` ou o namespace offline cru).\r\n */\r\nexport type UseSyncStateInput = NeetruClient | SyncStateSource;\r\n\r\n/**\r\n * Type guard — detecta se a entrada é um `NeetruClient` (tem `.db` que é, ele\r\n * próprio, um `SyncStateSource`) e não uma fonte direta. Distinção em runtime\r\n * porque os shapes não se sobrepõem: a fonte direta expõe `syncState` no nível\r\n * de topo; o client expõe via `.db`.\r\n */\r\nfunction isNeetruClient(input: UseSyncStateInput): input is NeetruClient {\r\n  const maybe = input as { db?: unknown; syncState?: unknown };\r\n  // Fonte direta já tem `syncState` no topo → não é o client wrapper.\r\n  if (typeof maybe.syncState !== 'undefined') return false;\r\n  const db = maybe.db as { syncState?: unknown; onSyncStateChanged?: unknown } | undefined;\r\n  return (\r\n    !!db &&\r\n    typeof db.syncState !== 'undefined' &&\r\n    typeof db.onSyncStateChanged === 'function'\r\n  );\r\n}\r\n\r\n/** Normaliza qualquer entrada aceita para a `SyncStateSource` subjacente. */\r\nfunction resolveSyncStateSource(input: UseSyncStateInput): SyncStateSource {\r\n  return isNeetruClient(input) ? (input.db as unknown as SyncStateSource) : input;\r\n}\r\n\r\n// ─── Serialização estável de query ────────────────────────────────────────────\r\n\r\n/**\r\n * Serializa uma DbQuery para string estável, usada como chave de efeito.\r\n *\r\n * `useCollection` re-subscreve somente quando a serialização muda, NÃO por\r\n * identidade de objeto. Isso evita a armadilha clássica de inline-object em\r\n * JSX que causaria re-subscribe em todo render.\r\n */\r\nfunction serializeQuery(query: DbQuery | undefined): string {\r\n  if (!query) return '';\r\n  try {\r\n    return JSON.stringify(query, Object.keys(query).sort());\r\n  } catch {\r\n    return String(query);\r\n  }\r\n}\r\n\r\n// ─── useDocument ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para um documento específico.\r\n *\r\n * Subscreve a `ref.doc(id).onSnapshot` no mount. Re-subscreve quando `ref`\r\n * ou `id` mudam. Cancela a subscrição no unmount.\r\n *\r\n * ```tsx\r\n * const { data, loading, fromCache, stale } = useDocument(ordersRef, orderId);\r\n * if (loading) return <Spinner />;\r\n * if (!data) return <NotFound />;\r\n * return <OrderCard order={data} fromCache={fromCache} />;\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode: a cleanup function do useEffect cancela\r\n * o listener no unmount, e o double-mount do StrictMode não vaza estado.\r\n */\r\nexport function useDocument<T>(\r\n  ref: DbCollectionRef<T>,\r\n  id: string,\r\n): UseDocumentResult<T> {\r\n  const [state, setState] = React.useState<UseDocumentResult<T>>({\r\n    data: null,\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n  });\r\n\r\n  // Ref para detectar unmount e evitar setState após cleanup.\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset para loading quando ref/id muda\r\n    setState({ data: null, loading: true, fromCache: true, stale: false });\r\n\r\n    const docRef = ref.doc(id);\r\n\r\n    const unsubscribe: Unsubscribe = docRef.onSnapshot(\r\n      (snap: DbGetResult<T> | null) => {\r\n        if (!mountedRef.current) return;\r\n        if (snap === null || snap.docs.length === 0) {\r\n          setState({\r\n            data: null,\r\n            loading: false,\r\n            fromCache: snap?.fromCache ?? true,\r\n            stale: snap?.stale ?? false,\r\n          });\r\n        } else {\r\n          setState({\r\n            data: snap.docs[0]?.data ?? null,\r\n            loading: false,\r\n            fromCache: snap.fromCache,\r\n            stale: snap.stale,\r\n          });\r\n        }\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, id]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useCollection ────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para uma coleção (ou subconjunto filtrado).\r\n *\r\n * Subscreve a `ref.onSnapshot(query, cb)` no mount. Re-subscreve quando `ref`\r\n * ou a serialização de `query` muda — NÃO por identidade de objeto, o que\r\n * evita re-subscribe desnecessário em inline objects.\r\n *\r\n * ```tsx\r\n * const { docs, loading, hasPendingWrites } = useCollection(ordersRef, {\r\n *   where: [{ field: 'status', op: '==', value: 'open' }],\r\n * });\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useCollection<T>(\r\n  ref: DbCollectionRef<T>,\r\n  query?: DbQuery,\r\n): UseCollectionResult<T> {\r\n  const [state, setState] = React.useState<UseCollectionResult<T>>({\r\n    docs: [],\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n    hasPendingWrites: false,\r\n  });\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  // Serializamos a query para garantir que mudanças de valor (não de referência)\r\n  // triggam o re-subscribe, mas que objetos iguais não causem loop.\r\n  const queryKey = serializeQuery(query);\r\n\r\n  // Bug corrigido: o efeito usava `query` da closure externa, que poderia estar\r\n  // desatualizado quando ref mudava sem o queryKey mudar. O ref mantém sempre o\r\n  // valor mais recente sem re-disparar o efeito.\r\n  const queryRef = React.useRef(query);\r\n  queryRef.current = query;\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset loading ao trocar de query/ref\r\n    setState({\r\n      docs: [],\r\n      loading: true,\r\n      fromCache: true,\r\n      stale: false,\r\n      hasPendingWrites: false,\r\n    });\r\n\r\n    const unsubscribe: Unsubscribe = ref.onSnapshot(\r\n      queryRef.current,\r\n      (snap: DbListResult<T>) => {\r\n        if (!mountedRef.current) return;\r\n        setState({\r\n          docs: snap.docs,\r\n          loading: false,\r\n          fromCache: snap.fromCache,\r\n          stale: snap.stale,\r\n          hasPendingWrites: snap.hasPendingWrites,\r\n        });\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, queryKey]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useSyncState ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook para observar o `SyncState` da camada offline em tempo real.\r\n *\r\n * Retorna o `SyncState` atual e re-renderiza quando ele muda. Usado para\r\n * renderizar indicadores \"sincronizando…\" / \"offline\" / contadores de escritas\r\n * pendentes na UI.\r\n *\r\n * Aceita duas formas de entrada (SDK-QW-4 — wiring ao client real):\r\n *\r\n * ```tsx\r\n * // Forma oficial — passe o client; o hook resolve client.db internamente.\r\n * const client = createNeetruClient({ apiKey });\r\n * const state = useSyncState(client);\r\n *\r\n * // Forma direta — passe a fonte (client.db ou o namespace offline cru).\r\n * const state = useSyncState(client.db);\r\n *\r\n * if (state.status === 'offline') return <OfflineBanner pending={state.pendingWrites} />;\r\n * ```\r\n *\r\n * Antes desta versão o hook só aceitava a `SyncStateSource` crua, o que levava\r\n * consumers a stub-arem o estado pra sempre `'idle'` em vez de ligar no client.\r\n * Agora `useSyncState(client)` (a forma documentada em 02-sdk.md §3.6) funciona\r\n * de ponta a ponta — `client.db.syncState` / `client.db.onSyncStateChanged` são\r\n * reais.\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useSyncState(input: UseSyncStateInput): SyncState {\r\n  // Resolve uma única vez por render; se a identidade da fonte resolvida mudar,\r\n  // o efeito abaixo re-subscreve (dependência `source`).\r\n  const source = resolveSyncStateSource(input);\r\n\r\n  const [state, setState] = React.useState<SyncState>(() => source.syncState);\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n\r\n    // Snapshot inicial imediato ao montar (pode ter mudado entre render e effect)\r\n    if (mountedRef.current) {\r\n      setState(source.syncState);\r\n    }\r\n\r\n    const unsubscribe: Unsubscribe = source.onSyncStateChanged((s: SyncState) => {\r\n      if (!mountedRef.current) return;\r\n      setState(s);\r\n    });\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [source]);\r\n\r\n  return state;\r\n}\r\n"]}

package/dist/db-react.d.cts

@@ -1,4 +1,4 @@
-import { aa as SyncState, af as Unsubscribe, o as DbDoc, z as NeetruClient, n as DbCollectionRef, t as DbQuery } from './types-nwErcRX8.cjs';
+import { aa as SyncState, af as Unsubscribe, o as DbDoc, z as NeetruClient, n as DbCollectionRef, t as DbQuery } from './types-DePdSU3P.cjs';
 import 'drizzle-orm/node-postgres';
 import './errors.cjs';
 

package/dist/db-react.d.ts

@@ -1,4 +1,4 @@
-import { aa as SyncState, af as Unsubscribe, o as DbDoc, z as NeetruClient, n as DbCollectionRef, t as DbQuery } from './types-BRv8wBxX.js';
+import { aa as SyncState, af as Unsubscribe, o as DbDoc, z as NeetruClient, n as DbCollectionRef, t as DbQuery } from './types-B3XFHD4A.js';
 import 'drizzle-orm/node-postgres';
 import './errors.js';
 

package/dist/db-react.mjs

@@ -67,6 +67,8 @@ function useCollection(ref, query) {
   });
   const mountedRef = React.useRef(true);
   const queryKey = serializeQuery(query);
+  const queryRef = React.useRef(query);
+  queryRef.current = query;
   React.useEffect(() => {
     mountedRef.current = true;
     setState({
@@ -77,7 +79,7 @@ function useCollection(ref, query) {
       hasPendingWrites: false
     });
     const unsubscribe = ref.onSnapshot(
-      query,
+      queryRef.current,
       (snap) => {
         if (!mountedRef.current) return;
         setState({

package/dist/db-react.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/db/react.ts"],"names":[],"mappings":"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","file":"db-react.mjs","sourcesContent":["/**\r\n * Bindings React do módulo db (M2) — `@neetru/sdk/react`.\r\n *\r\n * Exporta três hooks de tempo real que se integram com a camada offline do\r\n * `@neetru/sdk/db`:\r\n *\r\n *   - `useDocument(ref, id)` — subscreve ao onSnapshot de um documento.\r\n *   - `useCollection(ref, query?)` — subscreve ao onSnapshot de uma coleção.\r\n *   - `useSyncState(ns)` — observa o SyncState do namespace offline.\r\n *\r\n * ### Design\r\n * Segue o padrão do subpath `/react` existente (cliente/ref passados\r\n * explicitamente, sem Context Provider obrigatório). Alinhado com 02-sdk.md §3.6.\r\n *\r\n * ### React 18/19 StrictMode\r\n * Cada hook usa um ref interno para rastrear se o componente foi desmontado,\r\n * e a função `useEffect` retorna sempre a função de unsubscribe. Em StrictMode,\r\n * o duplo-mount/unmount do React 18 chama cleanup corretamente — não há leak.\r\n *\r\n * ### Dependências\r\n * `react` é peer dependency — não importada como dep direta.\r\n */\r\nimport * as React from 'react';\r\nimport type { DbCollectionRef, DbDoc, DbQuery, DbListResult, DbGetResult } from './collection-ref';\r\nimport type { SyncState, Unsubscribe } from './offline/types';\r\nimport type { NeetruClient } from '../types';\r\n\r\n// ─── Tipos públicos dos hooks ─────────────────────────────────────────────────\r\n\r\n/**\r\n * Resultado de `useDocument`.\r\n *\r\n * - `data` — dados do documento, ou `null` se não existe / ainda carregando.\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local, não do servidor.\r\n * - `stale` — conexão caída ou sincronizando; pode haver dados mais novos.\r\n */\r\nexport interface UseDocumentResult<T> {\r\n  data: T | null;\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n}\r\n\r\n/**\r\n * Resultado de `useCollection`.\r\n *\r\n * - `docs` — documentos da coleção (ou subconjunto via query).\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local.\r\n * - `stale` — conexão caída ou sincronizando.\r\n * - `hasPendingWrites` — ao menos um doc tem escrita local não confirmada.\r\n */\r\nexport interface UseCollectionResult<T> {\r\n  docs: DbDoc<T>[];\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n  hasPendingWrites: boolean;\r\n}\r\n\r\n/**\r\n * Subconjunto mínimo do namespace offline que `useSyncState` precisa.\r\n * Compatível com `NeetruDbDocuments` de `collection-ref.ts`.\r\n *\r\n * Passado explicitamente (sem Context) para alinhar com o padrão do SDK.\r\n * Tipicamente: o namespace retornado por `createOfflineDocumentsNamespace`.\r\n *\r\n * `client.db` (o `NeetruDb` retornado por `createNeetruClient`) também satisfaz\r\n * este contrato — expõe `syncState` + `onSyncStateChanged` reais. Por isso\r\n * `useSyncState` aceita tanto a fonte direta quanto o `NeetruClient` inteiro\r\n * (ver `UseSyncStateInput`).\r\n */\r\nexport interface SyncStateSource {\r\n  readonly syncState: SyncState;\r\n  onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;\r\n}\r\n\r\n/**\r\n * Entrada aceita por `useSyncState`:\r\n *   - `NeetruClient`     → resolve `client.db` automaticamente (forma oficial,\r\n *                          alinhada com 02-sdk.md §3.6 `useSyncState(client)`).\r\n *   - `SyncStateSource`  → fonte direta (`client.db` ou o namespace offline cru).\r\n */\r\nexport type UseSyncStateInput = NeetruClient | SyncStateSource;\r\n\r\n/**\r\n * Type guard — detecta se a entrada é um `NeetruClient` (tem `.db` que é, ele\r\n * próprio, um `SyncStateSource`) e não uma fonte direta. Distinção em runtime\r\n * porque os shapes não se sobrepõem: a fonte direta expõe `syncState` no nível\r\n * de topo; o client expõe via `.db`.\r\n */\r\nfunction isNeetruClient(input: UseSyncStateInput): input is NeetruClient {\r\n  const maybe = input as { db?: unknown; syncState?: unknown };\r\n  // Fonte direta já tem `syncState` no topo → não é o client wrapper.\r\n  if (typeof maybe.syncState !== 'undefined') return false;\r\n  const db = maybe.db as { syncState?: unknown; onSyncStateChanged?: unknown } | undefined;\r\n  return (\r\n    !!db &&\r\n    typeof db.syncState !== 'undefined' &&\r\n    typeof db.onSyncStateChanged === 'function'\r\n  );\r\n}\r\n\r\n/** Normaliza qualquer entrada aceita para a `SyncStateSource` subjacente. */\r\nfunction resolveSyncStateSource(input: UseSyncStateInput): SyncStateSource {\r\n  return isNeetruClient(input) ? (input.db as unknown as SyncStateSource) : input;\r\n}\r\n\r\n// ─── Serialização estável de query ────────────────────────────────────────────\r\n\r\n/**\r\n * Serializa uma DbQuery para string estável, usada como chave de efeito.\r\n *\r\n * `useCollection` re-subscreve somente quando a serialização muda, NÃO por\r\n * identidade de objeto. Isso evita a armadilha clássica de inline-object em\r\n * JSX que causaria re-subscribe em todo render.\r\n */\r\nfunction serializeQuery(query: DbQuery | undefined): string {\r\n  if (!query) return '';\r\n  try {\r\n    return JSON.stringify(query, Object.keys(query).sort());\r\n  } catch {\r\n    return String(query);\r\n  }\r\n}\r\n\r\n// ─── useDocument ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para um documento específico.\r\n *\r\n * Subscreve a `ref.doc(id).onSnapshot` no mount. Re-subscreve quando `ref`\r\n * ou `id` mudam. Cancela a subscrição no unmount.\r\n *\r\n * ```tsx\r\n * const { data, loading, fromCache, stale } = useDocument(ordersRef, orderId);\r\n * if (loading) return <Spinner />;\r\n * if (!data) return <NotFound />;\r\n * return <OrderCard order={data} fromCache={fromCache} />;\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode: a cleanup function do useEffect cancela\r\n * o listener no unmount, e o double-mount do StrictMode não vaza estado.\r\n */\r\nexport function useDocument<T>(\r\n  ref: DbCollectionRef<T>,\r\n  id: string,\r\n): UseDocumentResult<T> {\r\n  const [state, setState] = React.useState<UseDocumentResult<T>>({\r\n    data: null,\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n  });\r\n\r\n  // Ref para detectar unmount e evitar setState após cleanup.\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset para loading quando ref/id muda\r\n    setState({ data: null, loading: true, fromCache: true, stale: false });\r\n\r\n    const docRef = ref.doc(id);\r\n\r\n    const unsubscribe: Unsubscribe = docRef.onSnapshot(\r\n      (snap: DbGetResult<T> | null) => {\r\n        if (!mountedRef.current) return;\r\n        if (snap === null || snap.docs.length === 0) {\r\n          setState({\r\n            data: null,\r\n            loading: false,\r\n            fromCache: snap?.fromCache ?? true,\r\n            stale: snap?.stale ?? false,\r\n          });\r\n        } else {\r\n          setState({\r\n            data: snap.docs[0]?.data ?? null,\r\n            loading: false,\r\n            fromCache: snap.fromCache,\r\n            stale: snap.stale,\r\n          });\r\n        }\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, id]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useCollection ────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para uma coleção (ou subconjunto filtrado).\r\n *\r\n * Subscreve a `ref.onSnapshot(query, cb)` no mount. Re-subscreve quando `ref`\r\n * ou a serialização de `query` muda — NÃO por identidade de objeto, o que\r\n * evita re-subscribe desnecessário em inline objects.\r\n *\r\n * ```tsx\r\n * const { docs, loading, hasPendingWrites } = useCollection(ordersRef, {\r\n *   where: [{ field: 'status', op: '==', value: 'open' }],\r\n * });\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useCollection<T>(\r\n  ref: DbCollectionRef<T>,\r\n  query?: DbQuery,\r\n): UseCollectionResult<T> {\r\n  const [state, setState] = React.useState<UseCollectionResult<T>>({\r\n    docs: [],\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n    hasPendingWrites: false,\r\n  });\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  // Serializamos a query para garantir que mudanças de valor (não de referência)\r\n  // triggam o re-subscribe, mas que objetos iguais não causem loop.\r\n  const queryKey = serializeQuery(query);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset loading ao trocar de query/ref\r\n    setState({\r\n      docs: [],\r\n      loading: true,\r\n      fromCache: true,\r\n      stale: false,\r\n      hasPendingWrites: false,\r\n    });\r\n\r\n    const unsubscribe: Unsubscribe = ref.onSnapshot(\r\n      query,\r\n      (snap: DbListResult<T>) => {\r\n        if (!mountedRef.current) return;\r\n        setState({\r\n          docs: snap.docs,\r\n          loading: false,\r\n          fromCache: snap.fromCache,\r\n          stale: snap.stale,\r\n          hasPendingWrites: snap.hasPendingWrites,\r\n        });\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, queryKey]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useSyncState ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook para observar o `SyncState` da camada offline em tempo real.\r\n *\r\n * Retorna o `SyncState` atual e re-renderiza quando ele muda. Usado para\r\n * renderizar indicadores \"sincronizando…\" / \"offline\" / contadores de escritas\r\n * pendentes na UI.\r\n *\r\n * Aceita duas formas de entrada (SDK-QW-4 — wiring ao client real):\r\n *\r\n * ```tsx\r\n * // Forma oficial — passe o client; o hook resolve client.db internamente.\r\n * const client = createNeetruClient({ apiKey });\r\n * const state = useSyncState(client);\r\n *\r\n * // Forma direta — passe a fonte (client.db ou o namespace offline cru).\r\n * const state = useSyncState(client.db);\r\n *\r\n * if (state.status === 'offline') return <OfflineBanner pending={state.pendingWrites} />;\r\n * ```\r\n *\r\n * Antes desta versão o hook só aceitava a `SyncStateSource` crua, o que levava\r\n * consumers a stub-arem o estado pra sempre `'idle'` em vez de ligar no client.\r\n * Agora `useSyncState(client)` (a forma documentada em 02-sdk.md §3.6) funciona\r\n * de ponta a ponta — `client.db.syncState` / `client.db.onSyncStateChanged` são\r\n * reais.\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useSyncState(input: UseSyncStateInput): SyncState {\r\n  // Resolve uma única vez por render; se a identidade da fonte resolvida mudar,\r\n  // o efeito abaixo re-subscreve (dependência `source`).\r\n  const source = resolveSyncStateSource(input);\r\n\r\n  const [state, setState] = React.useState<SyncState>(() => source.syncState);\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n\r\n    // Snapshot inicial imediato ao montar (pode ter mudado entre render e effect)\r\n    if (mountedRef.current) {\r\n      setState(source.syncState);\r\n    }\r\n\r\n    const unsubscribe: Unsubscribe = source.onSyncStateChanged((s: SyncState) => {\r\n      if (!mountedRef.current) return;\r\n      setState(s);\r\n    });\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [source]);\r\n\r\n  return state;\r\n}\r\n"]}
+{"version":3,"sources":["../src/db/react.ts"],"names":[],"mappings":"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","file":"db-react.mjs","sourcesContent":["/**\r\n * Bindings React do módulo db (M2) — `@neetru/sdk/react`.\r\n *\r\n * Exporta três hooks de tempo real que se integram com a camada offline do\r\n * `@neetru/sdk/db`:\r\n *\r\n *   - `useDocument(ref, id)` — subscreve ao onSnapshot de um documento.\r\n *   - `useCollection(ref, query?)` — subscreve ao onSnapshot de uma coleção.\r\n *   - `useSyncState(ns)` — observa o SyncState do namespace offline.\r\n *\r\n * ### Design\r\n * Segue o padrão do subpath `/react` existente (cliente/ref passados\r\n * explicitamente, sem Context Provider obrigatório). Alinhado com 02-sdk.md §3.6.\r\n *\r\n * ### React 18/19 StrictMode\r\n * Cada hook usa um ref interno para rastrear se o componente foi desmontado,\r\n * e a função `useEffect` retorna sempre a função de unsubscribe. Em StrictMode,\r\n * o duplo-mount/unmount do React 18 chama cleanup corretamente — não há leak.\r\n *\r\n * ### Dependências\r\n * `react` é peer dependency — não importada como dep direta.\r\n */\r\nimport * as React from 'react';\r\nimport type { DbCollectionRef, DbDoc, DbQuery, DbListResult, DbGetResult } from './collection-ref';\r\nimport type { SyncState, Unsubscribe } from './offline/types';\r\nimport type { NeetruClient } from '../types';\r\n\r\n// ─── Tipos públicos dos hooks ─────────────────────────────────────────────────\r\n\r\n/**\r\n * Resultado de `useDocument`.\r\n *\r\n * - `data` — dados do documento, ou `null` se não existe / ainda carregando.\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local, não do servidor.\r\n * - `stale` — conexão caída ou sincronizando; pode haver dados mais novos.\r\n */\r\nexport interface UseDocumentResult<T> {\r\n  data: T | null;\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n}\r\n\r\n/**\r\n * Resultado de `useCollection`.\r\n *\r\n * - `docs` — documentos da coleção (ou subconjunto via query).\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local.\r\n * - `stale` — conexão caída ou sincronizando.\r\n * - `hasPendingWrites` — ao menos um doc tem escrita local não confirmada.\r\n */\r\nexport interface UseCollectionResult<T> {\r\n  docs: DbDoc<T>[];\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n  hasPendingWrites: boolean;\r\n}\r\n\r\n/**\r\n * Subconjunto mínimo do namespace offline que `useSyncState` precisa.\r\n * Compatível com `NeetruDbDocuments` de `collection-ref.ts`.\r\n *\r\n * Passado explicitamente (sem Context) para alinhar com o padrão do SDK.\r\n * Tipicamente: o namespace retornado por `createOfflineDocumentsNamespace`.\r\n *\r\n * `client.db` (o `NeetruDb` retornado por `createNeetruClient`) também satisfaz\r\n * este contrato — expõe `syncState` + `onSyncStateChanged` reais. Por isso\r\n * `useSyncState` aceita tanto a fonte direta quanto o `NeetruClient` inteiro\r\n * (ver `UseSyncStateInput`).\r\n */\r\nexport interface SyncStateSource {\r\n  readonly syncState: SyncState;\r\n  onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;\r\n}\r\n\r\n/**\r\n * Entrada aceita por `useSyncState`:\r\n *   - `NeetruClient`     → resolve `client.db` automaticamente (forma oficial,\r\n *                          alinhada com 02-sdk.md §3.6 `useSyncState(client)`).\r\n *   - `SyncStateSource`  → fonte direta (`client.db` ou o namespace offline cru).\r\n */\r\nexport type UseSyncStateInput = NeetruClient | SyncStateSource;\r\n\r\n/**\r\n * Type guard — detecta se a entrada é um `NeetruClient` (tem `.db` que é, ele\r\n * próprio, um `SyncStateSource`) e não uma fonte direta. Distinção em runtime\r\n * porque os shapes não se sobrepõem: a fonte direta expõe `syncState` no nível\r\n * de topo; o client expõe via `.db`.\r\n */\r\nfunction isNeetruClient(input: UseSyncStateInput): input is NeetruClient {\r\n  const maybe = input as { db?: unknown; syncState?: unknown };\r\n  // Fonte direta já tem `syncState` no topo → não é o client wrapper.\r\n  if (typeof maybe.syncState !== 'undefined') return false;\r\n  const db = maybe.db as { syncState?: unknown; onSyncStateChanged?: unknown } | undefined;\r\n  return (\r\n    !!db &&\r\n    typeof db.syncState !== 'undefined' &&\r\n    typeof db.onSyncStateChanged === 'function'\r\n  );\r\n}\r\n\r\n/** Normaliza qualquer entrada aceita para a `SyncStateSource` subjacente. */\r\nfunction resolveSyncStateSource(input: UseSyncStateInput): SyncStateSource {\r\n  return isNeetruClient(input) ? (input.db as unknown as SyncStateSource) : input;\r\n}\r\n\r\n// ─── Serialização estável de query ────────────────────────────────────────────\r\n\r\n/**\r\n * Serializa uma DbQuery para string estável, usada como chave de efeito.\r\n *\r\n * `useCollection` re-subscreve somente quando a serialização muda, NÃO por\r\n * identidade de objeto. Isso evita a armadilha clássica de inline-object em\r\n * JSX que causaria re-subscribe em todo render.\r\n */\r\nfunction serializeQuery(query: DbQuery | undefined): string {\r\n  if (!query) return '';\r\n  try {\r\n    return JSON.stringify(query, Object.keys(query).sort());\r\n  } catch {\r\n    return String(query);\r\n  }\r\n}\r\n\r\n// ─── useDocument ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para um documento específico.\r\n *\r\n * Subscreve a `ref.doc(id).onSnapshot` no mount. Re-subscreve quando `ref`\r\n * ou `id` mudam. Cancela a subscrição no unmount.\r\n *\r\n * ```tsx\r\n * const { data, loading, fromCache, stale } = useDocument(ordersRef, orderId);\r\n * if (loading) return <Spinner />;\r\n * if (!data) return <NotFound />;\r\n * return <OrderCard order={data} fromCache={fromCache} />;\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode: a cleanup function do useEffect cancela\r\n * o listener no unmount, e o double-mount do StrictMode não vaza estado.\r\n */\r\nexport function useDocument<T>(\r\n  ref: DbCollectionRef<T>,\r\n  id: string,\r\n): UseDocumentResult<T> {\r\n  const [state, setState] = React.useState<UseDocumentResult<T>>({\r\n    data: null,\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n  });\r\n\r\n  // Ref para detectar unmount e evitar setState após cleanup.\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset para loading quando ref/id muda\r\n    setState({ data: null, loading: true, fromCache: true, stale: false });\r\n\r\n    const docRef = ref.doc(id);\r\n\r\n    const unsubscribe: Unsubscribe = docRef.onSnapshot(\r\n      (snap: DbGetResult<T> | null) => {\r\n        if (!mountedRef.current) return;\r\n        if (snap === null || snap.docs.length === 0) {\r\n          setState({\r\n            data: null,\r\n            loading: false,\r\n            fromCache: snap?.fromCache ?? true,\r\n            stale: snap?.stale ?? false,\r\n          });\r\n        } else {\r\n          setState({\r\n            data: snap.docs[0]?.data ?? null,\r\n            loading: false,\r\n            fromCache: snap.fromCache,\r\n            stale: snap.stale,\r\n          });\r\n        }\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, id]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useCollection ────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para uma coleção (ou subconjunto filtrado).\r\n *\r\n * Subscreve a `ref.onSnapshot(query, cb)` no mount. Re-subscreve quando `ref`\r\n * ou a serialização de `query` muda — NÃO por identidade de objeto, o que\r\n * evita re-subscribe desnecessário em inline objects.\r\n *\r\n * ```tsx\r\n * const { docs, loading, hasPendingWrites } = useCollection(ordersRef, {\r\n *   where: [{ field: 'status', op: '==', value: 'open' }],\r\n * });\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useCollection<T>(\r\n  ref: DbCollectionRef<T>,\r\n  query?: DbQuery,\r\n): UseCollectionResult<T> {\r\n  const [state, setState] = React.useState<UseCollectionResult<T>>({\r\n    docs: [],\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n    hasPendingWrites: false,\r\n  });\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  // Serializamos a query para garantir que mudanças de valor (não de referência)\r\n  // triggam o re-subscribe, mas que objetos iguais não causem loop.\r\n  const queryKey = serializeQuery(query);\r\n\r\n  // Bug corrigido: o efeito usava `query` da closure externa, que poderia estar\r\n  // desatualizado quando ref mudava sem o queryKey mudar. O ref mantém sempre o\r\n  // valor mais recente sem re-disparar o efeito.\r\n  const queryRef = React.useRef(query);\r\n  queryRef.current = query;\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset loading ao trocar de query/ref\r\n    setState({\r\n      docs: [],\r\n      loading: true,\r\n      fromCache: true,\r\n      stale: false,\r\n      hasPendingWrites: false,\r\n    });\r\n\r\n    const unsubscribe: Unsubscribe = ref.onSnapshot(\r\n      queryRef.current,\r\n      (snap: DbListResult<T>) => {\r\n        if (!mountedRef.current) return;\r\n        setState({\r\n          docs: snap.docs,\r\n          loading: false,\r\n          fromCache: snap.fromCache,\r\n          stale: snap.stale,\r\n          hasPendingWrites: snap.hasPendingWrites,\r\n        });\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, queryKey]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useSyncState ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook para observar o `SyncState` da camada offline em tempo real.\r\n *\r\n * Retorna o `SyncState` atual e re-renderiza quando ele muda. Usado para\r\n * renderizar indicadores \"sincronizando…\" / \"offline\" / contadores de escritas\r\n * pendentes na UI.\r\n *\r\n * Aceita duas formas de entrada (SDK-QW-4 — wiring ao client real):\r\n *\r\n * ```tsx\r\n * // Forma oficial — passe o client; o hook resolve client.db internamente.\r\n * const client = createNeetruClient({ apiKey });\r\n * const state = useSyncState(client);\r\n *\r\n * // Forma direta — passe a fonte (client.db ou o namespace offline cru).\r\n * const state = useSyncState(client.db);\r\n *\r\n * if (state.status === 'offline') return <OfflineBanner pending={state.pendingWrites} />;\r\n * ```\r\n *\r\n * Antes desta versão o hook só aceitava a `SyncStateSource` crua, o que levava\r\n * consumers a stub-arem o estado pra sempre `'idle'` em vez de ligar no client.\r\n * Agora `useSyncState(client)` (a forma documentada em 02-sdk.md §3.6) funciona\r\n * de ponta a ponta — `client.db.syncState` / `client.db.onSyncStateChanged` são\r\n * reais.\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useSyncState(input: UseSyncStateInput): SyncState {\r\n  // Resolve uma única vez por render; se a identidade da fonte resolvida mudar,\r\n  // o efeito abaixo re-subscreve (dependência `source`).\r\n  const source = resolveSyncStateSource(input);\r\n\r\n  const [state, setState] = React.useState<SyncState>(() => source.syncState);\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n\r\n    // Snapshot inicial imediato ao montar (pode ter mudado entre render e effect)\r\n    if (mountedRef.current) {\r\n      setState(source.syncState);\r\n    }\r\n\r\n    const unsubscribe: Unsubscribe = source.onSyncStateChanged((s: SyncState) => {\r\n      if (!mountedRef.current) return;\r\n      setState(s);\r\n    });\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [source]);\r\n\r\n  return state;\r\n}\r\n"]}

package/dist/db.cjs

@@ -87,8 +87,47 @@ var init_idempotency = __esm({
 // src/http.ts
 var http_exports = {};
 __export(http_exports, {
+  checkCoreVersionCompat: () => checkCoreVersionCompat,
   httpRequest: () => httpRequest
 });
+function stripRevision(v) {
+  return v.split("+")[0] ?? v;
+}
+function compareCalVer(a, b) {
+  const partsA = stripRevision(a).split(".").map(Number);
+  const partsB = stripRevision(b).split(".").map(Number);
+  const len = Math.max(partsA.length, partsB.length);
+  for (let i = 0; i < len; i++) {
+    const pa = partsA[i] ?? 0;
+    const pb = partsB[i] ?? 0;
+    if (pa !== pb) return pa - pb;
+  }
+  return 0;
+}
+function getSdkMajor() {
+  try {
+    const ver = globalThis.__NEETRU_SDK_VERSION__;
+    if (ver) return parseInt(ver.split(".")[0] ?? "3", 10);
+  } catch {
+  }
+  return 3;
+}
+function checkCoreVersionCompat(coreVersion) {
+  if (!coreVersion) return;
+  const sdkMajor = getSdkMajor();
+  const minCore = COMPAT_MATRIX[sdkMajor];
+  if (!minCore) return;
+  const stripped = stripRevision(coreVersion);
+  if (compareCalVer(stripped, minCore) < 0) {
+    const key = `${sdkMajor}:${stripped}`;
+    if (!_warnedCoreTooOld.has(key)) {
+      _warnedCoreTooOld.add(key);
+      console.warn(
+        `[Neetru SDK] Aten\xE7\xE3o: Core vers\xE3o "${coreVersion}" \xE9 anterior ao m\xEDnimo recomendado "${minCore}" para SDK major ${sdkMajor}. Alguns recursos podem n\xE3o funcionar corretamente. Atualize o Core para a vers\xE3o mais recente.`
+      );
+    }
+  }
+}
 function backoffMs(attempt) {
   const base = 200 * Math.pow(4, attempt);
   const jitter = base * 0.2 * (Math.random() * 2 - 1);
@@ -97,11 +136,11 @@ function backoffMs(attempt) {
 function parseRetryAfter(value) {
   if (!value) return null;
   const secs = Number(value);
-  if (Number.isFinite(secs) && secs >= 0) return Math.round(secs * 1e3);
+  if (Number.isFinite(secs) && secs >= 0) return Math.min(Math.round(secs * 1e3), MAX_RETRY_AFTER_MS);
   const dateMs = Date.parse(value);
   if (Number.isFinite(dateMs)) {
     const delta = dateMs - Date.now();
-    if (delta > 0) return delta;
+    if (delta > 0) return Math.min(delta, MAX_RETRY_AFTER_MS);
   }
   return null;
 }
@@ -112,6 +151,7 @@ function statusToCode(status) {
   if (status === 401) return "unauthorized";
   if (status === 403) return "forbidden";
   if (status === 404) return "not_found";
+  if (status === 409) return "conflict";
   if (status === 422 || status === 400) return "validation_failed";
   if (status === 429) return "rate_limited";
   if (status >= 500) return "server_error";
@@ -183,6 +223,8 @@ async function httpRequest(config, opts) {
     }
     const requestId = res.headers.get("x-request-id") ?? res.headers.get("x-correlation-id") ?? void 0;
     if (res.ok) {
+      const coreVersion = res.headers.get("x-neetru-version");
+      if (coreVersion) checkCoreVersionCompat(coreVersion);
       const parsed = await safeJson(res);
       return parsed;
     }
@@ -211,11 +253,17 @@ async function httpRequest(config, opts) {
   }
   throw lastError ?? new NeetruError("unknown", "unexpected httpRequest exit");
 }
-var DEFAULT_RETRIES_READ, DEFAULT_RETRIES_WRITE, READ_METHODS, RETRYABLE_CODES2;
+var COMPAT_MATRIX, _warnedCoreTooOld, DEFAULT_RETRIES_READ, DEFAULT_RETRIES_WRITE, READ_METHODS, RETRYABLE_CODES2, MAX_RETRY_AFTER_MS;
 var init_http = __esm({
   "src/http.ts"() {
     init_errors();
     init_idempotency();
+    COMPAT_MATRIX = {
+      // SDK major 3.x requer Core ≥ 2026.05.1 (suporte a X-Neetru-Version header,
+      // runTransaction write-after-read, verifyWebhookRequest, webhooks 3.0+)
+      3: "2026.05.1"
+    };
+    _warnedCoreTooOld = /* @__PURE__ */ new Set();
     DEFAULT_RETRIES_READ = 2;
     DEFAULT_RETRIES_WRITE = 0;
     READ_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD"]);
@@ -224,6 +272,7 @@ var init_http = __esm({
       "server_error",
       "network_error"
     ]);
+    MAX_RETRY_AFTER_MS = 6e4;
   }
 });
 
@@ -790,6 +839,31 @@ var LocalStore = class {
     this.db?.close();
     this.db = null;
   }
+  /**
+   * Apaga completamente o banco IndexedDB e o recria do zero.
+   *
+   * Ao contrário de `close()` + `open()` (que reabre o banco existente sem
+   * apagar dados), `clearAll()` chama `indexedDB.deleteDatabase(dbName)` e
+   * só então chama `open()` — garantindo que nenhum documento, mutação ou
+   * metadado sobrevive.
+   *
+   * BUG fix: `clearCache()` em `NeetruDbDocumentsImpl` chamava close+open,
+   * que reabre o mesmo banco. `clearAll()` é o método correto.
+   */
+  async clearAll() {
+    if (this.db !== null) {
+      this.db.close();
+      this.db = null;
+    }
+    await new Promise((resolve, reject) => {
+      const req = indexedDB.deleteDatabase(this.dbName);
+      req.onsuccess = () => resolve();
+      req.onerror = () => reject(req.error);
+      req.onblocked = () => {
+      };
+    });
+    await this.open();
+  }
   assertOpen() {
     if (this.db === null) {
       throw new Error("LocalStore: banco n\xE3o est\xE1 aberto. Chame open() primeiro.");
@@ -997,6 +1071,12 @@ var MemoryStore = class {
   async open() {
   }
   async close() {
+  }
+  /**
+   * Apaga todos os dados em memória — equivalente ao `indexedDB.deleteDatabase`
+   * que `LocalStore.clearAll()` executa em ambientes com IndexedDB.
+   */
+  async clearAll() {
     this._docs.clear();
     this._mutations.clear();
     this._meta.clear();
@@ -1522,6 +1602,8 @@ var SyncEngine = class {
       const phase1Ok = await this._phase1Push();
       if (!phase1Ok) {
         this._updateState({ status: "idle" });
+        this._refreshPendingWrites().catch(() => {
+        });
         this._syncing = false;
         return;
       }
@@ -1908,7 +1990,7 @@ var SyncEngine = class {
             ownerId: localDoc.meta.ownerId
           }
         };
-        const pendingMuts = await this._queue.drain();
+        const pendingMuts = await this._queue.listAll();
         const docMut = pendingMuts.find(
           (m) => m.collection === serverDoc.collection && m.docId === serverDoc.id
         );
@@ -3262,8 +3344,13 @@ var NeetruDbDocumentsImpl = class {
     return this._engine.flush();
   }
   async clearCache() {
-    await this._store.close();
-    await this._store.open();
+    const storeWithClear = this._store;
+    if (typeof storeWithClear.clearAll === "function") {
+      await storeWithClear.clearAll();
+    } else {
+      await this._store.close();
+      await this._store.open();
+    }
   }
   async getConflicts() {
     return this._store.listConflicts();