@seedgrid/ai-toolkit 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,113 @@
+---
+tags: [seedgrid, front, component, fundamentos, api]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-components/src
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# API dos utilitários do `@seedgrid/fe-components`
+
+Visão geral e instalação: [[SeedGrid/SeedGrid-components/fundamentos/Visao-geral|Fundamentos — visão geral]]. Exemplos: [[SeedGrid/SeedGrid-components/fundamentos/Exemplos|Exemplos]].
+
+Todas as assinaturas abaixo foram lidas no código (**Confirmado**), salvo indicação. Caminhos relativos a `front/seedgrid-fe-components/packages/seedgrid-fe-components/`.
+
+## Máscaras — `src/masks.ts`
+
+Todas recebem `value: string` e retornam `string`. Exportadas no barrel (`src/index.ts`).
+
+| Função | Comportamento |
+|---|---|
+| `onlyDigits(value)` | remove tudo que não é dígito. **Também** existe uma `onlyDigits` em `validators.ts`; a exportada no barrel é a de `masks.ts`. |
+| `maskCpf(value)` | até 11 dígitos → `000.000.000-00` progressivo. |
+| `maskCnpj(value)` | até 14 caracteres **alfanuméricos** (maiúsculos) → `AA.AAA.AAA/AAAA-00` progressivo (suporta CNPJ alfanumérico). |
+| `maskCpfCnpj(value)` | se houver letra → `maskCnpj`; senão ≤ 11 dígitos → `maskCpf`, acima → `maskCnpj`. |
+| `maskCep(value)` | alias de `maskPostalCodeBR`. |
+| `maskPostalCodeBR(value)` | 8 dígitos → `00000-000`. |
+| `maskPostalCodePT(value)` | 7 dígitos → `0000-000`. |
+| `maskPostalCodeUS(value)` | até 9 dígitos → `00000` ou `00000-0000`. |
+| `maskPostalCodeES(value)` / `maskPostalCodeUY(value)` | 5 dígitos, sem separador. |
+| `maskPostalCodeAR(value)` | até 8 alfanuméricos maiúsculos, sem separador (comentário: `A0000AAA` ou legado `0000`). |
+| `maskPostalCodePY(value)` | 6 dígitos. |
+| `maskPhone(value)` | até 11 dígitos → `(DD) 0000-0000` ou `(DD) 00000-0000` progressivo. |
+
+## Validadores — `src/validators.ts`
+
+| Export | Assinatura | Comportamento |
+|---|---|---|
+| `isValidCpf` | `(value: string) => boolean` | 11 dígitos, rejeita todos iguais, valida os 2 DV (módulo 11). |
+| `isValidCnpj` | `(value: string) => boolean` | 14 alfanuméricos; valor do caractere = ASCII − 48 (regra do CNPJ alfanumérico); DV devem ser numéricos; rejeita explicitamente `00000000000000`. |
+| `isValidEmail` | `(value: string) => boolean` | regex simples `/.+@.+\..+/` após `trim`. |
+| `isBlockedEmailDomain` | `(email: string, extra?: string[]) => boolean` | extrai o domínio após o último `@` e compara (minúsculas) com `getBlockedEmailDomains(extra)`. |
+| `getBlockedEmailDomains` | `(extra?: string[]) => string[]` | união deduplicada e normalizada (trim + lowercase) de: `DEFAULT_BLOCKED_EMAIL_DOMAINS` + `globalThis.__seedgridBlockedEmailDomains` (se for array) + `extra`. |
+| `DEFAULT_BLOCKED_EMAIL_DOMAINS` | `string[]` | 37 domínios de `src/blocked-email-domains.ts` (yopmail, guerrillamail, mailinator, 10minutemail, temp-mail etc.). |
+| `validatePassword` | `(value, policy: PasswordPolicy = {}, i18n?) => string \| null` | `null` = válida; senão mensagem i18n `components.validators.password.invalid` com `{reasons}` concatenadas por `; `. Vazio → `components.validators.password.empty`. |
+| `validateBirthDate` | `(value, policy: BirthDatePolicy, i18n?) => string \| null` | exige `minAge` ou `maxAge` (senão retorna mensagem `configMissing`); `minAge > maxAge` → `configRange`; data inválida → `invalidDate`; fora da faixa → `ageBetween`/`ageMin`/`ageMax`. Valor vazio → `null`. |
+| `isDateAfter` | `(value: string, minDate?: string) => boolean` | `true` se algum argumento vazio; compara `getTime()` com `>=`. |
+| `isDateBefore` | `(value: string, maxDate?: string) => boolean` | idem com `<=`. |
+
+### `PasswordPolicy` (tipo exportado)
+
+| Campo | Tipo | Padrão efetivo em `validatePassword` | Efeito |
+|---|---|---|---|
+| `minSize` | `number` | `8` (mínimo forçado `1`) | tamanho mínimo |
+| `upper` | `boolean` | `true` | exige `[A-Z]` |
+| `lower` | `boolean` | `true` | exige `[a-z]` |
+| `number` | `boolean` | `true` | exige dígito |
+| `special` | `boolean` | `true` | exige `[^A-Za-z0-9]` |
+| `noRepeat` | `boolean` | `true` | proíbe sequência asc/desc de 3 (`abc`, `321`) e repetição (`aaa`, padrões tipo `a-a-a-a`) |
+
+### `BirthDatePolicy`
+`{ minAge?: number; maxAge?: number }` — ver `validateBirthDate`.
+
+### Configuração em runtime de domínios bloqueados
+Global `globalThis.__seedgridBlockedEmailDomains: string[]` (lido em `getRuntimeBlockedEmailDomains()`). Não há setter exportado — o app atribui diretamente (**Confirmado** pela leitura; nenhum setter encontrado). `SgInputEmail` usa `isBlockedEmailDomain(value, blockedEmailDomains)` quando `blockFakeMail` (padrão `true`) — `src/inputs/SgInputEmail.tsx`.
+
+## React Hook Form — `src/rhf.ts` (interno, **não exportado** no barrel)
+
+| Símbolo | Descrição |
+|---|---|
+| `type RhfFieldProps` | `{ name?: string; control?: any; register?: UseFormRegister<any>; rules?: RegisterOptions<any>; error?: string }`. `any` proposital (comentário): permite passar `register`/`control` de `useForm<T>()` tipado sem conflito de contravariância. |
+| `resolveFieldError(...errors)` | retorna a primeira string não vazia (após `trim`) ou `undefined`. |
+| `mergeRequiredRule(rules, required, message)` | se `required` verdadeiro, injeta `required: message` em `rules` quando ausente/`false`; preserva um `required` já definido. |
+
+Importado por 26 arquivos de `src/` (contagem `grep "../rhf"`), ex.: `SgAutocomplete`, `SgCheckboxGroup`, `SgCombobox`, `SgInputBirthDate`, `SgInputCNPJ`, `SgInputCPF`, `SgInputCurrency`, `SgInputDate`, `SgInputNumber`. Testes: `tests/rhf.test.mjs`, `tests/rhf-components-contract.test.mjs` (não executados).
+
+## i18n — `src/i18n/index.ts` (`"use client"`)
+
+Locais embutidos: `pt-BR`, `pt-PT`, `en-US` (alias `en`), `es`, `fr` — arquivos `.ts` com 214 chaves `components.*` cada (contagem por `grep`). Padrão global: `en-US`.
+
+| Export no barrel | Nome interno | Assinatura / comportamento |
+|---|---|---|
+| `SgComponentsI18nProvider` | idem | `({ locale?, messages?, children })` — contexto React; mescla mensagens embutidas do locale + `messages`. |
+| `useComponentsI18n` | idem | `() => SgComponentsI18n` — contexto ou, sem provider, `getComponentsI18n()`. |
+| `setComponentsI18n` | idem | `(input: SgComponentsI18nInput) => void` — grava em `globalThis.__seedgridComponentsI18n`; preserva mensagens customizadas anteriores se o locale não mudar. |
+| `getComponentsI18n` | idem | `() => SgComponentsI18n` — global ou `DEFAULT_I18N` (`en-US`). |
+| `resolveComponentsI18n` | idem | `(input?) => SgComponentsI18n` — mescla global + input. |
+| `tComponents` | `t` | `(i18n, key, params?) => string` — busca em `i18n.messages` → embutido do locale → `en-US` → a própria chave; aplica `formatMessage`. |
+| `formatComponentsMessage` | `formatMessage` | `(template, params?)` — substitui `{nome}`; placeholders sem valor permanecem. |
+| `normalizeComponentsLocale` | idem | `undefined` → `en-US`; `en` → `en-US`; demais inalterados. |
+| `getBuiltInComponentsMessages` | idem | catálogo embutido do locale (desconhecido → `en-US`). |
+| `componentsMessagesPtBr`, `componentsMessagesPtPt`, `componentsMessagesEnUs`, `componentsMessagesEn`, `componentsMessagesEs`, `componentsMessagesFr` | — | catálogos brutos. |
+
+Tipos: `SgComponentsLocale` (`"pt-BR" | "pt-PT" | "en-US" | "en" | "es" | "fr" | (string & {})`), `SgComponentsMessages` (`Record<string,string>`), `SgComponentsMessagesByNamespace`, `SgComponentsI18n` (`{locale, messages}`), `SgComponentsI18nInput` (`{locale?, messages?}`).
+
+`messages` aceita forma plana **ou** por namespace: se o objeto tiver a chave `components`, só ela é usada (`resolveMessages`).
+
+Metadados de IA: `src/i18n/SgComponentsI18nProvider.meta.ts` e `useComponentsI18n.meta.ts` entram no manifesto (`build-ai-manifest.mjs`).
+
+## Estilos — `src/injectStyles.ts` e `src/generated/compiledStyles.ts`
+
+| Símbolo | Exportado? | Descrição |
+|---|---|---|
+| `ensureSeedgridStylesInjected()` | não (chamado no topo de `src/index.ts`) | Injeta `<style id="seedgrid-fe-components-styles">` uma vez; no-op em SSR. |
+| `SEEDGRID_COMPILED_CSS` | não | String gerada por `scripts/build-style.mjs` ("AUTO-GENERATED … Do not edit by hand"). Começa com `:root{--sg-mode:light;--sg-bg:…}` (tema padrão). |
+
+## Metadados de IA — `src/ai-meta/`
+
+| Arquivo | Conteúdo |
+|---|---|
+| `types.ts` | `SgMetaPropV0`, `SgMetaExampleV0`, `SgMetaV0` (`version "0.1"`, `componentId`, `package "@seedgrid/fe-components"`, `exportName`, `slug`, `category` ∈ input/action/layout/feedback/navigation/data/provider/hook/gadget, `props`, `examples`, `showcase{route,hasPlayground,hasPropsTable}`, `sdui{rendererType,…}`) e `SgAiHintsV0` (`preferredUseCases`, `avoidUseCases`, `synonyms`, `rankingSignals`…). |
+| `generated-props.json` | `{ [exportName]: [{name,type,required,description}] }` gerado por `scripts/extract-props.mjs` (~186 KB). |
+
+O manifesto final `dist/ai/seedgrid-components.manifest.json` é servido pelo showcase em `GET /api/ai-manifest` e consumido pelo `seedgrid-components-mcp`.

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

@@ -0,0 +1,159 @@
+---
+tags: [seedgrid, front, component, fundamentos, exemplos]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-components; front/seedgrid-fe-components/apps/showcase/src/app/samples
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# Exemplos — fundamentos do `@seedgrid/fe-components`
+
+Referência: [[SeedGrid/SeedGrid-components/fundamentos/API|API dos utilitários]] · [[SeedGrid/SeedGrid-components/fundamentos/Visao-geral|Visão geral]].
+
+Cada exemplo indica a fonte. Os marcados "montado a partir da API" usam apenas assinaturas confirmadas no código, mas não existem literalmente no repositório.
+
+## 1. Instalação e estilos
+
+Fonte: `packages/seedgrid-fe-components/README.md`.
+
+```bash
+pnpm add @seedgrid/fe-components @seedgrid/fe-theme react-hook-form lucide-react
+```
+
+```tsx
+// Opcional: CSS estático em vez da injeção automática via JS
+import "@seedgrid/fe-components/style.css";
+import { SgInputText } from "@seedgrid/fe-components";
+```
+
+## 2. Tema no layout raiz (Next.js App Router)
+
+Fonte: `apps/showcase/src/app/layout.tsx` (trecho).
+
+```tsx
+import { SeedThemeProvider } from "@seedgrid/fe-theme";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="pt-BR" suppressHydrationWarning>
+      <body className="bg-[rgb(var(--sg-bg))] text-[rgb(var(--sg-text))]">
+        <SeedThemeProvider
+          initialTheme={{ seed: "#16803D", mode: "auto", radius: 8, persistMode: true }}
+          applyTo="html"
+        >
+          {children}
+        </SeedThemeProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+`suppressHydrationWarning` é usado porque o tema `auto`/persistido é resolvido no client (comentário no arquivo).
+
+## 3. i18n global (fora do React)
+
+Fonte: `apps/showcase/src/app/samples/set-components-i18n.tsx.sample`.
+
+```tsx
+import { setComponentsI18n } from "@seedgrid/fe-components";
+
+setComponentsI18n({
+  locale: "en-US",
+  messages: {
+    "components.inputs.required": "Required field.",
+    "components.password.common": "Password is too common."
+  }
+});
+```
+
+## 4. i18n por provider
+
+Fonte: `apps/showcase/src/app/samples/i18n-provider-root-layout.tsx.sample`.
+
+```tsx
+import { SgComponentsI18nProvider } from "@seedgrid/fe-components";
+
+const messagesEn = {
+  "components.inputs.required": "Required field.",
+  "components.inputs.email.invalid": "Invalid email."
+};
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en-US">
+      <body>
+        <SgComponentsI18nProvider locale="en-US" messages={messagesEn}>
+          {children}
+        </SgComponentsI18nProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+Para português: `locale="pt-BR"` já carrega o catálogo embutido; `messages` só sobrescreve chaves.
+
+## 5. Formulário com React Hook Form
+
+Fonte: `packages/seedgrid-fe-components/README.md` ("Formulario com React Hook Form").
+
+```tsx
+"use client";
+import { useForm } from "react-hook-form";
+import { SgButton, SgInputEmail, SgInputText, SgStack } from "@seedgrid/fe-components";
+
+type FormValues = { nome: string; email: string };
+
+export default function ExampleForm() {
+  const { register, handleSubmit } = useForm<FormValues>({ defaultValues: { nome: "", email: "" } });
+  return (
+    <form onSubmit={handleSubmit((data) => console.log(data))}>
+      <SgStack gap={12}>
+        <SgInputText id="nome" name="nome" register={register} label="Nome" required requiredMessage="Informe o nome." />
+        <SgInputEmail id="email" name="email" register={register} label="Email" required />
+        <SgButton label="Salvar" type="submit" />
+      </SgStack>
+    </form>
+  );
+}
+```
+
+## 6. Máscaras e validadores em código próprio
+
+Montado a partir da API (`src/masks.ts`, `src/validators.ts`).
+
+```ts
+import {
+  maskCpfCnpj, maskPhone, maskPostalCodeBR,
+  isValidCpf, isValidCnpj, validatePassword, validateBirthDate, isBlockedEmailDomain
+} from "@seedgrid/fe-components";
+
+maskCpfCnpj("12345678901");      // "123.456.789-01"
+maskPhone("11987654321");        // "(11) 98765-4321"
+maskPostalCodeBR("01001000");    // "01001-000"
+
+isValidCpf("123.456.789-09");    // boolean (checa DV)
+isValidCnpj(valorDigitado);      // aceita CNPJ numérico ou alfanumérico; os 2 DV devem ser numéricos
+
+// null = ok; string = mensagem i18n com os motivos
+const erroSenha = validatePassword("abc", { minSize: 10, special: false });
+const erroNascimento = validateBirthDate("2010-05-01", { minAge: 18 });
+
+isBlockedEmailDomain("x@yopmail.com");                 // true (lista padrão)
+isBlockedEmailDomain("x@empresa.com", ["empresa.com"]); // true (lista extra)
+```
+
+## 7. Domínios bloqueados em runtime (global)
+
+Montado a partir de `getRuntimeBlockedEmailDomains()` em `src/validators.ts` — não há setter exportado; o app atribui a global.
+
+```ts
+(globalThis as { __seedgridBlockedEmailDomains?: string[] }).__seedgridBlockedEmailDomains = [
+  "dominio-descartavel.example"
+];
+```
+
+## 8. Consumo do manifesto de IA
+
+Fonte: `apps/showcase/src/app/api/ai-manifest/route.ts` — lê `packages/seedgrid-fe-components/dist/ai/seedgrid-components.manifest.json` e devolve em `GET /api/ai-manifest` (`cache-control: no-store`; 404 `{"error":"AI manifest not available"}` se ausente).

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

@@ -0,0 +1,92 @@
+---
+tags: [seedgrid, front, component, fundamentos]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-components
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# Fundamentos do `@seedgrid/fe-components`
+
+Esta nota cobre **o que não é componente `Sg*`** dentro do pacote `@seedgrid/fe-components`: instalação, montagem (peers, CSS, tema), `exports` do `package.json`, build, e os utilitários transversais (`masks`, `validators`, `rhf`, `i18n`, `injectStyles`, `blocked-email-domains`, `ai-meta`, `generated`).
+
+- API detalhada: [[SeedGrid/SeedGrid-components/fundamentos/API|API dos utilitários]]
+- Exemplos: [[SeedGrid/SeedGrid-components/fundamentos/Exemplos|Exemplos dos utilitários]]
+- Pacotes irmãos: [[SeedGrid/SeedGrid-components/pacotes/Visao-geral|Pacotes do monorepo front]] · tema em [[SeedGrid/SeedGrid-components/pacotes/fe-theme|@seedgrid/fe-theme]]
+- App de demonstração: [[SeedGrid/SeedGrid-components/showcase|Showcase]]
+
+## Identificação do pacote
+
+| Campo | Valor | Certeza |
+|---|---|---|
+| Nome | `@seedgrid/fe-components` | Confirmado (`package.json`) |
+| Versão | `2026.7.1` | Confirmado |
+| Licença | MIT | Confirmado |
+| Módulo | ESM (`"type": "module"`), `main: dist/index.js`, `types: dist/index.d.ts` | Confirmado |
+| `sideEffects` | `true` (o import do barrel injeta CSS) | Confirmado |
+| `files` | `dist` | Confirmado |
+
+### `exports` do `package.json`
+
+| Subpath | Destino | Observação |
+|---|---|---|
+| `.` | `./dist/index.js` (+ `./dist/index.d.ts`) | Barrel único com todos os componentes e utilitários. |
+| `./style.css` | `./dist/style.css` | CSS estático pré-compilado (alternativa à injeção automática). |
+
+**Confirmado**: não há subpaths por grupo (`/inputs`, `/i18n` etc.). `dist/sandbox.cjs` (gerado pelo `build:sandbox`) **não** está no mapa de `exports`; ele é usado pelo `SgPlayground` via arquivo virtual `/node_modules/@seedgrid/fe-components/dist/index.js` → `require("./sandbox.cjs")` (ver [[SeedGrid/SeedGrid-components/pacotes/fe-playground|@seedgrid/fe-playground]]).
+
+## Dependências
+
+| Tipo | Pacotes | Observação |
+|---|---|---|
+| `dependencies` | `@pqina/flip ^1.8.4`, `qrcode.react ^4.2.0`, `@seedgrid/pulse-subscriber-react ^3.0.0` | flip → `SgFlipDigit`; QR → `SgQRCode`; Pulse → `SgRealtimeProvider` (Confirmado pelos comentários do `tsup.sandbox.config.ts`). |
+| `peerDependencies` obrigatórios na prática | `react ^18.2.0 \|\| ^19.0.0`, `react-hook-form ^7.0.0`, `lucide-react ^0.468.0 \|\| ^1.0.0` | Todos declarados como peer (sem `peerDependenciesMeta`, portanto nenhum marcado como opcional). |
+| `peerDependencies` TipTap | `@tiptap/core`, `@tiptap/pm`, `@tiptap/react`, `@tiptap/starter-kit`, `@tiptap/extension-*` (underline, link, image, text-align, text-style, color, highlight, subscript, superscript, font-family), todos `^2.9.1` | O README diz que só são necessários para `SgTextEditor`; o `package.json` não os marca como opcionais (**Inferência**: o gerenciador avisará peer ausente se não instalados). |
+| `devDependencies` relevantes | `@seedgrid/fe-theme` (workspace), `tailwindcss ^3.4.10`, `tailwindcss-animate`, `postcss`, `autoprefixer`, `tsup ^8.4.0`, `jsdom` | Tailwind só é usado no build; consumidor não precisa de Tailwind. |
+
+
+## Instalação e montagem
+
+Fonte: `packages/seedgrid-fe-components/README.md` (seções "Instalacao" e "Uso rapido") e código citado.
+
+1. Instalação recomendada (README): `pnpm add @seedgrid/fe-components @seedgrid/fe-theme react-hook-form lucide-react`. Para `SgTextEditor`, adicionar os peers TipTap. Para playground, `@seedgrid/fe-playground`.
+2. **Estilos — três camadas** (Confirmado):
+   - **Injeção automática**: `src/index.ts` chama `ensureSeedgridStylesInjected()` no topo do barrel. A função cria `<style id="seedgrid-fe-components-styles">` em `document.head` com `SEEDGRID_COMPILED_CSS` (string gerada). É protegida contra SSR (`typeof document === "undefined"`) e contra dupla injeção (verifica o `id`). O comentário explica que é uma **chamada real** (não `import "./x"`) para não ser eliminada por bundlers.
+   - **CSS estático**: `import "@seedgrid/fe-components/style.css"` — mesmo CSS, útil para evitar *flash* antes da hidratação (README).
+   - **Tema em runtime (opcional)**: `SeedThemeProvider` de `@seedgrid/fe-theme` regrava as variáveis `--sg-*`. O CSS compilado já contém um bloco `:root{...}` com as variáveis do `defaultSeedTheme` (modo light), então os componentes ficam estilizados **sem provider** (Confirmado em `scripts/build-style.mjs` e no início de `src/generated/compiledStyles.ts`).
+3. **i18n**: por padrão as mensagens dos componentes estão em `en-US` (`DEFAULT_I18N`). Para trocar: `SgComponentsI18nProvider` (contexto React) ou `setComponentsI18n` (global em `globalThis.__seedgridComponentsI18n`). Ver [[SeedGrid/SeedGrid-components/fundamentos/API|API › i18n]].
+4. **React Hook Form**: inputs aceitam `register`/`control`/`rules`/`error` (tipo interno `RhfFieldProps`, em `src/rhf.ts`).
+5. Next.js: o showcase usa `transpilePackages: ["@seedgrid/fe-components", "@seedgrid/fe-theme"]` em `apps/showcase/next.config.ts` (Confirmado). **Inferência**: não é obrigatório para consumidores do pacote publicado (o `dist` já é JS compilado), mas é o padrão usado no monorepo.
+
+## Build (`scripts.build`)
+
+Ordem exata (Confirmado em `package.json`):
+
+| Passo | Comando | Saída |
+|---|---|---|
+| 1 | `pnpm run clean` | remove `dist/` |
+| 2 | `node scripts/build-style.mjs` | roda Tailwind sobre `styles/tailwind.css` (content `./src/**/*.{ts,tsx}`) + bloco `:root` gerado com `generateThemeVars`/`generateComponentTokens` do `@seedgrid/fe-theme` (importa os `.js` do `dist` do tema por *deep import*); escreve `dist/style.css` **e** `src/generated/compiledStyles.ts` |
+| 3 | `tsc -p tsconfig.json` | `dist/**` (JS + `.d.ts` + `declarationMap`) |
+| 4 | `node scripts/extract-props.mjs` | `src/ai-meta/generated-props.json` — props extraídas dos tipos `<Export>Props` via TypeScript compiler API (ignora `control`, `register`, `rules`, `inputProps`, `className`, `labelClassName`, `style`, `ref`, `key`, `elevation`, `borderRadius`, `aria-*`, `data-*`) |
+| 5 | `node scripts/build-ai-manifest.mjs` | `dist/ai/seedgrid-components.manifest.json` — une os `*.meta.ts` (curadoria) com `generated-props.json` |
+| 6 | `node scripts/validate-example-refs.mjs` | falha o build se algum `examples[].file` do manifesto não existir (baseline em `scripts/example-refs-baseline.json`, declarado vazio no comentário) |
+| 7 | `pnpm run build:sandbox` | `tsup` → `dist/sandbox.cjs` (CJS minificado, para Sandpack) |
+
+**Atenção**: o passo 2 depende de `@seedgrid/fe-theme` já ter `dist/` (deep import de `node_modules/@seedgrid/fe-theme/dist/theme/*.js`). **Inferência**: no `turbo build` isso é garantido pelo `dependsOn: ["^build"]`.
+
+Outros scripts: `dev` (build-style + `tsc --watch`), `typecheck`, `test` (faz `build` e roda 27 arquivos `node --test tests/*.test.mjs`, incluindo `i18n.test.mjs`, `rhf.test.mjs`, `rhf-components-contract.test.mjs`, `i18n-components-contract.test.mjs`, `utils.test.mjs`, `ai-manifest-props-contract.test.mjs`). Testes **não executados** nesta análise.
+
+`tsup.sandbox.config.ts` (Confirmado): entry `src/index.ts`; externos `react`, `react-dom`, `lucide-react`, `qrcode`, todos os `@tiptap/*`, `@codesandbox/sandpack-react`; embutidos (`noExternal`) `react-hook-form`, `qrcode.react`, `@pqina/flip`, `@seedgrid/pulse-subscriber-react`; define `process.env.NODE_ENV="production"`.
+
+## Mapa dos utilitários
+
+| Arquivo | Exportado no barrel? | Papel |
+|---|---|---|
+| `src/masks.ts` | sim | Máscaras de CPF, CNPJ (inclusive alfanumérico), CPF/CNPJ, CEP e códigos postais BR/PT/US/ES/UY/AR/PY, telefone BR. |
+| `src/validators.ts` | sim | Validação CPF, CNPJ (alfanumérico), e-mail, domínios de e-mail descartáveis, senha (política), datas e data de nascimento (idade). |
+| `src/blocked-email-domains.ts` | indireto (via `DEFAULT_BLOCKED_EMAIL_DOMAINS`) | Lista padrão de 37 domínios descartáveis. |
+| `src/rhf.ts` | **não** | Tipo `RhfFieldProps` e helpers `resolveFieldError`, `mergeRequiredRule`, usados internamente pelos inputs. |
+| `src/i18n/` | sim | Provider, hooks, `t`, catálogos `pt-BR`, `pt-PT`, `en-US`, `es`, `fr` (214 chaves `components.*` cada). |
+| `src/injectStyles.ts` | **não** (executado no import) | Injeção do CSS compilado no `<head>`. |
+| `src/generated/compiledStyles.ts` | **não** | Constante `SEEDGRID_COMPILED_CSS` (auto-gerada, ~67 KB). |
+| `src/ai-meta/` | **não** | Tipos `SgMetaV0`/`SgAiHintsV0` dos `*.meta.ts` e `generated-props.json`; alimentam o manifesto de IA. |