@softize/opus 26.1.0 → 27.0.0

package/CHANGELOG.md

@@ -7,6 +7,63 @@ 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.
 
+## 27.0.0 — 2026-10-13
+
+O aplicativo passa a saber, na recusa de um anexo, o que entrou na mesma ação, e o glob do runtime
+de design passa a seguir a semântica usual de `**`. A seção **Breaking** traz as migrações, que
+atingem só quem chama `onReject` diretamente ou passa um handler com um segundo parâmetro opcional de
+outro tipo.
+
+- **Recusa com os aceitos da mesma ação.** `ComposerAttachments.onReject` recebe um segundo
+  argumento, `ComposerRejectionContext`, com `accepted`: os arquivos aceitos na mesma escolha,
+  colagem ou soltura, ou uma lista vazia quando nada passou. Assim o aplicativo explica uma soltura
+  mista, como uma imagem e um PDF arrastados juntos, sem guardar estado entre as duas chamadas. O
+  tipo `ComposerRejectionContext` sai de `@softize/opus/ui/react`.
+- **Ordem das chamadas documentada.** Em uma ação com arquivos aceitos e recusados, `onAddFiles`
+  roda antes de `onReject`, de forma síncrona e uma vez cada. O mesmo vale para o soltar sobre a
+  conversa do `Chat`. A ordem já era essa; agora faz parte do contrato.
+- **`**` casa zero ou mais pastas no glob de `opusDesign`.** Em `entry` e `scenarios`, `**` como
+  pasta inteira segue a semântica usual. Antes, `design/scenarios/**/*.ts` exigia pelo menos uma
+  subpasta e ignorava, sem aviso, o cenário salvo direto em `design/scenarios/`. Um projeto com
+  `**/` no padrão pode passar a carregar arquivos que antes ficavam de fora; se dois cenários da
+  mesma action passarem a entrar, o runtime de design deixa de subir e o erro lista a action.
+- **`?` literal no glob.** Antes, o `?` virava quantificador de regex, e `design/*/a?.ts` casava
+  `design/x/.ts`. Os demais padrões sem `**` continuam casando os mesmos arquivos.
+
+### Breaking
+
+**O contexto de `onReject` é obrigatório na assinatura.** Quem implementa o callback com um só
+parâmetro não muda nada. Duas situações deixam de compilar:
+
+- quem chama `onReject` diretamente, como ao reaproveitar o tipo `ComposerAttachments` em uma área de
+  soltar própria. Migração: passe `{ accepted }`, com uma lista vazia quando nada foi aceito:
+
+  ```ts
+  // antes: attachments.onReject?.(rejected)
+  attachments.onReject?.(rejected, { accepted })
+  ```
+
+- quem passa direto um handler que já declarava um segundo parâmetro opcional de outro tipo. Migração:
+  envolva o handler, como em `(rejections) => handle(rejections)`.
+
+## 26.2.0 — 2026-10-09
+
+Portais podem organizar capítulos em subgrupos e abrir ferramentas relacionadas sem substituir
+a página em leitura.
+
+- `DocGroup.groups` declara subgrupos opcionais. Navegação, busca, URLs diretas e sequência
+  editorial percorrem todos os níveis, com as páginas próprias antes dos subgrupos. A busca
+  preserva os ancestrais dos resultados; no modo inicialmente recolhido, restaura o estado
+  manual ao limpar. No modo expandido, os ancestrais da página ativa são reabertos. Ramos
+  vazios não aparecem, sem sugerir outro termo quando não há consulta.
+- `DocBrowser.sidebarLinks` preserva a navegação nativa para URLs HTTP(S) absolutas.
+- `SidebarItem` e `DocBrowser.sidebarLinks` aceitam `newTab`: o link abre em outra aba com
+  `noopener noreferrer` e informa a abertura no nome acessível. No portal, também exibe
+  um ícone de nova aba. A opção não intercepta a navegação nem chama `onClick`.
+
+As novas propriedades são opcionais. Consumidores sem subgrupos ou `newTab` mantêm seus
+contratos; não há migração obrigatória nesta versão.
+
 ## 26.1.0 — 2026-10-09
 
 Subheadings descrevem a finalidade da superfície; orientações necessárias ficam visíveis no corpo

package/docs/adr/0057-doc-browser-permite-busca-no-chrome-do-consumidor.md

@@ -39,6 +39,19 @@ de ADRs ou versões.
 
 ### Hierarquia e leitura
 
+> **Emenda — 2026-10-08, protótipo local:** `DocGroup.groups` permite subgrupos
+> opcionais. Um assunto como Integrações pode pertencer a Domínios e ainda reunir
+> páginas por sistema. A navegação, a busca, a seleção direta e a sequência de
+> leitura percorrem os mesmos grupos aninhados. Páginas próprias aparecem antes
+> dos subgrupos; ramos sem resultados somem da busca, sem perder a abertura manual.
+> O contrato anterior continua válido quando `groups` é omitido. Uma árvore paralela
+> no host e rótulos artificiais para simular profundidade foram descartados por
+> duplicar comportamento ou perder a hierarquia. Testes de links diretos, busca,
+> grupos vazios, rótulos repetidos e continuidade verificam a extensão.
+
+> **Consolidação — 2026-10-09:** a extensão de subgrupos compõe o candidato da versão
+> 26.2.0, sobre a base 26.1.0. Publicação e adoção permanecem etapas separadas.
+
 `sidebarSize` configura a largura inicial usando o `PaneSize` do `Split`. A omissão preserva
 `14rem`. `sidebarInitiallyCollapsed` permite começar com seções e grupos nomeados recolhidos,
 inclusive quando a pessoa abre uma página por URL direta. A busca revela os resultados
@@ -52,6 +65,16 @@ Esses destinos usam `SidebarItem.href`, não uma cópia do estilo da linha. A ex
 botão quando `href` é omitido, o foco nos dois modos e a abertura nativa em outra aba. Quando há
 `onClick`, somente a navegação simples é interceptada; o host mantém a decisão de roteamento.
 
+> **Emenda — 2026-10-09:** destinos HTTP(S) absolutos em `sidebarLinks` usam a navegação
+> nativa, pois podem apontar para outra aplicação. `newTab` é opcional em `SidebarItem`
+> e `sidebarLinks`: com `href`, declara `target="_blank"`, `rel="noopener noreferrer"`
+> e a abertura no nome acessível, sem chamar `onClick`. Sem `href`, não muda o botão.
+> O portal acrescenta o ícone pelo slot `badge` do item canônico. Interceptar esses
+> destinos no roteador ou copiar a linha no host foi descartado: o primeiro impede
+> a navegação entre aplicações e o segundo duplica foco, acessibilidade e composição.
+> Testes verificam links internos e absolutos, modificadores, nome acessível, ícone
+> nos dois modos iniciais do portal e comportamento do item aberto ou recolhido.
+
 O modo opcional `editorial` acrescenta contexto, sumário dos headings realmente renderizados e
 links de continuidade segundo a ordem declarada. `additionalPages` preserva URLs de páginas fora
 da árvore e da sequência. O renderer de exemplos aceita `codeCollapsible={false}` quando ocultar
@@ -143,6 +166,10 @@ e separa a consulta documental da consulta local.
 
 - Testes de `DocBrowser`: busca local e externa, vazio, largura configurável, lateral opcional,
   persistência de grupos, expansão temporária, conteúdo do host, redirects e leitura editorial.
+- Regressões da extensão: espaçamento dos grupos sem rótulo em diferentes níveis, acervo vazio
+  sem consulta, modificadores em links absolutos e ícone de nova aba nos dois modos iniciais.
+- Testes de `SidebarItem`: nova aba com modificadores, botão habilitado sem `href`, estado
+  desabilitado e preservação do badge textual no nome acessível do item aberto.
 - Testes de `DocHeader`: slots, atributos nativos e composição com ou sem busca e navegação.
 - Testes de `DocCatalog`: busca local controlada, independência do topo, ausência de controles de
   coleção, texto integral das versões, incompatibilidades e abertura nativa em outra aba.

package/docs/adr/0058-mensagem-da-ia-aceita-imagem-e-o-chat-recebe-anexos.md

@@ -116,6 +116,18 @@ imagem. Assim, retenção, expiração, governança e dado pessoal ficam com que
   imagem, e `ChatMessage` continua só com texto. Se um consumidor precisar, uma nova decisão define
   como.
 
+> **Emenda — 2026-10-13:** a ordem entre as duas chamadas da triagem passa a ser garantida. Em uma
+> mesma escolha, colagem ou soltura com arquivos aceitos e recusados, `onAddFiles` roda antes de
+> `onReject`, de forma síncrona e uma vez cada, também no soltar sobre a conversa do `Chat`.
+> `onReject` recebe um segundo argumento, `context: ComposerRejectionContext`, cujo `accepted`
+> traz os arquivos aceitos na mesma ação, ou uma lista vazia quando nada passou. Com ele, o app
+> explica uma soltura mista sem guardar estado entre as duas chamadas; a adoção pela Grand Brasil
+> mostrou a necessidade. O contexto é obrigatório na assinatura: opcional, ele obrigaria quem
+> desestrutura `{ accepted }` a tratar `undefined`, embora o composer sempre o informe. Quem
+> implementa o callback com um só parâmetro não muda nada; quem chama `onReject` diretamente precisa
+> passar o contexto, e um handler com segundo parâmetro opcional de outro tipo precisa ser envolvido.
+> Por essas migrações, a mudança saiu como major, na 27.0.0.
+
 ### 6. Preparação da imagem no navegador
 
 `prepareImage(file, options)` prepara a imagem antes do envio, com os tetos que o app passa:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "26.1.0",
+  "version": "27.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

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

@@ -79,6 +79,8 @@ export interface SidebarItemProps {
   className?: string;
   /** Destino nativo. Com onClick, intercepta somente a navegação simples; preserva novas abas. */
   href?: string;
+  /** Abre o destino em nova aba, sem interceptar a navegação nativa. */
+  newTab?: boolean;
   onClick?: () => void;
 }
 
@@ -98,11 +100,19 @@ export function SidebarItem({
   className,
   onClick,
   href,
+  newTab = false,
 }: SidebarItemProps): React.ReactElement {
   const collapsed = useSidebarCollapsed();
   const Target = href !== undefined && !disabled ? "a" : "button";
   const targetProps =
-    Target === "a" ? { href } : { type: "button" as const, disabled };
+    Target === "a"
+      ? {
+          href,
+          ...(newTab ? { target: "_blank", rel: "noopener noreferrer" } : {}),
+        }
+      : { type: "button" as const, disabled };
+  const accessibleLabel =
+    Target === "a" && newTab ? `${label} (abre em nova aba)` : label;
   const activate = (
     event: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement>,
   ) => {
@@ -113,6 +123,7 @@ export function SidebarItem({
         event.ctrlKey ||
         event.shiftKey ||
         event.altKey ||
+        newTab ||
         !onClick
       )
         return;
@@ -129,7 +140,7 @@ export function SidebarItem({
     const button = (
       <Target
         {...targetProps}
-        aria-label={label}
+        aria-label={accessibleLabel}
         aria-current={active ? "page" : undefined}
         onClick={activate}
         className={cn(
@@ -156,7 +167,7 @@ export function SidebarItem({
         <Tooltip>
           <TooltipTrigger asChild>{button}</TooltipTrigger>
           <TooltipContent side="right">
-            {label}
+            {accessibleLabel}
             {tooltipHint}
           </TooltipContent>
         </Tooltip>
@@ -275,6 +286,9 @@ export function SidebarItem({
             {badge}
           </span>
         )}
+        {Target === "a" && newTab && (
+          <span className="sr-only"> (abre em nova aba)</span>
+        )}
       </Target>
       {hasActions && (
         <div

package/src/ui/components/primitives/composer.tsx

@@ -29,14 +29,25 @@ export interface ComposerFileRejection {
   reason: "type" | "limit";
 }
 
+/** O que mais aconteceu na mesma ação (escolher, colar ou soltar) que gerou as recusas. */
+export interface ComposerRejectionContext {
+  /** Arquivos aceitos na mesma ação, já entregues a `onAddFiles`; vazio quando nenhum passou. */
+  accepted: File[];
+}
+
 /**
  * Anexos da mensagem, controlados pelo app (ADR 0058). O composer faz a triagem e mostra a faixa;
  * preparar, enviar, guardar e limpar depois do envio são do app, que é o dono do transporte.
+ *
+ * Em uma mesma ação com arquivos aceitos e recusados, `onAddFiles` é chamado antes de `onReject`,
+ * de forma síncrona e uma vez cada. Ação sem aceito não chama `onAddFiles`; sem recusado, não
+ * chama `onReject`.
  */
 export interface ComposerAttachments {
   /** Anexos pendentes, na ordem em que aparecem na faixa. */
   items: ComposerAttachment[];
-  /** Recebe os arquivos aceitos pela triagem — do botão, do colar ou do soltar. */
+  /** Recebe os arquivos aceitos pela triagem — do botão, do colar ou do soltar. Na mesma ação,
+   *  roda antes de `onReject`. */
   onAddFiles: (files: File[]) => void;
   /** A pessoa removeu um anexo da faixa. */
   onRemove: (id: string) => void;
@@ -46,8 +57,10 @@ export interface ComposerAttachments {
    *  Não há curinga (`image/*`): a triagem compara o tipo exato do arquivo. */
   accept?: readonly AiImageMediaType[];
   /** Recebe os arquivos recusados. Presente, a explicação da recusa é do app; ausente, o
-   *  composer a mostra acima do campo. */
-  onReject?: (rejections: ComposerFileRejection[]) => void;
+   *  composer a mostra acima do campo. Roda depois de `onAddFiles` na mesma ação, e
+   *  `context.accepted` traz os arquivos aceitos nela (vazio quando nenhum passou) — o app
+   *  distingue "nada entrou" de "parte entrou" sem guardar estado entre as duas chamadas. */
+  onReject?: (rejections: ComposerFileRejection[], context: ComposerRejectionContext) => void;
 }
 
 /** Limite padrão de anexos por mensagem. */
@@ -296,7 +309,8 @@ export function Composer({
   const twoRow = actions !== undefined || attachments !== undefined;
 
   /** Triagem: tipo aceito e espaço na mensagem. Os aceitos vão ao app; os recusados, ao
-   *  `onReject` do app ou ao aviso do composer. */
+   *  `onReject` do app ou ao aviso do composer. A ordem (aceitos antes, recusados depois, com os
+   *  aceitos no contexto) é contrato público de `ComposerAttachments`. */
   const intake = (files: File[]): void => {
     if (attachments === undefined || files.length === 0) return;
     const remaining = Math.max(0, max - items.length);
@@ -309,7 +323,7 @@ export function Composer({
     }
     if (accepted.length > 0) attachments.onAddFiles(accepted);
     if (rejected.length > 0 && attachments.onReject !== undefined) {
-      attachments.onReject(rejected);
+      attachments.onReject(rejected, { accepted });
       setNotice(null);
     } else {
       setNotice(rejected.length > 0 ? rejectionMessage(rejected, accept, max) : null);

package/src/ui/docs/DocBrowser.tsx

@@ -12,8 +12,15 @@
  * Nos dois, navegar emite `popstate`: host que guarda o path por conta própria acompanha.
  * `basePath` adapta o prefixo das URLs (`/docs` no Maestro, `/__docs` nos apps).
  */
-import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
-import { ArrowLeft, ArrowRight, Search } from "lucide-react";
+import {
+  Fragment,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { ArrowLeft, ArrowRight, ExternalLink, Search } from "lucide-react";
 import type { DocEntry, DocGroup, DocSection } from "./types.ts";
 import { Pane, Split, type PaneSize } from "../components/patterns/split.tsx";
 import { Input } from "../components/primitives/input.tsx";
@@ -33,14 +40,28 @@ import {
 } from "../components/patterns/sidebar.tsx";
 import { navigate, usePathname } from "../router.ts";
 
+function documentEntries(
+  sections: DocSection[],
+): Array<{ entry: DocEntry; context: string }> {
+  const entriesFrom = (
+    groups: DocGroup[],
+    parent: string,
+  ): Array<{ entry: DocEntry; context: string }> =>
+    groups.flatMap((group) => {
+      const context = group.label?.trim() || parent;
+      return [
+        ...group.pages.map((entry) => ({ entry, context })),
+        ...entriesFrom(group.groups ?? [], context),
+      ];
+    });
+  return sections.flatMap((section) =>
+    entriesFrom(section.groups, section.label),
+  );
+}
+
 function findPage(sections: DocSection[], slug: string): DocEntry | undefined {
-  for (const s of sections) {
-    for (const g of s.groups) {
-      const p = g.pages.find((p) => p.slug === slug);
-      if (p) return p;
-    }
-  }
-  return undefined;
+  return documentEntries(sections).find(({ entry }) => entry.slug === slug)
+    ?.entry;
 }
 
 interface DocBrowserSearchCopy {
@@ -58,7 +79,7 @@ export interface DocBrowserProps {
   basePath?: string;
   /** Path controlado pelo host (modo Maestro). Ausente = standalone (gerencia o próprio). */
   path?: string;
-  /** Seções a exibir (seção → grupo → página). */
+  /** Seções a exibir; grupos podem conter páginas e subgrupos. */
   sections: DocSection[];
   /** Slugs antigos que devem abrir e substituir a URL pela página canônica. */
   redirects?: Readonly<Record<string, string>>;
@@ -79,8 +100,13 @@ export interface DocBrowserProps {
   additionalPages?: DocEntry[];
   /** Substitui a leitura, mantendo a árvore; o host resolve conteúdo, título e rota. */
   content?: ReactNode;
-  /** Destinos fora dos capítulos; não participam da sequência de leitura. */
-  sidebarLinks?: Array<{ label: string; href: string; active?: boolean }>;
+  /** Destinos fora dos capítulos; `newTab` abre em nova aba com ícone e descrição acessível. */
+  sidebarLinks?: Array<{
+    label: string;
+    href: string;
+    active?: boolean;
+    newTab?: boolean;
+  }>;
   /** Seções e grupos começam recolhidos; a busca revela resultados sem mudar a escolha manual. */
   sidebarInitiallyCollapsed?: boolean;
 }
@@ -116,14 +142,7 @@ function EditorialDocument({
   const [headings, setHeadings] = useState<
     Array<{ id: string; title: string }>
   >([]);
-  const entries = sections.flatMap((section) =>
-    section.groups.flatMap((group) =>
-      group.pages.map((entry) => ({
-        entry,
-        context: group.label || section.label,
-      })),
-    ),
-  );
+  const entries = documentEntries(sections);
   const index = entries.findIndex(({ entry }) => entry.slug === page.slug);
   const previous = index > 0 ? entries[index - 1]?.entry : undefined;
   const next = index >= 0 ? entries[index + 1]?.entry : undefined;
@@ -271,9 +290,14 @@ function searchable(value: string): string {
     .toLocaleLowerCase("pt-BR");
 }
 
+type SidebarGroup = Omit<DocGroup, "groups"> & {
+  navigationKey: string;
+  groups: SidebarGroup[];
+};
+
 type SidebarSection = Omit<DocSection, "groups"> & {
   navigationKey: string;
-  groups: Array<DocGroup & { navigationKey: string }>;
+  groups: SidebarGroup[];
 };
 
 function filterSections(
@@ -282,25 +306,35 @@ function filterSections(
 ): SidebarSection[] {
   const terms = searchable(query).split(/\s+/).filter(Boolean);
   // Identidade vem do manifesto completo, antes de remover ramos pela busca.
+  const indexGroups = (groups: DocGroup[], parent: string): SidebarGroup[] =>
+    groups.map((group, index) => {
+      const navigationKey = `${parent}:${index}`;
+      return {
+        ...group,
+        navigationKey,
+        groups: indexGroups(group.groups ?? [], navigationKey),
+      };
+    });
   const indexedSections = sections.map((section, sectionIndex) => ({
     ...section,
     navigationKey: `section:${sectionIndex}`,
-    groups: section.groups.map((group, groupIndex) => ({
-      ...group,
-      navigationKey: `group:${sectionIndex}:${groupIndex}`,
-    })),
+    groups: indexGroups(section.groups, `group:${sectionIndex}`),
   }));
-  if (terms.length === 0) return indexedSections;
-  return indexedSections.flatMap((section) => {
-    const groups = section.groups.flatMap((group) => {
+  const matchingGroups = (groups: SidebarGroup[]): SidebarGroup[] =>
+    groups.flatMap((group) => {
       const pages = group.pages.filter((page) => {
         const text = searchable(
           `${page.title}\n${page.navigationTitle ?? ""}\n${page.badge ?? ""}\n${page.searchText ?? ""}`,
         );
         return terms.every((term) => text.includes(term));
       });
-      return pages.length === 0 ? [] : [{ ...group, pages }];
+      const children = matchingGroups(group.groups);
+      return pages.length === 0 && children.length === 0
+        ? []
+        : [{ ...group, pages, groups: children }];
     });
+  return indexedSections.flatMap((section) => {
+    const groups = matchingGroups(section.groups);
     return groups.length === 0 ? [] : [{ ...section, groups }];
   });
 }
@@ -327,22 +361,21 @@ function DocSidebarTree({
 
   useEffect(() => {
     if (forceExpanded || initiallyCollapsed) return;
-    const activeGroup = sections
-      .flatMap((section) =>
-        section.groups.map((group) => ({
-          key: group.navigationKey,
-          group,
-        })),
-      )
-      .find(({ group }) =>
-        group.pages.some((page) => page.slug === activeSlug),
-      );
-
-    if (activeGroup === undefined) return;
+    const activePath = (groups: SidebarGroup[]): string[] => {
+      for (const group of groups) {
+        if (group.pages.some((page) => page.slug === activeSlug))
+          return [group.navigationKey];
+        const children = activePath(group.groups);
+        if (children.length > 0) return [group.navigationKey, ...children];
+      }
+      return [];
+    };
+    const keys = sections.flatMap((section) => activePath(section.groups));
+    if (keys.length === 0) return;
     setToggledBranches((current) => {
-      if (!current.has(activeGroup.key)) return current;
+      if (!keys.some((key) => current.has(key))) return current;
       const next = new Set(current);
-      next.delete(activeGroup.key);
+      keys.forEach((key) => next.delete(key));
       return next;
     });
   }, [activeSlug, forceExpanded, sections, initiallyCollapsed]);
@@ -372,6 +405,36 @@ function DocSidebarTree({
     />
   );
 
+  const renderGroup = (group: SidebarGroup): ReactNode => {
+    const key = group.navigationKey;
+    const children = [
+      ...group.pages.map(renderPage),
+      ...group.groups.map(renderGroup),
+    ];
+    if ((group.label ?? "").trim() === "") {
+      return <Fragment key={key}>{children}</Fragment>;
+    }
+    const expanded =
+      forceExpanded ||
+      (initiallyCollapsed
+        ? toggledBranches.has(key)
+        : !toggledBranches.has(key));
+    return (
+      <div key={key} className="space-y-0.5">
+        <SidebarItem
+          label={group.label!}
+          icon={group.icon}
+          expanded={expanded}
+          onToggle={forceExpanded ? undefined : () => toggleGroup(key)}
+          onClick={() => {
+            if (!forceExpanded) toggleGroup(key);
+          }}
+        />
+        {expanded && <SidebarTreeGroup>{children}</SidebarTreeGroup>}
+      </div>
+    );
+  };
+
   return (
     <nav
       aria-label="Navegação da documentação"
@@ -384,38 +447,7 @@ function DocSidebarTree({
           initiallyCollapsed && section.label.trim() !== "";
         const sectionExpanded =
           forceExpanded || toggledBranches.has(sectionBranch);
-        const groups = section.groups.map((group) => {
-          const key = group.navigationKey;
-          if (group.pages.length === 0) return null;
-          if ((group.label ?? "").trim() === "") {
-            return group.pages.map((page) => renderPage(page));
-          }
-
-          const expanded =
-            forceExpanded ||
-            (initiallyCollapsed
-              ? toggledBranches.has(key)
-              : !toggledBranches.has(key));
-          return (
-            <div key={key} className="space-y-0.5">
-              <SidebarItem
-                label={group.label!}
-                icon={group.icon}
-                expanded={expanded}
-                onToggle={forceExpanded ? undefined : () => toggleGroup(key)}
-                // Durante a busca, o grupo é contexto dos resultados e permanece aberto.
-                onClick={() => {
-                  if (!forceExpanded) toggleGroup(key);
-                }}
-              />
-              {expanded && (
-                <SidebarTreeGroup>
-                  {group.pages.map((page) => renderPage(page))}
-                </SidebarTreeGroup>
-              )}
-            </div>
-          );
-        });
+        const groups = section.groups.map(renderGroup);
         return (
           <div key={sectionBranch} className="space-y-0.5">
             {collapsibleSection ? (
@@ -452,9 +484,24 @@ function DocSidebarTree({
               key={link.href}
               href={link.href}
               active={link.active}
-              onClick={() => navigate(link.href)}
+              newTab={link.newTab}
+              badge={
+                link.newTab ? (
+                  <ExternalLink
+                    aria-hidden="true"
+                    className="size-3.5 text-muted-foreground"
+                  />
+                ) : undefined
+              }
+              onClick={
+                link.newTab || /^https?:\/\//i.test(link.href)
+                  ? undefined
+                  : () => navigate(link.href)
+              }
               label={link.label}
-              icon={initiallyCollapsed ? <span aria-hidden="true" /> : undefined}
+              icon={
+                initiallyCollapsed ? <span aria-hidden="true" /> : undefined
+              }
             />
           ))}
         </div>
@@ -485,8 +532,8 @@ export function DocBrowser({
   // hooks); o que muda é quem vence no `??`.
   const livePath = usePathname();
   const path = controlledPath ?? livePath;
-  // Default = 1ª página do 1º grupo da 1ª seção (a doc abre na 1ª página).
-  const defaultSlug = sections[0]?.groups[0]?.pages[0]?.slug ?? "";
+  // Abre na primeira página do percurso, inclusive dentro de subgrupos.
+  const defaultSlug = documentEntries(sections)[0]?.entry.slug ?? "";
   // Slug = TODOS os segmentos após o basePath, unidos (rota aninhada: `/docs/guias/deploy`
   // → `guias/deploy`). Slug flat de 1 segmento continua igual (`join` de 1 elemento = ele).
   const rel = path.startsWith(basePath) ? path.slice(basePath.length) : "";
@@ -567,14 +614,14 @@ export function DocBrowser({
             <div className="min-h-0 flex-1 overflow-y-auto px-3 py-6">
               <p
                 className={
-                  visibleSections.length === 0
+                  query.trim() !== "" && visibleSections.length === 0
                     ? "px-2 text-sm text-muted-foreground"
                     : "sr-only"
                 }
                 role={search === false ? undefined : "status"}
                 aria-atomic={search === false ? undefined : "true"}
               >
-                {visibleSections.length === 0
+                {query.trim() !== "" && visibleSections.length === 0
                   ? (searchOptions.emptyMessage ??
                     "Nenhum documento encontrado. Tente outro termo.")
                   : ""}

package/src/ui/docs/content/actions.md

@@ -321,9 +321,11 @@ export const eventDetail = defineDesignScenario(eventGet, (input) => ({
 
 A resposta é tipada pela entrada e pela saída do contrato; em `list`, é a página inteira. Informe ao
 plugin onde os cenários estão, com caminhos ou globs:
-`opusDesign({ scenarios: 'design/scenarios/*.ts' })`. O cenário vence a resposta gerada. Um cenário
-de uma action que não existe, ou dois cenários para a mesma action, impedem o runtime de design de
-subir, e o erro lista os nomes.
+`opusDesign({ scenarios: 'design/scenarios/**/*.ts' })`. Nos globs, `*` casa parte do nome dentro
+de uma pasta e `**` casa qualquer número de pastas, inclusive nenhuma: o padrão do exemplo carrega
+tanto `design/scenarios/pedidos.ts` quanto `design/scenarios/pedidos/lista.ts`. O cenário vence a
+resposta gerada. Um cenário de uma action que não existe, ou dois cenários para a mesma action,
+impedem o runtime de design de subir, e o erro lista os nomes.
 
 O Opus não decide onde os cenários ficam nem se entram no repositório. Eles não fazem parte da
 aplicação: podem ficar em uma pasta ignorada pelo git e ser escritos durante a sessão de design,

package/src/ui/docs/content/chat.md

@@ -261,6 +261,11 @@ O arraste de arquivos sobre a conversa é consumido pelo Chat e não sobe para o
 aplicativo: um contêiner com o próprio soltar, como uma área de envio de arquivos, não recebe a mesma
 imagem duas vezes. Sem `composerAttachments`, o arraste segue para o contêiner, como antes.
 
+O soltar sobre a conversa passa pela mesma triagem do composer. Quando ele traz imagens aceitas e
+arquivos recusados juntos, `onAddFiles` recebe as imagens primeiro, e `onReject`, quando presente,
+recebe os recusados logo depois, com as imagens da mesma ação em `accepted`. Veja
+[recusas no Composer](/ui/composer#com-imagens-anexadas).
+
 ## Propriedades de Chat
 
 | Propriedade | Tipo | Padrão | Descrição |

package/src/ui/docs/content/composer.md

@@ -143,6 +143,23 @@ curinga como `image/*`. O que fica de fora é explicado acima do campo, como “
 Para dar outra explicação, passe `onReject`: o composer deixa de mostrar o aviso e entrega os
 arquivos recusados, com o motivo, ao aplicativo.
 
+Uma mesma escolha, colagem ou soltura pode trazer arquivos aceitos e recusados, como uma imagem e um
+PDF arrastados juntos. O segundo argumento de `onReject`, do tipo `ComposerRejectionContext`, traz
+em `accepted` os aceitos da mesma ação, e a lista vem vazia quando nada passou. Em uma ação mista,
+`onAddFiles` roda antes de `onReject`. Assim o aplicativo explica a recusa conforme o resultado, sem
+guardar estado entre as duas chamadas:
+
+```ts
+const onReject: ComposerAttachments['onReject'] = (rejections, { accepted }) => {
+  const names = rejections.map((r) => r.file.name).join(', ')
+  notify(
+    accepted.length > 0
+      ? `Parte dos arquivos foi anexada. Ficaram de fora: ${names}.`
+      : `Nenhum arquivo foi anexado. Ficaram de fora: ${names}.`,
+  )
+}
+```
+
 Colar texto continua colando texto, mesmo quando a área de transferência também traz uma imagem, como
 ao copiar células de uma planilha. Uma imagem colada sem texto, como um print, recebe um nome que a
 pessoa reconhece na conversa: “Imagem colada 1.png”. A numeração não volta atrás: remover a primeira e
@@ -197,11 +214,11 @@ mesmos que o servidor confere.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `items` | `ComposerAttachment[]` | | Imagens anexadas à mensagem que está sendo escrita, na ordem da faixa. |
-| `onAddFiles` | `(files: File[]) => void` | | Recebe os arquivos aceitos pela triagem, vindos do botão, do colar ou do soltar. |
+| `onAddFiles` | `(files: File[]) => void` | | Recebe os arquivos aceitos pela triagem, vindos do botão, do colar ou do soltar. Em uma ação com aceitos e recusados, é chamado antes de `onReject`. |
 | `onRemove` | `(id: string) => void` | | A pessoa removeu uma imagem da faixa; o foco volta ao campo. |
 | `max` | `number` | `4` | Limite de imagens por mensagem. O botão de anexar fica desabilitado quando ele é atingido. |
 | `accept` | `readonly AiImageMediaType[]` | PNG, JPEG e WebP | Formatos aceitos pelo botão e pela triagem, comparados com o tipo exato do arquivo. |
-| `onReject` | `(rejections: ComposerFileRejection[]) => void` | | Recebe os arquivos recusados, com o motivo `type` ou `limit`. Sem ele, o composer explica a recusa acima do campo. |
+| `onReject` | `(rejections: ComposerFileRejection[], context: ComposerRejectionContext) => void` | | Recebe os arquivos recusados, com o motivo `type` ou `limit`, depois de `onAddFiles`; `context.accepted` (`File[]`) traz os arquivos aceitos na mesma ação e vem vazio quando nenhum passou. Sem ele, o composer explica a recusa acima do campo. |
 
 `ComposerAttachment` é `{ id, name, status, previewUrl?, error? }`. `status` vale `uploading`,
 `ready` ou `failed`; `previewUrl` é o endereço da miniatura e `error` é o motivo mostrado quando a

package/src/ui/docs/content/documentation-portal.md

@@ -46,6 +46,36 @@ conceitos relacionados, não para reproduzir automaticamente a árvore de arquiv
 tem `slug`, `title` e `render`; `searchText` acrescenta conteúdo à busca e `navigationTitle` permite
 um rótulo lateral curto sem mudar o título completo.
 
+Um grupo pode conter páginas próprias e subgrupos em `groups`. Por exemplo, uma documentação
+por domínio pode reunir as conexões externas em Integrações e manter um grupo por sistema:
+
+```tsx
+const sections: DocSection[] = [{
+  label: 'Domínios',
+  groups: [{
+    label: 'Integrações',
+    pages: [{ slug: 'integrations', title: 'Integrações', render: () => <p>Conexões com sistemas externos.</p> }],
+    groups: [{
+      label: 'Insider',
+      pages: [{ slug: 'integrations/insider', title: 'Insider', render: () => <p>Envio de atributos e eventos.</p> }],
+    }],
+  }],
+}]
+```
+
+As páginas próprias vêm antes dos subgrupos na sequência de leitura. Um grupo com `pages: []`
+pode reunir somente subgrupos; ramos sem páginas em nenhum nível não aparecem na lateral.
+O contexto editorial usa o grupo nomeado mais próximo. A busca revela os ancestrais dos
+resultados e, no modo `sidebarInitiallyCollapsed`, restaura os ramos abertos manualmente
+quando a consulta é limpa. No modo expandido padrão, os ancestrais da página ativa são
+reabertos para mantê-la visível. `groups` é opcional:
+as declarações existentes continuam válidas. Essa hierarquia é uma escolha de leitura do host,
+não exige mover arquivos nem muda a descoberta por pastas.
+
+Se o host também percorre as páginas para montar índices ou resolver links, esse percurso
+precisa visitar `group.groups` recursivamente. Achatar somente `section.groups[].pages`
+não inclui as páginas dos subgrupos.
+
 Com `editorial`, a leitura recebe contexto, sumário dos títulos renderizados e links de página
 anterior e seguinte. `additionalPages` preserva destinos diretos que não entram nessa sequência.
 A busca documental do topo mantém seu rótulo, valor e função ao navegar para catálogos e detalhes;
@@ -64,6 +94,19 @@ o contrato desktop a partir de `64rem`. O aplicativo organiza a moldura do porta
 
 ADRs e changelog mantêm o mapa dos guias, sem acrescentar uma árvore para cada registro. Use `sidebarLinks` para oferecer entradas
 no mesmo nível dos grupos, após os capítulos, sem incluí-las na sequência anterior/próxima.
+Destinos com URL HTTP(S) absoluta usam navegação nativa, inclusive para outro aplicativo;
+destinos relativos usam o roteamento compartilhado.
+
+Para abrir uma ferramenta sem substituir a leitura atual, declare `newTab` no destino:
+
+```tsx
+<DocBrowser sections={sections}
+  sidebarLinks={[{ label: 'Lente', href: '/lens', newTab: true }]} />
+```
+
+O link exibe um ícone de nova aba, informa a abertura no nome acessível e usa
+`rel="noopener noreferrer"`. Sem `newTab`, mantém a navegação na aba atual.
+
 `DocCatalog` recebe registros derivados dos Markdown e uma consulta local independente do cabeçalho.
 Passe o catálogo em `content` para preservar a lateral:
 
@@ -148,7 +191,7 @@ não define as rotas nem a autorização do aplicativo.
 
 | Propriedade | Tipo | Padrão | Uso |
 | --- | --- | --- | --- |
-| `sections` | `DocSection[]` | Obrigatória na entrada leve | Seções, grupos e páginas na ordem de leitura. |
+| `sections` | `DocSection[]` | Obrigatória na entrada leve | Seções, grupos, subgrupos opcionais e páginas na ordem de leitura. |
 | `basePath` | `string` | `/docs` | Prefixo das rotas. |
 | `path` | `string` | Rota compartilhada | Caminho controlado por um host externo. |
 | `redirects` | `Record<string, string>` | `{}` | Slugs anteriores e seus destinos canônicos. |
@@ -160,7 +203,7 @@ não define as rotas nem a autorização do aplicativo.
 | `navigationLabel` | `string` | `Documentação` | Nome da área no contexto editorial; por exemplo, `UI` para o catálogo de componentes. |
 | `additionalPages` | `DocEntry[]` | `[]` | Destinos diretos fora da árvore e da sequência. |
 | `content` | `ReactNode` | — | Conteúdo do host no lugar da página documental, mantendo a lateral. O host resolve rota e título; `null` deixa a leitura vazia. |
-| `sidebarLinks` | `{ label: string; href: string; active?: boolean }[]` | `[]` | Destinos globais fora dos capítulos; `active` marca o catálogo atual. |
+| `sidebarLinks` | `{ label: string; href: string; active?: boolean; newTab?: boolean }[]` | `[]` | Destinos globais fora dos capítulos; `active` marca o catálogo atual e `newTab` abre em outra aba com ícone e descrição acessível. |
 | `sidebarInitiallyCollapsed` | `boolean` | `false` | Seções e grupos nomeados começam recolhidos, inclusive em links diretos. A busca revela resultados temporariamente sem alterar os ramos abertos pela pessoa. |
 
 A entrada histórica `@softize/opus/ui/docs` inclui o catálogo e oferece suas páginas quando

package/src/ui/docs/content/sidebar.md

@@ -73,6 +73,10 @@ diretamente quando a composição precisar de controles, badges ou hierarquia pa
 Quando o host usa um roteador, forneça também `onClick`: somente o clique simples é interceptado;
 cliques com modificadores preservam o comportamento do link. Sem `href`, o item continua sendo um botão.
 
+Para manter a página atual aberta ao visitar outro destino, declare `newTab` junto de `href`.
+O link usa `target="_blank"` e `rel="noopener noreferrer"`, não chama `onClick` e informa
+“abre em nova aba” no nome acessível, inclusive no rail recolhido. Sem `href`, `newTab` não tem efeito.
+
 ## Colapso
 
 `collapsed` informa o estado compacto aos itens. Forneça labels acessíveis mesmo quando somente os
@@ -99,3 +103,22 @@ render(
 - `Sidebar` oferece a coluna de navegação.
 - `SidebarNav`, `SidebarItem` e elementos nativos organizam o conteúdo interno.
 - `Surface` oferece anatomia e tratamento visual quando a região não é uma sidebar.
+
+## Propriedades de SidebarItem
+
+| Propriedade | Tipo | Padrão | Uso |
+| --- | --- | --- | --- |
+| `label` | `string` | Obrigatória | Nome do destino, também usado no modo recolhido. |
+| `href` | `string` | — | Renderiza um link nativo quando o item está habilitado; sem ela, renderiza um botão. |
+| `newTab` | `boolean` | `false` | Com `href`, abre em outra aba, informa a abertura no nome acessível e não chama `onClick`. |
+| `onClick` | `() => void` | — | Ativa o botão ou intercepta o clique simples do link, exceto com `newTab`. |
+| `icon`, `badge` | `ReactNode` | — | Ícone e complemento visual da linha. O modo recolhido mostra somente o ícone. |
+| `active` | `boolean` | `false` | Destaca o destino atual e declara `aria-current="page"`. |
+| `disabled` | `boolean` | `false` | Desabilita o alvo principal e impede que seja um link. |
+| `actions` | `ReactNode` | — | Controles irmãos do alvo principal, no modo aberto. |
+| `onToggle` | `() => void` | — | Exibe um controle separado para expandir ou recolher descendentes no modo aberto. |
+| `expanded` | `boolean` | `false` | Estado visual e acessível do controle de expansão. |
+| `dropPosition` | `'before' \| 'inside' \| 'after'` | — | Indicação visual de posição durante arraste, no modo aberto. |
+| `dragProps` | `HTMLAttributes<HTMLDivElement>` | — | Eventos e atributos de arraste aplicados à linha. |
+| `tooltipHint` | `ReactNode` | — | Complementa o tooltip do modo recolhido. |
+| `className` | `string` | — | Classes da linha nos dois modos. |

package/src/ui/docs/types.ts

@@ -18,6 +18,8 @@ export interface DocGroup {
   label?: string
   icon?: React.ReactNode
   pages: DocEntry[]
+  /** Subgrupos opcionais; páginas próprias vêm antes dos grupos na sequência de leitura. */
+  groups?: DocGroup[]
 }
 
 export interface DocSection {

package/src/ui/react.tsx

@@ -73,6 +73,7 @@ export type {
   ComposerAttachmentStatus,
   ComposerAttachments,
   ComposerFileRejection,
+  ComposerRejectionContext,
 } from "./components/primitives/composer.tsx";
 // Preparação da imagem no navegador antes do envio (ADR 0058).
 export { prepareImage } from "./lib/prepare-image.ts";

package/src/vite/design.ts

@@ -82,7 +82,9 @@ export interface OpusDesignOptions {
    * CADA rebuild — domínio novo entra no ar ao salvar o arquivo, sem editar
    * entry nenhum. Dos módulos casados entram os exports (default e named) com
    * shape de registrável; schemas/helpers exportados junto ficam de fora.
-   * Pode misturar estáticos e globs no array.
+   * Pode misturar estáticos e globs no array. No glob, `*` casa parte de um
+   * nome dentro de uma pasta e `**` casa zero ou mais pastas:
+   * 'design/scenarios/**\/*.ts' inclui o arquivo solto em `design/scenarios/`.
    */
   entry?: string | string[]
 
@@ -531,17 +533,33 @@ async function loadGlobEntry(server: ViteDevServer, pattern: string): Promise<un
 }
 
 /**
- * Matcher próprio de propósito (sem dep nova): `*` casa um segmento (sem '/'),
- * `**` casa qualquer profundidade. Cobre o entry por pasta de domínio; padrão
- * exótico não suportado = aponte entries estáticos.
+ * Matcher próprio de propósito (sem dep nova): `*` casa parte de um segmento
+ * (sem '/'); `**` como segmento inteiro é globstar e casa zero ou mais pastas
+ * — `design/**\/*.ts` casa `design/a.ts`, `design/x/a.ts` e `design/x/y/a.ts`.
+ * No fim do padrão (`design/**`), casa qualquer arquivo abaixo da pasta. Cobre o
+ * entry por pasta de domínio e os cenários; padrão exótico não suportado =
+ * aponte entries estáticos.
+ *
+ * Exportada só para teste: o índice de `@softize/opus/vite` não a reexporta.
  */
-function globToRegExp(pattern: string): RegExp {
-  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&')
-  // `\u0000` como placeholder do `**`: nunca ocorre num path real.
-  const body = escaped
-    .replace(/\*\*/g, '\u0000')
-    .replace(/\*/g, '[^/]*')
-    .replace(/\u0000/g, '.*')
+export function globToRegExp(pattern: string): RegExp {
+  const segments = pattern.split('/')
+  const body = segments
+    .map((segment, index) => {
+      const last = index === segments.length - 1
+      // Globstar no começo ou no meio: o grupo opcional leva a barra junto, então
+      // "nenhuma pasta" casa sem exigir `//` no path.
+      if (segment === '**') return last ? '.*' : '(?:.*/)?'
+      const escaped = segment.replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+      // `**` colado a outro texto no segmento (`a**`) mantém o comportamento
+      // anterior: qualquer sequência. `\u0000` é placeholder: nunca ocorre num path.
+      const converted = escaped
+        .replace(/\*\*/g, '\u0000')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\u0000/g, '.*')
+      return last ? converted : `${converted}/`
+    })
+    .join('')
   return new RegExp(`^${body}$`)
 }