@softize/opus 8.6.6

package/src/ui/docs/doc.tsx

@@ -0,0 +1,301 @@
+/**
+ * doc.tsx — blocos de construção das páginas da doc de UI (DocBrowser).
+ *
+ * Toda página compõe a partir daqui: DocPage (cabeçalho com meta), Example
+ * (exemplo vivo + snippet), CodeBlock e PropsTable. O `meta` vem de
+ * `@softize/opus/ui/meta` — whenToUse/ancestry têm UMA fonte (o
+ * próprio componente); a doc só renderiza.
+ */
+import { useLayoutEffect, useRef, useState } from 'react'
+import { Check, ChevronDown, Copy } from 'lucide-react'
+import { Highlight, type PrismTheme } from 'prism-react-renderer'
+import type { ComponentMeta } from '../index.ts'
+import {
+  Badge,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  cn,
+} from '../react.tsx'
+
+/** Prosa curta com `código` inline: trecho entre crases vira chip <code> — o
+ *  whenToUse/lead são texto plano (não passam pelo DocMarkdown). */
+function InlineMd({ text }: { text: string }): React.ReactElement {
+  const parts = text.split('`')
+  return (
+    <>
+      {parts.map((part, i) =>
+        i % 2 === 1 ? (
+          // eslint-disable-next-line react/no-array-index-key
+          <code key={i} className="rounded-[calc(var(--radius)-4px)] bg-muted px-1.5 py-0.5 font-mono text-[0.85em]">
+            {part}
+          </code>
+        ) : (
+          // eslint-disable-next-line react/no-array-index-key
+          <span key={i}>{part}</span>
+        ),
+      )}
+    </>
+  )
+}
+
+/**
+ * Página da doc: título, badge de origem (ancestry) e o whenToUse do meta como
+ * lead. Páginas conceituais (sem meta) passam só `lead`.
+ */
+export function DocPage({
+  title,
+  meta,
+  lead,
+  children,
+}: {
+  title: string
+  meta?: ComponentMeta
+  lead?: string
+  children: React.ReactNode
+}): React.ReactElement {
+  return (
+    <article className="space-y-10">
+      <header className="space-y-3">
+        <div className="flex items-center gap-3">
+          <h1 className="text-2xl font-semibold tracking-tight">{title}</h1>
+          {meta && (
+            <Badge variant="outline">{meta.ancestry === 'shadcn' ? 'shadcn' : 'Nativo do Opus'}</Badge>
+          )}
+        </div>
+        {(lead ?? meta?.whenToUse) !== undefined && (
+          <p className="max-w-2xl text-sm leading-relaxed break-words text-muted-foreground">
+            <InlineMd text={lead ?? meta?.whenToUse ?? ''} />
+          </p>
+        )}
+        {meta?.deprecated !== undefined && (
+          <div className="max-w-2xl rounded-lg border border-amber-500/30 bg-amber-500/10 px-3 py-2 text-sm leading-relaxed text-foreground">
+            <span className="font-medium">Deprecated{meta.deprecated.since !== undefined ? ` desde ${meta.deprecated.since}` : ''}.</span>{' '}
+            Use <InlineMd text={meta.deprecated.alternative} />.
+          </div>
+        )}
+      </header>
+      {children}
+    </article>
+  )
+}
+
+/** Seção nomeada dentro de uma página (agrupa exemplos ou prosa). */
+export function DocSection({
+  title,
+  hint,
+  children,
+}: {
+  title: string
+  hint?: string
+  children: React.ReactNode
+}): React.ReactElement {
+  return (
+    <section className="space-y-4">
+      <div className="space-y-1">
+        <h2 className="text-base font-semibold tracking-tight">{title}</h2>
+        {hint !== undefined && (
+          <p className="max-w-2xl text-sm leading-relaxed text-muted-foreground">
+            <InlineMd text={hint} />
+          </p>
+        )}
+      </div>
+      {children}
+    </section>
+  )
+}
+
+/**
+ * Exemplo vivo: preview renderizado com o tema da casa + o snippet de como se
+ * escreve. O snippet é a fonte de cópia — o preview, a expectativa visual.
+ */
+export function Example({
+  title,
+  hint,
+  code,
+  children,
+  previewClassName,
+  lang = 'tsx',
+}: {
+  title?: string
+  hint?: string
+  code: string
+  children: React.ReactNode
+  /** Layout do palco do preview (padrão: linha com wrap, itens centrados). */
+  previewClassName?: string
+  /** Linguagem do snippet pro highlight (default `tsx`). */
+  lang?: string
+}): React.ReactElement {
+  return (
+    <div className="space-y-2">
+      {title !== undefined && (
+        <div className="space-y-0.5">
+          <h3 className="font-medium leading-relaxed">{title}</h3>
+          {hint !== undefined && <p className="text-sm leading-relaxed text-muted-foreground">{hint}</p>}
+        </div>
+      )}
+      <div className="overflow-hidden rounded-lg border border-border">
+        <div className={cn('flex flex-wrap items-center gap-3 bg-background p-6', previewClassName)}>
+          {children}
+        </div>
+        <CodeBlock code={code} lang={lang} className="rounded-none border-x-0 border-b-0" />
+      </div>
+    </div>
+  )
+}
+
+// Tema do prism mapeado nos CSS vars da casa (theme.css) — o cascade troca light/dark sozinho.
+const codeTheme: PrismTheme = {
+  plain: { color: 'var(--code-fg)', backgroundColor: 'transparent' },
+  styles: [
+    { types: ['comment', 'prolog', 'doctype', 'cdata'], style: { color: 'var(--code-comment)', fontStyle: 'italic' } },
+    { types: ['keyword', 'selector', 'changed', 'operator', 'atrule'], style: { color: 'var(--code-keyword)' } },
+    { types: ['string', 'char', 'inserted', 'attr-value', 'url'], style: { color: 'var(--code-string)' } },
+    { types: ['function', 'function-variable'], style: { color: 'var(--code-function)' } },
+    { types: ['number', 'boolean', 'constant', 'symbol'], style: { color: 'var(--code-number)' } },
+    { types: ['class-name', 'tag', 'builtin', 'maybe-class-name'], style: { color: 'var(--code-class)' } },
+    { types: ['attr-name', 'property', 'variable'], style: { color: 'var(--code-property)' } },
+    { types: ['punctuation'], style: { color: 'var(--code-punctuation)' } },
+  ],
+}
+
+/** Altura do peek colapsado (px). Bate com `max-h-44` (11rem) — o conteúdo acima disto colapsa. */
+const PEEK_PX = 176
+
+/**
+ * Bloco de código com highlight (prism-react-renderer, tema da casa via CSS vars), gutter de
+ * número de linha e copiar. Código que TRANSBORDA o peek (medido, não por contagem de linha)
+ * colapsa num peek com fade + botão "Ver código"; o que cabe mostra inteiro. `collapsible={false}`
+ * força aberto.
+ */
+export function CodeBlock({
+  code,
+  className,
+  lang = 'tsx',
+  collapsible = true,
+}: {
+  code: string
+  className?: string
+  /** Linguagem do highlight (prism). Default `tsx`; passe `bash`/`css`/`json` quando couber. */
+  lang?: string
+  /** Permite o colapso (peek + Ver código) quando o código transborda o peek. Default `true`. */
+  collapsible?: boolean
+}): React.ReactElement {
+  const [copied, setCopied] = useState(false)
+  const [expanded, setExpanded] = useState(false)
+  const [overflows, setOverflows] = useState(false)
+  const contentRef = useRef<HTMLDivElement>(null)
+  const clean = code.replace(/\n$/, '')
+
+  // Colapsa só quando o código realmente passa da altura do peek — sem limiar de linha mágico
+  // (scrollHeight é a altura plena mesmo com o overflow-hidden aplicado). Re-mede via
+  // ResizeObserver: o mount sozinho pega o layout antes de assentar (fonte/flex) e mede errado
+  // de forma inconsistente — o observer corrige quando a altura final se estabelece.
+  useLayoutEffect(() => {
+    const el = contentRef.current
+    if (!el) return
+    const measure = (): void => setOverflows(el.scrollHeight > PEEK_PX)
+    measure()
+    const ro = new ResizeObserver(measure)
+    ro.observe(el)
+    return () => ro.disconnect()
+  }, [clean])
+
+  const canCollapse = collapsible && overflows
+  const collapsed = canCollapse && !expanded
+
+  return (
+    // overflow-hidden: os filhos (fade incluso) são CLIPADOS no raio do contêiner — sem
+    // isso, o overlay desenhava um segundo arco nos cantos (a "borda dobrada").
+    <div className={cn('group relative overflow-hidden rounded-lg border border-border bg-muted/40', className)}>
+      <button
+        onClick={() => {
+          void navigator.clipboard.writeText(clean)
+          setCopied(true)
+          setTimeout(() => setCopied(false), 1500)
+        }}
+        title="Copiar código"
+        className="absolute right-2 top-2 z-20 rounded-md p-1.5 text-muted-foreground opacity-0 transition-opacity hover:bg-muted hover:text-foreground group-hover:opacity-100"
+      >
+        {copied ? <Check className="h-3.5 w-3.5" /> : <Copy className="h-3.5 w-3.5" />}
+      </button>
+
+      <div ref={contentRef} className={cn('relative', collapsed && 'max-h-44 overflow-hidden')}>
+        <Highlight code={clean} language={lang} theme={codeTheme}>
+          {({ tokens, getLineProps, getTokenProps }) => (
+            <pre className="overflow-x-auto py-4 font-mono text-xs leading-7">
+              {tokens.map((line, i) => {
+                const { key, ...lineProps } = getLineProps({ line })
+                return (
+                  <div key={i} {...lineProps} className={cn(lineProps.className, 'flex')}>
+                    <span className="w-12 shrink-0 select-none pr-4 text-right tabular-nums text-muted-foreground/40">
+                      {i + 1}
+                    </span>
+                    <span className="flex-1 pr-4">
+                      {line.map((token, k) => {
+                        const { key: tk, ...tokenProps } = getTokenProps({ token })
+                        return <span key={k} {...tokenProps} />
+                      })}
+                    </span>
+                  </div>
+                )
+              })}
+            </pre>
+          )}
+        </Highlight>
+
+        {collapsed && (
+          // O fade NÃO fecha opaco — o código segue levemente visível; o clip do
+          // contêiner (overflow-hidden) cuida dos cantos.
+          <div className="absolute inset-x-0 bottom-0 z-10 flex items-end justify-center bg-gradient-to-t from-background/90 via-background/55 to-transparent pb-1.5 pt-16">
+            <button
+              aria-label="Ver código"
+              onClick={() => setExpanded(true)}
+              className="text-muted-foreground transition-colors hover:text-foreground"
+            >
+              <ChevronDown className="h-5 w-5" />
+            </button>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export interface PropRow {
+  prop: string
+  type: string
+  default?: string
+  description: string
+}
+
+/** Tabela de props — só as que o consumidor decide (não o spread de DOM props). */
+export function PropsTable({ rows }: { rows: PropRow[] }): React.ReactElement {
+  return (
+    <div className="overflow-hidden rounded-lg border border-border">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead className="w-[18%]">Prop</TableHead>
+            <TableHead className="w-[30%]">Tipo</TableHead>
+            <TableHead className="w-[12%]">Padrão</TableHead>
+            <TableHead>Descrição</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {rows.map((r) => (
+            <TableRow key={r.prop}>
+              <TableCell className="font-mono text-xs">{r.prop}</TableCell>
+              <TableCell className="whitespace-normal font-mono text-xs text-muted-foreground">{r.type}</TableCell>
+              <TableCell className="font-mono text-xs text-muted-foreground">{r.default ?? '—'}</TableCell>
+              <TableCell className="whitespace-normal text-xs">{r.description}</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  )
+}

package/src/ui/docs/folder.tsx

@@ -0,0 +1,149 @@
+/**
+ * folder — transforma a pasta `docs/` de um projeto em `DocSection[]` pro DocBrowser.
+ * Recebe o resultado de um glob eager do Vite (caminho → conteúdo do .md) e monta a nav
+ * espelhando a árvore de arquivos:
+ *
+ *   docs/getting-started.md   → seção raiz · página "Getting started"
+ *   docs/guias/deploy.md      → seção "Guias" · página (slug aninhado `guias/deploy`)
+ *   docs/guias/ci/build.md    → seção "Guias" · grupo "ci" · página `guias/ci/build`
+ *
+ * Convenção zero-config (frontmatter só SOBRESCREVE):
+ *  - seção  = 1ª pasta (`section:` sobrescreve; arquivo na raiz → `rootLabel`)
+ *  - grupo  = 2ª pasta em diante (`group:` sobrescreve)
+ *  - título = `title:` → 1º `# H1` → nome do arquivo humanizado
+ *  - ordem  = `order:` → prefixo numérico do nome (`01-deploy.md`) → alfabética
+ *  - slug   = caminho sem prefixo numérico/extensão (aninhado, estável pra deep link)
+ *
+ * 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.
+ */
+import { DocMarkdown } from './markdown.tsx'
+import type { DocEntry, DocGroup, DocSection } from './registry.tsx'
+
+interface FrontMatter {
+  title?: string
+  section?: string
+  group?: string
+  order?: number
+}
+
+/** Extrai o bloco `--- … ---` do topo (subset `key: value`) + o corpo restante. */
+function parseFrontMatter(raw: string): { data: FrontMatter; body: string } {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw)
+  if (!m) return { data: {}, body: raw }
+  const kv: Record<string, string> = {}
+  for (const line of (m[1] ?? '').split(/\r?\n/)) {
+    const pair = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line.trim())
+    if (pair) kv[pair[1]!] = (pair[2] ?? '').replace(/^['"]|['"]$/g, '').trim()
+  }
+  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 },
+    body: raw.slice(m[0].length),
+  }
+}
+
+/** `01-getting-started` → { order: 1, name: 'getting-started' }. Sem prefixo → order ausente. */
+function splitOrder(seg: string): { order?: number; name: string } {
+  const m = /^(\d+)[-_](.+)$/.exec(seg)
+  return m ? { order: Number(m[1]), name: m[2]! } : { name: seg }
+}
+
+/** `getting-started` → "Getting started"; `guias` → "Guias". */
+function humanize(seg: string): string {
+  const s = seg.replace(/[-_]+/g, ' ').trim()
+  return s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1)
+}
+
+/** 1º `# H1` do markdown, se houver — vira título quando não há frontmatter. */
+function firstH1(body: string): string | undefined {
+  const m = /^#\s+(.+)$/m.exec(body)
+  return m ? m[1]!.trim() : undefined
+}
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+export interface FolderOptions {
+  /** Pasta-fonte usada no glob (removida do início das chaves). Ex.: 'docs'. */
+  root?: string
+  /** Rótulo da seção para arquivos na raiz da pasta. Default "Documentação". */
+  rootLabel?: string
+}
+
+const LAST = 1e9
+
+interface Row {
+  slug: string
+  title: string
+  body: string
+  section: string
+  group?: string
+  secOrder: number
+  grpOrder: number
+  order: number
+}
+
+/**
+ * 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.
+ */
+export function docSectionsFromFolder(files: Record<string, string>, options: FolderOptions = {}): DocSection[] {
+  const rootLabel = options.rootLabel ?? 'Documentação'
+  const stripRe = options.root
+    ? new RegExp('^/?' + escapeRe(options.root.replace(/^\/+|\/+$/g, '')) + '/')
+    : /^\/?[^/]+\//
+  const rows: Row[] = []
+
+  for (const [path, raw] of Object.entries(files)) {
+    const rel = path.replace(stripRe, '').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('/'),
+      title: data.title ?? firstH1(body) ?? humanize(file.name),
+      body,
+      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,
+      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[] }> }>()
+  for (const r of rows) {
+    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: [] }
+    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))
+
+  return [...sections.entries()]
+    .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} /> })),
+          }),
+        ),
+    }))
+}

package/src/ui/docs/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @softize/opus/ui/docs — a doc de UI da casa (o "DocBrowser"), reusável por qualquer app.
+ *
+ * Consumo:
+ *  - Embutida num shell (Maestro): `<DocBrowser basePath="/docs" path={path} />` (modo controlado).
+ *  - 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 { 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'
+// 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.
+export { DocMarkdown } from './markdown.tsx'
+export type { DocMarkdownProps } from './markdown.tsx'
+// O changelog do pacote, pronto pra montar (o site o usa como página do menu superior).
+export { OpusChangelog, ChangelogView } from './changelog.tsx'

package/src/ui/docs/markdown.tsx

@@ -0,0 +1,130 @@
+/**
+ * DocMarkdown — o renderer de markdown do DocBrowser. Prosa/tabelas via markdown-it; e
+ * fence-dispatch pelos TOKENS do markdown-it (robusto — crase inline na prosa NÃO confunde,
+ * ao contrário de um split por regex):
+ *
+ *   ```tsx preview  → componente RODANDO (sucrase transpila o jsx → createElement, avaliado
+ *                     com o `scope`), dentro do <Example> (preview + snippet, tema da casa)
+ *   ```<lang>       → <CodeBlock> (highlight + copiar)
+ *   (prosa/tabelas) → markdown-it
+ *
+ * `scope` (default: o opus/ui) = os componentes disponíveis nos blocos `tsx preview`. O
+ * `new Function` é aceitável porque o markdown é conteúdo do projeto (confiável), não de terceiro.
+ * 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 { 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
+// pelo `scope` (o registry passa o lucide inteiro) — assim o renderer não arrasta o lucide pro
+// bundle de TODO consumidor do DocMarkdown; só a superfície que exibe o catálogo paga por ele.
+const DEFAULT_SCOPE: Record<string, unknown> = {
+  ...opusUi,
+  useState: React.useState,
+  useEffect: React.useEffect,
+  useRef: React.useRef,
+  useMemo: React.useMemo,
+  useCallback: React.useCallback,
+  useId: React.useId,
+}
+
+function LiveBlock({
+  code,
+  scope,
+  previewClassName,
+}: {
+  code: string
+  scope: Record<string, unknown>
+  previewClassName?: string
+}): React.ReactElement {
+  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
+      // 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.
+      const entries = Object.entries({ React, ...scope }).filter(
+        ([k]) => /^[A-Za-z_$][\w$]*$/.test(k) && k !== 'default' && (k === 'React' || code.includes(k)),
+      )
+      const fn = new Function(...entries.map(([k]) => k), js)
+      const args = entries.map(([, v]) => v)
+      // Componente estável (memoizado por [code, scope]): React o chama no render, então os
+      // hooks do snippet executam durante um render de verdade — não num eval solto.
+      const Comp = (): React.ReactNode => fn(...args) as React.ReactNode
+      return { Comp }
+    } catch (e) {
+      return { error: e instanceof Error ? e.message : String(e) }
+    }
+  }, [code, scope])
+  const Comp = result.Comp
+  return (
+    <Example code={code.trim()} previewClassName={previewClassName}>
+      {result.error ? <span className="text-sm text-red-500">{result.error}</span> : Comp ? <Comp /> : null}
+    </Example>
+  )
+}
+
+export interface DocMarkdownProps {
+  content: string
+  /** 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>
+}
+
+export function DocMarkdown({ content, scope }: 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 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, {}) }} />)
+    buffer = []
+  }
+  for (const t of tokens) {
+    if (t.type === 'fence' && t.level === 0) {
+      flush()
+      const info = (t.info ?? '').trim()
+      const infoTokens = info.split(/\s+/)
+      const lang = infoTokens[0] || 'tsx'
+      const flags = infoTokens.slice(1)
+      // 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 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(
+        <div key={key++} className="not-prose">
+          {/\b(preview|live)\b/.test(info) ? (
+            <LiveBlock code={t.content} scope={liveScope} previewClassName={previewClassName} />
+          ) : (
+            <CodeBlock code={t.content.replace(/\n$/, '')} lang={lang} />
+          )}
+        </div>,
+      )
+    } else {
+      buffer.push(t)
+    }
+  }
+  flush()
+  return <div className="prose prose-sm max-w-none space-y-4">{parts}</div>
+}

package/src/ui/docs/md-raw.d.ts

@@ -0,0 +1,4 @@
+declare module '*.md?raw' {
+  const src: string
+  export default src
+}