@softize/opus 26.2.0 → 27.1.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.1.0 — 2026-10-13
+
+Portais documentais podem oferecer navegação recolhível em telas estreitas com
+`DocBrowser.collapsibleNavigation`. O menu ocupa a área disponível, preserva os ramos
+abertos e mostra os resultados da busca; selecionar um destino interno ou pressionar
+Escape retorna à leitura. A composição desktop e consumidores sem a opção não mudam.
+
+**Ao adotar:** remova as regras CSS móveis do host que limitavam `Split` e `Pane` a
+uma faixa curta. Preserve a instância de `DocBrowser` entre áreas, sem uma `key`
+que remonte o navegador a cada troca; isso mantém a busca, os ramos abertos e o foco.
+Mapas distintos usam `basePath` distintos para preservar a abertura dos ramos de cada
+área. Uma consulta já preenchida na montagem não abre o menu; editar a busca revela
+os resultados.
+
+`DocSection.readingSequence: false` mantém uma seção na navegação e na busca, mas a retira
+dos links de leitura anterior/próxima. Isso permite consultar registros históricos sem
+apresentá-los como continuidade de guias vigentes.
+
+## 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

package/docs/adr/0017-ui-assumes-a-fixed-desktop-layout.md

@@ -2,7 +2,7 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-15.
-- **Emenda:** 2026-10-07; portal documental delimitado pela ADR 0057.
+- **Emendas:** 2026-10-07 e 2026-10-13; portal documental delimitado pela ADR 0057.
 
 ## Contexto
 
@@ -32,8 +32,9 @@ nesse caso, o cancelamento usa `outline`.
 ### Exceção: portal de documentação
 
 O portal documental tem uma jornada de leitura distinta da UI operacional das aplicações. Conforme
-a ADR 0057, `DocHeader`, a leitura editorial de `DocBrowser` e `DocCatalog`/`DocRecordDetail`
-podem adaptar cabeçalho, espaçamento e sumário à largura da tela. A exceção foi aprovada para
+a ADR 0057, `DocHeader`, a leitura editorial e a navegação móvel opcional de `DocBrowser`,
+além de `DocCatalog`/`DocRecordDetail`, podem adaptar cabeçalho, navegação, espaçamento e
+sumário à largura da tela. A exceção foi aprovada para
 preservar a composição validada nos portais do Opus e da Grand Brasil.
 
 A exceção não torna responsivos `Split`, `Sidebar`, formulários, tabelas ou outros componentes da
@@ -41,9 +42,13 @@ UI das aplicações. O host documental continua responsável pela composição d
 estreita. Exemplos vivos usam o mesmo contrato desktop dos componentes demonstrados; o portal não
 promete que todos os exemplos sejam adequados a telas menores que `64rem`.
 
-O gate permite variantes de viewport somente nos três arquivos documentais identificados na ADR
-0057. Arquivos novos, mesmo dentro de `docs/`, continuam sujeitos à regra até uma decisão explícita.
-Container queries não entram na exceção.
+O gate permite variantes de viewport somente nas funções editoriais identificadas pela ADR 0057.
+A consulta direta de largura via `matchMedia` tem uma exceção separada: somente os helpers
+`subscribeCompactNavigation` e `compactNavigationSnapshot` de `DocBrowser.tsx` podem consultar
+a constante `compactNavigationQuery`, fixada em `(max-width: 48rem)`. Isso não libera variantes
+na função `DocBrowser`. Chamadas diretas com consultas dinâmicas não identificáveis são recusadas;
+preferências explícitas continuam permitidas. Arquivos novos, mesmo dentro de `docs/`, seguem
+a regra. Container queries não entram na exceção.
 
 ## Consequências
 
@@ -67,7 +72,8 @@ Container queries não entram na exceção.
 ## Verificação
 
 - Um teste de inventário reprova variantes de largura e container queries na UI viva.
-- O mesmo teste delimita a exceção documental por arquivo e comprova que ela não alcança componentes
-  da aplicação, outros arquivos documentais ou container queries.
+- O mesmo teste delimita a exceção documental por função e verifica chamadas diretas de `matchMedia`,
+  inclusive constantes e consultas dinâmicas. Mutações fora dos helpers, do arquivo ou do breakpoint
+  documentados reprovam; a exceção não alcança componentes da aplicação nem container queries.
 - Testes estruturais fixam layouts, larguras de modal e distribuição dos footers.
 - Documentação pública declara a largura mínima, o default por conteúdo e a exceção `equal`.

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

@@ -1,8 +1,37 @@
 # ADR 0057 — Portal documental compartilha navegação, busca e leitura
 
-- **Status:** aceita para implementação local; publicação pendente.
+- **Status:** aceita; composição original em 25.7.0, subgrupos e abertura em nova aba em 26.2.0,
+  navegação recolhível e sequência de leitura em 27.1.0.
 - **Data:** 2026-10-07.
 
+> **Emenda — 2026-10-13, versão 27.1.0:** a composição anterior reúne as entregas
+> das versões 25.7.0 e 26.2.0. Esta extensão separa presença no mapa de participação na leitura:
+> `DocSection.readingSequence: false` retira a seção dos links anterior/próxima, mas
+> preserva busca, contexto e URLs. A omissão mantém a sequência existente. Excluir o
+> arquivo histórico da árvore impediria sua descoberta; duplicar o mapa para calcular
+> continuidade criaria duas ordens concorrentes.
+>
+> `DocBrowser.collapsibleNavigation` é opcional e começa desligado. Quando ligado, em
+> telas de até `48rem`, oferece um botão de navegação e começa recolhido. Ao abrir,
+> a árvore ocupa a área disponível no lugar da leitura, sem a faixa fixa de `14rem`.
+> A seleção de um destino interno e a tecla Escape recolhem o menu; editar a busca revela
+> seus resultados. A consulta preenchida na montagem não abre o menu sobre a leitura.
+> A árvore permanece montada para preservar ramos abertos. Acima
+> desse limite, a lateral continua visível. `Split` e `Sidebar` não mudam de contrato.
+> O host preserva a instância também entre Documentação e UI: remontá-la descartaria
+> o botão que recebeu o foco e o estado dos ramos. Mapas distintos usam `basePath`
+> distintos; as chaves dos ramos incluem essa identidade antes da posição no mapa.
+> Assim, abrir um capítulo em Documentação não abre outro na mesma posição em UI,
+> e voltar restaura a abertura manual. A ordem interna de cada mapa permanece estável.
+> Escape retorna
+> o foco ao botão Navegação, inclusive quando acionado pela busca externa; a consulta
+> permanece para permitir retomar os mesmos resultados.
+> Esta composição substitui os ajustes CSS duplicados nos dois portais, estendendo
+> a exceção documental à montagem do navegador, não aos exemplos ou demais telas.
+> A alternativa de manter uma lateral curta preservaria a rolagem que esconde destinos
+> globais. Testes de teclado, redimensionamento, busca, rotas e sequência de leitura,
+> além de inspeção visual nos dois consumidores, verificam a extensão antes de publicar.
+
 ## Contexto
 
 Portais de documentação precisam apresentar guias, decisões e entregas sem trocar o mapa de
@@ -114,10 +143,14 @@ A composição documental é uma exceção explícita à ADR 0017: `DocHeader.ts
 (na leitura editorial) e `DocCatalog.tsx` (incluindo `DocRecordDetail`) podem usar variantes de
 viewport para organizar cabeçalho, sumário e espaçamento. A exceção fica restrita a esses arquivos;
 não libera toda a pasta `docs/` nem container queries. O gate verifica as funções de composição
-permitidas, sem liberar outras funções ou a montagem de `Split` no mesmo arquivo.
+permitidas. A emenda de 13/10 admite a consulta de largura via `matchMedia` apenas nos helpers
+`subscribeCompactNavigation` e `compactNavigationSnapshot`, em `DocBrowser.tsx`, usando a
+constante `compactNavigationQuery` fixada em `(max-width: 48rem)`. Variantes de viewport
+continuam proibidas na função `DocBrowser`; consultas diretas dinâmicas não identificáveis
+também reprovam. Preferências explícitas de acessibilidade e tema permanecem permitidas.
 
 Essa adaptação foi aprovada para o portal de leitura, não para a UI das aplicações. O host organiza
-sua moldura em telas estreitas; `Split`, `Sidebar` e os exemplos vivos não ganham um contrato
+sua moldura; o navegador pode oferecer sua navegação móvel opcional. `Split`, `Sidebar` e os exemplos vivos não ganham um contrato
 responsivo por estarem dentro da documentação. Manter o portal inteiramente desktop descartaria
 a composição já validada; ampliar a exceção para toda a UI alteraria uma decisão fora deste escopo.
 
@@ -159,8 +192,9 @@ e separa a consulta documental da consulta local.
 - Os dois portais compartilham cabeçalho e catálogos sem compartilhar sua taxonomia específica.
 - Guias, índices e fontes acessíveis por URL direta precisam ser filtrados antes de chegar ao
   navegador quando houver restrição de acesso. Esta composição não é uma fronteira de segurança.
-- A consolidação é um candidato local. A publicação e a adoção pela Grand Brasil são etapas
-  distintas, posteriores à revisão independente.
+- A composição original integra a versão 25.7.0; subgrupos e abertura em nova aba, a 26.2.0;
+  a navegação recolhível e a sequência de leitura, a 27.1.0. A adoção por cada portal é uma
+  etapa própria.
 
 ## Verificação
 

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.2.0",
+  "version": "27.1.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

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

@@ -15,15 +15,25 @@
 import {
   Fragment,
   useEffect,
+  useId,
   useMemo,
   useRef,
   useState,
+  useSyncExternalStore,
   type ReactNode,
 } from "react";
-import { ArrowLeft, ArrowRight, ExternalLink, Search } from "lucide-react";
+import {
+  ArrowLeft,
+  ArrowRight,
+  ExternalLink,
+  Menu,
+  Search,
+  X,
+} 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";
+import { Button } from "../components/primitives/button.tsx";
 import {
   Breadcrumb,
   BreadcrumbList,
@@ -109,6 +119,8 @@ export interface DocBrowserProps {
   }>;
   /** Seções e grupos começam recolhidos; a busca revela resultados sem mudar a escolha manual. */
   sidebarInitiallyCollapsed?: boolean;
+  /** Em telas de até 48rem, oferece navegação recolhível no lugar da lateral fixa. Default false. */
+  collapsibleNavigation?: boolean;
 }
 
 function documentNavigation(
@@ -142,11 +154,15 @@ function EditorialDocument({
   const [headings, setHeadings] = useState<
     Array<{ id: string; title: string }>
   >([]);
-  const entries = documentEntries(sections);
+  const entries = documentEntries(
+    sections.filter((section) => section.readingSequence !== false),
+  );
   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;
-  const context = entries[index]?.context;
+  const context = documentEntries(sections).find(
+    ({ entry }) => entry.slug === page.slug,
+  )?.context;
 
   useEffect(() => {
     const article = articleRef.current;
@@ -303,8 +319,10 @@ type SidebarSection = Omit<DocSection, "groups"> & {
 function filterSections(
   sections: DocSection[],
   query: string,
+  basePath: string,
 ): SidebarSection[] {
   const terms = searchable(query).split(/\s+/).filter(Boolean);
+  const namespace = JSON.stringify(basePath);
   // Identidade vem do manifesto completo, antes de remover ramos pela busca.
   const indexGroups = (groups: DocGroup[], parent: string): SidebarGroup[] =>
     groups.map((group, index) => {
@@ -317,8 +335,8 @@ function filterSections(
     });
   const indexedSections = sections.map((section, sectionIndex) => ({
     ...section,
-    navigationKey: `section:${sectionIndex}`,
-    groups: indexGroups(section.groups, `group:${sectionIndex}`),
+    navigationKey: `${namespace}:section:${sectionIndex}`,
+    groups: indexGroups(section.groups, `${namespace}:group:${sectionIndex}`),
   }));
   const matchingGroups = (groups: SidebarGroup[]): SidebarGroup[] =>
     groups.flatMap((group) => {
@@ -343,6 +361,7 @@ function DocSidebarTree({
   sections,
   activeSlug,
   onSelect,
+  onNavigate = navigate,
   forceExpanded = false,
   initiallyCollapsed = false,
   links = [],
@@ -350,6 +369,7 @@ function DocSidebarTree({
   sections: SidebarSection[];
   activeSlug?: string;
   onSelect: (slug: string) => void;
+  onNavigate?: (href: string) => void;
   forceExpanded?: boolean;
   initiallyCollapsed?: boolean;
   links?: DocBrowserProps["sidebarLinks"];
@@ -496,7 +516,7 @@ function DocSidebarTree({
               onClick={
                 link.newTab || /^https?:\/\//i.test(link.href)
                   ? undefined
-                  : () => navigate(link.href)
+                  : () => onNavigate(link.href)
               }
               label={link.label}
               icon={
@@ -510,6 +530,17 @@ function DocSidebarTree({
   );
 }
 
+const compactNavigationQuery = "(max-width: 48rem)";
+const subscribeCompactNavigation = (notify: () => void): (() => void) => {
+  const media = window.matchMedia(compactNavigationQuery);
+  media.addEventListener("change", notify);
+  return () => media.removeEventListener("change", notify);
+};
+const compactNavigationSnapshot = (): boolean =>
+  window.matchMedia(compactNavigationQuery).matches;
+const serverNavigationSnapshot = (): boolean => false;
+const skipNavigationSubscription = (): (() => void) => () => {};
+
 export function DocBrowser({
   basePath = "/docs",
   path: controlledPath,
@@ -525,8 +556,19 @@ export function DocBrowser({
   content,
   sidebarLinks = [],
   sidebarInitiallyCollapsed = false,
+  collapsibleNavigation = false,
 }: DocBrowserProps): React.ReactElement {
   const [sidebarQuery, setSidebarQuery] = useState("");
+  const watchViewport = sidebar && collapsibleNavigation;
+  const narrowViewport = useSyncExternalStore(
+    watchViewport ? subscribeCompactNavigation : skipNavigationSubscription,
+    watchViewport ? compactNavigationSnapshot : serverNavigationSnapshot,
+    serverNavigationSnapshot,
+  );
+  const compactNavigation = collapsibleNavigation && narrowViewport;
+  const [navigationOpen, setNavigationOpen] = useState(false);
+  const navigationId = useId();
+  const navigationButtonRef = useRef<HTMLButtonElement>(null);
   // Standalone: o path vem do router da casa (`usePathname` — pathname É o estado).
   // Controlado: o host manda, e este valor é ignorado. O hook roda sempre (regra dos
   // hooks); o que muda é quem vence no `??`.
@@ -542,9 +584,10 @@ export function DocBrowser({
   const searchOptions = typeof search === "object" ? search : {};
   const query =
     searchOptions.placement === "external" ? searchOptions.value : sidebarQuery;
+  const previousQuery = useRef(query);
   const visibleSections = useMemo(
-    () => filterSections(sections, query),
-    [query, sections],
+    () => filterSections(sections, query, basePath),
+    [query, sections, basePath],
   );
   const hasCustomContent = content !== undefined;
   const page = hasCustomContent
@@ -555,7 +598,40 @@ export function DocBrowser({
 
   // `navigate` emite `popstate`, então o host é notificado nos dois modos — inclusive o
   // que ainda escuta o evento na unha, que era como este componente avisava antes.
-  const go = (to: string): void => navigate(to);
+  const go = (to: string): void => {
+    if (compactNavigation) {
+      setNavigationOpen(false);
+      navigationButtonRef.current?.focus();
+    }
+    navigate(to);
+  };
+
+  useEffect(() => {
+    setNavigationOpen(false);
+    if (
+      collapsibleNavigation &&
+      document.getElementById(navigationId)?.contains(document.activeElement)
+    )
+      navigationButtonRef.current?.focus();
+  }, [path, collapsibleNavigation, navigationId]);
+
+  useEffect(() => {
+    if (previousQuery.current === query) return;
+    previousQuery.current = query;
+    if (collapsibleNavigation && query.trim()) setNavigationOpen(true);
+  }, [collapsibleNavigation, query]);
+
+  useEffect(() => {
+    if (!sidebar || !compactNavigation || !navigationOpen) return;
+    const closeOnEscape = (event: KeyboardEvent): void => {
+      if (event.key !== "Escape" || event.defaultPrevented) return;
+      event.preventDefault();
+      setNavigationOpen(false);
+      navigationButtonRef.current?.focus();
+    };
+    document.addEventListener("keydown", closeOnEscape);
+    return () => document.removeEventListener("keydown", closeOnEscape);
+  }, [sidebar, compactNavigation, navigationOpen]);
 
   useEffect(() => {
     if (!hasCustomContent && requestedSlug !== slug)
@@ -592,9 +668,14 @@ export function DocBrowser({
     <div className="mx-auto max-w-3xl px-8 py-8">{page?.render()}</div>
   );
 
-  return (
+  const browser = (
     <Split className="h-full">
-      <Pane initialSize={sidebarSize}>
+      <Pane
+        id={collapsibleNavigation ? navigationId : undefined}
+        initialSize={compactNavigation ? undefined : sidebarSize}
+        grow={compactNavigation}
+        className={compactNavigation && !navigationOpen ? "hidden" : undefined}
+      >
         <Sidebar className="w-full">
           <div className="flex min-h-0 flex-1 flex-col">
             {search !== false && searchOptions.placement !== "external" && (
@@ -632,6 +713,7 @@ export function DocBrowser({
                 forceExpanded={query.trim() !== ""}
                 initiallyCollapsed={sidebarInitiallyCollapsed}
                 links={sidebarLinks}
+                onNavigate={go}
                 onSelect={(nextSlug) => go(`${basePath}/${nextSlug}`)}
               />
             </div>
@@ -641,10 +723,38 @@ export function DocBrowser({
       <Pane
         key={hasCustomContent ? path : page?.slug}
         grow
-        className="overflow-y-auto"
+        className={
+          compactNavigation && navigationOpen ? "hidden" : "overflow-y-auto"
+        }
       >
         {readingContent}
       </Pane>
     </Split>
   );
+
+  if (!collapsibleNavigation) return browser;
+  return (
+    <div data-slot="doc-browser" className="flex h-full min-h-0 flex-col">
+      {compactNavigation && (
+        <div className="shrink-0 border-b border-border p-2">
+          <Button
+            ref={navigationButtonRef}
+            context="neutral"
+            variant="ghost"
+            aria-controls={navigationId}
+            aria-expanded={navigationOpen}
+            onClick={() => setNavigationOpen((open) => !open)}
+          >
+            {navigationOpen ? (
+              <X aria-hidden="true" />
+            ) : (
+              <Menu aria-hidden="true" />
+            )}
+            Navegação
+          </Button>
+        </div>
+      )}
+      {browser}
+    </div>
+  );
 }

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

@@ -88,7 +88,45 @@ que a pessoa possa consultar, inclusive aquelas disponíveis por URL direta.
 A adaptação do cabeçalho, da leitura editorial e dos catálogos à largura da tela é uma exceção
 restrita ao portal documental. A UI das aplicações e os componentes dos exemplos vivos preservam
 o contrato desktop a partir de `64rem`. O aplicativo organiza a moldura do portal em telas estreitas;
-`DocBrowser` não muda sozinho a orientação de `Split` nem transforma os exemplos em layouts móveis.
+`DocBrowser` não transforma os exemplos em layouts móveis.
+
+### Navegação em telas estreitas
+
+Em portais autônomos, use `collapsibleNavigation` para oferecer um menu recolhível em telas
+de até `48rem`. O botão Navegação abre a árvore na área disponível, no lugar da leitura.
+Selecionar um destino interno ou pressionar Escape recolhe o menu. A busca global abre
+os resultados quando a consulta muda; uma consulta já preenchida na montagem não abre
+o menu sobre a leitura. Ramos abertos manualmente são preservados. Acima desse limite, a lateral
+permanece visível. Sem essa opção, a composição existente não muda.
+
+```tsx
+<DocBrowser sections={sections} editorial collapsibleNavigation />
+```
+
+Ao adotar a opção, retire do host as regras móveis que limitam a altura ou a dimensão
+inicial de `Split` e `Pane`, como a antiga faixa de `14rem`. O navegador passa a organizar
+essa área; a moldura externa continua sendo do aplicativo. Preserve a mesma instância
+de `DocBrowser` ao trocar de área: uma `key` baseada na área descarta o botão que
+recebeu o foco e os ramos abertos. Áreas com mapas diferentes usam `basePath` distintos:
+cada uma preserva seus próprios ramos, sem expandir capítulos da outra. Catálogos que
+compartilham o mapa mantêm o mesmo `basePath`. Dentro de cada mapa, a ordem dos ramos
+deve permanecer estável durante a navegação. Escape retorna ao botão Navegação e mantém a consulta.
+
+### Histórico fora da sequência de leitura
+
+Um arquivo histórico pode continuar disponível no menu e na busca sem aparecer como próxima
+leitura de um guia vigente. Declare `readingSequence: false` na sua `DocSection`:
+
+```tsx
+const archive: DocSection = {
+  label: 'Registros históricos',
+  readingSequence: false,
+  groups: [{ pages: historicalPages }],
+}
+```
+
+A opção afeta somente os links anterior/próxima. URLs diretas e contexto continuam disponíveis;
+ela não é uma restrição de acesso. Seções sem essa declaração participam da sequência.
 
 ## Consulte decisões e entregas
 
@@ -205,6 +243,7 @@ não define as rotas nem a autorização do aplicativo.
 | `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; 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. |
+| `collapsibleNavigation` | `boolean` | `false` | Em telas de até `48rem`, oferece um botão para alternar entre navegação e leitura, preservando a árvore. |
 
 A entrada histórica `@softize/opus/ui/docs` inclui o catálogo e oferece suas páginas quando
 `sections` é omitida. Para conteúdo próprio, prefira a entrada leve do exemplo.

package/src/ui/docs/types.ts

@@ -25,4 +25,6 @@ export interface DocGroup {
 export interface DocSection {
   label: string
   groups: DocGroup[]
+  /** False exclui a seção da leitura anterior/próxima, sem retirá-la da navegação ou busca. */
+  readingSequence?: boolean
 }

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}$`)
 }