AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Markdown Preview Agent Guide

Agent guide for Markdown rendering, DOM sanitization, and preview-copy behavior.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Markdown Preview in the alexandrai-tools project.

Project overview

This guide covers src/tools/markdown-preview/index.ts and src/tools/markdown-preview/Body.astro. The pure logic wrapper renders Markdown with marked. The browser body sanitizes the rendered HTML with DOMPurify before assigning innerHTML, debounces live preview updates, supports sample and clear actions, and copies the sanitized preview HTML.

Primary source files

  • src/tools/markdown-preview/index.ts defines meta and renderMarkdown.
  • src/tools/markdown-preview/index.test.ts covers headings, strong text, emphasis, lists, and empty input.
  • src/tools/markdown-preview/Body.astro wires renderMarkdown, DOMPurify.sanitize, debounce, clear, sample, and copy behavior.
  • src/lib/dom.ts provides selector, debounce, and copy helpers.
  • src/tools/markdown-preview/i18n.ts owns localized labels.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Keep raw marked output out of the DOM until it has passed through DOMPurify.
  • Copy sanitized preview HTML, not unsanitized renderer output.
  • Keep renderMarkdown pure so tests can exercise renderer behavior without DOM state.
  • Debounce input handling in the browser body to avoid unnecessary render churn.
  • Do not add remote Markdown rendering or upload behavior.
  • If custom marked options are introduced, add XSS regression coverage around the Body.astro sanitization path.
  • Avoid sample content with private links or personal data in generated public docs.

Testing

Test common Markdown output, empty input, sanitization around script-like input, copy behavior using sanitized HTML, clear behavior, debounce behavior where practical, and sample rendering. Keep renderer tests separate from DOM safety tests.

PR checklist

  • npm test passes for markdown-preview.
  • DOMPurify remains in the render-to-DOM path.
  • No unsanitized renderer output is assigned to innerHTML.
  • The tool remains browser-local.