Migração do Markstream

Visão Geral

Substitua um renderizador Markdown existente sem descartar silenciosamente transformações, componentes personalizados, política de URL, comportamento de HTML bruto ou semântica de streaming. Leia references/adoption-checklist.md primeiro.

Quando Usar

Use ao substituir react-markdown, markdown-it, marked ou outro renderizador; migrar renderizadores de nó; ou escolher entre Markstream content, streaming suave e nodes.

Fluxo de Trabalho

Antes de alterar dependências ou arquivos de origem, inspecione o gerenciador de pacotes existente e as convenções do projeto, visualize as edições pretendidas e obtenha aprovação explícita do usuário.

1. Inventarie importações de renderizador, locais de chamada, plugins, política de HTML, transformações de URL, listas de permissões, renderizadores personalizados, CSS e testes.
2. Classifique a migração como direta, personalizada-renderizador, com muitos plugins ou com foco em segurança.
3. Instale o pacote do framework e o CSS explícito. Preserve o comportamento visível antes dos recursos opcionais.
4. Mapeie os embutidos para substituições com escopo; no React, prefira mapas de componentes locais do renderizador.
5. Use tags personalizadas confiáveis apenas para conteúdo confiável e reserve transformações de análise para requisitos irredutíveis de token/AST.
6. Mantenha content com streaming suave para fluxos de token comuns. Use nodes apenas para análise de worker, propriedade compartilhada de AST ou transformações estruturais.
7. Preserve os padrões seguros de HTML e Mermaid estritos; escopo e documente quaisquer exceções legadas confiáveis.
8. Execute os builds e testes de comportamento relevantes. Relate mapeamentos, diferenças intencionais e revisões não resolvidas.

Exemplo

// Before:
// import ReactMarkdown from 'react-markdown'
// return <ReactMarkdown>{markdown}</ReactMarkdown>

import MarkdownRender from 'markstream-react'
import 'markstream-react/index.css'

export function AssistantAnswer({
  markdown,
  isDone,
}: {
  markdown: string
  isDone: boolean
}) {
  return (
    <MarkdownRender
      content={markdown}
      final={isDone}
      fade={isDone}
      typewriter={!isDone}
      smoothStreaming={isDone ? false : 'auto'}
      htmlPolicy="safe"
    />
  )
}

Limitações

• O Markstream não pode reproduzir automaticamente todos os plugins remark, rehype ou markdown-it.
• A paridade visual não prova a paridade de segurança ou política de URL.
• Migrações grandes podem exigir conversão em estágios.

Notas de Segurança e Proteção

Não enfraqueça a sanitização para paridade de captura de tela. Revise explicitamente dependências, HTML bruto, transformações de URL e limites de confiança.