@dr-ishaan/rehype-perfect-code-blocks 2.0.0 → 2.1.0

package/dist/types.d.ts

@@ -114,6 +114,21 @@ export interface PerfectCodeOptions {
             themes: string[];
             langs: string[];
         }) => Promise<unknown>;
+        /**
+         * v2.1.0: Lazy initialization — don't load Shiki until the first code block
+         * is encountered. On pages with no code blocks, Shiki (and its WASM engine)
+         * is never loaded, saving ~1MB of bundle.
+         *
+         * Default: false (Shiki initializes eagerly, same as v1.x/v2.0)
+         */
+        lazy?: boolean;
+        /**
+         * v2.1.0: Languages to preload when lazy is true. Only loaded if the
+         * document contains at least one code block.
+         *
+         * Default: ['typescript', 'bash', 'javascript', 'json', 'html', 'css']
+         */
+        preloadLangs?: string[];
         [key: string]: unknown;
     };
     /**
@@ -474,6 +489,44 @@ export interface PerfectCodeOptions {
      * Default: `undefined` (no scoping; CSS applies everywhere)
      */
     scope?: string;
+    /**
+     * Math/LaTeX rendering via KaTeX. When enabled, the plugin intercepts:
+     *   - Inline math: `$...$` in text (when `math.inline` is true)
+     *   - Block math: `$$...$$` blocks (when `math.block` is true)
+     *   - Fenced code blocks with language `math`, `latex`, or `tex`
+     *
+     * KaTeX renders at build time (server-side) — no client-side JS needed.
+     * The KaTeX CSS + fonts must be loaded on the client (the plugin injects
+     * a `<link>` to KaTeX CSS if `math.injectCss` is true).
+     *
+     * `katex` must be installed: `npm install katex`
+     *
+     * Default: `undefined` (no math rendering; `$...$` renders as literal text)
+     */
+    math?: {
+        /** Math engine. 'katex' renders via KaTeX (must be installed). Default: 'none' */
+        engine?: 'katex' | 'none';
+        /** Render inline `$...$` math. Default: true */
+        inline?: boolean;
+        /** Render block `$$...$$` and ```math blocks. Default: true */
+        block?: boolean;
+        /** Inject KaTeX CSS alongside plugin CSS. Default: true */
+        injectCss?: boolean;
+        /** Don't crash on invalid LaTeX — render the source as-is. Default: true */
+        throwOnError?: boolean;
+        /** Allow non-standard LaTeX commands. Default: false */
+        strict?: boolean | 'ignore' | 'error' | 'warn';
+    };
+    /**
+     * Emit warnings to the logger during build/dev for common misconfigurations:
+     *   - Unknown language not loaded in Shiki
+     *   - Invalid meta syntax (e.g., `{1,a-5}` instead of `{1,3-5}`)
+     *   - Conflicting options (e.g., `wrap` + `collapseAfter` both enabled)
+     *   - Code block inside raw HTML detected but rehype-raw not installed
+     *
+     * Default: true in development (when `NODE_ENV !== 'production'`), false in production.
+     */
+    devWarnings?: boolean;
     /** Also style inline `code` cosmetically (no tokenization). Default: false */
     inline?: boolean;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dr-ishaan/rehype-perfect-code-blocks",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Beautiful, configurable code blocks for Astro / MDX / any rehype pipeline. Built on Shiki, inspired by rehype-pretty-code, VitePress, Docusaurus, and Expressive Code.",
   "type": "module",
   "main": "./dist/index.js",
@@ -51,7 +51,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json && cp src/styles.css dist/styles.css",
     "dev": "tsc -p tsconfig.json --watch",
-    "test": "node test-meta-parser.mjs && node test-dom-structure.mjs && node test-options.mjs && node test-notations.mjs && node test-security.mjs && node test-integration.mjs && node test-regression.mjs && node test-css.mjs && node test-edge-cases.mjs && node stress-tests.mjs && node new-feature-tests.mjs && node test-issue-12.mjs && node test-issue-11.mjs && node test-architecture-patterns.mjs && node test-copy-button-fix.mjs && node test-tailwind-compat.mjs && node test-v2-css-architecture.mjs",
+    "test": "node test-meta-parser.mjs && node test-dom-structure.mjs && node test-options.mjs && node test-notations.mjs && node test-security.mjs && node test-integration.mjs && node test-regression.mjs && node test-css.mjs && node test-edge-cases.mjs && node stress-tests.mjs && node new-feature-tests.mjs && node test-issue-12.mjs && node test-issue-11.mjs && node test-architecture-patterns.mjs && node test-copy-button-fix.mjs && node test-tailwind-compat.mjs && node test-v2-css-architecture.mjs && node test-v2-phase2.mjs",
     "prepublishOnly": "npm run build && npm test",
     "prepack": "npm run build"
   },

package/src/copy-script.ts

@@ -103,6 +103,9 @@ export const COPY_SCRIPT = `
     var finish = function () {
       btn.classList.add('pcb__copy--done');
       if (label) label.textContent = done;
+      // v2.1.0: Update aria-label for screen readers — announce "copied" state
+      var originalAriaLabel = btn.getAttribute('aria-label') || 'Copy code';
+      btn.setAttribute('aria-label', done + ' — ' + originalAriaLabel);
       if (successIconHtml && icon) {
         var tmp = document.createElement('span');
         tmp.innerHTML = successIconHtml;
@@ -116,6 +119,8 @@ export const COPY_SCRIPT = `
       setTimeout(function () {
         btn.classList.remove('pcb__copy--done');
         if (label && originalLabel != null) label.textContent = originalLabel;
+        // v2.1.0: Restore original aria-label after feedback duration
+        btn.setAttribute('aria-label', originalAriaLabel);
         if (originalIconHtml && icon) {
           var tmp2 = document.createElement('span');
           tmp2.innerHTML = originalIconHtml;

package/src/dev-warnings.ts

@@ -0,0 +1,125 @@
+/**
+ * Development warnings (v2.1.0).
+ *
+ * Emits warnings to the logger during build/dev for common misconfigurations:
+ *   - Unknown language not loaded in Shiki
+ *   - Invalid meta syntax (e.g., `{1,a-5}` instead of `{1,3-5}`)
+ *   - Conflicting options (e.g., `wrap` + `collapseAfter` both enabled)
+ *   - Code block inside raw HTML detected but rehype-raw not installed
+ *
+ * Warnings are emitted once per unique message (deduped) to avoid spam.
+ */
+
+import type { Element, Root } from 'hast';
+import { visit } from 'unist-util-visit';
+
+export interface DevWarningContext {
+  logger: { warn: (msg: string) => void; error: (msg: string) => void };
+  hasRehypeRaw: boolean;
+  wrap: boolean;
+  collapseAfter: number | null;
+}
+
+const warnedMessages = new Set<string>();
+
+function warnOnce(ctx: DevWarningContext, msg: string): void {
+  if (warnedMessages.has(msg)) return;
+  warnedMessages.add(msg);
+  ctx.logger.warn(msg);
+}
+
+/**
+ * Check for common misconfigurations and emit dev warnings.
+ * Call this once per document after the plugin has processed the tree.
+ */
+export function runDevWarnings(tree: Root, ctx: DevWarningContext): void {
+  // 1. Check for conflicting options
+  if (ctx.wrap && ctx.collapseAfter !== null) {
+    warnOnce(
+      ctx,
+      '[rehype-perfect-code-blocks] Both `wrap` and `collapseAfter` are enabled. ' +
+        'Collapsed blocks may not wrap correctly. Consider disabling one.'
+    );
+  }
+
+  // 2. Check for code blocks inside raw HTML without rehype-raw
+  if (!ctx.hasRehypeRaw) {
+    let foundRawHtmlAroundCode = false;
+    visit(tree, 'element', (node: Element) => {
+      if (foundRawHtmlAroundCode) return;
+      // Look for <pre> elements that are children of raw HTML elements
+      // like <details>, <div> with class containing "card", etc.
+      // This is a heuristic — we can't perfectly detect raw HTML vs markdown HTML.
+      if (
+        node.tagName === 'details' ||
+        (node.tagName === 'div' && node.properties?.className &&
+         Array.isArray(node.properties.className) &&
+         node.properties.className.some((c: unknown) =>
+           typeof c === 'string' && (c.includes('card') || c.includes('container'))
+         ))
+      ) {
+        const hasPre = node.children?.some(
+          (c) => c.type === 'element' && c.tagName === 'pre'
+        );
+        if (hasPre) foundRawHtmlAroundCode = true;
+      }
+    });
+    if (foundRawHtmlAroundCode) {
+      warnOnce(
+        ctx,
+        '[rehype-perfect-code-blocks] Code block inside raw HTML detected but rehype-raw ' +
+          'does not appear to be installed. Code blocks inside <details>, <div class="card">, ' +
+          'etc. may not render correctly. Add rehype-raw to your pipeline: ' +
+          'npm install rehype-raw'
+      );
+    }
+  }
+
+  // 3. Check for unknown/invalid meta syntax
+  visit(tree, 'element', (node: Element) => {
+    if (node.tagName !== 'pre') return;
+    const codeEl = node.children?.find(
+      (c): c is Element => c.type === 'element' && c.tagName === 'code'
+    );
+    if (!codeEl) return;
+    const meta = (codeEl.properties?.dataMeta as string | undefined) ??
+      (node.properties?.dataMeta as string | undefined) ?? '';
+    if (!meta) return;
+
+    // Check for invalid range syntax like {1,a-5} or {1-}
+    const rangeMatch = meta.match(/\{([^}]*)\}/g);
+    if (rangeMatch) {
+      for (const range of rangeMatch) {
+        const inside = range.slice(1, -1);
+        // Valid: digits, commas, hyphens, spaces, #id, /word/
+        // Invalid: letters (except in /word/ or "phrase"), other punctuation
+        if (!/^[\d\s,/-]+$/.test(inside) && !inside.includes('"') && !inside.includes('/')) {
+          warnOnce(
+            ctx,
+            `[rehype-perfect-code-blocks] Invalid meta syntax: "${range}" in "${meta}". ` +
+              'Expected format like {1,3-5} for line highlighting.'
+          );
+        }
+      }
+    }
+  });
+}
+
+/**
+ * Warn about an unknown language that Shiki couldn't load.
+ * Called from shiki.ts when a language fails to tokenize.
+ */
+export function warnUnknownLanguage(lang: string, ctx: DevWarningContext): void {
+  warnOnce(
+    ctx,
+    `[rehype-perfect-code-blocks] Unknown language "${lang}" — not loaded in Shiki. ` +
+      'Falling back to plaintext. Add it to `shiki.langs` or install the grammar.'
+  );
+}
+
+/**
+ * Reset the warning dedup set (for testing).
+ */
+export function resetWarningDedup(): void {
+  warnedMessages.clear();
+}

package/src/index.ts

@@ -26,13 +26,18 @@ import { wordDiff, hasChanges } from './word-diff.js';
 import type { DiffToken } from './word-diff.js';
 import { generateTokenStyles, applyScopeToCss, generateDarkModeSelector, generateLightModeSelector } from './tokens.js';
 import type { DesignTokens } from './tokens.js';
+import { resolveMathOptions, isMathLanguage, renderMath } from './math.js';
+import type { MathOptions, ResolvedMathOptions } from './math.js';
+import { runDevWarnings, warnUnknownLanguage } from './dev-warnings.js';
 import type { PerfectCodeOptions } from './types.js';
 
 export { remarkPreserveCodeMeta };
 export { disposeHighlighter, runHighlighterTask };
 export { wordDiff, hasChanges };
 export { generateTokenStyles, applyScopeToCss, generateDarkModeSelector, generateLightModeSelector };
-export type { DiffToken, DesignTokens };
+export { resolveMathOptions, isMathLanguage, renderMath };
+export { runDevWarnings, warnUnknownLanguage };
+export type { DiffToken, DesignTokens, MathOptions, ResolvedMathOptions };
 
 export const rehypePerfectCodeBlocks: Plugin<[PerfectCodeOptions?], Root> =
   (options = {}) => {
@@ -166,6 +171,9 @@ function resolveDefaults(opts: PerfectCodeOptions): Required<PerfectCodeOptions>
     tokens: opts.tokens ?? (undefined as unknown as NonNullable<typeof opts.tokens>),
     darkMode: opts.darkMode ?? (undefined as unknown as NonNullable<typeof opts.darkMode>),
     scope: opts.scope ?? (undefined as unknown as string),
+    // v2.1.0: P1 features
+    math: opts.math ?? (undefined as unknown as NonNullable<typeof opts.math>),
+    devWarnings: opts.devWarnings ?? (process.env.NODE_ENV !== 'production'),
     inline: opts.inline ?? false,
   };
 }

package/src/katex.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Minimal type declaration for katex (optional peer dependency).
+ * When katex is installed, its own types take precedence.
+ */
+declare module 'katex' {
+  export interface KatexOptions {
+    displayMode?: boolean;
+    throwOnError?: boolean;
+    strict?: boolean | 'ignore' | 'error' | 'warn';
+    output?: 'html' | 'mathml' | 'htmlAndMathml';
+    [key: string]: unknown;
+  }
+  export function renderToString(latex: string, options?: KatexOptions): string;
+  const _default: { renderToString: typeof renderToString };
+  export default _default;
+}

package/src/math.ts

@@ -0,0 +1,268 @@
+/**
+ * Math/LaTeX rendering via KaTeX (v2.1.0).
+ *
+ * Renders LaTeX at build time (server-side) — no client-side JS needed.
+ * `katex` is an optional peer dependency: if not installed, the plugin
+ * falls back to rendering the LaTeX source as plain text in a styled
+ * container.
+ *
+ * Supports:
+ *   - Inline math: `$...$` in text nodes (via a remark plugin)
+ *   - Block math: `$$...$$` blocks
+ *   - Fenced code blocks with language `math`, `latex`, or `tex`
+ */
+
+export interface MathOptions {
+  engine?: 'katex' | 'none';
+  inline?: boolean;
+  block?: boolean;
+  injectCss?: boolean;
+  throwOnError?: boolean;
+  strict?: boolean | 'ignore' | 'error' | 'warn';
+}
+
+export interface ResolvedMathOptions {
+  engine: 'katex' | 'none';
+  inline: boolean;
+  block: boolean;
+  injectCss: boolean;
+  throwOnError: boolean;
+  strict: boolean | 'ignore' | 'error' | 'warn';
+}
+
+export function resolveMathOptions(math?: MathOptions): ResolvedMathOptions {
+  return {
+    engine: math?.engine ?? 'none',
+    inline: math?.inline ?? true,
+    block: math?.block ?? true,
+    injectCss: math?.injectCss ?? true,
+    throwOnError: math?.throwOnError ?? true,
+    strict: math?.strict ?? false,
+  };
+}
+
+/** Languages that should be rendered as math instead of syntax-highlighted. */
+export const MATH_LANGS = new Set(['math', 'latex', 'tex']);
+
+/** Cache for the dynamically-imported katex module. */
+let _katexModule: typeof import('katex') | null | undefined;
+
+/**
+ * Try to load the katex module. Returns null if katex is not installed.
+ * Caches the result so subsequent calls don't re-import.
+ */
+async function getKatex(): Promise<typeof import('katex') | null> {
+  if (_katexModule !== undefined) return _katexModule;
+  try {
+    _katexModule = await import('katex');
+    return _katexModule;
+  } catch {
+    _katexModule = null;
+    return null;
+  }
+}
+
+/**
+ * Check if a language identifier should be treated as math.
+ */
+export function isMathLanguage(lang: string): boolean {
+  return MATH_LANGS.has(lang.toLowerCase());
+}
+
+/**
+ * Render a LaTeX string to HTML via KaTeX.
+ *
+ * @param latex The LaTeX source string
+ * @param displayMode true for block math ($$...$$), false for inline ($...$)
+ * @param options Resolved math options
+ * @returns { html: string, isKatex: boolean } — if katex is available,
+ *   html is the KaTeX-rendered HTML; otherwise it's the LaTeX source in a
+ *   `<code>` element, and isKatex is false.
+ */
+export async function renderMath(
+  latex: string,
+  displayMode: boolean,
+  options: ResolvedMathOptions
+): Promise<{ html: string; isKatex: boolean }> {
+  if (options.engine === 'none') {
+    return { html: escapeHtml(latex), isKatex: false };
+  }
+
+  const katex = await getKatex();
+  if (!katex) {
+    // KaTeX not installed — fall back to plain text
+    return { html: escapeHtml(latex), isKatex: false };
+  }
+
+  try {
+    const html = katex.renderToString(latex, {
+      displayMode,
+      throwOnError: options.throwOnError,
+      strict: options.strict,
+      output: 'html',
+    });
+    return { html, isKatex: true };
+  } catch {
+    // KaTeX rendering failed — fall back to plain text
+    return { html: escapeHtml(latex), isKatex: false };
+  }
+}
+
+/**
+ * Escape HTML special characters in a string (for the fallback path).
+ */
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Regex to find inline `$...$` math in text.
+ * Matches `$` followed by non-$ content followed by `$`.
+ * Does NOT match `$$` (which is block math) or escaped `\$`.
+ *
+ * Examples:
+ *   "$x^2$" → match (inline math)
+ *   "$$x^2$$" → NO match (block math)
+ *   "cost is \$5" → NO match (escaped dollar sign)
+ *   "a $ b $ c" → match "$ b $" (ambiguous, but we match it)
+ */
+export const INLINE_MATH_REGEX = /(^|[^\\$])\$(?!\$)([^$]+?)\$(?!\$)/g;
+
+/**
+ * Regex to find block `$$...$$` math in text.
+ * Matches `$$` followed by content followed by `$$`.
+ */
+export const BLOCK_MATH_REGEX = /\$\$([\s\S]+?)\$\$/g;
+
+/**
+ * Process a text string, replacing inline `$...$` and block `$$...$$`
+ * with rendered math HTML.
+ *
+ * @param text The input text
+ * @param options Resolved math options
+ * @returns Array of { type: 'text' | 'inline-math' | 'block-math', content: string }
+ *   segments. The caller is responsible for converting these to HAST nodes.
+ */
+export async function processMathInText(
+  text: string,
+  options: ResolvedMathOptions
+): Promise<Array<{ type: 'text' | 'inline-math' | 'block-math'; content: string; html?: string }>> {
+  if (options.engine === 'none' || (!options.inline && !options.block)) {
+    return [{ type: 'text', content: text }];
+  }
+
+  const segments: Array<{ type: 'text' | 'inline-math' | 'block-math'; content: string; html?: string }> = [];
+  let remaining = text;
+
+  // First, extract block math ($$...$$)
+  if (options.block) {
+    let lastIndex = 0;
+    let match: RegExpExecArray | null;
+    const blockRegex = new RegExp(BLOCK_MATH_REGEX);
+    while ((match = blockRegex.exec(remaining)) !== null) {
+      // Text before the block math
+      if (match.index > lastIndex) {
+        const beforeText = remaining.slice(lastIndex, match.index);
+        // Process inline math in the text before
+        if (options.inline) {
+          const inlineSegments = await processInlineMath(beforeText, options);
+          segments.push(...inlineSegments);
+        } else {
+          segments.push({ type: 'text', content: beforeText });
+        }
+      }
+      // The block math
+      const latex = match[1].trim();
+      const { html, isKatex } = await renderMath(latex, true, options);
+      segments.push({ type: 'block-math', content: latex, html });
+      lastIndex = match.index + match[0].length;
+    }
+    // Remaining text after the last block math
+    if (lastIndex < remaining.length) {
+      const afterText = remaining.slice(lastIndex);
+      if (options.inline) {
+        const inlineSegments = await processInlineMath(afterText, options);
+        segments.push(...inlineSegments);
+      } else {
+        segments.push({ type: 'text', content: afterText });
+      }
+    }
+  } else if (options.inline) {
+    // Only inline math
+    const inlineSegments = await processInlineMath(remaining, options);
+    segments.push(...inlineSegments);
+  } else {
+    segments.push({ type: 'text', content: remaining });
+  }
+
+  return segments;
+}
+
+/**
+ * Process inline `$...$` math in a text string.
+ * Returns segments of text and inline-math.
+ */
+async function processInlineMath(
+  text: string,
+  options: ResolvedMathOptions
+): Promise<Array<{ type: 'text' | 'inline-math'; content: string; html?: string }>> {
+  const segments: Array<{ type: 'text' | 'inline-math'; content: string; html?: string }> = [];
+  const regex = new RegExp(INLINE_MATH_REGEX);
+  let lastIndex = 0;
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(text)) !== null) {
+    // Text before the match (including the prefix character)
+    const prefix = match[1] || '';
+    const matchStart = match.index + prefix.length;
+    if (matchStart > lastIndex) {
+      segments.push({ type: 'text', content: text.slice(lastIndex, match.index) + prefix });
+    } else if (prefix) {
+      segments.push({ type: 'text', content: prefix });
+    }
+
+    const latex = match[2].trim();
+    const { html } = await renderMath(latex, false, options);
+    segments.push({ type: 'inline-math', content: latex, html });
+    lastIndex = regex.lastIndex;
+  }
+
+  if (lastIndex < text.length) {
+    segments.push({ type: 'text', content: text.slice(lastIndex) });
+  }
+
+  return segments.length > 0 ? segments : [{ type: 'text', content: text }];
+}
+
+/**
+ * Get the KaTeX CSS path for injection.
+ * Returns the path to `katex/dist/katex.min.css` relative to the project.
+ */
+export function getKatexCssPath(): string {
+  return 'katex/dist/katex.min.css';
+}
+
+/**
+ * Try to read the KaTeX CSS content from the filesystem.
+ * Returns null if katex is not installed or the CSS file can't be read.
+ */
+export async function tryReadKatexCss(): Promise<string | null> {
+  try {
+    const katex = await getKatex();
+    if (!katex) return null;
+    // katex module path — try to read the CSS
+    const { readFileSync } = await import('node:fs');
+    const { createRequire } = await import('node:module');
+    const require = createRequire(import.meta.url);
+    const katexPath = require.resolve('katex');
+    const katexDir = katexPath.replace(/[/\\]katex\.(mjs|js|cjs)$/, '');
+    const cssPath = katexDir + '/katex.min.css';
+    return readFileSync(cssPath, 'utf8');
+  } catch {
+    return null;
+  }
+}

package/src/shiki.ts

@@ -18,6 +18,7 @@ import { fromHtml } from 'hast-util-from-html';
 import { visit } from 'unist-util-visit';
 import type { PerfectCodeOptions } from './types.js';
 import { computeThemeAwareDefaults } from './color-utils.js';
+import { isMathLanguage, renderMath, resolveMathOptions, MATH_LANGS } from './math.js';
 import {
   transformerNotationDiff,
   transformerNotationFocus,
@@ -447,6 +448,50 @@ export async function runShikiOnRawBlocks(
 
   if (targets.length === 0) return;
 
+  // v2.1.0: Handle math language blocks — render via KaTeX instead of Shiki.
+  const mathOpts = resolveMathOptions(opts.math as Record<string, unknown> | undefined);
+  if (mathOpts.engine === 'katex' && mathOpts.block) {
+    const mathTargets: Element[] = [];
+    const codeTargets: Element[] = [];
+    for (const pre of targets) {
+      const code = pre.children.find(
+        (c): c is Element => c.type === 'element' && c.tagName === 'code'
+      );
+      if (!code) { codeTargets.push(pre); continue; }
+      const cls = (code.properties?.className as string[] | undefined) ?? [];
+      const langClass = cls.find((c) => c.startsWith('language-'));
+      const lang = langClass ? langClass.replace('language-', '') : '';
+      if (isMathLanguage(lang)) {
+        mathTargets.push(pre);
+      } else {
+        codeTargets.push(pre);
+      }
+    }
+
+    // Render math blocks via KaTeX
+    for (const pre of mathTargets) {
+      const code = pre.children.find(
+        (c): c is Element => c.type === 'element' && c.tagName === 'code'
+      );
+      if (!code) continue;
+      const text = extractText(code).replace(/\r\n?/g, '\n').trim();
+      const { html, isKatex } = await renderMath(text, true, mathOpts);
+      // Replace the <pre> with rendered math
+      const mathDiv: Element = {
+        type: 'element',
+        tagName: 'div',
+        properties: { className: ['pcb__math', isKatex ? 'pcb__math--katex' : 'pcb__math--fallback'] },
+        children: [{ type: 'text', value: html }],
+      };
+      Object.assign(pre, mathDiv);
+    }
+
+    // Only process non-math targets with Shiki
+    targets.splice(0, targets.length, ...codeTargets);
+  }
+
+  if (targets.length === 0) return;
+
   // Build theme keys — supports single (string), dual ({light,dark}), and
   // multi-theme (Record<string,string> with 3+ entries) for advanced use cases.
   const themeSpec = opts.shiki.theme;
@@ -473,8 +518,16 @@ export async function runShikiOnRawBlocks(
   // (javascript, typescript, python). This matches Shiki's own case-
   // insensitive behavior in codeToHast/codeToHtml, and matches what every
   // other CommonMark renderer accepts. See issue #12.
+  //
+  // v2.1.0: When shiki.lazy is true, don't preload the user's `langs` list —
+  // only load languages that are actually in this document. This avoids
+  // loading grammars for pages that only use 1-2 languages out of a
+  // configured set of 20+. The lazy-load path below will load them on demand.
+  const isLazy = (opts.shiki as { lazy?: boolean }).lazy === true;
   const langSet = new Set<string>(
-    (opts.shiki.langs ?? []).map((l) => l.toLowerCase())
+    isLazy
+      ? []  // Lazy: don't preload anything — document-specific langs added below
+      : (opts.shiki.langs ?? []).map((l) => l.toLowerCase())
   );
   for (const pre of targets) {
     const code = pre.children.find(

package/src/transformer.ts

@@ -247,6 +247,8 @@ export function rehypePerfectCodeBlocks(userOptions: PerfectCodeOptions = {}) {
     tokens: undefined as unknown as NonNullable<PerfectCodeOptions['tokens']>,
     darkMode: undefined as unknown as NonNullable<PerfectCodeOptions['darkMode']>,
     scope: undefined as unknown as string,
+    math: undefined as unknown as NonNullable<PerfectCodeOptions['math']>,
+    devWarnings: process.env.NODE_ENV !== 'production',
     inline: false,
     ...rest,
   };