@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/seedgridKB/SeedGrid/SeedGrid-components/providers/API.md

@@ -0,0 +1,177 @@
+---
+tags: [seedgrid, front, component, providers]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-components/src/environment, front/seedgrid-fe-components/packages/seedgrid-fe-components/src/realtime
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# API — providers de ambiente e realtime
+
+Visão geral: [[SeedGrid/SeedGrid-components/providers/Visao-geral|Providers — visão geral]] · Exemplos: [[SeedGrid/SeedGrid-components/providers/Exemplos|Exemplos dos providers]]
+
+> **Como ler as tabelas.** Geradas a partir do tipo TypeScript real do 1º parâmetro de cada componente (TS checker, commit `ad30fc11de`) — lista completa das props próprias. **Padrão**: valor sem marca = inicializador na desestruturação do componente (Confirmado); `ᶠ` = fallback interno `??` no corpo do componente (Confirmado, expressão pode estar abreviada); `ᵇ` = padrão aplicado pelo componente base para o qual a prop é repassada; `ᵐ` = declarado só no `*.meta.ts`; `ˢ` = declarado só na tabela de props do showcase (`ᵐ`/`ˢ` = Não confirmado no código); `—` = sem padrão. **Descrição**: JSDoc > `*.meta.ts` > tabela do showcase (textos originais, sem acento quando assim na fonte); *(Inferência)* = escrita a partir da leitura do código. **Obrigatória** = prop não opcional no tipo.
+
+## SgEnvironmentProvider
+
+Provider de namespace, escopo e estratégia de persistência usados pelos componentes SeedGrid. Fonte: `src/environment/SgEnvironmentProvider.tsx` → `SgEnvironmentProvider`; tipos em `src/environment/persistence.ts`.
+
+### Import
+
+```tsx
+import {
+  SgEnvironmentProvider,
+  useSgEnvironment,
+  useSgNamespaceProvider,
+  useSgPersistence,
+  useSgPersistentState,
+  buildSgPersistenceKey,
+  createLocalStorageStrategy,
+  createApiPersistenceStrategy,
+  createCompositePersistenceStrategy,
+  type SgEnvironmentValue,
+  type PersistenceStrategy,
+  type NamespaceProvider
+} from "@seedgrid/fe-components";
+```
+
+### Props
+
+| Prop | Tipo | Padrão | Obrigatória | Descrição |
+|---|---|---|---|---|
+| `value` | `Partial<SgEnvironmentValue>` | — | Não | Sobrescritas parciais do ambiente (`namespaceProvider`, `persistenceStrategy`, `persistence.scope/mode/stateVersion`); cada campo ausente cai no padrão interno (namespace vazio, localStorage, `app:unknown`, `fallback`, `1`). |
+| `children` | `React.ReactNode` | — | Sim | Arvore que consome o contexto de ambiente. |
+
+- Tipo de props declarado inline na assinatura de `SgEnvironmentProvider` (não há tipo `SgEnvironmentProviderProps` exportado).
+
+Resolução de `value` (Confirmado, `useMemo` do provider): cada campo é resolvido isoladamente com `??`.
+
+| Campo de `value` | Tipo | Padrão quando ausente |
+|---|---|---|
+| `namespaceProvider` | `NamespaceProvider` | `{ getNamespace: () => "" }` |
+| `persistenceStrategy` | `PersistenceStrategy` | `createLocalStorageStrategy()` (sem prefixo) |
+| `persistence.scope` | `string` | `"app:unknown"` |
+| `persistence.mode` | `SgPersistenceMode` | `"fallback"` |
+| `persistence.stateVersion` | `number` | `1` |
+
+O valor do contexto só é recriado quando muda uma dessas cinco referências (dependências do `useMemo`).
+
+### Eventos e callbacks
+
+Nenhum evento próprio. Os callbacks relevantes estão nas estratégias (`load`/`save`/`clear`) — ver tipos abaixo.
+
+### Ref
+
+Não aceita `ref` (função simples, sem `forwardRef`).
+
+### Children, slots e composição
+
+`children` obrigatório: a árvore que consome o contexto. Pode ser aninhado; o provider mais próximo vence (contexto React). Componentes que leem este contexto: `SgFloatActionButton`, `SgCard`, `SgMenu`, `SgToolBar`, `SgDockMenu`, `SgDockLayout` (Confirmado por import).
+
+### Contexto, providers e hooks
+
+Contexto interno `SgEnvironmentContext` (não exportado). Hooks exportados:
+
+| Hook | Assinatura | Retorno / comportamento (Confirmado) |
+|---|---|---|
+| `useSgEnvironment` | `(): SgEnvironmentValue` | Contexto do provider mais próximo ou o ambiente padrão (namespace `""`, localStorage, `app:unknown`/`fallback`/`1`). |
+| `useSgNamespaceProvider` | `(): NamespaceProvider` | `useSgEnvironment().namespaceProvider`. |
+| `useSgPersistence` | `(): { namespace: string \| null; scope: string; mode: SgPersistenceMode; stateVersion: number; load(baseKey: string): Promise<unknown>; save(baseKey: string, state: unknown): Promise<void>; clear(baseKey: string): Promise<void> }` | Calcula a chave com `buildSgPersistenceKey(baseKey, namespace, scope)`; se a chave for `null` (namespace vazio) `load` retorna `null` e `save`/`clear` não fazem nada. `load/save/clear` são memoizados por estratégia, namespace e scope. |
+| `useSgPersistentState<T>` | `(args: { baseKey: string; defaultValue: T; serialize?: (value: T) => unknown; deserialize?: (value: unknown) => T }): { value: T; setValue: (next: T \| ((prev: T) => T)) => void; clear: () => Promise<void>; hydrated: boolean }` | Começa com `defaultValue` e `hydrated=false`; no mount carrega (com provider: `useSgPersistence().load(baseKey)`; sem provider: `localStorage.getItem(baseKey)` + `JSON.parse`), aplica `deserialize` se o valor não for `null/undefined` e marca `hydrated=true` (em erro volta ao `defaultValue`). Depois de hidratado, cada mudança de `value` é salva (com provider: `save(baseKey, serialize(value))`; sem provider: `localStorage.setItem(baseKey, JSON.stringify(value))`, sem `serialize`). `clear` limpa e volta ao `defaultValue`. |
+
+Observação (Inferência): o efeito de carregamento depende de `defaultValue` e `deserialize`; passar um objeto/função novo a cada render provoca recarga. `serialize`/`deserialize` são memoizados pela referência recebida.
+
+### Funções e tipos de persistência (exportados)
+
+| Símbolo | Assinatura | Comportamento (Confirmado — `src/environment/persistence.ts`) |
+|---|---|---|
+| `buildSgPersistenceKey` | `(baseKey: string, namespace?: string \| null, scope?: string \| null) => string \| null` | `null` se namespace vazio; `sg:<namespace>:<baseKey>` se scope vazio (após `trim`); senão `sg:<namespace>:<scope>:<baseKey>`. |
+| `createLocalStorageStrategy` | `(options?: { prefix?: string }) => PersistenceStrategy` | `window.localStorage` com `JSON.stringify/parse`; chave = `prefix + key`; erros engolidos (`load` → `null`). |
+| `createApiPersistenceStrategy` | `(args: { baseUrl: string; fetcher?: (input: RequestInfo \| URL, init?: RequestInit) => Promise<Response>; scope: string; stateVersion: number }) => PersistenceStrategy` | `load`: `GET {baseUrl}/sg/persistence?key=…` → espera `{ found?: boolean; record?: SgPersistenceRecordDTO }` e devolve `record.state` ou `null`. `save`: `POST {baseUrl}/sg/persistence` com corpo `{ record }` (`protocolVersion: 1`, `key`, `scope`, `stateVersion`, `updatedAt` ISO, `state`). `clear`: `DELETE {baseUrl}/sg/persistence?key=…`. Resposta não-OK lança `Error("SG persistence <op> failed (<status>)")`. Barra final de `baseUrl` é removida; `fetcher` padrão = `fetch` global. |
+| `createCompositePersistenceStrategy` | `(args: { mode: SgPersistenceMode; primary: PersistenceStrategy; secondary: PersistenceStrategy }) => PersistenceStrategy` | `strict`: só a primária. `fallback`: primária; se lançar, secundária. `mirror`: `load` tenta a primária e usa a secundária se der erro ou vier `null/undefined`; `save`/`clear` em ambas com `Promise.allSettled`. |
+| `resolvePersistedStateValue<T>` | `(args: { loaded: unknown; defaultValue: T; deserialize: (value: unknown) => T }) => T` | `defaultValue` se `loaded` é `null/undefined`; senão `deserialize(loaded)`. |
+| `readLocalPersistentState<T>` | `(args: { storage: Pick<Storage, "getItem">; baseKey: string; defaultValue: T; deserialize: (value: unknown) => T }) => T` | Lê e faz `JSON.parse`; ausência ou erro → `defaultValue`. |
+| `writeLocalPersistentState<T>` | `(args: { storage: Pick<Storage, "setItem">; baseKey: string; value: T }) => void` | `setItem(baseKey, JSON.stringify(value))` (pode lançar). |
+| `clearLocalPersistentState<T>` | `(args: { storage: Pick<Storage, "removeItem">; baseKey: string; defaultValue: T }) => T` | `removeItem(baseKey)` e devolve `defaultValue`. |
+
+| Tipo | Definição (Confirmado) |
+|---|---|
+| `NamespaceProvider` | `{ getNamespace: () => string \| null }` |
+| `PersistenceStrategy` | `{ load: (key: string) => unknown \| Promise<unknown>; save: (key: string, state: unknown) => void \| Promise<void>; clear: (key: string) => void \| Promise<void> }` |
+| `SgPersistenceMode` | `"strict" \| "fallback" \| "mirror"` |
+| `SgPersistenceConfig` | `{ scope: string; mode: SgPersistenceMode; stateVersion: number }` |
+| `SgEnvironmentValue` | `{ namespaceProvider: NamespaceProvider; persistenceStrategy: PersistenceStrategy; persistence: SgPersistenceConfig }` |
+| `SgEnvironment` | alias de `SgEnvironmentValue` |
+| `SgPersistenceRecordDTO` | `{ protocolVersion: 1; key: string; scope: string; stateVersion: number; updatedAt: string; state: unknown }` |
+
+### Acessibilidade
+
+Não se aplica (não renderiza DOM; só `Context.Provider`).
+
+## SgRealtimeProvider
+
+Avisos em tempo real para o usuário logado pelo SeedGrid Pulse. Fonte: `src/realtime/SgRealtimeProvider.tsx` → `SgRealtimeProvider`, `useSgRealtimeEvent`, `useSgRealtimeStatus`, `matchesSgRealtimeEvent`.
+
+### Import
+
+```tsx
+import {
+  SgRealtimeProvider,
+  useSgRealtimeEvent,
+  useSgRealtimeStatus,
+  matchesSgRealtimeEvent,
+  type SgRealtimeProviderProps,
+  type SgRealtimeStatus,
+  type SgRealtimeEvent,
+  type SgRealtimeConnectResponse
+} from "@seedgrid/fe-components";
+```
+
+### Props
+
+| Prop | Tipo | Padrão | Obrigatória | Descrição |
+|---|---|---|---|---|
+| `children` | `React.ReactNode` | — | Sim | Arvore que ouve os avisos com useSgRealtimeEvent. |
+| `channels` | `string[]` | — | Sim | Channels que a tela quer ouvir (ex.: `["backup"]`). |
+| `tokenEndpoint` | `string` | `"/api/realtime/connect"` (`DEFAULT_TOKEN_ENDPOINT`) | Não | Rota que entrega o token de conexão do usuário logado. Default: `/api/realtime/connect` (a BFF, na mesma origem — o navegador manda o cookie da sessão). |
+| `tokenRequestInit` | `RequestInit` | — | Não | Opções do `fetch` do token (ex.: `headers: { Authorization: ... }` quando não há cookie). |
+| `fetchToken` | `() => Promise<SgRealtimeConnectResponse>` | — | Não | Substitui o pedido de token inteiro (apps sem BFF, testes). |
+| `pulseUrl` | `string` | — | Não | Endereço do Pulse, usado quando o token não traz `connectUrl` (Pulse sem endereço público). |
+| `enabled` | `boolean` | `true` | Não | Liga/desliga (ex.: `false` enquanto não há usuário logado). Default: `true`. |
+| `connectOptions` | `Omit<ConnectInput, "getToken" \| "accountKey" \| "baseUrl">` | — | Não | Opções avançadas do cliente do Pulse (reconexão, `webSocketImpl` em testes...). |
+
+`ConnectInput` vem de `@seedgrid/pulse-subscriber-react/core` (v3.0.0 instalada). Campos que restam após o `Omit` (lidos em `dist/core.d.ts` do pacote): `protocolVersion?` (padrão 1), `reconnect?: ReconnectOptions`, `auth?: PulseAuthOptions`, `connectPath?` (padrão `/api/v1/connect`), `webSocketImpl?`, `wsOptions?`, `connectTimeoutMs?` (padrão 10000), `logger?`. O provider sempre injeta `getToken` e, se informado, `baseUrl = pulseUrl`.
+
+### Eventos e callbacks
+
+- `fetchToken()` — chamado na conexão e em cada reconexão (o primeiro token é reaproveitado uma única vez). Sem `fetchToken`, o provider faz `fetch(tokenEndpoint, { method: "POST", credentials: "same-origin", ...tokenRequestInit })`; HTTP não-OK lança erro → status `unavailable`.
+- Resposta `enabled: false` ou sem `token` → status `disabled` e nenhuma conexão.
+- Mensagens recebidas viram `SgRealtimeEvent` e são entregues a todos os listeners; exceção num handler não afeta os demais.
+
+### Ref
+
+Não aceita `ref`.
+
+### Children, slots e composição
+
+`children` obrigatório. Montar uma vez (ex.: no layout autenticado). Sem `channels` (array vazio) ou com `enabled=false` não conecta (status `idle` ou `disabled`, respectivamente). Em SSR (`typeof window === "undefined"`) não conecta.
+
+### Contexto, providers e hooks
+
+Contexto interno `SgRealtimeContext` (`{ status, addListener }`, não exportado).
+
+| Símbolo | Assinatura | Comportamento (Confirmado) |
+|---|---|---|
+| `useSgRealtimeEvent` | `(channel: string, events: string \| string[], handler: (event: SgRealtimeEvent) => void) => void` | Registra listener enquanto montado; chama `handler` quando `event.channel === channel` e o nome casa algum padrão de `events`. Usa sempre o `handler` mais recente (ref). Fora do provider, não faz nada. |
+| `useSgRealtimeStatus` | `() => { status: SgRealtimeStatus; connected: boolean }` | `connected = status === "connected"`; fora do provider, `status = "disabled"`. |
+| `matchesSgRealtimeEvent` | `(pattern: string, event: string) => boolean` | `true` para `"*"`, nome idêntico ou `prefixo.*` (casa nomes que começam com `prefixo.`). |
+
+| Tipo | Definição (Confirmado) |
+|---|---|
+| `SgRealtimeStatus` | `"idle" \| "disabled" \| "connecting" \| "connected" \| "reconnecting" \| "unavailable" \| "auth-error"` — JSDoc: fora de `connected`, a tela deve usar polling. |
+| `SgRealtimeConnectResponse` | `{ enabled: boolean; token?: string; expiresAt?: number /* segundos desde a época */; connectUrl?: string }` — campos da resposta do `POST /realtime/connect` das extensões de realtime que o provider lê (Confirmado). |
+| `SgRealtimeEvent` | `{ channel: string; event: string; data: unknown; messageId: string; publishedAt: string }` — JSDoc: `data` só traz identificadores; buscar o registro pela API. |
+
+### Acessibilidade
+
+Não se aplica (não renderiza DOM).

package/seedgridKB/SeedGrid/SeedGrid-components/providers/Exemplos.md

@@ -0,0 +1,332 @@
+---
+tags: [seedgrid, front, component, providers]
+fonte: front/seedgrid-fe-components/apps/showcase/src/app/components/providers, front/seedgrid-fe-components/apps/showcase/src/app/components/hooks
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# Exemplos — providers de ambiente e realtime
+
+API: [[SeedGrid/SeedGrid-components/providers/API|API dos providers]] · Visão geral: [[SeedGrid/SeedGrid-components/providers/Visao-geral|Providers — visão geral]]
+
+Todos os exemplos abaixo foram copiados 1:1 dos samples do showcase (exceto onde indicado) e passaram em type-check contra `packages/seedgrid-fe-components/src/index.ts` (TypeScript do monorepo, `strict`).
+
+## SgEnvironmentProvider
+
+### Namespace e escopo customizados
+
+Mostra a chave final que os componentes usariam (`sg:u:123:app:crm:fab:theme`).
+
+Fonte: `apps/showcase/src/app/components/providers/sg-environment-provider/samples/namespace-customizado.tsx.sample` (type-check: OK).
+
+```tsx
+import { SgEnvironmentProvider, buildSgPersistenceKey, useSgEnvironment } from "@seedgrid/fe-components";
+
+function EnvInfo() {
+  const env = useSgEnvironment();
+  const namespace = env.namespaceProvider.getNamespace();
+  const fullKey = buildSgPersistenceKey("fab:theme", namespace, env.persistence.scope);
+  return <div>fullKey: {fullKey ?? "null"}</div>;
+}
+
+export default function Example() {
+  return (
+    <SgEnvironmentProvider
+      value={{
+        namespaceProvider: { getNamespace: () => "u:123" },
+        persistence: { scope: "app:crm", mode: "fallback", stateVersion: 1 },
+      }}
+    >
+      <EnvInfo />
+    </SgEnvironmentProvider>
+  );
+}
+```
+
+### Persistência REST por usuário com fallback local
+
+Adaptado do sample `providers/sg-environment-provider/samples/rest-por-usuario.tsx.sample`: o original **não importa** `createApiPersistenceStrategy`, `createLocalStorageStrategy` e `createCompositePersistenceStrategy` e falha no type-check; abaixo, o mesmo código com o import completo (type-check: OK). Em modo `fallback`, se a API lançar erro, a estratégia usa o `localStorage`. A URL é ilustrativa.
+
+```tsx
+import {
+  SgEnvironmentProvider,
+  createApiPersistenceStrategy,
+  createCompositePersistenceStrategy,
+  createLocalStorageStrategy,
+} from "@seedgrid/fe-components";
+
+const api = createApiPersistenceStrategy({
+  baseUrl: "https://api.seedgrid.com",
+  scope: "app:crm",
+  stateVersion: 1,
+});
+
+const local = createLocalStorageStrategy();
+const persistence = createCompositePersistenceStrategy({
+  mode: "fallback",
+  primary: api,
+  secondary: local,
+});
+
+export default function Example() {
+  return (
+    <SgEnvironmentProvider
+      value={{
+        namespaceProvider: { getNamespace: () => "u:123" },
+        persistenceStrategy: persistence,
+        persistence: { scope: "app:crm", mode: "fallback", stateVersion: 1 },
+      }}
+    >
+      <div>componentes persistentes</div>
+    </SgEnvironmentProvider>
+  );
+}
+```
+
+Para espelhar em ambos (`mirror`), troque `mode: "fallback"` por `mode: "mirror"` em `createCompositePersistenceStrategy` (é o que faz o sample `hybrid-local-rest`, com o mesmo problema de import).
+
+## useSgEnvironment
+
+### Lendo o ambiente fornecido
+
+Fonte: `apps/showcase/src/app/components/hooks/use-sg-environment/samples/com-provider.tsx.sample` (type-check: OK).
+
+```tsx
+import { SgEnvironmentProvider, useSgEnvironment } from "@seedgrid/fe-components";
+
+function Consumer() {
+  const env = useSgEnvironment();
+  return <div>scope: {env.persistence.scope}</div>;
+}
+
+export default function App() {
+  return (
+    <SgEnvironmentProvider
+      value={{
+        namespaceProvider: { getNamespace: () => "user:42" },
+        persistence: { scope: "app:dashboard", mode: "strict", stateVersion: 3 },
+      }}
+    >
+      <Consumer />
+    </SgEnvironmentProvider>
+  );
+}
+```
+
+## useSgPersistence
+
+### load / save / clear sob demanda
+
+Sem `SgEnvironmentProvider` o namespace padrão é vazio, portanto a chave é `null` e as três operações não fazem nada; para persistir de fato, envolva com um provider que tenha `namespaceProvider` (ver exemplo anterior).
+
+Fonte: `apps/showcase/src/app/components/hooks/use-sg-persistence/samples/uso-basico.tsx.sample` (type-check: OK).
+
+```tsx
+import { useSgPersistence } from "@seedgrid/fe-components";
+
+export default function SaveOnAction() {
+  const persistence = useSgPersistence();
+
+  const handleSave = async () => {
+    await persistence.save("user:preferences", { theme: "dark", lang: "pt-BR" });
+  };
+
+  const handleLoad = async () => {
+    const prefs = await persistence.load("user:preferences");
+    console.log(prefs);
+  };
+
+  const handleClear = async () => {
+    await persistence.clear("user:preferences");
+  };
+
+  return (
+    <div>
+      <button onClick={handleSave}>Salvar</button>
+      <button onClick={handleLoad}>Carregar</button>
+      <button onClick={handleClear}>Limpar</button>
+    </div>
+  );
+}
+```
+
+## useSgPersistentState
+
+### Contador persistido
+
+Sem provider, grava em `localStorage["app:counter"]`. `hydrated` indica que o valor salvo já foi carregado.
+
+Fonte: `apps/showcase/src/app/components/hooks/use-sg-persistent-state/samples/uso-basico.tsx.sample` (type-check: OK).
+
+```tsx
+import { useSgPersistentState } from "@seedgrid/fe-components";
+
+export default function Counter() {
+  const { value, setValue, clear, hydrated } = useSgPersistentState({
+    baseKey: "app:counter",
+    defaultValue: 0,
+  });
+
+  return (
+    <div>
+      <span>{hydrated ? value : "..."}</span>
+      <button onClick={() => setValue((v) => v + 1)}>+1</button>
+      <button onClick={() => setValue((v) => v - 1)}>-1</button>
+      <button onClick={() => clear()}>Reset</button>
+    </div>
+  );
+}
+```
+
+### Isolamento por namespace (usuário)
+
+Com provider, a chave vira `sg:user:<id>:app:crm:app:counter`.
+
+Fonte: `apps/showcase/src/app/components/hooks/use-sg-persistent-state/samples/com-isolamento-por-namespace.tsx.sample` (type-check: OK).
+
+```tsx
+import { SgEnvironmentProvider, useSgPersistentState } from "@seedgrid/fe-components";
+
+function Counter() {
+  const { value, setValue } = useSgPersistentState({
+    baseKey: "app:counter",
+    defaultValue: 0,
+  });
+  return <button onClick={() => setValue((v) => v + 1)}>{value}</button>;
+}
+
+export default function App({ userId }: { userId: string }) {
+  return (
+    <SgEnvironmentProvider
+      value={{
+        namespaceProvider: { getNamespace: () => `user:${userId}` },
+        persistence: { scope: "app:crm", mode: "fallback", stateVersion: 1 },
+      }}
+    >
+      <Counter />
+    </SgEnvironmentProvider>
+  );
+}
+```
+
+### serialize / deserialize customizados
+
+`serialize` só é aplicado quando há provider (sem provider o valor vai por `JSON.stringify`, que também converte `Date` em string ISO).
+
+Fonte: `apps/showcase/src/app/components/hooks/use-sg-persistent-state/samples/serialize-e-deserialize-customizados.tsx.sample` (type-check: OK).
+
+```tsx
+import { useSgPersistentState } from "@seedgrid/fe-components";
+
+export default function DatePicker() {
+  const { value: selectedDate, setValue } = useSgPersistentState<Date | null>({
+    baseKey: "app:selected-date",
+    defaultValue: null,
+    serialize: (date) => date?.toISOString() ?? null,
+    deserialize: (raw) => (typeof raw === "string" ? new Date(raw) : null),
+  });
+
+  return (
+    <input
+      type="date"
+      value={selectedDate?.toISOString().slice(0, 10) ?? ""}
+      onChange={(e) => setValue(e.target.value ? new Date(e.target.value) : null)}
+    />
+  );
+}
+```
+
+## SgRealtimeProvider
+
+### Montagem no layout autenticado (com BFF)
+
+Fonte: `apps/showcase/src/app/components/providers/sg-realtime-provider/samples/layout-com-bff.tsx.sample` (type-check: OK).
+
+```tsx
+// app/(private)/layout.tsx — monte UMA vez, onde ja ha usuario logado.
+"use client";
+
+import { SgRealtimeProvider } from "@seedgrid/fe-components";
+
+export default function PrivateLayout({ children }: { children: React.ReactNode }) {
+  // Pede o token a /api/realtime/connect (a BFF, mesma origem: vai o cookie da sessao),
+  // que repassa ao backend (POST /realtime/connect da seedgrid-quarkus-ext-realtime).
+  // O backend emite o token para o usuario DA SESSAO; o front conecta direto no Pulse.
+  return <SgRealtimeProvider channels={["backup"]}>{children}</SgRealtimeProvider>;
+}
+
+// app/api/realtime/connect/route.ts — a BFF so repassa, com o token da sessao.
+//
+// export async function POST() {
+//   const response = await backendFetch("/realtime/connect", { method: "POST" });
+//   return new Response(await response.text(), {
+//     status: response.status,
+//     headers: { "Content-Type": "application/json" },
+//   });
+// }
+```
+
+## useSgRealtimeEvent + useSgRealtimeStatus
+
+### Aviso substitui o polling; polling volta quando não conectado
+
+Fonte: `apps/showcase/src/app/components/providers/sg-realtime-provider/samples/polling-de-reserva.tsx.sample` (type-check: OK).
+
+```tsx
+import * as React from "react";
+import { useSgRealtimeEvent, useSgRealtimeStatus } from "@seedgrid/fe-components";
+
+// Tela de exports: o aviso do Pulse substitui o polling; o polling so volta quando o realtime
+// nao esta conectado (desligado, Pulse fora, credencial revogada) E ha job em andamento.
+export function ExportList({ jobs, reload }: { jobs: { status: string }[]; reload: () => void }) {
+  const { connected } = useSgRealtimeStatus();
+  const running = jobs.some((job) => job.status === "QUEUED" || job.status === "RUNNING");
+
+  useSgRealtimeEvent("backup", "backup.finished.*", () => reload());
+
+  React.useEffect(() => {
+    if (connected || !running) return undefined;
+    const timer = setInterval(reload, 15_000);
+    return () => clearInterval(timer);
+  }, [connected, running, reload]);
+
+  return null;
+}
+```
+
+### Indicador de status
+
+Fonte: `apps/showcase/src/app/components/hooks/use-sg-realtime-status/samples/uso-basico.tsx.sample` (type-check: OK).
+
+```tsx
+import { useSgRealtimeStatus } from "@seedgrid/fe-components";
+
+export function RealtimeBadge() {
+  const { status, connected } = useSgRealtimeStatus();
+  // connected === false: desligado, Pulse fora, reconectando ou credencial revogada.
+  // E o sinal para a tela voltar ao polling de reserva.
+  return <span>{connected ? "Ao vivo" : `Polling (${status})`}</span>;
+}
+```
+
+### Handler por padrão de evento
+
+Fonte: `apps/showcase/src/app/components/hooks/use-sg-realtime-event/samples/uso-basico.tsx.sample` (type-check: OK).
+
+```tsx
+import { useSgRealtimeEvent } from "@seedgrid/fe-components";
+
+// Dentro de um SgRealtimeProvider com channels={["backup"]}.
+export function ExportsNotices({ reload }: { reload: () => void }) {
+  // "backup.finished.*" casa backup.finished.success e backup.finished.error.
+  useSgRealtimeEvent("backup", "backup.finished.*", (event) => {
+    // event.data so traz identificadores ({ exportPublicId, status }):
+    // busque o registro pela API de sempre, onde a permissao e checada.
+    reload();
+  });
+  return null;
+}
+```
+
+Simulação completa sem rede (WebSocket de demonstração via `connectOptions.webSocketImpl` e `fetchToken` fixo): `apps/showcase/src/app/components/providers/sg-realtime-provider/samples/simulador.tsx.sample` (type-check: OK; não reproduzido aqui pelo tamanho).

package/seedgridKB/SeedGrid/SeedGrid-components/providers/Visao-geral.md

@@ -0,0 +1,106 @@
+---
+tags: [seedgrid, front, component, providers]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-components/src/environment, front/seedgrid-fe-components/packages/seedgrid-fe-components/src/realtime
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# Providers de ambiente e realtime — visão geral
+
+Este grupo reúne os dois providers "de aplicação" do `@seedgrid/fe-components`, montados uma vez perto da raiz da árvore React:
+
+- **`SgEnvironmentProvider`** (`src/environment/`) — define *namespace* (ex.: usuário/tenant), *escopo* e a *estratégia de persistência* que os componentes SeedGrid usam para lembrar estado (posição de FAB/toolbar/dock-menu, layout do dock, cards recolhidos, menu etc.). Acompanha hooks (`useSgEnvironment`, `useSgPersistence`, `useSgPersistentState`…) e fábricas de estratégia (localStorage, API REST e composta).
+- **`SgRealtimeProvider`** (`src/realtime/`) — conecta a tela ao SeedGrid Pulse para receber avisos em tempo real do usuário logado, com hooks `useSgRealtimeEvent` e `useSgRealtimeStatus` e degradação para *polling*.
+
+- API completa: [[SeedGrid/SeedGrid-components/providers/API|API dos providers]]
+- Exemplos: [[SeedGrid/SeedGrid-components/providers/Exemplos|Exemplos dos providers]]
+- Fundamentos do pacote (instalação, i18n, `SgComponentsI18nProvider`, estilos): [[SeedGrid/SeedGrid-components/fundamentos/Visao-geral|Fundamentos]]
+- Lado servidor do realtime: [[SeedGrid/Extensions/realtime/Visao-geral|extension realtime]]
+
+Outros providers do pacote ficam nos grupos de origem: `SgTimeProvider` e `SgClockThemeProvider` em [[SeedGrid/SeedGrid-components/gadgets/API|gadgets]]; `SgComponentsI18nProvider` em [[SeedGrid/SeedGrid-components/fundamentos/API|fundamentos]].
+
+## Componentes, hooks e funções
+
+| Símbolo | Tipo | Exportado | Para que serve | Showcase |
+|---|---|---|---|---|
+| `SgEnvironmentProvider` | componente (provider) | sim | Fornece namespace, estratégia e configuração de persistência | `/components/providers/sg-environment-provider` |
+| `useSgEnvironment` | hook | sim | Lê o ambiente (ou o padrão, sem provider) | `/components/hooks/use-sg-environment` |
+| `useSgNamespaceProvider` | hook | sim | Atalho para `useSgEnvironment().namespaceProvider` | (página do provider) |
+| `useSgPersistence` | hook | sim | `load`/`save`/`clear` com chave isolada por namespace e escopo | `/components/hooks/use-sg-persistence` |
+| `useSgPersistentState` | hook | sim | "useState persistido" com hidratação assíncrona | `/components/hooks/use-sg-persistent-state` |
+| `useHasSgEnvironmentProvider` | hook | não (interno) | Diz se há provider; usado por FAB, Card, Menu, ToolBar, DockMenu | — |
+| `buildSgPersistenceKey` | função | sim | Monta a chave `sg:<namespace>[:<scope>]:<baseKey>` | — |
+| `createLocalStorageStrategy` | função | sim | Estratégia sobre `window.localStorage` | — |
+| `createApiPersistenceStrategy` | função | sim | Estratégia REST (`GET/POST/DELETE {baseUrl}/sg/persistence`) | — |
+| `createCompositePersistenceStrategy` | função | sim | Combina primária + secundária (`strict`/`fallback`/`mirror`) | — |
+| `readLocalPersistentState`, `writeLocalPersistentState`, `clearLocalPersistentState`, `resolvePersistedStateValue` | funções | sim | Helpers puros de estado persistido em `Storage` | — |
+| `SgRealtimeProvider` | componente (provider) | sim | Conexão ao Pulse e distribuição de avisos | `/components/providers/sg-realtime-provider` |
+| `useSgRealtimeEvent` | hook | sim | Registra handler por channel + padrão de evento | `/components/hooks/use-sg-realtime-event` |
+| `useSgRealtimeStatus` | hook | sim | `{ status, connected }` para decidir aviso × polling | `/components/hooks/use-sg-realtime-status` |
+| `matchesSgRealtimeEvent` | função | sim | Casa nome exato, `prefixo.*` ou `*` | — |
+
+Tipos exportados: `NamespaceProvider`, `PersistenceStrategy`, `SgEnvironment`, `SgEnvironmentValue`, `SgPersistenceMode`, `SgPersistenceConfig`, `SgPersistenceRecordDTO`, `SgRealtimeProviderProps`, `SgRealtimeStatus`, `SgRealtimeEvent`, `SgRealtimeConnectResponse` (Confirmado em `src/index.ts`).
+
+## Como funciona
+
+### Ambiente e persistência (Confirmado — `src/environment/*.ts(x)`)
+
+```mermaid
+flowchart LR
+  P[SgEnvironmentProvider value] --> E[useSgEnvironment]
+  E --> PS[useSgPersistence]
+  PS -->|buildSgPersistenceKey| K["sg:namespace:scope:baseKey"]
+  PS --> S[persistenceStrategy.load/save/clear]
+  E -.sem provider.-> D[padrão: namespace vazio + localStorage]
+  PST[useSgPersistentState] -->|com provider| PS
+  PST -->|sem provider| LS[localStorage direto com baseKey]
+```
+
+- Sem provider, `useSgEnvironment()` devolve um ambiente padrão: `getNamespace: () => ""`, `createLocalStorageStrategy()`, `persistence = { scope: "app:unknown", mode: "fallback", stateVersion: 1 }`.
+- `buildSgPersistenceKey` devolve `null` quando o namespace é vazio. Consequência: **com** `SgEnvironmentProvider` mas **sem** `namespaceProvider` que retorne algo, `useSgPersistence().load` retorna `null` e `save`/`clear` não fazem nada — a persistência fica desligada (Confirmado; coberto por `tests/providers-hooks.test.mjs` "returns null without namespace").
+- `useSgPersistentState` sem provider grava direto em `localStorage` sob a própria `baseKey` (sem prefixo `sg:`), ignorando `serialize` ao gravar (Confirmado: `writeLocalPersistentState({ storage, baseKey, value })`).
+- Componentes que consomem a persistência (Confirmado por import): `SgFloatActionButton`, `SgCard`, `SgMenu`, `SgToolBar`, `SgDockMenu` (via `useSgPersistence` + `useHasSgEnvironmentProvider`) e `SgDockLayout` (via `useSgPersistentState`). Também há menção em `SgDatatable` (grupo inputs, não analisado aqui).
+- `persistence.mode` e `persistence.stateVersion` do ambiente ficam disponíveis para leitura em `useSgEnvironment().persistence` e no retorno de `useSgPersistence()`. O comportamento de persistência é definido pela estratégia: o modo efetivo é o `mode` passado a `createCompositePersistenceStrategy`, e a versão gravada no servidor é o `stateVersion` passado a `createApiPersistenceStrategy` (Confirmado).
+
+### Realtime (Confirmado — `src/realtime/SgRealtimeProvider.tsx`)
+
+```mermaid
+sequenceDiagram
+  participant UI as SgRealtimeProvider
+  participant BFF as tokenEndpoint (POST)
+  participant Pulse as SeedGrid Pulse
+  UI->>BFF: POST /api/realtime/connect (credentials same-origin)
+  BFF-->>UI: { enabled, token, expiresAt, connectUrl }
+  alt enabled=false ou sem token
+    UI-->>UI: status = disabled
+  else
+    UI->>Pulse: PulseSubscriberClient.connect(getToken)
+    UI->>Pulse: subscribe({ channels })
+    Pulse-->>UI: message → listeners (useSgRealtimeEvent)
+  end
+```
+
+- Usa `PulseSubscriberClient` de `@seedgrid/pulse-subscriber-react/core` (dependência direta do pacote, `^3.0.0`).
+- Mapeamento de estado: `connected`/`subscribed` → `connected`; `connecting`, `reconnecting`, `auth-error`, `idle` mantidos; demais (`disconnected`, `error`) → `unavailable`. Falha no pedido do token → `unavailable`; resposta `enabled:false` → `disabled`.
+- Reconexão: a cada nova conexão o provider pede um token novo (o primeiro é reaproveitado uma vez).
+- Reconecta apenas quando mudam `enabled`, `channels` (comparado por `join(",")`) ou `pulseUrl`; `tokenEndpoint`, `tokenRequestInit`, `fetchToken` e `connectOptions` são lidos por *ref* (valor mais recente, sem reconectar).
+
+## Dependências
+
+- `react` (peer), `@seedgrid/pulse-subscriber-react` (dependência, só realtime).
+- Persistência REST: o backend precisa expor `GET/POST/DELETE {baseUrl}/sg/persistence` com o contrato de `SgPersistenceRecordDTO` (ver [[SeedGrid/SeedGrid-components/providers/API|API]]). **Não confirmado** qual extension Java/Rust implementa essa rota — não foi verificado neste grupo.
+- Realtime: rota de token (BFF) que repassa ao `POST /realtime/connect` da extension realtime (comentário do sample `layout-com-bff` e JSDoc de `SgRealtimeConnectResponse`).
+
+## Testes existentes (não executados)
+
+| Arquivo | Cobre |
+|---|---|
+| `tests/providers-hooks.test.mjs` | `buildSgPersistenceKey` (incl. `null` sem namespace); `createLocalStorageStrategy`; `createCompositePersistenceStrategy` (fallback, mirror, strict); `createApiPersistenceStrategy` (fetcher injetado, erros determinísticos); helpers de persistent-state; `SgEnvironmentProvider` expondo sobrescritas; também `SgComponentsI18nProvider` e `SgTimeProvider` |
+| `tests/providers-hooks-dom.test.mjs` | `useSgPersistentState` com localStorage e com estratégia do provider (hidratação e `clear`) |
+| `tests/realtime-dom.test.mjs` | conexão com token e entrega ao handler (filtro por channel/evento); backend desligado → `disabled`; token 401/503 → `unavailable`; credencial revogada (4403) → `auth-error` sem reconectar; sem provider → `disabled`; `matchesSgRealtimeEvent` |
+
+## Limitações e pontos de atenção
+
+- Nomes de channel com vírgula quebrariam a assinatura (o provider serializa/deserializa `channels` com `","`) — Inferência a partir de `channelsKey.split(",")`.
+- Fora de `SgRealtimeProvider`, `useSgRealtimeEvent` não faz nada e `useSgRealtimeStatus` devolve `disabled`.