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

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/meta.ts

@@ -57,6 +57,9 @@ export function parseMeta(meta: string | undefined): ParsedMeta {
     wordHighlights: [],
     lineNumbersStart: null,
     collapseRanges: [],
+    author: null,
+    year: null,
+    source: null,
     flags: {
       wrap: null,
       lineNumbers: null,
@@ -85,6 +88,20 @@ export function parseMeta(meta: string | undefined): ParsedMeta {
       continue;
     }
 
+    // v2.2.0: Attribution metadata — author="...", year="...", source="..."
+    if (tok.startsWith('author=')) {
+      result.author = unquote(tok.slice('author='.length));
+      continue;
+    }
+    if (tok.startsWith('year=')) {
+      result.year = unquote(tok.slice('year='.length));
+      continue;
+    }
+    if (tok.startsWith('source=')) {
+      result.source = unquote(tok.slice('source='.length));
+      continue;
+    }
+
     // collapse="5-12,20-30" — per-line collapsible sections
     if (tok.startsWith('collapse=')) {
       const val = unquote(tok.slice('collapse='.length));
@@ -182,8 +199,8 @@ function tokenize(input: string): string[] {
     while (i < input.length && /\s/.test(input[i])) i++;
     if (i >= input.length) break;
 
-    // Quoted key="value" or key='value' (title=, caption=, collapse=)
-    if (/^(?:title|caption|collapse)=$/.test(input.slice(i).match(/^[a-z]+=/i)?.[0] ?? '')) {
+    // Quoted key="value" or key='value' (title=, caption=, collapse=, author=, year=, source=)
+    if (/^(?:title|caption|collapse|author|year|source)=$/.test(input.slice(i).match(/^[a-z]+=/i)?.[0] ?? '')) {
       const eq = input.indexOf('=', i);
       let j = eq + 1;
       const quote = input[j];

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/styles.css

@@ -654,3 +654,71 @@
 html.no-js .pcb__copy {
   display: none !important;
 }
+
+/* ============================================================
+   v2.2.0: Phase 3 — Split diff, annotations, attribution
+   ============================================================ */
+
+/* ---------- Split diff view ---------- */
+:where(.pcb--split-diff) .pcb__body {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+}
+:where(.pcb--split-diff) .pcb__body > pre {
+  border-right: 1px solid var(--pcb-border);
+}
+:where(.pcb--split-diff) .pcb__body > pre:last-child) {
+  border-right: none;
+}
+@media (max-width: 768px) {
+  :where(.pcb--split-diff) .pcb__body {
+    grid-template-columns: 1fr;
+  }
+  :where(.pcb--split-diff) .pcb__body > pre {
+    border-right: none;
+    border-bottom: 1px solid var(--pcb-border);
+  }
+}
+
+/* ---------- Line annotations ---------- */
+:where(.pcb__ann) {
+  display: none; /* hidden by default, shown when .pcb--annotations */
+}
+:where(.pcb--annotations) .pcb__line[data-ann] {
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  align-items: baseline;
+}
+:where(.pcb--annotations) .pcb__ann) {
+  display: block;
+  padding-left: 1rem;
+  color: var(--pcb-text-muted);
+  font-size: 0.8125em;
+  font-style: italic;
+  white-space: normal;
+  border-left: 2px solid var(--pcb-border);
+  user-select: none;
+}
+@media (max-width: 768px) {
+  :where(.pcb--annotations) .pcb__line[data-ann]) {
+    grid-template-columns: auto 1fr;
+  }
+  :where(.pcb--annotations) .pcb__ann) {
+    grid-column: 1 / -1;
+    padding-left: 0;
+    border-left: none;
+    border-top: 1px dashed var(--pcb-border);
+    margin-top: 0.25rem;
+  }
+}
+
+/* ---------- Attribution footer ---------- */
+:where(.pcb__attribution) {
+  padding: 0.5rem 1rem;
+  font-family: var(--pcb-bar-font);
+  font-size: var(--pcb-bar-font-size);
+  color: var(--pcb-caption-color);
+  background: var(--pcb-caption-bg);
+  border-top: 1px solid var(--pcb-border);
+  font-style: italic;
+}

package/src/transformer.ts

@@ -247,6 +247,12 @@ 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',
+    // v2.2.0: Phase 3
+    diffMode: 'unified' as const,
+    annotations: false,
+    attribution: false,
     inline: false,
     ...rest,
   };
@@ -637,6 +643,31 @@ async function transformPre(
     figureChildren.push(cap);
   }
 
+  // v2.2.0: Attribution footer — render author/year/source as a footer below the code block.
+  if ((opts as { attribution?: boolean }).attribution && (meta.author || meta.year || meta.source)) {
+    const parts: string[] = [];
+    if (meta.author) parts.push(meta.author);
+    if (meta.year) parts.push(`(${meta.year})`);
+    if (meta.source) parts.push(`. ${meta.source}.`);
+    else if (meta.author || meta.year) parts.push('.');
+    const attrText = parts.join(' ').trim();
+    if (attrText) {
+      figureChildren.push(
+        h('figcaption', { className: ['pcb__attribution'] }, [hText(attrText)])
+      );
+    }
+  }
+
+  // v2.2.0: Add pcb--split-diff class when diffMode is 'split'
+  if ((opts as { diffMode?: string }).diffMode === 'split') {
+    figClasses.push('pcb--split-diff');
+  }
+
+  // v2.2.0: Add pcb--annotations class when annotations are enabled
+  if ((opts as { annotations?: boolean }).annotations) {
+    figClasses.push('pcb--annotations');
+  }
+
   return h('figure', { className: figClasses }, figureChildren);
 }
 
@@ -939,6 +970,19 @@ function toLineSpans(
     // Map word-highlight spans inside this line.
     const mappedChildren = mapWordHighlights(line.children);
 
+    // v2.2.0: Parse and strip // [!ann: "text"] annotation notation.
+    let annotationText: string | null = null;
+    if ((opts as { annotations?: boolean }).annotations) {
+      const lineText = extractLineText(line);
+      const annMatch = lineText.match(/\[!ann:\s*"([^"]*)"\s*\]/);
+      if (annMatch) {
+        annotationText = annMatch[1];
+        // Strip the annotation from the line's text content
+        // (replace in all text nodes within the line)
+        stripAnnotationFromLine(line, annMatch[0]);
+      }
+    }
+
     // The line wrapper itself (the Shiki <span class="line ...">) becomes the
     // content of .pcb__code. Strip its classes — we've already mapped them
     // onto the outer .pcb__line wrapper, so they shouldn't also appear here.
@@ -951,7 +995,7 @@ function toLineSpans(
       children: mappedChildren,
     };
 
-    // Build the row: [gutter-cell?, code-cell]
+    // Build the row: [gutter-cell?, code-cell, annotation?]
     const lineChildren: ElementContent[] = [];
     if (resolved.lineNumbers) {
       lineChildren.push(
@@ -962,7 +1006,18 @@ function toLineSpans(
       h('span', { className: ['pcb__code'] }, [innerWrapper])
     );
 
-    return h('span', { className: [...classes] }, lineChildren);
+    // v2.2.0: Add annotation cell if this line has an annotation
+    if (annotationText !== null) {
+      lineChildren.push(
+        h('span', { className: ['pcb__ann'], 'dataAnn': annotationText }, [hText(annotationText)])
+      );
+    }
+
+    const lineProps: Record<string, unknown> = { className: [...classes] };
+    if (annotationText !== null) {
+      lineProps['dataAnn'] = annotationText;
+    }
+    return h('span', lineProps, lineChildren);
   });
 }
 
@@ -1151,6 +1206,18 @@ function hText(value: string): Text {
   return { type: 'text', value };
 }
 
+/** v2.2.0: Strip an annotation notation from all text nodes in a line element. */
+function stripAnnotationFromLine(line: Element, annotation: string): void {
+  const walk = (node: ElementContent): void => {
+    if (node.type === 'text') {
+      node.value = node.value.replace(annotation, '');
+    } else if (node.type === 'element') {
+      for (const child of node.children) walk(child);
+    }
+  };
+  for (const child of line.children) walk(child);
+}
+
 /* ---------- Pattern 5: word-level diff (selective adoption from expressive-code) ---------- */
 
 /**