@softize/opus 21.0.1 → 22.1.0

package/docs/radius-scale.md

@@ -2,6 +2,9 @@
 
 > **Status: decidido (ago/2026).** A forma usa uma escala contínua do Tailwind; o nome do
 > componente não cria um segundo conjunto de tokens.
+>
+> **Atualização (2026-09-28).** A ADR 0033 conclui a validação que este documento deixou pendente e
+> aplica `rounded-xl` ao Drawer junto da sua nova moldura recuada.
 
 ## Contexto
 
@@ -42,8 +45,8 @@ voltaria a acoplar forma e tipo de componente, problema removido na versão 10.0
   `--radius` alcançar também os extremos usados pelo Opus. `rounded-3xl` continua nativo do
   Tailwind; aplicações que usam esse degrau precisam revisar a fronteira ao alterar a base.
 - Novos componentes podem escolher uma utility da escala sem inventar vocabulário próprio.
-- Drawer e outras superfícies presas à viewport não mudam neste entregável. Arredondar somente os
-  cantos expostos exige validar clipping, scroll e conteúdo full-bleed em uma mudança própria.
+- Naquele entregável, Drawer e outras superfícies presas à viewport não mudaram. A ADR 0033 fez a
+  validação própria de clipping, scroll e conteúdo full-bleed e passou o Drawer para `rounded-xl`.
 
 ## Alternativas descartadas
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "21.0.1",
+  "version": "22.1.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -173,6 +173,10 @@
       "types": "./src/seed/index.ts",
       "default": "./src/seed/index.ts"
     },
+    "./design": {
+      "types": "./src/design/index.ts",
+      "default": "./src/design/index.ts"
+    },
     "./presentation": {
       "types": "./src/presentation/index.ts",
       "default": "./src/presentation/index.ts"

package/registry/skills/build-opus-ui/SKILL.md

@@ -43,18 +43,21 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
 7. Tratar página, filtro, seleção e modal importante como estado navegável por URL quando
    o produto precisa de deep link, back/forward ou refresh. Em `Presentation`, declarar `route`
    no artefato e deixar o adaptador apenas conectar a spec ao router da aplicação.
-8. Compor superfícies pela gramática estrutural do catálogo: `PageHeader` declara o chrome,
-   `PageIntro` a introdução opcional e `PageBody` o conteúdo. Na composição explícita, declare
-   exatamente um heading principal com `PageTitle` no header/intro, `Content level={1}` ou um
-   `PageState` ativo no body;
-   dentro de `PageShell`, os slots de
-   `PageHeader` são projetados na barra. `Content` contém `ContentHeader` e `ContentBody`; Card,
+8. Compor superfícies pela gramática estrutural do catálogo: `PageHeader` é a única introdução
+   estrutural e reúne navegação contextual opcional, título e ações; `PageBody` contém o conteúdo.
+   Na composição explícita, declare exatamente um heading principal com `PageTitle` no header,
+   `Content level={1}` ou um `PageState` ativo no body. `PageShell` pode fornecer navegação e ações
+   conhecidas pela aplicação, mas não cria uma barra visual. `Content` contém `ContentHeader` e `ContentBody`; Card,
    Drawer e Pane usam seus
    respectivos `*Body`. Para o caso direto, usar a sintaxe abreviada de `Page` (`title`,
    `actions`) ou de `Content` (`title`, `description`, `actions` e `count`); não misturá-la com o
    header explícito. O título da página não carrega contador. Ajustar o
    nível do heading pela hierarquia semântica, não pelo destaque visual. O `Page` mantém seu teto
    centralizado padrão de `80rem`.
+   Em `Content framed`, usar `layout="sectioned"` quando o filho direto já controlar o recuo do
+   body, como `DetailGroup` com divisores, lista ou tabela; não reconstruir divisor, padding ou
+   recorte por classes no consumidor. `frameVariant="legend"` continua sendo um acabamento da
+   borda contínua e não combina com o layout seccionado.
 9. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
    seu interior.
 10. Não definir a fonte raiz em uma biblioteca ou componente. O navegador e a aplicação são

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

@@ -4,8 +4,8 @@
 - Não dispara: “Ajuste o CSS de um e-mail estático.”
 - Execução: implementar uma lista com modal roteável e provar loading, erro, vazio e back.
 - Execução estrutural: montar uma página de relatório isolada com `Page > PageHeader + PageBody`,
-  outra em `PageShell` com `Page > PageHeader? + PageIntro? + PageBody`, garantindo exatamente um
-  `PageTitle` entre header/intro, e uma coleção nomeada com
+  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
   `Criar recurso`, enquanto uma operação dependente do recorte usa `toolbarActions`; incluir
@@ -22,6 +22,9 @@
   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
   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"`.
 - 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

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

@@ -8,25 +8,21 @@
   parâmetro podem declarar `route.record` para hidratar o item a partir de uma Presentation de
   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`, `PageIntro` e
-  `PageFooter`. Declare esse heading com `PageTitle` em header/intro, `Content level={1}` ou um
-  `PageState` ativo no body. `PageHeader`
-  declara chrome; `PageIntro` declara uma introdução opcional no conteúdo. `title` e `actions` no
+  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
+  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
   real de largura; não reconstruir esse container em cada rota.
-- `PageIntro` é a região estrutural de uma introdução no conteúdo. Pode coexistir com
-  `PageHeader`, porque as duas regiões têm papéis diferentes.
-- `PageHeader` declara navegação e ações globais; fora do shell também pode carregar o título. Em
-  uma subpágina simples, `PageBack` recebe o destino pai explícito e aparece
-  antes do título como controle somente com ícone. Para mais de um ancestral relevante, use
+- `PageHeader` declara navegação contextual, título e ações. Em uma subpágina simples, `PageBack`
+  recebe o destino pai explícito e aparece acima da linha do título como controle somente com
+  ícone. Para mais de um ancestral relevante, use
   `Breadcrumb` dentro de `PageNavigation`. Não combine retorno e breadcrumb nem crie um chrome
   paralelo para uma `Page`. `PageActionsTarget` fica reservado a workspaces imersivos que já
   possuam chrome próprio.
 - Quando shell e rota conhecem partes diferentes da mesma página, use `PageShell` ao redor da rota.
-  O shell é o único responsável pela barra e projeta os slots de `PageHeader`; `PageIntro` permanece
-  no conteúdo.
-  Ações com texto na barra usam o tamanho `default`, como as ações de footer de Dialog e Drawer;
+  O shell entrega navegação e ações ao `PageHeader` descendente sem criar uma barra visual.
+  Ações com texto no cabeçalho usam o tamanho `default`, como as ações de footer de Dialog e Drawer;
   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
@@ -34,9 +30,8 @@
   `PaneHeader`, 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 isolada
-  some inteiro — incluindo o `PageBack`; dentro de `PageShell`, `PageIntro` some e a barra
-  permanece. O estado ocupa a área disponível e seu título assume o heading
+  explícita, fica sozinho dentro de `PageBody`. Nos três estados ativos, o cabeçalho da Page
+  some inteiro — incluindo navegação e ações recebidas de `PageShell`. O estado ocupa a área disponível e seu título assume o heading
   principal, inclusive quando um componente intermediário renderiza o estado. Uma subpágina que
   dependa do retorno ao pai oferece essa saída pelo `action` do próprio `PageState`. O erro mantém
   `role="alert"`, usa a mesma composição central e sem moldura dos demais estados e apresenta a
@@ -48,7 +43,10 @@ ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader`
   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`.
   O diálogo de criação usa `Criar recurso` e o de edição, `Editar recurso`. `level` preserva a
-  hierarquia semântica do heading.
+  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
   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.

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

@@ -1,12 +1,14 @@
 # Contrato e binding
 
-O contrato contém `name`, `kind`, documentação, schemas, metadata de UI, autorização
-declarativa compartilhável e `mockHandler` de design quando aplicável.
+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.
 
 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`
 registrado no runtime.
 
 Ordem cobrada pelo check: identidade → documentação → input/output → autorização →
-handler/mock → comportamento. Campos específicos do kind permanecem junto do grupo ao qual
+handler → comportamento. Campos específicos do kind permanecem junto do grupo ao qual
 servem e o scaffold acompanha a forma atual do SDK.

package/registry/skills/create-opus-action/scripts/scaffold.mjs

@@ -18,7 +18,6 @@ ${common}
   input: z.object({}),
   output: z.object({ id: z.string() }),
   paginate: 'cursor',
-  mockHandler: async () => ({ items: [], cursor: { next: null }, total: 0 }),
 })`
   }
   if (kind === 'form') {
@@ -30,7 +29,6 @@ ${common}
   input: z.object({ id: z.string() }),
   output: z.object({ id: z.string() }),
   fields: { id: { label: 'Identificador' } },
-  mockHandler: async (_ctx, input) => ({ id: input.id }),
 })`
   }
   if (kind === 'view') {
@@ -40,7 +38,6 @@ ${common}
   description: 'Descreva o comportamento de negócio e seus limites.',
   input: z.object({ id: z.string() }),
   output: z.object({ id: z.string() }),
-  mockHandler: async (_ctx, input) => ({ id: input.id }),
 })`
   }
   return `export const ${identifier} = defineContract({
@@ -50,7 +47,6 @@ ${common}
   messages: { success: 'Operação concluída.', error: 'Não foi possível concluir.' },
   input: z.object({ id: z.string() }),
   output: z.object({ ok: z.boolean() }),
-  mockHandler: async () => ({ ok: true }),
 })`
 }
 

package/registry/skills/test-opus-action/SKILL.md

@@ -12,8 +12,8 @@ infraestrutura real quando a unidade é o contrato.
 
 ## Procedimento
 
-1. Importar o `ActionDef` produzido pelo binding; para contrato puro, testar `mockHandler`
-   apenas no modo design.
+1. Importar o `ActionDef` produzido pelo binding. Dados do modo design não são comportamento da
+   action e não entram nestes testes.
 2. Executar com `runAction` e fornecer `user`, `can`, `loaded`, storage ou outros adapters
    pelas opções do harness.
 3. Cobrir sucesso, input inválido, autorização negada e erros de negócio materiais.

package/registry/skills/test-opus-action/references/harness.md

@@ -6,5 +6,5 @@
 - `memStorage()`: adapter de storage em memória com inspeção de chaves.
 - `fake` e `fakeMany`: dados determinísticos derivados de schema.
 
-Prefira o binding completo em testes de execução. Um contrato sem handler só executa via
-`mockHandler` quando `OPUS_MODE=design`.
+Teste o binding completo. Um contrato sem handler falha com `testing.no_handler`: os dados do modo
+design são gerados pelo plugin `opusDesign()` e não são comportamento da action.

package/registry/templates/app/src/App.tsx

@@ -9,7 +9,7 @@ type TaskItem = z.infer<typeof Task>
 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 o mockHandler, isolado de qualquer backend.
+  // `pnpm dev:design` responde com dado gerado a partir do contrato, isolado de qualquer backend.
   const { items, isLoading, error, refetch } = useListAction<TaskItem>(taskList)
 
   return (

package/registry/templates/app/src/domains/tasks/actions/list.test.ts

@@ -1,6 +1,6 @@
-import { afterEach, describe, expect, it } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import { runAction } from '@softize/opus/testing'
-import { Task, taskList, taskListImpl } from './list.ts'
+import { taskListImpl } from './list.ts'
 
 // O harness roda o MESMO pipeline do runtime (valida input, cobra auth, valida
 // output) — teste pelo contrato, não chamando o handler à mão.
@@ -14,21 +14,4 @@ describe('task.list', () => {
   it('sem usuário, barra: a action não é pública', async () => {
     await expect(runAction(taskListImpl, {})).rejects.toMatchObject({ code: 'auth.unauthenticated' })
   })
-
-  describe('modo design (o que o `pnpm dev:design` serve)', () => {
-    afterEach(() => {
-      // OPUS_MODE é global do processo — limpa pra não vazar entre testes.
-      delete process.env['OPUS_MODE']
-    })
-
-    it('o contrato puro responde pelo mockHandler, com dado válido pro schema', async () => {
-      process.env['OPUS_MODE'] = 'design'
-      const { output } = await runAction(taskList, {}, { user: { id: 'u1' } })
-      expect(output.items.length).toBeGreaterThan(0)
-      // `list` pula a validação de output no pipeline — afirme item a item.
-      for (const item of output.items) {
-        expect(Task.safeParse(item).success).toBe(true)
-      }
-    })
-  })
 })

package/registry/templates/app/src/domains/tasks/actions/list.ts

@@ -1,14 +1,13 @@
 import { z } from 'zod'
 import { bindAction, defineContract } from '@softize/opus/core'
-import { fakeMany } from '@softize/opus/testing'
 
-/** Item do domínio-exemplo — o schema alimenta contrato, mock e testes. */
+/** Item do domínio-exemplo — o schema alimenta contrato, dados de design e testes. */
 export const Task = z.object({ id: z.string(), title: z.string(), done: z.boolean() })
 
 // O split canônico contrato↔handler: o CONTRATO é declarativo e roda nos dois
 // lados (a SPA consome via useListAction); o BINDING é server-only. Em
-// `pnpm dev:design` o mockHandler responde (dado fake do próprio schema);
-// no dev normal e em prod, o handler real do binding assume.
+// `pnpm dev:design` o plugin responde com dado gerado a partir do `output`
+// (ADR 0037); no dev normal e em prod, o handler real do binding assume.
 export const taskList = defineContract({
   name: 'task.list',
   kind: 'list',
@@ -19,7 +18,6 @@ export const taskList = defineContract({
   input: z.object({}),
   output: Task,
   paginate: 'cursor',
-  mockHandler: async () => ({ items: fakeMany(Task, 5), cursor: { next: null }, total: 5 }),
 })
 
 // Fixture em memória — o domínio-exemplo não tem banco; troque pelo seu repositório.

package/registry/templates/app/vite.config.ts

@@ -5,11 +5,12 @@ import { fileURLToPath } from 'node:url'
 
 /**
  * Modo design (`vite --mode design`, script dev:design): o runtime Opus sobe DENTRO do
- * dev server e os mockHandler dos contratos respondem o `/api` — preview autossuficiente,
+ * dev server e as actions respondem o `/api` com dado gerado a partir do `output` do contrato
+ * (ADR 0037; cenários específicos entram pela opção `scenarios`) — preview autossuficiente,
  * isolado de prod (o plugin desliga o `server.proxy` sozinho; prefixo ex-proxy sem
  * cobertura responde 503, nunca vaza pra porta real). Quando o app ganhar um backend real,
  * o `dev` normal proxeia pra ele (adicione `server.proxy`); o preview de design segue nos
- * mocks. O entry default do plugin é `./opus.config.ts` (a fonte da spec deste app).
+ * dados de design. O entry default do plugin é `./opus.config.ts` (a fonte da spec deste app).
  *
  * Import DINÂMICO NO TOP-LEVEL, de propósito, e em duas condições que andam juntas: (1) o
  * @softize/opus embarca TS source e o config loader padrão (esbuild bundle — o que build e

package/src/core/domain.ts

@@ -36,7 +36,7 @@ import type { ActionDef, ReactionDef, ScheduleDef } from './types.ts'
  * Um registrável de action num domínio: BOUND (`ActionDef`, com handler) ou
  * contrato PURO (`ActionContract`, sem handler). Um domínio de design — a
  * fatia isomorfa (ADR 0004) — registra só contratos, e em modo design o
- * `mockHandler` responde. Fora de design, contrato sem handler falha no
+ * plugin `opusDesign()` responde por eles (ADR 0037). Fora de design, contrato sem handler falha no
  * `execute` (comportamento INTENCIONAL); o tipo só deixa de exigir o cast.
  */
 export type DomainAction = ActionDef | ActionContract
@@ -205,7 +205,7 @@ function* iterateActions(
 ): IterableIterator<ActionDef> {
   if (actions === undefined) return
   // Um contrato puro (`ActionContract`, sem handler) entra como `ActionDef` no
-  // runtime — em design o `mockHandler` responde; fora de design, a ausência de
+  // runtime — em design o plugin `opusDesign()` responde; fora de design, a ausência de
   // handler falha no `execute` (intencional). O cast reconcilia o tipo neste
   // boundary de normalização; ver `DomainAction`.
   if (Array.isArray(actions)) {

package/src/core/types.ts

@@ -821,27 +821,11 @@ export interface ActionBase<In, Out, ParsedIn = In> {
 
   /**
    * Handler alternativo executado quando `process.env.OPUS_MODE === 'design'`.
-   * Use pra prototipar UI com dados realistas sem precisar do backend pronto.
    *
-   * Em modo design: runtime tenta `mockHandler` primeiro; se ausente, cai
-   * no `handler` normal (permitindo testar pontualmente real ao lado de
-   * mocks).
-   *
-   * Em modo default (sem env): `mockHandler` é ignorado. Útil pra apagar
-   * em revisão ou manter pro Designer reusar.
-   *
-   * Pattern recomendado pra ações que só têm mock durante dev:
-   *
-   * ```ts
-   * defineAction({
-   *   name: 'ticket.list',
-   *   // ...
-   *   mockHandler: async () => MOCK_TICKETS,
-   *   handler: () => {
-   *     throw new Error('handler real ainda não implementado — use 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>
 
@@ -919,6 +903,8 @@ export interface ListAction<In, Out, ParsedIn = In>
   /**
    * 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,

package/src/design/index.ts

@@ -0,0 +1,179 @@
+/**
+ * Dados do modo design fora do contrato (ADR 0037).
+ *
+ * No modo design, toda action responde: sem cenário, a resposta é gerada pelo `fake` a partir do
+ * `output` do contrato. Quando o design precisa de coerência (um item em cada situação, algo criado
+ * que aparece na lista), um cenário registrado pelo nome da action vence a resposta padrão.
+ *
+ * O módulo é isomórfico e não conhece Vite: o plugin `opusDesign()` carrega os cenários e liga as
+ * respostas ao runtime de design.
+ */
+
+import { z } from 'zod'
+import type { ActionContext, InferOutput, Paginated } from '../core/types.ts'
+import { fake, fakeMany } from '../testing/fake.ts'
+
+// =============================================================================
+// Cenários
+// =============================================================================
+
+// `Symbol.for`: o plugin roda no processo do Vite e carrega os cenários pelo pipeline SSR, então
+// a marca precisa sobreviver a duas instâncias do módulo.
+const SCENARIO = Symbol.for('@softize/opus/design-scenario')
+
+type ContractKind = 'simple' | 'form' | 'list' | 'view'
+
+interface ScenarioContract {
+  name: string
+  kind: ContractKind
+  input: unknown
+  output: unknown
+}
+
+type ScenarioInput<C> = C extends { input: infer S } ? InferOutput<S> : never
+
+type ScenarioOutput<C> = C extends { output: infer S }
+  ? C extends { kind: 'list' }
+    ? Paginated<InferOutput<S>>
+    : InferOutput<S>
+  : never
+
+/** Resposta de um cenário: o valor devolvido, ou uma função da entrada já validada. */
+export type DesignScenarioResponse<C> =
+  | ScenarioOutput<C>
+  | ((input: ScenarioInput<C>, ctx: ActionContext) => ScenarioOutput<C> | Promise<ScenarioOutput<C>>)
+
+/** Cenário de design ligado a uma action pelo nome. */
+export interface DesignScenario {
+  readonly [SCENARIO]: true
+  readonly action: string
+  respond(input: unknown, ctx: ActionContext): Promise<unknown>
+}
+
+/**
+ * Declara a resposta de uma action no modo design, fora do contrato. A resposta é tipada pela
+ * entrada e pela saída do contrato; em `list`, é a página completa (`items`, `cursor`, `total`).
+ */
+export function defineDesignScenario<C extends ScenarioContract>(
+  contract: C,
+  // NoInfer: o contrato é inferido só do primeiro argumento. Sem isso, a resposta entra na
+  // inferência e os literais do retorno de uma função alargam (`'closed'` vira `string`).
+  response: NoInfer<DesignScenarioResponse<C>>,
+): DesignScenario {
+  const respond =
+    typeof response === 'function'
+      ? async (input: unknown, ctx: ActionContext): Promise<unknown> =>
+          (response as (input: unknown, ctx: ActionContext) => unknown)(input, ctx)
+      : async (): Promise<unknown> => response
+  return { [SCENARIO]: true, action: contract.name, respond }
+}
+
+/** `true` quando o valor foi criado por `defineDesignScenario`. */
+export function isDesignScenario(value: unknown): value is DesignScenario {
+  return typeof value === 'object' && value !== null && (value as Record<symbol, unknown>)[SCENARIO] === true
+}
+
+// =============================================================================
+// Resposta padrão
+// =============================================================================
+
+/** Itens por página da listagem padrão quando a entrada não pede `limit`. */
+export const DESIGN_PAGE_SIZE = 20
+
+// Teto do `limit` atendido: o maior tamanho de página que o `ActionList` oferece.
+const DESIGN_MAX_PAGE_SIZE = 100
+
+// Três páginas: o bastante para a paginação do preview ter para onde ir.
+const DESIGN_PAGES = 3
+
+const PAGINATION_KEYS = new Set(['page', 'cursor', 'offset', 'limit'])
+
+interface DesignActionShape {
+  name: string
+  kind: ContractKind
+  output?: unknown
+  paginate?: 'cursor' | 'offset' | false
+}
+
+/**
+ * Resposta padrão do modo design: dado gerado pelo `fake` a partir do `output`, com semente
+ * derivada do nome da action e da entrada. A mesma requisição recebe a mesma resposta.
+ *
+ * - `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`.
+ */
+export function designResponse(action: DesignActionShape, input: unknown): unknown {
+  const output = action.output
+  if (!(output instanceof z.ZodType)) return null
+  const seed = `${action.name}:${canonicalJson(withoutPagination(input))}`
+
+  if (action.kind === 'list') {
+    const paginate = action.paginate ?? 'cursor'
+    const size = pageSize(input)
+    if (paginate === false) {
+      return { items: fakeMany(output, size, { seed }), cursor: { next: null }, total: size }
+    }
+    // O `limit` fica fora da semente: mudar o tamanho da página redistribui os mesmos itens.
+    const all = fakeMany(output, size * DESIGN_PAGES, { seed })
+    const page = requestedPage(input, size)
+    const start = (page - 1) * size
+    const next = paginate === 'cursor' && page < DESIGN_PAGES ? `design:${page + 1}` : null
+    const prev = paginate === 'cursor' && page > 1 ? `design:${page - 1}` : null
+    return {
+      items: all.slice(start, start + size),
+      cursor: { next, prev },
+      total: all.length,
+    } satisfies Paginated<unknown>
+  }
+
+  const value = fake(output, { seed })
+  const inputId = isRecord(input) ? input.id : undefined
+  if (inputId !== undefined && isRecord(value) && 'id' in value) {
+    // Só ecoa quando a saída continua válida: `id` numérico ou uuid na saída não aceita qualquer
+    // valor da entrada, e a validação de output do runtime recusaria a resposta.
+    const echoed = { ...value, id: inputId }
+    if (output.safeParse(echoed).success) return echoed
+  }
+  return value
+}
+
+function pageSize(input: unknown): number {
+  const limit = isRecord(input) && typeof input.limit === 'number' ? Math.trunc(input.limit) : DESIGN_PAGE_SIZE
+  return Math.min(Math.max(1, limit), DESIGN_MAX_PAGE_SIZE)
+}
+
+/** Página pedida, de 1 em diante; além da última página, a lista vem vazia. */
+function requestedPage(input: unknown, size: number): number {
+  if (!isRecord(input)) return 1
+  const cursor = typeof input.cursor === 'string' ? /^design:(\d+)$/.exec(input.cursor) : null
+  const fromCursor = cursor === null ? undefined : Number(cursor[1])
+  const fromOffset = typeof input.offset === 'number' ? Math.floor(input.offset / size) + 1 : undefined
+  const fromPage = typeof input.page === 'number' ? input.page : undefined
+  return Math.max(1, Math.trunc(fromCursor ?? fromPage ?? fromOffset ?? 1))
+}
+
+function withoutPagination(input: unknown): unknown {
+  if (!isRecord(input)) return input
+  return Object.fromEntries(Object.entries(input).filter(([key]) => !PAGINATION_KEYS.has(key)))
+}
+
+/** JSON com chaves ordenadas: a mesma entrada produz a mesma semente, qualquer que seja a ordem. */
+function canonicalJson(value: unknown): string {
+  if (typeof value === 'bigint') return `${value}n`
+  if (value instanceof Date) return JSON.stringify(value.toISOString())
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
+  if (isRecord(value)) {
+    const entries = Object.keys(value)
+      .filter((key) => value[key] !== undefined)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+    return `{${entries.join(',')}}`
+  }
+  return JSON.stringify(value) ?? 'null'
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/testing/fake.ts

@@ -1,7 +1,7 @@
 /**
  * `fake` — dado sintético DETERMINÍSTICO a partir de um schema zod. É a matéria-prima do
- * modo design: um `mockHandler` devolve `fake(entity)`/`fakeMany(entity, n)` e o preview mostra
- * a UI com dado realista, sem backend nem banco (o design-mode do runtime nem toca `ctx.db`).
+ * modo design: a resposta gerada pelo plugin `opusDesign()` (ADR 0037) sai de `fake`/`fakeMany`
+ * sobre o `output` do contrato, e o preview mostra a UI com dado realista, sem backend nem banco.
  *
  * DETERMINISMO: PRNG próprio semeado (mulberry32) — mesma `seed` → mesma saída, sempre. Nunca
  * `Math.random` (o preview tem que ser reproduzível entre execuções). O default é semeado por

package/src/testing/index.ts

@@ -206,9 +206,13 @@ 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) executa via `mockHandler` em modo design. */
+  /** Opcional: contrato puro (sem handler) só executa pelo `mockHandler` obsoleto. */
   handler?: HandlerFn<ParsedIn, Out>
-  /** Em `OPUS_MODE=design` vence o handler real — mesma régua do runtime. */
+  /**
+   * 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>
 }
 
@@ -329,7 +333,7 @@ export async function runAction<In, Out, ParsedIn = In>(
     throw error({
       code: 'testing.no_handler',
       category: 'internal',
-      message: `Action "${action.name}" não tem handler executável — contrato puro roda em modo design (OPUS_MODE=design) com mockHandler; fora dele, teste o ActionDef do bindAction`,
+      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)