@dr-ishaan/rehype-perfect-code-blocks 1.1.7 → 1.2.1

package/src/transformer.ts

@@ -21,7 +21,7 @@
 import type { Element, ElementContent, Properties, Root, Text } from 'hast';
 import { visit } from 'unist-util-visit';
 import { parseMeta } from './meta.js';
-import type { PerfectCodeOptions, ResolvedBlock, MagicComment } from './types.js';
+import type { PerfectCodeOptions, ResolvedBlock, MagicComment, ParsedMeta } from './types.js';
 
 /** Default inline SVG copy icon (16x16 GitHub octicon copy). */
 const DEFAULT_COPY_ICON = `<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"/><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"/></svg>`;
@@ -170,7 +170,7 @@ const DEFAULT_MAGIC_COMMENTS: MagicComment[] = [
   },
 ];
 
-const DEFAULT_TERMINAL_LANGS = ['sh', 'bash', 'zsh', 'shell', 'console', 'powershell', 'bat', 'cmd', 'fish'];
+const DEFAULT_TERMINAL_LANGS = ['sh', 'bash', 'zsh', 'shell', 'console', 'powershell', 'bat', 'cmd', 'fish', 'ansi'];
 
 export function rehypePerfectCodeBlocks(userOptions: PerfectCodeOptions = {}) {
   const { shiki: userShiki, ...rest } = userOptions;
@@ -189,6 +189,8 @@ export function rehypePerfectCodeBlocks(userOptions: PerfectCodeOptions = {}) {
     errorLevels: true,
     wrap: false,
     collapseAfter: null,
+    collapseRanges: null,
+    collapseStyle: 'github',
     showWhitespace: false,
     indentGuides: false,
     caption: true,
@@ -197,11 +199,17 @@ export function rehypePerfectCodeBlocks(userOptions: PerfectCodeOptions = {}) {
       theme: { light: 'github-light', dark: 'github-dark' },
       langs: [],
       transformers: [],
+      transformerOrder: 'after',
       ...(userShiki ?? {}),
     },
     keepBackground: false,
     styleToClass: false,
     useHastApi: true,
+    disableAutoTransformers: false,
+    removeComments: false,
+    removeLineBreaks: false,
+    zeroIndexed: false,
+    lineOptions: [],
     customNotations: {},
     magicComments: DEFAULT_MAGIC_COMMENTS,
     inlineCode: false,
@@ -213,9 +221,12 @@ export function rehypePerfectCodeBlocks(userOptions: PerfectCodeOptions = {}) {
     languageLabels: {},
     languageAliases: {},
     defaultBlockLang: '',
+    tabWidth: 0,
+    copyStripComments: true,
     accessibleScroll: true,
     announceCopy: true,
     hideCopyWithoutJs: true,
+    terminalSrOnlyTitle: true,
     rehypePlugins: [],
     filterMetaString: (s) => s,
     onVisitLine: () => {},
@@ -223,6 +234,9 @@ export function rehypePerfectCodeBlocks(userOptions: PerfectCodeOptions = {}) {
     onVisitHighlightedChars: () => {},
     onVisitTitle: () => {},
     onVisitCaption: () => {},
+    texts: {},
+    logger: console,
+    cspNonce: '',
     preset: 'default',
     injectStyles: true,
     theme: 'auto',
@@ -232,6 +246,7 @@ export function rehypePerfectCodeBlocks(userOptions: PerfectCodeOptions = {}) {
 
   return async (tree: Root) => {
     const visits: Element[] = [];
+    const inlineCodes: Element[] = [];
 
     visit(tree, 'element', (node) => {
       if (node.tagName !== 'pre') return;
@@ -243,15 +258,88 @@ export function rehypePerfectCodeBlocks(userOptions: PerfectCodeOptions = {}) {
       visits.push(node);
     });
 
+    // Inline code highlighting: visit <code> elements whose parent is NOT <pre>.
+    // These are inline code spans like `code{:lang}` or `code{:.token}`.
+    if (options.inlineCode) {
+      visit(tree, 'element', (node, index, parent) => {
+        if (node.tagName !== 'code') return;
+        if (!parent || parent.type !== 'element' || parent.tagName === 'pre') return;
+        if (node.properties?.dataPcbDone) return;
+        inlineCodes.push(node);
+      });
+    }
+
     for (const pre of visits) {
       const replacement = await transformPre(pre, options);
       if (replacement) {
         Object.assign(pre, replacement);
       }
     }
+
+    // Process inline code blocks (after the block-level transform).
+    for (const code of inlineCodes) {
+      transformInlineCode(code, options);
+    }
   };
 }
 
+/**
+ * Transform an inline `<code>` element (not inside a `<pre>`).
+ *
+ * Supports two modes (matching rehype-pretty-code's syntax):
+ *   - `inlineCode: 'lang'` or `true` — parse `code{:lang}` suffix and tokenize via Shiki
+ *   - `inlineCode: 'token'` — parse `code{:.token}` suffix and color by VS Code token
+ *
+ * The suffix is stripped from the displayed text. The resulting tokenized
+ * spans are wrapped in a `<code class="pcb__inline">` element.
+ *
+ * NOTE: This function only modifies the inline `<code>` element's children
+ * and adds a class. Shiki tokenization happens at render time via the
+ * `engine: 'shiki'` path (runShikiOnRawBlocks handles `<pre><code>` only —
+ * inline code is styled by the CSS based on the `pcb__inline` class).
+ */
+function transformInlineCode(
+  code: Element,
+  opts: Required<PerfectCodeOptions>
+): void {
+  // Extract the text content.
+  const text = extractText(code);
+  if (!text) return;
+
+  // Parse the `{:lang}` or `{:.token}` suffix.
+  // rehype-pretty-code uses `{:lang}` for language and `{:.token}` for token.
+  const langMatch = text.match(/\{:([a-zA-Z][\w.-]*)\}$/);
+  const tokenMatch = text.match(/\{:\.([\w-]+)\}$/);
+
+  let displayText = text;
+  let lang: string | null = null;
+  let token: string | null = null;
+
+  if (opts.inlineCode === 'token' && tokenMatch) {
+    token = tokenMatch[1];
+    displayText = text.slice(0, tokenMatch.index);
+  } else if (opts.inlineCode === true || opts.inlineCode === 'lang') {
+    if (langMatch) {
+      lang = langMatch[1];
+      displayText = text.slice(0, langMatch.index);
+    } else if (opts.inlineDefaultLang || opts.defaultInlineLang) {
+      lang = opts.inlineDefaultLang || opts.defaultInlineLang || null;
+    }
+  }
+
+  // Replace the text content with the stripped display text.
+  code.children = [{ type: 'text', value: displayText } as Text];
+
+  // Add the `pcb__inline` class plus optional lang/token classes for CSS.
+  const cls = ['pcb__inline'];
+  if (lang) cls.push(`pcb__inline--${lang}`);
+  if (token) cls.push(`pcb__inline--token-${token}`);
+  code.properties = code.properties ?? {};
+  code.properties.className = cls;
+  // Mark as done so we don't re-process it.
+  code.properties.dataPcbDone = true;
+}
+
 async function transformPre(
   pre: Element,
   opts: Required<PerfectCodeOptions>
@@ -309,6 +397,13 @@ async function transformPre(
   // buildCopyButton().
   const copyButtonEnabled = typeof opts.copyButton === 'object' ? true : !!opts.copyButton;
   const autoTitleBar = !!(title || effectiveLang || copyButtonEnabled);
+  // Distinguish whole-block collapse (collapseAfter threshold or `collapse` flag)
+  // from per-line collapse (collapseRanges from `collapse="N-M"` meta).
+  // Per-line collapse uses <details> sections INSIDE the <pre>, not around it.
+  const hasCollapseRanges = !!(meta.collapseRanges && meta.collapseRanges.length > 0);
+  const wholeBlockCollapse = !hasCollapseRanges && (
+    meta.flags.collapse ?? (opts.collapseAfter != null ? shouldCollapse(pre, opts.collapseAfter) : false)
+  );
   const resolved: ResolvedBlock = {
     language: effectiveLang,
     title,
@@ -321,7 +416,7 @@ async function transformPre(
     decorations: meta.flags.decorations ?? opts.decorations,
     showLanguage: meta.flags.showLanguage ?? opts.showLanguage,
     copyButton: meta.flags.copyButton ?? copyButtonEnabled,
-    collapse: meta.flags.collapse ?? (opts.collapseAfter != null ? shouldCollapse(pre, opts.collapseAfter) : false),
+    collapse: wholeBlockCollapse,
   };
 
   // Auto-detect terminal preset based on language.
@@ -348,6 +443,10 @@ async function transformPre(
   // Filter out trailing empty line (from trailing newline in source).
   const filteredLines = filterTrailingEmpty(lineSpans);
 
+  // Apply per-line collapsible sections (meta `collapse="5-12,20-30"`).
+  // Wraps matching line ranges in <details><summary>N collapsed lines</summary>...</details>.
+  const collapsedLines = wrapCollapsedSections(filteredLines, meta, opts, resolved.lineNumbersStart);
+
   // Call onVisitLine / onVisitHighlightedLine hooks.
   filteredLines.forEach((line, i) => {
     const lineNumber = i + resolved.lineNumbersStart;
@@ -359,6 +458,9 @@ async function transformPre(
   });
 
   // data-line-numbers-max-digits attribute on <code> for CSS-driven gutter sizing.
+  // Uses filteredLines.length (not collapsedLines) because collapsed sections
+  // contain the same total number of logical lines — we just want the max
+  // gutter number's digit count.
   const maxDigits = String(filteredLines.length + resolved.lineNumbersStart - 1).length;
   const codeDataProps: Record<string, unknown> = {
     dataLineNumbersMaxDigits: String(maxDigits),
@@ -371,11 +473,36 @@ async function transformPre(
     codeDataProps.dataLineNumbers = '';
   }
 
+  // Collect body-level `has-*` classes (e.g. `has-diff`, `has-focused`,
+  // `has-highlighted`) from the line spans. These were previously stripped —
+  // restoring them lets CSS target the whole <pre> when any line has a state.
+  const preLevelClasses = new Set<string>();
+  for (const line of collapsedLines) {
+    // Skip <details> wrapper elements — only inspect actual line spans.
+    if (line.tagName !== 'span') continue;
+    const lineClasses = (line.properties?.className as string[] | undefined) ?? [];
+    if (lineClasses.includes('pcb__line--add') || lineClasses.includes('pcb__line--del')) {
+      preLevelClasses.add('has-diff');
+    }
+    if (lineClasses.includes('pcb__line--focus')) {
+      preLevelClasses.add('has-focused');
+    }
+    if (lineClasses.includes('pcb__line--hl')) {
+      preLevelClasses.add('has-highlighted');
+    }
+    if (lineClasses.includes('pcb__line--error') || lineClasses.includes('pcb__line--warning') || lineClasses.includes('pcb__line--info')) {
+      preLevelClasses.add('has-error-level');
+    }
+  }
+
   // Build code <pre><code> with line spans.
   // When keepBackground is true, preserve Shiki's inline `style` (which includes
   // background-color + color from the theme) on the new <pre>.
-  const newCode = h('code', codeDataProps, filteredLines);
+  const newCode = h('code', codeDataProps, collapsedLines);
   const newPreProps: Record<string, unknown> = {};
+  if (preLevelClasses.size > 0) {
+    newPreProps.className = [...preLevelClasses];
+  }
   if (opts.keepBackground && pre.properties?.style) {
     newPreProps.style = pre.properties.style;
   }
@@ -387,25 +514,40 @@ async function transformPre(
   const bodyClasses = ['pcb__body'];
   if (resolved.highlight.length > 0) bodyClasses.push('pcb__body--has-hl');
   // Accessibility: mark scrollable region so screen readers announce it (WCAG 4.1.2).
+  // Also add tabindex=0 for keyboard scrolling (WCAG 2.1.1).
   const bodyProps: Record<string, unknown> = { className: bodyClasses };
   if (opts.accessibleScroll) {
     bodyProps.role = 'region';
+    bodyProps.tabIndex = 0;
+    // i18n: allow user to override the aria-label prefix.
+    const ariaPrefix = opts.texts?.codeBlockAriaPrefix ?? 'Code block';
     // Escape the title/lang for use in an aria-label attribute (defense in depth:
     // prevents any <script> or other HTML from leaking into the attribute).
     const safeLabel = title
-      ? `Code block: ${title.replace(/[<>"'&]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;', '&': '&amp;' }[c] ?? c))}`
+      ? `${ariaPrefix}: ${title.replace(/[<>"'&]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;', '&': '&amp;' }[c] ?? c))}`
       : effectiveLang
-        ? `Code block: ${effectiveLang}`
-        : 'Code block';
+        ? `${ariaPrefix}: ${effectiveLang}`
+        : ariaPrefix;
     bodyProps.ariaLabel = safeLabel;
   }
   const body = h('div', bodyProps, [newPre]);
 
+  // i18n: screen-reader-only title for terminal preset (improves context).
+  const terminalSrText = (presetClass === 'terminal' && !title && opts.terminalSrOnlyTitle !== false)
+    ? (opts.texts?.terminalSrOnlyTitle ?? 'Terminal window')
+    : null;
+
   // Header bar.
+  // Use <figcaption> when there's no separate caption (more semantic).
+  // When both title-bar and caption are present, use <div> for bar and
+  // <figcaption> for the caption (matches rehype-pretty-code).
   let bar: Element | null = null;
   if (resolved.titleBar) {
     const barChildren: ElementContent[] = [];
     if (resolved.decorations) barChildren.push(dotsElement());
+    if (terminalSrText) {
+      barChildren.push(h('span', { className: ['pcb__sr-only'] }, [hText(terminalSrText)]));
+    }
     barChildren.push(
       h('div', { className: ['pcb__title'] }, title ? [hText(title)] : [])
     );
@@ -413,9 +555,18 @@ async function transformPre(
       barChildren.push(h('div', { className: ['pcb__lang'] }, [hText(languageLabel ?? resolved.language)]));
     }
     if (resolved.copyButton) {
-      barChildren.push(buildCopyButton(opts));
+      const btn = buildCopyButton(opts);
+      // For terminal preset + copyStripComments, mark the button so the
+      // client script knows to strip # comments from the copied text.
+      if (presetClass === 'terminal' && opts.copyStripComments !== false) {
+        (btn.properties as Record<string, unknown>).dataStripComments = '';
+      }
+      barChildren.push(btn);
     }
-    bar = h('div', { className: ['pcb__bar'] }, barChildren);
+    // Use figcaption for the bar when there's no separate caption below —
+    // this gives the figure an accessible name from the title.
+    const barTag = (!opts.caption || !meta.caption) && title ? 'figcaption' : 'div';
+    bar = h(barTag, { className: ['pcb__bar'] }, barChildren);
     if (title) opts.onVisitTitle(bar);
   }
 
@@ -433,6 +584,9 @@ async function transformPre(
   if (resolved.collapse) {
     const summaryChildren: ElementContent[] = [];
     if (resolved.decorations) summaryChildren.push(dotsElement());
+    if (terminalSrText) {
+      summaryChildren.push(h('span', { className: ['pcb__sr-only'] }, [hText(terminalSrText)]));
+    }
     summaryChildren.push(
       h('span', { className: ['pcb__title'] }, [hText(title ?? 'code')])
     );
@@ -459,8 +613,14 @@ async function transformPre(
 
 /** Build the copy button based on options (legacy boolean or new object form). */
 function buildCopyButton(opts: Required<PerfectCodeOptions>): Element {
-  let label: string | null = 'copy';
-  let doneLabel: string = 'copied!';
+  // i18n: allow user to override default UI strings via `texts` option.
+  const texts = opts.texts ?? {};
+  const defaultLabel = texts.copyLabel ?? 'copy';
+  const defaultDoneLabel = texts.doneLabel ?? 'copied!';
+  const defaultAriaLabel = texts.copyAriaLabel ?? 'Copy code';
+
+  let label: string | null = defaultLabel;
+  let doneLabel: string = defaultDoneLabel;
   let copyIcon: string | undefined;
   let successIcon: string | undefined;
   let feedbackDuration: number | undefined;
@@ -471,16 +631,25 @@ function buildCopyButton(opts: Required<PerfectCodeOptions>): Element {
       label = opts.copyButton.label ?? null;
     }
     if ('doneLabel' in opts.copyButton) {
-      doneLabel = opts.copyButton.doneLabel ?? 'copied!';
+      doneLabel = opts.copyButton.doneLabel ?? defaultDoneLabel;
     }
     copyIcon = opts.copyButton.copyIcon;
     successIcon = opts.copyButton.successIcon;
     feedbackDuration = opts.copyButton.feedbackDuration;
-  } else {
-    // Legacy: use copyButtonLabel / copyButtonDoneLabel.
-    label = opts.copyButtonLabel;
-    doneLabel = opts.copyButtonDoneLabel;
+  } else if (opts.copyButton === true) {
+    // Legacy boolean `copyButton: true`.
+    // If user explicitly set copyButtonLabel/copyButtonDoneLabel (deprecated),
+    // honor them. Otherwise use the i18n defaults from `texts`.
+    // We detect "explicitly set" by checking against the defaults: 'copy' and 'copied!'.
+    // (This is a bit of a hack but maintains backward compat.)
+    if (opts.copyButtonLabel !== 'copy') {
+      label = opts.copyButtonLabel;
+    }
+    if (opts.copyButtonDoneLabel !== 'copied!') {
+      doneLabel = opts.copyButtonDoneLabel;
+    }
   }
+  // Note: when copyButton=false, buildCopyButton is never called.
 
   const btnChildren: ElementContent[] = [copyIconElement(copyIcon)];
   if (label) {
@@ -490,7 +659,7 @@ function buildCopyButton(opts: Required<PerfectCodeOptions>): Element {
   const btnProps: Record<string, unknown> = {
     className: ['pcb__copy'],
     type: 'button',
-    ariaLabel: 'Copy code',
+    ariaLabel: defaultAriaLabel,
     dataDoneLabel: doneLabel,
   };
   // SECURITY: successIcon is stored verbatim as a data-* attribute and later
@@ -787,6 +956,63 @@ function filterTrailingEmpty(lines: Element[]): Element[] {
   return hasText ? lines : lines.slice(0, -1);
 }
 
+/**
+ * Wrap per-line collapsible sections in <details><summary>…</summary>…</details>.
+ *
+ * Reads `meta.collapseRanges` (parsed from `collapse="5-12,20-30"` meta) and
+ * wraps matching line ranges. Lines are 1-indexed (matching the lineNumbersStart
+ * offset passed in).
+ *
+ * The summary element shows "N collapsed lines" (or the i18n variant).
+ * The details element gets class `pcb__collapse` plus a style class based on
+ * `opts.collapseStyle` (e.g. `pcb__collapse--github`).
+ *
+ * Lines outside any range are passed through unchanged.
+ */
+function wrapCollapsedSections(
+  lines: Element[],
+  meta: ParsedMeta,
+  opts: Required<PerfectCodeOptions>,
+  lineNumbersStart: number
+): Element[] {
+  if (!meta.collapseRanges || meta.collapseRanges.length === 0) {
+    return lines;
+  }
+  // Build a map of lineNumber → index in `lines`.
+  // Line numbers are 1-indexed starting at `lineNumbersStart`.
+  // Index in `lines` is 0-indexed, so line N corresponds to lines[N - lineNumbersStart].
+  const result: Element[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const lineNumber = i + lineNumbersStart;
+    // Find a collapse range that starts at this line.
+    const range = meta.collapseRanges.find((r) => r.from === lineNumber);
+    if (range) {
+      const rangeSize = range.to - range.from + 1;
+      const sectionLines = lines.slice(i, i + rangeSize);
+      // i18n: customize the summary label.
+      const labelFn = opts.texts?.collapsedLinesLabel;
+      const summaryText = labelFn
+        ? labelFn(rangeSize)
+        : `${rangeSize} collapsed line${rangeSize === 1 ? '' : 's'}`;
+      const summary = h('summary', { className: ['pcb__collapse-summary'] }, [hText(summaryText)]);
+      const detailsClasses = ['pcb__collapse'];
+      if (opts.collapseStyle && opts.collapseStyle !== 'github') {
+        detailsClasses.push(`pcb__collapse--${opts.collapseStyle}`);
+      } else {
+        detailsClasses.push('pcb__collapse--github');
+      }
+      const details = h('details', { className: detailsClasses }, [summary, ...sectionLines]);
+      result.push(details);
+      i += rangeSize;
+    } else {
+      result.push(lines[i]);
+      i++;
+    }
+  }
+  return result;
+}
+
 /** Walk line children and remap "highlighted-word" → "pcb__word" class. */
 function mapWordHighlights(children: ElementContent[]): ElementContent[] {
   return children.map((child) => {

package/src/types.ts

@@ -59,6 +59,16 @@ export interface PerfectCodeOptions {
   wrap?: boolean;
   /** Auto-collapse blocks longer than N lines. null = never. Default: null */
   collapseAfter?: number | null;
+  /**
+   * Per-line collapsible sections.
+   * Pass a meta string like `collapse="5-12,20-30"` to wrap matching line ranges
+   * in `<details><summary>N collapsed lines</summary>...</details>`.
+   * Style options: 'github' (default), 'collapsible-start', 'collapsible-end', 'collapsible-auto'.
+   * Default: null (disabled).
+   */
+  collapseRanges?: string | null;
+  /** Style for collapsible sections. Default: 'github'. */
+  collapseStyle?: 'github' | 'collapsible-start' | 'collapsible-end' | 'collapsible-auto';
   /** Show visible whitespace (tabs/spaces). Default: false */
   showWhitespace?: false | 'all' | 'boundary' | 'trailing' | 'leading';
   /** Render vertical indent guides. false | true (default 2) | number (indent width). Default: false */
@@ -76,8 +86,12 @@ export interface PerfectCodeOptions {
   engine?: 'auto' | 'shiki' | 'passthrough';
   /** Shiki options passed through when the plugin calls Shiki itself. */
   shiki?: {
-    /** Theme — string for single theme, { light, dark } for dual-theme via CSS vars. */
-    theme?: string | { light: string; dark: string };
+    /**
+     * Theme — string for single theme, { light, dark } for dual-theme via CSS vars,
+     * or a Record<string, string> for multi-theme (3+ themes) support.
+     * Multi-theme example: `{ light: 'github-light', dark: 'github-dark', dim: 'github-dark-dimmed' }`.
+     */
+    theme?: string | { light: string; dark: string } | Record<string, string>;
     /** Pre-loaded languages. Defaults to a sensible set; missing langs are lazy-loaded. */
     langs?: string[];
     /**
@@ -88,6 +102,12 @@ export interface PerfectCodeOptions {
     regexEngine?: 'oniguruma' | 'javascript';
     /** Additional Shiki transformers to apply (see @shikijs/transformers). */
     transformers?: ShikiTransformer[];
+    /**
+     * Controls whether user-provided transformers run 'before' or 'after' the
+     * auto-registered ones (default: 'after'). Use 'before' to give user
+     * transformers first access to the code text.
+     */
+    transformerOrder?: 'before' | 'after';
     /** Override the highlighter factory (e.g. for custom TextMate grammars). */
     getHighlighter?: (opts: { themes: string[]; langs: string[] }) => Promise<unknown>;
     [key: string]: unknown;
@@ -108,6 +128,34 @@ export interface PerfectCodeOptions {
    * round-trip. Faster + safer. Default: true.
    */
   useHastApi?: boolean;
+  /**
+   * Disable auto-registration of @shikijs/transformers. When true, ONLY the
+   * transformers in `shiki.transformers` are applied. Default: false.
+   * Useful for advanced users who want full manual control.
+   */
+  disableAutoTransformers?: boolean;
+  /**
+   * Strip all comments from the rendered code (// ..., # ..., /* ... *\/, <!-- ... -->).
+   * Powered by @shikijs/transformers `transformerRemoveComments`. Default: false.
+   */
+  removeComments?: boolean;
+  /**
+   * Remove line breaks from the rendered code (joins all lines into one).
+   * Powered by @shikijs/transformers `transformerRemoveLineBreaks`. Default: false.
+   * Useful for compact inline-style code blocks.
+   */
+  removeLineBreaks?: boolean;
+  /**
+   * When `true`, treat {1,3-5} meta ranges as zero-indexed (line 0 is the first
+   * line). When `false` (default), line numbers start at 1.
+   */
+  zeroIndexed?: boolean;
+  /**
+   * Programmatic per-line class assignment (Shiki's `transformerCompactLineOptions`).
+   * Example: `[{ line: 1, classes: ['highlight'] }, { line: 3, classes: ['add'] }]`.
+   * Default: [] (disabled).
+   */
+  lineOptions?: { line: number; classes?: string[]; attrs?: Record<string, string> }[];
 
   /* ---------- Inline comment notations (VitePress-style) ---------- */
   /**
@@ -141,7 +189,7 @@ export interface PerfectCodeOptions {
   /* ---------- Auto frame detection (Expressive Code style) ---------- */
   /**
    * Auto-switch to terminal preset for these languages. Default:
-   * ['sh', 'bash', 'zsh', 'shell', 'console', 'powershell', 'bat', 'cmd', 'fish']
+   * ['sh', 'bash', 'zsh', 'shell', 'console', 'powershell', 'bat', 'cmd', 'fish', 'ansi']
    */
   terminalLangs?: string[];
   /**
@@ -172,10 +220,22 @@ export interface PerfectCodeOptions {
    * (Renamed from `inlineDefaultLang` for clarity; old name still works.)
    */
   defaultInlineLang?: string;
+  /**
+   * Replace tabs with N spaces before tokenization. 0 disables (default).
+   * Useful for languages where Shiki's tab rendering doesn't match the
+   * surrounding code style.
+   */
+  tabWidth?: number;
+  /**
+   * Strip leading `#` comment lines from terminal code when copying to clipboard.
+   * Default: true (only effective when preset === 'terminal').
+   */
+  copyStripComments?: boolean;
 
   /* ---------- Accessibility ---------- */
   /**
-   * Add `role="region"` and `aria-label` to scrollable code blocks (WCAG 4.1.2).
+   * Add `role="region"`, `aria-label`, and `tabindex="0"` to scrollable code
+   * blocks (WCAG 2.1.1 keyboard accessible, 4.1.2 name-role-value).
    * Default: true.
    */
   accessibleScroll?: boolean;
@@ -190,6 +250,12 @@ export interface PerfectCodeOptions {
    * Default: true.
    */
   hideCopyWithoutJs?: boolean;
+  /**
+   * Add a screen-reader-only `<span class="pcb__sr-only">Terminal window</span>`
+   * to terminal-preset blocks that have no title. Improves screen reader context.
+   * Default: true.
+   */
+  terminalSrOnlyTitle?: boolean;
 
   /**
    * Additional rehype plugins to run BEFORE rehype-perfect-code-blocks.
@@ -214,6 +280,40 @@ export interface PerfectCodeOptions {
   /** Called for the caption element (if present). */
   onVisitCaption?: (element: unknown) => void;
 
+  /* ---------- i18n (internationalization) ---------- */
+  /**
+   * Localized UI strings. Defaults are English. Override per-locale by
+   * passing a different `texts` object based on the current language.
+   */
+  texts?: {
+    /** Copy button label (default: 'copy'). */
+    copyLabel?: string;
+    /** Label shown after successful copy (default: 'copied!'). */
+    doneLabel?: string;
+    /** Aria-label for the copy button (default: 'Copy code'). */
+    copyAriaLabel?: string;
+    /** Screen-reader-only title for terminal-preset blocks (default: 'Terminal window'). */
+    terminalSrOnlyTitle?: string;
+    /** aria-label prefix for scrollable body (default: 'Code block'). */
+    codeBlockAriaPrefix?: string;
+    /** Summary text for collapsed sections, with `{n}` placeholder (default: '{n} collapsed lines'). */
+    collapsedLinesLabel?: (n: number) => string;
+  };
+
+  /* ---------- Logging ---------- */
+  /**
+   * Custom logger. Defaults to `console`. Useful for silencing warnings in
+   * production or routing them to a structured logger.
+   */
+  logger?: { warn: (msg: string) => void; error: (msg: string) => void };
+
+  /* ---------- CSP (Content Security Policy) ---------- */
+  /**
+   * Nonce to add to injected `<script>` and `<style>` tags. Enables strict CSP
+   * (`script-src 'self' 'nonce-...'`). Default: undefined (no nonce).
+   */
+  cspNonce?: string;
+
   /* ---------- Styling ---------- */
   /** Visual preset. Default: 'default' */
   preset?: 'default' | 'terminal' | 'minimal';
@@ -245,6 +345,7 @@ export interface ParsedMeta {
   highlightGroups: { lines: number[]; id?: string }[];  // {1,2}#a {3,4}#b
   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"
   flags: {
     wrap: boolean | null;
     lineNumbers: boolean | null;