@softize/opus 25.4.0 → 25.5.0

package/CHANGELOG.md

@@ -7,6 +7,33 @@ 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.
 
+## 25.5.0 — 2026-10-07
+
+Aplicações que publicam documentação própria podem usar a nova entrada
+`@softize/opus/ui/docs/browser`. Ela oferece `DocBrowser`, transformação de pastas, Markdown e os
+tipos de navegação sem carregar o catálogo do Opus, os exemplos vivos nem o compilador usado por
+esses exemplos. A entrada histórica `@softize/opus/ui/docs` continua incluindo o catálogo completo
+e mantém seu comportamento atual.
+
+O `DocBrowser` aceita busca local por título, badge e conteúdo pesquisável. A busca pode configurar
+nome acessível, placeholder e mensagem sem resultados; o padrão orienta a tentar outro termo.
+Páginas derivadas de pastas passam a informar `sourcePath` e `searchText`; `renderPage` permite
+resolver links ou compor a apresentação sem duplicar descoberta, hierarquia e ordenação. O
+Markdown compartilhado também pode reescrever links e gerar IDs estáveis para títulos. Não há
+migração para consumidores existentes.
+
+## 25.4.1 — 2026-10-05
+
+Corrige a busca remota de filtros `lookup` quando a `ActionList` também recebe opções iniciais em
+`filterOptions`, como nas dimensões disponíveis para agrupamento. Enquanto há um termo de busca, as
+opções iniciais agora são filtradas localmente e combinadas com o resultado do servidor; antes,
+elas permaneciam todas visíveis e podiam esconder o efeito da busca. Não há migração para o
+consumidor. Valores já selecionados preservam o rótulo durante e depois da busca, inclusive quando
+a opção veio apenas do servidor. Fechar o seletor limpa o termo também no lookup remoto. No
+`Select` com `onSearch`, esse reset é comunicado imediatamente com `""` apenas quando uma busca não
+vazia chegou a ser enviada; abrir e fechar sem digitar não repete a consulta inicial. Respostas
+remotas fora de ordem não substituem mais o resultado da consulta mais recente.
+
 ## 25.4.0 — 2026-10-05
 
 `ListAction.grouping.fields` passa a aceitar filtros `select` ou `lookup` cujas opções completas

package/docs/adr/0056-doc-browser-separa-runtime-leve-do-catalogo.md

@@ -0,0 +1,77 @@
+# ADR 0056 — DocBrowser separa o runtime leve do catálogo do Opus
+
+- **Status:** aceita.
+- **Data:** 2026-10-07.
+
+## Contexto
+
+O ponto de entrada `@softize/opus/ui/docs` combina duas responsabilidades: o navegador de
+documentação e o catálogo completo do próprio Opus. Esse catálogo importa páginas TSX, exemplos
+vivos e o compilador usado para executá-los. A composição é adequada ao site do SDK, mas faz uma
+aplicação que publica seus próprios Markdown carregar código que não consulta nem apresenta.
+
+O portal da Grand Brasil precisa reutilizar navegação, busca, transformação de pastas e Markdown,
+mantendo no produto a classificação dos documentos, os espaços de navegação e a política de
+acesso. Copiar esses recursos para o consumidor criaria duas implementações; obrigá-lo a consumir
+o catálogo do SDK ampliaria o bundle e confundiria a fronteira entre ferramenta e conteúdo.
+
+## Decisão
+
+### 1. O navegador base recebe o catálogo do consumidor
+
+O `DocBrowser` base passa a exigir `sections`. Ele pode oferecer busca local sobre título, badge e
+texto pesquisável, mas não conhece páginas específicas do Opus.
+
+Os pontos de entrada históricos mantêm o comportamento atual por meio de adaptadores:
+`@softize/opus/ui/docs` injeta o catálogo completo quando o consumidor não informa seções, e a
+transformação de pastas usada pelo plugin e pelo standalone preserva exemplos vivos e blocos de
+código. Assim, a mudança permanece compatível para os consumidores existentes.
+
+### 2. Um subpath explícito publica somente a superfície leve
+
+`@softize/opus/ui/docs/browser` exporta o navegador base, os tipos de seção, a transformação de
+pastas e o renderizador de Markdown. Seu grafo não pode alcançar o registro de páginas do Opus,
+o renderizador de exemplos vivos nem o compilador desses exemplos.
+
+A transformação de pastas fornece `sourcePath` e `searchText` e aceita `renderPage`. Esses pontos
+permitem ao consumidor resolver links e compor a página sem reimplementar descoberta, ordenação ou
+hierarquia.
+
+### 3. O Markdown básico admite comportamento documental opcional
+
+O renderizador compartilhado pode reescrever links e criar IDs estáveis para títulos. Essas
+opções são explícitas; o caminho usado em conversas continua sem IDs e sem tratamento editorial
+quando elas não são pedidas. Frontmatter é removido somente nas superfícies documentais.
+
+### 4. A superfície permanece no pacote Opus
+
+O runtime leve continua em `@softize/opus` enquanto compartilha dependências, manutenção e ciclo
+de release com os componentes de documentação existentes. Um pacote separado só será considerado
+quando houver adoção independente, ciclo de release próprio ou dependências que não devam fazer
+parte do SDK. O crescimento da quantidade de arquivos, isoladamente, não muda essa fronteira.
+
+## Alternativas consideradas
+
+### Consumir o catálogo completo em qualquer aplicação
+
+Evitaria um novo subpath, mas carregaria páginas e compilação de exemplos que não pertencem ao
+produto consumidor.
+
+### Copiar o navegador para cada produto
+
+Manteria bundles isolados, mas duplicaria busca, navegação, ordenação e tratamento de Markdown.
+
+### Criar imediatamente outro pacote
+
+Produziria isolamento mais forte, porém acrescentaria release e adoção independentes antes de
+existir evidência operacional para sustentar essa separação.
+
+## Consequências
+
+- Aplicações podem publicar documentação própria sem incluir o catálogo do Opus.
+- O site do Opus preserva a API histórica e seus exemplos vivos.
+- Classificação, autorização e conteúdo permanecem responsabilidade do consumidor.
+- A busca é local e recebe o conteúdo no navegador; ela não substitui filtragem no servidor quando
+  houver documentos com audiências diferentes.
+- Um teste de arquitetura percorre o grafo do novo subpath e reprova se ele alcançar catálogo,
+  exemplos vivos ou o compilador correspondente.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "25.4.0",
+  "version": "25.5.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -217,6 +217,10 @@
       "types": "./src/ui/docs/index.ts",
       "default": "./src/ui/docs/index.ts"
     },
+    "./ui/docs/browser": {
+      "types": "./src/ui/docs/browser.tsx",
+      "default": "./src/ui/docs/browser.tsx"
+    },
     "./ui/docs/standalone": {
       "types": "./src/ui/docs/standalone.tsx",
       "default": "./src/ui/docs/standalone.tsx"

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

@@ -516,14 +516,16 @@ function useLookupOptions(
 ): {
   options: SelectOption[];
   loading: boolean;
+  query: string;
   onSearch?: (q: string) => void;
 } {
+  const [query, setQuery] = useState("");
   const lookup = spec.options?.kind === "lookup" ? spec.options : undefined;
   const search = useLookupAction<Record<string, unknown>, SelectOption>({
     name: lookup?.source ?? "noop",
     kind: "list",
   } as unknown as ActionDef);
-  if (lookup === undefined) return { options: [], loading: false };
+  if (lookup === undefined) return { options: [], loading: false, query: "" };
   const depInput: Record<string, unknown> = {};
   for (const d of lookup.depends ?? []) {
     if (!isEmptyValue(allValues[d])) depInput[d] = allValues[d];
@@ -534,7 +536,9 @@ function useLookupOptions(
       label: i.label,
     })),
     loading: search.isLoading,
+    query,
     onSearch: (q: string) => {
+      setQuery(q);
       void search.run({ ...(q !== "" ? { q } : {}), ...depInput });
     },
   };
@@ -577,21 +581,66 @@ function FilterField({
   );
   const lookup = useLookupOptions(spec, allValues);
   const dicts = useDicts();
+  const resolvedOptionByValue = useRef(new Map<string, SelectOption>());
   // Precedência: runtime/estáticas (prop `options`) > dictionary do provider;
   // sem nenhuma, as do lookup (server-side).
   const base = options.length > 0 ? options : dictOptionsFor(spec, dicts);
+  const baseByValue = new Map(base.map((option) => [option.value, option]));
+  const canonicalLookupOptions = lookup.options.map(
+    (option) => baseByValue.get(option.value) ?? option,
+  );
+  for (const option of canonicalLookupOptions) {
+    if (!resolvedOptionByValue.current.has(option.value)) {
+      resolvedOptionByValue.current.set(option.value, option);
+    }
+  }
+  for (const option of base) {
+    resolvedOptionByValue.current.set(option.value, option);
+  }
+  const selectedValues = new Set(
+    Array.isArray(value)
+      ? value.filter((item): item is string => typeof item === "string")
+      : typeof value === "string"
+        ? value === ""
+          ? []
+          : [value]
+        : defaultValue === ""
+          ? []
+          : [defaultValue],
+  );
+  const runtimeOptions =
+    lookup.onSearch !== undefined && lookup.query !== ""
+      ? 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 merged = new Map<string, SelectOption>();
+    for (const group of groups) {
+      for (const option of group) {
+        if (!merged.has(option.value)) merged.set(option.value, option);
+      }
+    }
+    return [...merged.values()];
+  };
   const effOptions =
     lookup.onSearch !== undefined && base.length > 0
-      ? [
-          ...base,
-          ...lookup.options.filter(
-            (candidate) =>
-              !base.some((option) => option.value === candidate.value),
-          ),
-        ]
+      ? mergeUniqueOptions(
+          runtimeOptions,
+          canonicalLookupOptions,
+          selectedResolvedOptions,
+        )
       : base.length > 0
         ? base
-        : lookup.options;
+        : mergeUniqueOptions(canonicalLookupOptions, selectedResolvedOptions);
   const singleValue = (value as string | undefined) ?? defaultValue;
   const changedFromDefault = singleValue !== defaultValue;
   const acceptsEmptyValue = spec.allowEmpty !== false;

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

@@ -37,12 +37,88 @@ markdownIt.renderer.rules.image = (tokens, idx, options, env, self) => {
 export interface MarkdownProps {
   content: string
   className?: string
+  /** Reescreve links antes da renderização, por exemplo para resolver caminhos relativos. */
+  resolveHref?: (href: string) => string
+  /** Cria IDs estáveis nos títulos. Útil em documentos navegáveis; omitido no chat. */
+  headingIds?: boolean
+}
+
+function resolveTokenLinks(tokens: ReturnType<typeof markdownIt.parse>, resolveHref: (href: string) => string): void {
+  for (const token of tokens) {
+    if (token.type === 'link_open') {
+      const href = token.attrGet('href')
+      if (href !== null) {
+        const resolved = resolveHref(href)
+        const normalized = markdownIt.normalizeLink(resolved)
+        const withoutControls = resolved.replace(/[\u0000-\u001f\u007f]/g, '')
+        const safe =
+          markdownIt.validateLink(normalized) && markdownIt.validateLink(withoutControls)
+        token.attrSet('href', safe ? normalized : '')
+      }
+    }
+    if (token.children !== null) resolveTokenLinks(token.children, resolveHref)
+  }
+}
+
+function headingId(value: string): string {
+  return value
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLocaleLowerCase('pt-BR')
+    .replace(/[^a-z0-9\s-]/g, '')
+    .trim()
+    .replace(/\s+/g, '-')
+}
+
+function visibleInlineText(tokens: ReturnType<typeof markdownIt.parse>): string {
+  return tokens
+    .map((token) => {
+      if (token.type === 'text' || token.type === 'code_inline') return token.content
+      if (token.type === 'softbreak' || token.type === 'hardbreak') return ' '
+      return token.children === null ? '' : visibleInlineText(token.children)
+    })
+    .join('')
+}
+
+function identifyHeadings(tokens: ReturnType<typeof markdownIt.parse>): void {
+  const used = new Set<string>()
+  for (let index = 0; index < tokens.length; index++) {
+    const opening = tokens[index]
+    const content = tokens[index + 1]
+    if (opening?.type !== 'heading_open' || content?.type !== 'inline') continue
+    const text = visibleInlineText(content.children ?? [])
+    const base = headingId(text)
+    if (base === '') continue
+    let candidate = base
+    let suffix = 1
+    while (used.has(candidate)) candidate = `${base}-${suffix++}`
+    used.add(candidate)
+    opening.attrSet('id', candidate)
+  }
+}
+
+/** Tokeniza Markdown de documentação com frontmatter removido, âncoras e links resolvidos. */
+export function documentationMarkdownTokens(
+  content: string,
+  resolveHref?: (href: string) => string,
+): ReturnType<typeof markdownIt.parse> {
+  const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '')
+  const tokens = markdownIt.parse(body, {})
+  identifyHeadings(tokens)
+  if (resolveHref !== undefined) resolveTokenLinks(tokens, resolveHref)
+  return tokens
 }
 
 export const Markdown = React.memo(function Markdown({
   content,
   className,
+  resolveHref,
+  headingIds = false,
 }: MarkdownProps): React.ReactElement {
+  const html =
+    resolveHref === undefined && !headingIds
+      ? markdownIt.render(content)
+      : markdownIt.renderer.render(documentationMarkdownTokens(content, resolveHref), markdownIt.options, {})
   return (
     <div
       data-slot="markdown"
@@ -50,7 +126,7 @@ export const Markdown = React.memo(function Markdown({
       // margem é do `<p>`, dentro deste wrapper: quem tentava zerar de fora (a bolha do
       // chat fazia) acertava o wrapper e errava o parágrafo.
       className={`prose prose-sm max-w-none [&>:first-child]:mt-0 [&>:last-child]:mb-0${className !== undefined ? ` ${className}` : ''}`}
-      dangerouslySetInnerHTML={{ __html: markdownIt.render(content) }}
+      dangerouslySetInnerHTML={{ __html: html }}
     />
   )
 })

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

@@ -95,7 +95,7 @@ interface SelectCustomBase extends SelectBaseProps {
   /** Liga a busca no próprio campo (lista longa/que cresce). */
   searchable?: boolean;
   /** Busca SERVER-SIDE (debounced): quando definida, o filtro local desliga e o pai
-   *  atualiza `options`. Implica `searchable`. */
+   *  atualiza `options`. Implica `searchable`; ao fechar, limpa uma busca enviada. */
   onSearch?: (query: string) => void;
   /** "Buscando…" enquanto o fetch corre (use com `onSearch`). */
   loading?: boolean;
@@ -279,6 +279,10 @@ function CustomSelect(
   /** Fechando por Esc: o foco volta pro gatilho, e focar abre. Marca pra ignorar UM foco. */
   const closingRef = React.useRef(false);
   const searchRef = React.useRef<HTMLInputElement>(null);
+  const wasOpenRef = React.useRef(false);
+  const lastSearchedQueryRef = React.useRef("");
+  const onSearchRef = React.useRef(onSearch);
+  onSearchRef.current = onSearch;
 
   const selectedOption = options.find((o) => o.value === singleValue);
 
@@ -303,7 +307,14 @@ function CustomSelect(
    * reabrir filtrada por algo que a pessoa procurou minutos antes e já esqueceu.
    */
   React.useEffect(() => {
-    if (!open) setQuery("");
+    if (!open && wasOpenRef.current) {
+      setQuery("");
+      if (lastSearchedQueryRef.current !== "") {
+        lastSearchedQueryRef.current = "";
+        onSearchRef.current?.("");
+      }
+    }
+    wasOpenRef.current = open;
   }, [open]);
 
   // O cmdk carimba o id DELE no input (a11y interna) e descarta o nosso — reaplicamos por
@@ -312,11 +323,13 @@ function CustomSelect(
     if (id !== undefined && inputRef.current !== null) inputRef.current.id = id;
   }, [id]);
 
-  const onSearchRef = React.useRef(onSearch);
-  onSearchRef.current = onSearch;
   React.useEffect(() => {
     if (onSearchRef.current === undefined || !open) return;
-    const t = setTimeout(() => onSearchRef.current?.(query.trim()), 200);
+    const t = setTimeout(() => {
+      const normalizedQuery = query.trim();
+      lastSearchedQueryRef.current = normalizedQuery;
+      onSearchRef.current?.(normalizedQuery);
+    }, 200);
     return () => clearTimeout(t);
   }, [query, open]);
 

package/src/ui/docs/CatalogDocBrowser.tsx

@@ -0,0 +1,15 @@
+import { DocBrowser as BaseDocBrowser, type DocBrowserProps as BaseDocBrowserProps } from './DocBrowser.tsx'
+import { DOC_SECTIONS } from './registry.tsx'
+
+export interface DocBrowserProps extends Omit<BaseDocBrowserProps, 'sections'> {
+  /** Seções a exibir. O catálogo completo do Opus é usado quando elas não são informadas. */
+  sections?: BaseDocBrowserProps['sections']
+}
+
+/**
+ * Entrada histórica do catálogo do Opus. Consumidores que fornecem as próprias páginas devem usar
+ * `@softize/opus/ui/docs/browser`, que não inclui o catálogo nem os exemplos vivos no bundle.
+ */
+export function DocBrowser({ sections = DOC_SECTIONS, ...props }: DocBrowserProps): React.ReactElement {
+  return <BaseDocBrowser {...props} sections={sections} />
+}

package/src/ui/docs/DocBrowser.tsx

@@ -12,9 +12,11 @@
  * 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, useState } from "react";
-import { DOC_SECTIONS, type DocSection, type DocEntry } from "./registry";
+import { useEffect, useMemo, useState } from "react";
+import { Search } from "lucide-react";
+import type { DocEntry, DocSection } from "./types.ts";
 import { Pane, Split } from "../components/patterns/split.tsx";
+import { Input } from "../components/primitives/input.tsx";
 import {
   Sidebar,
   SidebarGroupLabel,
@@ -38,29 +40,58 @@ 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). Default = catálogo inteiro. */
-  sections?: DocSection[];
+  /** Seções a exibir (seção → grupo → página). */
+  sections: DocSection[];
   /** Slugs antigos que devem abrir e substituir a URL pela página canônica. */
   redirects?: Readonly<Record<string, string>>;
   /** Monta o `document.title` a partir do título da página atual (ex.: `(t) => `${t} · Opus``).
    *  Ausente = não mexe no title. */
   documentTitle?: (pageTitle: string) => string;
+  /** Busca local por título, badge e `searchText` das páginas. Omitida = sem campo de busca. */
+  search?: boolean | { label?: string; placeholder?: string; emptyMessage?: string };
+}
+
+function searchable(value: string): string {
+  return value
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLocaleLowerCase("pt-BR");
+}
+
+function filterSections(sections: DocSection[], query: string): DocSection[] {
+  const terms = searchable(query).split(/\s+/).filter(Boolean);
+  if (terms.length === 0) return sections;
+  return sections.flatMap((section) => {
+    const groups = section.groups.flatMap((group) => {
+      const pages = group.pages.filter((page) => {
+        const text = searchable(
+          `${page.title}\n${page.badge ?? ""}\n${page.searchText ?? ""}`,
+        );
+        return terms.every((term) => text.includes(term));
+      });
+      return pages.length === 0 ? [] : [{ ...group, pages }];
+    });
+    return groups.length === 0 ? [] : [{ ...section, groups }];
+  });
 }
 
 function DocSidebarTree({
   sections,
   activeSlug,
   onSelect,
+  forceExpanded = false,
 }: {
   sections: DocSection[];
   activeSlug?: string;
   onSelect: (slug: string) => void;
+  forceExpanded?: boolean;
 }): React.ReactElement {
   const [closedGroups, setClosedGroups] = useState<Set<string>>(
     () => new Set(),
   );
 
   useEffect(() => {
+    if (forceExpanded) return;
     const activeGroup = sections
       .flatMap((section, sectionIndex) =>
         section.groups.map((group, groupIndex) => ({
@@ -79,7 +110,7 @@ function DocSidebarTree({
       next.delete(activeGroup.key);
       return next;
     });
-  }, [activeSlug, sections]);
+  }, [activeSlug, forceExpanded, sections]);
 
   const toggleGroup = (key: string): void => {
     setClosedGroups((current) => {
@@ -120,15 +151,18 @@ function DocSidebarTree({
               return group.pages.map((page) => renderPage(page));
             }
 
-            const expanded = !closedGroups.has(key);
+            const expanded = forceExpanded || !closedGroups.has(key);
             return (
               <div key={key} className="space-y-0.5">
                 <SidebarItem
                   label={group.label!}
                   icon={group.icon}
                   expanded={expanded}
-                  onToggle={() => toggleGroup(key)}
-                  onClick={() => toggleGroup(key)}
+                  onToggle={forceExpanded ? undefined : () => toggleGroup(key)}
+                  // Durante a busca, o grupo é contexto dos resultados e permanece aberto.
+                  onClick={() => {
+                    if (!forceExpanded) toggleGroup(key);
+                  }}
                 />
                 {expanded && (
                   <SidebarTreeGroup>
@@ -147,10 +181,12 @@ function DocSidebarTree({
 export function DocBrowser({
   basePath = "/docs",
   path: controlledPath,
-  sections = DOC_SECTIONS,
+  sections,
   redirects = {},
   documentTitle,
+  search = false,
 }: DocBrowserProps): React.ReactElement {
+  const [query, setQuery] = useState("");
   // 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 `??`.
@@ -164,6 +200,8 @@ export function DocBrowser({
   const requestedSlug = rel.split("/").filter(Boolean).join("/") || defaultSlug;
   const slug = redirects[requestedSlug] ?? requestedSlug;
   const page = findPage(sections, slug) ?? findPage(sections, defaultSlug);
+  const visibleSections = useMemo(() => filterSections(sections, query), [query, sections]);
+  const searchOptions = typeof search === "object" ? search : {};
 
   // `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.
@@ -183,12 +221,42 @@ export function DocBrowser({
     <Split className="h-full">
       <Pane initialSize="14rem">
         <Sidebar className="w-full">
-          <div className="min-h-0 flex-1 overflow-y-auto px-3 py-6">
-            <DocSidebarTree
-              sections={sections}
-              activeSlug={page?.slug}
-              onSelect={(nextSlug) => go(`${basePath}/${nextSlug}`)}
-            />
+          <div className="flex min-h-0 flex-1 flex-col">
+            {search !== false && (
+              <div className="shrink-0 border-b border-border p-3">
+                <Input
+                  type="search"
+                  icon={<Search />}
+                  aria-label={searchOptions.label ?? "Buscar na documentação"}
+                  placeholder={
+                    searchOptions.placeholder ?? "Buscar na documentação…"
+                  }
+                  value={query}
+                  onChange={(event) => setQuery(event.target.value)}
+                />
+              </div>
+            )}
+            <div className="min-h-0 flex-1 overflow-y-auto px-3 py-6">
+              <p
+                className={
+                  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
+                  ? searchOptions.emptyMessage ?? "Nenhum documento encontrado. Tente outro termo."
+                  : ""}
+              </p>
+              {visibleSections.length > 0 && (
+                <DocSidebarTree
+                  sections={visibleSections}
+                  activeSlug={page?.slug}
+                  forceExpanded={query.trim() !== ""}
+                  onSelect={(nextSlug) => go(`${basePath}/${nextSlug}`)}
+                />
+              )}
+            </div>
           </div>
         </Sidebar>
       </Pane>

package/src/ui/docs/browser.tsx

@@ -0,0 +1,11 @@
+/**
+ * Superfície leve para aplicações que publicam a própria documentação. Não inclui o catálogo do
+ * Opus, o compilador de exemplos TSX nem os componentes usados apenas por esses exemplos.
+ */
+export { DocBrowser } from './DocBrowser.tsx'
+export type { DocBrowserProps } from './DocBrowser.tsx'
+export { docSectionsFromFolder } from './folder.tsx'
+export type { FolderOptions, FolderPage } from './folder.tsx'
+export type { DocEntry, DocGroup, DocSection } from './types.ts'
+export { Markdown } from '../components/primitives/markdown.tsx'
+export type { MarkdownProps } from '../components/primitives/markdown.tsx'

package/src/ui/docs/catalog-folder.tsx

@@ -0,0 +1,22 @@
+import { docSectionsFromFolder as createSections } from './folder.tsx'
+import type { DocSection } from './types.ts'
+import { DocMarkdown } from './markdown.tsx'
+
+export type { FolderOptions, FolderPage } from './folder.tsx'
+import type { FolderOptions } from './folder.tsx'
+
+/**
+ * Adaptador histórico de pastas: preserva exemplos vivos e blocos de código do catálogo do Opus.
+ * A entrada leve exporta diretamente o transformador base, cujo padrão é o Markdown básico.
+ */
+export function docSectionsFromFolder(
+  files: Record<string, string>,
+  options: FolderOptions = {},
+): DocSection[] {
+  return createSections(files, {
+    ...options,
+    renderPage:
+      options.renderPage ?? ((page) => <DocMarkdown content={page.body} />),
+  })
+}
+

package/src/ui/docs/content/action-list.md

@@ -409,7 +409,10 @@ render(
 - **`options: { kind: 'dictionary', ref: 'sessionStatus' }`:** resolve opções e rótulos por um
   dicionário registrado no `OpusProvider`. `filterOptions` substitui essa fonte quando informado.
 - **`options: { kind: 'lookup', source: 'x.lookup' }`:** consulta uma action com `{ q }` e os valores
-  das dependências. A resposta segue o formato `{ value, label }`.
+  das dependências. A resposta segue o formato `{ value, label }`. Quando o consumidor também
+  fornece `filterOptions`, essas opções são filtradas localmente pelo termo e combinadas com a
+  resposta remota. Para o mesmo `value`, o rótulo e a apresentação de `filterOptions` prevalecem;
+  valores selecionados preservam o rótulo mesmo depois que a busca é limpa.
 
 ```tsx
 filters: {

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

@@ -140,8 +140,10 @@ render(
 
 ## Busca no servidor
 
-Com `onSearch`, o consumidor consulta as opções ao abrir e ao digitar, com debounce. Atualize
-`options` com a resposta e use `loading` durante a consulta. Esse modo já habilita o campo de busca.
+Com `onSearch`, o consumidor consulta as opções ao abrir e ao digitar, com debounce. Ao fechar o
+seletor depois de uma busca, recebe `""` imediatamente para restaurar as opções iniciais; abrir e
+fechar sem digitar não repete a consulta vazia. Atualize `options` com a resposta e use `loading`
+durante a consulta. Esse modo já habilita o campo de busca.
 
 ```tsx preview col md
 const ASSIGNEES = [
@@ -395,7 +397,7 @@ render(
 | `placeholder` | `string` | `'Selecione…'`; sem padrão com `native` | Texto do campo vazio. Com `native`, só existe quando declarado e vira uma opção desabilitada no início da lista. |
 | `searchPlaceholder` | `string` | `'Buscar…'` | Placeholder da linha de busca dentro da lista. |
 | `emptyText` | `string` | `'Nada encontrado.'` | Mensagem quando a busca não acha nada. |
-| `onSearch` | `(query: string) => void` | | Busca no servidor, chamada ao abrir a lista e depois de uma breve pausa na digitação. Desliga o filtro local; o consumidor atualiza `options` com a resposta. |
+| `onSearch` | `(query: string) => void` | | Busca no servidor, chamada ao abrir a lista e depois de uma breve pausa na digitação. Ao fechar depois de uma busca enviada, recebe `""` imediatamente para restaurar as opções iniciais. Desliga o filtro local; o consumidor atualiza `options` com a resposta. |
 | `loading` | `boolean` | | Mostra “Buscando…” enquanto a consulta de `onSearch` está em andamento. |
 | `clearable` | `boolean` | `false` | Mostra, quando há seleção, uma ação que limpa o valor sem abrir a lista. |
 | `icon` | `React.ReactNode` | | Ícone decorativo no início do controle, em `1rem` e no tom atenuado. |

package/src/ui/docs/folder.tsx

@@ -16,10 +16,11 @@
  *
  * Frontmatter: parser mínimo browser-safe — este transform roda no bundle do app, e o
  * gray-matter usa Buffer/js-yaml (inóspito no browser). Cobre title/section/group/order;
- * YAML rico fica pra depois. Uso: ver `opusDocs({ source })` em ./plugin.ts.
+ * YAML rico fica pra depois. A entrada leve usa este transformador diretamente; as entradas
+ * históricas injetam o renderizador de exemplos vivos em `catalog-folder.tsx`.
  */
-import { DocMarkdown } from './markdown.tsx'
-import type { DocEntry, DocGroup, DocSection } from './registry.tsx'
+import { Markdown } from '../components/primitives/markdown.tsx'
+import type { DocEntry, DocGroup, DocSection } from './types.ts'
 
 interface FrontMatter {
   title?: string
@@ -39,7 +40,12 @@ function parseFrontMatter(raw: string): { data: FrontMatter; body: string } {
   }
   const n = kv.order !== undefined ? Number(kv.order) : NaN
   return {
-    data: { title: kv.title, section: kv.section, group: kv.group, order: Number.isFinite(n) ? n : undefined },
+    data: {
+      title: kv.title,
+      section: kv.section,
+      group: kv.group,
+      order: Number.isFinite(n) ? n : undefined,
+    },
     body: raw.slice(m[0].length),
   }
 }
@@ -71,6 +77,15 @@ export interface FolderOptions {
   root?: string
   /** Rótulo da seção para arquivos na raiz da pasta. Default "Documentação". */
   rootLabel?: string
+  /** Substitui a renderização padrão da página sem reimplementar descoberta, ordem ou navegação. */
+  renderPage?: (page: FolderPage) => React.ReactElement
+}
+
+export interface FolderPage {
+  slug: string
+  title: string
+  body: string
+  sourcePath: string
 }
 
 const LAST = 1e9
@@ -79,6 +94,7 @@ interface Row {
   slug: string
   title: string
   body: string
+  sourcePath: string
   section: string
   group?: string
   secOrder: number
@@ -88,7 +104,8 @@ interface Row {
 
 /**
  * Constrói `DocSection[]` a partir do glob eager do Vite (chaves = caminhos, valores = o
- * conteúdo raw do .md). Cada página renderiza `<Markdown>` do corpo do arquivo.
+ * conteúdo raw do .md). Cada página renderiza `<Markdown>` do corpo do arquivo, salvo quando o
+ * consumidor fornece `renderPage`.
  */
 export function docSectionsFromFolder(files: Record<string, string>, options: FolderOptions = {}): DocSection[] {
   const rootLabel = options.rootLabel ?? 'Documentação'
@@ -98,7 +115,8 @@ export function docSectionsFromFolder(files: Record<string, string>, options: Fo
   const rows: Row[] = []
 
   for (const [path, raw] of Object.entries(files)) {
-    const rel = path.replace(stripRe, '').replace(/\.mdx?$/, '')
+    const sourcePath = path.replace(stripRe, '').replace(/^\/+/, '')
+    const rel = sourcePath.replace(/\.mdx?$/, '')
     const segs = rel.split('/').filter(Boolean)
     if (segs.length === 0) continue
     const { data, body } = parseFrontMatter(raw)
@@ -108,42 +126,95 @@ export function docSectionsFromFolder(files: Record<string, string>, options: Fo
       slug: [...dirs.map((d) => d.name), file.name].join('/'),
       title: data.title ?? firstH1(body) ?? humanize(file.name),
       body,
+      sourcePath,
       section: data.section ?? (dirs[0] ? humanize(dirs[0].name) : rootLabel),
-      group: data.group ?? (dirs.length > 1 ? humanize(dirs.slice(1).map((d) => d.name).join('/')) : undefined),
-      secOrder: dirs.length === 0 ? -1 : dirs[0]!.order ?? LAST,
-      grpOrder: dirs.length > 1 ? dirs[1]!.order ?? LAST : -1,
+      group:
+        data.group ??
+        (dirs.length > 1
+          ? humanize(
+              dirs
+                .slice(1)
+                .map((d) => d.name)
+                .join('/'),
+            )
+          : undefined),
+      secOrder: dirs.length === 0 ? -1 : (dirs[0]!.order ?? LAST),
+      grpOrder: dirs.length > 1 ? (dirs[1]!.order ?? LAST) : -1,
       order: data.order ?? file.order ?? LAST,
     })
   }
 
   // Agrega seção → grupo → páginas, guardando a MENOR ordem vista de cada nível.
-  const sections = new Map<string, { order: number; groups: Map<string, { label?: string; order: number; rows: Row[] }> }>()
+  const sections = new Map<
+    string,
+    {
+      order: number
+      groups: Map<string, { label?: string; order: number; rows: Row[] }>
+    }
+  >()
   for (const r of rows) {
-    const sec = sections.get(r.section) ?? { order: r.secOrder, groups: new Map() }
+    const sec = sections.get(r.section) ?? {
+      order: r.secOrder,
+      groups: new Map(),
+    }
     sec.order = Math.min(sec.order, r.secOrder)
     const gkey = r.group ?? ''
-    const grp = sec.groups.get(gkey) ?? { label: r.group, order: r.grpOrder, rows: [] }
+    const grp = sec.groups.get(gkey) ?? {
+      label: r.group,
+      order: r.grpOrder,
+      rows: [],
+    }
     grp.order = Math.min(grp.order, r.grpOrder)
     grp.rows.push(r)
     sec.groups.set(gkey, grp)
     sections.set(r.section, sec)
   }
 
-  const byOrder = <T,>(o: (t: T) => number, l: (t: T) => string) => (a: T, b: T) => o(a) - o(b) || l(a).localeCompare(l(b))
+  const byOrder =
+    <T,>(o: (t: T) => number, l: (t: T) => string) =>
+    (a: T, b: T) =>
+      o(a) - o(b) || l(a).localeCompare(l(b))
 
   return [...sections.entries()]
-    .sort(byOrder(([, s]) => s.order, ([label]) => label))
+    .sort(
+      byOrder(
+        ([, s]) => s.order,
+        ([label]) => label,
+      ),
+    )
     .map(([label, s]): DocSection => ({
       label,
       groups: [...s.groups.values()]
-        .sort(byOrder((g) => g.order, (g) => g.label ?? ''))
-        .map(
-          (g): DocGroup => ({
-            label: g.label,
-            pages: g.rows
-              .sort(byOrder((r) => r.order, (r) => r.title))
-              .map((r): DocEntry => ({ slug: r.slug, title: r.title, render: () => <DocMarkdown content={r.body} /> })),
-          }),
-        ),
+        .sort(
+          byOrder(
+            (g) => g.order,
+            (g) => g.label ?? '',
+          ),
+        )
+        .map((g): DocGroup => ({
+          label: g.label,
+          pages: g.rows
+            .sort(
+              byOrder(
+                (r) => r.order,
+                (r) => r.title,
+              ),
+            )
+            .map((r): DocEntry => {
+              const page: FolderPage = {
+                slug: r.slug,
+                title: r.title,
+                body: r.body,
+                sourcePath: r.sourcePath,
+              }
+              return {
+                slug: r.slug,
+                title: r.title,
+                searchText: r.body,
+                sourcePath: r.sourcePath,
+                render: () => options.renderPage?.(page) ?? <Markdown content={r.body} headingIds />,
+              }
+            }),
+        })),
     }))
 }

package/src/ui/docs/index.ts

@@ -6,12 +6,12 @@
  *  - Rota dev `/__docs` de um app: o plugin `opusDocs()` (vite) usa `mountDocs` de
  *    `@softize/opus/ui/docs/standalone` — não passa por aqui.
  */
-export { DocBrowser } from './DocBrowser.tsx'
-export type { DocBrowserProps } from './DocBrowser.tsx'
+export { DocBrowser } from './CatalogDocBrowser.tsx'
+export type { DocBrowserProps } from './CatalogDocBrowser.tsx'
 export { DOC_SECTIONS, PROTOCOL_SECTIONS, UI_SECTIONS } from './registry.tsx'
-export type { DocEntry, DocGroup, DocSection } from './registry.tsx'
-export { docSectionsFromFolder } from './folder.tsx'
-export type { FolderOptions } from './folder.tsx'
+export type { DocEntry, DocGroup, DocSection } from './types.ts'
+export { docSectionsFromFolder } from './catalog-folder.tsx'
+export type { FolderOptions, FolderPage } from './catalog-folder.tsx'
 // Primitivos de página reusáveis (o mesmo Example/CodeBlock das páginas TSX do DocBrowser).
 export { Example, CodeBlock, DocPage } from './doc.tsx'
 // Renderer de markdown do DocBrowser: prosa + fence ```tsx preview vira componente vivo.

package/src/ui/docs/markdown.tsx

@@ -13,12 +13,11 @@
  * Só fences de nível 0 viram preview/CodeBlock; fences aninhados caem no HTML do markdown-it.
  */
 import * as React from 'react'
-import { markdownIt as md } from '../components/primitives/markdown.tsx'
+import { documentationMarkdownTokens, markdownIt as md } from '../components/primitives/markdown.tsx'
 import { transform } from 'sucrase'
 import { CodeBlock, Example } from './doc.tsx'
 import * as opusUi from '../react.tsx'
 
-
 // Scope default estável (computado uma vez) — evita re-eval do LiveBlock a cada render. Os blocos
 // `tsx preview` enxergam o opus/ui (componentes) + os hooks do React (bare `useState`… além de
 // `React.useState`). Ícones (lucide) NÃO entram aqui de propósito: quem monta a doc injeta a paleta
@@ -43,14 +42,20 @@ function LiveBlock({
   scope: Record<string, unknown>
   previewClassName?: string
 }): React.ReactElement {
-  const result = React.useMemo<{ Comp?: () => React.ReactNode; error?: string }>(() => {
+  const result = React.useMemo<{
+    Comp?: () => React.ReactNode
+    error?: string
+  }>(() => {
     try {
       // Exemplo com ESTADO: se o snippet chama `render(<…/>)`, ele roda como CORPO de um
       // componente (os hooks rodam no lugar certo). Bare JSX (uma OU várias irmãs) → embrulho
       // num Fragment antes do render() — várias expressões soltas não passam como um argumento só.
       const hasRender = /\brender\s*\(/.test(code)
       const body = `let __el = null; const render = (e) => { __el = e; };\n${hasRender ? code.trim() : `render(<>${code.trim()}</>)`}\nreturn __el;`
-      const js = transform(body, { transforms: ['jsx', 'typescript'], jsxRuntime: 'classic' }).code
+      const js = transform(body, {
+        transforms: ['jsx', 'typescript'],
+        jsxRuntime: 'classic',
+      }).code
       // Só passa pro new Function os identificadores que o snippet realmente cita (o scope tem
       // ~1500 nomes com o lucide) e que são identificador válido (ex.: 'default' fica de fora).
       // React entra SEMPRE — o JSX clássico compila pra React.createElement.
@@ -80,23 +85,32 @@ export interface DocMarkdownProps {
   /** ESTENDE o scope dos blocos ```tsx preview (opus/ui + lucide + hooks). Ex.: um pattern injeta
    *  o palco doc-client. Omitido = só o default. */
   scope?: Record<string, unknown>
+  /** Reescreve links do Markdown antes da renderização. Útil para resolver caminhos relativos
+   *  quando o documento é publicado sob uma rota do aplicativo. */
+  resolveHref?: (href: string) => string
 }
 
-export function DocMarkdown({ content, scope }: DocMarkdownProps): React.ReactElement {
+export function DocMarkdown({ content, scope, resolveHref }: DocMarkdownProps): React.ReactElement {
   // O `scope` ESTENDE o default (não substitui): o pattern injeta o palco doc-client
   // (DocBrowserActionProvider + contratos) sem perder o opus/ui + lucide + hooks. Memoiza pra
   // não re-avaliar os LiveBlocks a cada render (o scope injetado é estável no chamador).
   const liveScope = React.useMemo(() => (scope ? { ...DEFAULT_SCOPE, ...scope } : DEFAULT_SCOPE), [scope])
   // Ignora o frontmatter (---\n…\n---) — a nav já tem o título e o corpo tem o H1. Sem isso,
   // o markdown-it renderiza "title: …" como texto (é robusto pros dois caminhos: registry e folder).
-  const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '')
-  const tokens = md.parse(body, {})
+  const tokens = documentationMarkdownTokens(content, resolveHref)
   const parts: React.ReactNode[] = []
   let buffer: typeof tokens = []
   let key = 0
   const flush = (): void => {
     if (buffer.length === 0) return
-    parts.push(<div key={key++} dangerouslySetInnerHTML={{ __html: md.renderer.render(buffer, md.options, {}) }} />)
+    parts.push(
+      <div
+        key={key++}
+        dangerouslySetInnerHTML={{
+          __html: md.renderer.render(buffer, md.options, {}),
+        }}
+      />,
+    )
     buffer = []
   }
   for (const t of tokens) {
@@ -109,7 +123,11 @@ export function DocMarkdown({ content, scope }: DocMarkdownProps): React.ReactEl
       // Palco do preview via flags no info (ex.: `tsx preview col md`): `col`/`col-start` = layout
       // em coluna (bloco: Alert, AspectRatio, grupo vertical); um token de largura (`md`, `2xl`…) =
       // cap de `max-w-*` (form/campo que não deve esticar). Viram o previewClassName do Example.
-      const dir = flags.includes('col-start') ? 'flex-col items-start' : flags.includes('col') ? 'flex-col items-stretch' : ''
+      const dir = flags.includes('col-start')
+        ? 'flex-col items-start'
+        : flags.includes('col')
+          ? 'flex-col items-stretch'
+          : ''
       const widthTok = flags.find((f) => /^(sm|md|lg|xl|2xl|3xl|4xl)$/.test(f))
       const previewClassName = [dir, widthTok ? `max-w-${widthTok}` : ''].filter(Boolean).join(' ') || undefined
       parts.push(

package/src/ui/docs/registry.tsx

@@ -22,6 +22,8 @@ import { navigate } from "../router.ts";
 import { DocPage } from "./doc.tsx";
 import { DocMarkdown } from "./markdown.tsx";
 import { OpusChangelog } from "./changelog.tsx";
+import type { DocSection } from "./types.ts";
+export type { DocEntry, DocGroup, DocSection } from "./types.ts";
 
 // — Conceituais (Começar/Framework/Design/Introdução) —
 import gettingStartedMd from "./content/getting-started.md?raw";
@@ -133,27 +135,6 @@ import splitMd from "./content/split.md?raw";
 import routerMd from "./content/router.md?raw";
 import dataStateMd from "./content/data-state.md?raw";
 
-export interface DocEntry {
-  slug: string;
-  title: string;
-  /** Tag técnica opcional exibida na nav ao lado do título — o subpath do SDK (ex.: 'auth'). */
-  badge?: string;
-  render: () => React.ReactElement;
-}
-
-export interface DocGroup {
-  /** Sub-rótulo opcional dentro da seção (ex.: Primitivos). Ausente = páginas direto na seção. */
-  label?: string;
-  /** Ícone opcional apresentado no nó expansível do grupo. */
-  icon?: React.ReactNode;
-  pages: DocEntry[];
-}
-
-export interface DocSection {
-  label: string;
-  groups: DocGroup[];
-}
-
 /**
  * O scope de previews da doc do Opus: a paleta de ícones (lucide inteiro) que os exemplos citam
  * por nome. Fica AQUI (no catálogo), não no DocMarkdown — assim só a superfície que exibe estes

package/src/ui/docs/standalone.tsx

@@ -11,15 +11,15 @@ import { StrictMode, useState } from 'react'
 import { createRoot } from 'react-dom/client'
 import { Moon, Sun } from 'lucide-react'
 import { Button, Toaster, TooltipProvider } from '../react.tsx'
-import { DocBrowser } from './DocBrowser.tsx'
+import { DocBrowser } from './CatalogDocBrowser.tsx'
 import type { DocSection } from './registry.tsx'
 
 const THEME_KEY = 'opus-theme'
 
 // Reexporta o adaptador de pasta: o entry do plugin `opusDocs({ source })` importa
 // `mountDocs` + `docSectionsFromFolder` daqui (mesmo subpath), sem export novo no package.
-export { docSectionsFromFolder } from './folder.tsx'
-export type { FolderOptions } from './folder.tsx'
+export { docSectionsFromFolder } from './catalog-folder.tsx'
+export type { FolderOptions, FolderPage } from './catalog-folder.tsx'
 
 function StandaloneDocBrowser({
   basePath,

package/src/ui/docs/types.ts

@@ -0,0 +1,24 @@
+import type * as React from 'react'
+
+export interface DocEntry {
+  slug: string
+  title: string
+  /** Tag técnica opcional exibida na navegação ao lado do título. */
+  badge?: string
+  /** Texto adicional consultado pela busca. Não é apresentado na navegação. */
+  searchText?: string
+  /** Caminho da fonte quando a página foi derivada de arquivo. */
+  sourcePath?: string
+  render: () => React.ReactElement
+}
+
+export interface DocGroup {
+  label?: string
+  icon?: React.ReactNode
+  pages: DocEntry[]
+}
+
+export interface DocSection {
+  label: string
+  groups: DocGroup[]
+}

package/src/ui/drivers/react.tsx

@@ -14,6 +14,7 @@
 import {
   useCallback,
   useMemo,
+  useRef,
   useState,
 } from 'react'
 import {
@@ -126,9 +127,11 @@ export function useLookupAction<TInput = unknown, TItem = unknown>(
 ): UseLookupActionResult<TInput, TItem> {
   const client = useClient('useLookupAction')
   const [state, setState] = useState<ListState<TItem>>(() => idleLookup<TItem>())
+  const latestRunRef = useRef(0)
 
   const run = useCallback(
     async (input: TInput): Promise<ListState<TItem>> => {
+      const runId = ++latestRunRef.current
       setState((prev) => ({
         ...prev,
         error: undefined,
@@ -162,13 +165,14 @@ export function useLookupAction<TInput = unknown, TItem = unknown>(
             isError: true,
           }
 
-      setState(next)
+      if (runId === latestRunRef.current) setState(next)
       return next
     },
     [client, action],
   )
 
   const reset = useCallback(() => {
+    latestRunRef.current += 1
     setState(idleLookup<TItem>())
   }, [])