@softize/opus 13.0.0 → 14.0.0

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
  *   - `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,20 @@ 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>
 }
 
 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 +98,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

@@ -69,7 +69,7 @@ export const componentMeta = {
     name: "button",
     ancestry: "shadcn",
     whenToUse:
-      "Inicie uma ação com um controle clicável. Use `context` para o significado, `variant` para o tratamento visual e `size` para a escala; `busy` comunica o andamento e impede um novo acionamento. Para ações relacionadas, use ButtonGroup.",
+      "Inicie uma ação com um controle clicável. Use `context` para o significado, `variant` para o tratamento visual e `size` para a escala compartilhada (`xs`…`lg` e os quadrados `icon-*`); `icon` recebe um nó e `busy` comunica o andamento e impede um novo acionamento. Para ações relacionadas, use ButtonGroup.",
   },
   card: {
     name: "card",
@@ -117,7 +117,7 @@ export const componentMeta = {
     name: "content-header",
     ancestry: "opus",
     whenToUse:
-      "Estruture o cabeçalho de um Content com título, descrição, metadados e ações. No caso comum, declare esses valores diretamente em Content; componha ContentHeader apenas quando precisar controlar a anatomia.",
+      "Estruture o cabeçalho de um Content com título, contador, descrição e ações — a mesma anatomia de PageHeader. No caso comum, declare esses valores diretamente em Content; componha ContentHeader apenas quando precisar controlar a anatomia.",
   },
   copyable: {
     name: "copyable",
@@ -183,7 +183,7 @@ export const componentMeta = {
     name: "spinner",
     ancestry: "shadcn",
     whenToUse:
-      "Indique uma espera sem progresso determinado, como uma ação ou consulta em andamento. Para reservar a forma do conteúdo, use Skeleton.",
+      "Indique uma espera sem progresso determinado, como uma ação ou consulta em andamento. O ícone é decorativo: o contêiner (`role=\"status\"`) ou o texto ao lado nomeia a espera. Para reservar a forma do conteúdo, use Skeleton.",
   },
   table: {
     name: "table",
@@ -327,7 +327,7 @@ export const componentMeta = {
     name: "sidebar",
     ancestry: "opus",
     whenToUse:
-      "Organize navegação global ou contextual em uma coluna lateral. Split e Pane definem posição e largura; Sidebar fornece a superfície e o colapso, enquanto PaneHeader, PaneBody e PaneFooter estruturam as regiões fixa e rolável. Use SidebarNav para grupos planos, componha árvores com SidebarItem e SidebarTreeGroup e use ShellNav quando a navegação precisar de cabeçalho e rodapé próprios.",
+      "Organize navegação global ou contextual em uma coluna lateral. Split e Pane definem posição e largura; Sidebar fornece a superfície e o colapso, enquanto PaneHeader, PaneBody e PaneFooter estruturam as regiões fixa e rolável. Use SidebarNav para grupos planos e componha árvores com SidebarItem e SidebarTreeGroup; cabeçalho e rodapé próprios ficam em PaneHeader e PaneFooter.",
   },
   "scroll-area": {
     name: "scroll-area",
@@ -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",
@@ -412,7 +412,7 @@ export const componentMeta = {
     name: "data-state",
     ancestry: "opus",
     whenToUse:
-      "Coordene carregamento, erro, vazio e conteúdo de uma consulta assíncrona. Use DataState dentro da estrutura que receberá os dados; para uma região disponível à criação, use Empty. Ações em andamento pertencem ao estado `busy` do controle que as iniciou.",
+      "Coordene carregamento, erro, vazio e conteúdo de uma consulta assíncrona com as mesmas superfícies de PageState: `emptyMessage` compõe Empty com moldura sólida, o erro é um Alert com `onRetry` e `retryLabel`. Use DataState dentro da estrutura que receberá os dados; para uma região disponível à criação, use Empty. Ações em andamento pertencem ao estado `busy` do controle que as iniciou.",
   },
   "action-list-dialog": {
     name: "action-list-dialog",

package/src/ui/react.tsx

@@ -18,7 +18,12 @@ export type {
   ButtonVariant,
   ButtonSize,
 } from "./components/primitives/button.tsx";
-export type { ControlShape } from "./components/primitives/control.ts";
+export type {
+  ControlShape,
+  ControlSize,
+  ControlIconSize,
+  ControlScale,
+} from "./components/primitives/control.ts";
 
 export { Input } from "./components/primitives/input.tsx";
 
@@ -358,6 +363,7 @@ export { useOverflowing } from "./lib/overflow.ts";
 export {
   ActionForm,
   ActionFormField,
+  LabelHelp,
   useActionFormContext,
 } from "./components/patterns/form.tsx";
 export type {
@@ -395,12 +401,7 @@ export { ActionView } from "./components/patterns/view.tsx";
 export type { ActionViewProps } from "./components/patterns/view.tsx";
 
 export { ActionTrigger } from "./components/patterns/trigger.tsx";
-export {
-  dialog,
-  DialogHost,
-  confirm,
-  ConfirmHost,
-} from "./components/patterns/confirm.tsx";
+export { dialog, DialogHost } from "./components/patterns/confirm.tsx";
 export type {
   AlertOptions,
   ChooseOptions,
@@ -426,6 +427,7 @@ export {
   PageDescription,
   PageMeta,
   PageActions,
+  PageActionsTarget,
   PageBody,
 } from "./components/patterns/page.tsx";
 export type { PageProps } from "./components/patterns/page.tsx";
@@ -475,6 +477,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.
@@ -497,15 +500,6 @@ export type {
   SidebarNavItem,
 } from "./components/patterns/sidebar.tsx";
 
-// O menu como primitivo pivotável: recolhe quando composto dentro de Sidebar.
-export { ShellNav, ShellNavHeading } from "./components/patterns/shell-nav.tsx";
-export type {
-  ShellNavProps,
-  ShellNavGroup,
-  ShellNavItem,
-  ShellNavHeadingProps,
-} from "./components/patterns/shell-nav.tsx";
-
 // Roteamento history-based (o pathname É o estado). Escopo pequeno de propósito: leitura
 // reativa da URL + navigate — sem tabela de rotas. Ver src/ui/router.ts.
 export {

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

package/src/vite/design.ts

@@ -21,7 +21,7 @@
  *   // vite --mode design
  */
 
-import { readdirSync, readFileSync } from 'node:fs'
+import { readdirSync } from 'node:fs'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import path from 'node:path'
 import type { Plugin, ViteDevServer } from 'vite'
@@ -40,6 +40,7 @@ import {
   type RuntimeSetup,
   type User,
 } from '../core/index.ts'
+import { readPackageVersion } from '../core/package-version.ts'
 import { mittEvents } from '../events/drivers/mitt.ts'
 import { nodeServer, type NodeServerHandle } from '../server/drivers/node.ts'
 import { serializeResult } from '../server/index.ts'
@@ -148,7 +149,7 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
   const stubEntries = Object.entries(options.stubs ?? {}).sort(
     (a, b) => b[0].length - a[0].length,
   )
-  const opusVersion = readOpusVersion()
+  const opusVersion = readPackageVersion()
 
   let exProxyPrefixes: string[] = []
   let current: Promise<DesignState> | undefined
@@ -373,7 +374,7 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
               sendEnvelope(res, 503, {
                 code: 'design.boot_failed',
                 category: 'dependency',
-                message: `Design runtime failed to boot: ${String(err)}`,
+                message: `O runtime de design não conseguiu iniciar: ${String(err)}`,
               })
               return
             }
@@ -421,7 +422,7 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
             sendEnvelope(res, 503, {
               code: 'design.no_backend',
               category: 'dependency',
-              message: `No backend for "${orphan}" in design mode — add a stub or serve it from the opus runtime`,
+              message: `Sem backend para "${orphan}" em modo design — adicione um stub ou sirva a action pelo runtime do Opus`,
             })
             return
           }
@@ -464,7 +465,7 @@ async function loadEntry(server: ViteDevServer, entry: string): Promise<unknown[
   throw error({
     code: 'design.invalid_entry',
     category: 'internal',
-    message: `Entry "${entry}" must default-export { domains: [...] } or an array of registrables`,
+    message: `O entry "${entry}" precisa exportar por default { domains: [...] } ou uma lista de registráveis`,
   })
 }
 
@@ -637,16 +638,3 @@ function sendEnvelope(res: ServerResponse, status: number, input: ErrorInput): v
   )
 }
 
-function readOpusVersion(): string {
-  // `import.meta.url` sobrevive ao bundling do vite.config (o vite injeta a
-  // URL original do arquivo), então o package.json resolve do source real.
-  try {
-    const pkg = JSON.parse(
-      readFileSync(new URL('../../package.json', import.meta.url), 'utf8'),
-    ) as { version?: string }
-    return pkg.version ?? '0.0.0'
-    /* v8 ignore next 3 — defensivo; o package.json viaja junto do source */
-  } catch {
-    return '0.0.0'
-  }
-}