@softize/opus 8.6.6

package/src/ui/index.ts

@@ -0,0 +1,92 @@
+/**
+ * @softize/opus/ui — shared types for UI drivers.
+ *
+ * Driver específico (react, vue) implementa Provider + hooks + componentes.
+ * Aqui ficam apenas types/contratos compartilhados.
+ */
+
+import type { ActionError, Paginated } from '../core/index.ts'
+
+/**
+ * Metadado de descoberta de um componente — cada componente co-localiza um `meta`
+ * com este shape; o manifesto/MCP lê isso da fonte (em vez de parsear cva via AST).
+ */
+export interface ComponentMeta {
+  /** Nome canônico (kebab), ex.: 'button', 'dropdown-menu'. */
+  name: string
+  /** Origem: descendente do shadcn (forkado) ou nativo do Opus. */
+  ancestry: 'shadcn' | 'opus'
+  /** Quando usar / quando não — guia o agente de design a escolher certo. */
+  whenToUse: string
+  /** Aviso de retirada no catálogo, com o caminho de migração. */
+  deprecated?: {
+    /** Alternativa recomendada; aceita `código` inline como `whenToUse`. */
+    alternative: string
+    /** Versão em que a retirada começou, quando houver. */
+    since?: string
+  }
+}
+
+/**
+ * Estado de invocação de uma action (sync). Hooks de UI driver expõem
+ * shape derivado disto.
+ */
+export interface ActionState<TData> {
+  data: TData | undefined
+  error: ActionError | undefined
+  isIdle: boolean
+  isLoading: boolean
+  isSuccess: boolean
+  isError: boolean
+}
+
+export interface ListState<TItem> {
+  items: TItem[]
+  cursor: { next: string | null; prev?: string | null }
+  total: number | undefined
+  error: ActionError | undefined
+  isIdle: boolean
+  isLoading: boolean
+  isSuccess: boolean
+  isError: boolean
+}
+
+/**
+ * Wrapper conveniente pra zerar estado quando handler chama `reset()`.
+ */
+export function idleAction<T>(): ActionState<T> {
+  return {
+    data: undefined,
+    error: undefined,
+    isIdle: true,
+    isLoading: false,
+    isSuccess: false,
+    isError: false,
+  }
+}
+
+export function idleLookup<T>(): ListState<T> {
+  return {
+    items: [],
+    cursor: { next: null },
+    total: undefined,
+    error: undefined,
+    isIdle: true,
+    isLoading: false,
+    isSuccess: false,
+    isError: false,
+  }
+}
+
+/**
+ * Helper pra checar se um output tem shape `Paginated`.
+ */
+export function isPaginated(value: unknown): value is Paginated<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'items' in value &&
+    Array.isArray((value as { items: unknown }).items) &&
+    'cursor' in value
+  )
+}

package/src/ui/lib/cn.ts

@@ -0,0 +1,10 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+/**
+ * Junta classes condicionais (clsx) e resolve conflitos do Tailwind (twMerge).
+ * Canônico do Opus — o app importa daqui em vez de duplicar.
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs))
+}

package/src/ui/lib/zod-pt-br.ts

@@ -0,0 +1,38 @@
+/**
+ * Dicionário de mensagens de validação em pt-BR (zod errorMap).
+ *
+ * O zod emite mensagens em inglês por default ("String must contain at least…");
+ * este mapa traduz os códigos de issue pra microcopy da casa. Aplicado pelo
+ * useFormAction no zodResolver — todo ActionForm valida em pt-BR sem que cada
+ * schema precise declarar mensagem campo a campo (schema declara só a REGRA).
+ * Pra mensagem específica, o schema ainda pode passar a sua (ex.: .min(8, '…')),
+ * que tem precedência sobre o mapa.
+ */
+import { z } from 'zod'
+
+export const zodErrorMapPtBr: z.ZodErrorMap = (issue, ctx) => {
+  switch (issue.code) {
+    case z.ZodIssueCode.invalid_type:
+      if (issue.received === 'undefined' || issue.received === 'null') return { message: 'Obrigatório.' }
+      return { message: 'Valor inválido.' }
+    case z.ZodIssueCode.too_small:
+      if (issue.type === 'string') {
+        return { message: Number(issue.minimum) <= 1 ? 'Obrigatório.' : `Mínimo de ${issue.minimum} caracteres.` }
+      }
+      if (issue.type === 'array') return { message: `Selecione pelo menos ${issue.minimum}.` }
+      return { message: `Valor mínimo: ${issue.minimum}.` }
+    case z.ZodIssueCode.too_big:
+      if (issue.type === 'string') return { message: `Máximo de ${issue.maximum} caracteres.` }
+      if (issue.type === 'array') return { message: `Selecione no máximo ${issue.maximum}.` }
+      return { message: `Valor máximo: ${issue.maximum}.` }
+    case z.ZodIssueCode.invalid_string:
+      if (issue.validation === 'email') return { message: 'Email inválido.' }
+      if (issue.validation === 'url') return { message: 'URL inválida.' }
+      if (issue.validation === 'uuid') return { message: 'Identificador inválido.' }
+      return { message: 'Formato inválido.' }
+    case z.ZodIssueCode.invalid_enum_value:
+      return { message: 'Escolha uma das opções.' }
+    default:
+      return { message: ctx.defaultError }
+  }
+}

package/src/ui/meta.ts

@@ -0,0 +1,412 @@
+/**
+ * @softize/opus/ui/meta — o mapa CENTRAL de `meta` de todos os componentes.
+ *
+ * O componente portado é byte-fiel ao shadcn (sem `meta` co-localizado, pra re-sincronizar
+ * limpo); o metadado de descoberta (whenToUse/ancestry) mora AQUI, fora do arquivo. Quem
+ * precisa do meta em RUNTIME — a doc de UI (DocBrowser), o manifesto, ferramentas — importa
+ * este subpath explicitamente (`@softize/opus/ui/meta`); o barrel de runtime (react.tsx) não
+ * o re-exporta de propósito (metadado de build-time, fora do bundle dos apps).
+ */
+import type { ComponentMeta } from './index.ts'
+
+/** Todos os metas, chaveados pelo nome canônico (kebab). Fonte única — zero duplicação. */
+export const componentMeta = {
+  'alert': {
+    name: 'alert',
+    ancestry: 'opus',
+    whenToUse:
+      'Aviso INLINE no fluxo da página (o erro do login, o "sincronizado" da lista) — `role="alert"`, então o leitor de tela anuncia sozinho. Forma CURTA (o caso comum): `<Alert title description icon variant />` numa linha; composição (`AlertTitle`/`AlertDescription`) só quando o conteúdo é rico (parágrafos, link, ação). `variant` default/destructive/success. Pra INTERROMPER cobrando decisão, use `confirm()`; pra recado passageiro, `toast`.',
+  },
+  'badge': {
+    name: 'badge',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Rótulo curto de status/categoria. `variant` pra intenção (default/secondary/destructive/outline) ou tom de status (success/warning/info, fill tingido). Não-interativo — pra clique, use Button ou `asChild` num <a>.',
+  },
+  'button': {
+    name: 'button',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Ação clicável. `variant` pra intenção (default/secondary/outline/ghost/destructive/link), `size` pro tamanho (default/sm/lg · icon/icon-sm/icon-xs pros só-ícone, 36/32/24px — o icon-xs é a ação DENTRO de um campo, o trailing do Input/Select). `busy` pra ação em andamento (spinner + desabilita — é o "depois" do clique, não o "carregando" de conteúdo, que é Spinner/Skeleton num nível de página). `asChild` pra renderizar como outro elemento (ex.: âncora com cara de botão).',
+  },
+  'card': {
+    name: 'card',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Superfície da casa (bg-card + borda + rounded-lg, flat). Box simples: `<Card className="p-4">…</Card>`. Estruturado: Card > CardHeader(CardTitle/CardDescription) + CardContent + CardFooter — o padding mora nos slots (como o Dialog). Divergência declarada vs shadcn: rounded-lg, sem shadow, sem flex/gap forçados (o upstream brigava com card-box simples).',
+  },
+  'chat': {
+    name: 'chat',
+    ancestry: 'opus',
+    whenToUse:
+      'Chat da casa (lista de mensagens + composer) que gerencia a conversa por dentro (estado/loading/auto-scroll; Enter envia, Shift+Enter quebra linha). A inteligência vem da prop `send` — resposta inteira (Promise<string>) OU streaming (AsyncIterable<ChatEvent>: texto incremental, indicador vivo do tool, artefato via renderArtifact). No Opus, o backend liga em `runtime.aiFor(base).run(...)` ou `.runStream(...)`. Dê altura ao container (ex.: `h-full`).',
+  },
+  'checkbox': {
+    name: 'checkbox',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Caixa de marcação booleana (Radix). Controlado por `checked`/`onCheckedChange`. Parear com Label. Pra escolha única de várias opções, use Select/RadioGroup.',
+  },
+  'icon-picker': {
+    name: 'icon-picker',
+    ancestry: 'opus',
+    whenToUse:
+      'Seletor de ícone: gatilho com o ícone corrente + lista buscável (mesma receita Popover+Command do Select buscável). O value é o NOME do ícone (kebab-case) — renderize com a mesma paleta (iconPickerIcons[name] ?? fallback). Paleta default curada (~40, lucide); vocabulário próprio via prop icons. Pra personalização de item criado pelo usuário (relatório, projeto, pasta).',
+  },
+  'command': {
+    name: 'command',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Lista filtrável com teclado (cmdk) — base de command-palettes. Use CommandDialog pra palette modal (⌘K). Pra escolha simples, use o Select direto.',
+  },
+  'composer': {
+    name: 'composer',
+    ancestry: 'opus',
+    whenToUse:
+      'A caixa de escrever da casa (o composer do Chat, extraído): textarea numa pílula elevada, Enter envia / Shift+Enter quebra linha, enviar dentro. Use SOZINHO quando há entrada de texto mas não um chat — ex.: o composer de criação de sessão do Maestro (sem histórico). Com `actions`, ganha uma barra embaixo pra seletores discretos à esquerda (app, agente, contexto…) — o mesmo lugar onde o Maestro põe app/task e a GB poria o agente. Sem `actions`, é a linha única de sempre. Controlado (`value`/`onChange`/`onSubmit`); `submitDisabled` gateia além de vazio/busy. Pra um chat completo (mensagens + este composer), use Chat.',
+  },
+  'copyable': {
+    name: 'copyable',
+    ancestry: 'opus',
+    whenToUse:
+      'Clicar-pra-copiar com feedback: copia `value` pro clipboard e o ícone vira check por ~1.5s. Sem filhos é um botão-ícone (toolbar/célula); com filhos, o rótulo visível + o ícone. Pra IDs, tokens, slugs, URLs. No-op silencioso se o clipboard não existir (contexto inseguro/SSR).',
+  },
+  'dialog': {
+    name: 'dialog',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Janela modal com overlay e trap de foco (Radix). O DialogContent é a superfície PURA (sem padding); o espaço mora nos slots: DialogHeader (fixo) > DialogTitle/Description, DialogBody (rola; opcional) e DialogFooter (faixa de ação; opcional). `showCloseButton={false}` no DialogContent esconde o "X" (modal que exige ação). Pra menu de ações, use Menu; pra ancorado sem modal, Popover.',
+  },
+  'input': {
+    name: 'input',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Campo de texto de uma linha. Aceita todos os atributos nativos de <input> (type, placeholder, disabled). `icon` (ícone leading, identidade) e `trailing` (ação no fim — limpar, mostrar senha) são adornos por PROP, as mesmas do Select (adorno de campo é prop, não composição). Pra rótulo, parear com Label; pra addon rico (botão no fim, prefixo de texto, múltiplos), InputGroup.',
+  },
+  'label': {
+    name: 'label',
+    ancestry: 'shadcn',
+    whenToUse: 'Rótulo acessível de um campo. `htmlFor` aponta pro id do controle. Parear com Input/Textarea/Select.',
+  },
+  'markdown': {
+    name: 'markdown',
+    ancestry: 'opus',
+    whenToUse:
+      'Renderiza markdown como HTML semântico (motor markdown-it — o MESMO da doc; o parser de regex saiu em 7.1.0). `html: false`: tag no fonte é escapada, então serve pra texto de gente e de modelo. A tipografia vem do `prose` mapeado nos tokens da casa (theme.css) — não passe classe de tipografia por fora; o 1º/último bloco já não empurram a caixa em volta. Pra código com destaque e cópia, CodeBlock.',
+  },
+  'menu': {
+    name: 'menu',
+    ancestry: 'opus',
+    whenToUse:
+      'O menu de AÇÕES da casa: lista flutuante ancorada num gatilho (Radix DropdownMenu). Compõe Menu > MenuTrigger (`asChild` funde no Button) + MenuContent > (MenuItem, MenuCheckboxItem, MenuRadioGroup>MenuRadioItem, MenuLabel, MenuSeparator, MenuShortcut, MenuSub>MenuSubTrigger+MenuSubContent). `variant="destructive"` no item para a ação que apaga. É o único menu (5.0.0): ContextMenu, Menubar e NavigationMenu saíram — mesmo papel com outro gatilho, zero uso. Pra ESCOLHER um valor, use Select; pra busca por teclado, Command; pra conteúdo livre ancorado, Popover.',
+  },
+  'popover': {
+    name: 'popover',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Painel flutuante ancorado num gatilho, sem modal (Radix). Pra conteúdo livre (form curto, detalhes). Use PopoverHeader/PopoverTitle/PopoverDescription pra estruturar. Pra lista de ações, use Menu; pra modal, Dialog.',
+  },
+  'select': {
+    name: 'select',
+    ancestry: 'opus',
+    whenToUse:
+      'O seletor ÚNICO da casa: toda escolha em lista. Data-driven (`options` = { value, label, hint?, content?, group? }), nunca JSX de item. Modos por prop, não por componente: `searchable` (busca; a régua é ACHABILIDADE — lista longa sem busca é rolar até cansar), `multiple` (chips + Selecionar tudo), `onSearch` (busca no servidor), `native` (o <select> do sistema — lista curta e sabida, picker do SO), `variant="ghost"` (a barra do composer, com `triggerLabel` encurtando o gatilho). Também: `icon` (leading), `trailing` (ação custom no fim do campo, ex.: um botão que age sobre o valor), `size` (default/sm), `clearable`. Absorveu Combobox, NativeSelect, ComposerSelect e o Select do Radix (3.0.0). Pra ação, Menu; pra 2–3 opções sempre visíveis, RadioGroup.',
+  },
+  'separator': {
+    name: 'separator',
+    ancestry: 'shadcn',
+    whenToUse: 'Linha divisória entre seções/itens (Radix). `orientation` horizontal|vertical. Decorativa por padrão (a11y).',
+  },
+  'skeleton': {
+    name: 'skeleton',
+    ancestry: 'shadcn',
+    whenToUse: 'Placeholder pulsante de carregamento. Dê o tamanho via className (h-4 w-32). Pra estado de loading antes do conteúdo chegar.',
+  },
+  'spinner': {
+    name: 'spinner',
+    ancestry: 'shadcn',
+    whenToUse: 'Loading girando (ação em andamento: botão, fetch). Pra placeholder com forma de conteúdo, use Skeleton.',
+  },
+  'table': {
+    name: 'table',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Tabela de dados. Compõe Table > (TableHeader > TableRow > TableHead, TableBody > TableRow > TableCell). Vem SEM borda externa — o datagrid da casa é a Table num wrapper "overflow-hidden rounded-lg border border-border". Pra listagem tabular — pro pattern de search use ActionList (que já monta a tabela emoldurada do spec).',
+  },
+  'tabs': {
+    name: 'tabs',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Abas pra alternar entre painéis de conteúdo (Radix). Compõe Tabs > (TabsList > TabsTrigger + TabsContent), pareando `value` do trigger com o do content. `variant` na TabsList: `default` (pill) ou `line` (barra sublinhada). `size` no Tabs (default h-9 / sm h-8 — o par do sm de Button/Select, pra fileira densa). `orientation` (horizontal/vertical).',
+  },
+  'textarea': {
+    name: 'textarea',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Campo de texto multilinha. Aceita os atributos nativos de <textarea> (rows, placeholder, disabled). Cresce com o conteúdo via `field-sizing-content`.',
+  },
+  'toast': {
+    name: 'toast',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Notificação efêmera (sonner). Monte `<Toaster />` 1x no root e dispare com `toast.success/error/message(...)`. Pra mensagem persistente inline, use Alert.',
+  },
+  'tooltip': {
+    name: 'tooltip',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Dica curta no hover/foco de um elemento (Radix). Envolver a árvore num TooltipProvider. Só texto auxiliar — nunca pôr ação ou conteúdo essencial aqui.',
+  },
+  'truncate': {
+    name: 'truncate',
+    ancestry: 'opus',
+    whenToUse:
+      'Texto truncado com tooltip SÓ quando transborda (medição do overflow, re-medida em resize) — substitui a composição `block truncate` + `title` sempre presente, que mostra dica até em texto que não corta. `tooltip` sobrepõe o conteúdo da dica (default: os children). Requer TooltipProvider na raiz. Pra célula de tabela, nome de arquivo, URL — qualquer linha única que pode estourar.',
+  },
+  'accordion': {
+    name: 'accordion',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Lista de seções empilhadas que abrem/fecham (Radix). `type` single (um painel por vez — combine com `collapsible` pra permitir fechar todos) ou multiple (vários abertos). Cada AccordionItem precisa de `value`; o chevron já vem no AccordionTrigger. Pra alternar conteúdo lado a lado, use Tabs; pra um único bloco recolhível solto, use Collapsible.',
+  },
+  'alert-dialog': {
+    name: 'alert-dialog',
+    ancestry: 'opus',
+    whenToUse:
+      'Diálogo modal que INTERROMPE pra cobrar decisão e NÃO fecha clicando fora (`role="alertdialog"`) — a confirmação destrutiva. Desenho ÚNICO e compacto (6.0.0: a prop `size` saiu, o largo não existe mais). Compõe AlertDialog > AlertDialogTrigger (asChild) + AlertDialogContent > AlertDialogHeader(AlertDialogMedia? + AlertDialogTitle/Description) + AlertDialogFooter(Cancel/Action). ATENÇÃO: Action e Cancel do Radix FECHAM ao clicar — pra ação async que só some no sucesso, use Button no footer. Na prática você quase nunca monta isto à mão: `confirm()` já faz, e o DeleteButton/ActionTrigger vêm prontos.',
+  },
+  'aspect-ratio': {
+    name: 'aspect-ratio',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Trava a proporção de um bloco (Radix) — a largura vem do pai e a altura é derivada de `ratio` (16/9 pra vídeo/preview, 1 pra quadrado, 4/3 clássico). Use pra mídia, thumbnails e previews de worktree não pularem o layout enquanto carregam. Borda/rounded/overflow-hidden moram no AspectRatio; o filho preenche com h-full w-full object-cover. Pra largura fixa em si, é o contêiner que decide, não este componente.',
+  },
+  'avatar': {
+    name: 'avatar',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Retrato de uma pessoa ou agente (Radix). AvatarImage (src/alt) + AvatarFallback (iniciais ou ícone) — o fallback cobre o carregamento e a falha da imagem. `size` sm/default/lg. AvatarBadge é o selo de status no canto (tinja o fundo). Pra a pilha de membros, envolva os Avatar num AvatarGroup e feche o excedente com AvatarGroupCount ("+N").',
+  },
+  'breadcrumb': {
+    name: 'breadcrumb',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Trilha de navegação hierárquica (workspace → repositório → sessão): mostra onde o usuário está e o caminho de volta. `BreadcrumbLink` pros níveis navegáveis, `BreadcrumbPage` pro atual (não clicável), `BreadcrumbSeparator` entre eles e `BreadcrumbEllipsis` pra colapsar trilhas longas. Pra alternar painéis no mesmo nível, use Tabs.',
+  },
+  'button-group': {
+    name: 'button-group',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Junta botões (e afins) num bloco coeso — bordas internas colapsadas e cantos arredondados só nas pontas. `orientation` horizontal/vertical. ButtonGroupText pra um rótulo/prefixo colado ao grupo; ButtonGroupSeparator pra cortar visualmente entre ações. Pra um menu de opções, prefira Menu; pra campo com addon, InputGroup.',
+  },
+  'calendar': {
+    name: 'calendar',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Grade de datas (react-day-picker) pra escolher um dia ou um intervalo. `mode` define a seleção (single/multiple/range) e o formato de `selected`/`onSelect` (Date, Date[] ou { from, to }). `captionLayout="dropdown"` troca o título do mês por seletores de mês/ano (pular pra um período distante); `numberOfMonths` mostra meses lado a lado; `disabled` (Matcher) corta datas. Pra exibir num popover de campo, ancore no Popover.',
+  },
+  'carousel': {
+    name: 'carousel',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Trilho de slides deslizáveis (embla). Compõe Carousel > CarouselContent > CarouselItem + CarouselPrevious/CarouselNext; o `basis` do item controla quantos cabem na vista. `orientation` (horizontal/vertical), `opts` repassa o embla (loop, align), `setApi` expõe a instância. Pra lista paginada de dados, use Table; pra navegação entre painéis, Tabs.',
+  },
+  'collapsible': {
+    name: 'collapsible',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Seção que abre e fecha (Radix): um CollapsibleTrigger revela ou esconde o CollapsibleContent. Compõe Collapsible > (CollapsibleTrigger + CollapsibleContent) — o Trigger já é o `<button>`. `defaultOpen` pro modo não controlado; `open`/`onOpenChange` pro controlado (ex.: girar o chevron); `disabled` trava o gatilho. Pra alternar entre vários painéis, use Tabs; pra menu de ações ancorado, Menu.',
+  },
+  'drawer': {
+    name: 'drawer',
+    ancestry: 'opus',
+    whenToUse:
+      'O painel que desliza de uma borda da tela (Radix Dialog: overlay + trap de foco + ESC), pra detalhe/edição lateral sem trocar de tela. Compõe Drawer > DrawerTrigger + DrawerContent (side="right|left|top|bottom") > (DrawerHeader > DrawerTitle/DrawerDescription, conteúdo, DrawerFooter); DrawerClose fecha, `asChild` funde no Button. É o port do `sheet` do shadcn com o nome que o ecossistema React usa — o `drawer` do registry (vaul, com gesto de arrastar) foi removido em 4.0.0: mesmo papel, zero uso. Pra modal centrado, Dialog; pra menu de ações, Menu.',
+  },
+  'empty': {
+    name: 'empty',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Estado vazio dentro de uma região: moldura tracejada centrada com `EmptyHeader` (mídia + `EmptyTitle` + `EmptyDescription`) e `EmptyContent` pras ações. `EmptyMedia variant` icon (quadrado muted) ou default (sem fundo). Pra erro inline use Alert; pra carregamento, Skeleton.',
+  },
+  'field': {
+    name: 'field',
+    ancestry: 'shadcn',
+    whenToUse:
+      'O esqueleto de um campo de formulário: rótulo, controle, descrição e erro compostos com espaçamento consistente. Field empilha (orientation vertical) ou põe o controle ao lado (horizontal/responsive, bom pra toggle); FieldLabel (htmlFor↔id), FieldDescription (ajuda) e FieldError (mensagem só quando há erro, ou uma lista de errors) preenchem. Agrupe campos relacionados num FieldSet > FieldLegend + FieldGroup, com FieldSeparator entre eles; FieldContent + FieldTitle dão o bloco texto quando o controle não é um <label>. É layout — o estado e a validação ficam no seu form (ou no ActionForm, que já monta tudo isto).',
+  },
+  'input-group': {
+    name: 'input-group',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Campo composto: cola ícones, texto e botões a um InputGroupInput/InputGroupTextarea numa única moldura (foco e erro propagam pro grupo todo). InputGroupAddon ancora os adornos — `align` inline-start/inline-end nas laterais, block-start/block-end empilha acima/abaixo (exige a moldura alta do InputGroupTextarea, é o padrão do composer). InputGroupText é o rótulo inerte (prefixo/sufixo); InputGroupButton é o botão embutido (ghost por padrão, `size` xs/sm/icon-xs/icon-sm). Só um ÍCONE leading não precisa disto — é a prop `icon` do Input (uma forma só pra adorno de campo, igual ao Select). InputGroup é pros casos que a prop não cobre: botão no fim, prefixo de texto, adorno em bloco, múltiplos. Pra agrupar botões soltos, ButtonGroup.',
+  },
+  'input-otp': {
+    name: 'input-otp',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Campo de código em casas (one-time password) montado sobre input-otp: InputOTP define `maxLength`, cada InputOTPSlot recebe seu `index`, InputOTPGroup agrupa as casas e InputOTPSeparator divide em blocos. Controle por `value`/`onChange`. Use pra confirmar acesso/2FA com código numérico; pra texto livre, use Input.',
+  },
+  'item': {
+    name: 'item',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Linha de conteúdo composta — mídia + título/descrição + ações numa linha clicável ou estática. Item é o container (`variant` default/outline/muted, `size` default/sm, `asChild` pra virar link/botão); componha ItemMedia (`variant` icon/image), ItemContent (ItemTitle + ItemDescription), ItemActions e, na borda, ItemHeader/ItemFooter. Empilhe vários num ItemGroup separados por ItemSeparator — o padrão pra listas de workspaces, agentes, repositórios e sessões.',
+  },
+  'kbd': {
+    name: 'kbd',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Tecla ou combinação de teclas num atalho (renderiza `<kbd>`). `Kbd` é uma tecla; envolva várias num `KbdGroup` pra formar o combo (ex.: ⌘ + K), com o conector ("+") como texto entre elas. Estiliza, não captura — o handler do atalho é seu. Aceita ícone (lucide) como filho. Dentro de um TooltipContent ganha o tom invertido automaticamente.',
+  },
+  'pagination': {
+    name: 'pagination',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Navegação entre páginas montada por composição (shadcn): Pagination › PaginationContent › PaginationItem com PaginationLink, mais PaginationPrevious/PaginationNext e PaginationEllipsis. Marque a página atual com `isActive` no PaginationLink; os links são `<a>`, então use `href` pra navegação real ou `onClick` no modo controlado. Pra rolagem infinita ou listas curtas, dispense a barra.',
+  },
+  'progress': {
+    name: 'progress',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Barra de progresso determinada (Radix): mostra o quanto de uma tarefa já foi feito num valor de 0 a 100 em `value`. Pra etapas de um processo conhecido — opus check, sincronização, cobertura. O preenchimento anima a cada mudança de `value`; sem `value` (ou null) fica vazia. Pra carga sem percentual (girando até chegar), use Spinner; pra placeholder com forma de conteúdo, Skeleton.',
+  },
+  'radio-group': {
+    name: 'radio-group',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Escolha única entre opções mutuamente exclusivas, todas visíveis ao mesmo tempo (Radix). Cada RadioGroupItem tem um `value`; o item escolhido vira o `value` do RadioGroup, controlado por `value`/`onValueChange` (ou `defaultValue` no modo não controlado). Pareie cada item com um Label. Pra poucas opções que cabem na tela; com muitas, prefira Select; pra ligar/desligar um único item, Checkbox ou Switch.',
+  },
+  'resizable': {
+    name: 'resizable',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Painéis redimensionáveis por arraste (react-resizable-panels). Compõe ResizablePanelGroup > ResizablePanel + ResizableHandle entre eles; `orientation` (horizontal/vertical) define a direção do arraste, `defaultSize`/`minSize`/`maxSize` (em %) limitam cada painel e `withHandle` desenha a pega na divisória. O grupo ocupa a altura do pai (h-full), então dê tamanho ao container. Pra alternar entre painéis sem dividir a vista, use Tabs.',
+    deprecated: { alternative: '`Split resizable` + `Pane`', since: 'próxima versão' },
+  },
+  'split': {
+    name: 'split',
+    ancestry: 'opus',
+    whenToUse:
+      'Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial/mínimo e inset. É o mecanismo espacial para sidebar, conteúdo e rail — não use AppShell/SectionShell novos.',
+  },
+  'sidebar': {
+    name: 'sidebar',
+    ancestry: 'opus',
+    whenToUse:
+      'Chrome e navegação de uma coluna lateral, encaixada onde um Split decidir. `Sidebar` possui o colapso; `PaneHeader`, `PaneContent` e `PaneFooter` estruturam qualquer pane, e `SidebarNav`/`SidebarItem` apresentam a navegação. Serve tanto a barra global quanto uma nav contextual; em Split redimensionável passe `divider={false}` para não duplicar a divisória. `SidebarHeader`, `SidebarContent` e `SidebarFooter` são aliases deprecated.',
+  },
+  'scroll-area': {
+    name: 'scroll-area',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Região rolável com barra estilizada da casa (Radix), no lugar da scrollbar do sistema. Dê altura (ou largura) ao ScrollArea via className e ponha o conteúdo dentro; a barra vertical já vem por padrão. Pra rolagem horizontal, acrescente `<ScrollBar orientation="horizontal" />` como filho. Pra a página inteira rolar, deixe o navegador cuidar — isto é pra um painel com altura fixa (lista de sessões, log, trilho de skills).',
+  },
+  'slider': {
+    name: 'slider',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Controle de valor numa faixa contínua, arrastado pelo thumb (Radix). `min`/`max`/`step` delimitam a faixa; `value`/`onValueChange` controlam (array de números — `[n]` pra um thumb, `[a, b]` pra um intervalo) ou `defaultValue` no modo não controlado. `orientation` horizontal/vertical, `disabled` esmaece. Pra um número exato digitado, use Input type=number; pra ligar/desligar, Switch.',
+  },
+  'switch': {
+    name: 'switch',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Liga/desliga imediato de uma preferência booleana (Radix). Controlado por `checked`/`onCheckedChange` (boolean) e em par com Label. Use pra estado que vale na hora (ativar agente, sincronizar); pra confirmar dentro de um formulário, prefira Checkbox.',
+  },
+  'toggle': {
+    name: 'toggle',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Botão de duas posições — liga/desliga um estado in-loco, sem sair da tela (Radix). `variant` default (fundo só quando ativo) ou outline (com borda); `size` sm/default/lg. Controlado por `pressed`/`onPressedChange` (ou `defaultPressed` no modo não controlado); ótimo pra alternar uma opção numa toolbar (negrito, quebra de linha, modo somente-leitura). Pra um conjunto de toggles mutuamente exclusivos ou um grupo de formatação, use ToggleGroup; pra um booleano com rótulo num formulário, prefira Switch ou Checkbox.',
+  },
+  'toggle-group': {
+    name: 'toggle-group',
+    ancestry: 'shadcn',
+    whenToUse:
+      'Grupo de botões de alternância (Radix). `type` single (um ativo, value: string) ou multiple (vários, value: string[]). Controlado por `value`/`onValueChange`. `variant` default|outline, `size` default|sm|lg e `spacing` descem pros itens via contexto. Pra alternar a visão de uma seção ou montar uma barra de formatação. Pra escolha única num form com rótulos longos, RadioGroup.',
+  },
+
+  'confirm': {
+    name: 'dialog',
+    ancestry: 'opus',
+    whenToUse:
+      'O trio imperativo `dialog.alert` (Promise<void>, reconhecimento obrigatório) · `dialog.confirm` (Promise<boolean>, com slot `body` pra corpo próprio) · `dialog.prompt` (Promise<string|null>, um input). Superfície imperativa como o `toast`, mas que RESPONDE — exige `<DialogHost />` no shell (sem ele LANÇA, em vez de pendurar a promise). Namespace de propósito: `window.alert/confirm/prompt` são globais do browser e um import esquecido cai no nativo; `window.dialog` não existe. Por baixo é o AlertDialog (role=alertdialog, não fecha fora); fila de uma por vez. `confirm()`/`<ConfirmHost/>` seguem como aliases. Pra excluir por contrato, ActionTrigger; pra form de verdade, ActionFormDialog; mais de duas ações, componha o AlertDialog.',
+  },
+  'action-form': {
+    name: 'action-form',
+    ancestry: 'opus',
+    whenToUse:
+      'Form de uma FormAction do Opus — submit + validação + toast encapsulados. AUTO (sem children): campos auto-detectados do Zod na ordem do contrato. COMPOSIÇÃO (children): diagrame com <ActionFormField name/> — label/widget/erro/asterisco vêm do contrato, o layout é seu. Pra ação sem form, ActionTrigger.',
+  },
+  'action-form-dialog': {
+    name: 'action-form-dialog',
+    ancestry: 'opus',
+    whenToUse:
+      'ActionForm dentro de um Dialog (form em modal) — controla open/onOpenChange + title; fecha no sucesso. Aceita children (modo composição) como o ActionForm. Pra form inline numa página, use ActionForm direto.',
+  },
+  'action-form-card': {
+    name: 'action-form-card',
+    ancestry: 'opus',
+    whenToUse:
+      'O ActionForm dentro de um Card do Opus (header/conteúdo/rodapé) — pra estruturar uma seção da página como painel. Segue o padrão do Card (sem divisor nem faixa de modal, com o respiro do Card). Pra form em overlay, ActionFormDialog; pra form cru sem chrome, ActionForm direto.',
+  },
+  'action-list': {
+    name: 'action-list',
+    ancestry: 'opus',
+    whenToUse:
+      'A listagem padronizada de uma ListAction — DECLARATIVA pelo contrato: `columns` (tipos, sortable, hidden) vira a tabela (com column picker); `filters` vira a toolbar (inline + `advanced` em modal + chips); `periods` vira o controle de período (presets + Personalizado com calendário → from/to); `text` liga a busca (q, à direita); sort escreve `sort: chave:dir`. `views` = renderers alternativos (board/galeria/lista) com segment — mesma fonte e filtros. Paginação server-driven (limit/page → total no rodapé + pager) e `batch` = multi-seleção com `can` (elegibilidade por item governa checkbox, selecionar-todos e o run). Células via `cells`; URL sync com listParamsToState/listStateToParams. Pra detalhe de 1 recurso, ActionView.',
+  },
+  'action-trigger': {
+    name: 'action-trigger',
+    ancestry: 'opus',
+    whenToUse:
+      'Botão que dispara uma SimpleAction do Opus (sem form): assign, close, archive, excluir. Loading + toast + confirmação (do `action.confirm` do contrato, ou pela prop). `icon` faz o botão virar icon-only com tooltip — a ação que mora NO item (linha, card), sem vazar o clique pro item; `itemLabel` nomeia o alvo na pergunta. Erro de NEGÓCIO (conflict/validation/not_found) mostra a frase do servidor; o resto cai no rótulo do contrato, pra não vazar texto técnico. ATENÇÃO: contrato sem `confirm` dispara DIRETO — a confirmação de ação destrutiva se declara no contrato. Absorveu o DeleteButton (7.0.0). Pra mutação com campos, ActionForm.',
+  },
+  'action-view': {
+    name: 'action-view',
+    ancestry: 'opus',
+    whenToUse:
+      'Carrega e exibe 1 recurso de uma ViewAction do Opus — loading/error/empty encapsulados; o layout vem por children `(data, refetch) => nó` (render segue como alias). Pra listagem, ActionList.',
+  },
+  'page': {
+    name: 'page',
+    ancestry: 'opus',
+    whenToUse:
+      'O esqueleto de página do back-office: <main> + container de largura cheia (className="max-w-5xl" estreita e centra) + header com título, descrição e ação à direita (em geral o criar). Presentacional (a página agrega N fontes); o action-driven mora dentro. Pra listagem em modal, ActionListDialog.',
+  },
+  'app-shell': {
+    name: 'app-shell',
+    ancestry: 'opus',
+    whenToUse:
+      'O chrome da aplicação: sidebar de navegação (header + nav rolável + rodapé ancorado) + conteúdo, com rail opcional à direita (chat de agente, inspetor) em painéis redimensionáveis. É o quadro — o que vai em cada slot é do app. Pro esqueleto de UMA página (título, descrição, ação), Page. Chrome `flush` opcional (full-bleed, filete à esquerda) com <AppShellBar> — a faixa h-12 border-b usada na sidebar (marca) e no topo do conteúdo pra linha do header atravessar a tela. Sidebar recolhível com `collapsible` (opt-in): o shell controla a largura e publica `data-collapsed` no aside; o rótulo some por CSS (`group-data-[collapsed=true]/sidebar:hidden`) porque o nav é do app. O botão é o <AppShellTrigger />, posicionado pelo consumidor; `useAppShell()` dá o estado em JS.',
+    deprecated: { alternative: '`Split` + `Pane` + `Sidebar`', since: 'próxima versão' },
+  },
+  'section-shell': {
+    name: 'section-shell',
+    ancestry: 'opus',
+    whenToUse:
+      'Uma SEÇÃO com navegação própria — o nível entre AppShell (o app) e Page (uma tela): nav w-56 com filete + painel, pras telas irmãs de Configurações, Relatórios ou doc. Use quando a seção é visitada raro e navegada por dentro quando visitada (não vale queimar item na sidebar do app), ou quando a lista é dinâmica demais pra um nav estático. Pra facetas do MESMO objeto, Tabs. Controlado (activeId + onSelect): o roteamento é do app. Grupos aceitam `items` e/ou `subgroups` (o 3º nível, ex.: sub-pasta na doc). O painel remonta quando o `activeId` muda — é o que zera o scroll; `scrollResetKey` sobrescreve a chave nos dois sentidos: constante = nunca remonta (preserva o scroll), mais fina que o activeId = remonta também dentro da mesma tela.',
+    deprecated: { alternative: '`Split` + `Pane` + `Sidebar`', since: 'próxima versão' },
+  },
+  'router': {
+    name: 'router',
+    ancestry: 'opus',
+    whenToUse:
+      'Roteamento history-based sem dependência: `usePathname`/`useSegments`/`useSearchParams` (leitura reativa da URL) + `navigate(path, { replace? })`. O pathname É o estado, então deep-link, reload e o botão voltar funcionam sem um segundo lugar guardando "onde estou". Escopo PEQUENO de propósito: não há tabela de rotas, params tipados nem data loader — quem decide o que renderizar é o app, com if/switch sobre os segmentos. Precisa casar padrão (`/users/:id/posts/:postId`) ou carregar dado por rota? O caso pede uma biblioteca de rotas, não isto. `navigate` é no-op em destino igual (senão o "voltar" não sai do lugar) e usa useSyncExternalStore (useState sofre tearing em concurrent).',
+  },
+  'data-state': {
+    name: 'data-state',
+    ancestry: 'opus',
+    whenToUse:
+      'O estado "carregando" (ANTES do conteúdo): orquestra erro/carregando/vazio/conteúdo de uma carga assíncrona num só lugar — Spinner centralizado no loading, texto no vazio, aviso calmo no erro. Pra "processando" (ação em andamento DEPOIS do clique), use o `busy` do Button. Pra placeholder com forma, Skeleton.',
+  },
+  'action-list-dialog': {
+    name: 'action-list-dialog',
+    ancestry: 'opus',
+    whenToUse:
+      'Uma ListAction em modal: lista query-backed (busca no mount, refaz via invalidates) + chrome padronizado (título/descrição, toolbar com nota "N no total" derivada + ação de criar). Children (items, refetch) diagrama os itens. `loading` agrega a query irmã; `empty` sobrepõe o vazio derivado (ex.: form inline aberto). Pra tabela numa página, ActionList; pra form em modal, ActionFormDialog.',
+  },
+} as const satisfies Record<string, ComponentMeta>
+
+export type ComponentMetaKey = keyof typeof componentMeta