@softize/opus 13.1.0 → 15.0.0

package/CHANGELOG.md

@@ -7,6 +7,103 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 15.0.0 — 2026-09-09
+
+`PageHeader` passa a oferecer `variant="bar"`, uma apresentação compacta da mesma região de título,
+descrição e ações. O novo `PageBack` recebe o destino pai explícito: no header padrão fica acima do
+título com rótulo; na barra vira icon-only com tooltip e nome acessível. Páginas comuns deixam de
+precisar de um chrome paralelo, enquanto `PageActionsTarget` permanece para workspaces imersivos que
+já tenham uma faixa própria. Para hierarquias com mais de um ancestral, `PageNavigation` recebe o
+`Breadcrumb` na mesma posição introdutória e não pode ser combinado com `PageBack`. Ações em barra
+usam a escala compacta: `sm` com texto e `icon-sm` quando exibem somente um ícone.
+
+`PageState` passa a centralizar carregamento, falha e vazio sem moldura e a ocupar a altura
+disponível. `Page` reconhece o estado mesmo quando um componente intermediário o renderiza, oculta
+o cabeçalho inteiro nos três estados e o restaura em `ready`. A falha mantém `role="alert"`, deixa
+de usar o visual de `Alert` e apresenta a recuperação como botão `outline` textual. A moldura tracejada continua disponível no `Empty` usado diretamente para
+representar uma região disponível à criação ou vínculo.
+
+O CLI carrega o `.env` ao lado do `opus.config.ts` antes de importar o config, em `db`, `seed` e
+`gen`. O config do consumer costuma abrir o banco no topo do módulo, lendo `process.env` na hora
+do import: sem isso, um projeto que guarda a URL no `.env` migrava o banco DEFAULT do config
+enquanto o runtime usava outro, e o schema aplicado sumia do banco que a aplicação abre. Variável
+já definida no ambiente vence o arquivo (a semântica do `--env-file` do Node), então
+`DATABASE_URL=... opus db migrate` e a injeção do container seguem mandando; ausência de `.env`
+é normal e não é erro. Um projeto que já carregava o `.env` por conta própria no `opus.config.ts`
+continua correto: as duas cargas são idempotentes e a primeira vence.
+
+**Breaking — API removida.** `Page` deixa de aceitar `count` e o barrel deixa de exportar
+`PageMeta` (ADR 0009). O cabeçalho da página reconhece somente `PageTitle`, `PageDescription`,
+`PageActions` e a região introdutória; um total vai para o conteúdo que o explica — a listagem, a
+métrica ou uma seção com `Content`, onde `ContentMeta` e `Content.count` continuam disponíveis.
+`PageBack` passa a exigir `href`: sem destino, o elemento não era tabulável nem tinha nome
+acessível. `PageNavigation` e `PageBack` não podem ser combinados na mesma página: escolha o
+retorno de um ancestral só ou a trilha completa.
+
+**Breaking — comportamento e DOM.** `Page` oculta o `PageHeader` inteiro enquanto o `PageState`
+estiver em carregamento, erro ou vazio, sem opt-out. Teste que procura o título da página durante a
+carga passa a falhar; o nível semântico segue disponível no `role="heading"` da própria superfície
+de estado. Some junto a região introdutória, então uma subpágina em erro fica sem o `PageBack` para
+o pai; quem depende desse retorno oferece a saída pelo `action` do próprio `PageState`. O motivo, a
+alternativa descartada e esse custo estão no adendo da ADR 0004. O erro e o vazio do `PageState`
+trocam de anatomia: sai `[data-slot="alert"]` e `[data-slot="alert-actions"]`, entram `error-state`
+e `state-actions`, e o vazio passa de `data-frame="region"` para `bare`. As ações de linha do
+`ActionList` passam a vir dentro de um `ButtonGroup`, o que acrescenta um `role="group"` por linha;
+as ações da barra (Filtros, Recarregar, Exibição) passaram de `outline` para `ghost`, e o que o
+consumidor entrega em `ActionFilterBar.actions` agora fica depois do grupo de controles auxiliares,
+no fim da barra. A recuperação do aviso inline de erro virou ação só de ícone, com o rótulo no nome
+acessível e no tooltip em vez do texto na tela. Quem afirma texto, variante ou slot nesses pontos
+precisa revisar as asserções.
+
+**Breaking — ícones voltam à escala.** `controlGlyph` passa a devolver seletores literais. Montada
+em runtime, a classe saía certa no DOM, mas o scanner do Tailwind não a via e o CSS nunca era
+gerado: na prática, todo ícone de `Button` sem `size-*` próprio vinha no tamanho padrão do lucide.
+Agora todos passam a medir o degrau da escala, então ícones encolhem visivelmente no consumidor. O
+`ActionTrigger` só de ícone usa `icon-xs` (1.5rem) por padrão, o degrau da ação que mora dentro de
+uma linha densa, e passa a respeitar um `size` declarado quando a composição pede mais presença —
+`icon-sm` na barra, por exemplo. Atenção ao inverso: um `size` que antes era ignorado no modo
+ícone passa a valer, então `size="lg"` esquecido ao lado de `icon` agora produz um botão de altura
+de texto com um ícone só.
+
+Do lado aditivo, `ButtonGroup` ganha `mode`: `connected`, o comportamento de sempre com as bordas
+coladas, e `spaced`, que só agrupa e espaça — é o que as ações de linha e os controles auxiliares
+da barra do `ActionList` passam a usar. `ActionList` ganha `toolbarActions` para o que o consumidor
+acrescenta no fim da barra de filtros.
+
+## 14.0.0 — 2026-09-09
+
+Estados vazio, carregando e erro passam a uma composição só. `DataState` compõe `Empty` (moldura
+sólida, `bare` dentro de tabela) e o mesmo `Alert` de contexto `danger` com botão de recuperação
+que `PageState` já usava; o `Spinner` vira decorativo e o contêiner carrega o único `role="status"`.
+As props de estado têm um nome só em `DataState`, `PageState`, `ActionList` e `ActionListDialog`:
+`emptyMessage`, `errorMessage`, `retryLabel`; `PageState` ganha `onRetry` e `ActionView` ganha
+`emptyMessage` como atalho. `ContentHeader` e `PageHeader` renderizam a mesma anatomia
+(`surface-header.tsx`), e `Content` passa a usar `count`, como `Page`.
+
+A escala de `size` é uma só (`primitives/control.ts`): `xs`, `sm`, `default`, `lg` (1.5, 2, 2.25
+e 2.5rem) e `icon-xs`, `icon-sm`, `icon`, `icon-lg` (1.5, 1.75, 2.25 e 2.5rem), consumida por
+Button, InputGroupButton, Toggle, Select, Tabs, Switch, Item, Avatar, Spinner, Pagination e
+ActionTrigger. O degrau de 1.75rem que os consumidores forçavam por classe agora é `icon-sm`.
+`Button.icon` recebe um nó (`icon={<Plus />}`), como todos os outros componentes. `LabelHelp` é
+exportado pelo barrel e documentado em `form.md`.
+
+O extrator de copy alcança o que antes escapava do inventário: chamadas imperativas de diálogo
+(`dialog.confirm`, `alert`, `prompt`, `choose` — título, descrição e rótulos das ações),
+`TooltipContent`, rótulos em arrays literais locais percorridos por `map`, o `help` de
+`LabelHelp` e elementos JSX com genérico (`<ActionList<A, B>>`). Os campos de estado seguem os
+nomes novos (`emptyMessage`, `errorMessage`, `retryLabel`).
+
+**Breaking:** renomeie `emptyText`, `errorText` e `retryText` para `emptyMessage`,
+`errorMessage` e `retryLabel` em `DataState`, `PageState` e `ActionListDialog`
+(`Select.emptyText` não muda). Troque `Content.meta` por `count`; `ContentHeader` só existe
+dentro de `Content`. `icon-sm` passa a medir 1.75rem e `Avatar` segue a escala (`sm` antigo é
+`xs`; `default` cresce para 2.25rem); classes `size-7` forçadas viram `size="icon-sm"`.
+`Button.icon` deixa de aceitar componente: `icon={Trash}` vira `icon={<Trash />}`. Removidos:
+`TbdlibProvider` (use `OpusProvider`), `ShellNav*` (use `SidebarNav`), `confirm()` e `ConfirmHost`
+(use `dialog.confirm` e `DialogHost`), `FieldSpec.hint` (use `help`) e as variantes semânticas
+legadas de Button, Badge, Alert, Dot e MenuItem — declare `context` e `variant`. Testes que
+liam o markup do vazio de `DataState` passam a olhar `[data-slot=empty]`.
+
 ## 13.1.0 — 2026-09-08
 
 Erros deixam de falar inglês e de vazar detalhe interno. `normalizeError` devolve a microcopy fixa

package/bin/cli.mjs

@@ -328,6 +328,8 @@ Flags
   --json             (introspect, seed) Saída estruturada em JSON.
   --monorepo         (create) Cria a raiz do workspace em vez de um app.
   --config <path>    (gen, db, seed) Caminho do opus.config.ts. Default: ./opus.config.ts.
+                     O .env ao lado desse arquivo é carregado antes do config; variável
+                     já definida no ambiente vence o arquivo.
   --output <path>    (gen) Pasta de saída. Default: a do config, ou ./.gen.
   --profile <nome>   (seed) Perfil do dataset. Default: o defaultProfile do seed.
   --scope <nome>     (seed) Escopo explícito dos dados. Alternativa: OPUS_SEED_SCOPE.

package/bin/lib/check.mjs

@@ -107,8 +107,9 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["PageHeader", new Set(["Page"])],
   ["PageBody", new Set(["Page"])],
   ["PageTitle", new Set(["PageHeader"])],
+  ["PageBack", new Set(["PageHeader"])],
+  ["PageNavigation", new Set(["PageHeader"])],
   ["PageDescription", new Set(["PageHeader"])],
-  ["PageMeta", new Set(["PageHeader"])],
   ["PageActions", new Set(["PageHeader"])],
   ["ContentHeader", new Set(["Content"])],
   ["ContentBody", new Set(["Content"])],
@@ -166,7 +167,11 @@ const UI_STRUCTURAL_ROOTS = new Map([
     {
       header: "PageHeader",
       body: "PageBody",
-      shorthand: new Set(["title", "description", "count", "actions"]),
+      shorthand: new Set(["title", "description", "actions"]),
+      // O contador saiu do título da página (ADR 0009). Tirar `count` do shorthand não proíbe
+      // nada sozinho — só apaga o marcador que fazia o gate enxergar aquele Page —, então a
+      // prop removida é cobrada aqui, nas duas formas de composição.
+      removed: new Map([["count", "o total pertence ao conteúdo que o explica"]]),
     },
   ],
   [
@@ -174,7 +179,8 @@ const UI_STRUCTURAL_ROOTS = new Map([
     {
       header: "ContentHeader",
       body: "ContentBody",
-      shorthand: new Set(["title", "description", "meta", "actions"]),
+      shorthand: new Set(["title", "description", "count", "actions"]),
+      removed: new Map([["meta", "use `count`"]]),
     },
   ],
 ]);
@@ -183,8 +189,9 @@ const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "PageHeader",
   "PageBody",
   "PageTitle",
+  "PageBack",
+  "PageNavigation",
   "PageDescription",
-  "PageMeta",
   "PageActions",
   "ContentHeader",
   "ContentBody",
@@ -202,7 +209,13 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "PageHeader",
     {
       title: "PageTitle",
-      optional: new Set(["PageDescription", "PageMeta", "PageActions"]),
+      optional: new Set([
+        "PageBack",
+        "PageNavigation",
+        "PageDescription",
+        "PageActions",
+      ]),
+      exclusive: [new Set(["PageBack", "PageNavigation"])],
       shorthand: new Set(),
     },
   ],
@@ -898,6 +911,10 @@ export function checkUiStructure(file, text) {
             (name) =>
               children.names.filter((child) => child === name).length > 1,
           );
+          const combinedExclusive = (header.exclusive ?? []).some(
+            (group) =>
+              children.names.filter((name) => group.has(name)).length > 1,
+          );
           const titleValid =
             header.titleRequired === false ? titles <= 1 : titles === 1;
           const recognizedContent =
@@ -910,6 +927,7 @@ export function checkUiStructure(file, text) {
               !(header.allowOpaque && children.hasOpaque)) ||
             unexpected ||
             duplicatedOptional ||
+            combinedExclusive ||
             (children.hasOpaque && !header.allowOpaque)
           ) {
             add(
@@ -932,6 +950,16 @@ export function checkUiStructure(file, text) {
               : [],
           ),
         );
+        for (const [attribute, hint] of root.removed ?? []) {
+          if (attributes.has(attribute)) {
+            add(
+              node,
+              component,
+              `${component} não aceita mais a propriedade \`${attribute}\`: ${hint}.`,
+              "ui-structure-removed-prop",
+            );
+          }
+        }
         const shorthand = [...root.shorthand].some((attribute) =>
           attributes.has(attribute),
         );

package/bin/lib/cli-shared.mjs

@@ -55,10 +55,39 @@ export async function fileExists(file) {
 // Config do consumer
 // =============================================================================
 
+/**
+ * Carrega o `.env` ao lado do `opus.config.ts` no processo do CLI, para que ele chegue
+ * aos runners (que herdam o ambiente) ANTES de o config do consumer ser importado.
+ *
+ * O config costuma abrir a conexão do banco no topo do módulo, lendo `process.env` na
+ * hora do import: sem isto, `db` e `seed` caem na conexão default e operam um banco
+ * diferente do que o runtime do projeto usa. Ausência do arquivo é normal (container e
+ * CI injetam por ambiente) e não é erro; qualquer outra falha de leitura sobe.
+ *
+ * Variável já definida no ambiente VENCE o arquivo (semântica do `--env-file` do Node),
+ * então `DATABASE_URL=... opus db migrate` e a injeção do container continuam mandando.
+ *
+ * Devolve o caminho carregado, ou `null` quando não havia `.env`.
+ */
+export function loadProjectEnv(configPath) {
+  const envFile = path.join(path.dirname(configPath), '.env')
+  try {
+    process.loadEnvFile(envFile)
+    return envFile
+  } catch (cause) {
+    if (cause.code === 'ENOENT') return null
+    throw cause
+  }
+}
+
 /**
  * Resolve o `opus.config.ts` a partir de `flags.config` (default: `./opus.config.ts`),
  * contido no projeto. Lança `Error` com uma mensagem única quando o arquivo não existe;
  * cada comando decide o canal (texto ou JSON) e o código de saída.
+ *
+ * Resolver o config é também o momento em que o projeto passa a ser conhecido, então o
+ * `.env` dele é carregado aqui (ver `loadProjectEnv`) — em um lugar só, para que nenhum
+ * comando que importe o config do consumer possa esquecer.
  */
 export function resolveConfig(flags, cwd = process.cwd()) {
   const root = canonicalProjectDirectory(cwd)
@@ -69,7 +98,7 @@ export function resolveConfig(flags, cwd = process.cwd()) {
         'Passe o caminho com --config <path> ou crie o arquivo na raiz do projeto.',
     )
   }
-  return { cwd: root, configPath: config.path }
+  return { cwd: root, configPath: config.path, envFile: loadProjectEnv(config.path) }
 }
 
 // =============================================================================

package/bin/lib/copy.mjs

@@ -103,12 +103,23 @@ const JSX_CHILD_ROLES = new Map([
   ['PopoverDescription', 'description'],
   ['PopoverTitle', 'title'],
   ['PageDescription', 'description'],
+  // O texto do PageBack é o NOME do destino ('Clientes'), como um item de trilha — não um
+  // comando. Classificado como `button`, a política universal cobraria verbo de ação.
+  ['PageBack', 'breadcrumb'],
   ['PageTitle', 'title'],
   ['TableCaption', 'description'],
   ['TableHead', 'heading'],
   ['TabsTrigger', 'tab'],
+  // A Base não tem papel `tooltip`. O tooltip nomeia um controle icon-only, logo é um
+  // fragmento (sem ponto final), não uma frase; `label` é o papel que reflete isso.
+  ['TooltipContent', 'label'],
 ])
 
+// Componentes cuja copy entra pelas próprias props e que, como filhos, não acrescentam
+// texto ao pai: `<FieldLabel>Nome<LabelHelp help="…" /></FieldLabel>` inventaria `Nome`
+// como label e a ajuda como helper-text, sem tornar o filho opaco.
+const SELF_CONTAINED_CHILD_COMPONENTS = new Set(['LabelHelp'])
+
 const OPTIONAL_CHILD_COMPONENTS = new Set(['ActionForm', 'ActionFormCard', 'ActionFormDialog'])
 const JSX_ACTION_CONSUMERS = new Set([
   'ActionForm', 'ActionFormCard', 'ActionFormDialog', 'ActionList', 'ActionListDialog', 'ActionTrigger', 'ActionView',
@@ -125,6 +136,14 @@ const JSX_PROP_ROLES = new Map([
   ['ActionForm', new Map([['submitLabel', 'button'], ['cancelLabel', 'button']])],
   ['ActionFormCard', new Map([['title', 'title'], ['description', 'description'], ['submitLabel', 'button'], ['cancelLabel', 'button']])],
   ['ActionFormDialog', new Map([['title', 'title'], ['description', 'dialog-body'], ['submitLabel', 'button'], ['cancelLabel', 'button']])],
+  // Estados unificados (14.0): a mesma tríade de mensagens em ActionList, ActionListDialog,
+  // DataState e PageState; ActionView só tem o vazio.
+  ['ActionList', new Map([['emptyMessage', 'empty-state'], ['errorMessage', 'error'], ['retryLabel', 'button']])],
+  ['ActionListDialog', new Map([
+    ['title', 'title'], ['description', 'dialog-body'],
+    ['emptyMessage', 'empty-state'], ['errorMessage', 'error'], ['retryLabel', 'button'],
+  ])],
+  ['ActionView', new Map([['emptyMessage', 'empty-state']])],
   // `itemLabel` identifica o dado alvo (por exemplo, `customer.name`); não é
   // microcopy estável e, por isso, não pertence ao inventário editorial.
   ['ActionTrigger', new Map([['label', 'button']])],
@@ -132,7 +151,7 @@ const JSX_PROP_ROLES = new Map([
   ['CommandInput', new Map([['placeholder', 'placeholder']])],
   ['Content', new Map([['title', 'title'], ['description', 'description']])],
   ['ContentHeader', new Map([['title', 'title'], ['description', 'description']])],
-  ['DataState', new Map([['emptyText', 'empty-state'], ['errorText', 'error']])],
+  ['DataState', new Map([['emptyMessage', 'empty-state'], ['errorMessage', 'error'], ['retryLabel', 'button']])],
   // A Dock nomeia a barra e cada ação por prop. Sem estas linhas, a copy sairia do inventário
   // exatamente quando uma superfície migra de <Button aria-label> para <DockAction label>.
   ['Dock', new Map([['label', 'label']])],
@@ -140,8 +159,14 @@ const JSX_PROP_ROLES = new Map([
   ['Input', new Map([['placeholder', 'placeholder']])],
   ['InputGroupInput', new Map([['placeholder', 'placeholder']])],
   ['InputGroupTextarea', new Map([['placeholder', 'placeholder']])],
+  // A ajuda vive num tooltip (portal): não herda transformação nem classe do label.
+  ['LabelHelp', new Map([['help', 'helper-text']])],
   ['MetricCard', new Map([['label', 'label'], ['description', 'description']])],
   ['Page', new Map([['title', 'title'], ['description', 'description']])],
+  ['PageState', new Map([
+    ['title', 'title'], ['description', 'description'],
+    ['emptyMessage', 'empty-state'], ['errorMessage', 'error'], ['retryLabel', 'button'],
+  ])],
   ['Select', new Map([
     ['placeholder', 'placeholder'],
     ['searchPlaceholder', 'placeholder'],
@@ -215,6 +240,36 @@ const JSX_PORTAL_BOUNDARIES = new Set([
   'PopoverContent', 'TooltipContent',
 ])
 
+// Respostas imperativas `dialog.*` da UI Opus. O DialogHost renderiza em portal com classes
+// próprias; nenhuma transformação do chamador alcança o texto.
+const DIALOG_METHOD_ROLES = new Map([
+  ['alert', new Map([['title', 'title'], ['description', 'dialog-body'], ['body', 'dialog-body'], ['action', 'button']])],
+  ['confirm', new Map([
+    ['title', 'title'], ['description', 'dialog-body'], ['body', 'dialog-body'],
+    ['action', 'button'], ['cancel', 'button'],
+  ])],
+  ['prompt', new Map([
+    ['title', 'title'], ['description', 'dialog-body'], ['body', 'dialog-body'],
+    ['action', 'button'], ['cancel', 'button'], ['placeholder', 'placeholder'],
+  ])],
+  ['choose', new Map([['title', 'title'], ['description', 'dialog-body'], ['body', 'dialog-body']])],
+])
+
+// Métodos de array que não mutam o receptor. Os que devolvem os próprios elementos (num
+// array novo ou avulsos) exigem que o resultado também seja usado de forma estável; os
+// demais só produzem primitivos, novos objetos ou nada.
+const ARRAY_RETURNING_ARRAY_METHODS = new Set(['concat', 'filter', 'flat', 'slice', 'toReversed', 'toSorted'])
+const ELEMENT_PICKING_ARRAY_METHODS = new Set(['at', 'find', 'findLast'])
+const ELEMENT_ITERATING_ARRAY_METHODS = new Set([
+  'every', 'filter', 'find', 'findIndex', 'findLast', 'findLastIndex', 'flatMap', 'forEach', 'map', 'some',
+])
+const READ_ONLY_ARRAY_METHODS = new Set([
+  ...ARRAY_RETURNING_ARRAY_METHODS, ...ELEMENT_PICKING_ARRAY_METHODS, ...ELEMENT_ITERATING_ARRAY_METHODS,
+  'includes', 'indexOf', 'join', 'lastIndexOf',
+])
+// Cadeia que preserva os elementos entre o array literal e a iteração que os lê.
+const ELEMENT_PRESERVING_ARRAY_METHODS = new Set(['filter', 'slice', 'toReversed', 'toSorted'])
+
 const digest = (content) => createHash('sha256').update(content).digest('hex')
 const portable = (value) => value.split(path.sep).join('/')
 
@@ -421,6 +476,17 @@ function knownBindAction(call, checker) {
   return importedMemberName(call.expression, checker, (module) => CONTRACT_MODULES.has(module)) === 'bindAction'
 }
 
+/** Reconhece `dialog.confirm({...})` e `Opus.dialog.alert({...})` importados da UI Opus. */
+function knownDialogCall(call, checker) {
+  const callee = unwrap(call.expression)
+  if (
+    ts.isPropertyAccessExpression(callee) &&
+    DIALOG_METHOD_ROLES.has(callee.name.text) &&
+    importedMemberName(callee.expression, checker, uiModule) === 'dialog'
+  ) return { method: callee.name.text, field: `dialog.${callee.name.text}()` }
+  return null
+}
+
 function safeBindActionBinding(call, checker) {
   if (call.arguments.length < 2) return false
   const binding = unwrap(call.arguments[1])
@@ -521,6 +587,16 @@ function stableExpressionUse(node, checker, mode, stack) {
   const parent = carrier.parent
 
   if (assignmentTarget(carrier)) return false
+  if (consumerMode === 'aggregate' && ts.isCallExpression(parent) && parent.expression === carrier) {
+    const access = unwrap(carrier)
+    return (
+      ts.isPropertyAccessExpression(access) && arrayValued(access.expression, checker) &&
+      readOnlyArrayMethodUse(access.name.text, parent, checker, stack)
+    )
+  }
+  if (ts.isForOfStatement(parent) && parent.expression === carrier) {
+    return consumerMode === 'aggregate' && arrayValued(carrier, checker) && readOnlyForOfBinding(parent, checker)
+  }
   if (ts.isVariableDeclaration(parent) && parent.initializer === carrier) {
     if (!ts.isVariableDeclarationList(parent.parent) || (parent.parent.flags & ts.NodeFlags.Const) === 0) return false
     const aliases = bindingNames(parent.name, checker)
@@ -534,6 +610,8 @@ function stableExpressionUse(node, checker, mode, stack) {
   if (ts.isCallExpression(parent) && parent.arguments.some((argument) => argument === carrier)) {
     if (consumerMode === 'aggregate') {
       if (knownDictionaryFactory(parent, checker)) return true
+      // O DialogHost copia as opções (`{ ...options }`) e só as lê; nada muta o literal.
+      if (parent.arguments[0] === carrier && knownDialogCall(parent, checker) !== null) return true
       return knownContractFactory(parent, checker) && stableFactoryResult(parent, checker, stack)
     }
     if (
@@ -573,6 +651,166 @@ function stableReferences(binding, checker, mode, stack) {
   return stable
 }
 
+/**
+ * Um parâmetro de callback (ou variável de `for…of`) é somente leitura quando cada uso é
+ * `elemento.chave` fora de posição de atribuição. Strings são imutáveis, então uma leitura de
+ * propriedade nunca altera o rótulo literal; qualquer outro uso (spread, argumento, retorno,
+ * atribuição) poderia mutar ou fazer o objeto escapar e é rejeitado. Destructuring copia os
+ * valores de primeiro nível e, por isso, também não alcança o literal.
+ */
+function readOnlyElementBinding(name, checker) {
+  if (ts.isObjectBindingPattern(name)) return true
+  if (!ts.isIdentifier(name)) return false
+  const symbol = bindingSymbol(name, checker)
+  if (symbol === undefined) return false
+  let readOnly = true
+  const visit = (node) => {
+    if (!readOnly) return
+    if (ts.isIdentifier(node) && sameBinding(node, symbol, checker) && !declarationIdentifier(node, symbol)) {
+      const carrier = transparentCarrier(node)
+      const access = carrier.parent
+      readOnly =
+        (ts.isPropertyAccessExpression(access) || ts.isElementAccessExpression(access)) &&
+        access.expression === carrier && !assignmentTarget(access)
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(name.getSourceFile())
+  return readOnly
+}
+
+function readOnlyCallback(callback, checker) {
+  const value = callback === undefined ? null : unwrap(callback)
+  if (value === null || (!ts.isArrowFunction(value) && !ts.isFunctionExpression(value))) return false
+  // O terceiro parâmetro expõe o próprio array ao callback; índice e `thisArg` não.
+  if (value.parameters.length > 2) return false
+  const element = value.parameters[0]
+  if (element === undefined) return true
+  if (element.dotDotDotToken !== undefined || element.initializer !== undefined) return false
+  return readOnlyElementBinding(element.name, checker)
+}
+
+function readOnlyArrayMethodUse(method, call, checker, stack) {
+  if (!READ_ONLY_ARRAY_METHODS.has(method)) return false
+  if (ELEMENT_ITERATING_ARRAY_METHODS.has(method) && !readOnlyCallback(call.arguments[0], checker)) return false
+  if (ARRAY_RETURNING_ARRAY_METHODS.has(method) || ELEMENT_PICKING_ARRAY_METHODS.has(method)) {
+    return stableExpressionUse(call, checker, 'aggregate', stack)
+  }
+  return true
+}
+
+/**
+ * A semântica somente leitura de `map`, `filter`… vale para arrays. Um objeto literal pode
+ * declarar um método com o mesmo nome e mutar o que quiser; por isso o receptor precisa ser
+ * um `const` com array literal ou o resultado de um método que devolve array sobre ele.
+ */
+function arrayValued(node, checker) {
+  const value = unwrap(node)
+  if (ts.isIdentifier(value)) {
+    const binding = constInitializer(value, checker)
+    return binding !== null && ts.isArrayLiteralExpression(unwrap(binding.initializer))
+  }
+  if (ts.isCallExpression(value)) {
+    const callee = unwrap(value.expression)
+    return ts.isPropertyAccessExpression(callee) && ARRAY_RETURNING_ARRAY_METHODS.has(callee.name.text) &&
+      arrayValued(callee.expression, checker)
+  }
+  return ts.isArrayLiteralExpression(value)
+}
+
+function readOnlyForOfBinding(statement, checker) {
+  const initializer = statement.initializer
+  if (!ts.isVariableDeclarationList(initializer) || initializer.declarations.length !== 1) return false
+  return readOnlyElementBinding(initializer.declarations[0].name, checker)
+}
+
+/**
+ * Localiza o array literal do qual um identificador é elemento: parâmetro de callback de
+ * `map`/`forEach`/`filter`… ou variável de `for…of`, possivelmente atrás de `filter`,
+ * `slice`, `toSorted` e `toReversed`, que preservam os elementos. Só arrays literais no
+ * mesmo arquivo entram; qualquer outra origem devolve null.
+ */
+function elementSource(identifier, checker) {
+  const symbol = bindingSymbol(identifier, checker)
+  const declaration = symbol?.declarations?.find(
+    (item) => ts.isParameter(item) || ts.isBindingElement(item) || ts.isVariableDeclaration(item),
+  )
+  if (declaration === undefined) return null
+
+  let key = null
+  let binding = declaration
+  if (ts.isBindingElement(declaration)) {
+    if (declaration.dotDotDotToken !== undefined || declaration.initializer !== undefined) return null
+    const pattern = declaration.parent
+    if (!ts.isObjectBindingPattern(pattern) || (!ts.isParameter(pattern.parent) && !ts.isVariableDeclaration(pattern.parent))) return null
+    const keyNode = declaration.propertyName ?? declaration.name
+    if (!ts.isIdentifier(keyNode) && !ts.isStringLiteral(keyNode)) return null
+    key = keyNode.text
+    binding = pattern.parent
+  }
+
+  let receiver
+  if (ts.isParameter(binding)) {
+    if (binding.dotDotDotToken !== undefined || binding.initializer !== undefined) return null
+    const callback = binding.parent
+    if ((!ts.isArrowFunction(callback) && !ts.isFunctionExpression(callback)) || callback.parameters[0] !== binding) return null
+    const call = transparentCarrier(callback).parent
+    if (!ts.isCallExpression(call) || call.arguments[0] !== transparentCarrier(callback)) return null
+    const callee = unwrap(call.expression)
+    if (!ts.isPropertyAccessExpression(callee) || !ELEMENT_ITERATING_ARRAY_METHODS.has(callee.name.text)) return null
+    receiver = callee.expression
+  } else if (ts.isVariableDeclaration(binding)) {
+    const list = binding.parent
+    if (!ts.isVariableDeclarationList(list) || !ts.isForOfStatement(list.parent) || list.parent.initializer !== list) return null
+    receiver = list.parent.expression
+  } else return null
+
+  let source = unwrap(receiver)
+  while (
+    ts.isCallExpression(source) && ts.isPropertyAccessExpression(unwrap(source.expression)) &&
+    ELEMENT_PRESERVING_ARRAY_METHODS.has(unwrap(source.expression).name.text)
+  ) source = unwrap(unwrap(source.expression).expression)
+  const array = resolveBinding(source, checker)
+  return ts.isArrayLiteralExpression(array) ? { array, key } : null
+}
+
+/**
+ * Resolve `elemento.chave` (ou a chave destruturada) para o texto literal de cada elemento
+ * do array de origem. Um único elemento opaco ou sem texto estático torna o conjunto todo
+ * inextraível: o inventário não pode listar só parte do que a superfície renderiza.
+ */
+function elementTexts(node, checker) {
+  const value = unwrap(node)
+  let identifier
+  let key = null
+  if (ts.isPropertyAccessExpression(value) && ts.isIdentifier(unwrap(value.expression))) {
+    identifier = unwrap(value.expression)
+    key = value.name.text
+  } else if (ts.isElementAccessExpression(value) && ts.isIdentifier(unwrap(value.expression))) {
+    identifier = unwrap(value.expression)
+    key = value.argumentExpression === undefined ? null : staticText(value.argumentExpression, checker)?.text ?? null
+  } else if (ts.isIdentifier(value)) {
+    identifier = value
+  } else return null
+  const source = elementSource(identifier, checker)
+  if (source === null) return null
+  if (ts.isIdentifier(value)) key = source.key
+  else if (source.key !== null) return null
+  if (key === null) return null
+
+  const listed = objects(source.array, checker)
+  if (listed.opaque.length > 0 || listed.values.length === 0) return null
+  const texts = []
+  for (const element of listed.values) {
+    const resolved = property(element, key, element.getSourceFile(), checker)
+    if (resolved.opaque !== undefined || resolved.candidate === undefined) return null
+    const text = staticText(propertyValue(resolved.candidate), checker)
+    if (text === null) return null
+    texts.push(text)
+  }
+  return texts
+}
+
 /**
  * Objetos e arrays `const` continuam mutáveis. A extração só faz fold quando cada uso
  * está numa allowlist observável: composição `const` igualmente estável, factory Opus
@@ -982,7 +1220,6 @@ export function extractCopyFromSource(file, sourceText) {
   const field = (object, prefix) => {
     addProperty(object, 'label', 'label', prefix)
     addProperty(object, 'placeholder', 'placeholder', prefix)
-    addProperty(object, 'hint', 'helper-text', prefix)
     addProperty(object, 'help', 'helper-text', prefix)
     nestedObject(object, 'options', optionItems, prefix)
   }
@@ -1384,6 +1621,11 @@ export function extractCopyFromSource(file, sourceText) {
         ? { kind: 'decorative' }
         : { kind: 'text', ...text, uppercase: inheritedUppercase }
     }
+    const listed = elementTexts(value, checker)
+    if (listed !== null) {
+      const values = listed.map((item) => ({ kind: 'text', ...item, uppercase: inheritedUppercase }))
+      return values.length === 1 ? values[0] : { kind: 'alternatives', values, node: values[0].node }
+    }
     if (ts.isJsxElement(value) || ts.isJsxSelfClosingElement(value) || ts.isJsxFragment(value)) {
       return childNode(value, inheritedUppercase, hiddenAncestor)
     }
@@ -1439,6 +1681,9 @@ export function extractCopyFromSource(file, sourceText) {
     if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
       const opening = ts.isJsxElement(child) ? child.openingElement : child
       const component = opusComponent(opening.tagName)
+      if (component !== null && SELF_CONTAINED_CHILD_COMPONENTS.has(component) && ts.isJsxSelfClosingElement(child)) {
+        return { kind: 'decorative' }
+      }
       const provenElement = transformableElement(opening, component)
       const hidden = attribute(opening.attributes, 'aria-hidden')
       if (hidden.opaque !== undefined) return { kind: 'opaque', node: hidden.opaque }
@@ -1593,7 +1838,10 @@ export function extractCopyFromSource(file, sourceText) {
     if (component === null) return
     let inherited
     const inheritedFor = (className, styleName, portal = false) => {
-      if (portal || localTransformOverridesInheritance(opening.attributes, className, styleName)) return false
+      // Um componente que renderiza em portal (TooltipContent) não é descendente visual
+      // dos ancestrais no JSX; a transformação deles não alcança o texto.
+      if (portal || JSX_PORTAL_BOUNDARIES.has(component)) return false
+      if (localTransformOverridesInheritance(opening.attributes, className, styleName)) return false
       inherited ??= ancestorTransform(element)
       return inherited.opaque ? false : inherited.uppercase
     }
@@ -1676,7 +1924,11 @@ export function extractCopyFromSource(file, sourceText) {
           }
         } else {
           const value = raw === null ? null : attributeText(item)
-          if (value === null) {
+          // `title={group.label}` dentro de `GROUPS.map(...)`: cada literal do array local
+          // vira um texto na própria linha, em vez de um diagnóstico sobre a prop.
+          const listed = value === null && raw !== null ? elementTexts(raw, checker) : null
+          const texts = value !== null ? [value] : listed ?? []
+          if (texts.length === 0) {
             diagnostics.push(diagnostic(
               file,
               sourceFile,
@@ -1685,8 +1937,8 @@ export function extractCopyFromSource(file, sourceText) {
               raw === null ? 'missing-content' : 'content',
             ))
           }
-          else {
-            const entry = { source: file, line: lineOf(sourceFile, value.node), role, text: value.text }
+          for (const text of texts) {
+            const entry = { source: file, line: lineOf(sourceFile, text.node), role, text: text.text }
             if (transformed.uppercase) entry.transform = 'uppercase'
             entries.push(entry)
           }
@@ -1838,7 +2090,28 @@ export function extractCopyFromSource(file, sourceText) {
     }
   }
 
+  /**
+   * `dialog.confirm({ title, description, action })` é copy tão editorial quanto a de um
+   * `<ActionFormDialog>`; a chamada só é imperativa. Um template com interpolação
+   * (`description: describe(name)`) cai no diagnóstico `content` normal, declarável em
+   * `copy.dynamic` como `message-template`.
+   */
+  function extractDialog(call, { method, field }) {
+    const raw = call.arguments[0]
+    const options = raw === undefined ? null : resolveBinding(raw, checker)
+    if (options === null || !ts.isObjectLiteralExpression(options)) {
+      diagnostics.push(diagnostic(file, sourceFile, raw ?? call, `${field} options`, 'structure'))
+      return
+    }
+    for (const [name, role] of DIALOG_METHOD_ROLES.get(method)) addVisualObjectProperty(options, name, role, `${field}.`)
+    if (method === 'choose') {
+      nestedObject(options, 'actions', (action, prefix) => addVisualObjectProperty(action, 'label', 'button', prefix), `${field}.`)
+    }
+  }
+
   function visit(node) {
+    const dialogCall = ts.isCallExpression(node) ? knownDialogCall(node, checker) : null
+    if (dialogCall !== null) extractDialog(node, dialogCall)
     const factory = ts.isCallExpression(node) ? contractFactory(node.expression) : null
     if (ts.isCallExpression(node) && factory !== null && node.arguments.length > 0) {
       hasContract = true