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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dr-ishaan/rehype-perfect-code-blocks",
-  "version": "1.3.3",
+  "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",
+    "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/astro.ts

@@ -22,6 +22,7 @@ import { rehypePerfectCodeBlocks } from './index.js';
 import { remarkPreserveCodeMeta } from './remark.js';
 import { COPY_SCRIPT } from './copy-script.js';
 import type { PerfectCodeOptions } from './types.js';
+import { generateTokenStyles, applyScopeToCss } from './tokens.js';
 import { readFileSync } from 'node:fs';
 import { readdirSync, writeFileSync, readFileSync as readFile } from 'node:fs';
 import { fileURLToPath } from 'node:url';
@@ -121,9 +122,26 @@ export default function perfectCode(
         const nonceAttr = options.cspNonce ? ` nonce="${escapeAttr(options.cspNonce)}"` : '';
 
         // CSS
-        if (options.injectStyles !== false) {
-          const css = loadCss();
+        if (options.injectStyles !== false && options.cssInjection !== 'import') {
+          let css = loadCss();
           if (css) {
+            // v2.0.0: Apply CSS scope if configured
+            if (options.scope) {
+              css = applyScopeToCss(css, options.scope);
+            }
+
+            // v2.0.0: Generate token-bridge CSS (derived --pcb-* variables)
+            const tokenCss = generateTokenStyles(options.tokens ?? {}, options.scope);
+            if (tokenCss) {
+              css = css + '\n' + tokenCss;
+            }
+
+            // v2.0.0: Wrap in @layer if configured
+            const layerName = options.cssLayer ?? 'pcb';
+            if (options.cssInjection === 'layer') {
+              css = `@layer ${layerName} {\n${css}\n}`;
+            }
+
             injections.push(`<style data-pcb${nonceAttr}>${css}</style>`);
           }
         }

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

@@ -24,12 +24,20 @@ import { runShikiOnRawBlocks, disposeHighlighter, runHighlighterTask } from './s
 import { remarkPreserveCodeMeta } from './remark.js';
 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 type { DiffToken };
+export { generateTokenStyles, applyScopeToCss, generateDarkModeSelector, generateLightModeSelector };
+export { resolveMathOptions, isMathLanguage, renderMath };
+export { runDevWarnings, warnUnknownLanguage };
+export type { DiffToken, DesignTokens, MathOptions, ResolvedMathOptions };
 
 export const rehypePerfectCodeBlocks: Plugin<[PerfectCodeOptions?], Root> =
   (options = {}) => {
@@ -157,6 +165,15 @@ function resolveDefaults(opts: PerfectCodeOptions): Required<PerfectCodeOptions>
     preset: opts.preset ?? 'default',
     injectStyles: opts.injectStyles ?? true,
     theme: opts.theme ?? 'auto',
+    // v2.0.0: CSS Architecture options
+    cssInjection: opts.cssInjection ?? 'inline',
+    cssLayer: opts.cssLayer ?? 'pcb',
+    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(