@softize/opus 25.4.1 → 25.6.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ 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.6.0 — 2026-10-07
+
+Aplicações que apresentam Markdown do próprio produto podem usar
+`@softize/opus/ui/docs/links` para resolver caminhos relativos, derivar slugs e normalizar
+fragmentos sem carregar React. A entrada `@softize/opus/ui/docs/browser` também reexporta esses
+utilitários. O renderizador compartilhado usa a mesma normalização nos IDs dos títulos, inclusive
+quando o texto contém hífens cercados por espaços ou repetidos; assim, links e headings deixam de
+divergir nesses casos.
+
+Não há migração geral obrigatória. Links profundos já salvos para títulos com hífen cercado por
+espaços ou com hífens consecutivos precisam usar um único hífen; por exemplo, `a---b` passa a ser
+`a-b`. Consumidores que já implementam essa gramática localmente podem substituí-la pelos
+utilitários compartilhados e continuar decidindo a rota e o espaço de destino. O resolvedor aceita
+fontes `.md` e `.mdx`; o caminho atual é relativo à raiz documental, e apenas `/docs/` com barra
+inicial declara essa raiz num link absoluto.
+
+## 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

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

@@ -0,0 +1,85 @@
+# 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.
+
+O subpath leve `@softize/opus/ui/docs/links` publica a normalização de âncoras, a derivação de slug a
+partir do caminho da fonte e a resolução de links Markdown relativos sem carregar React. A entrada
+`browser` também os reexporta por conveniência. O renderizador e os consumidores usam essas funções
+em comum: uma aplicação decide em qual espaço ou superfície abrir a fonte resolvida, mas não
+reimplementa a gramática de caminhos, prefixos numéricos e fragmentos.
+
+### 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.
+- Links Markdown relativos, slugs e fragmentos seguem uma gramática compartilhada; o consumidor
+  continua responsável por mapear a fonte resolvida para seu espaço, sua rota e sua política.
+- 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.1",
+  "version": "25.6.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -217,6 +217,14 @@
       "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/links": {
+      "types": "./src/ui/docs/links.ts",
+      "default": "./src/ui/docs/links.ts"
+    },
     "./ui/docs/standalone": {
       "types": "./src/ui/docs/standalone.tsx",
       "default": "./src/ui/docs/standalone.tsx"

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

@@ -12,6 +12,7 @@
  */
 import * as React from 'react'
 import MarkdownIt from 'markdown-it'
+import { documentationHeadingAnchor } from '../../docs/links.ts'
 
 /** A instância ÚNICA — a doc (`DocMarkdown`) importa esta mesma. Duas instâncias com
  *  opções próprias divergiriam no primeiro edge case, e "mesmo motor" viraria promessa. */
@@ -37,12 +38,78 @@ 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 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 = documentationHeadingAnchor(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 +117,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/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,18 @@
+/**
+ * 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 {
+  documentationAnchor,
+  documentationHeadingAnchor,
+  documentationSlugFromSourcePath,
+  resolveDocumentationLinkTarget,
+} from './links.ts'
+export type { DocumentationLinkTarget } from './links.ts'
+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/markdown.md

@@ -34,6 +34,45 @@ const sample = [
 render(<Markdown content={sample} />)
 ```
 
+## Documentos navegáveis
+
+Ao apresentar uma pasta de documentação, use `headingIds` para gerar âncoras e `resolveHref` para
+transformar os links internos na rota da aplicação. Os utilitários de
+`@softize/opus/ui/docs/links` mantêm os dois lados na mesma gramática sem decidir a URL final.
+
+```tsx
+import {
+  documentationSlugFromSourcePath,
+  resolveDocumentationLinkTarget,
+} from '@softize/opus/ui/docs/links'
+
+const sourcePath = 'guides/current.md'
+
+<Markdown
+  content={content}
+  headingIds
+  resolveHref={(href) => {
+    const target = resolveDocumentationLinkTarget(sourcePath, href)
+    if (target === null) return href
+    const slug = documentationSlugFromSourcePath(target.sourcePath)
+    return `/docs/project/${slug}${target.anchor === undefined ? '' : `#${target.anchor}`}`
+  }}
+/>
+```
+
+Passe `sourcePath` relativo à raiz documental. Um link absoluto iniciado por `/docs/` volta a essa
+raiz; `docs/` sem a barra inicial continua sendo uma subpasta comum. Protocolos, arquivos que não
+são Markdown e caminhos que escapam da raiz retornam `null`, para a aplicação preservar ou tratar o
+endereço original.
+
+## Referência de links documentais
+
+| Função | Resultado |
+|---|---|
+| `resolveDocumentationLinkTarget(currentSourcePath, href)` | Devolve o caminho `.md` ou `.mdx` relativo à raiz e a âncora normalizada. Decodifica segmentos percentuais válidos e devolve `null` quando o endereço não pertence ao acervo. |
+| `documentationSlugFromSourcePath(sourcePath)` | Remove a extensão e os prefixos numéricos de ordenação de cada segmento. Preserva a hierarquia restante. |
+| `documentationAnchor(fragment)` | Decodifica e normaliza um fragmento URI para comparação com o ID do título. |
+| `documentationHeadingAnchor(text)` | Normaliza o texto visível de um título sem interpretar sequências percentuais como URI. |
 
 ## Propriedades de Markdown
 
@@ -41,3 +80,5 @@ render(<Markdown content={sample} />)
 |---|---|---|---|
 | `content` | `string` | obrigatório | O texto em Markdown (CommonMark e tabelas do GFM, via markdown-it). HTML no texto é escapado, não interpretado, por isso o componente serve para texto escrito por pessoas ou gerado por modelos. Endereços soltos, como `https://…`, viram links. |
 | `className` | `string` | | Classes do contêiner. |
+| `resolveHref` | `(href: string) => string` | | Reescreve cada link antes da validação e da renderização. Use para transformar caminhos documentais em rotas da aplicação. |
+| `headingIds` | `boolean` | `false` | Gera IDs normalizados e únicos nos títulos. Ative em documentos navegáveis; mantenha desativado em mensagens comuns. |

package/src/ui/docs/folder.tsx

@@ -16,10 +16,12 @@
  *
  * 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 { documentationSlugFromSourcePath } from './links.ts'
+import type { DocEntry, DocGroup, DocSection } from './types.ts'
 
 interface FrontMatter {
   title?: string
@@ -39,7 +41,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 +78,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 +95,7 @@ interface Row {
   slug: string
   title: string
   body: string
+  sourcePath: string
   section: string
   group?: string
   secOrder: number
@@ -88,7 +105,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,52 +116,106 @@ 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)
     const file = splitOrder(segs[segs.length - 1]!)
     const dirs = segs.slice(0, -1).map(splitOrder)
     rows.push({
-      slug: [...dirs.map((d) => d.name), file.name].join('/'),
+      slug: documentationSlugFromSourcePath(sourcePath),
       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/links.ts

@@ -0,0 +1,102 @@
+export interface DocumentationLinkTarget {
+  sourcePath: string
+  anchor?: string
+}
+
+function decodePathSegment(segment: string): string {
+  try {
+    return decodeURIComponent(segment)
+  } catch {
+    return segment
+  }
+}
+
+function normalizeDocumentationPath(path: string): string | null {
+  const segments: string[] = []
+  for (const encodedSegment of path.split('/')) {
+    const segment = decodePathSegment(encodedSegment)
+    if (segment === '' || segment === '.') continue
+    if (segment === '..') {
+      if (segments.length === 0) return null
+      segments.pop()
+      continue
+    }
+    if (segment.includes('/') || segment.includes('\\')) return null
+    segments.push(segment)
+  }
+  return segments.join('/')
+}
+
+function normalizeDocumentationAnchor(value: string, decodeUri: boolean): string {
+  let decoded = value
+  if (decodeUri) {
+    try {
+      decoded = decodeURIComponent(value)
+    } catch {
+      // Fragmentos malformados continuam navegáveis pela normalização conservadora.
+    }
+  }
+  return decoded
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLocaleLowerCase('pt-BR')
+    .replace(/[^a-z0-9\s-]/g, '')
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+}
+
+/** Normaliza um fragmento URI para a âncora usada pela documentação. */
+export function documentationAnchor(value: string): string {
+  return normalizeDocumentationAnchor(value, true)
+}
+
+/** Normaliza o texto visível de um título sem interpretar sequências percentuais como URI. */
+export function documentationHeadingAnchor(value: string): string {
+  return normalizeDocumentationAnchor(value, false)
+}
+
+/** Deriva o slug de um caminho já relativo à raiz documental do consumidor. */
+export function documentationSlugFromSourcePath(sourcePath: string): string {
+  return sourcePath
+    .replace(/^\/+/, '')
+    .replace(/\.mdx?$/i, '')
+    .split('/')
+    .filter(Boolean)
+    .map((segment) => segment.replace(/^\d+[-_](.+)$/, '$1'))
+    .join('/')
+}
+
+/**
+ * Resolve links Markdown internos. `currentSourcePath` deve ser relativo à raiz documental.
+ * `/docs/` indica essa raiz em um link absoluto; `docs/` sem a barra inicial é uma pasta normal.
+ * Retorna `null` para protocolos, arquivos que não são Markdown e caminhos fora da raiz.
+ */
+export function resolveDocumentationLinkTarget(
+  currentSourcePath: string,
+  href: string,
+): DocumentationLinkTarget | null {
+  if (/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(href)) return null
+
+  const current = normalizeDocumentationPath(currentSourcePath.replace(/^\/+/, ''))
+  if (current === null) return null
+  if (href.startsWith('#')) {
+    return { sourcePath: current, anchor: documentationAnchor(href.slice(1)) }
+  }
+
+  const fragmentIndex = href.indexOf('#')
+  const target = fragmentIndex < 0 ? href : href.slice(0, fragmentIndex)
+  const fragment = fragmentIndex < 0 ? undefined : href.slice(fragmentIndex + 1)
+  if (target.startsWith('/') && !target.startsWith('/docs/')) return null
+  const currentDirectory = current.slice(0, current.lastIndexOf('/') + 1)
+  const candidate = normalizeDocumentationPath(
+    target.startsWith('/docs/')
+      ? target.slice('/docs/'.length)
+      : `${currentDirectory}${target}`,
+  )
+  if (candidate === null || !/\.mdx?$/i.test(candidate)) return null
+  return {
+    sourcePath: candidate,
+    ...(fragment === undefined ? {} : { anchor: documentationAnchor(fragment) }),
+  }
+}

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[]
+}