@seedgrid/ai-toolkit 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,68 @@
+---
+tags: [seedgrid, front, pacote]
+fonte: front/seedgrid-fe-components/packages; front/seedgrid-fe-components/package.json; front/seedgrid-fe-components/pnpm-workspace.yaml; front/seedgrid-fe-components/turbo.json
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# Pacotes do monorepo `seedgrid-fe-components`
+
+Monorepo pnpm (`packageManager: pnpm@9.12.0`) + Turborepo. Workspaces (`pnpm-workspace.yaml`): `apps/*`, `packages/*`, `packages/modules/*`. Repositório declarado nos `package.json`: `github.com/SeedGrid/seedgrid-fe-components`.
+
+## Pacotes de base (`packages/*`)
+
+| Pacote | Versão | Papel | Nota |
+|---|---|---|---|
+| `@seedgrid/fe-components` | 2026.7.1 | Biblioteca de componentes `Sg*` + utilitários (máscaras, validadores, i18n) | [[SeedGrid/SeedGrid-components/fundamentos/Visao-geral\|Fundamentos]] |
+| `@seedgrid/fe-theme` | 0.3.0 | Tema por cor *seed*, tokens `--sg-*`, `SeedThemeProvider` | [[SeedGrid/SeedGrid-components/pacotes/fe-theme\|fe-theme]] |
+| `@seedgrid/fe-core` | 2026.7.1 | Manifesto de módulo da CLI, registry, persistência, `createApiClient`, erros | [[SeedGrid/SeedGrid-components/pacotes/fe-core\|fe-core]] |
+| `@seedgrid/fe-commons` | 0.2.0 | `createHttpClient`, `buscarCep`, `buscarCnpj` | [[SeedGrid/SeedGrid-components/pacotes/fe-commons\|fe-commons]] |
+| `@seedgrid/fe-playground` | 0.1.0 | `SgPlayground` (Sandpack) | [[SeedGrid/SeedGrid-components/pacotes/fe-playground\|fe-playground]] |
+
+Módulos de domínio (`packages/modules/*`, todos `@seedgrid/fe-<nome>`): ver [[SeedGrid/SeedGrid-components/modulos/Visao-geral|Módulos front]]. App de demonstração: [[SeedGrid/SeedGrid-components/showcase|Showcase]].
+
+## Dependências entre pacotes (Confirmado nos `package.json`)
+
+```mermaid
+graph LR
+  theme["fe-theme"] -->|dependency| core["fe-core"]
+  commons["fe-commons"] -->|dependency (sem uso no src)| core
+  components["fe-components"] -.->|devDependency (build-style)| theme
+  playground["fe-playground"] -->|peer ^0.2.10| components
+  modules["fe-<módulo>"] -->|peer| core
+  modules -->|peer| security["fe-security"]
+  security -->|peer| components
+  security -->|peer| core
+  showcase["apps/showcase"] --> components
+  showcase --> theme
+  showcase --> playground
+```
+
+- `fe-components` **não** depende de `fe-core`.
+- `fe-components` usa `fe-theme` só no build (`scripts/build-style.mjs` importa `generateThemeVars`/`generateComponentTokens` do `dist` do tema) para embutir o tema padrão no CSS.
+
+## Padrões comuns
+- Todos ESM (`"type": "module"`), compilados com `tsc` para `dist/` (fe-components também gera `dist/sandbox.cjs` com `tsup`).
+- Cada pacote de base tem `scripts/build-ai-manifest.mjs` que gera `dist/ai/<pacote>.manifest.json` a partir dos `*.meta.ts` (metadados `SgMetaV0`/`SgAiHintsV0`).
+- Versões: componentes e core seguem calendário (`2026.7.x`); theme/commons/playground ainda em `0.x`.
+- `peerDependencies` de React: `^18.2.0 || ^19.0.0` em todos.
+
+## Scripts da raiz (`package.json`, Confirmado; não executados)
+
+| Script | Comando |
+|---|---|
+| `dev` | `turbo dev` |
+| `dev:components` | `pnpm -C packages/seedgrid-fe-components dev` |
+| `dev:showcase` | `pnpm -C apps/showcase dev` |
+| `dev:showcase:with-components` | `pnpm -r --parallel dev:components dev:showcase` |
+| `build` / `typecheck` | `turbo build` / `turbo typecheck` |
+
+`turbo.json`: `build` depende de `^build` (saídas `dist/**`, `.next/**`); `dev` sem cache, persistente, depende de `^build`.
+
+## Publicação
+Scripts na raiz: `publish-package.sh <dir> [patch|minor|major|prerelease|none]` (aceita `PUBLISH_VERSION`, voltado a npm Trusted Publishing/OIDC no GitHub Actions — texto de ajuda do script) e atalhos `publish-<pacote>.sh` para components, core, theme, commons, playground e cada módulo. Não executados.
+
+## Compatibilidade
+
+- O peer de `fe-playground` (`@seedgrid/fe-components ^0.2.10`) não aceita a versão atual 2026.7.1.

package/seedgridKB/SeedGrid/SeedGrid-components/pacotes/fe-commons.md

@@ -0,0 +1,61 @@
+---
+tags: [seedgrid, front, pacote, fe-commons]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-commons
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# `@seedgrid/fe-commons`
+
+Utilitários leves: cliente HTTP mínimo (`createHttpClient`), consulta de CEP (ViaCEP) e de CNPJ (Publica CNPJ).
+
+Relacionados: [[SeedGrid/SeedGrid-components/pacotes/Visao-geral|Pacotes]] · cliente HTTP mais completo em [[SeedGrid/SeedGrid-components/pacotes/fe-core|@seedgrid/fe-core]] (`createApiClient`).
+
+## Pacote
+
+| Campo | Valor (Confirmado em `package.json`) |
+|---|---|
+| Nome / versão | `@seedgrid/fe-commons` `0.2.0` |
+| `exports` | só `.` |
+| `dependencies` | `@seedgrid/fe-core` (`workspace:*`) — **nenhum import de `@seedgrid/fe-core` em `src/`** (grep) |
+| `peerDependencies` | `react ^18.2.0 \|\| ^19.0.0` (o código não importa React) |
+| Build | `tsc -p tsconfig.json && node scripts/build-ai-manifest.mjs` |
+| Testes | nenhum |
+
+## API (`src/index.ts`)
+
+| Export | Tipo | Fonte | Comportamento |
+|---|---|---|---|
+| `createHttpClient(opts)` | função | `src/http/httpClient.ts` | retorna `{ request<T>(path, init?) }`; URL = `baseUrl + path` (concatenação simples); define `Content-Type: application/json` se ausente; `Authorization: Bearer` se `getAccessToken()` (síncrono) retornar valor; status não-OK → `Error("HTTP <status> <statusText>: <corpo>")`; 204 → `undefined` |
+| `HttpClientOptions` | tipo | idem | `{ baseUrl: string; getAccessToken?: () => string \| null }` |
+| `buscarCep(cep, options?)` | função async | `src/cep/viacep.ts` | normaliza para dígitos; ≠ 8 → `Error("CEP deve ter 8 dígitos.")`; `GET https://viacep.com.br/ws/<cep>/json/`; não-OK → `Error("Falha ao consultar CEP (<status>).")`; `erro: true` → `Error("CEP não encontrado.")` |
+| `ViaCepResponse` | tipo | idem | `cep, logradouro, complemento, bairro, localidade, uf, ibge, gia, ddd, siafi, erro?` |
+| `CepLookupOptions` | tipo | idem | `{ signal?: AbortSignal }` |
+| `buscarCnpj(cnpj, options?)` | função async | `src/cnpj/publica.ts` | normaliza para dígitos; ≠ 14 → **lança** `Error("CNPJ deve ter 14 dígitos.")`; `GET https://publica.cnpj.ws/cnpj/<cnpj>`; não-OK **ou** erro de rede → `null` |
+| `PublicaCnpjResponse` | tipo | idem | estrutura da API Publica (razão social, porte, natureza jurídica, sócios, simples, estabelecimento com endereço/atividades/inscrições estaduais) |
+| `CnpjLookupOptions` | tipo | idem | `{ signal?: AbortSignal }` |
+
+Metadados de IA: `src/cep/viacep.meta.ts`, `src/cnpj/publica.meta.ts`, `src/http/httpClient.meta.ts` (componentIds `hook.cep-lookup`, `hook.cnpj-lookup`, …).
+
+## Pontos de atenção (Confirmado)
+- `buscarCnpj` remove letras (`\D`), portanto **não suporta CNPJ alfanumérico**, ao contrário de `isValidCnpj`/`maskCnpj` do `@seedgrid/fe-components`.
+- Serviços externos fixos (ViaCEP e publica.cnpj.ws) — não há configuração de URL nem variável de ambiente.
+- O `aiHints` de `publica.meta.ts` diz "Returns null on network error or non-2xx" — coerente com o código; mas a entrada com tamanho inválido **lança** erro.
+
+## Exemplo
+Fonte: `packages/seedgrid-fe-commons/README.md`.
+
+```ts
+import { createHttpClient, buscarCep, buscarCnpj } from "@seedgrid/fe-commons";
+
+const apiClient = createHttpClient({
+  baseUrl: "https://api.exemplo.com",
+  getAccessToken: () => localStorage.getItem("sg:session-token")
+});
+
+const cep = await buscarCep("01001-000");     // cep.localidade, cep.uf
+const empresa = await buscarCnpj("10404812000100"); // empresa?.razao_social
+const dados = await apiClient.request("/v1/dashboard");
+```
+(Base URL substituída por placeholder.)

package/seedgridKB/SeedGrid/SeedGrid-components/pacotes/fe-core.md

@@ -0,0 +1,140 @@
+---
+tags: [seedgrid, front, pacote, fe-core]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-core
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# `@seedgrid/fe-core`
+
+Infraestrutura comum dos pacotes front: contrato de manifesto de módulo para a CLI SeedGrid, registry de runtime, merge de i18n, estratégias de persistência, cliente HTTP (`createApiClient`) com refresh de token/retry, tratamento e extração de mensagens de erro (RFC 7807) e `useDebouncedValue`.
+
+Relacionados: [[SeedGrid/SeedGrid-components/pacotes/Visao-geral|Pacotes]] · [[SeedGrid/SeedGrid-components/modulos/Visao-geral|Módulos front]] (usam `SeedGridCliModuleManifest`) · [[SeedGrid/SeedGrid-components/pacotes/fe-theme|@seedgrid/fe-theme]] (usa a persistência).
+
+## Pacote
+
+| Campo | Valor (Confirmado em `package.json`) |
+|---|---|
+| Nome / versão | `@seedgrid/fe-core` `2026.7.1` |
+| `exports` | só `.` (não há subpath `./server`; `src/server.ts` é reexportado pelo barrel) |
+| `peerDependencies` | `react ^18.2.0 \|\| ^19.0.0` |
+| `dependencies` | nenhuma |
+| Build | `tsc -p tsconfig.json && node scripts/build-ai-manifest.mjs` |
+| Testes | `pnpm run build && node --test tests/api-errors.test.mjs` (não executados) — cobre `extractApiErrorMessage`, `readApiErrorMessage`, `isApiClientErrorLike`, `messageForHttpStatus` |
+
+## API (barrel `src/index.ts`)
+
+### Módulos e registry
+
+| Export | Tipo | Fonte | Descrição |
+|---|---|---|---|
+| `SeedGridCliModuleManifest` | interface | `src/cli-module-manifest.ts` | Contrato lido pela **CLI SeedGrid (Rust)** para plugar um pacote `@seedgrid/fe-*` em um app gerado. Campos: `id`, `requires?: string[]`, `variantGroup?`, `configKey`, `env?: string[]`, `provider?: ImportRef[]`, `navigation?: ImportRef`, `messages?: ImportRef`, `postAuthResolver?: ImportRef` |
+| `SeedGridCliModuleImportRef` | interface | idem | `{ import: string; from: string }` |
+| `SeedGridProvider`, `SeedGridNavItem`, `SeedGridRoute` | tipos | `src/module.ts` | elementos aceitos pelo `SeedGridRegistry` (`SeedGridNavItem`: `id, labelKey, href, icon?, requiresAuth?, order?`; `SeedGridRoute`: `id, path, requiresAuth?`) |
+| `SeedGridRegistry` | **classe** | `src/registry.ts` | `addProvider`, `addNavItem`, `addRoute`, `getProviders()`, `getNavItems()` (ordenado por `order`, padrão 999), `getRoutes()` |
+
+Segundo o comentário de `cli-module-manifest.ts` (Confirmado): cada pacote exporta um `module` em `src/module.ts`, e um *postbuild* serializa para `dist/module.json`, único artefato lido pela CLI (ADR `seedgrid-cli/docs/adr/0004-module-manifest-contract.md`, **não analisado**). `postAuthResolver` = função `(permissions: Iterable<string>) => Promise<string|null> | string | null` registrada no `navigation.ts` do fe-security.
+
+### i18n
+
+| Export | Descrição |
+|---|---|
+| `SeedGridLocale` | `"pt-BR"` |
+| `SeedGridMessages` | `Record<namespace, Record<chave, texto>>` |
+| `mergeMessages(target, add)` | merge raso por namespace (o `add` vence) |
+
+### Persistência — `src/persistence.ts`
+
+| Export | Descrição |
+|---|---|
+| `PersistenceStrategy` | `{ load(key), save(key, state), clear(key) }` — síncrono ou `Promise` |
+| `NamespaceProvider` | `{ getNamespace(): string \| null }` |
+| `SgPersistenceRecordDTO` | `{ protocolVersion: 1, key, scope, stateVersion, updatedAt, state }` |
+| `SgPersistenceMode` | `"strict" \| "fallback" \| "mirror"` |
+| `SgPersistenceConfig` | `{ scope, mode, stateVersion }` |
+| `SgEnvironmentValue` / `SgEnvironment` | `{ namespaceProvider, persistenceStrategy, persistence }` |
+| `buildSgPersistenceKey(baseKey, namespace?, scope?)` | `null` se sem namespace; senão `sg:<ns>:<baseKey>` ou `sg:<ns>:<scope>:<baseKey>` |
+| `createLocalStorageStrategy({prefix?})` | JSON em `localStorage`; erros silenciados (load → `null`) |
+| `createApiPersistenceStrategy({baseUrl, fetcher?, scope, stateVersion})` | `GET {base}/sg/persistence?key=` (espera `{found, record}`), `POST {base}/sg/persistence` com `{record}`, `DELETE {base}/sg/persistence?key=`; lança `Error` em status não-OK |
+| `createCompositePersistenceStrategy({mode, primary, secondary})` | `strict`: só primary; `fallback`: primary e, se lançar, secondary; `mirror`: load do primary (se `null`/erro → secondary), save/clear em ambos com `allSettled` |
+
+**Lacuna**: o endpoint backend `/sg/persistence` não foi localizado nesta análise (lado Java/Rust fora do escopo F3).
+
+### HTTP — `src/http/api-client.ts` (reexportado também por `src/server.ts`)
+
+`createApiClient(config: ApiClientConfig)` → `{ request, get, post, put, patch, delete }` (todos `(path, options?) => Promise<T>`).
+
+| `ApiClientConfig` | Tipo | Descrição |
+|---|---|---|
+| `baseUrl` | `string` | absoluta, ou relativa (prefixada com `window.location.origin`; no servidor usa `http://localhost:3000` — Confirmado em `resolveAbsoluteBase`) |
+| `defaultHeaders` | `HeadersInit` | — |
+| `defaultCache` | `RequestCache` | — |
+| `defaultNext` | `{ revalidate?, tags? }` | opções `next` do fetch do Next.js |
+| `getAccessToken` | `() => Promise<string\|null>` | Bearer quando `requireAuth` (padrão `true`) |
+| `refreshAccessToken` | `() => Promise<string\|null>` | chamado **uma vez** em 401; `null` → `onAuthFailure` + erro |
+| `onAuthFailure` | `(ctx) => void` | em 401 sem refresh possível |
+| `onException` | `(error, ctx) => void` | antes do `captureException` global |
+
+| `ApiRequestOptions` (além de `RequestInit`) | Padrão | Descrição |
+|---|---|---|
+| `body` | — | `BodyInit` passa direto; objeto → `JSON.stringify` + `Content-Type: application/json` |
+| `query` | — | `Record<string, primitivo\|null\|undefined>`; nulos ignorados |
+| `parseAs` | `"json"` | `"json"` (204 → `null`), `"text"`, `"response"` |
+| `requireAuth` | `true` | — |
+| `retry` | sem retry | `true` → 2 tentativas extras, 250 ms × (n+1), em `[429, 502, 503, 504]` e em `TypeError` (rede); objeto `{attempts?, baseDelayMs?, retryOn?}` |
+| `captureExceptions` | `true` | `false` → `suppressException` |
+| `next` | `config.defaultNext` | — |
+
+`ApiClientError` (`name`, `status`, `responseBody`) é lançado para status não-OK.
+
+**Pontos de atenção (Confirmado na leitura)**:
+- `request` faz `console.log` do comando **curl completo, URL, método, body e headers** (inclui `Authorization: Bearer …`) a cada chamada, e de `response`/erros (`console.log('aqui ', response)`, `'chegou no catch '`); `readResponseBody` também loga o corpo. Isso expõe tokens e dados em logs do navegador/servidor.
+- **Inferência**: para erros HTTP, `config.onException` pode ser chamado duas vezes — uma no bloco `try` e outra no `catch` que recaptura o próprio `ApiClientError` lançado (o `captureException` global é idempotente via `Symbol.for("seedgrid.captured_exception")`, mas `onException` não).
+
+### Tratamento de exceções — `src/http/api-exception-handler.ts`
+
+`ExceptionArea` (`api|client|server`), `ExceptionContext` (`area, source, status, retryable, metadata`), `ExceptionReporter`, `registerExceptionReporter(fn) => unregister`, `captureException(error, ctx)` (dedup por símbolo, `console.error("[seedgrid]", …)`, chama reporters), `runGuarded(action, ctx)`, `suppressException(error)`, `normalizeError(unknown)`.
+
+### Mensagens de erro — `src/http/api-errors.ts`
+
+| Export | Descrição |
+|---|---|
+| `extractApiErrorMessage(error)` | busca em largura na cadeia `responseBody/cause/error/data/body`; prioridade `violations[].message → errors[].message → userMessage → detail → message → error → title`; nunca devolve JSON cru |
+| `readApiErrorMessage(body)` | mesma lógica para um corpo já em mãos (objeto ou string JSON) |
+| `messageForHttpStatus(status)` | mensagens pt-BR para 400, 401, 403, 404, 408/504, 409, 422, 429, 503, ≥500 e genérica |
+| `isApiClientErrorLike(error)` | *type guard* (qualquer objeto) |
+
+### Hook
+`useDebouncedValue<T>(value, delayMs, normalize?)` — `"use client"`; `src/useDebouncedValue.ts`.
+
+## Exemplo
+Fonte: `packages/seedgrid-fe-core/README.md` (registry/persistência) + API confirmada (cliente HTTP, montado a partir da API).
+
+```ts
+import {
+  SeedGridRegistry, mergeMessages,
+  createLocalStorageStrategy, createCompositePersistenceStrategy,
+  createApiClient, extractApiErrorMessage
+} from "@seedgrid/fe-core";
+
+const registry = new SeedGridRegistry();
+registry.addNavItem({ id: "marketing", labelKey: "menu.marketing", href: "/marketing", order: 10 });
+
+const messages = mergeMessages({ app: { welcome: "Bem-vindo" } }, { app: { logout: "Sair" } });
+
+const persistence = createCompositePersistenceStrategy({
+  mode: "mirror",
+  primary: createLocalStorageStrategy({ prefix: "sg:" }),
+  secondary: createLocalStorageStrategy(),
+});
+
+const api = createApiClient({ baseUrl: "", getAccessToken: async () => null });
+try {
+  await api.get("/api/recurso", { retry: true, requireAuth: false });
+} catch (e) {
+  const msg = extractApiErrorMessage(e);
+}
+```
+
+Marcadores `// seedgrid:managed` no topo de `api-client.ts`, `api-errors.ts`, `api-exception-handler.ts`, `server.ts` e `useDebouncedValue.ts`. **Inferência**: arquivos sincronizados/gerenciados pela CLI SeedGrid (não confirmado).

package/seedgridKB/SeedGrid/SeedGrid-components/pacotes/fe-playground.md

@@ -0,0 +1,112 @@
+---
+tags: [seedgrid, front, pacote, fe-playground]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-playground
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# `@seedgrid/fe-playground`
+
+Exporta o componente `SgPlayground`: bloco de código somente leitura **ou** editor + preview interativo baseado em **Sandpack** (`@codesandbox/sandpack-react`), com runtime do `@seedgrid/fe-components`, shims para dependências pesadas e herança do tema da página hospedeira. É o `SgPlayground` exigido em toda página do [[SeedGrid/SeedGrid-components/showcase|Showcase]].
+
+Relacionados: [[SeedGrid/SeedGrid-components/pacotes/Visao-geral|Pacotes]] · [[SeedGrid/SeedGrid-components/fundamentos/Visao-geral|Fundamentos do fe-components]] (`dist/sandbox.cjs`).
+
+## Pacote
+
+| Campo | Valor (Confirmado em `package.json`) |
+|---|---|
+| Nome / versão | `@seedgrid/fe-playground` `0.1.0`, MIT, `sideEffects: false` |
+| `exports` | só `.` |
+| `dependencies` | `@codesandbox/sandpack-react ^2.20.0` |
+| `peerDependencies` | `@seedgrid/fe-components ^0.2.10`, `react`/`react-dom ^18.2.0 \|\| ^19.0.0` |
+| Build | `clean` + `tsc` + `scripts/build-ai-manifest.mjs`; `dev` = `tsc --watch` |
+| Testes | nenhum no pacote (o showcase tem `tests/playground-app-file-imports.test.mjs`) |
+
+**Atenção**: o peer `@seedgrid/fe-components ^0.2.10` não é satisfeito pela versão atual `2026.7.1` (semver `^0.2.x` só aceita `0.2.*`); espere aviso de peer ao instalar.
+
+## Exports (`src/index.ts`)
+`SgPlayground` (default de `src/SgPlayground.tsx`, `"use client"`), tipos `SgPlaygroundProps`, `SgPlaygroundPreset` (`"auto" | "basic" | "seedgrid" | "editor" | "full"`), `SgPlaygroundNpmRegistry`.
+
+## Props de `SgPlayground` (Confirmado na desestruturação)
+
+`SgPlaygroundProps` é uma união: **exatamente um** de `code` ou `playgroundFile`.
+
+| Prop | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `code` | `string` | — | código inline |
+| `playgroundFile` | `string` | — | caminho do arquivo; carregado via `fetch("/api/showcase-code?path=…")` — **exige essa rota no app hospedeiro** (existe no showcase) |
+| `interactive` | `boolean` | `false` | `false` = bloco somente leitura (`ReadonlyBlock`); `true` = Sandpack com editor + preview |
+| `codeContract` | `"renderBody" \| "appFile"` | `"renderBody"` | `renderBody`: o código é o corpo JSX, embrulhado num `App.tsx` gerado com `defaultImports`; `appFile`: o código é o `App.tsx` completo |
+| `preset` | `SgPlaygroundPreset` | `"auto"` | `auto` → `editor` se usar `SgTextEditor`, `seedgrid` se importar `@seedgrid/fe-components`, senão `basic` |
+| `title` | `string` | — (card: `"Codigo"`) | título |
+| `description` | `string` | — | descrição do card |
+| `height` | `number \| string` | `360` | altura |
+| `expandedHeight` | `number \| string` | `"70vh"` | altura expandida |
+| `expandable` | `boolean` | `true` | botão expandir |
+| `resizable` | `boolean` | `true` | redimensionável |
+| `resizeAxis` | `"vertical" \| "horizontal" \| "both"` | `"vertical"` | eixo |
+| `previewPadding` | `number \| string` | `12` se `appFile`, senão `0` | padding do preview |
+| `className`, `style` | — | — | no card (ou no container sem card) |
+| `dependencies` | `Record<string,string>` | `{}` | dependências npm extras do sandbox |
+| `defaultImports` | `string` | import de `SgScreen, SgPanel, SgGrid, SgStack, SgButton, SgAutocomplete` | cabeçalho usado no modo `renderBody` |
+| `previewWrapperClassName` | `string` | `"h-[420px] rounded-xl border border-border bg-muted/30 p-3"` | wrapper do preview em `renderBody` |
+| `seedgridDependency` | `string` | env `NEXT_PUBLIC_SANDPACK_SEEDGRID_DEPENDENCY` ou `"latest"` | versão do `@seedgrid/fe-components` no sandbox |
+| `bundlerURL` | `string` | env `NEXT_PUBLIC_SANDPACK_BUNDLER_URL` ou `https://sandpack.seedgrid.com.br` | bundler Sandpack self-hosted |
+| `bundlerTimeoutMs` | `number` | env `NEXT_PUBLIC_SANDPACK_BUNDLER_TIMEOUT_MS` ou `60000` | timeout |
+| `npmRegistries` | `SgPlaygroundNpmRegistry[]` | derivado das envs `NEXT_PUBLIC_SANDPACK_NPM_REGISTRY_*` (se `…_URL` definida) | registries privados |
+| `withCard` | `boolean` | `true` | envolve em `SgCard` |
+| `collapsible` | `boolean` | `true` | card recolhível |
+| `defaultOpen` | `boolean` | `true` | card inicia aberto |
+| `cardId` | `string` | — | `id` do `SgCard` (âncoras do showcase) |
+
+`SgPlaygroundNpmRegistry`: `{ enabledScopes: string[]; limitToScopes: boolean; registryUrl: string; proxyEnabled: boolean; registryAuthToken?: string }`.
+
+### Comportamentos relevantes (Confirmado)
+- Com SeedGrid incluído, injeta arquivos virtuais: `/node_modules/@seedgrid/fe-components/dist/index.js` → `module.exports = require("./sandbox.cjs")` (exige `build:sandbox` no pacote publicado), shim de `qrcode`, `public/index.html` com Tailwind, shims de i18n JSON/JS.
+- `lucide-react` é substituído por um SVG genérico em todos os presets exceto `full` (evita OOM); TipTap e Sandpack-React também podem ser *shimados*; polyfills Node só no preset `editor`/`full`.
+- Lê variáveis CSS e CSS do Next da página hospedeira (`MutationObserver` em `style`/`class`/`data-theme` do `<html>`) e repassa ao preview; tema claro/escuro do editor segue a página.
+- Dependências padrão do sandbox: `react`/`react-dom` `18.2.0`, `react-hook-form ^7.0.0`; editor: `@tiptap/* ^2.9.1`.
+
+## Configuração (variáveis de ambiente)
+
+Lidas via `process.env` em `src/SgPlayground.tsx`. Por serem `NEXT_PUBLIC_*`, o Next.js as **embute no bundle do cliente em build** (Inferência baseada na convenção do Next; o pacote em si só lê `process.env`). Props explícitas têm precedência.
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `NEXT_PUBLIC_SANDPACK_SEEDGRID_DEPENDENCY` | string | versão/range npm | `latest` | Não | versão do `@seedgrid/fe-components` no sandbox | `resolvedSeedgridDependency` | prop `seedgridDependency` vence | build (NEXT_PUBLIC inline) | `SgPlayground` |
+| `NEXT_PUBLIC_SANDPACK_BUNDLER_URL` | string | URL válida (`new URL`) | `https://sandpack.seedgrid.com.br` | Não | URL do bundler; inválida → padrão; barra final removida | `normalizeUrl` | prop `bundlerURL` vence | build (NEXT_PUBLIC inline) | `SgPlayground` |
+| `NEXT_PUBLIC_SANDPACK_BUNDLER_TIMEOUT_MS` | número | > 0 | `60000` | Não | timeout do bundler; inválido/≤0 → padrão | `normalizeTimeoutMs` | prop `bundlerTimeoutMs` vence | build (NEXT_PUBLIC inline) | `SgPlayground` |
+| `NEXT_PUBLIC_SANDPACK_DEBUG` | boolean | `1/true/yes/on`, `0/false/no/off` | `false` | Não | loga a config do Sandpack (`console.info`) quando `interactive` | `useEffect` | — | build (NEXT_PUBLIC inline) | `SgPlayground` |
+| `NEXT_PUBLIC_SANDPACK_NPM_REGISTRY_URL` | string | URL | — | Condicional (sem ela nenhum registry é criado) | registry npm privado; barras finais removidas | `resolveDefaultNpmRegistriesFromEnv` | habilita as 4 abaixo; prop `npmRegistries` vence | build (NEXT_PUBLIC inline) | `resolveDefaultNpmRegistriesFromEnv` |
+| `NEXT_PUBLIC_SANDPACK_NPM_REGISTRY_SCOPES` | string CSV | ex. `@seedgrid,@outro` | `@seedgrid` | Não | `enabledScopes` | idem | requer `…_URL` | build (NEXT_PUBLIC inline) | idem |
+| `NEXT_PUBLIC_SANDPACK_NPM_REGISTRY_LIMIT_TO_SCOPES` | boolean | idem DEBUG | `true` | Não | `limitToScopes` | idem | requer `…_URL` | build (NEXT_PUBLIC inline) | idem |
+| `NEXT_PUBLIC_SANDPACK_NPM_REGISTRY_PROXY_ENABLED` | boolean | idem DEBUG | `false` | Não | `proxyEnabled` | idem | requer `…_URL` | build (NEXT_PUBLIC inline) | idem |
+| 🔒 `NEXT_PUBLIC_SANDPACK_NPM_REGISTRY_AUTH_TOKEN` | string | token | — | Não | `registryAuthToken` do registry | idem | requer `…_URL` | build (NEXT_PUBLIC inline) | idem |
+
+**Risco (Inferência)**: um token em variável `NEXT_PUBLIC_*` fica visível no JavaScript entregue ao navegador. Usar somente com token de leitura restrito.
+
+Nenhum arquivo `.env*` com essas variáveis foi encontrado no showcase (lacuna: não houve busca em ambientes de deploy).
+
+## Exemplo
+Fonte: `packages/seedgrid-fe-playground/README.md`.
+
+```tsx
+import { SgPlayground } from "@seedgrid/fe-playground";
+
+export function PlaygroundExample() {
+  return (
+    <SgPlayground
+      code={`<>Olá SeedGrid!</>`}
+      preset="seedgrid"
+      interactive
+      title="Experimentando componentes"
+      description="Duplo clique para editar o código do componente."
+      expandedHeight="500px"
+      resizable
+      previewPadding={24}
+    />
+  );
+}
+```
+

package/seedgridKB/SeedGrid/SeedGrid-components/pacotes/fe-theme.md

@@ -0,0 +1,97 @@
+---
+tags: [seedgrid, front, pacote, fe-theme]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-theme
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# `@seedgrid/fe-theme`
+
+Sistema de temas: gera paletas 50–900 a partir de uma cor *seed*, modos `light`/`dark`/`auto`, tokens CSS `--sg-*` (base + componentes), persistência da preferência e provider React. Inclui o provider/hook **legado** (`ThemeProvider`/`useTheme`) e um `AppShell` simples.
+
+Relacionados: [[SeedGrid/SeedGrid-components/pacotes/Visao-geral|Pacotes]] · [[SeedGrid/SeedGrid-components/pacotes/fe-core|@seedgrid/fe-core]] (persistência) · [[SeedGrid/SeedGrid-components/fundamentos/Visao-geral|Fundamentos do fe-components]] (o CSS compilado embute o tema padrão).
+
+## Pacote
+
+| Campo | Valor (Confirmado em `package.json`) |
+|---|---|
+| Nome / versão | `@seedgrid/fe-theme` `0.3.0` |
+| `exports` | só `.` → `./dist/index.js` / `./dist/index.d.ts` |
+| `dependencies` | `@seedgrid/fe-core` (`workspace:*`) — usa `createLocalStorageStrategy` e o tipo `PersistenceStrategy` |
+| `peerDependencies` | `react ^18.2.0 \|\| ^19.0.0` |
+| Build | `tsc -p tsconfig.json && node ./scripts/copy-i18n.mjs && node ./scripts/build-ai-manifest.mjs` → `dist/`, `dist/i18n/pt-BR.json`, `dist/ai/seedgrid-theme.manifest.json` |
+| Testes | nenhum diretório `tests/` |
+
+## API exportada (`src/index.ts`)
+
+| Export | Tipo | Fonte | Descrição |
+|---|---|---|---|
+| `SeedThemeProvider` | componente | `src/theme/ThemeProvider.tsx` | provider principal (ver abaixo) |
+| `useSgTheme` | hook | idem | retorna `ThemeContextValue`; lança erro fora do provider |
+| `ThemeProvider` | componente **@deprecated** | idem | provider legado baseado em HSL (`SeedGridThemeConfig`) |
+| `useTheme` | hook **@deprecated** | idem | retorna `SeedGridThemeConfig` do provider legado |
+| `Mode` | tipo | `src/theme/ThemeConfig.ts` | `"light" \| "dark" \| "auto"` |
+| `SeedThemeInput` | tipo | idem | entrada do tema (tabela abaixo) |
+| `ThemeVars` | tipo | idem | `Record<string,string>` |
+| `ThemeContextValue` | tipo | idem | `{ vars, setTheme, setMode, currentMode, currentTheme }` |
+| `SeedGridThemeConfig` | tipo (legado) | idem | `brand{name,logoUrl?}`, `colors{primary,onPrimary,…,foreground}`, `layout{sidebarWidth,radius}` |
+| `defaultTheme` | const (legado) | idem | marca "SeedGrid", cores HSL, `sidebarWidth 260`, `radius 12` |
+| `defaultSeedTheme` | const | idem | `{ seed: "#16803D", mode: "light", radius: 12, persistMode: true }` |
+| `clamp`, `hexToRgb`, `rgbToHex`, `rgbToHsl`, `hslToRgb`, `hslToHex`, `relativeLuminance`, `pickOnColor`, `toRgbVarValue`, `shiftHue`, `buildScaleFromHex` | funções | `src/theme/colorUtils.ts` | utilitários de cor; `buildScaleFromHex(baseHex, mode, {boostS?, biasL?})` gera stops 50–900 |
+| `getSystemMode` | função | `src/theme/themeGenerator.ts` | `prefers-color-scheme`; `"light"` em SSR |
+| `generateThemeVars` | função | idem | `(input, resolvedMode) => ThemeVars` |
+| `generateComponentTokens` | função | `src/theme/componentTokens.ts` | `(baseVars) => ThemeVars` aliases `--sg-btn-*`, `--sg-input-*`, `--sg-card-*`, `--sg-alert-*`, `--sg-table-*`, `--sg-menu-*`, `--sg-modal-*`… |
+| `AppShell` | componente | `src/ui/AppShell.tsx` | layout sidebar + header + main; usa `useTheme()` **legado** |
+
+### `SeedThemeInput`
+
+| Campo | Tipo | Padrão | Comportamento |
+|---|---|---|---|
+| `seed` | `string` (`#RRGGBB`) | obrigatório | base da paleta primária; secundária = `shiftHue(seed,+35)`, terciária = `shiftHue(seed,+210)`; neutros "puxados" para o matiz da seed |
+| `mode` | `Mode` | `"light"` (em `generateThemeVars`/provider) | `auto` segue o sistema e escuta `matchMedia` |
+| `radius` | `number` (px) | `12` | gera `--radius` e `--sg-radius` |
+| `warning`, `error`, `info`, `success` | `string` hex | gerado com matiz fixo (45°, 5°, 210°, 145°) | sobrescreve a base semântica |
+| `customVars` | `Record<string,string>` | — | aplicado por último em `generateThemeVars` (sobrescreve variáveis) |
+| `persistMode` | `boolean` | `undefined` (`true` no `defaultSeedTheme`) | se `true`, salva modo e `{seed,mode,radius}` |
+| `persistenceStrategy` | `PersistenceStrategy` (fe-core) | `createLocalStorageStrategy()` | permite persistir via API (estratégia assíncrona) |
+
+### `SeedThemeProvider` — props e comportamento (Confirmado)
+
+| Prop | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `initialTheme` | `SeedThemeInput` | `defaultSeedTheme` | tema inicial |
+| `applyTo` | `"html" \| "wrapper"` | `"html"` | `html`: `style.setProperty` em `document.documentElement`; `wrapper`: variáveis inline em um `<div>` |
+| `children` | `ReactNode` | — | — |
+
+- Chaves de persistência: `sg:theme:mode` e `sg:theme:config` (na estratégia; o localStorage padrão não usa prefixo).
+- Tema persistido **tem precedência** sobre `initialTheme` (exceto `persistMode` e `persistenceStrategy`, que vêm do inicial).
+- Estratégias assíncronas: hidratação em `useEffect` após o primeiro render.
+- `setTheme(partial)` mescla; `mode: "auto"` resolve via `getSystemMode()`. `setMode("light"|"dark")` salva se `persistMode`.
+
+### Tokens CSS gerados
+`generateThemeVars` produz, entre outros: `--sg-mode`, `--sg-bg`, `--sg-surface`, `--sg-muted-surface`, `--sg-border`, `--sg-ring`, `--sg-text`, `--sg-muted`, `--sg-disabled`, `--sg-on-disabled`, `--sg-link`, `--sg-link-hover`, `--sg-badge`, `--sg-on-badge`, `--sg-tooltip`, `--sg-on-tooltip`, escalas `--sg-{primary,secondary,tertiary,warning,error,info,success}-{50..900}`, `-hover` (= stop 600, todas as escalas) e `-active` (= stop 700, só primary/secondary/tertiary), `--sg-on-{primary,…}`, `--radius`, `--sg-radius`. Valores RGB "r g b" (para `rgb(var(--sg-x) / alpha)`). `generateComponentTokens` adiciona ~147 ocorrências de chaves `--sg-*` de componentes (contagem `grep`).
+
+## Contrato real
+
+- `useSgTheme()` retorna `{ vars, setTheme, setMode, currentMode, currentTheme }` (não há `seed` direto nem `reset`).
+- `SeedThemeProvider` aceita `initialTheme`, `applyTo` e `children`; `seed`, `radius`, `customVars` etc. vão dentro de `initialTheme`.
+- `AppShell` depende do `ThemeProvider` legado (`useTheme()` lança erro se ausente).
+
+## Exemplo
+Fonte: `packages/seedgrid-fe-theme/README.md` (uso básico) e `apps/showcase/src/app/layout.tsx`:
+
+```tsx
+import { SeedThemeProvider, useSgTheme } from "@seedgrid/fe-theme";
+
+<SeedThemeProvider initialTheme={{ seed: "#16803D", mode: "auto", radius: 12, persistMode: true }}>
+  {children}
+</SeedThemeProvider>
+
+function ThemeToggle() {
+  const { currentMode, setMode } = useSgTheme();
+  return <button onClick={() => setMode(currentMode === "light" ? "dark" : "light")}>Tema</button>;
+}
+```
+
+Outros: `examples/ThemeDemo.tsx`, `tailwind.config.example.js` no pacote (não detalhados).