@softize/opus 13.0.0 → 13.1.0

package/src/ui/docs/content/sidebar.md

@@ -134,8 +134,9 @@ render(
 Esse é o padrão usado pelo `DocBrowser`: seções são rótulos, grupos nomeados são nós expansíveis e
 páginas são folhas. Um grupo começa aberto e volta a abrir quando contém a página ativa.
 
-Use `ShellNav` para uma navegação plana que precisa de cabeçalho próprio e grupos ancorados no
-rodapé. Ele gerencia a rolagem internamente e se adapta quando estiver dentro de uma `Sidebar`
+`ShellNav` continua disponível para uma navegação plana com cabeçalho próprio e grupos ancorados no
+rodapé, mas está descontinuado: código novo usa `SidebarNav`, que cobre o mesmo caso integrado à
+`Sidebar`. Ele gerencia a rolagem internamente e se adapta quando estiver dentro de uma `Sidebar`
 recolhida.
 
 ```tsx
@@ -156,6 +157,10 @@ recolhida.
 somente os ícones e expõem os rótulos em tooltips. Por isso, todo destino que aparece no modo
 recolhido precisa de um ícone reconhecível e de um `label` completo.
 
+O slot de ícone do `SidebarItem` ocupa `1rem` nos dois estados e normaliza SVGs para essa medida.
+O consumidor escolhe o símbolo e sua cor sem precisar repetir largura ou altura em ícones SVG.
+Outros tipos de `ReactNode` continuam responsáveis pelas próprias dimensões.
+
 ```tsx preview
 const [collapsed, setCollapsed] = useState(false)
 
@@ -216,12 +221,13 @@ estrutura evita botões aninhados e permite que cada controle receba foco de for
     }
     onClick={() => {}}
   />
-  <SidebarItem
-    label="Criar workspace"
-    icon={<FilePlus2 />}
-    className="pl-6"
-    onClick={() => {}}
-  />
+  <SidebarTreeGroup>
+    <SidebarItem
+      label="Criar workspace"
+      icon={<FilePlus2 />}
+      onClick={() => {}}
+    />
+  </SidebarTreeGroup>
 </div>
 ```
 

package/src/ui/docs/content/skeleton.md

@@ -33,3 +33,9 @@ O esqueleto reproduz o layout final do card — título, descrição, conteúdo
   </CardFooter>
 </Card>
 ```
+
+## Propriedades de Skeleton
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Dá forma ao placeholder (`h-4 w-40`, `size-10 rounded-full`); o componente só traz o pulso e o fundo. |

package/src/ui/docs/content/split.md

@@ -74,3 +74,24 @@ const defaultLayout = readLayout('workspace-layout')
 ```
 
 Em aplicações renderizadas no servidor, leia o armazenamento somente no cliente. `onLayoutChanged` também permite usar `sessionStorage` ou uma camada própria quando o layout precisa acompanhar outro escopo.
+
+## Propriedades de Split
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Sentido em que os panes se alinham. |
+| `resizable` | `boolean` | `false` | Cada fronteira ganha um separador acessível e arrastável. |
+| `handle` | `boolean` | `false` | Mostra a alça visual no separador. |
+| `id` | `string` | | Identidade estável do grupo redimensionável. |
+| `defaultLayout` | `Record<string, number>` | | Layout percentual restaurado, indexado pelos ids dos panes. |
+| `onLayoutChanged` | `(layout, { isUserInteraction }) => void` | | Chamado ao concluir uma mudança de layout; persista onde fizer sentido. |
+
+## Propriedades de Pane
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `id` | `string` | | Identidade estável usada pelo layout redimensionável e persistido. |
+| `initialSize` | `number \| string` | | Tamanho inicial; número é porcentagem, string aceita `%`, `rem`, `em`, `vh`, `vw` e `px`. |
+| `minSize` / `maxSize` | `number \| string` | | Limites quando o split é redimensionável. |
+| `grow` | `boolean` | `false` | Ocupa o espaço remanescente no layout simples. |
+| `inset` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Respiro interno; `none` para chrome, navegação ou conteúdo com inset próprio. |

package/src/ui/docs/content/textarea.md

@@ -29,3 +29,10 @@ Associe `htmlFor` no `Label` ao `id` do campo para manter o rótulo acessível.
 <Textarea aria-invalid placeholder="Conte o contexto da mudança." />
 <Textarea disabled defaultValue="Sessão encerrada — o brief não pode mais ser editado." />
 ```
+
+## Propriedades de Textarea
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `…props` | `ComponentProps<'textarea'>` | | Todos os atributos nativos (`value`, `defaultValue`, `rows`, `disabled`, `aria-invalid`…). A altura acompanha o conteúdo (`field-sizing-content`) a partir de `min-h-16`. |
+| `className` | `string` | | Compõe sobre o estilo padrão. |

package/src/ui/docs/content/tokens.md

@@ -1,8 +1,8 @@
 ---
-title: Tokens & Tema
+title: Tokens e tema
 ---
 
-# Tokens & Tema
+# Tokens e tema
 
 O tema canônico vive no Opus (`theme.css`): tokens com a cor inteira na var, mapeados para o
 Tailwind via `@theme inline`. Os swatches abaixo leem as vars **ao vivo** — troque o tema do app
@@ -73,8 +73,8 @@ render(
 
 ## Linhas e foco
 
-> Bordas e o anel de foco também são tokens — nada de cinza hardcoded. A aresta de superfície
-> elevada (`--edge`) mora na seção Elevação por papel.
+> Bordas e o anel de foco também são tokens — nada de cinza hardcoded. Superfícies elevadas usam
+> a mesma `border-border`; o que muda entre elas é a sombra, descrita na seção Escala de elevação.
 
 ```tsx preview
 const LINES = [

package/src/ui/docs/content/truncate.md

@@ -60,3 +60,11 @@ quando o texto completo ainda não oferecer contexto suficiente.
 
 Requer `TooltipProvider` na raiz (o esqueleto do `opus create` já monta). Largura vem do
 container ou de `className` (`max-w-*`) — o span é `block truncate`.
+
+## Propriedades de Truncate
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `tooltip` | `ReactNode` | os próprios `children` | Conteúdo da dica quando o texto transborda. |
+| `fade` | `boolean` | `false` | Sinaliza o corte esmaecendo o fim da linha, no lugar das reticências. |
+| `className` | `string` | | Largura (`max-w-*`) e demais ajustes; o span é `block truncate`. |

package/src/ui/docs/content/ui.md

@@ -30,6 +30,20 @@ import { Button, Dialog, useAction } from '@softize/opus/ui/react'
 @source '../node_modules/@softize/opus/src/ui';
 ```
 
+## Prebundle do Vite
+
+A entrada `@softize/opus/ui/react` é um `.tsx`, e o prebundle do Vite só considera entradas
+`.js`/`.ts`. Sem ajuste, o dev server avisa `Cannot optimize dependency` e serve a árvore do Opus
+arquivo a arquivo na carga fria. Há duas saídas, cada uma com um custo conhecido:
+
+- `optimizeDeps.include: ['@softize/opus/ui/react']` com `extensions: ['.tsx']` pré-empacota o
+  Opus, mas pode duplicar `@tanstack/react-query` quando o app também o importa direto (dois
+  `QueryClient`, hooks fora do provider).
+- `optimizeDeps.exclude: ['@softize/opus/ui/react']` evita a duplicação e infla a carga fria.
+
+Escolha pelo sintoma que aparece no seu app e registre a decisão no `vite.config.ts`. A saída
+definitiva (entrada `.ts` no pacote) está no radar do Opus.
+
 ## Origem e anti-drift
 
 > Cada componente declara de onde veio — e a regra de sincronização vem junto.

package/src/ui/docs/doc-client.tsx

@@ -8,7 +8,7 @@ import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { z } from 'zod'
 import { attachLogicalType, defineContract, error } from '../../core/index.ts'
 import type { ActionDef, ActionResult, ClientAdapter, LogicalTypeMeta, Paginated } from '../../core/index.ts'
-import { TbdlibProvider } from '../react.tsx'
+import { OpusProvider } from '../react.tsx'
 
 // — Dados enlatados (domínio da casa) —
 export interface DocBrowserWorkspace {
@@ -37,7 +37,7 @@ export const docWorkspaceStatus: LogicalTypeMeta = {
     keys: [...STATUS],
     entries: {
       active: { label: 'Ativo', context: 'success', description: 'Agentes em operação para o cliente.' },
-      onboarding: { label: 'Onboarding', context: 'warning' },
+      onboarding: { label: 'Em integração', context: 'warning' },
       paused: { label: 'Pausado' },
     },
     presentation: 'status',
@@ -59,7 +59,7 @@ export const docWorkspaceCreate = defineContract({
   }),
   output: z.object({ id: z.string() }),
   fields: {
-    name: { label: 'Nome', placeholder: 'Ex.: Empresa X', hint: 'Digite "Softize" pra ver o erro de servidor.' },
+    name: { label: 'Nome', placeholder: 'Ex.: Empresa X', help: 'Digite “Softize” para ver o erro de servidor.' },
     status: { label: 'Status' },
     contact: { label: 'Contato', placeholder: 'email@cliente.com' },
     notes: { label: 'Observações', placeholder: 'Contexto do onboarding…' },
@@ -100,7 +100,7 @@ export const docWorkspaceList = defineContract({
         kind: 'static',
         items: [
           { value: 'active', label: 'Ativo' },
-          { value: 'onboarding', label: 'Onboarding' },
+          { value: 'onboarding', label: 'Em integração' },
           { value: 'paused', label: 'Pausado' },
         ],
       },
@@ -225,7 +225,7 @@ const queryClient = new QueryClient()
 export function DocBrowserActionProvider({ children }: { children: React.ReactNode }): React.ReactElement {
   return (
     <QueryClientProvider client={queryClient}>
-      <TbdlibProvider client={docClient}>{children}</TbdlibProvider>
+      <OpusProvider client={docClient}>{children}</OpusProvider>
     </QueryClientProvider>
   )
 }

package/src/ui/docs/doc.tsx

@@ -18,6 +18,10 @@ import {
   TableHead,
   TableHeader,
   TableRow,
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
   cn,
 } from '../react.tsx'
 
@@ -72,8 +76,8 @@ export function DocPage({
           </p>
         )}
         {meta?.deprecated !== undefined && (
-          <div className="max-w-2xl rounded-lg border border-amber-500/30 bg-amber-500/10 px-3 py-2 text-sm leading-relaxed text-foreground">
-            <span className="font-medium">Deprecated{meta.deprecated.since !== undefined ? ` desde ${meta.deprecated.since}` : ''}.</span>{' '}
+          <div className="max-w-2xl rounded-lg border border-context-warning-border bg-context-warning-subtle px-3 py-2 text-sm leading-relaxed text-foreground">
+            <span className="font-medium">Descontinuado{meta.deprecated.since !== undefined ? ` desde ${meta.deprecated.since}` : ''}.</span>{' '}
             Use <InlineMd text={meta.deprecated.alternative} />.
           </div>
         )}
@@ -211,17 +215,25 @@ export function CodeBlock({
     // overflow-hidden: os filhos (fade incluso) são CLIPADOS no raio do contêiner — sem
     // isso, o overlay desenhava um segundo arco nos cantos (a "borda dobrada").
     <div className={cn('group relative overflow-hidden rounded-lg border border-border bg-muted/40', className)}>
-      <button
-        onClick={() => {
-          void navigator.clipboard.writeText(clean)
-          setCopied(true)
-          setTimeout(() => setCopied(false), 1500)
-        }}
-        title="Copiar código"
-        className="absolute right-2 top-2 z-20 rounded-md p-1.5 text-muted-foreground opacity-0 transition-opacity hover:bg-muted hover:text-foreground group-hover:opacity-100"
-      >
-        {copied ? <Check className="h-3.5 w-3.5" /> : <Copy className="h-3.5 w-3.5" />}
-      </button>
+      {/* Provider próprio: a doc também é montada fora do shell do app (standalone, testes). */}
+      <TooltipProvider delayDuration={200}>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <button
+            onClick={() => {
+              void navigator.clipboard.writeText(clean)
+              setCopied(true)
+              setTimeout(() => setCopied(false), 1500)
+            }}
+            aria-label="Copiar código"
+            className="absolute right-2 top-2 z-20 rounded-md p-1.5 text-muted-foreground opacity-0 transition-opacity hover:bg-muted hover:text-foreground group-hover:opacity-100 focus-visible:opacity-100"
+          >
+            {copied ? <Check className="h-3.5 w-3.5" /> : <Copy className="h-3.5 w-3.5" />}
+          </button>
+        </TooltipTrigger>
+        <TooltipContent>{copied ? 'Copiado' : 'Copiar código'}</TooltipContent>
+      </Tooltip>
+      </TooltipProvider>
 
       <div ref={contentRef} className={cn('relative', collapsed && 'max-h-44 overflow-hidden')}>
         <Highlight code={clean} language={lang} theme={codeTheme}>
@@ -279,7 +291,7 @@ export function PropsTable({ rows }: { rows: PropRow[] }): React.ReactElement {
       <Table>
         <TableHeader>
           <TableRow>
-            <TableHead className="w-[18%]">Prop</TableHead>
+            <TableHead className="w-[18%]">Propriedade</TableHead>
             <TableHead className="w-[30%]">Tipo</TableHead>
             <TableHead className="w-[12%]">Padrão</TableHead>
             <TableHead>Descrição</TableHead>

package/src/ui/docs/registry.tsx

@@ -221,13 +221,13 @@ export const PROTOCOL_SECTIONS: DocSection[] = [
         pages: [
           {
             slug: "getting-started",
-            title: "Getting started",
+            title: "Primeiros passos",
             render: doc(gettingStartedMd),
           },
           { slug: "cycle", title: "Evolução contínua", render: doc(cycleMd) },
           {
             slug: "upgrading",
-            title: "Atualizar a base",
+            title: "Atualizar o Opus",
             render: doc(upgradingMd),
           },
         ],
@@ -337,7 +337,7 @@ export const UI_SECTIONS: DocSection[] = [
         pages: [
           {
             slug: "como-consumir",
-            title: "Getting started",
+            title: "Como consumir",
             render: doc(uiMd),
           },
         ],
@@ -349,10 +349,10 @@ export const UI_SECTIONS: DocSection[] = [
     groups: [
       {
         pages: [
-          { slug: "tokens", title: "Tokens & Tema", render: doc(tokensMd) },
+          { slug: "tokens", title: "Tokens e tema", render: doc(tokensMd) },
           {
             slug: "semantic-context",
-            title: "Contexto & Variante",
+            title: "Contexto e variante",
             render: doc(semanticContextMd),
           },
           {

package/src/ui/docs/standalone.tsx

@@ -66,7 +66,7 @@ export interface MountDocsOptions {
   basePath?: string
   /** Elemento alvo. Default: `#root` (cria um se faltar). */
   el?: HTMLElement
-  /** Título no topo. Default `Components` (o site-base passa `opus`). */
+  /** Título no topo. Default `Componentes` (o site-base passa `opus`). */
   title?: string
   /** Legenda ao lado do título. Default `a verdade visual deste projeto`. */
   subtitle?: string
@@ -78,7 +78,7 @@ export interface MountDocsOptions {
 /** Monta a doc na página. Chamado pelo entry do plugin opusDocs (depois de importar o CSS do app). */
 export function mountDocs(options: MountDocsOptions = {}): void {
   const basePath = options.basePath ?? '/__docs'
-  const title = options.title ?? 'Components'
+  const title = options.title ?? 'Componentes'
   const subtitle = options.subtitle ?? 'a verdade visual deste projeto'
   // Tema persistido pela própria doc; senão, a preferência do sistema.
   let saved: string | null = null

package/src/ui/drivers/react.tsx

@@ -2,11 +2,11 @@
  * @softize/opus/ui/react — React driver
  *
  * Hooks + Provider pra invocar actions client-side.
- *   - `TbdlibProvider` — injeta ClientAdapter no contexto
+ *   - `OpusProvider` — injeta ClientAdapter no contexto (`TbdlibProvider` é alias em retirada)
  *   - `useAction(action)` — invoca actions simple/form/view
  *   - `useLookupAction(action)` — variante pra search (output Paginated)
  *
- * Compatível com React 18 e 19. Não dona estado global de cache —
+ * Requer React 19 (peer `react@^19`). Não dona estado global de cache —
  * cada hook mantém o seu (suficiente pra v0). Integração com
  * TanStack Query fica em `@softize/opus/client/tanstack` no futuro.
  */
@@ -58,14 +58,14 @@ export interface DictLike {
   options(): Array<{ value: string; label: string }>
 }
 
-interface TbdlibContextValue {
+interface OpusContextValue {
   client: ClientAdapter
   dicts: Record<string, DictLike>
 }
 
-const TbdlibContext = createContext<TbdlibContextValue | null>(null)
+const OpusContext = createContext<OpusContextValue | null>(null)
 
-export interface TbdlibProviderProps {
+export interface OpusProviderProps {
   client: ClientAdapter
   /** Dicionários por ref — resolvem `options: { kind: 'dictionary', ref }` de
    *  filters/fields (ActionList/ActionForm). Campo de dict sem registro aqui ainda
@@ -74,20 +74,25 @@ export interface TbdlibProviderProps {
   children: ReactNode
 }
 
-export function TbdlibProvider({
+export function OpusProvider({
   client,
   dicts,
   children,
-}: TbdlibProviderProps): ReactNode {
-  const value = useMemo<TbdlibContextValue>(() => ({ client, dicts: dicts ?? {} }), [client, dicts])
-  return <TbdlibContext.Provider value={value}>{children}</TbdlibContext.Provider>
+}: OpusProviderProps): ReactNode {
+  const value = useMemo<OpusContextValue>(() => ({ client, dicts: dicts ?? {} }), [client, dicts])
+  return <OpusContext.Provider value={value}>{children}</OpusContext.Provider>
 }
 
+/** @deprecated Renomeado para `OpusProvider`; o alias segue até a próxima série. */
+export const TbdlibProvider = OpusProvider
+/** @deprecated Use `OpusProviderProps`. */
+export type TbdlibProviderProps = OpusProviderProps
+
 function useClient(): ClientAdapter {
-  const ctx = useContext(TbdlibContext)
+  const ctx = useContext(OpusContext)
   if (ctx === null) {
     throw new Error(
-      'useAction/useLookupAction must be used inside <TbdlibProvider>',
+      'useAction/useLookupAction precisam estar dentro de <OpusProvider>.',
     )
   }
   return ctx.client
@@ -98,7 +103,7 @@ const NO_DICTS: Record<string, DictLike> = {}
 /** Dicts do provider. Default {} — inclusive fora do provider: o resolvedor cai
  *  nos fallbacks (estáticas do spec, meta do `t.dict`) sem exigir registry. */
 export function useDicts(): Record<string, DictLike> {
-  return useContext(TbdlibContext)?.dicts ?? NO_DICTS
+  return useContext(OpusContext)?.dicts ?? NO_DICTS
 }
 
 // =============================================================================

package/src/ui/lib/action-errors.ts

@@ -0,0 +1,45 @@
+/**
+ * O que a pessoa pode ler quando uma action falha.
+ *
+ * Categorias cuja frase do SERVIDOR vence o rótulo do contrato: "Este agente tem 3 conversas —
+ * desabilite em vez de excluir" é acionável; "Falha ao excluir" não. É ALLOWLIST de propósito —
+ * erro inesperado carrega texto técnico cru (uma violação de FK viraria
+ * `violates foreign key constraint "user_unit_id_fkey"` para quem só clicou no botão), então
+ * categoria desconhecida cai no texto genérico, o lado seguro de errar. `authorization` e
+ * `authentication` entram porque o runtime já responde em pt-BR ("Acesso negado",
+ * "Autenticação necessária") e a pessoa precisa saber que o problema é de permissão, não de rede.
+ */
+export const BUSINESS_ERRORS: readonly string[] = [
+  'conflict',
+  'validation',
+  'not_found',
+  'authorization',
+  'authentication',
+]
+
+/** Erro que tentar de novo não resolve: falta de permissão ou de sessão. */
+export function isRetryable(err: HumanizableError): boolean {
+  return err.category !== 'authorization' && err.category !== 'authentication'
+}
+
+export interface HumanizableError {
+  category?: string
+  message?: string
+}
+
+/** A frase do servidor é de negócio (allowlist) e tem conteúdo. */
+export function isBusinessError(err: HumanizableError): boolean {
+  return (
+    err.category !== undefined &&
+    BUSINESS_ERRORS.includes(err.category) &&
+    (err.message ?? '').trim() !== ''
+  )
+}
+
+/**
+ * Texto para a pessoa: a frase do servidor quando ela é de negócio; `fallback` no resto. Código
+ * técnico (`internal.unhandled`, `db.constraint`) nunca chega à tela por aqui.
+ */
+export function humanizeActionError(err: HumanizableError, fallback: string): string {
+  return isBusinessError(err) ? (err.message as string).trim() : fallback
+}

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

@@ -10,28 +10,55 @@
  */
 import { z } from 'zod'
 
+const INVALID = 'Valor inválido.'
+
+function options(count: number | bigint): string {
+  return Number(count) === 1 ? '1 opção' : `${count} opções`
+}
+
 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.' }
+      return { message: INVALID }
     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}.` }
+      if (issue.type === 'array') return { message: `Selecione pelo menos ${options(issue.minimum)}.` }
+      if (issue.type === 'date') return { message: 'Data anterior ao permitido.' }
       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}.` }
+      if (issue.type === 'array') return { message: `Selecione no máximo ${options(issue.maximum)}.` }
+      if (issue.type === 'date') return { message: 'Data posterior ao permitido.' }
       return { message: `Valor máximo: ${issue.maximum}.` }
     case z.ZodIssueCode.invalid_string:
-      if (issue.validation === 'email') return { message: 'Email inválido.' }
+      if (issue.validation === 'email') return { message: 'E-mail 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:
+    case z.ZodIssueCode.invalid_union_discriminator:
       return { message: 'Escolha uma das opções.' }
+    case z.ZodIssueCode.invalid_literal:
+    case z.ZodIssueCode.invalid_union:
+    case z.ZodIssueCode.invalid_intersection_types:
+    case z.ZodIssueCode.invalid_arguments:
+    case z.ZodIssueCode.invalid_return_type:
+    case z.ZodIssueCode.custom:
+      return { message: INVALID }
+    case z.ZodIssueCode.invalid_date:
+      return { message: 'Data inválida.' }
+    case z.ZodIssueCode.not_multiple_of:
+      return { message: `Use múltiplos de ${issue.multipleOf}.` }
+    case z.ZodIssueCode.unrecognized_keys:
+      return {
+        message:
+          issue.keys.length === 1
+            ? `Campo não reconhecido: ${issue.keys[0]}.`
+            : `Campos não reconhecidos: ${issue.keys.join(', ')}.`,
+      }
     default:
       return { message: ctx.defaultError }
   }

package/src/ui/meta.ts

@@ -355,10 +355,10 @@ export const componentMeta = {
   },
 
   confirm: {
-    name: "dialog",
+    name: "confirm",
     ancestry: "opus",
     whenToUse:
-      "Solicite reconhecimento, confirmação ou uma resposta curta por uma API imperativa. Monte DialogHost uma vez no shell e use `dialog.alert`, `dialog.confirm` ou `dialog.prompt`; as solicitações são exibidas uma por vez. Para ações declaradas em contrato, prefira ActionTrigger; para formulários, use ActionFormDialog.",
+      "Solicite reconhecimento, confirmação, uma escolha ou uma resposta curta por uma API imperativa. Monte DialogHost uma vez no shell e use `dialog.alert`, `dialog.confirm`, `dialog.choose` ou `dialog.prompt`; as solicitações são exibidas uma por vez. Para ações declaradas em contrato, prefira ActionTrigger; para formulários, use ActionFormDialog.",
   },
   "action-form": {
     name: "action-form",
@@ -400,7 +400,7 @@ export const componentMeta = {
     name: "page",
     ancestry: "opus",
     whenToUse:
-      "O esqueleto de página do back-office: <main> + container centralizado com teto padrão de 80rem (`max-w-7xl`). O shorthand com title, description, count e actions cria a mesma anatomia de PageHeader(PageTitle/PageDescription/PageMeta/PageActions) + PageBody disponível na forma explícita. `className` substitui o teto quando a composição pede outra largura. Quando todo o body estiver carregando, falhar ou estiver vazio, use PageState. Para listagem em modal, ActionListDialog.",
+      "O esqueleto de página do back-office: <main> + container centralizado com teto padrão de 80rem (`max-w-7xl`). O shorthand com title, description, count e actions cria a mesma anatomia de PageHeader(PageTitle/PageDescription/PageMeta/PageActions) + PageBody disponível na forma explícita. PageActionsTarget projeta as ações no chrome reservado pelo shell sem retirar sua declaração da Page. `className` substitui o teto quando a composição pede outra largura. Quando todo o body estiver carregando, falhar ou estiver vazio, use PageState. Para listagem em modal, ActionListDialog.",
   },
   router: {
     name: "router",

package/src/ui/react.tsx

@@ -426,6 +426,7 @@ export {
   PageDescription,
   PageMeta,
   PageActions,
+  PageActionsTarget,
   PageBody,
 } from "./components/patterns/page.tsx";
 export type { PageProps } from "./components/patterns/page.tsx";
@@ -475,6 +476,7 @@ export type {
   DockProps,
   DockActionProps,
   SurfaceStatusProps,
+  SurfaceStatusContext,
 } from "./components/patterns/dock.tsx";
 
 // Barra lateral composicional: header/conteúdo/footer e navegação, sem possuir o layout.

package/src/ui/theme.css

@@ -59,6 +59,9 @@
   --context-primary-subtle: color-mix(in oklab, var(--primary) 8%, transparent);
   --context-primary-emphasis: var(--foreground);
   --context-primary-border: color-mix(in oklab, var(--primary) 25%, transparent);
+  /* info/success/warning: base, foreground, subtle e border (12 tokens) valem nos dois temas
+     de propósito — são cores saturadas com alpha, que já se assentam sobre qualquer canvas;
+     só `*-emphasis` (texto sobre o popover) precisa clarear no escuro, e é redefinido em .dark. */
   --context-info: hsl(217 91% 60%);
   --context-info-foreground: hsl(0 0% 100%);
   --context-info-subtle: hsl(217 91% 60% / 0.1);
@@ -82,7 +85,7 @@
   --border: hsl(0 0% 92.5%);
   --input: hsl(0 0% 92.5%);
   /* Ring de foco LEVE (pedido da casa): aro sutil, não um halo. Com ring-[0.1875rem] + /50,
-     ~86% encosta na borda (89.8%) — um sussurro de foco. */
+     ~86% encosta na borda (92.5%) — um sussurro de foco. */
   --ring: hsl(0 0% 86%);
   --radius: 0.75rem;
 }
@@ -107,10 +110,9 @@
   --accent-foreground: hsl(0 0% 98%);
   /* Vermelho CLARO no escuro (era 30.6% — calibrado só pra FUNDO, com texto branco).
      Como o menu/alert/field/erros usam `text-destructive` como FOREGROUND, o valor
-     escuro dava ~1,7:1 sobre o popover — ilegível. ~58% passa o AA como texto e é o
-     que o success já fazia (dark:text-emerald-400 pula pro tom claro). Fundo sólido
-     (Button/Badge/toast destructive) fica mais vivo — igual ao light, com branco por
-     cima, como o shadcn novo. */
+     escuro dava ~1,7:1 sobre o popover — ilegível. ~58% passa o AA como texto, o mesmo
+     salto que os `*-emphasis` abaixo dão para o tom claro. Fundo sólido (Button/Badge/toast
+     danger) fica mais vivo — igual ao light, com branco por cima, como o shadcn novo. */
   --destructive: hsl(0 72% 58%);
   --destructive-foreground: hsl(0 0% 98%);
   --context-info-emphasis: hsl(213 94% 68%);
@@ -272,8 +274,8 @@
   }
   :root::-webkit-scrollbar-thumb,
   :root *::-webkit-scrollbar-thumb {
-    border: 2px solid transparent;
-    border-radius: 9999px;
+    border: 2px solid transparent; /* px: hairline dupla do thumb — não deve escalar com a fonte. */
+    border-radius: 9999px; /* px: raio efetivamente infinito do scrollbar nativo. */
     background-color: transparent;
     background-clip: content-box;
   }
@@ -322,7 +324,7 @@
 
 /* Code block = superfície da casa (borda + bg muted) — só o <pre> CRU do prose. */
 .prose :where(pre):not(:where([class~='not-prose'], [class~='not-prose'] *)) {
-  border: 1px solid var(--border);
+  border: 1px solid var(--border); /* px: hairline do bloco de código — 1 pixel físico, não escala. */
 }
 
 /* O Sonner reserva por padrão apenas 1rem para a mídia. A moldura semântica do