Migrate Markdown renderers without breaking features

This skill replaces an existing Markdown renderer without silently dropping transforms, custom components, URL policy, raw-HTML behavior, or streaming semantics, directing readers to a companion adoption-checklist reference first. Its workflow: before changing dependencies or source files, inspect the existing package manager and project conventions, preview the intended edits, and obtain explicit user approval; inventory renderer imports, call sites, plugins, HTML policy, URL transforms, allowlists, custom renderers, CSS, and tests; classify the migration as direct, renderer-custom, plugin-heavy, or security-heavy; install the Markstream framework package and its explicit CSS, preserving visible behavior before adding optional features; map built-ins to scoped overrides, preferring renderer-local component maps in React; use trusted custom tags only for trusted content and reserve parse transforms for irreducible token/AST requirements; keep the content prop with smooth streaming for ordinary token streams, reaching for nodes only for worker parsing, shared AST ownership, or structural transforms; preserve safe HTML and strict Mermaid defaults, scoping and documenting any trusted legacy exception; and finally run the relevant builds and behavior tests, reporting mappings, intentional differences, and anything left for review.

Documented limitations: Markstream cannot reproduce every remark, rehype, or markdown-it plugin automatically, visual parity does not prove security or URL-policy parity, and large migrations may require a staged conversion. A security note: do not weaken sanitization just to achieve screenshot parity, and explicitly review dependencies, raw HTML, URL transforms, and trust boundaries during the migration.

Use when replacing react-markdown, markdown-it, marked, or another renderer; migrating node renderers; or choosing between Markstream's content, smooth streaming, and nodes modes.

Input is an existing Markdown-rendering codebase using a different library. Output is a Markstream-based renderer with visible behavior preserved, explicit HTML/URL/trust-boundary decisions documented, and a report of mappings, intentional differences, and unresolved review items.

// 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"
    />
  )
}

Developers migrating an existing app off react-markdown, markdown-it, marked, or another renderer onto Markstream, who need to preserve custom transforms, URL policy, and security behavior rather than just matching the old visual output.