@softize/opus 25.5.0 → 25.6.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ 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

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

@@ -43,6 +43,12 @@ O renderizador compartilhado pode reescrever links e criar IDs estáveis para t
 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
@@ -73,5 +79,7 @@ existir evidência operacional para sustentar essa separação.
 - 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.5.0",
+  "version": "25.6.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -221,6 +221,10 @@
       "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. */
@@ -60,16 +61,6 @@ function resolveTokenLinks(tokens: ReturnType<typeof markdownIt.parse>, resolveH
   }
 }
 
-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) => {
@@ -87,7 +78,7 @@ function identifyHeadings(tokens: ReturnType<typeof markdownIt.parse>): void {
     const content = tokens[index + 1]
     if (opening?.type !== 'heading_open' || content?.type !== 'inline') continue
     const text = visibleInlineText(content.children ?? [])
-    const base = headingId(text)
+    const base = documentationHeadingAnchor(text)
     if (base === '') continue
     let candidate = base
     let suffix = 1

package/src/ui/docs/browser.tsx

@@ -6,6 +6,13 @@ 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/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

@@ -20,6 +20,7 @@
  * históricas injetam o renderizador de exemplos vivos em `catalog-folder.tsx`.
  */
 import { Markdown } from '../components/primitives/markdown.tsx'
+import { documentationSlugFromSourcePath } from './links.ts'
 import type { DocEntry, DocGroup, DocSection } from './types.ts'
 
 interface FrontMatter {
@@ -123,7 +124,7 @@ export function docSectionsFromFolder(files: Record<string, string>, options: Fo
     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,

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) }),
+  }
+}