@softize/opus 22.2.0 → 23.0.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@ 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.
 
+## 23.0.0 — 2026-09-29
+
+Esta major conclui a separação entre contrato e dados de design, simplifica a hierarquia de
+`Content` e dá a Tabs uma anatomia pública única para navegação. A seção **Breaking** reúne as
+migrações obrigatórias.
+
+### Breaking
+
+`mockHandler` foi removido de `ActionBase`, contratos, actions de lista, runtime e `runAction`,
+concluindo a ADR 0037. O core não lê mais `OPUS_MODE`: o plugin `opusDesign()` liga cenários ou
+respostas geradas como handlers antes de registrar as actions no runtime. Migração: remova cada
+`mockHandler`; quando a resposta específica importar para o design, transforme-a em cenário com
+`defineDesignScenario`. Testes devem passar a action produzida por `bindAction` ao `runAction`.
+
+Filtros `select` de escolha única aceitam `presentation: "toggle"` para manter opções curtas e
+mutuamente exclusivas visíveis em um grupo conectado. A apresentação padrão continua sendo
+`Select`; estado, URL, defaults e input da action não mudam. Opções vindas de dicionário também
+apresentam o ícone declarado na entrada, sempre acompanhado pelo rótulo.
+
+`TabsList` passa a usar somente a linha de navegação e deixa de aceitar `variant`. Migração: remova
+`variant="line"`; usos da antiga superfície preenchida devem representar escolha de valor com
+`ToggleGroup`, usando `variant="outline"` quando precisarem de borda.
+
+A anatomia pública de Tabs passa a nomear estrutura, não o mecanismo da primitiva:
+`TabsTrigger` vira `TabsListItem` e `TabsContent` vira `TabsPanel`. A mudança não mantém aliases;
+consumidores devem atualizar imports e JSX no mesmo upgrade.
+
+`Content` deixa de aceitar `variant="page" | "section"`. `level={1}` identifica o conteúdo
+principal, aplica automaticamente a escala de `PageHeader` e usa o mesmo intervalo de `1.5rem`
+entre header e body; níveis de 2 a 6 preservam a apresentação compacta de seção. Migração: remova
+`variant="page"` e mantenha `level={1}`. Não existe substituição para `variant="section"`, que era
+o comportamento dos níveis internos.
+
+### Filtros e controles
+
+`Toggle` e `ToggleGroupItem` em `variant="outline"` preservam a borda no estado ativo e usam um
+fundo sutil distinto dela, inclusive no tema escuro.
+
 ## 22.2.0 — 2026-09-29
 
 As actions passam a declarar o que fazem com os dados (ADR 0041). Dois campos novos no contrato,
@@ -381,7 +419,7 @@ página (ADR 0024). A `Presentation` de lista em `layout="fill"` passa a entrega
 lista ocupa a altura da página e só os resultados rolam.
 
 Quem encadeava `flex min-h-0 flex-1 flex-col` à mão pode remover as classes; mantidas, continuam
-funcionando. Com um contêiner próprio entre `ContentBody` e a lista, como um `TabsContent`, a lista
+funcionando. Com um contêiner próprio entre `ContentBody` e a lista, como um `TabsPanel`, a lista
 continua em `flow`: declare `layout="fill"` nela e dê ao contêiner `flex min-h-0 flex-1 flex-col`.
 
 ### Superfícies e patterns

package/bin/cli.mjs

@@ -40,16 +40,8 @@ async function cmdCheck(dir) {
     for (const error of materialization.errors) log('error', `✗ opus check: ${error}`)
     process.exit(1)
   }
-  const { files, actions, contracts, deprecatedMockHandlers, missingEffect, missingPersonalData, findings, hasMarker } =
+  const { files, actions, contracts, missingEffect, missingPersonalData, findings, hasMarker } =
     await scanDir(root)
-  // Aviso de migração, não violação: uma linha só, para não poluir o gate a cada execução.
-  if (deprecatedMockHandlers > 0) {
-    log(
-      'warn',
-      `⚠ opus check: ${deprecatedMockHandlers} action(s) ainda declaram \`mockHandler\`, que sai na próxima major. ` +
-        'No modo design, a action sem mock já responde com dado gerado; use `defineDesignScenario` quando o design precisar de um cenário (ADR 0037).',
-    )
-  }
 
   if (missingEffect > 0 || missingPersonalData > 0) {
     log(

package/bin/lib/check.mjs

@@ -58,7 +58,6 @@ const FIELD_GROUP = {
   authorize: 3,
   loads: 3,
   handler: 4,
-  mockHandler: 4,
   audit: 5,
   confirm: 5,
   invalidates: 5,
@@ -651,8 +650,6 @@ export function checkProject(sources) {
   const productDeclarations = [];
   const entityNames = new Set();
   const actionNames = new Set();
-  // `mockHandler` obsoleto (ADR 0037): contado, não reprovado — a minor ainda o aceita.
-  let deprecatedMockHandlers = 0;
   // Natureza da action (ADR 0041): declarações ausentes são contadas, não reprovadas, na minor.
   let missingEffect = 0;
   let missingPersonalData = 0;
@@ -680,7 +677,6 @@ export function checkProject(sources) {
         if (item.name !== null) actionNames.add(item.name);
       }
       for (const f of lintAction(item)) findings.push({ ...f, file });
-      if (item.keys.includes("mockHandler")) deprecatedMockHandlers += 1;
       if (item.form !== "bindAction") {
         const writesByGet = item.kind === "list" || item.kind === "view";
         if (!writesByGet && !item.keys.includes("effect")) missingEffect += 1;
@@ -791,7 +787,6 @@ export function checkProject(sources) {
     actions,
     contracts,
     dataProducts: productDeclarations.length,
-    deprecatedMockHandlers,
     missingEffect,
     missingPersonalData,
     findings,
@@ -1944,7 +1939,7 @@ async function walkUiFiles(dir, acc = []) {
   return acc;
 }
 
-/** Escaneia um diretório → { files, actions, contracts, deprecatedMockHandlers, findings, hasMarker }.
+/** Escaneia um diretório → { files, actions, contracts, findings, hasMarker }.
  *  `hasMarker` = o diretório é um projeto opus (tem opus.json na raiz). */
 export async function scanDir(rootDir) {
   rootDir = canonicalProjectDirectory(rootDir);
@@ -1974,7 +1969,6 @@ export async function scanDir(rootDir) {
     actions: checked.actions,
     contracts: checked.contracts,
     dataProducts: checked.dataProducts,
-    deprecatedMockHandlers: checked.deprecatedMockHandlers,
     missingEffect: checked.missingEffect,
     missingPersonalData: checked.missingPersonalData,
     findings: [...checked.findings, ...uiFindings],

package/bin/lib/copy.mjs

@@ -128,7 +128,7 @@ const JSX_CHILD_ROLES = new Map([
   ['PaneTitle', 'title'],
   ['TableCaption', 'description'],
   ['TableHead', 'heading'],
-  ['TabsTrigger', 'tab'],
+  ['TabsListItem', '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'],

package/bin/lib/gen-runner.mjs

@@ -466,6 +466,8 @@ function serializeFilters(filters) {
       placeholder: spec.placeholder ?? null,
       type: spec.type ?? null,
       multiple: spec.multiple === true,
+      presentation: spec.presentation ?? null,
+      allowEmpty: spec.allowEmpty ?? null,
       mode: spec.mode ?? null,
       operators: Array.isArray(spec.operators) ? spec.operators : null,
       path: spec.path ?? null,

package/bin/lib/gen-stubs.mjs

@@ -182,7 +182,9 @@ function stripNullsFromFields(record) {
     for (const [k, v] of Object.entries(spec)) {
       if (v === null || v === undefined) continue
       if (k === 'hasShowWhen' || k === 'hasRequireWhen') continue
-      if (typeof v === 'boolean' && v === false) continue
+      // `false` costuma ser o default implícito e não precisa viajar. `allowEmpty` é a
+      // exceção: seu default é aceitar vazio, então `false` altera o comportamento.
+      if (typeof v === 'boolean' && v === false && k !== 'allowEmpty') continue
       clean[k] = v
     }
     out[name] = clean

package/docs/adr/0005-structural-surfaces-share-an-explicit-anatomy.md

@@ -62,7 +62,7 @@ por propriedades continua disponível temporariamente dentro de `Content`, mas a
 explícita usa os slots da família.
 
 `Content` técnico mantém seu nome quando representa o contêiner montado por uma primitiva ou um
-painel controlado, como `DialogContent`, `PopoverContent`, `TabsContent` e `AccordionContent`.
+painel controlado, como `DialogContent`, `PopoverContent`, `TabsPanel` e `AccordionContent`.
 `CarouselContent` também permanece porque representa o trilho técnico da primitiva, não o body de
 uma superfície estrutural. No `Empty`, a antiga região `EmptyContent` não é um body: como contém
 somente comandos, seu nome canônico passa a ser `EmptyActions`.

package/docs/adr/0032-tab-baseline-respects-the-container-inset.md

@@ -2,7 +2,8 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-28.
-- **Relacionada:** ADR 0023, quanto ao alinhamento horizontal dentro de superfícies.
+- **Relacionadas:** ADR 0023, quanto ao alinhamento horizontal dentro de superfícies; ADR 0040,
+  que torna a linha a única apresentação de `TabsList`.
 
 ## Contexto
 
@@ -23,14 +24,16 @@ continua pertencendo à anatomia da superfície, e Tabs apenas ocupa a largura q
 
 ### Emenda de 2026-09-28 — a aba combina uma área de botão e o indicador
 
-Na variante horizontal `line`, o gatilho mantém duas camadas: uma área interna com os estados
-interativos e a mesma altura de um Button do tamanho correspondente, e o indicador ancorado na
-linha-base da lista. A área interna permanece transparente e recebe fundo apenas no hover; a aba
-ativa se distingue pelo indicador primário. Um respiro de `0.375rem` separa as duas camadas no uso
-comum; dentro de `Tabs framed`, ele aumenta para `0.5rem` e acompanha o padding superior da moldura.
+Na apresentação horizontal que então se chamava `line`, o gatilho mantém duas camadas: uma área
+interna com os estados interativos e a mesma altura de um Button do tamanho correspondente, e o
+indicador ancorado na linha-base da lista. A área interna permanece transparente e recebe fundo
+apenas no hover; a aba ativa se distingue pelo indicador primário. Um respiro de `0.375rem` separa
+as duas camadas no uso comum; dentro de `Tabs framed`, ele aumenta para `0.5rem` e acompanha o
+padding superior da moldura.
 
-Essa apresentação pertence ao Opus: consumidores escolhem `variant="line"` e não repetem classes
-de fundo, raio, padding ou interação para obter o estado selecionado.
+Essa apresentação pertence ao Opus: consumidores não repetem classes de fundo, raio, padding ou
+interação para obter o estado selecionado. Desde a ADR 0040, a linha é a única apresentação de
+`TabsList` e `variant` não faz mais parte da API.
 
 ## Consequências
 
@@ -38,7 +41,7 @@ de fundo, raio, padding ou interação para obter o estado selecionado.
 - A seleção permanece indicada pela linha inferior, sem manter um segundo fundo persistente.
 - Drawer e Dialog não mantêm uma integração implícita com Tabs.
 - Um consumidor que realmente precise de uma linha até as bordas deve compor essa apresentação de
-  forma explícita, pois ela não é mais o comportamento padrão da variante `line`.
+  forma explícita, pois ela não faz parte do comportamento canônico de `TabsList`.
 
 ## Alternativas descartadas
 
@@ -54,6 +57,7 @@ sem consumidor conhecido. A composição explícita é suficiente caso essa nece
 
 ## Verificação
 
-O teste da variante `line` verifica que a linha usa `inset-inline: 0`, inclusive quando Tabs está
-dentro de `DrawerBody`. O mesmo teste verifica a separação estrutural entre a superfície interna e
-o indicador da aba ativa. A documentação viva demonstra a variante com os limites do contêiner.
+O teste da apresentação horizontal verifica que a linha usa `inset-inline: 0`, inclusive quando
+Tabs está dentro de `DrawerBody`. O mesmo teste verifica a separação estrutural entre a superfície
+interna e o indicador da aba ativa. A documentação viva demonstra a linha com os limites do
+contêiner.

package/docs/adr/0034-tabs-can-own-a-frame-without-owning-a-surface.md

@@ -2,7 +2,8 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-28.
-- **Relacionadas:** ADR 0023, quanto à anatomia das superfícies; ADR 0032, quanto à linha-base das abas.
+- **Relacionadas:** ADR 0023, quanto à anatomia das superfícies; ADR 0032, quanto à linha-base das
+  abas; ADR 0040, que substitui a escolha de variante em `TabsList`.
 
 ## Contexto
 
@@ -23,9 +24,10 @@ Quando ativa, `framed` aplica ao root a moldura estrutural canônica para esse b
 `rounded-xl` e recorte do conteúdo. Ela não aplica token de fundo nem de foreground. O conjunto
 herda a superfície do contêiner em que foi composto.
 
-Essa propriedade não altera a apresentação de `TabsList`, a seleção, o tamanho nem a orientação. O
-consumidor continua escolhendo esses comportamentos nas APIs existentes, inclusive
-`TabsList variant="line"`.
+Essa propriedade não altera a apresentação de `TabsList`, a seleção, o tamanho nem a orientação. À
+época desta decisão, o consumidor ainda escolhia a apresentação com `TabsList variant="line"`.
+Essa parte foi substituída pela ADR 0040, que tornou a linha a única apresentação; a independência
+entre moldura e apresentação permanece válida.
 
 ## Consequências
 
@@ -33,8 +35,8 @@ consumidor continua escolhendo esses comportamentos nas APIs existentes, inclusi
 - Em Drawer, Dialog ou Pane, a moldura acompanha o fundo da superfície externa nos temas claro e
   escuro.
 - `Card` continua correto quando as abas realmente precisarem de uma superfície semântica própria.
-- `framed` permanece independente de `TabsList variant`, que descreve apenas a apresentação da
-  lista.
+- `framed` permanece independente da apresentação de `TabsList`; desde a ADR 0040, a lista usa
+  somente a linha de navegação e não aceita `variant`.
 
 ## Alternativas descartadas
 

package/docs/adr/0036-tabs-declares-trigger-distribution.md

@@ -2,7 +2,9 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-28.
-- **Relacionadas:** ADR 0032, quanto à composição da variante `line`; ADR 0034, quanto à moldura de Tabs; ADR 0035, quanto ao eixo de distribuição em grupos de controles.
+- **Relacionadas:** ADR 0032, quanto à composição da linha; ADR 0034, quanto à moldura de Tabs; ADR
+  0035, quanto ao eixo de distribuição em grupos de controles; ADR 0040, que substitui a escolha de
+  variante em `TabsList`.
 
 ## Contexto
 
@@ -11,10 +13,11 @@ entre os gatilhos. A view de Evento usa quatro abas no cabeçalho de um bloco em
 derivadas do texto deixam esse cabeçalho visualmente desequilibrado, embora todas as seções tenham o
 mesmo nível.
 
-Hoje, a variante horizontal `line` força cada gatilho a usar a largura do próprio conteúdo. Um
-consumidor que precise de larguras iguais teria de sobrescrever o `flex` interno ou reconstruir a
-lista com grid, duplicando uma decisão que já existe em `ButtonGroup` como
-`distribution="content" | "equal"`.
+Na API vigente quando esta decisão foi registrada, a variante horizontal `line` forçava cada
+gatilho a usar a largura do próprio conteúdo. Um consumidor que precisasse de larguras iguais teria
+de sobrescrever o `flex` interno ou reconstruir a lista com grid, duplicando uma decisão que já
+existia em `ButtonGroup` como `distribution="content" | "equal"`. A ADR 0040 depois tornou a linha
+a única apresentação e removeu `variant`, sem alterar o problema de distribuição resolvido aqui.
 
 ## Decisão
 
@@ -30,9 +33,9 @@ largura nem o layout dos painéis de conteúdo.
 ## Consequências
 
 - Consumidores escolhem a mesma linguagem de distribuição usada por `ButtonGroup`.
-- `TabsList variant="line"` continua responsável pela linha e pelos estados visuais; não recebe
-  classes de layout no consumidor.
-- A view de Evento declara `distribution="equal"` no `Tabs` sem alterar cada `TabsTrigger`.
+- `TabsList` continua responsável pela linha e pelos estados visuais; desde a ADR 0040, não aceita
+  `variant` nem recebe classes de layout no consumidor.
+- A view de Evento declara `distribution="equal"` no `Tabs` sem alterar cada `TabsListItem`.
 - Usos existentes preservam a distribuição pelo conteúdo.
 
 ## Alternativas descartadas

package/docs/adr/0037-design-data-lives-outside-the-contract.md

@@ -1,6 +1,6 @@
 # ADR 0037 — Dados do modo design ficam fora do contrato
 
-- **Status:** aceita; a primeira etapa saiu na 22.1.0, e a remoção fica para a 23.0.0.
+- **Status:** aceita; transição concluída na 23.0.0.
 - **Data:** 2026-09-28.
 - **Relacionadas:** ADR 0002 (seeds estruturados).
 

package/docs/adr/0038-content-level-defines-primary-presentation.md

@@ -0,0 +1,62 @@
+# ADR 0038 — O nível do Content define sua apresentação principal
+
+- **Status:** aceita.
+- **Data:** 2026-09-29.
+- **Complementa:** ADRs 0016, 0021, 0023 e 0029.
+
+## Contexto
+
+`Content` aceitava duas declarações independentes para a mesma hierarquia: `level={1}` fazia da
+região o heading principal da `Page`, enquanto `variant="page"` escolhia a escala visual desse
+mesmo papel. Todos os consumidores válidos precisavam repetir as duas propriedades, e o contrato
+também permitia combinações contraditórias como um heading principal com aparência de seção.
+
+A duplicação ainda produzia ritmos diferentes entre páginas equivalentes. Quando `PageHeader`
+fornecia o heading, `Page` separava introdução e corpo por `1.5rem`; quando `Content` fornecia o
+heading principal, a raiz mantinha os `0.75rem` próprios de uma seção interna.
+
+## Decisão
+
+`Content` deixa de expor `variant`. O nível semântico passa a selecionar a única apresentação
+válida para esse componente:
+
+- `level={1}` identifica o conteúdo principal, usa a escala de `PageHeader` e separa header e body
+  por `1.5rem` no layout contínuo;
+- níveis de 2 a 6 identificam seções internas e preservam a escala e o intervalo de `0.75rem`;
+- `fieldset` permanece uma seção interna: sua legenda não participa da hierarquia de headings.
+
+`Page` continua sendo a superfície estrutural, e `heading: "content"` continua declarando na
+`Presentation` quem possui o heading principal. A decisão não transforma `Content` em `Page`; ela
+remove uma escolha visual que não tinha significado independente dentro de `Content`.
+
+## Consequências
+
+- combinações contraditórias deixam de ser representáveis;
+- consumidores removem `variant="page"` e preservam `level={1}`;
+- o ritmo do conteúdo principal fica igual ao de páginas cujo heading pertence a `PageHeader`;
+- a remoção da propriedade é incompatível e exige migração coordenada dos consumidores;
+- a escala interna continua centralizada em `SurfaceHeader`, sem duplicação no consumidor.
+
+## Alternativas descartadas
+
+### Manter variant e corrigir somente o espaço
+
+Corrigiria o sintoma visual, mas preservaria a duplicação e os estados inválidos no contrato.
+
+### Renomear variant para role
+
+Tornaria a intenção mais explícita, porém continuaria exigindo duas propriedades para declarar o
+mesmo papel e permitiria que elas divergissem.
+
+### Derivar a apresentação da presença em Page
+
+Acoplaria `Content` ao local de renderização. O heading principal já é declarado diretamente por
+`level={1}` e pode ser validado por `Page` sem outro contexto implícito.
+
+## Verificação
+
+- testes de `Content` confirmam escala e intervalo de página no nível 1 e de seção nos demais;
+- tipos e exemplos públicos não aceitam mais `variant` em `Content`;
+- testes de `Page`, `Presentation` e preenchimento preservam `Content level={1}` como heading
+  principal;
+- consumidores compilam sem `variant="page"`.

package/docs/adr/0039-filter-presentation-is-independent-from-filter-type.md

@@ -0,0 +1,62 @@
+# ADR 0039 — A apresentação do filtro é independente de seu tipo
+
+- **Status:** aceita.
+- **Data:** 2026-09-29.
+- **Complementa:** ADR 0019.
+
+## Contexto
+
+`FilterSpec` declara o significado e o transporte de cada filtro, mas a interface apresentava todo
+filtro `select` com o mesmo controle. Escolhas únicas, curtas e mutuamente exclusivas — como um
+canal com três opções — continuavam escondidas em um menu mesmo quando a comparação direta entre
+as alternativas era mais útil.
+
+Transformar `toggle` em um novo `type` misturaria apresentação com valor: tanto o menu quanto o
+grupo produzem a mesma string, ocupam o mesmo campo no estado navegável e chegam sem mudança à
+action.
+
+## Decisão
+
+`FilterSpec` passa a aceitar `presentation: "select" | "toggle"`. A ausência da propriedade
+preserva `select` como apresentação padrão.
+
+`toggle` aplica-se a filtros `type: "select"` de escolha única e usa as mesmas opções, valor de
+repouso, regra de vazio, dependências e atualização de estado do controle padrão. A apresentação
+mostra todas as opções em um `ToggleGroup` conectado e não permite desmarcar a opção ativa quando o
+filtro não aceita vazio. Quando a opção vem de um dicionário e sua entrada declara um ícone do
+catálogo, o grupo apresenta ícone e rótulo juntos.
+
+O tipo do filtro continua descrevendo o valor e sua operação. A apresentação escolhe somente o
+controle usado para editá-lo.
+
+## Consequências
+
+- contratos podem expor escolhas pequenas e fechadas sem reconstruir a barra no consumidor;
+- URL, input da action, defaults e handlers permanecem inalterados;
+- filtros existentes continuam usando `Select` sem migração;
+- `toggle` não se aplica a seleção múltipla, lookup, texto, número ou data;
+- conjuntos extensos ou pesquisáveis continuam usando `Select`.
+
+## Alternativas descartadas
+
+### Criar `type: "toggle"`
+
+Duplicaria a semântica de `select` e exigiria que serialização, validação e adaptadores conhecessem
+um tipo cujo valor não mudou.
+
+### Compor o ToggleGroup em cada página
+
+Preservaria o contrato incompleto e duplicaria a sincronização entre controle, URL, default e input
+efetivo da action.
+
+### Trocar automaticamente selects com poucas opções
+
+Quantidade de opções não determina a melhor apresentação. O contrato precisa declarar a intenção,
+sem uma heurística visual invisível.
+
+## Verificação
+
+- teste do `ActionFilterBar` confirma que `presentation: "toggle"` renderiza todas as opções e
+  atualiza o mesmo campo de filtro;
+- teste de regressão confirma que um `select` sem apresentação continua usando `Select`;
+- typecheck impede valores de apresentação fora do vocabulário público.

package/docs/adr/0040-tabs-use-a-single-navigation-presentation.md

@@ -0,0 +1,60 @@
+# ADR 0040 — Tabs usa uma única apresentação de navegação
+
+- **Status:** aceita.
+- **Data:** 2026-09-29.
+- **Substitui parcialmente:** ADR 0032, ADR 0034 e ADR 0036 quanto à escolha de variante em `TabsList`.
+
+## Contexto
+
+`TabsList` oferecia uma superfície preenchida e uma variante com linha. A superfície preenchida
+ficava visualmente próxima de um controle segmentado, embora `Tabs` represente navegação entre
+painéis e um `ToggleGroup` represente escolha de valores. A mesma aparência para comportamentos
+diferentes dificultava escolher o componente correto e levou filtros a serem descritos como tabs.
+
+## Decisão
+
+`TabsList` usa somente a linha de navegação e deixa de aceitar `variant`. Cada `TabsListItem`
+continua associado a um `TabsPanel` pelo mesmo valor. Orientação, tamanho, distribuição e moldura
+permanecem propriedades independentes do conjunto.
+
+A anatomia pública nomeia a posição de cada parte: `TabsListItem` pertence a `TabsList`, enquanto
+`TabsPanel` identifica o painel associado. Os nomes anteriores, `TabsTrigger` e `TabsContent`, não
+são mantidos como aliases porque há um único consumidor e a migração é atômica.
+
+Escolhas únicas ou múltiplas que alteram um valor no contexto atual usam `ToggleGroup`. Quando o
+grupo precisa de um contorno conectado, o consumidor declara `variant="outline"` com `spacing={0}`;
+a borda pertence aos itens e as arestas internas duplicadas são removidas pela primitiva.
+
+## Consequências
+
+- Tabs mantém uma identidade visual única e vinculada à navegação entre painéis.
+- Filtros e escolhas de formulário não usam semântica de tabs para obter uma aparência compacta.
+- Consumidores removem `variant="line"`; não há substituição para a antiga superfície preenchida.
+- Consumidores renomeiam `TabsTrigger` para `TabsListItem` e `TabsContent` para `TabsPanel`.
+- A documentação de ToggleGroup explicita como formar o contorno conectado.
+
+## Alternativas descartadas
+
+### Manter duas variantes em TabsList
+
+Preservaria flexibilidade visual, mas manteria a ambiguidade entre navegação e escolha de valor.
+
+### Compartilhar uma apresentação segmentada entre Tabs e ToggleGroup
+
+Permitiria a mesma aparência com semânticas distintas, mas não resolveria a dificuldade de leitura
+observada no produto. A linha torna a navegação reconhecível sem depender do contexto ao redor.
+
+### Preservar Trigger e Content como nomes públicos
+
+Manteria proximidade com a primitiva subjacente, mas nomearia mecanismo e conteúdo genérico em vez
+da anatomia exposta ao consumidor. `ListItem` e `Panel` deixam a composição legível no JSX.
+
+## Verificação
+
+- o tipo público de `TabsList` não aceita `variant`;
+- a exportação pública oferece `TabsListItem` e `TabsPanel`, sem aliases para os nomes anteriores;
+- testes da primitiva confirmam a linha-base, o indicador ativo e a distribuição;
+- testes do `ActionFilterBar` confirmam que `presentation: "toggle"` usa seleção exclusiva sem
+  alterar o estado transportado para a action;
+- a documentação de Tabs não oferece apresentação preenchida e a de ToggleGroup demonstra o grupo
+  conectado com borda.

package/docs/code-style.md

@@ -115,7 +115,7 @@ O extrator cobre três superfícies, sem heurística de nome:
    reprovam em vez de serem executadas e o dicionário mantém um snapshot imutável das entradas;
 3. texto estático em filhos e props de uma allowlist de componentes importados diretamente
    de `@softize/opus/ui*` — por exemplo, `Button`, `DialogTitle`, `DialogBody`,
-   `FieldLabel`, `TabsTrigger`, `Page`, `Input` e `DataState`. Alias e namespace de import
+   `FieldLabel`, `TabsListItem`, `Page`, `Input` e `DataState`. Alias e namespace de import
    continuam rastreáveis. `uppercase`, variantes como `sm:hover:uppercase`, modificadores
    `!uppercase`/`uppercase!` e classes em descendentes são projetados na superfície que
    realmente herda o CSS. Props específicas também respeitam a implementação: por exemplo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "22.2.0",
+  "version": "23.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -52,7 +52,7 @@ ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader`
   `toolbarActions` fica reservado a operações que dependem do recorte atual.
 - Card, Drawer e Pane nomeiam a região principal como `CardBody`, `DrawerBody` e `PaneBody`.
   `*Content` permanece reservado a raízes técnicas ou painéis cujo papel não é o corpo de uma
-  estrutura, como `DialogContent`, `PopoverContent` e `TabsContent`.
+  estrutura, como `DialogContent`, `PopoverContent` e `TabsPanel`.
 - Componentes compartilhados não impõem margem externa; páginas e shells compõem layout.
 - A UI assume layout desktop fixo e largura mínima suportada de `64rem`. Não introduzir
   breakpoints de viewport ou container queries isoladas; uma futura responsividade precisa começar

package/registry/skills/create-opus-action/references/contract-and-binding.md

@@ -1,9 +1,9 @@
 # Contrato e binding
 
 O contrato contém `name`, `kind`, documentação, schemas, metadata de UI e autorização
-declarativa compartilhável. Ele não declara dados de design: no modo design, a action sem mock já
-responde com dado gerado a partir do `output`, e um cenário específico, quando necessário, fica
-fora do contrato em `defineDesignScenario` (ADR 0037). `mockHandler` está obsoleto.
+declarativa compartilhável. Ele não declara dados de design: no modo design, a action responde
+com dado gerado a partir do `output`, e um cenário específico, quando necessário, fica fora do
+contrato em `defineDesignScenario` (ADR 0037).
 
 O binding contém `handler`, `loads`, autorização dependente de dados carregados, execução
 em background, eventos e idempotência. `bindAction(contract, binding)` produz o `ActionDef`

package/src/core/contracts.ts

@@ -42,7 +42,7 @@ type BindingKeys = 'handler' | 'loads' | 'background' | 'emits' | 'idempotency'
  * `ParsedIn` (o lado PARSEADO do schema de input — defaults aplicados) defaulta
  * a `any` nos contratos, de propósito: quem anota contrato à mão é o CLIENTE
  * (`FormContract<MeuInput, MeuOutput>` em hooks/props), que só conhece o fio —
- * e `authorize`/`mockHandler` são contravariantes em `ParsedIn`, então um
+ * e `authorize` é contravariante em `ParsedIn`, então um
  * default estreito rejeitaria contrato real cujo schema tem `.default()`.
  * Quem precisa do parseado com precisão (`bindAction`) o infere do schema.
  */

package/src/core/runtime.ts

@@ -833,16 +833,7 @@ export class Runtime {
       }
 
       // — 5. Handler ————————————————————————————————————————————————————————
-      // Modo design (`OPUS_MODE=design`): tenta mockHandler primeiro, cai
-      // no handler real se não houver. Em qualquer outro modo, handler real
-      // sempre manda. Leitura de env mora aqui, no boundary do execute — o
-      // resto do core continua sem tocar `process.env`.
-      const isDesignMode = isOpusDesignMode()
-      const handlerToRun =
-        isDesignMode && action.mockHandler !== undefined
-          ? action.mockHandler
-          : action.handler
-      const output = await handlerToRun(
+      const output = await action.handler(
         ctx,
         validatedInput,
         loaded,
@@ -850,8 +841,6 @@ export class Runtime {
           ? progress
           : undefined,
       )
-      const usedMock = handlerToRun === action.mockHandler
-
       // — 6. Validate output (dev only) —————————————————————————————————————
       // Search retorna Paginated<Item> mas `output` schema descreve só Item;
       // skipamos pra evitar falso negativo. v1 pode validar items[].
@@ -874,7 +863,6 @@ export class Runtime {
           ctx,
           input: validatedInput,
           output: validatedOutput,
-          mode: usedMock ? 'design' : undefined,
         }),
         action.audit,
       )
@@ -1271,8 +1259,6 @@ export class Runtime {
     input: unknown
     output?: unknown
     error?: ReturnType<typeof error>
-    /** Quando `'design'`, sinaliza que o mockHandler foi executado. */
-    mode?: 'design' | undefined
   }): AuditRecord {
     const record: AuditRecord = {
       id: args.actionId,
@@ -1293,13 +1279,12 @@ export class Runtime {
     if (args.nature !== undefined) {
       const effect = resolveActionEffect(args.nature)
       if (effect !== undefined) record.effect = effect
-      // A exposição só existe quando a action devolveu algo: erro não expõe o dado declarado, e a
-      // resposta simulada do modo design (mock, cenário ou gerada) não é de ninguém.
-      if (args.nature.personalData === true && args.outcome === 'success' && args.mode !== 'design') {
+      // A exposição só existe quando a action devolveu algo. O plugin de design remove o marcador
+      // das respostas simuladas antes de registrar a action no runtime.
+      if (args.nature.personalData === true && args.outcome === 'success') {
         record.personalData = { records: countReturnedRecords(args.nature.kind, args.output) }
       }
     }
-    if (args.mode !== undefined) record.meta = { mode: args.mode }
     return record
   }
 
@@ -2095,21 +2080,3 @@ function generateId(): string {
   // fallback determinístico-suficiente quando crypto não disponível
   return `id_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`
 }
-
-/**
- * Único ponto do core que lê `process.env`. Usado pelo `execute()` pra
- * decidir entre `handler` real e `mockHandler`. Isolado em função pra
- * testabilidade — testes podem `vi.stubEnv('OPUS_MODE', ...)`.
- *
- * Mantém a invariante "core nunca lê env" intacta no resto do código:
- * adapters/config seguem recebendo valores literais.
- *
- * Exportado (fora do index público) pro harness de `testing` aplicar a MESMA
- * régua no `runAction` — a semântica de design mora num lugar só.
- */
-export function isOpusDesignMode(): boolean {
-  // Acesso via globalThis: defensivo pra runtimes sem `process` (browser, edge) E
-  // não exige @types/node no consumidor que compila este source (apps web).
-  const g = globalThis as { process?: { env?: Record<string, string | undefined> } }
-  return g.process?.env?.['OPUS_MODE'] === 'design'
-}