@softize/opus 12.6.1 → 12.6.3

package/CHANGELOG.md

@@ -7,6 +7,20 @@ 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.
 
+## 12.6.3 — 2026-08-26
+
+A skill `build-opus-ui` passa a orientar operacionalmente os patterns entregues em 12.6.0 e
+12.6.1: composição com `ContentHeader`, teto padrão de `72rem` em `Page`, uso isolado de
+`ActionFilterBar`, estrutura de `ItemGroup`, modos atuais de `ActionForm` e `ActionList`, diferença
+entre `Empty` e vazio estrutural, alinhamento explícito de colunas numéricas e cancelamento `ghost`
+em modais. As avaliações da skill agora cobram essas decisões em conjunto.
+
+## 12.6.2 — 2026-08-26
+
+O `postinstall` passa a materializar `base.json` e `opus.json` somente a partir do exemplar de
+`@softize/opus` resolvido pelo workspace declarado. Versões transitivas instaladas no mesmo projeto
+não disputam mais esses marcadores durante instalações concorrentes.
+
 ## 12.6.1 — 2026-08-26
 
 Os padrões de UI passam a distinguir melhor estrutura e ação. `Page` centraliza o conteúdo com

package/bin/lib/postinstall-target.mjs

@@ -0,0 +1,32 @@
+import { realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+import { readProjectFile, safeProjectPath } from '@softize/base/project-path'
+
+function resolutionDirectory(projectDir) {
+  try {
+    const base = JSON.parse(readProjectFile(projectDir, 'base.json', { allowMissing: true }).content || '{}')
+    const resolveFrom = base?.packages?.['@softize/opus']?.resolveFrom
+    if (typeof resolveFrom !== 'string') return projectDir
+    const candidate = safeProjectPath(projectDir, resolveFrom, { mustExist: true })
+    return candidate.kind === 'directory' ? candidate.path : projectDir
+  } catch {
+    return projectDir
+  }
+}
+
+/**
+ * Só o exemplar resolvido pelo workspace declarado pode materializar o projeto.
+ * Gerenciadores de pacote executam o postinstall de exemplares transitivos com o mesmo
+ * INIT_CWD; sem esta prova, versões diferentes disputam base.json e opus.json.
+ */
+export function isResolvedOpusInstance(projectDir, packageRoot) {
+  try {
+    const from = resolutionDirectory(projectDir)
+    const resolved = createRequire(path.join(from, 'package.json')).resolve('@softize/opus/package.json')
+    return realpathSync(path.dirname(resolved)) === realpathSync(packageRoot)
+  } catch {
+    return false
+  }
+}

package/bin/lib/postinstall.mjs

@@ -19,6 +19,7 @@ import { fileURLToPath } from 'node:url'
 import { canonicalProjectDirectory, readProjectFile } from '@softize/base/project-path'
 
 import { initProject } from './init.mjs'
+import { isResolvedOpusInstance } from './postinstall-target.mjs'
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
 const REGISTRY_DIR = path.join(PACKAGE_ROOT, 'registry')
@@ -40,6 +41,7 @@ async function main() {
   if (pkg.name === '@softize/opus') return
   const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) }
   if (!deps['@softize/opus']) return // Não é consumidor do Opus.
+  if (!isResolvedOpusInstance(projectDir, PACKAGE_ROOT)) return
 
   const r = await initProject(REGISTRY_DIR, projectDir)
   if (!r.materialization.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.6.1",
+  "version": "12.6.3",
   "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/SKILL.md

@@ -17,24 +17,30 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
 2. Usar os hooks e componentes do catálogo `@softize/opus/ui/react` adequados ao kind.
 3. 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.
-4. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
+4. Compor páginas com `Page` e seu teto centralizado padrão de `72rem`. Usar
+   `ContentHeader` em seções que precisam da mesma estrutura de título, descrição,
+   metadados e ações; ajustar `level` pela hierarquia semântica, não pelo destaque visual.
+5. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
    seu interior.
-5. Não definir a fonte raiz em uma biblioteca ou componente. O navegador e a aplicação são
+6. Não definir a fonte raiz em uma biblioteca ou componente. O navegador e a aplicação são
    responsáveis por `font-size` em `html`; medidas escaláveis da UI usam `rem` ou a escala
    relativa do Tailwind. Reservar `px` a hairlines e compensações presas à geometria da borda,
    com justificativa e cobertura explícitas.
-6. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.
-7. Tratar tokens de superfície como pares indivisíveis no mesmo fragmento de classes:
+7. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.
+8. Tratar tokens de superfície como pares indivisíveis no mesmo fragmento de classes:
    `bg-card text-card-foreground` e `bg-popover text-popover-foreground`. Não depender da
    igualdade atual com `--foreground`, porque o app pode sobrescrever cada par.
-8. Usar diretamente a escala `rounded-*`; não criar radius por nome de componente quando
+9. Usar diretamente a escala `rounded-*`; não criar radius por nome de componente quando
    `rounded-xs` a `rounded-2xl` já expressam a forma. Escolher o degrau pela escala visual:
    detalhes e itens internos tendem a `xs`/`sm`, controles e flutuantes compactos a `md`,
    molduras estruturais a `lg`, e superfícies principais ou modais a `xl`. Essa associação
    orienta o default, não cria uma restrição semântica. Em aninhamento, evitar moldura dupla e
    reduzir o raio interno; em grupos conectados, remover os raios das arestas internas. Tamanho
    e forma permanecem eixos separados; usar `shape="pill"` quando a pílula for intencional.
-9. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
+10. Distinguir uma região disponível para criação ou vínculo, representada por `Empty` com
+    moldura tracejada, de um resultado vazio dentro de uma estrutura existente, que preserva
+    a moldura sólida dessa estrutura.
+11. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
 
 ## Verificação
 

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

@@ -3,9 +3,17 @@
 - Dispara: “Monte a tela de edição usando a form action do Opus.”
 - 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 com `Page`, `ContentHeader` em uma seção,
+  `ActionFilterBar` separado do renderer, `ItemGroup` para uma coleção secundária e um
+  `ActionFormDialog`; provar teto padrão de `72rem`, hierarquia por `level`, vazio estrutural
+  sólido, `Empty` apenas para criação ou vínculo, números sem alinhamento inferido e cancelamento
+  `ghost` no modal.
 - 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`.
 - 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
   manter cantos arredondados nas arestas internas de um grupo conectado.
+- 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.

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

@@ -4,6 +4,12 @@
 - Campos, labels, mensagens e invalidações pertencem ao contrato quando são parte da
   operação, não a uma tela isolada.
 - URL representa estado que precisa sobreviver a refresh, deep link ou histórico.
+- `Page` fornece o `<main>`, o container centralizado com teto padrão de `72rem` e o header
+  de página. Alterar `className` apenas quando a superfície tiver uma necessidade real de
+  largura; não reconstruir esse container em cada rota.
+- `ContentHeader` compartilha a composição de título, descrição, metadados e ações entre
+  páginas e seções. `variant` define o destaque visual; `level` preserva separadamente a
+  hierarquia semântica do heading.
 - Componentes compartilhados não impõem margem externa; páginas e shells compõem layout.
 - A fonte raiz pertence ao navegador e à aplicação. Medidas escaláveis usam `rem` ou a escala
   relativa do Tailwind; `px` fica restrito a hairlines e compensações ligadas a essas bordas.
@@ -16,4 +22,24 @@
 - Superfície aninhada evita moldura dupla e normalmente usa um degrau abaixo do contêiner.
   Grupos conectados removem os raios internos. O tamanho do controle não muda sua forma;
   `shape="pill"` declara a pílula quando ela for intencional.
+- `ActionFilterBar` renderiza busca, filtros, período e ações declarados por uma list action
+  quando a tela precisa da toolbar sem entregar os resultados a `ActionList`. Manter seu
+  `state` e `onStateChange` ligados à mesma projeção de URL usada pela superfície.
+- `ActionForm` mantém validação, execução e estados do contrato nos dois modos: sem `children`,
+  renderiza os campos declarados; com `children`, o consumidor diagrama `ActionFormField` e
+  controles customizados pelo contexto. `ActionFormCard` e `ActionFormDialog` acrescentam a
+  casca; não duplicar o form para obter card ou modal. Cancelamento em forms, confirmações e
+  modais usa `ghost`, deixando o destaque visual para a ação principal.
+- `ActionList` mantém fetch, toolbar, loading, erro, retry, vazio, seleção e paginação enquanto
+  permite três composições de resultado: tabela por `columns`, renderer completo por `children`
+  ou views nomeadas. Usar `ActionFilterBar` isoladamente só quando outra superfície assumir a
+  renderização dos resultados. Colunas numéricas não recebem alinhamento ou tipografia por
+  inferência do tipo: declarar `className` no header e na célula quando o produto exigir, de
+  modo que números preservem o alinhamento natural por padrão.
+- `ItemGroup` representa uma coleção e pode oferecer moldura explícita; `Item` já carrega
+  semântica de item de lista. Preferir essa composição a uma sequência visual sem estrutura.
+- `Empty` com moldura tracejada comunica uma região disponível para criar ou vincular algo.
+  Quando uma tabela, card ou grupo existente apenas não tem resultados, manter sua moldura
+  sólida e renderizar o vazio estrutural dentro dela; não trocar toda ausência de dados por
+  `Empty`.
 - Catálogo e API efetivos vêm dos exports da versão instalada, não de memória ou exemplo antigo.