@softize/opus 15.2.2 → 16.1.0

package/CHANGELOG.md

@@ -7,15 +7,54 @@ 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.
 
+## 16.1.0 — 2026-09-11
+
+`PresentationDevtoolsProvider`, `usePresentationRegistration` e `PresentationDevtools` permitem
+que o shell reúna as Presentations ativas em um único launcher de desenvolvimento. Cada recurso
+registra sua definição e o estado vivo da invocação; a pessoa escolhe qual snapshot inspecionar no
+menu. O JSON continua mascarando dados sensíveis e só é materializado depois da escolha, evitando
+serialização desnecessária durante a renderização. O consumidor deve montar o provider, os registros
+e o launcher apenas em ambiente de desenvolvimento.
+
+## 16.0.0 — 2026-09-11
+
+Opus 16 introduz `Presentation` como artefato público declarativo, disponível também pelo subpath
+`@softize/opus/presentation`, e sua composição React portátil entre Page, Dialog e Drawer. A
+`PresentationInvocation` guarda o identificador do recurso, a surface, input estritamente JSON e a
+pilha de frames usada por `back`; `openPresentation`, `backPresentation`, `closePresentation` e
+`applyPresentationEffects` oferecem transições puras para o renderer. O efeito `navigate` declara
+input por bindings e escolhe entre `push` e `replace`.
+
+`PresentationInspector` oferece, sob demanda, um snapshot único da definição, invocação, bindings
+resolvidos e diagnósticos. Chaves que indicam senha, segredo, token, cookie, autorização ou chave de
+API são mascaradas antes de o JSON aparecer ou ser copiado. A Lens continua expondo somente a
+definição estática projetada no manifest.
+
+`PageFooter` entra na composição explícita de Page. `PageHeader` organiza retorno ou breadcrumb,
+título e ações na mesma linha, acompanhando a anatomia usada pela Presentation; `PageIntro` também
+aceita a navegação própria do recurso quando existe um `PageShell`. `PageBack` vira um controle
+somente com ícone; o nome do destino continua no nome acessível e no tooltip. `ButtonGroup` ganha a
+distribuição `equal` para ações compactas de mesma largura. A Sidebar recolhida passa a `4rem`, com
+itens de `2.5rem` e respiro de `0.75rem`.
+
+**Breaking:** cabeçalhos de Dialog e Drawer passam a nomear apenas a superfície. Remova
+`DialogDescription` e `DrawerDescription` e leve explicações para o body ou para o `help` do campo
+correspondente. Nos wrappers `ActionFormDialog` e `ActionListDialog`, remova `description` pelo
+mesmo motivo. Nas APIs imperativas `alert`, `confirm`, `prompt` e `choose`, e em
+`ActionTrigger.confirm`, renomeie `description` para `body`. `PageHeader.variant` e o tipo
+`PageHeaderVariant` deixam de existir; use `PageShell` para a barra persistente e `PageIntro` para
+a introdução do conteúdo.
+
+
 ## 15.2.2 — 2026-09-11
 
 O acesso descritivo de Produtos de Dados usa `permissionContexts` no lugar do nome genérico
-`contexts`. A qualificação evita confundir contextos do framework, contexto de tela, domínio de
+`contexts`. A qualificação evita confundir contexto do framework, contexto de tela, domínio de
 dados e vocabulário de autorização nas projeções do manifest e da Lens.
 
 **Migração recomendada:** em declarações `defineDataProduct`, renomeie `access.contexts` para
 `access.permissionContexts` e regenere o manifest. O nome anterior continua aceito e projetado em
-toda a série 15.x como alias deprecated; consumidores novos devem ler somente o nome qualificado.
+toda a série 15.x como alias obsoleto; consumidores novos devem ler somente o nome qualificado.
 
 ## 15.2.1 — 2026-09-11
 
@@ -214,7 +253,7 @@ resizable e slider passam a ejetados no `registry.lock.json`.
 Descontinuados, com aviso no editor e sem mudança de comportamento: as variantes legadas
 (`default`, `secondary`, `destructive`, `success`, `warning`, `info`), `confirm()`, `ConfirmHost`,
 `FieldSpec.hint` (use `help`), `ShellNav*` (use `SidebarNav`) e `TbdlibProvider`, renomeado para
-`OpusProvider`. `'danger'` deixa de ser aceito como *variante* legada de Badge e Alert no tipo (era
+`OpusProvider`. `'danger'` deixa de ser aceito como _variante_ legada de Badge e Alert no tipo (era
 um contexto disfarçado): declare `context="danger"`. O botão de confirmar do `ActionTrigger` passa a
 ser sempre `solid` — `danger` quando a action é `destructive`, senão o `context` do gatilho — e não
 herda mais o `variant` do gatilho; a permissão negada (`authorization`/`authentication`) entra na
@@ -454,6 +493,7 @@ Os patterns existentes passam a reutilizar os primitives canônicos: `ActionForm
 `FieldGroup`, descrições e erros associados ao controle; `ActionList` usa a moldura de `Table` e
 os estados seguros de `DataState`, preservando a tentativa de recuperação; e a confirmação de uma
 `ActionTrigger` destrutiva mantém o tratamento destrutivo mesmo quando o gatilho visual é discreto.
+
 ## 12.5.5 — 2026-08-25
 
 Só documentação: leva ao pacote a correção de nota que a 12.5.4 recebeu no repositório depois de
@@ -800,6 +840,7 @@ todas as mensagens que apenas têm comportamento `sticky` disponível.
 fronteira memoizada separada do estado do composer, e cada bloco Markdown reaproveita o
 resultado enquanto seu conteúdo não muda. Conversas longas mantêm o custo de digitação
 constante; durante streaming, somente a mensagem alterada volta a passar pelo parser.
+
 ## 9.0.3 — 2026-08-12
 
 **O pre-push ignora worktrees internos do Maestro.** Projetos sob `.maestro/` pertencem
@@ -1033,11 +1074,11 @@ de backend de pé — nem, pior, falar com prod por um proxy esquecido no vite.c
   `vite --mode design`, o vite.config traz `opusDesign({ devBackend: true })` (dev normal
   serve o handler real via /api; design roteia pro mock) e o domínio-exemplo mostra o
   split canônico: `defineContract` com `mockHandler` alimentado pelo schema (`fakeMany`)
-  + `bindAction` com o handler in-memory — o App consome o CONTRATO via `useListAction`
-  (fim do "chama o handler direto, sem servidor ainda"), e o teste cobre o bound E o
-  contrato puro em design. O plugin também marca `@softize/opus` como `ssr.noExternal`:
-  o pacote embarca TS source e, externalizado, o node recusa TS sob node_modules no
-  load SSR do entry.
+  - `bindAction` com o handler in-memory — o App consome o CONTRATO via `useListAction`
+    (fim do "chama o handler direto, sem servidor ainda"), e o teste cobre o bound E o
+    contrato puro em design. O plugin também marca `@softize/opus` como `ssr.noExternal`:
+    o pacote embarca TS source e, externalizado, o node recusa TS sob node_modules no
+    load SSR do entry.
 - **`options: { kind: 'dictionary', ref }` agora resolve.** O `TbdlibProvider` ganha
   `dicts` (`Record<ref, DictLike>` — o `DictType` do `t.dict` encaixa direto) e a UI
   resolve a origem declarada no contrato: no `ActionList`, filtro e chips mostram os
@@ -1292,7 +1333,7 @@ todos. Elemento novo (table, figure, dl) entra sozinho.
 
 **O respiro fantasma nas mensagens.** As bolhas do `Chat` tentavam zerar a margem do
 primeiro e do último bloco com `[&>*:first-child]:mt-0`, mas o primeiro filho da bolha é o
-*wrapper* do `prose` — que não tem margem; quem tem é o `<p>` um nível abaixo. A
+_wrapper_ do `prose` — que não tem margem; quem tem é o `<p>` um nível abaixo. A
 compensação nunca surtiu efeito, e cada mensagem carregava ~16px invisíveis em cima e
 embaixo. Agora mora dentro do `Markdown`, onde alcança o bloco certo.
 
@@ -1644,7 +1685,7 @@ ver a nota de migração do t.json()).
 - **`readOnlyContextPool` (`@softize/opus/data/readonly-pool`).** SQL escrito por LLM
   com as QUATRO defesas dos ADRs 0003/0007 — todas no BANCO, nenhuma em regex: pool com
   teto (`max` do pool e/ou `maxConcurrent` com fila própria), `BEGIN TRANSACTION READ
-  ONLY`, `SET LOCAL ROLE` por transação (alcance do contexto; roles/grants
+ONLY`, `SET LOCAL ROLE` por transação (alcance do contexto; roles/grants
   default-fechado são migração sua) e protocolo estendido (o SQL roda sempre com array
   de valores — multi-sentença é recusada pelo protocolo). Saindo, `DISCARD ALL` devolve
   a conexão limpa; limpeza que falha DESTRÓI a conexão (nunca volta suja ao pool).
@@ -1676,7 +1717,7 @@ novos, todos aditivos).
   mas roda qualquer um (o hook usa name/kind e lê `invalidates`) — disparar um
   FormContract fora de form (modal composto que submete `role.update`) exigia
   `as unknown as SimpleContract<...>`. Agora o parâmetro é `ActionContract<TInput,
-  TData>`; o cast morre. Nenhuma chamada existente muda.
+TData>`; o cast morre. Nenhuma chamada existente muda.
 - **`useActionFormContext()` (novo export, `ui/react`).** A válvula de escape pra
   CONTROLE CUSTOM no modo composição do `<ActionForm>`: campo com UI própria (a grade
   de permissões que forçou abandonar o form inteiro) participa do form do contrato —
@@ -1765,9 +1806,9 @@ o guard agora moram na base, então qualquer consumidor de IA do Opus nasce prot
 breaking** (tipos/campos/exports novos, aditivos).
 
 - **Contrato de pergunta (novos tipos, `@softize/opus`).** `AskQuestion` (enunciado + `header`
-  + `options` + `multiSelect`), `AskOption` e `AskAnswer` (rótulos escolhidos + texto livre) —
-  a forma única que todo mundo fala. Espelha o AskUserQuestion do Claude Code, mas servida por
-  um round-trip REAL.
+  - `options` + `multiSelect`), `AskOption` e `AskAnswer` (rótulos escolhidos + texto livre) —
+    a forma única que todo mundo fala. Espelha o AskUserQuestion do Claude Code, mas servida por
+    um round-trip REAL.
 - **`AiRunOptions.onAsk` / `BoundAiRunOptions.onAsk` (novo hook).** O round-trip de "perguntar
   à pessoa": com ele, o driver INTERCEPTA a tool reservada `ask_user` (injetada automaticamente
   no catálogo) e chama o handler, devolvendo as respostas ao modelo. Passa direto por `ctx.ai`
@@ -1859,8 +1900,8 @@ Correções da 2.35.0 (que saiu antes de passar pelo review). **Prefira esta à
 
 ## 2.35.0 — 2026-07-21
 
-Sidebar recolhível no `AppShell` e o **rem base passa a 15px**. *(Publicada com os defeitos
-que a 2.35.1 conserta — use a 2.35.1.)*
+Sidebar recolhível no `AppShell` e o **rem base passa a 15px**. _(Publicada com os defeitos
+que a 2.35.1 conserta — use a 2.35.1.)_
 
 - **Base do rem em 15px. Visual: GLOBAL — e o delta depende de onde você está.** Todo `rem`
   deriva daqui, então tipografia, espaçamento e tamanho de controle mudam em toda tela no
@@ -1875,9 +1916,10 @@ que a 2.35.1 conserta — use a 2.35.1.)*
   reincidência). Quem quiser a escala densa fixa `html { font-size: 14px }` no próprio entry.
   **Consumidor que já sobrescrevia pra 15px pode remover o override** — vira redundante, não
   conflitante (mesmo valor), então dá pra limpar sem pressa.
-  <br>*Correção de registro:* a entrada da 2.31.5 saiu com dois erros (chamava 15px de "a
+  <br>_Correção de registro:_ a entrada da 2.31.5 saiu com dois erros (chamava 15px de "a
   escala anterior" e dizia "encolhe ~6,7%"), ambos por supor uma baseline de 15px que nunca
   existiu. Corrigidos lá, com nota.
+
 - **`AppShell` ganha `collapsible` (opt-in).** Sem a prop, nada muda. Com ela, o shell
   controla a **largura** e publica o estado; **o que some é decisão do conteúdo**, porque o
   `sidebarNav` é do consumidor. Em vez de exigir estado no app, o aside expõe
@@ -1946,7 +1988,7 @@ para cá.**
   empilhava uma entrada. Era o caso pt-BR inteiro.
 - Some a última cópia à mão do mecanismo, que tinha sobrado dentro do próprio
   `registry.tsx` (o redirect de `/docs/ui` pra `/ui` — agora `navigate('/ui', { replace:
-  true })`, porque redirect não merece entrada no histórico).
+true })`, porque redirect não merece entrada no histórico).
 
 ## 2.34.0 — 2026-07-21
 

package/bin/lib/check.mjs

@@ -107,9 +107,10 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["PageHeader", new Set(["Page"])],
   ["PageIntro", new Set(["Page"])],
   ["PageBody", new Set(["Page"])],
+  ["PageFooter", new Set(["Page"])],
   ["PageTitle", new Set(["PageHeader", "PageIntro"])],
-  ["PageBack", new Set(["PageHeader"])],
-  ["PageNavigation", new Set(["PageHeader"])],
+  ["PageBack", new Set(["PageHeader", "PageIntro"])],
+  ["PageNavigation", new Set(["PageHeader", "PageIntro"])],
   ["PageDescription", new Set(["PageHeader", "PageIntro"])],
   ["PageActions", new Set(["PageHeader", "PageIntro"])],
   ["ContentHeader", new Set(["Content"])],
@@ -169,11 +170,14 @@ const UI_STRUCTURAL_ROOTS = new Map([
       header: "PageHeader",
       alternateHeader: "PageIntro",
       body: "PageBody",
+      footer: "PageFooter",
       shorthand: new Set(["title", "description", "actions"]),
       // O contador saiu do título da página (ADR 0009). Tirar `count` do shorthand não proíbe
       // nada sozinho — só apaga o marcador que fazia o gate enxergar aquele Page —, então a
       // prop removida é cobrada aqui, nas duas formas de composição.
-      removed: new Map([["count", "o total pertence ao conteúdo que o explica"]]),
+      removed: new Map([
+        ["count", "o total pertence ao conteúdo que o explica"],
+      ]),
     },
   ],
   [
@@ -191,6 +195,7 @@ const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "PageHeader",
   "PageIntro",
   "PageBody",
+  "PageFooter",
   "PageTitle",
   "PageBack",
   "PageNavigation",
@@ -207,6 +212,44 @@ const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "AlertActions",
 ]);
 
+const UI_REMOVED_PROPS = new Map([
+  [
+    "PageHeader",
+    new Map([
+      ["variant", "use `PageShell` para a barra persistente da página"],
+    ]),
+  ],
+  [
+    "ActionFormDialog",
+    new Map([
+      [
+        "description",
+        "use `intro` somente para contexto relevante no início do corpo",
+      ],
+    ]),
+  ],
+  [
+    "ActionListDialog",
+    new Map([
+      [
+        "description",
+        "use `intro` somente para contexto relevante no início do corpo",
+      ],
+    ]),
+  ],
+]);
+
+const UI_REMOVED_COMPONENTS = new Map([
+  [
+    "DialogDescription",
+    "mova contexto relevante para o início de `DialogBody`",
+  ],
+  [
+    "DrawerDescription",
+    "mova contexto relevante para o início de `DrawerBody`",
+  ],
+]);
+
 const UI_STRUCTURAL_CONTAINERS = new Set(["PageShell"]);
 
 const UI_STRUCTURAL_HEADERS = new Map([
@@ -228,7 +271,13 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "PageIntro",
     {
       title: "PageTitle",
-      optional: new Set(["PageDescription", "PageActions"]),
+      optional: new Set([
+        "PageBack",
+        "PageNavigation",
+        "PageDescription",
+        "PageActions",
+      ]),
+      exclusive: [new Set(["PageBack", "PageNavigation"])],
       shorthand: new Set(),
     },
   ],
@@ -295,14 +344,7 @@ const UI_LEGACY_VARIANTS = new Map([
   ],
   [
     "Alert",
-    new Set([
-      "default",
-      "destructive",
-      "info",
-      "success",
-      "warning",
-      "danger",
-    ]),
+    new Set(["default", "destructive", "info", "success", "warning", "danger"]),
   ],
   [
     "Dot",
@@ -969,6 +1011,16 @@ export function checkUiStructure(file, text) {
     if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
       const local = jsxLocalName(node);
       const component = local === null ? null : imports.get(local);
+      const removedComponent =
+        component === null ? undefined : UI_REMOVED_COMPONENTS.get(component);
+      if (component !== null && removedComponent !== undefined) {
+        add(
+          node,
+          component,
+          `${component} não faz mais parte da API pública: ${removedComponent}.`,
+          "ui-structure-removed-component",
+        );
+      }
       const parents =
         component === null ? undefined : UI_STRUCTURAL_PARENTS.get(component);
       if (parents !== undefined) {
@@ -990,6 +1042,29 @@ export function checkUiStructure(file, text) {
         }
       }
 
+      const removedProps =
+        component === null ? undefined : UI_REMOVED_PROPS.get(component);
+      if (removedProps !== undefined) {
+        const opening = jsxOpening(node);
+        const attributes = new Set(
+          opening.attributes.properties.flatMap((attribute) =>
+            ts.isJsxAttribute(attribute) && ts.isIdentifier(attribute.name)
+              ? [attribute.name.text]
+              : [],
+          ),
+        );
+        for (const [attribute, hint] of removedProps) {
+          if (attributes.has(attribute)) {
+            add(
+              node,
+              component,
+              `${component} não aceita mais a propriedade \`${attribute}\`: ${hint}.`,
+              "ui-structure-removed-prop",
+            );
+          }
+        }
+      }
+
       const header =
         component === null ? undefined : UI_STRUCTURAL_HEADERS.get(component);
       if (header !== undefined) {
@@ -1090,7 +1165,8 @@ export function checkUiStructure(file, text) {
         ).filter(Boolean);
         const structural =
           acceptedHeaders.some((header) => children.names.includes(header)) ||
-          children.names.includes(root.body);
+          children.names.includes(root.body) ||
+          (root.footer !== undefined && children.names.includes(root.footer));
         // A prop removida saiu do `shorthand`, então sozinha ela não marca o nó como forma curta:
         // ele cai no ramo explícito, que cobra header e body — uma segunda mensagem inteiramente
         // induzida pela prop. Sem filhos estruturais essa cobrança dispara de qualquer jeito, e
@@ -1113,19 +1189,26 @@ export function checkUiStructure(file, text) {
           const bodies = children.names.filter(
             (name) => name === root.body,
           ).length;
+          const footers = children.names.filter(
+            (name) => name === root.footer,
+          ).length;
           const unexpected = children.names.some(
-            (name) => !acceptedHeaders.includes(name) && name !== root.body,
+            (name) =>
+              !acceptedHeaders.includes(name) &&
+              name !== root.body &&
+              name !== root.footer,
           );
           if (
             headers !== 1 ||
             bodies !== 1 ||
+            footers > 1 ||
             unexpected ||
             children.hasOpaque
           ) {
             add(
               node,
               component,
-              `${component} explícito exige exatamente um ${acceptedHeaders.join(" ou ")} e um ${root.body} como filhos diretos.`,
+              `${component} explícito exige exatamente um ${acceptedHeaders.join(" ou ")}, um ${root.body} e no máximo um ${root.footer ?? "footer"} como filhos diretos.`,
             );
           }
         }