@softize/opus 22.2.0 → 24.0.0

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

@@ -6,8 +6,8 @@
 - Execução estrutural: montar uma página de relatório isolada com `Page > PageHeader + PageBody`,
   outra em `PageShell` com navegação contextual acima de `Page > PageHeader + PageBody`, garantindo
   exatamente um `PageTitle` no header, e uma coleção nomeada com
-  `Content > ContentHeader + ContentBody > ActionList`. Provar que criação fica em
-  `ContentActions`, no extremo oposto ao título, como botão textual `default` sem ícone e com
+  `Surface > SurfaceHeader + SurfaceBody > ActionList`. Provar que criação fica em
+  `SurfaceActions`, no extremo oposto ao título, como botão textual `default` sem ícone e com
   `Criar recurso`, enquanto uma operação dependente do recorte usa `toolbarActions`; incluir
   `ActionFilterBar` separado do renderer, `ItemGroup` para
   uma coleção secundária e um `ActionFormDialog`; provar teto padrão de `80rem`, hierarquia por
@@ -18,13 +18,14 @@
 - Execução roteável: declarar Page, criação e edição com `Presentation.route`; provar deep link,
   hidratação do registro, fechamento para a lista e projeção integral no manifest.
 - Execução abreviada: montar outra página com `<Page title actions>` e uma seção com
-  `<Content title description actions>`, provando que ambas produzem a mesma anatomia e que o lint
+  `<Surface title description actions>`, provando que ambas produzem a mesma anatomia e que o lint
   rejeita a mistura entre props abreviadas e headers explícitos.
-- Execução de forma: compor uma tabela dentro de Card sem moldura duplicada, manter a moldura
+- Execução de forma: compor uma tabela dentro de `Surface` sem moldura duplicada, manter a moldura
   estrutural standalone em `rounded-lg` e os controles internos em `rounded-md`.
-- Execução de Content seccionado: compor `Content framed layout="sectioned"` com mídia e
-  `DetailGroup` com divisores; provar header com divisor, body sem recuo e ausência de classes no
-  consumidor que reconstruam essa anatomia. Reprovar a combinação com `frameVariant="legend"`.
+- Execução de Surface seccionada: compor `Surface framed layout="sectioned"` com mídia e
+  `DetailGroup` com divisores; provar header com divisor, `SurfaceBody flush` sem recuo e ausência
+  de classes no consumidor que reconstruam essa anatomia. Provar `as="fieldset"` com `legend`
+  nativa sem `frameVariant`.
 - Reprova: criar uma casca `bg-card` que herda o texto global ou introduzir `rounded-widget`
   quando a escala `rounded-*` atende ao papel.
 - Reprova: trocar automaticamente o radius de um controle quando apenas seu tamanho muda ou
@@ -32,8 +33,8 @@
 - Reprova: reconstruir manualmente o container de página, usar `Empty` tracejado como vazio de
   tabela, alinhar toda coluna numérica à direita por inferência ou destacar “Cancelar” como ação
   primária em modal.
-- Reprova: deixar `ContentHeader` fora de `Content`, omitir `PageBody`/`ContentBody` na composição
-  explícita, usar `CardContent`/`PaneContent` em código novo ou tratar `DialogContent` como Body.
+- Reprova: deixar `SurfaceHeader` fora de `Surface`, omitir `PageBody`/`SurfaceBody` na composição
+  explícita, usar `Card*` ou `Content*` em código novo ou tratar `DialogContent` como Body.
 - Execução de dicionários: montar a lista de clientes com “Pessoa física/Empresa” e
   “Prospect/Cliente”; provar que o tipo ocupa a coluna “Tipo” como classificação (badge `outline`
   com os ícones declarados `user` e `building`), que o estágio ocupa a coluna “Estágio” como badge

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

@@ -9,7 +9,7 @@
   lista; não reconstruir essa decisão com condicionais no componente da página.
 - `Page` fornece o `<main>` e o container centralizado com teto padrão de `80rem`. Sua forma
   explícita exige `PageBody`, exatamente um heading principal e aceita `PageHeader` e `PageFooter`.
-  Declare esse heading com `PageTitle` no header, `Content level={1}` ou um `PageState` ativo no
+  Declare esse heading com `PageTitle` no header, `Surface level={1}` ou um `PageState` ativo no
   body. `PageHeader` é a única introdução estrutural e reúne navegação, título e ações. `title` e `actions` no
   próprio `Page` são a abreviação para o caso direto.
   Não misturar as duas formas. Alterar `className` apenas quando a superfície tiver uma necessidade
@@ -26,8 +26,8 @@
   ações somente com ícone de chrome usam `icon`. O tamanho `sm` fica para ações operacionais em
   toolbar, seção ou coleção densa, e `xs`/`icon-xs` para ações internas de linha ou célula. Contexto
   e variante resolvem a hierarquia visual sem alterar essa medida. Em uma coleção, a ação de
-  criar usa botão textual `default`, sem ícone, no extremo oposto do `ContentHeader`. Não monte
-  `PaneHeader`, portal ou seletor global para reconstruir essa composição.
+  criar usa botão textual `default`, sem ícone, no extremo oposto do `SurfaceHeader`. Não monte
+  cabeçalho paralelo, portal ou seletor global para reconstruir essa composição.
 - `PageState` substitui todo o conteúdo principal quando a página carrega, falha ou está vazia. Na
   forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma
   explícita, fica sozinho dentro de `PageBody`. Nos três estados ativos, o cabeçalho da Page
@@ -37,22 +37,23 @@
   `role="alert"`, usa a mesma composição central e sem moldura dos demais estados e apresenta a
   recuperação como botão `outline` textual. Estados de seção ou coleção continuam em `DataState`,
   `ActionView`, `ActionList` ou `Alert`; não elevar uma falha parcial a estado da página.
-- `Content` delimita uma seção e segue a mesma anatomia: `Content > ContentHeader (ContentTitle,
-ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader` nunca fica
-  solto. `title`, `description`, `count` e `actions` no `Content` são a abreviação para o caso
-  direto e não podem ser misturados ao header explícito. Na variante `page`, ações da coleção ficam
-  no extremo oposto ao título; a criação usa botão textual `default`, sem ícone, com `Criar recurso`.
+- `Surface` delimita uma região e segue a anatomia `Surface > SurfaceHeader (SurfaceMedia,
+SurfaceTitle, SurfaceDescription, SurfaceMeta, SurfaceActions) + SurfaceBody + SurfaceFooter`.
+  Os slots nunca ficam soltos. `title`, `description`, `count`, `media` e `actions` são a abreviação
+  para o caso direto e não podem ser misturados ao header explícito. Em `level={1}`, ações da
+  coleção ficam no extremo oposto ao título; a criação usa botão textual `default`, sem ícone, com
+  `Criar recurso`.
   O diálogo de criação usa `Criar recurso` e o de edição, `Editar recurso`. `level` preserva a
-  hierarquia semântica do heading. `Content framed` aceita `layout="sectioned"` quando o filho
-  direto já possui recuo interno, como `DetailGroup` com divisores, lista ou tabela: o header recebe
-  divisor e o body fica sem padding. `frameVariant="legend"` trata a borda contínua e não combina
-  com esse layout.
-- Uma página centrada em coleção compõe `Content + ActionList`. O `ContentHeader` recebe título e
+  hierarquia semântica do heading. `Surface framed` aceita `layout="sectioned"`; declare
+  `SurfaceBody flush` quando o filho direto já possui recuo interno, como `DetailGroup` com
+  divisores, lista ou tabela. `as="fieldset"` cria a `legend` nativa sem variante de moldura.
+- Uma página centrada em coleção compõe `Surface + ActionList`. O `SurfaceHeader` recebe título e
   criação; o `ActionList` mantém busca, filtros, atualização, resultados, estados e paginação.
   `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`.
+- `Surface` e Drawer nomeiam a região principal como `SurfaceBody` e `DrawerBody`. `Pane` é apenas
+  uma unidade dimensionável de `Split` e não possui anatomia interna. `*Content` permanece
+  reservado a raízes técnicas ou painéis cujo papel não é o corpo de uma 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/registry/templates/app/src/App.tsx

@@ -1,8 +1,13 @@
-import type { z } from 'zod'
-import { Badge, Card, DataState, useListAction } from '@softize/opus/ui/react'
-import { Task, taskList } from './domains/tasks/actions/list.ts'
+import type { z } from "zod";
+import {
+  Badge,
+  DataState,
+  Surface,
+  useListAction,
+} from "@softize/opus/ui/react";
+import { Task, taskList } from "./domains/tasks/actions/list.ts";
 
-type TaskItem = z.infer<typeof Task>
+type TaskItem = z.infer<typeof Task>;
 
 /** Página inicial do esqueleto: prova a fundação (tema + componentes do Opus) e o
  *  domínio-exemplo. Troque tudo — este arquivo é seu. */
@@ -10,14 +15,16 @@ export function App(): React.ReactElement {
   // O front consome o CONTRATO via /api — o plugin opusDesign (vite.config.ts)
   // serve o backend no próprio dev server: dev normal executa o handler real;
   // `pnpm dev:design` responde com dado gerado a partir do contrato, isolado de qualquer backend.
-  const { items, isLoading, error, refetch } = useListAction<TaskItem>(taskList)
+  const { items, isLoading, error, refetch } =
+    useListAction<TaskItem>(taskList);
 
   return (
     <main className="flex min-h-full items-center justify-center bg-background p-6">
-      <Card className="w-full max-w-md p-6">
-        <h1 className="mb-1 text-lg font-semibold">{'{{APP_NAME}}'}</h1>
+      <Surface framed elevation="raised" className="w-full max-w-md p-6">
+        <h1 className="mb-1 text-lg font-semibold">{"{{APP_NAME}}"}</h1>
         <p className="mb-4 text-sm text-muted-foreground">
-          Esqueleto criado pelo opus create. A spec vive nas declarações do domínio.
+          Esqueleto criado pelo opus create. A spec vive nas declarações do
+          domínio.
         </p>
         {/* Carregando, erro e vazio saem do DataState; a lista só cuida dos itens. */}
         <DataState
@@ -29,14 +36,19 @@ export function App(): React.ReactElement {
         >
           <ul className="space-y-2">
             {items.map((t) => (
-              <li key={t.id} className="flex items-center justify-between gap-2 text-sm">
+              <li
+                key={t.id}
+                className="flex items-center justify-between gap-2 text-sm"
+              >
                 <span>{t.title}</span>
-                <Badge context={t.done ? 'success' : 'neutral'}>{t.done ? 'Feita' : 'Aberta'}</Badge>
+                <Badge context={t.done ? "success" : "neutral"}>
+                  {t.done ? "Feita" : "Aberta"}
+                </Badge>
               </li>
             ))}
           </ul>
         </DataState>
-      </Card>
+      </Surface>
     </main>
-  )
+  );
 }

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'
-}

package/src/core/types.ts

@@ -638,6 +638,9 @@ export interface FilterSpec {
 
   type: 'text' | 'select' | 'lookup' | 'date' | 'number'
   multiple?: boolean
+  /** Controle usado para um `select` de escolha única. `select` é o padrão; `toggle`
+   *  mantém todas as opções curtas visíveis em um grupo conectado. */
+  presentation?: 'select' | 'toggle'
   /** Habilita busca local nas opções de um `select`; `lookup` já é pesquisável por natureza. */
   searchable?: boolean
   /** Quando `false`, a interface omite a opção vazia. Limpar restaura o default do filtro. */
@@ -799,7 +802,7 @@ export type LoadersSpec<In> = Record<string, LoaderFn<In>>
  *     aqui.
  *   - **`ParsedIn`** — o lado PARSEADO (o output do schema de input, defaults
  *     aplicados). O runtime SEMPRE valida antes de executar, então `handler`,
- *     `mockHandler`, `authorize` e `loads` recebem `ParsedIn`.
+ *     `handler`, `authorize` e `loads` recebem `ParsedIn`.
  *
  * O default `ParsedIn = In` mantém retrocompat com anotações à mão de dois
  * genéricos; `defineAction`/`defineContract` inferem os dois lados do schema.
@@ -848,16 +851,6 @@ export interface ActionBase<In, Out, ParsedIn = In> {
   // — Execução —
   handler: HandlerFn<ParsedIn, Out>
 
-  /**
-   * Handler alternativo executado quando `process.env.OPUS_MODE === 'design'`.
-   *
-   * @deprecated Desde a 22.1.0 (ADR 0037); sai na próxima major. No modo design, a action sem
-   * mock já responde com dado gerado a partir do `output`; quando o design precisar de uma resposta
-   * específica, declare um cenário fora do contrato com `defineDesignScenario`, de
-   * `@softize/opus/design`, e aponte a opção `scenarios` do `opusDesign()` para ele.
-   */
-  mockHandler?: HandlerFn<ParsedIn, Out>
-
   // — Comportamento —
   audit?: boolean | AuditConfig
   confirm?: ConfirmSpec
@@ -922,24 +915,13 @@ export interface SearchFilters {
  * envelope — handler é fonte de verdade.
  */
 export interface ListAction<In, Out, ParsedIn = In>
-  extends Omit<ActionBase<In, Out, ParsedIn>, 'handler' | 'mockHandler'> {
+  extends Omit<ActionBase<In, Out, ParsedIn>, 'handler'> {
   kind: 'list'
   handler: (
     ctx: ActionContext,
     input: ParsedIn,
     loaded?: Record<string, unknown>,
   ) => Paginated<Out> | Promise<Paginated<Out>>
-  /**
-   * Mesma semântica de `ActionBase.mockHandler`, mas devolve `Paginated<Out>`
-   * (search retorna lista paginada, não item solto).
-   *
-   * @deprecated Desde a 22.1.0 (ADR 0037); ver `ActionBase.mockHandler`.
-   */
-  mockHandler?: (
-    ctx: ActionContext,
-    input: ParsedIn,
-    loaded?: Record<string, unknown>,
-  ) => Paginated<Out> | Promise<Paginated<Out>>
   /** Colunas declarativas da listagem (a UI deriva a tabela; ver ListColumnSpec). */
   columns?: ListColumnSpec[]
   filters?: Record<string, FilterSpec>

package/src/design/index.ts

@@ -9,7 +9,7 @@
  * respostas ao runtime de design.
  */
 
-import { z } from 'zod'
+import type { ZodTypeAny } from 'zod'
 import type { ActionContext, InferOutput, Paginated } from '../core/types.ts'
 import { fake, fakeMany } from '../testing/fake.ts'
 
@@ -102,11 +102,14 @@ interface DesignActionShape {
  * - `list` devolve três páginas do tamanho pedido em `limit` ({@link DESIGN_PAGE_SIZE} quando a
  *   entrada não pede) e respeita a paginação declarada; busca e filtros não filtram o dado gerado.
  * - Nas demais, a saída ecoa o `id` da entrada quando o schema da saída aceita esse valor.
- * - Saída que não é schema zod não tem gerador: a resposta é `null`.
+ * - Saída que não é schema Zod não tem gerador: a resposta é `null`.
  */
 export function designResponse(action: DesignActionShape, input: unknown): unknown {
   const output = action.output
-  if (!(output instanceof z.ZodType)) return null
+  // O contrato vem do grafo do consumidor e pode carregar outra instância física do Zod.
+  // `instanceof` confundiria identidade de módulo com contrato; o gerador usa somente a
+  // estrutura pública/estável que já recebe (`safeParse`) e a definição introspectável (`_def`).
+  if (!isZodSchema(output)) return null
   const seed = `${action.name}:${canonicalJson(withoutPagination(input))}`
 
   if (action.kind === 'list') {
@@ -177,3 +180,11 @@ function canonicalJson(value: unknown): string {
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
+
+function isZodSchema(value: unknown): value is ZodTypeAny {
+  return (
+    isRecord(value) &&
+    isRecord(value._def) &&
+    typeof value.safeParse === 'function'
+  )
+}

package/src/testing/index.ts

@@ -14,8 +14,6 @@
  *     valida output (pulado em `list`, como no runtime). Falha estoura o MESMO
  *     `ActionError` tipado do runtime (`validation.invalid_input`, `auth.unauthenticated`,
  *     `auth.system_forbidden`, `auth.forbidden`…). A opção `schedule` executa como o sistema.
- *     Em `OPUS_MODE=design` roteia pro `mockHandler` como o runtime — contrato puro
- *     (sem handler) é testável em design; fora dele, erro claro (`testing.no_handler`).
  *   • `memStorage()` — StorageAdapter em memória pra testar handler que anexa
  *     arquivo, com a mesma régua de key dos drivers reais.
  *
@@ -30,9 +28,7 @@ import { evalExpression } from '../dsl/eval.ts'
 import { parseExpression } from '../dsl/parser.ts'
 import { normalizeKey } from '../storage/index.ts'
 import { error } from '../core/errors.ts'
-// Import direto do runtime (fora do index público): a régua handler×mockHandler
-// tem UMA fonte — o harness nunca pode divergir do execute().
-import { assertAuthenticated, isOpusDesignMode, markSystemActor } from '../core/runtime.ts'
+import { assertAuthenticated, markSystemActor } from '../core/runtime.ts'
 import type {
   ActionContext,
   ActionKind,
@@ -206,14 +202,8 @@ export interface TestableAction<In, Out, ParsedIn = In> {
   authorize?: AuthorizeSpec<ParsedIn>
   input: Schema<In, ParsedIn>
   output: Schema<Out> | Schema<unknown, Out>
-  /** Opcional: contrato puro (sem handler) só executa pelo `mockHandler` obsoleto. */
+  /** Opcional para produzir um erro útil quando um contrato puro chega ao harness. */
   handler?: HandlerFn<ParsedIn, Out>
-  /**
-   * Em `OPUS_MODE=design` vence o handler real — mesma régua do runtime.
-   *
-   * @deprecated Desde a 22.1.0 (ADR 0037); teste a action ligada ao handler.
-   */
-  mockHandler?: HandlerFn<ParsedIn, Out>
 }
 
 /** Variante list: o schema descreve o ITEM, o handler devolve `Paginated<Item>`. */
@@ -230,11 +220,6 @@ export interface TestableListAction<In, Item, ParsedIn = In> {
     input: ParsedIn,
     loaded?: Record<string, unknown>,
   ) => Paginated<Item> | Promise<Paginated<Item>>
-  mockHandler?: (
-    ctx: ActionContext,
-    input: ParsedIn,
-    loaded?: Record<string, unknown>,
-  ) => Paginated<Item> | Promise<Paginated<Item>>
 }
 
 export interface RunActionOptions extends TestContextOptions {
@@ -278,9 +263,8 @@ async function validate<T>(
  * validado + o contexto observável (`emitted`, `logged`); falha estoura o mesmo
  * `ActionError` do runtime — afirme com `expect(...).rejects`.
  *
- * A escolha do executável segue a régua do `execute()`: em `OPUS_MODE=design`,
- * `mockHandler` presente vence; senão, `handler` real. Contrato puro (sem
- * handler) só roda em design — fora dele, `testing.no_handler`.
+ * Contrato puro sem handler termina em `testing.no_handler`: dados de design
+ * pertencem ao plugin `opusDesign()` e não são comportamento da action.
  */
 export async function runAction<In, Item, ParsedIn = In>(
   action: TestableListAction<In, Item, ParsedIn>,
@@ -325,18 +309,14 @@ export async function runAction<In, Out, ParsedIn = In>(
     if (decision !== true) throw decision
   }
 
-  const handlerToRun =
-    isOpusDesignMode() && action.mockHandler !== undefined
-      ? action.mockHandler
-      : action.handler
-  if (handlerToRun === undefined) {
+  if (action.handler === undefined) {
     throw error({
       code: 'testing.no_handler',
       category: 'internal',
       message: `Action "${action.name}" não tem handler executável: teste o ActionDef produzido pelo bindAction. Os dados do modo design são gerados pelo plugin opusDesign() e não são comportamento da action.`,
     })
   }
-  const raw = await handlerToRun(ctx, parsed, loaded)
+  const raw = await action.handler(ctx, parsed, loaded)
 
   // Mesmo skip do runtime: list devolve Paginated<Item>, o schema descreve Item.
   const output = action.kind === 'list' ? (raw as Out) : await validate<Out>(action.output, raw, 'output')

package/src/ui/appearance.ts

@@ -0,0 +1,149 @@
+/**
+ * @softize/opus/ui/appearance — personalização de aparência sem React (ADR 0044).
+ *
+ * O tema deriva a escala neutra de quatro eixos inteiros (0 a 100) declarados por modo em
+ * `theme.css`: `--appearance-light-*` e `--appearance-dark-*`. Este módulo publica os tipos, os
+ * presets oficiais e o helper que converte overrides parciais nas custom properties que o
+ * consumidor aplica onde quiser (em geral, inline em `<html>`).
+ *
+ * Reset não pertence ao Opus UI: um eixo sem override vira `null`, e o consumidor remove a
+ * propriedade para voltar ao cascade — ou seja, ao preset do tema ou ao CSS do próprio app.
+ * Persistência e interface de ajuste também ficam com o consumidor.
+ */
+
+export type AppearanceMode = "light" | "dark";
+
+export const appearanceModes = [
+  "light",
+  "dark",
+] as const satisfies readonly AppearanceMode[];
+
+export type AppearanceAxis =
+  "colorIntensity" | "contrast" | "surfaceBrightness" | "layerContrast";
+
+/** Ordem canônica dos eixos: a mesma usada em documentação, presets e custom properties. */
+export const appearanceAxes = [
+  "colorIntensity",
+  "contrast",
+  "surfaceBrightness",
+  "layerContrast",
+] as const satisfies readonly AppearanceAxis[];
+
+/** Valor completo de um modo: todo eixo é um inteiro entre `APPEARANCE_MIN` e `APPEARANCE_MAX`. */
+export type AppearanceSettings = Readonly<Record<AppearanceAxis, number>>;
+
+/** Override parcial: eixo ausente (ou não finito) segue o cascade em vez de ser reescrito. */
+export type AppearanceOverrides = Partial<
+  Record<AppearanceAxis, number | null | undefined>
+>;
+
+export const APPEARANCE_MIN = 0;
+export const APPEARANCE_MAX = 100;
+
+/**
+ * Presets oficiais por modo — reproduzem exatamente os valores do tema sem personalização.
+ * Intensidade, contraste e contraste entre camadas partem de zero: o preset é o piso, e o ajuste
+ * só acrescenta cor ou separação. No claro, a superfície elevada já é branca; o brilho parte do
+ * máximo e só pode diminuir. No escuro, o brilho fica no meio para permitir um escuro mais
+ * profundo ou mais suave.
+ */
+export const appearancePresets: Readonly<
+  Record<AppearanceMode, AppearanceSettings>
+> = {
+  light: {
+    colorIntensity: 0,
+    contrast: 0,
+    surfaceBrightness: 100,
+    layerContrast: 0,
+  },
+  dark: {
+    colorIntensity: 0,
+    contrast: 0,
+    surfaceBrightness: 50,
+    layerContrast: 0,
+  },
+};
+
+const AXIS_PROPERTY: Record<AppearanceAxis, string> = {
+  colorIntensity: "color-intensity",
+  contrast: "contrast",
+  surfaceBrightness: "surface-brightness",
+  layerContrast: "layer-contrast",
+};
+
+export type AppearanceCustomProperty =
+  `--appearance-${AppearanceMode}-${string}`;
+
+/** Nome da custom property que `theme.css` lê para um eixo de um modo. */
+export function appearanceCustomProperty(
+  mode: AppearanceMode,
+  axis: AppearanceAxis,
+): AppearanceCustomProperty {
+  return `--appearance-${mode}-${AXIS_PROPERTY[axis]}`;
+}
+
+/**
+ * Normaliza um valor de eixo: arredonda para inteiro e limita ao intervalo. Retorna `undefined`
+ * para o que não é um número finito — o consumidor pode ter lido um valor corrompido de
+ * persistência, e a resposta correta é seguir o cascade, não travar a interface.
+ */
+export function normalizeAppearanceValue(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  return Math.min(APPEARANCE_MAX, Math.max(APPEARANCE_MIN, Math.round(value)));
+}
+
+/** Preset do modo com os overrides válidos aplicados por cima. */
+export function resolveAppearance(
+  mode: AppearanceMode,
+  overrides: AppearanceOverrides = {},
+): AppearanceSettings {
+  const preset = appearancePresets[mode];
+  const resolved = { ...preset } as Record<AppearanceAxis, number>;
+  for (const axis of appearanceAxes) {
+    const value = normalizeAppearanceValue(overrides[axis]);
+    if (value !== undefined) resolved[axis] = value;
+  }
+  return resolved;
+}
+
+/**
+ * Converte overrides parciais nas custom properties do modo. Todo eixo aparece no resultado:
+ * com valor normalizado quando há override e `null` quando não há, para o consumidor remover a
+ * propriedade e deixar o cascade valer. Assim, o mesmo mapa serve para aplicar e para desfazer.
+ */
+export function appearanceCustomProperties(
+  mode: AppearanceMode,
+  overrides: AppearanceOverrides = {},
+): Record<AppearanceCustomProperty, string | null> {
+  const properties = {} as Record<AppearanceCustomProperty, string | null>;
+  for (const axis of appearanceAxes) {
+    const value = normalizeAppearanceValue(overrides[axis]);
+    properties[appearanceCustomProperty(mode, axis)] =
+      value === undefined ? null : String(value);
+  }
+  return properties;
+}
+
+/** Alvo mínimo para aplicar propriedades: `CSSStyleDeclaration` satisfaz, e um stub de teste também. */
+export interface AppearanceStyleTarget {
+  setProperty(name: string, value: string): void;
+  removeProperty(name: string): string | void;
+}
+
+/**
+ * Aplica os overrides de um modo num alvo de estilo. Eixos sem override são removidos, então
+ * chamar sem overrides devolve o elemento ao cascade — é o reset, feito pelo consumidor, sem
+ * estado no Opus.
+ */
+export function applyAppearanceCustomProperties(
+  target: AppearanceStyleTarget,
+  mode: AppearanceMode,
+  overrides: AppearanceOverrides = {},
+): void {
+  for (const [name, value] of Object.entries(
+    appearanceCustomProperties(mode, overrides),
+  )) {
+    if (value === null) target.removeProperty(name);
+    else target.setProperty(name, value);
+  }
+}