memd-cli 1.5.0 → 2.0.0

package/highlight-plan.md

@@ -0,0 +1,710 @@
+memd v2 Syntax Highlighting Overhaul: cli-highlight -> Shiki
+=============================================================
+
+## Decisions
+
+| # | Topic | Decision |
+|---|-------|----------|
+| 1 | Missing themes strategy | Pattern C: Use nearest Shiki built-in theme for syntax highlighting; keep beautiful-mermaid built-in for diagrams |
+| 2 | Theme architecture | Pattern F: beautiful-mermaid built-in themes for diagrams, Shiki themes for syntax highlighting + markdown styling only |
+| 3 | Language preload | Pattern G: Preload top 19 languages on first use (lazy init, not at import time) |
+| 4 | Node.js minimum | Node.js >= 20 (required by Shiki v4 JS RegExp engine) |
+| 5 | cli-highlight dep | Pattern L: Remove from package.json direct dependencies (remains as transitive dep of marked-terminal) |
+| 6 | cli-highlight bypass | Code renderer override via `marked.use()` intercepts all code blocks before marked-terminal's internal highlight; marked-terminal's `highlightOptions` passed as `null` (falls back to `{}` internally, but never reached) |
+
+## Background
+
+### Current Problems
+
+1. **Color source fragmentation**: 5 themes have hand-crafted 13-color palettes in memd (`TERMINAL_THEMES`), 10 themes auto-derive from beautiful-mermaid's `DiagramColors` (3 colors), resulting in inconsistent quality
+2. **cli-highlight limitations**: Based on highlight.js v10, limited language support, no built-in truecolor themes, "Could not find the language" warnings leak to console
+3. **Redundant color utilities**: `mute()`, `hexToHsl()`, `hslToHex()`, `buildTheme()`, `buildMarkdownFromDiagramColors()` all exist to compensate for the lack of a proper theme system
+4. **beautiful-mermaid and terminal text colors are decoupled**: Diagram colors come from `MERMAID_THEMES`, terminal text colors come from memd's hand-crafted palettes or auto-derivation -- no single source of truth
+
+### Solution
+
+Replace cli-highlight with **Shiki** (v4.0.2) for syntax highlighting. Shiki uses VS Code / TextMate themes -- the same origin as beautiful-mermaid.
+
+- **Syntax highlighting + markdown styling**: Shiki theme objects (50+ token colors per theme)
+- **Diagram colors**: beautiful-mermaid built-in `MERMAID_THEMES` (hand-tuned DiagramColors, higher quality than auto-derivation)
+
+### HTML Path Impact: None
+
+The HTML output path (`--html`) is **not affected** by this migration:
+
+- Uses an independent `new Marked()` instance (main.js:305), never configured with `markedTerminal`
+- Does not use `cli-highlight` or any syntax highlighter (CSS-only styling for code blocks)
+- Only consumes `diagramColors` for CSS variables and SVG diagram rendering
+- `renderToHTML()` (main.js:303-334) requires zero changes
+
+## Architecture (After)
+
+### Color Flow
+
+```mermaid
+flowchart TD
+    A["--theme name<br>(e.g. nord)"] --> B["THEME_MAP[name]"]
+    B --> C["Shiki theme object<br>(VS Code / TextMate format)<br>50+ token colors"]
+    B --> D["MERMAID_THEMES[mermaidTheme]<br>DiagramColors (built-in)<br>bg, fg, accent, muted, line"]
+
+    C --> E["Shiki highlighter<br>codeToTokensBase() -> ANSI<br>truecolor syntax highlight"]
+    C --> F["extractMarkdownStyle()<br>+ softenHex() desaturation<br>heading, link, code, blockquote..."]
+
+    D --> G["renderMermaidSVG /<br>renderMermaidASCII<br>diagram colors"]
+
+    E --> H["marked code renderer<br>(override)"]
+    F --> I["markedTerminal options<br>markdown element styling"]
+
+    H --> J["Terminal output"]
+    I --> J
+    G --> J
+```
+
+### What Gets Removed
+
+| Item | Location | Reason |
+|------|----------|--------|
+| `hexToHsl()` | main.js:19-37 | Replaced by `softenHex()` (sRGB blend, no HSL needed) |
+| `hslToHex()` | main.js:39-61 | Same as above |
+| `mute()` | main.js:64-69 | Same as above |
+| `buildTheme()` | main.js:88-133 | Replaced by `extractMarkdownStyle()` from Shiki themes |
+| `TERMINAL_THEMES` (5 palettes) | main.js:136-172 | Replaced by Shiki themes |
+| `buildMarkdownFromDiagramColors()` | main.js:175-193 | Replaced by `extractMarkdownStyle()` |
+| `resolveTerminalTheme()` | main.js:195-197 | Replaced by `THEME_MAP` lookup |
+| `resolveDiagramTheme()` | main.js:230-234 | Replaced by unified `THEME_MAP` validation |
+| `console.error` suppression hack | main.js:503-515 | highlight.js is no longer called |
+| `cli-highlight` import | main.js:6 | Replaced by Shiki |
+| `cli-highlight` in package.json | package.json:15 | Removed from direct dependencies |
+
+### What Gets Kept (unchanged)
+
+| Item | Location | Reason |
+|------|----------|--------|
+| `mixHex()` | main.js:73-82 | Still needed for diagram/HTML path |
+| `MIX` | main.js:85 | Still needed for diagram/HTML path |
+| `diagramColorsToAsciiTheme()` | main.js:202-215 | Still needed for ASCII diagram rendering |
+| `resolveThemeColors()` | main.js:218-227 | Still needed for HTML path CSS |
+
+### What Gets Added
+
+| Item | Purpose |
+|------|---------|
+| `shiki` dependency | Syntax highlighting engine (v4.0.2); automatically includes `@shikijs/themes`, `@shikijs/langs`, `@shikijs/engine-javascript` as sub-packages |
+| Shiki imports (core, engine, themes, langs) | Individual default imports for tree-shaking |
+| `THEME_MAP` | Maps memd theme name -> `{ shikiTheme, mermaidTheme }` |
+| `THEME_NAMES` | `Object.keys(THEME_MAP)` (replaces `Object.keys(MERMAID_THEMES)`) |
+| `getHighlighter()` (lazy singleton) | Returns Shiki highlighter instance, created on first call (skips init for --version/--help) |
+| `highlightWithShiki()` | Tokenizes code with Shiki and converts to ANSI |
+| `tokensToAnsi()` | Converts Shiki `ThemedToken[][]` to truecolor ANSI string |
+| `softenHex()` | sRGB blend toward gray for gentle desaturation of markdown styles |
+| `extractMarkdownStyle()` | Extracts markdown element styling from Shiki theme token scopes, with `softenHex()` applied |
+| `engines` field in package.json | `"node": ">=20"` |
+
+## Theme Mapping
+
+### Final Theme Table: memd --theme -> Shiki theme -> beautiful-mermaid theme
+
+| memd --theme | Shiki built-in theme | beautiful-mermaid theme | Notes |
+|---|---|---|---|
+| nord | `nord` | `nord` | Direct match |
+| dracula | `dracula` | `dracula` | Direct match |
+| one-dark | `one-dark-pro` | `one-dark` | Name differs in Shiki |
+| github-dark | `github-dark` | `github-dark` | Direct match |
+| github-light | `github-light` | `github-light` | Direct match |
+| solarized-dark | `solarized-dark` | `solarized-dark` | Direct match |
+| solarized-light | `solarized-light` | `solarized-light` | Direct match |
+| catppuccin-mocha | `catppuccin-mocha` | `catppuccin-mocha` | Direct match |
+| catppuccin-latte | `catppuccin-latte` | `catppuccin-latte` | Direct match |
+| tokyo-night | `tokyo-night` | `tokyo-night` | Direct match |
+| tokyo-night-storm | `tokyo-night` | `tokyo-night-storm` | Shiki has no storm variant; use base `tokyo-night` (difference is bg only) |
+| tokyo-night-light | `one-light` | `tokyo-night-light` | Shiki has no light variant; `one-light` is closest |
+| nord-light | `everforest-light` | `nord-light` | Shiki has no nord-light; `everforest-light` has similar soft palette |
+| zinc-dark | `min-dark` | `zinc-dark` | Neutral/minimal dark |
+| zinc-light | `min-light` | `zinc-light` | Neutral/minimal light |
+
+All 15 memd themes are preserved. Diagram colors always use beautiful-mermaid built-in themes (high quality, hand-tuned). Syntax highlighting uses the nearest Shiki built-in theme.
+
+## Detailed Implementation
+
+### Step 1: Install Shiki and update package.json
+
+```bash
+pnpm add shiki
+pnpm remove cli-highlight
+```
+
+Add `engines` field to package.json:
+```json
+{
+  "engines": {
+    "node": ">=20"
+  }
+}
+```
+
+### Step 2: Replace imports in main.js
+
+**Remove** (line 6):
+```javascript
+import { highlight, supportsLanguage, plain } from 'cli-highlight';
+```
+
+**Add** (after existing imports):
+```javascript
+import { createHighlighterCoreSync } from 'shiki/core';
+import { createJavaScriptRegexEngine } from 'shiki/engine/javascript';
+
+// Shiki themes (individual default imports for tree-shaking)
+import themeNord from '@shikijs/themes/nord';
+import themeDracula from '@shikijs/themes/dracula';
+import themeOneDarkPro from '@shikijs/themes/one-dark-pro';
+import themeGithubDark from '@shikijs/themes/github-dark';
+import themeGithubLight from '@shikijs/themes/github-light';
+import themeSolarizedDark from '@shikijs/themes/solarized-dark';
+import themeSolarizedLight from '@shikijs/themes/solarized-light';
+import themeCatppuccinMocha from '@shikijs/themes/catppuccin-mocha';
+import themeCatppuccinLatte from '@shikijs/themes/catppuccin-latte';
+import themeTokyoNight from '@shikijs/themes/tokyo-night';
+import themeOneLight from '@shikijs/themes/one-light';
+import themeEverforestLight from '@shikijs/themes/everforest-light';
+import themeMinDark from '@shikijs/themes/min-dark';
+import themeMinLight from '@shikijs/themes/min-light';
+
+// Shiki languages (top 19 for >95% real-world coverage)
+// Note: @shikijs/langs/bash exports { name: 'shellscript', aliases: ['bash', 'sh', 'shell', 'zsh'] }.
+// getLoadedLanguages() includes all aliases, so 'bash', 'js', 'ts', 'py' etc. all resolve automatically.
+import langJavascript from '@shikijs/langs/javascript';
+import langTypescript from '@shikijs/langs/typescript';
+import langPython from '@shikijs/langs/python';
+import langBash from '@shikijs/langs/bash';
+import langGo from '@shikijs/langs/go';
+import langRust from '@shikijs/langs/rust';
+import langJava from '@shikijs/langs/java';
+import langC from '@shikijs/langs/c';
+import langCpp from '@shikijs/langs/cpp';
+import langRuby from '@shikijs/langs/ruby';
+import langPhp from '@shikijs/langs/php';
+import langHtml from '@shikijs/langs/html';
+import langCss from '@shikijs/langs/css';
+import langJson from '@shikijs/langs/json';
+import langYaml from '@shikijs/langs/yaml';
+import langToml from '@shikijs/langs/toml';
+import langSql from '@shikijs/langs/sql';
+import langMarkdown from '@shikijs/langs/markdown';
+import langDiff from '@shikijs/langs/diff';
+```
+
+### Step 3: Create Shiki highlighter singleton (lazy)
+
+Place this after imports, at module level. The highlighter is created lazily on first
+call to `getHighlighter()`, so `--version` and `--help` skip the initialization cost.
+
+```javascript
+// All Shiki themes used by memd
+const SHIKI_THEMES = [
+  themeNord, themeDracula, themeOneDarkPro,
+  themeGithubDark, themeGithubLight,
+  themeSolarizedDark, themeSolarizedLight,
+  themeCatppuccinMocha, themeCatppuccinLatte,
+  themeTokyoNight, themeOneLight,
+  themeEverforestLight, themeMinDark, themeMinLight,
+];
+
+// All languages pre-loaded (19 languages)
+const SHIKI_LANGS = [
+  langJavascript, langTypescript, langPython, langBash,
+  langGo, langRust, langJava, langC, langCpp,
+  langRuby, langPhp, langHtml, langCss, langJson,
+  langYaml, langToml, langSql, langMarkdown, langDiff,
+];
+
+let _highlighter;
+function getHighlighter() {
+  if (!_highlighter) {
+    _highlighter = createHighlighterCoreSync({
+      themes: SHIKI_THEMES,
+      langs: SHIKI_LANGS,
+      engine: createJavaScriptRegexEngine(),
+    });
+  }
+  return _highlighter;
+}
+```
+
+### Step 4: Implement THEME_MAP and THEME_NAMES
+
+```javascript
+// Maps memd theme name -> { shikiTheme: string (Shiki theme ID), mermaidTheme: string }
+// shikiTheme: used for syntax highlighting + markdown style extraction
+// mermaidTheme: key into MERMAID_THEMES for diagram colors
+const THEME_MAP = {
+  'nord':              { shikiTheme: 'nord',              mermaidTheme: 'nord' },
+  'dracula':           { shikiTheme: 'dracula',           mermaidTheme: 'dracula' },
+  'one-dark':          { shikiTheme: 'one-dark-pro',      mermaidTheme: 'one-dark' },
+  'github-dark':       { shikiTheme: 'github-dark',       mermaidTheme: 'github-dark' },
+  'github-light':      { shikiTheme: 'github-light',      mermaidTheme: 'github-light' },
+  'solarized-dark':    { shikiTheme: 'solarized-dark',    mermaidTheme: 'solarized-dark' },
+  'solarized-light':   { shikiTheme: 'solarized-light',   mermaidTheme: 'solarized-light' },
+  'catppuccin-mocha':  { shikiTheme: 'catppuccin-mocha',  mermaidTheme: 'catppuccin-mocha' },
+  'catppuccin-latte':  { shikiTheme: 'catppuccin-latte',  mermaidTheme: 'catppuccin-latte' },
+  'tokyo-night':       { shikiTheme: 'tokyo-night',       mermaidTheme: 'tokyo-night' },
+  'tokyo-night-storm': { shikiTheme: 'tokyo-night',       mermaidTheme: 'tokyo-night-storm' },
+  'tokyo-night-light': { shikiTheme: 'one-light',         mermaidTheme: 'tokyo-night-light' },
+  'nord-light':        { shikiTheme: 'everforest-light',   mermaidTheme: 'nord-light' },
+  'zinc-dark':         { shikiTheme: 'min-dark',           mermaidTheme: 'zinc-dark' },
+  'zinc-light':        { shikiTheme: 'min-light',          mermaidTheme: 'zinc-light' },
+};
+
+// Single source of truth for available theme names (used in --help and validation)
+const THEME_NAMES = Object.keys(THEME_MAP);
+```
+
+### Step 5: Implement softenHex() and tokensToAnsi()
+
+```javascript
+// Gentle desaturation by blending toward neutral gray (#808080) in sRGB space.
+// Reuses the same linear interpolation approach as mixHex() -- no HSL conversion needed.
+// amount=0.15 means 15% toward gray. Replaces the old mute() (HSL-based) with a simpler,
+// more predictable sRGB blend that avoids hue shifts from HSL rounding.
+function softenHex(hex, amount = 0.15) {
+  const parse = (h, o) => parseInt(h.slice(o, o + 2), 16);
+  const mix = (c, gray) => Math.round(c * (1 - amount) + gray * amount);
+  const toHex = x => x.toString(16).padStart(2, '0');
+  const r = mix(parse(hex, 1), 128);
+  const g = mix(parse(hex, 3), 128);
+  const b = mix(parse(hex, 5), 128);
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
+function tokensToAnsi(lines) {
+  if (chalk.level === 0) {
+    // --no-color: return plain text without ANSI codes
+    return lines.map(line => line.map(t => t.content).join('')).join('\n');
+  }
+  return lines.map(line =>
+    line.map(token => {
+      if (!token.color) return token.content;
+      const r = parseInt(token.color.slice(1, 3), 16);
+      const g = parseInt(token.color.slice(3, 5), 16);
+      const b = parseInt(token.color.slice(5, 7), 16);
+      return `\x1b[38;2;${r};${g};${b}m${token.content}\x1b[39m`;
+    }).join('')
+  ).join('\n');
+}
+```
+
+### Step 6: Implement highlightWithShiki()
+
+```javascript
+function highlightWithShiki(code, lang, shikiThemeName) {
+  // getLoadedLanguages() includes all aliases (e.g. 'js', 'ts', 'bash', 'py', 'yml'),
+  // so no manual LANG_ALIASES map is needed.
+  const hl = getHighlighter();
+  const loadedLangs = hl.getLoadedLanguages();
+  const effectiveLang = loadedLangs.includes(lang) ? lang : 'text';
+
+  if (effectiveLang === 'text') {
+    // Plain text: no tokenization needed
+    return code;
+  }
+
+  const tokens = hl.codeToTokensBase(code, {
+    lang: effectiveLang,
+    theme: shikiThemeName,
+  });
+  return tokensToAnsi(tokens);
+}
+```
+
+Note: `codeToTokensBase` returns `ThemedToken[][]` (array of lines, each line is array of tokens with `{ content, color }`).
+
+### Step 7: Implement extractMarkdownStyle()
+
+Extracts colors from Shiki theme's `settings` array (Shiki v4 normalizes TextMate `tokenColors` into `settings`) for marked-terminal options. Colors are softened via `softenHex()` to avoid overly saturated output in terminal.
+
+```javascript
+function extractMarkdownStyle(shikiThemeName) {
+  const theme = getHighlighter().getTheme(shikiThemeName);
+
+  const findColor = (...scopes) => {
+    for (const scope of scopes) {
+      const setting = theme.settings?.find(s => {
+        if (!s.scope) return false;
+        const scopeList = Array.isArray(s.scope) ? s.scope : [s.scope];
+        return scopeList.some(sc => sc === scope || sc.startsWith(scope + '.'));
+      });
+      if (setting?.settings?.foreground) return setting.settings.foreground;
+    }
+    return theme.fg;
+  };
+
+  const accent = softenHex(findColor('entity.name.function', 'support.function', 'keyword'));
+  const string = softenHex(findColor('string', 'string.quoted'));
+  const comment = softenHex(findColor('comment', 'punctuation.definition.comment'));
+  const type = softenHex(findColor('entity.name.type', 'support.type', 'storage.type'));
+  const param = softenHex(findColor('variable.parameter', 'variable.other', 'entity.name.tag'));
+  const fg = theme.fg;
+
+  return {
+    firstHeading: chalk.hex(accent).underline.bold,
+    heading:      chalk.hex(accent).bold,
+    code:         chalk.hex(string),
+    codespan:     chalk.hex(string),
+    blockquote:   chalk.hex(comment).italic,
+    strong:       chalk.hex(fg).bold,
+    em:           chalk.hex(param).italic,
+    del:          chalk.hex(comment).strikethrough,
+    link:         chalk.hex(type),
+    href:         chalk.hex(type).underline,
+  };
+}
+```
+
+### Step 8: Rewire main.js terminal path (action function)
+
+Replace the terminal path code inside the `action` callback (main.js lines 451-525).
+
+**Before** (current code, lines 460-515):
+```javascript
+const shouldHighlight = useColor;
+const selectedTheme = resolveTerminalTheme(options.theme, diagramColors);
+const highlightOptions = shouldHighlight
+  ? {
+      ignoreIllegals: true,
+      ...(selectedTheme.highlight ? { theme: selectedTheme.highlight } : {}),
+    }
+  : undefined;
+
+marked.use(markedTerminal({
+  reflowText: true,
+  width: options.width ?? process.stdout.columns ?? 80,
+  ...selectedTheme.markdown,
+}, highlightOptions));
+
+// ... link renderer override ...
+
+if (!shouldHighlight) {
+  marked.use({ renderer: { code(token) { ... } } });
+}
+
+// ... console.error suppression hack ...
+const origConsoleError = console.error;
+for (const markdown of markdownParts) {
+  const processed = convertMermaidToAscii(markdown, { ... });
+  console.error = () => {};
+  parts.push(marked.parse(processed));
+  console.error = origConsoleError;
+}
+```
+
+**After** (new code):
+```javascript
+// themeEntry is already declared in Step 10 (action scope, before if/else)
+const shikiThemeName = themeEntry.shikiTheme;
+
+// Extract markdown element styling from Shiki theme (with softenHex desaturation)
+const markdownStyle = extractMarkdownStyle(shikiThemeName);
+
+// Pass null for highlightOptions to marked-terminal.
+// Note: marked-terminal internally converts null to {} and would still call
+// cli-highlight, but the code renderer override below intercepts all code
+// blocks before marked-terminal's internal highlight function is reached.
+marked.use(markedTerminal({
+  reflowText: true,
+  width: options.width ?? process.stdout.columns ?? 80,
+  ...markdownStyle,
+}, null));
+
+// Override link renderer (unchanged)
+marked.use({
+  renderer: {
+    link(token) {
+      return token.text + (token.text !== token.href ? ` (${token.href})` : '');
+    }
+  }
+});
+
+// Override code renderer to use Shiki instead of cli-highlight.
+// This marked.use() call MUST come after markedTerminal() so that it takes
+// precedence over marked-terminal's internal code renderer (marked v17+
+// applies later overrides first).
+marked.use({
+  renderer: {
+    code(token) {
+      const lang = token.lang || '';
+      const code = typeof token === 'string' ? token : (token.text || token);
+      const highlighted = highlightWithShiki(String(code), lang, shikiThemeName);
+      const lines = highlighted.split('\n');
+      const indented = lines.map(line => '    ' + line).join('\n');
+      return indented + '\n';
+    }
+  }
+});
+
+// Convert DiagramColors to AsciiTheme for terminal rendering
+const asciiTheme = diagramColorsToAsciiTheme(diagramColors);
+const colorMode = useColor ? undefined : 'none';
+
+const parts = [];
+// No more console.error suppression needed (highlight.js is gone)
+for (const markdown of markdownParts) {
+  const processed = convertMermaidToAscii(markdown, {
+    useAscii: options.ascii,
+    colorMode,
+    theme: asciiTheme,
+  });
+  parts.push(marked.parse(processed));
+}
+```
+
+Key changes:
+- `resolveTerminalTheme()` replaced by `THEME_MAP` lookup + `extractMarkdownStyle()`
+- `highlightOptions` passed as `null` to `markedTerminal()` (cli-highlight never reached due to code renderer override)
+- Code renderer always overridden (uses Shiki for color, respects `chalk.level === 0` via `tokensToAnsi()`)
+- `console.error` suppression hack removed entirely
+
+### Step 9: Remove dead code from main.js
+
+Delete these functions and constants (in order of appearance):
+
+| Lines | Item |
+|-------|------|
+| 19-37 | `hexToHsl()` |
+| 39-61 | `hslToHex()` |
+| 64-69 | `mute()` |
+| 88-133 | `buildTheme()` |
+| 136-172 | `TERMINAL_THEMES` |
+| 175-193 | `buildMarkdownFromDiagramColors()` |
+| 195-197 | `resolveTerminalTheme()` |
+| 230-234 | `resolveDiagramTheme()` |
+
+Also remove the `cli-highlight` import line (line 6).
+
+### Step 10: Unify theme validation via THEME_MAP
+
+Replace the current `resolveDiagramTheme()` call in the action callback with unified `THEME_MAP` validation. This single check serves both HTML and terminal paths:
+
+```javascript
+// In action callback, replace:
+//   diagramColors = resolveDiagramTheme(options.theme);
+// With:
+if (!(options.theme in THEME_MAP)) {
+  const names = Object.keys(THEME_MAP).join(', ');
+  console.error(`Unknown theme: ${options.theme}\nAvailable themes: ${names}`);
+  process.exit(1);
+}
+const themeEntry = THEME_MAP[options.theme];
+const diagramColors = MERMAID_THEMES[themeEntry.mermaidTheme];
+if (!diagramColors) {
+  console.error(`Internal error: mermaid theme '${themeEntry.mermaidTheme}' not found in beautiful-mermaid`);
+  process.exit(1);
+}
+```
+
+This replaces `resolveDiagramTheme()` entirely. Both paths then use `diagramColors` directly:
+- **HTML path**: `renderToHTML(combined, diagramColors)` -- unchanged
+- **Terminal path**: `themeEntry.shikiTheme` for Shiki, `diagramColors` for ASCII diagrams
+
+### Step 11: Update tests
+
+**test/memd.test.js changes:**
+
+1. **Update `--no-color strips ANSI from all highlight themes` test** (lines 285-298):
+   - Currently tests only 5 hand-crafted themes: `dracula, one-dark, github-dark, solarized-dark, nord`
+   - Expand to test all 15 themes since Shiki provides highlighting for all
+
+```javascript
+describe('--no-color strips ANSI from all themes', () => {
+  const themes = [
+    'nord', 'dracula', 'one-dark', 'github-dark', 'github-light',
+    'solarized-dark', 'solarized-light', 'catppuccin-mocha', 'catppuccin-latte',
+    'tokyo-night', 'tokyo-night-storm', 'tokyo-night-light',
+    'nord-light', 'zinc-dark', 'zinc-light',
+  ];
+
+  for (const theme of themes) {
+    it(`--theme ${theme} --no-color has no ANSI codes`, async () => {
+      const output = await run(
+        ['--no-pager', '--no-color', '--theme', theme, 'test/test-highlight.md'],
+        { waitFor: t => t.includes('TypeScript') },
+      );
+      // eslint-disable-next-line no-control-regex
+      expect(output).not.toMatch(/\x1b\[[\d;]*m/);
+    });
+  }
+});
+```
+
+2. **Add Shiki highlighting test** (new):
+```javascript
+it('syntax highlighting produces truecolor ANSI for known languages', async () => {
+  const output = await run(
+    ['--no-pager', '--theme', 'nord', 'test/test-highlight.md'],
+    { waitFor: t => t.includes('TypeScript') },
+  );
+  // Truecolor ANSI escape: ESC[38;2;R;G;Bm
+  // eslint-disable-next-line no-control-regex
+  expect(output).toMatch(/\x1b\[38;2;\d+;\d+;\d+m/);
+});
+```
+
+3. **Add unknown language fallback test** (new):
+```javascript
+it('unknown language falls back to plain text without errors', async () => {
+  const session = await launchTerminal({
+    command: 'sh',
+    args: ['-c', `echo '# Test\n\n\`\`\`unknownlang\nsome code\n\`\`\`' | node ${MAIN} --no-pager --no-color`],
+    cols: 80,
+    rows: 10,
+    waitForData: false,
+  });
+  const output = (await session.text({
+    waitFor: t => t.includes('some code'),
+    timeout: 8000,
+  })).trim();
+  expect(output).toContain('some code');
+  // No error output expected
+  expect(output).not.toContain('Error');
+  expect(output).not.toContain('Could not find the language');
+});
+```
+
+4. **Add cli-highlight bypass verification test** (new):
+```javascript
+it('cli-highlight is not invoked (no highlight.js errors in output)', async () => {
+  // Use a language that highlight.js would warn about but Shiki handles gracefully
+  const session = await launchTerminal({
+    command: 'sh',
+    args: ['-c', `echo '# Test\n\n\`\`\`rust\nfn main() {}\n\`\`\`' | node ${MAIN} --no-pager`],
+    cols: 80,
+    rows: 10,
+    waitForData: false,
+  });
+  const output = (await session.text({
+    waitFor: t => t.includes('fn main'),
+    timeout: 8000,
+  })).trim();
+  expect(output).toContain('fn main');
+  expect(output).not.toContain('Could not find the language');
+});
+```
+
+5. **Existing tests that should pass without changes:**
+   - `--version`, `--help`, basic rendering tests (test1.md, test2.md, test-br.md, test-cjk.md)
+   - HTML path tests (no changes to HTML rendering)
+   - Terminal theme render tests (dracula, tokyo-night, one-dark, nonexistent, default nord)
+   - `--no-color strips ANSI` test (line 85-92)
+   - stdin test
+
+### Step 12: Update README.md theme list
+
+The theme list in README.md (lines 31-34) should remain unchanged since all 15 themes are preserved. No action needed unless the order or formatting changes.
+
+## Dependency Changes
+
+### package.json (after)
+
+```json
+{
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "beautiful-mermaid": "^1.1.2",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "marked": "^17.0.3",
+    "marked-terminal": "^7.3.0",
+    "shiki": "^4.0.0"
+  }
+}
+```
+
+- **Added**: `shiki` (its `dependencies` include `@shikijs/themes`, `@shikijs/langs`, `@shikijs/engine-javascript`, `@shikijs/core`, `@shikijs/types` -- all automatically installed by `pnpm add shiki`)
+- **Removed**: `cli-highlight` (remains as transitive dependency of `marked-terminal`, but memd code no longer imports it)
+- **Unchanged**: `beautiful-mermaid`, `chalk`, `commander`, `marked`, `marked-terminal`
+
+## File-level Diff Summary
+
+### main.js
+
+```
+ REMOVE  import { highlight, supportsLanguage, plain } from 'cli-highlight'
+ ADD     import { createHighlighterCoreSync } from 'shiki/core'
+ ADD     import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
+ ADD     import themeNord from '@shikijs/themes/nord'              (x14 themes)
+ ADD     import langJavascript from '@shikijs/langs/javascript'    (x19 langs)
+ REMOVE  hexToHsl()           (lines 19-37)
+ REMOVE  hslToHex()           (lines 39-61)
+ REMOVE  mute()               (lines 64-69)
+ REMOVE  buildTheme()         (lines 88-133)
+ REMOVE  TERMINAL_THEMES      (lines 136-172)
+ REMOVE  buildMarkdownFromDiagramColors()  (lines 175-193)
+ REMOVE  resolveTerminalTheme()            (lines 195-197)
+ REMOVE  resolveDiagramTheme()             (lines 230-234)
+ ADD     getHighlighter() lazy singleton (createHighlighterCoreSync)
+ ADD     THEME_MAP
+ ADD     THEME_NAMES = Object.keys(THEME_MAP)
+ ADD     softenHex()
+ ADD     tokensToAnsi()
+ ADD     highlightWithShiki()
+ ADD     extractMarkdownStyle()
+ MODIFY  action: unified theme validation via THEME_MAP (replaces resolveDiagramTheme)
+ MODIFY  action: markedTerminal() with extractMarkdownStyle() + null highlightOptions
+ MODIFY  action: code renderer always uses Shiki (override after markedTerminal)
+ REMOVE  action: console.error suppression hack
+ KEEP    mixHex(), MIX, diagramColorsToAsciiTheme(), resolveThemeColors()
+ KEEP    escapeHtml(), readMarkdownFile(), convertMermaidToAscii(), convertMermaidToSVG()
+ KEEP    renderToHTML(), readStdin(), shouldUsePager(), spawnPager()
+```
+
+### package.json
+
+```
+ ADD     "engines": { "node": ">=20" }
+ ADD     "shiki": "^4.0.0"
+ REMOVE  "cli-highlight": "^2.1.11"
+```
+
+### test/memd.test.js
+
+```
+ MODIFY  --no-color theme loop: expand from 5 themes to 15 themes
+ ADD     truecolor ANSI test (Shiki produces ESC[38;2;R;G;Bm)
+ ADD     unknown language fallback test
+ ADD     cli-highlight bypass verification test
+ KEEP    all other existing tests
+```
+
+## Implementation Order
+
+1. `pnpm add shiki && pnpm remove cli-highlight`
+2. Add `"engines": { "node": ">=20" }` to package.json
+3. Replace imports in main.js (remove cli-highlight, add Shiki)
+4. Add highlighter lazy singleton + THEME_MAP + THEME_NAMES at module level
+5. Add `softenHex()`, `tokensToAnsi()`, `highlightWithShiki()`, `extractMarkdownStyle()`
+6. Rewire action: unified THEME_MAP validation (replaces resolveDiagramTheme), markedTerminal with null, code renderer with Shiki
+7. Remove dead code: hexToHsl, hslToHex, mute, buildTheme, TERMINAL_THEMES, buildMarkdownFromDiagramColors, resolveTerminalTheme, resolveDiagramTheme, console.error hack
+8. Run existing tests: `pnpm test`
+9. Update tests (expand --no-color loop, add Shiki-specific tests, add bypass test)
+10. Manual verification: `node main.js test/test-highlight.md` with several themes
+
+## Risk Assessment
+
+| Risk | Likelihood | Mitigation |
+|------|-----------|------------|
+| Shiki startup time slows CLI | Low | Lazy init via `getHighlighter()`: only pays cost when rendering (not for --version/--help). Estimated 100-300ms on first render call. |
+| Package size increase | Low | shiki ~10MB vs cli-highlight ~8MB (with highlight.js). Same order. Tree-shaking via individual imports. |
+| Code renderer override not intercepting all code blocks | Low | marked v17+ applies later `marked.use()` overrides first. Code renderer MUST be registered after `markedTerminal()`. Verified by cli-highlight bypass test. |
+| `codeToTokensBase()` API differs from plan | Low | Verified in Shiki v4.0.2 docs. Sync API via `createHighlighterCoreSync()`. |
+| Language aliases not resolved | Very Low | Confirmed: `getLoadedLanguages()` includes all aliases (js, ts, bash, py, yml, etc.). No manual alias map needed. |
+| `extractMarkdownStyle()` returns wrong colors for some themes | Low | Test all 15 themes visually. Token scopes are standard TextMate scopes. `softenHex()` prevents overly saturated output. |
+| `softenHex()` amount too strong/weak | Low | Default `amount=0.15` is conservative. sRGB blend is more predictable than HSL mute (no hue shifts). Tune after visual testing. |
+
+## Scope Exclusions
+
+- HTML path: unchanged (uses `new Marked()` without syntax highlighting; confirmed no cli-highlight usage)
+- Diagram rendering: unchanged (beautiful-mermaid)
+- Pager logic: unchanged
+- `--ascii` option: unchanged
+- stdin/file reading: unchanged