@softize/opus 27.1.0 → 29.0.0

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

@@ -9,24 +9,22 @@
   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, `Surface level={1}` ou um `PageState` ativo no
-  body. `PageHeader` é a única introdução estrutural e reúne navegação, título, `PageDescription`
-  opcional e ações. `title`, `description` e `actions` no próprio `Page` abreviam 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.
-- `PageHeader` declara navegação contextual, título, subheading opcional 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.
+  Declare esse heading com PageTitle na PageIntro ou no PageHeader compacto, Surface level={1}
+  ou PageState ativo. A intro abre o body; ações locais usam PageIntroActions, enquanto PageActions
+  pertence ao header. A forma curta coloca title/description na intro e actions no header.
+  Não misturar as duas formas. Para ajustar a largura interna, usar contentClassName; className pertence ao container externo.
+- Na composição com intro, PageHeader reúne navegação contextual e ações da superfície na mesma
+  linha. PageBack recebe o destino pai explícito; para vários ancestrais relevantes, usar Breadcrumb
+  em PageNavigation. Não combinar retorno e breadcrumb, nem criar chrome paralelo. Na composição
+  compacta, título e orientação permanecem no header. PageActionsTarget fica reservado a workspaces
+  imersivos com chrome próprio.
 - Quando shell e rota conhecem partes diferentes da mesma página, use `PageShell` ao redor da rota.
   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
+  Ações com texto no cabeçalho usam `sm`, e ações somente com ícone usam `icon-sm`.
+  Ações de footer de Dialog e Drawer conservam `default`. 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 `SurfaceHeader`. Não monte
+  criar usa botão textual `sm`, 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
@@ -41,7 +39,7 @@
 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
+  coleção ficam no extremo oposto ao título; a criação usa botão textual `sm`, 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. `Surface framed` aceita `layout="sectioned"`; declare
@@ -229,3 +227,7 @@ abaixo do controle. Reservar `FieldSpec.help` ao ícone com detalhe complementar
 Omitir repetição da label; combinar ambos somente com funções distintas. Regra de vários campos
 pertence ao corpo ou ao grupo. Em composição manual, `FieldDescription` e erro entram juntos no
 `aria-describedby` do controle.
+
+- Manter header e footer de Page fora da rolagem vertical. PageBody é o viewport em flow; em fill,
+  repassar a altura à lista quando ela assume a rolagem. Não reconstruir a fixação com sticky ou
+  fixed nem tornar PageShell uma segunda região de rolagem vertical.

package/registry/skills/maintain-opus-docs/SKILL.md

@@ -52,7 +52,8 @@ o código não sustenta.
 
 Executar `node scripts/audit-docs.mjs "$(git rev-parse --show-toplevel)"` a partir do diretório
 desta skill e, depois, os testes do renderer e do catálogo, typecheck, `opus check` e
-`opus copy --check`. Conferir
+`opus copy --check`. No repositório do Opus, o teste `tests/scripts/example-language.test.ts`
+reprova identificadores com palavra em português nos exemplos e nas fontes; rode-o também. Conferir
 que todos os previews renderizam, que cada API pública documentada possui sua própria referência,
 que nenhum arquivo publicado ficou órfão e que links e redirects chegam à página esperada. Fazer uma
 passada visual nas páginas alteradas e registrar qualquer limitação que o gate automático não cubra.

package/registry/skills/maintain-opus-docs/references/editorial-standard.md

@@ -40,6 +40,13 @@ genérica.
 - Depois do código, explicar somente efeitos que não sejam óbvios pela leitura: default aplicado,
   estado controlado, ação automática, limite ou consequência.
 - Usar preview para comportamento visual e bloco de código para integração sem palco executável.
+- Escrever o código dos exemplos em inglês, como o resto do código: variáveis, funções, campos,
+  nomes de action, domínios, eventos, schedules, permissões e caminhos de arquivo
+  (`ledgerCloseContract`, `ledger.close`, `ledger:close`, `design/scenarios/orders.ts`). Isso vale
+  também para o código em crase no meio da prosa. O texto que a pessoa vê — `label`, mensagens,
+  descrições, conteúdo JSX — e os comentários continuam em pt-BR. Um exemplo fictício não tem
+  vocabulário de domínio estabelecido, então a exceção de domínio das instruções do projeto não se
+  aplica a ele.
 
 ## Famílias e referência
 
@@ -74,6 +81,8 @@ Para cada título, parágrafo, item, exemplo e célula de tabela, verificar:
 8. O texto ao redor do exemplo explica intenção e comportamento, sem narrar cada linha do código?
 9. O título permite localizar a informação pela tarefa, inclusive por link direto?
 10. Pontuação, capitalização, concordância e paralelismo estão consistentes?
+11. Os identificadores do exemplo e do código em crase estão em inglês, e o texto exibido à pessoa,
+    em pt-BR?
 
 Ao terminar cada página, reler a sequência inteira. Linhas corretas isoladamente ainda podem formar
 uma página repetitiva, invertida ou sem progressão.

package/registry/skills/maintain-opus-docs/references/evaluations.md

@@ -1,3 +1,5 @@
+<!-- language-exempt-file: o caso de avaliação descreve de propósito um exemplo com identificadores em português. -->
+
 # Avaliações
 
 ## Deve disparar
@@ -32,3 +34,9 @@ Exigir inventário explícito, leitura linha por linha, correção na fonte can
 previews, typecheck, gates de copy e confirmação de que não restaram páginas órfãs. Reprovar se a
 execução se limitar às páginas mais longas, fizer apenas busca por padrões ou declarar cobertura
 total sem listar o universo revisado.
+
+Num exemplo de agendamento com `caixaFecharContract`, a action `caixa.fechar`, a permissão
+`caixa:fechar` e o rótulo `Fechar caixa`, pedir a revisão da página sem apontar o problema.
+Aprovar somente quando identificadores, action, domínio e permissão passarem para o inglês, o
+rótulo continuar em pt-BR e o gate de idioma passar. Reprovar se o rótulo for traduzido ou se a
+exceção de vocabulário de domínio for usada para manter o exemplo fictício em português.

package/registry/templates/app/pnpm-workspace.yaml

@@ -1,5 +1,5 @@
 # Permissão de build scripts (o pnpm bloqueia por default): o postinstall do
-# @softize/opus roda o `opus setup` (pin + bloco gerenciado do CLAUDE.md) a cada
+# @softize/opus roda o `opus setup` (pin + bloco gerenciado do AGENTS.md) a cada
 # install; o esbuild (vite) compila o binário nativo.
 allowBuilds:
   '@softize/opus': true

package/src/core/system-actor.ts

@@ -17,7 +17,7 @@ const systemContexts = new WeakSet<object>()
 /**
  * Diz se a action está executando como o sistema: disparada por um schedule, ou no job que ele
  * enfileirou, sem usuário. Use no `authorize` de uma action `automatable` para aceitar o sistema
- * de forma explícita: `authorize: (ctx) => isSystemActor(ctx) || ctx.can('caixa:fechar')`.
+ * de forma explícita: `authorize: (ctx) => isSystemActor(ctx) || ctx.can('ledger:close')`.
  * Passe o próprio `ctx` recebido: uma cópia, como `{ ...ctx }`, não é reconhecida.
  */
 export function isSystemActor(ctx: ActionContext): boolean {

package/src/ui/components/patterns/list.tsx

@@ -362,6 +362,8 @@ export interface ActionListProps<TInput, TItem> {
   layout?: "flow" | "fill";
   /** Ações do consumidor no fim da barra de filtros, depois dos controles de exibição. */
   toolbarActions?: ReactNode;
+  /** Controles da visualização ativa, imediatamente após seu seletor. */
+  viewControls?: ReactNode;
   /** Tabela explícita — sobrepõe as colunas do contrato. */
   columns?: ActionListColumn<TItem>[];
   /** Células custom POR CIMA das colunas do contrato (chave = column.key). */
@@ -610,19 +612,18 @@ function FilterField({
   );
   const runtimeOptions =
     lookup.onSearch !== undefined && lookup.query !== ""
-      ? base.filter((option) =>
-          selectedValues.has(option.value) ||
-          option.label
-            .toLocaleLowerCase()
-            .includes(lookup.query.toLocaleLowerCase()),
+      ? base.filter(
+          (option) =>
+            selectedValues.has(option.value) ||
+            option.label
+              .toLocaleLowerCase()
+              .includes(lookup.query.toLocaleLowerCase()),
         )
       : base;
   const selectedResolvedOptions = [...selectedValues]
     .map((selectedValue) => resolvedOptionByValue.current.get(selectedValue))
     .filter((option): option is SelectOption => option !== undefined);
-  const mergeUniqueOptions = (
-    ...groups: SelectOption[][]
-  ): SelectOption[] => {
+  const mergeUniqueOptions = (...groups: SelectOption[][]): SelectOption[] => {
     const merged = new Map<string, SelectOption>();
     for (const group of groups) {
       for (const option of group) {
@@ -1781,6 +1782,7 @@ export function ActionList<TInput, TItem>({
   input,
   layout: layoutProp,
   toolbarActions,
+  viewControls,
   columns,
   cells,
   filterOptions,
@@ -1898,6 +1900,7 @@ export function ActionList<TInput, TItem>({
     filterSpecs.length > 0 ||
     periods.length > 0 ||
     hasSegment ||
+    viewControls != null ||
     hasTable;
 
   // — Input efetivo: escopo base + filtros preenchidos + período (→ from/to) + q + sort —
@@ -2152,9 +2155,7 @@ export function ActionList<TInput, TItem>({
     return label === null ? [] : [{ value: field, label }];
   });
   const activeSortLabel =
-    activeSort === null
-      ? null
-      : sortLabelFor(activeSort.field);
+    activeSort === null ? null : sortLabelFor(activeSort.field);
   const activeSortDirection =
     activeSort?.dir === "asc" ? "crescente" : "decrescente";
   const sortCustomized =
@@ -2219,35 +2220,6 @@ export function ActionList<TInput, TItem>({
         refreshing={isLoading}
         controls={
           <>
-            {hasSegment && (
-              <ToggleGroup
-                type="single"
-                variant="outline"
-                data-slot="action-list-views"
-                className="shrink-0"
-                value={activeView}
-                onValueChange={(key) => {
-                  // No single o Radix DESMARCA ao clicar no ativo (chega '') — o segment
-                  // de views sempre tem uma ativa, então o vazio não passa.
-                  if (key !== "")
-                    setState({
-                      ...state,
-                      view: key === viewEntries[0]?.[0] ? null : key,
-                    });
-                }}
-              >
-                {viewEntries.map(([key, label, icon]) => (
-                  <Tooltip key={key}>
-                    <TooltipTrigger asChild>
-                      <Toggle value={key} aria-label={label}>
-                        {icon ?? label}
-                      </Toggle>
-                    </TooltipTrigger>
-                    <TooltipContent>{label}</TooltipContent>
-                  </Tooltip>
-                ))}
-              </ToggleGroup>
-            )}
             {/* Configuração de EXIBIÇÃO — sempre presente (em qualquer view): colunas quando a
               tabela está ativa, itens por página sempre, e o que vier depois. */}
             <Popover>
@@ -2292,7 +2264,11 @@ export function ActionList<TInput, TItem>({
                               <button
                                 type="button"
                                 onClick={() =>
-                                  setState({ ...state, sort: defaultSort, page: 1 })
+                                  setState({
+                                    ...state,
+                                    sort: defaultSort,
+                                    page: 1,
+                                  })
                                 }
                                 className="inline-flex items-center gap-1 text-xs text-muted-foreground transition-colors hover:text-foreground"
                               >
@@ -2324,7 +2300,12 @@ export function ActionList<TInput, TItem>({
                             }
                             options={[
                               ...(defaultSort === null
-                                ? [{ value: "__none__", label: "Sem ordenação" }]
+                                ? [
+                                    {
+                                      value: "__none__",
+                                      label: "Sem ordenação",
+                                    },
+                                  ]
                                 : []),
                               ...sortableFields,
                             ]}
@@ -2468,6 +2449,36 @@ export function ActionList<TInput, TItem>({
                 </div>
               </PopoverContent>
             </Popover>
+            {hasSegment && (
+              <ToggleGroup
+                type="single"
+                variant="outline"
+                data-slot="action-list-views"
+                className="shrink-0"
+                value={activeView}
+                onValueChange={(key) => {
+                  // No single o Radix DESMARCA ao clicar no ativo (chega '') — o segment
+                  // de views sempre tem uma ativa, então o vazio não passa.
+                  if (key !== "")
+                    setState({
+                      ...state,
+                      view: key === viewEntries[0]?.[0] ? null : key,
+                    });
+                }}
+              >
+                {viewEntries.map(([key, label, icon]) => (
+                  <Tooltip key={key}>
+                    <TooltipTrigger asChild>
+                      <Toggle value={key} aria-label={label}>
+                        {icon ?? label}
+                      </Toggle>
+                    </TooltipTrigger>
+                    <TooltipContent>{label}</TooltipContent>
+                  </Tooltip>
+                ))}
+              </ToggleGroup>
+            )}
+            {viewControls}
           </>
         }
         actions={toolbarActions}
@@ -2838,10 +2849,9 @@ export function ActionList<TInput, TItem>({
   //   Encosta na última linha: a borda de cima é o fecho da tabela, não a de um
   //   bloco solto, então o rodapé não entra no `gap` da pilha.
   //   Altura: 2.5rem de piso (a mesma do `TableHead`) para a faixa não mudar de
-  //   tamanho quando o pager aparece — ele ocupa 1.75rem e cabe dentro do piso.
-  //   O padding fica em 0.25rem só para o dia em que o conteúdo passar disso:
-  //   com `py-2` o padding empurraria o pager para fora e a faixa voltaria a
-  //   crescer —
+  //   tamanho quando o pager aparece — ele ocupa 2rem e cabe dentro do piso.
+  //   O padding vertical de 0.125rem acomoda o pager de 2rem e a borda dentro
+  //   do piso, mantendo a altura igual quando não há paginação.
   const pages =
     total !== undefined
       ? Math.max(1, Math.ceil(total / (state.limit ?? pageSize)))
@@ -2872,7 +2882,7 @@ export function ActionList<TInput, TItem>({
     total !== undefined && !isError && activeGroupBy !== null ? (
       <div
         data-slot="action-list-footer"
-        className="flex min-h-10 flex-wrap items-center justify-between gap-3 border-t border-border px-3 py-1 text-xs text-muted-foreground"
+        className="flex min-h-10 flex-wrap items-center justify-between gap-3 border-t border-border px-3 py-0.5 text-xs text-muted-foreground"
       >
         {displaySummary}
         <span className={cn(displaySummary === null && "ml-auto")}>
@@ -2882,7 +2892,7 @@ export function ActionList<TInput, TItem>({
     ) : total !== undefined && !isError ? (
       <div
         data-slot="action-list-footer"
-        className="grid min-h-10 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-3 border-t border-border px-3 py-1 text-xs text-muted-foreground"
+        className="grid min-h-10 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-3 border-t border-border px-3 py-0.5 text-xs text-muted-foreground"
       >
         <span className="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1">
           <span className="whitespace-nowrap">
@@ -2893,7 +2903,7 @@ export function ActionList<TInput, TItem>({
         </span>
         {pages > 1 && (
           // A primitiva pública na escala densa do rodapé: setas no quadrado `icon-sm`,
-          // números `h-7 min-w-7` que crescem com os dígitos (5726 e 5727 não se colam).
+          // números `sm` que crescem com os dígitos (5726 e 5727 não se colam).
           <Pagination className="mx-0 w-auto">
             <PaginationContent className="gap-0.5">
               <PaginationItem>
@@ -2915,7 +2925,8 @@ export function ActionList<TInput, TItem>({
                     <PaginationLink
                       page={n}
                       isActive={n === state.page}
-                      className="h-7 min-w-7 text-xs"
+                      size="sm"
+                      className="text-xs"
                       onClick={() => goTo(n)}
                     />
                   </PaginationItem>
@@ -2977,9 +2988,7 @@ export function ActionList<TInput, TItem>({
               className={cn(
                 "min-h-0",
                 layout === "fill" && "overflow-auto",
-                busy &&
-                  items.length > 0 &&
-                  "pointer-events-none opacity-60",
+                busy && items.length > 0 && "pointer-events-none opacity-60",
               )}
             >
               {body}
@@ -3049,7 +3058,7 @@ export function ActionList<TInput, TItem>({
 // URL sync — a serialização padrão do estado da toolbar (querystring compacta)
 // =============================================================================
 //
-// Convenção: `q` · `sort=chave:dir` (omitido quando é o default do contrato) ·
+// Convenção: `q` · `sort=key:dir` (omitido quando é o default do contrato) ·
 // `period=preset` relativo ou `period=from..to` (o custom é implícito; default
 // omitido) · `view` (omitida quando é a primeira) · `cols=a,b,c` (omitida no
 // default) · filtros pelo PRÓPRIO nome (multiple → CSV). Quem embala liga: