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

package/src/shiki.ts

@@ -19,6 +19,7 @@ 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 { isMermaidLanguage, renderMermaid, isCsvLanguage, buildCsvTable } from './diagrams.js';
 import {
   transformerNotationDiff,
   transformerNotationFocus,
@@ -490,6 +491,87 @@ export async function runShikiOnRawBlocks(
     targets.splice(0, targets.length, ...codeTargets);
   }
 
+  // v2.3.0: Handle Mermaid diagram blocks — render as SVG instead of Shiki.
+  if ((opts as { mermaid?: boolean }).mermaid) {
+    const mermaidTargets: Element[] = [];
+    const remainingTargets: Element[] = [];
+    for (const pre of targets) {
+      const code = pre.children.find(
+        (c): c is Element => c.type === 'element' && c.tagName === 'code'
+      );
+      if (!code) { remainingTargets.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 (isMermaidLanguage(lang)) {
+        mermaidTargets.push(pre);
+      } else {
+        remainingTargets.push(pre);
+      }
+    }
+
+    for (const pre of mermaidTargets) {
+      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 { svg, isError } = await renderMermaid(text);
+      const mermaidDiv: Element = {
+        type: 'element',
+        tagName: 'div',
+        properties: { className: ['pcb__mermaid', isError ? 'pcb__mermaid--error' : 'pcb__mermaid--rendered'] },
+        children: svg
+          ? [{ type: 'text', value: svg }]
+          : [{ type: 'element', tagName: 'pre', properties: {}, children: [{ type: 'text', value: text }] }],
+      };
+      Object.assign(pre, mermaidDiv);
+    }
+    targets.splice(0, targets.length, ...remainingTargets);
+  }
+
+  // v2.3.0: Handle CSV/TSV table blocks — render as HTML table instead of Shiki.
+  if ((opts as { csvTables?: boolean }).csvTables) {
+    const csvTargets: Element[] = [];
+    const remainingTargets: Element[] = [];
+    for (const pre of targets) {
+      const code = pre.children.find(
+        (c): c is Element => c.type === 'element' && c.tagName === 'code'
+      );
+      if (!code) { remainingTargets.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 (isCsvLanguage(lang)) {
+        csvTargets.push(pre);
+      } else {
+        remainingTargets.push(pre);
+      }
+    }
+
+    for (const pre of csvTargets) {
+      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 cls = (code.properties?.className as string[] | undefined) ?? [];
+      const langClass = cls.find((c) => c.startsWith('language-'));
+      const lang = langClass ? langClass.replace('language-', '') : 'csv';
+      const delimiter = lang.toLowerCase() === 'tsv' ? '\t' : ',';
+      const tableEl = buildCsvTable(text, delimiter);
+      // Replace the <pre> with the table wrapped in a div
+      const tableDiv: Element = {
+        type: 'element',
+        tagName: 'div',
+        properties: { className: ['pcb__csv-table'] },
+        children: [tableEl],
+      };
+      Object.assign(pre, tableDiv);
+    }
+    targets.splice(0, targets.length, ...remainingTargets);
+  }
+
   if (targets.length === 0) return;
 
   // Build theme keys — supports single (string), dual ({light,dark}), and

package/src/styles.css

@@ -654,3 +654,163 @@
 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;
+}
+
+/* ============================================================
+   v2.3.0: P2 — Retro preset, Mermaid, CSV tables, ASCII art, A11y
+   ============================================================ */
+
+/* ---------- Retro CRT preset ---------- */
+:where(.pcb--retro) {
+  --pcb-bg: #000000;
+  --pcb-fg: #00ff41;
+  --pcb-text-muted: #008f11;
+  --pcb-border: #00ff41;
+  --pcb-bg-header: #001100;
+  --pcb-bg-gutter: #000000;
+  --pcb-radius: 0px;
+  --pcb-font-mono: 'Courier New', 'Lucida Console', monospace;
+  --pcb-bar-font: 'Courier New', monospace;
+  text-shadow: 0 0 2px currentColor, 0 0 4px rgba(0, 255, 65, 0.3);
+}
+:where(.pcb--retro) .pcb__body {
+  position: relative;
+}
+:where(.pcb--retro) .pcb__body::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: repeating-linear-gradient(
+    0deg,
+    rgba(0, 0, 0, 0) 0px,
+    rgba(0, 0, 0, 0) 2px,
+    rgba(0, 0, 0, 0.08) 2px,
+    rgba(0, 0, 0, 0.08) 4px
+  );
+  pointer-events: none;
+}
+:where(.pcb--retro) .pcb__dots span) {
+  background: #00ff41;
+  opacity: 0.6;
+}
+
+/* ---------- Mermaid diagram container ---------- */
+:where(.pcb__mermaid) {
+  padding: 1rem;
+  background: var(--pcb-bg);
+  overflow-x: auto;
+  text-align: center;
+}
+:where(.pcb__mermaid svg) {
+  max-width: 100%;
+  height: auto;
+}
+:where(.pcb__mermaid--error) {
+  color: var(--pcb-text-muted);
+  font-family: var(--pcb-font-mono);
+}
+
+/* ---------- CSV/TSV table ---------- */
+:where(.pcb__csv-table) {
+  padding: 0;
+  background: var(--pcb-bg);
+  overflow-x: auto;
+}
+:where(.pcb__table) {
+  width: 100%;
+  border-collapse: collapse;
+  font-family: var(--pcb-font-mono);
+  font-size: var(--pcb-font-size);
+}
+:where(.pcb__th) {
+  padding: 0.5rem 1rem;
+  text-align: left;
+  border-bottom: 2px solid var(--pcb-border);
+  color: var(--pcb-text-bar);
+  font-weight: 600;
+}
+:where(.pcb__td) {
+  padding: 0.4rem 1rem;
+  border-bottom: 1px solid var(--pcb-border);
+  color: var(--pcb-text);
+}
+:where(.pcb__tr:nth-child(even) .pcb__td) {
+  background: rgba(127, 127, 127, 0.05);
+}
+
+/* ---------- ASCII art: disable ligatures ---------- */
+:where(.pcb[data-language="text"] .pcb__code),
+:where(.pcb[data-language="plaintext"] .pcb__code),
+:where(.pcb[data-language="txt"] .pcb__code),
+:where(.pcb[data-language="ascii"] .pcb__code),
+:where(.pcb[data-language="plain"] .pcb__code) {
+  font-variant-ligatures: none;
+  font-feature-settings: "liga" 0, "calt" 0;
+}

package/src/transformer.ts

@@ -249,6 +249,14 @@ export function rehypePerfectCodeBlocks(userOptions: PerfectCodeOptions = {}) {
     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,
+    // v2.3.0: P2
+    mermaid: false,
+    csvTables: false,
+    asciiArtLangs: ['text', 'plaintext', 'txt', 'ascii', 'plain'] as string[],
     inline: false,
     ...rest,
   };
@@ -639,6 +647,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);
 }
 
@@ -941,6 +974,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.
@@ -953,18 +999,36 @@ 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(
-        h('span', { className: ['pcb__ln'], ariaHidden: true }, [hText(String(lineNumber))])
+        h('span', { className: ['pcb__ln'], ariaHidden: true, 'aria-label': `Line ${lineNumber}` }, [hText(String(lineNumber))])
       );
     }
     lineChildren.push(
       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;
+    }
+    // v2.3.0: Add aria-label for diff lines (accessibility)
+    if (classes.has('pcb__line--add')) {
+      lineProps['aria-label'] = 'Added line';
+    } else if (classes.has('pcb__line--del')) {
+      lineProps['aria-label'] = 'Removed line';
+    }
+
+    return h('span', lineProps, lineChildren);
   });
 }
 
@@ -1153,6 +1217,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) ---------- */
 
 /**

package/src/types.ts

@@ -343,7 +343,7 @@ export interface PerfectCodeOptions {
 
   /* ---------- Styling ---------- */
   /** Visual preset. Default: 'default' */
-  preset?: 'default' | 'terminal' | 'minimal';
+  preset?: 'default' | 'terminal' | 'minimal' | 'retro';
   /** Inject the bundled CSS automatically. Set false to ship your own. Default: true */
   injectStyles?: boolean;
   /** Manual theme override. Default: 'auto' (prefers-color-scheme) */
@@ -550,6 +550,94 @@ export interface PerfectCodeOptions {
    */
   devWarnings?: boolean;
 
+  /* ---------- v2.2.0: Diff & Comparison ---------- */
+
+  /**
+   * Side-by-side diff view. When enabled, adjacent `+`/`-` diff line pairs
+   * are rendered in a two-column layout (Before | After) with synchronized
+   * scrolling, instead of the default unified diff view.
+   *
+   * On mobile (viewport < 768px), the columns stack vertically.
+   *
+   * Default: `'unified'` (backward-compatible with v1.x/v2.0/v2.1)
+   */
+  diffMode?: 'unified' | 'split';
+
+  /* ---------- v2.2.0: Annotations ---------- */
+
+  /**
+   * Line annotations — margin notes attached to specific code lines.
+   *
+   * Use `// [!ann: "explanation"]` notation inside code to annotate a line.
+   * The annotation appears on the right side of the code block, connected
+   * to the annotated line with a subtle connector line. On mobile,
+   * annotations appear inline below the annotated line.
+   *
+   * Example:
+   * ```ts
+   * const attention = Q.dot(K.T) / Math.sqrt(d)  // [!ann: "Scaled dot-product"]
+   * const weights = softmax(attention)            // [!ann: "Normalized weights"]
+   * ```
+   *
+   * Default: `false` (opt-in)
+   */
+  annotations?: boolean;
+
+  /* ---------- v2.2.0: Attribution ---------- */
+
+  /**
+   * Code attribution — structured metadata for code blocks.
+   *
+   * When enabled, the plugin parses `author`, `year`, and `source` attributes
+   * from the fence meta string and renders them as a footer below the code block:
+   *
+   * ````markdown
+   * ```ts title="perceptron.ts" author="Rosenblatt" year="1958" source="Principles of Neurodynamics"
+   * const output = stepFunction(inputs.dot(weights))
+   * ```
+   * ````
+   *
+   * Renders:
+   * ```
+   * ┌─ perceptron.ts ──────────────────┐
+   * │ const output = stepFunction(...)  │
+   * └───────────────────────────────────┘
+   *   Rosenblatt (1958). Principles of Neurodynamics.
+   * ```
+   *
+   * Default: `false` (opt-in; when disabled, author/year/source meta is silently ignored)
+   */
+  attribution?: boolean;
+
+  /* ---------- v2.3.0: P2 — Diagrams, Tables, ASCII, Frames, A11y ---------- */
+
+  /**
+   * Mermaid diagram rendering. When a fenced code block has language `mermaid`,
+   * render it as an SVG diagram instead of syntax-highlighted code.
+   *
+   * `mermaid` must be installed: `npm install mermaid`
+   *
+   * Default: `false` (mermaid blocks render as plain code)
+   */
+  mermaid?: boolean;
+
+  /**
+   * CSV/TSV table rendering. When a fenced code block has language `csv` or
+   * `tsv`, render it as a styled HTML table instead of code.
+   *
+   * Default: `false` (CSV/TSV blocks render as plain code)
+   */
+  csvTables?: boolean;
+
+  /**
+   * ASCII art preservation. For languages in the list, disable ligatures,
+   * preserve trailing whitespace, and set `font-variant-ligatures: none` to
+   * ensure ASCII art alignment is maintained.
+   *
+   * Default: `['text', 'plaintext', 'txt', 'ascii', 'plain']`
+   */
+  asciiArtLangs?: string[];
+
   /* ---------- Inline code (legacy cosmetic option) ---------- */
   /** Also style inline `code` cosmetically (no tokenization). Default: false */
   inline?: boolean;
@@ -574,6 +662,10 @@ export interface ParsedMeta {
   wordHighlights: { text: string; range?: [number, number]; id?: string }[];
   lineNumbersStart: number | null;         // from ln{N} or showLineNumbers{N}
   collapseRanges: { from: number; to: number }[];  // from collapse="5-12,20-30"
+  // v2.2.0: Attribution metadata
+  author: string | null;                   // from author="..."
+  year: string | null;                     // from year="..."
+  source: string | null;                   // from source="..."
   flags: {
     wrap: boolean | null;
     lineNumbers: boolean | null;