upcontent 0.0.0-stage → 0.1.1

package/src/components/StructuredDataCopy.astro

@@ -0,0 +1,22 @@
+<script>
+  const buttons = document.querySelectorAll<HTMLButtonElement>('[data-sdp-copy]')
+
+  for (const button of buttons) {
+    button.addEventListener('click', async () => {
+      const source = button.dataset.sdpCopy
+      const label = button.querySelector('.sdp-copy-label')
+      if (!source || !label) return
+
+      try {
+        await navigator.clipboard.writeText(decodeURIComponent(source))
+        label.textContent = 'Copied'
+      } catch {
+        label.textContent = 'Copy failed'
+      }
+
+      window.setTimeout(() => {
+        label.textContent = 'Copy'
+      }, 1500)
+    })
+  }
+</script>

package/src/content/__mocks__/astro-content.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod'
+
+export { z }
+
+export function defineCollection(config: unknown) {
+  return config
+}

package/src/content/__mocks__/astro-loaders.ts

@@ -0,0 +1,3 @@
+export function glob(_config: unknown) {
+  return {}
+}

package/src/content/i18n/en.json

@@ -0,0 +1 @@
+{}

package/src/content.config.test.ts

@@ -0,0 +1,209 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+  readFileSync: vi.fn(),
+}))
+
+import * as fs from 'node:fs'
+import { domainFieldsSchema, isBlocked, resolveTitle, toCollectionId, toRelativeDocPath } from './content.config'
+import { _resetPortalConfigCache } from './lib/portal-config'
+
+beforeEach(() => {
+  _resetPortalConfigCache()
+  vi.mocked(fs.existsSync).mockReturnValue(false)
+})
+
+// domainFieldsSchema cobre só os campos de domínio deste portal — o título
+// obrigatório do Starlight é resolvido por resolveTitle() antes da
+// validação (ver describe('resolveTitle') abaixo), não faz parte deste schema.
+describe('domainFieldsSchema', () => {
+  it('aceita frontmatter completamente vazio', () => {
+    const result = domainFieldsSchema.safeParse({})
+    expect(result.success).toBe(true)
+  })
+
+  it('aceita status outdated', () => {
+    const result = domainFieldsSchema.safeParse({ status: 'outdated' })
+    expect(result.success).toBe(true)
+  })
+
+  it('aceita SEO por página com canonical absoluto e noindex', () => {
+    const result = domainFieldsSchema.safeParse({
+      canonical: 'https://docs.example.com/guides/seo/',
+      image: 'https://docs.example.com/social-card.png',
+      noindex: true,
+    })
+
+    expect(result.success).toBe(true)
+  })
+
+  it('rejeita canonical relativo', () => {
+    const result = domainFieldsSchema.safeParse({ canonical: '/guides/seo/' })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('rejeita canonical com esquema que não é HTTP(S)', () => {
+    const result = domainFieldsSchema.safeParse({ canonical: 'mailto:docs@example.com' })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('aceita created/updated como objeto Date (YAML parseia datas automaticamente)', () => {
+    const result = domainFieldsSchema.safeParse({
+      created: new Date('2026-08-07'),
+      updated: new Date('2026-08-07'),
+    })
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.created).toBe('2026-08-07')
+      expect(result.data.updated).toBe('2026-08-07')
+    }
+  })
+
+  it('aceita todos os campos de domínio preenchidos', () => {
+    const result = domainFieldsSchema.safeParse({
+      type: 'architecture',
+      status: 'active',
+      created: '2026-08-07',
+      updated: '2026-08-07',
+      teams: ['my-team'],
+      impacted_teams: [],
+      domains: [],
+      repos: ['my-frontend-repo'],
+      areas: [],
+      tags: ['sdd/prd'],
+      aliases: [],
+      related: [],
+    })
+    expect(result.success).toBe(true)
+  })
+})
+
+describe('resolveTitle', () => {
+  it('mantém o title do frontmatter quando presente', () => {
+    const data: Record<string, unknown> = { title: 'Meu Título' }
+    resolveTitle('docs/algo.md', data)
+    expect(data.title).toBe('Meu Título')
+  })
+
+  it('deriva do filename em Title Case quando title ausente', () => {
+    const data: Record<string, unknown> = {}
+    resolveTitle('domains/trd-backend.md', data)
+    expect(data.title).toBe('Trd Backend')
+  })
+
+  it('remove todas as extensões Markdown suportadas no título', () => {
+    const data: Record<string, unknown> = {}
+    resolveTitle('guides/legacy.markdown', data)
+    expect(data.title).toBe('Legacy')
+  })
+
+  it('remove prefixo numérico do filename antes de converter', () => {
+    const data: Record<string, unknown> = {}
+    resolveTitle('docs/adr/0001-self-hosted.md', data)
+    expect(data.title).toBe('Self Hosted')
+  })
+
+  it('usa apenas o nome do arquivo, ignorando o diretório', () => {
+    const data: Record<string, unknown> = {}
+    resolveTitle('domains/licencas/gestao-acessos.md', data)
+    expect(data.title).toBe('Gestao Acessos')
+  })
+
+  it('usa o campo configurado em content.titleField quando presente', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ content: { titleField: 'heading' } })
+    )
+    const data: Record<string, unknown> = { heading: 'Título Alternativo' }
+    resolveTitle('domains/algo.md', data)
+    expect(data.title).toBe('Título Alternativo')
+  })
+
+  it('cai no fallback de filename quando content.titleField está configurado mas ausente no frontmatter', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ content: { titleField: 'heading' } })
+    )
+    const data: Record<string, unknown> = {}
+    resolveTitle('domains/algo-especifico.md', data)
+    expect(data.title).toBe('Algo Especifico')
+  })
+})
+
+describe('isBlocked', () => {
+  it('bloqueia CLAUDE.md (case-insensitive)', () => {
+    expect(isBlocked('CLAUDE.md')).toBe(true)
+    expect(isBlocked('claude.md')).toBe(true)
+  })
+
+  it('bloqueia RULES.md (case-insensitive)', () => {
+    expect(isBlocked('RULES.md')).toBe(true)
+    expect(isBlocked('rules.md')).toBe(true)
+  })
+
+  it('bloqueia qualquer arquivo dentro de .claude/', () => {
+    expect(isBlocked('.claude/settings.json')).toBe(true)
+  })
+
+  it('bloqueia qualquer arquivo dentro de .github/', () => {
+    expect(isBlocked('.github/workflows/ci.yml')).toBe(true)
+  })
+
+  it('bloqueia qualquer arquivo dentro de .upcontent/', () => {
+    expect(isBlocked('.upcontent/config.json')).toBe(true)
+    expect(isBlocked('.upcontent/assets/logo.svg')).toBe(true)
+  })
+
+  // adversarial: arquivo com nome parecido mas que NÃO deve ser bloqueado
+  it('não bloqueia domains/README.md', () => {
+    expect(isBlocked('domains/README.md')).toBe(false)
+  })
+
+  it('bloqueia shared/INDEX.md (case-insensitive — arquivo real usa maiúsculo)', () => {
+    expect(isBlocked('shared/INDEX.md')).toBe(true)
+  })
+
+  it('não bloqueia docs/prd/prd.md', () => {
+    expect(isBlocked('docs/prd/prd.md')).toBe(false)
+  })
+
+  // adversarial: arquivo com prefixo ".cl" que NÃO é ".claude/"
+  it('não bloqueia um arquivo hipotético .clue/something.md', () => {
+    expect(isBlocked('.clue/something.md')).toBe(false)
+  })
+})
+
+describe('toRelativeDocPath', () => {
+  // o loader glob() do Astro gera entry.filePath relativo à raiz do projeto
+  // (ex: "src/content/docs/RULES.md"), não relativo ao content base — isBlocked()
+  // espera o path relativo ao content base (ex: "RULES.md")
+  it('remove o prefixo src/content/docs/', () => {
+    expect(toRelativeDocPath('src/content/docs/RULES.md')).toBe('RULES.md')
+    expect(toRelativeDocPath('src/content/docs/shared/index.md')).toBe('shared/index.md')
+  })
+
+  it('mantém o path como está se o prefixo não estiver presente', () => {
+    expect(toRelativeDocPath('RULES.md')).toBe('RULES.md')
+  })
+})
+
+describe('toCollectionId', () => {
+  it('maps the root README to the Starlight homepage id', () => {
+    expect(toCollectionId('README.md')).toBe('index')
+  })
+
+  it('normalizes document ids while preserving nested routes', () => {
+    expect(toCollectionId('Guides/Getting-Started.mdx')).toBe('guides/getting-started')
+  })
+
+  it('normalizes alternative Markdown extensions', () => {
+    expect(toCollectionId('Guides/Legacy.markdown')).toBe('guides/legacy')
+  })
+
+  it('normalizes nested index documents to their directory route', () => {
+    expect(toCollectionId('customization/index.md')).toBe('customization')
+  })
+})

package/src/content.config.ts

@@ -0,0 +1,113 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineCollection } from 'astro:content'
+import { z } from 'astro/zod'
+import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'
+import { i18nLoader } from '@astrojs/starlight/loaders'
+import { glob } from 'astro/loaders'
+import type { Loader, LoaderContext } from 'astro/loaders'
+import { getBlocklist, isBlocked, toRelativeDocPath, toTitleCase } from './lib/content-blocklist'
+import { getPortalConfig } from './lib/portal-config'
+
+export { getBlocklist, isBlocked, toRelativeDocPath }
+
+const MARKDOWN_EXTENSION = /\.(?:markdown|mdown|mkdn|mkd|mdwn|md|mdx)$/i
+
+// Campos de domínio específicos deste portal, além do schema padrão do
+// Starlight (title, description, sidebar, etc). Mantido isolado do
+// docsSchema() do Starlight pra ser testável sem precisar de um
+// SchemaContext (o título obrigatório do Starlight é resolvido pelo loader,
+// não pelo schema — ver resolveTitle()).
+export const domainFieldsSchema = z.object({
+  canonical: z.string().refine(value => {
+    try {
+      const url = new URL(value)
+      return (url.protocol === 'http:' || url.protocol === 'https:') && !url.username && !url.password
+    } catch {
+      return false
+    }
+  }, 'canonical must be an absolute HTTP(S) URL').optional(),
+  image: z.string().optional(),
+  noindex: z.boolean().optional(),
+  type: z.string().optional(),
+  status: z.string().optional(),
+  created: z.string().or(z.date().transform(d => d.toISOString().split('T')[0])).optional(),
+  updated: z.string().or(z.date().transform(d => d.toISOString().split('T')[0])).optional(),
+  teams: z.array(z.string()).optional(),
+  impacted_teams: z.array(z.string()).optional(),
+  domains: z.array(z.string()).optional(),
+  repos: z.array(z.string()).optional(),
+  areas: z.array(z.string()).optional(),
+  tags: z.array(z.string()).optional(),
+  aliases: z.array(z.string()).optional(),
+  related: z.array(z.string()).optional(),
+})
+
+// Resolve o título obrigatório do Starlight ANTES da validação do schema:
+// usa content.titleField do .upcontent/config.json se presente no frontmatter,
+// senão deriva do nome do arquivo em Title Case (prefixo numérico removido).
+// Muda `data` in-place — é chamado de dentro do generateId/parseData do
+// loader, no ponto em que o frontmatter ainda não foi validado.
+export function resolveTitle(relativeFilePath: string, data: Record<string, unknown>): void {
+  if (typeof data.title === 'string' && data.title.trim().length > 0) return
+
+  const titleField = getPortalConfig().content?.titleField ?? 'title'
+  if (titleField !== 'title') {
+    const custom = data[titleField]
+    if (typeof custom === 'string' && custom.trim().length > 0) {
+      data.title = custom
+      return
+    }
+  }
+
+  const filename = relativeFilePath.split('/').pop() ?? relativeFilePath
+  const withoutExt = filename.replace(MARKDOWN_EXTENSION, '')
+  data.title = toTitleCase(withoutExt)
+}
+
+export function toCollectionId(relativeFilePath: string): string {
+  const normalized = relativeFilePath.split(path.sep).join('/').replace(MARKDOWN_EXTENSION, '').toLowerCase()
+  if (normalized === 'readme') return 'index'
+  return normalized.endsWith('/index') ? normalized.slice(0, -'/index'.length) : normalized
+}
+
+function toCaseInsensitiveGlob(value: string): string {
+  return value.replace(/[A-Za-z]/g, character => `[${character.toLowerCase()}${character.toUpperCase()}]`)
+}
+
+// Carrega Markdown com glob(): injeta o fallback de título antes da validação
+// e aplica a blocklist como exclusões de glob antes do parse dos documentos.
+function portalDocsLoader(): Loader {
+  return {
+    name: 'portal-docs-loader',
+    async load(context: LoaderContext) {
+      const docsBasePath = fileURLToPath(new URL('src/content/docs/', context.config.root))
+      const patterns = [
+        '**/[^_]*.{markdown,mdown,mkdn,mkd,mdwn,md,mdx}',
+        ...getBlocklist().map(blocked => `!${toCaseInsensitiveGlob(blocked)}${blocked.endsWith('/') ? '**' : ''}`),
+      ]
+      const wrappedContext: LoaderContext = {
+        ...context,
+        parseData: async (props) => {
+          if (props.filePath) {
+            const relative = path.relative(docsBasePath, props.filePath).split(path.sep).join('/')
+            resolveTitle(relative, props.data)
+          }
+          return context.parseData(props)
+        },
+      }
+      await glob({ base: docsBasePath, pattern: patterns, generateId: ({ entry }) => toCollectionId(entry) }).load(wrappedContext)
+    },
+  }
+}
+
+export const collections = {
+  docs: defineCollection({
+    loader: portalDocsLoader(),
+    schema: docsSchema({ extend: domainFieldsSchema }),
+  }),
+  i18n: defineCollection({
+    loader: i18nLoader(),
+    schema: i18nSchema(),
+  }),
+}

package/src/lib/content-blocklist.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+  readFileSync: vi.fn(),
+}))
+
+import * as fs from 'node:fs'
+import { isBlocked, resolveLabel, toTitleCase } from './content-blocklist'
+import { _resetPortalConfigCache } from './portal-config'
+
+beforeEach(() => {
+  _resetPortalConfigCache()
+  vi.mocked(fs.existsSync).mockReturnValue(false)
+})
+
+describe('toTitleCase', () => {
+  it('deixa o resto da palavra em minúsculo mesmo quando o nome original é tudo maiúsculo', () => {
+    expect(toTitleCase('README')).toBe('Readme')
+  })
+
+  it('capitaliza cada palavra separada por hífen', () => {
+    expect(toTitleCase('gestao-licencas-acessos')).toBe('Gestao Licencas Acessos')
+  })
+})
+
+describe('resolveLabel', () => {
+  it('usa toTitleCase quando não há override configurado', () => {
+    expect(resolveLabel('historico')).toBe('Historico')
+  })
+
+  it('usa o override do .upcontent/config.json quando presente (case-insensitive)', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ navigation: { labelOverrides: { historico: 'Histórico' } } }),
+    )
+    expect(resolveLabel('historico')).toBe('Histórico')
+    expect(resolveLabel('Historico')).toBe('Histórico')
+  })
+})
+
+describe('isBlocked', () => {
+  it('protects the renderer checkout from external consumer content', () => {
+    expect(isBlocked('.upcontent-renderer/README.md')).toBe(true)
+    expect(isBlocked('.UPCONTENT-RENDERER/README.md')).toBe(true)
+  })
+})

package/src/lib/content-blocklist.ts

@@ -0,0 +1,55 @@
+import { getPortalConfig } from './portal-config'
+
+// Extraído de content.config.ts: precisa ser importável de astro.config.mjs
+// (sidebar.ts) e vitest sem depender de 'astro:content', que só resolve
+// dentro do pipeline do Astro — content.config.ts importa esse módulo em vez
+// de definir a lógica localmente.
+
+// Floor hardcoded: nunca aparecem independentemente do config.json.
+// Comparação sempre case-insensitive — arquivos reais podem usar qualquer
+// caixa (ex: shared/INDEX.md em vez de shared/index.md).
+const FLOOR_EXACT = new Set(['claude.md', 'rules.md', 'shared/index.md'])
+const FLOOR_PREFIXES = ['.claude/', '.github/', '.upcontent/', '.upcontent-renderer/']
+
+const DOCS_BASE = 'src/content/docs/'
+
+// entry.filePath de collections com o loader glob()/docsLoader() é relativo
+// à raiz do projeto (ex: "src/content/docs/RULES.md") — isBlocked() espera
+// o path relativo ao content base (ex: "RULES.md").
+export function toRelativeDocPath(filePath: string): string {
+  return filePath.startsWith(DOCS_BASE) ? filePath.slice(DOCS_BASE.length) : filePath
+}
+
+export function isBlocked(path: string): boolean {
+  const normalizedPath = path.toLowerCase()
+  if (FLOOR_EXACT.has(normalizedPath)) return true
+  if (FLOOR_PREFIXES.some(prefix => normalizedPath.startsWith(prefix.toLowerCase()))) return true
+  const cfg = getPortalConfig()
+  const exact = cfg.navigation?.blocklist?.exact ?? []
+  const prefixes = cfg.navigation?.blocklist?.prefixes ?? []
+  if (exact.some(e => normalizedPath === e.toLowerCase())) return true
+  return prefixes.some(prefix => normalizedPath.startsWith(prefix.toLowerCase()))
+}
+
+export function getBlocklist(): string[] {
+  const cfg = getPortalConfig()
+  const extraExact = cfg.navigation?.blocklist?.exact ?? []
+  const extraPrefixes = cfg.navigation?.blocklist?.prefixes ?? []
+  return [...FLOOR_EXACT, ...FLOOR_PREFIXES, ...extraExact, ...extraPrefixes]
+}
+
+export function toTitleCase(filenameWithoutExt: string): string {
+  const withoutNumericPrefix = filenameWithoutExt.replace(/^\d+[-_]/, '')
+  const words = withoutNumericPrefix.split(/[-_\s]+/).filter(Boolean)
+  if (words.length === 0) return filenameWithoutExt
+  return words.map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join(' ')
+}
+
+// Nomes de pasta/arquivo em ASCII (sem acento) não podem ser recuperados
+// automaticamente pro português — quem conhece o vocabulário é o
+// repositório de conteúdo, via navigation.labelOverrides no .upcontent/config.json.
+// Fallback é sempre toTitleCase(name) quando não há override.
+export function resolveLabel(name: string): string {
+  const override = getPortalConfig().navigation?.labelOverrides?.[name.toLowerCase()]
+  return override ?? toTitleCase(name)
+}

package/src/lib/doc-links.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest'
+import { buildGitHubUrl, resolveRelated } from './doc-links'
+
+describe('buildGitHubUrl', () => {
+  it('retorna undefined quando repoUrl não definido', () => {
+    expect(buildGitHubUrl(undefined, 'domains/foo/bar.md', 'view')).toBeUndefined()
+  })
+
+  it('retorna link view quando repoUrl definido', () => {
+    const url = buildGitHubUrl('https://github.com/org/repo', 'domains/foo/bar.md', 'view')
+    expect(url).toBe('https://github.com/org/repo/blob/main/domains/foo/bar.md')
+  })
+
+  it('retorna link edit quando repoUrl definido', () => {
+    const url = buildGitHubUrl('https://github.com/org/repo', 'domains/foo/bar.md', 'edit')
+    expect(url).toBe('https://github.com/org/repo/edit/main/domains/foo/bar.md')
+  })
+
+  it('não adiciona .md duplo quando entryId já termina em .md', () => {
+    const url = buildGitHubUrl('https://github.com/org/repo', 'domains/foo/bar.md', 'view')
+    expect(url).not.toContain('.md.md')
+  })
+})
+
+describe('resolveRelated', () => {
+  const allDocs = [
+    { id: 'domains/foo/prd.md', data: { title: 'Foo PRD' } },
+    { id: 'shared/glossary.md', data: { title: 'Glossário' } },
+    { id: 'domains/bar/trd.md', data: {} },
+  ]
+
+  it('retorna lista vazia quando related é undefined', () => {
+    expect(resolveRelated(undefined, allDocs as any)).toEqual([])
+  })
+
+  it('retorna lista vazia quando related é array vazio', () => {
+    expect(resolveRelated([], allDocs as any)).toEqual([])
+  })
+
+  it('resolve entry com .md normalizado', () => {
+    const result = resolveRelated(['domains/foo/prd'], allDocs as any)
+    expect(result).toHaveLength(1)
+    expect(result[0].title).toBe('Foo PRD')
+    expect(result[0].slug).toBe('domains/foo/prd')
+  })
+
+  it('resolve entry referenciado com extensão .md', () => {
+    const result = resolveRelated(['shared/glossary.md'], allDocs as any)
+    expect(result).toHaveLength(1)
+    expect(result[0].title).toBe('Glossário')
+  })
+
+  it('ignora referências que não existem na coleção', () => {
+    const result = resolveRelated(['domains/nao-existe'], allDocs as any)
+    expect(result).toHaveLength(0)
+  })
+
+  it('usa o id como título fallback quando title ausente', () => {
+    const result = resolveRelated(['domains/bar/trd'], allDocs as any)
+    expect(result[0].title).toBe('domains/bar/trd')
+  })
+})

package/src/lib/doc-links.ts

@@ -0,0 +1,31 @@
+import type { CollectionEntry } from 'astro:content'
+
+export function buildGitHubUrl(
+  repoUrl: string | undefined,
+  entryId: string,
+  mode: 'view' | 'edit',
+): string | undefined {
+  if (!repoUrl) return undefined
+  const action = mode === 'edit' ? 'edit' : 'blob'
+  return `${repoUrl}/${action}/main/${entryId}`
+}
+
+export interface RelatedDoc {
+  slug: string
+  title: string
+}
+
+export function resolveRelated(
+  related: string[] | undefined,
+  allDocs: CollectionEntry<'docs'>[],
+): RelatedDoc[] {
+  if (!related || related.length === 0) return []
+  return related.flatMap(ref => {
+    const normalized = ref.endsWith('.md') ? ref : `${ref}.md`
+    const entry = allDocs.find(d => d.id === normalized)
+    if (!entry) return []
+    const slug = normalized.replace(/\.md$/, '')
+    const title = (entry.data as Record<string, unknown>).title as string | undefined ?? slug
+    return [{ slug, title }]
+  })
+}

package/src/lib/mermaid-render.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, vi } from 'vitest'
+import { renderMermaidDiagram, type MermaidLib } from './mermaid-render'
+
+describe('renderMermaidDiagram', () => {
+  it('código válido → retorna o SVG renderizado', async () => {
+    const mermaid: MermaidLib = {
+      render: vi.fn().mockResolvedValue({ svg: '<svg>diagrama</svg>' }),
+    }
+    const result = await renderMermaidDiagram(mermaid, 'flowchart TD\nA-->B')
+    expect(result).toEqual({ status: 'ok', svg: '<svg>diagrama</svg>' })
+  })
+
+  it('código inválido → retorna a fonte original + mensagem de erro, sem lançar', async () => {
+    const mermaid: MermaidLib = {
+      render: vi.fn().mockRejectedValue(new Error('Parse error on line 1')),
+    }
+    const source = 'isso não é mermaid válido'
+    const result = await renderMermaidDiagram(mermaid, source)
+    expect(result).toEqual({ status: 'error', source, message: 'Parse error on line 1' })
+  })
+
+  it('erro que não é instância de Error também vira mensagem string, sem lançar', async () => {
+    const mermaid: MermaidLib = {
+      render: vi.fn().mockRejectedValue('algo deu errado'),
+    }
+    const result = await renderMermaidDiagram(mermaid, 'fonte')
+    expect(result).toEqual({ status: 'error', source: 'fonte', message: 'algo deu errado' })
+  })
+
+  it('cada chamada usa um id único (evita colisão entre diagramas na mesma página)', async () => {
+    const ids: string[] = []
+    const mermaid: MermaidLib = {
+      render: vi.fn().mockImplementation(async (id: string) => {
+        ids.push(id)
+        return { svg: '<svg/>' }
+      }),
+    }
+    await renderMermaidDiagram(mermaid, 'a')
+    await renderMermaidDiagram(mermaid, 'b')
+    expect(ids[0]).not.toBe(ids[1])
+  })
+})

package/src/lib/mermaid-render.ts

@@ -0,0 +1,24 @@
+// Interface mínima da lib mermaid que este módulo precisa — permite mockar
+// em teste sem importar a lib real (que depende de DOM/canvas).
+export interface MermaidLib {
+  render(id: string, source: string): Promise<{ svg: string }>
+}
+
+export type MermaidRenderResult =
+  | { status: 'ok'; svg: string }
+  | { status: 'error'; source: string; message: string }
+
+let renderCounter = 0
+
+// Função pura de parse/render: nunca lança — sintaxe inválida vira um
+// resultado 'error' carregando a fonte original + mensagem, pro caller
+// decidir como exibir (em vez de deixar a página em branco).
+export async function renderMermaidDiagram(mermaid: MermaidLib, source: string): Promise<MermaidRenderResult> {
+  const id = `mermaid-diagram-${renderCounter++}`
+  try {
+    const { svg } = await mermaid.render(id, source)
+    return { status: 'ok', svg }
+  } catch (error) {
+    return { status: 'error', source, message: error instanceof Error ? error.message : String(error) }
+  }
+}