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

package/src/color-utils.ts

@@ -0,0 +1,214 @@
+/**
+ * Color manipulation utilities for theme-aware CSS variable defaults.
+ *
+ * Pattern 2 (adopted from expressive-code's `helpers/color-transforms.ts`):
+ * CSS variable defaults are derived from the loaded Shiki theme and adjusted
+ * to meet WCAG contrast ratios, so code blocks look good with ANY Shiki theme
+ * out of the box — line numbers, diff backgrounds, and focus highlights are
+ * automatically legible against the theme's background color.
+ *
+ * The functions here are intentionally minimal — we only implement what we
+ * need to compute a few default `--pcb-*` values. For full color manipulation
+ * (lighten/darken/mix), see expressive-code's implementation.
+ */
+
+/** A color in RGB format (0–255 per channel). */
+export interface RGB {
+  r: number;
+  g: number;
+  b: number;
+  a?: number; // 0–1, optional alpha
+}
+
+/** Relative luminance per WCAG 2.1: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance */
+function relativeLuminance({ r, g, b }: RGB): number {
+  const channel = (c: number): number => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+/** Contrast ratio per WCAG 2.1: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio (1–21). */
+export function contrastRatio(fg: RGB, bg: RGB): number {
+  const l1 = relativeLuminance(fg);
+  const l2 = relativeLuminance(bg);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Parse a hex color (#RGB, #RGBA, #RRGGBB, #RRGGBBAA) or rgb()/rgba() string
+ * into an RGB object. Returns null if the input can't be parsed.
+ */
+export function parseColor(input: string | undefined | null): RGB | null {
+  if (!input) return null;
+  const s = input.trim().toLowerCase();
+  // Hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
+  const hexMatch = s.match(/^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/);
+  if (hexMatch) {
+    let hex = hexMatch[1];
+    if (hex.length === 3 || hex.length === 4) {
+      hex = hex
+        .split('')
+        .map((c) => c + c)
+        .join('');
+    }
+    const r = parseInt(hex.slice(0, 2), 16);
+    const g = parseInt(hex.slice(2, 4), 16);
+    const b = parseInt(hex.slice(4, 6), 16);
+    const a = hex.length === 8 ? parseInt(hex.slice(6, 8), 16) / 255 : undefined;
+    return { r, g, b, a };
+  }
+  // rgb() / rgba()
+  const rgbMatch = s.match(/^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/);
+  if (rgbMatch) {
+    return {
+      r: parseInt(rgbMatch[1], 10),
+      g: parseInt(rgbMatch[2], 10),
+      b: parseInt(rgbMatch[3], 10),
+      a: rgbMatch[4] !== undefined ? parseFloat(rgbMatch[4]) : undefined,
+    };
+  }
+  return null;
+}
+
+/** Convert an RGB color back to a hex string (#RRGGBB or #RRGGBBAA). */
+export function toHex({ r, g, b, a }: RGB): string {
+  const toHex2 = (n: number): string => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, '0');
+  const base = `#${toHex2(r)}${toHex2(g)}${toHex2(b)}`;
+  if (a !== undefined && a < 1) return base + toHex2(a * 255);
+  return base;
+}
+
+/** Mix two colors by a ratio (0 = pure a, 1 = pure b). */
+export function mix(a: RGB, b: RGB, ratio: number): RGB {
+  const t = Math.max(0, Math.min(1, ratio));
+  return {
+    r: a.r * (1 - t) + b.r * t,
+    g: a.g * (1 - t) + b.g * t,
+    b: a.b * (1 - t) + b.b * t,
+    a: a.a !== undefined || b.a !== undefined ? (a.a ?? 1) * (1 - t) + (b.a ?? 1) * t : undefined,
+  };
+}
+
+/** Lighten a color toward white by a ratio (0–1). */
+export function lighten(color: RGB, ratio: number): RGB {
+  return mix(color, { r: 255, g: 255, b: 255 }, ratio);
+}
+
+/** Darken a color toward black by a ratio (0–1). */
+export function darken(color: RGB, ratio: number): RGB {
+  return mix(color, { r: 0, g: 0, b: 0 }, ratio);
+}
+
+/**
+ * Adjust a foreground color to meet a target contrast ratio against a
+ * background. If the contrast is already sufficient, returns the foreground
+ * unchanged. Otherwise, lightens (if bg is dark) or darkens (if bg is light)
+ * the foreground until the target ratio is met.
+ *
+ * @param fg Foreground color to adjust
+ * @param bg Background color to adjust against
+ * @param minRatio Minimum WCAG contrast ratio (default 4.5 = AA for normal text)
+ * @param maxRatio Maximum ratio to aim for if adjusting (default 7.0 = AAA)
+ * @returns The adjusted foreground color (or the original if already sufficient)
+ */
+export function ensureColorContrastOnBackground(
+  fg: RGB,
+  bg: RGB,
+  minRatio = 4.5,
+  maxRatio = 7.0
+): RGB {
+  const current = contrastRatio(fg, bg);
+  if (current >= minRatio) return fg;
+
+  // Decide direction: if bg is dark (luminance < 0.5), lighten fg; else darken.
+  const bgLum = relativeLuminance(bg);
+  const direction = bgLum < 0.5 ? 'lighten' : 'darken';
+  // Binary search between current and pure white/black for the target ratio.
+  let lo = 0;
+  let hi = 1;
+  let best = fg;
+  for (let i = 0; i < 16; i++) {
+    const mid = (lo + hi) / 2;
+    const candidate = direction === 'lighten' ? lighten(fg, mid) : darken(fg, mid);
+    const ratio = contrastRatio(candidate, bg);
+    if (ratio >= minRatio && ratio <= maxRatio) {
+      return candidate;
+    }
+    if (ratio < minRatio) {
+      lo = mid;
+    } else {
+      best = candidate;
+      hi = mid;
+    }
+  }
+  return best;
+}
+
+/**
+ * Extract the background and foreground colors from a Shiki theme object.
+ * Shiki themes have a `bg` and `fg` property at the top level (hex strings).
+ * Returns nulls if the theme shape doesn't match.
+ */
+export function extractThemeColors(theme: unknown): { bg: RGB | null; fg: RGB | null } {
+  const t = theme as { bg?: string; fg?: string; name?: string };
+  return {
+    bg: parseColor(t?.bg),
+    fg: parseColor(t?.fg),
+  };
+}
+
+/**
+ * Compute theme-aware `--pcb-*` defaults for a code block based on the
+ * loaded Shiki theme. These are applied as inline styles on the `<figure>`
+ * element, so the static `dist/styles.css` can ship its own defaults while
+ * the runtime overrides them with theme-aware values.
+ *
+ * Currently computes:
+ *   - --pcb-bg: theme background (or 'inherit' if unknown)
+ *   - --pcb-fg: theme foreground (or 'inherit' if unknown)
+ *   - --pcb-line-numbers-fg: theme fg, contrast-adjusted against theme bg
+ *   - --pcb-line-highlight-bg: theme fg at ~12% alpha (subtle highlight)
+ *   - --pcb-line-diff-add-bg: green at ~18% alpha
+ *   - --pcb-line-diff-del-bg: red at ~18% alpha
+ *   - --pcb-line-focus-bg: theme fg at ~6% alpha (subtle dim)
+ *
+ * @param theme The Shiki theme object (must have `bg` and `fg` hex strings)
+ * @returns A CSS style string (e.g. `--pcb-bg:#fff;--pcb-fg:#000;...`) or empty string
+ */
+export function computeThemeAwareDefaults(theme: unknown): string {
+  const { bg, fg } = extractThemeColors(theme);
+  if (!bg || !fg) return '';
+
+  const parts: string[] = [];
+  parts.push(`--pcb-bg:${toHex(bg)}`);
+  parts.push(`--pcb-fg:${toHex(fg)}`);
+
+  // Line numbers: use fg, but adjust contrast to >= 3.0 (WCAG AA for large text)
+  // against the background. Shiki themes often have low-contrast line-number
+  // colors baked in; we override them with a guaranteed-legible value.
+  const lineNumFg = ensureColorContrastOnBackground(fg, bg, 3.0, 4.5);
+  parts.push(`--pcb-ln-fg:${toHex(lineNumFg)}`);
+
+  // Line highlight background: subtle tint of the foreground at ~12% alpha.
+  // Use mix() with the background to get a slightly-lighter/darker shade.
+  const hlBg = mix(bg, fg, 0.12);
+  parts.push(`--pcb-line-highlight-bg:${toHex(hlBg)}`);
+
+  // Diff add: green (#22863a in github) at 18% alpha over bg.
+  const diffAdd = mix(bg, { r: 34, g: 134, b: 58 }, 0.18);
+  parts.push(`--pcb-line-add-bg:${toHex(diffAdd)}`);
+
+  // Diff del: red (#cb2431 in github) at 18% alpha over bg.
+  const diffDel = mix(bg, { r: 203, g: 36, b: 49 }, 0.18);
+  parts.push(`--pcb-line-del-bg:${toHex(diffDel)}`);
+
+  // Focus background: dim the non-focused lines by mixing bg with fg at low alpha.
+  const focusBg = mix(bg, fg, 0.04);
+  parts.push(`--pcb-line-focus-bg:${toHex(focusBg)}`);
+
+  return parts.join(';');
+}

package/src/copy-script.ts

@@ -1,9 +1,9 @@
 /**
  * The copy-button client script. Inlined once per page (deduped by the
- * Astro integration via `injectScript`). ~600 bytes gzipped.
+ * Astro integration via `injectScript`). ~1.2 KB gzipped.
  *
  * Behavior:
- *   - Listens for clicks on `.pcb__copy`
+ *   - Listens for clicks on `.pcb__copy` (event delegation on document)
  *   - Copies the textContent of the nearest `pre code`
  *   - Toggles `.pcb__copy--done` and swaps the icon + label
  *   - Resets after `data-feedback-duration` ms (default 1600)
@@ -13,6 +13,13 @@
  *   - Strips leading `#` comment lines when `data-strip-comments` is set (terminal preset)
  *   - Announces "Copied" to screen readers via an aria-live region (WCAG 4.1.2)
  *   - Hides copy button when JS is disabled (via .no-js class on <html>)
+ *
+ * Pattern 4 (adopted from VitePress + expressive-code):
+ *   - Event delegation via `document.addEventListener('click', ...)` — works
+ *     regardless of how buttons were rendered (SSR, CSR, view transitions).
+ *   - MutationObserver re-initializes the aria-live region and the .no-js → .js
+ *     class swap when new code blocks are added to the DOM (SPA support).
+ *   - `astro:page-load` event listener for Astro view transitions.
  */
 export const COPY_SCRIPT = `
 (function () {
@@ -20,27 +27,37 @@ export const COPY_SCRIPT = `
   window.__pcbCopyReady = true;
 
   // Remove the .no-js class so the copy buttons become visible (graceful degradation).
-  if (document.documentElement.classList.contains('no-js')) {
-    document.documentElement.classList.remove('no-js');
-    document.documentElement.classList.add('js');
+  function swapNoJs() {
+    if (document.documentElement.classList.contains('no-js')) {
+      document.documentElement.classList.remove('no-js');
+      document.documentElement.classList.add('js');
+    }
   }
+  swapNoJs();
 
   // Reuse a single aria-live region for all copy announcements.
-  var liveRegion = document.querySelector('.pcb__sr-live');
-  if (!liveRegion) {
-    liveRegion = document.createElement('span');
-    liveRegion.className = 'pcb__sr-live';
-    liveRegion.setAttribute('aria-live', 'polite');
-    liveRegion.setAttribute('aria-atomic', 'true');
-    liveRegion.setAttribute('role', 'status');
-    document.body.appendChild(liveRegion);
+  var liveRegion = null;
+  function ensureLiveRegion() {
+    if (liveRegion && document.body.contains(liveRegion)) return liveRegion;
+    liveRegion = document.querySelector('.pcb__sr-live');
+    if (!liveRegion) {
+      liveRegion = document.createElement('span');
+      liveRegion.className = 'pcb__sr-live';
+      liveRegion.setAttribute('aria-live', 'polite');
+      liveRegion.setAttribute('aria-atomic', 'true');
+      liveRegion.setAttribute('role', 'status');
+      document.body.appendChild(liveRegion);
+    }
+    return liveRegion;
   }
+  ensureLiveRegion();
 
   function announce(msg) {
-    if (!liveRegion) return;
-    liveRegion.textContent = '';
+    var lr = ensureLiveRegion();
+    if (!lr) return;
+    lr.textContent = '';
     // Force re-announcement by clearing then setting on next tick.
-    setTimeout(function () { liveRegion.textContent = msg; }, 50);
+    setTimeout(function () { lr.textContent = msg; }, 50);
   }
 
   function findLabel(btn) {
@@ -60,6 +77,9 @@ export const COPY_SCRIPT = `
     return text.replace(/^[ \\t]*(?:#|\\/\\/|REM\\b).*$/gm, '').replace(/\\n{3,}/g, '\\n\\n').trim();
   }
 
+  // Event-delegated click handler. Works for buttons added after initial
+  // render (e.g. via React/Vue re-render or Astro view transitions) because
+  // the listener is on document, not on each button.
   document.addEventListener('click', function (e) {
     var btn = e.target && e.target.closest && e.target.closest('.pcb__copy');
     if (!btn) return;
@@ -123,5 +143,44 @@ export const COPY_SCRIPT = `
       document.body.removeChild(ta);
     }
   });
+
+  // Pattern 4: MutationObserver for SPA support.
+  // When new code blocks are inserted into the DOM (e.g. by React/Vue
+  // re-render, Astro view transitions, or Turbolinks navigation), the
+  // .no-js → .js class swap may need to be re-applied so newly-added
+  // copy buttons become visible. The observer watches for added .pcb nodes.
+  if (typeof MutationObserver !== 'undefined') {
+    var pendingObserve = false;
+    var observer = new MutationObserver(function (mutations) {
+      // Batch checks with microtask to avoid layout thrash.
+      if (pendingObserve) return;
+      pendingObserve = true;
+      Promise.resolve().then(function () {
+        pendingObserve = false;
+        // If any new .pcb nodes were added, ensure the .js class is set
+        // (in case the page was rendered server-side with .no-js and the
+        // client took over after initial load).
+        for (var i = 0; i < mutations.length; i++) {
+          if (mutations[i].addedNodes && mutations[i].addedNodes.length) {
+            swapNoJs();
+            ensureLiveRegion();
+            break;
+          }
+        }
+      });
+    });
+    // Observe the whole document subtree for added nodes.
+    observer.observe(document.documentElement, { childList: true, subtree: true });
+  }
+
+  // Pattern 4: astro:page-load event listener for Astro view transitions.
+  // Astro emits this event after a view transition completes; the new page's
+  // DOM may have replaced the old, so re-apply the .no-js → .js swap.
+  if (typeof document.addEventListener === 'function') {
+    document.addEventListener('astro:page-load', function () {
+      swapNoJs();
+      ensureLiveRegion();
+    });
+  }
 })();
 `;

package/src/index.ts

@@ -20,11 +20,16 @@
 import type { Plugin } from 'unified';
 import type { Root } from 'hast';
 import { rehypePerfectCodeBlocks as transformer } from './transformer.js';
-import { runShikiOnRawBlocks } from './shiki.js';
+import { runShikiOnRawBlocks, disposeHighlighter, runHighlighterTask } from './shiki.js';
 import { remarkPreserveCodeMeta } from './remark.js';
+import { wordDiff, hasChanges } from './word-diff.js';
+import type { DiffToken } from './word-diff.js';
 import type { PerfectCodeOptions } from './types.js';
 
 export { remarkPreserveCodeMeta };
+export { disposeHighlighter, runHighlighterTask };
+export { wordDiff, hasChanges };
+export type { DiffToken };
 
 export const rehypePerfectCodeBlocks: Plugin<[PerfectCodeOptions?], Root> =
   (options = {}) => {
@@ -90,6 +95,7 @@ function resolveDefaults(opts: PerfectCodeOptions): Required<PerfectCodeOptions>
     lineNumbersStart: opts.lineNumbersStart ?? 1,
     highlight: opts.highlight ?? true,
     diff: opts.diff ?? true,
+    wordDiff: opts.wordDiff ?? false,
     focus: opts.focus ?? true,
     errorLevels: opts.errorLevels ?? true,
     wrap: opts.wrap ?? false,

package/src/meta.ts

@@ -103,7 +103,13 @@ export function parseMeta(meta: string | undefined): ParsedMeta {
       const idMatch = after.match(/^#([\w-]+)/);
       const lines = parseRanges(rangePart);
       if (lines.length > 0) {
-        result.highlight.push(...lines);
+        // Issue #11: use a loop instead of `push(...lines)` to avoid
+        // stack overflow if `lines` is somehow huge (e.g. via a future
+        // code path that bypasses the MAX_HIGHLIGHT_LINES cap in
+        // parseRanges). Spread on >~100k args exhausts the V8 call stack.
+        for (let i = 0; i < lines.length; i++) {
+          result.highlight.push(lines[i]);
+        }
         result.highlightGroups.push({ lines, id: idMatch?.[1] });
       }
       continue;
@@ -287,6 +293,24 @@ function parseRanges(spec: string): number[] {
   // `,` and remaining whitespace (between range tokens), so `{1, 3 - 5, 7}`
   // → `1, 3-5, 7` → splits to ['1', '3-5', '7'] → [1, 3, 4, 5, 7]. ✓
   const normalized = spec.replace(/\s*-\s*/g, '-');
+
+  // Issue #11: a range like {1-1000000} would previously expand to a
+  // 1,000,000-element Set, then `result.highlight.push(...lines)` at the
+  // call site would blow the V8 stack (spread on huge arrays exceeds the
+  // ~100k-arg limit). This is a DoS vector for any deployment that renders
+  // user-supplied markdown.
+  //
+  // Fix: short-circuit ranges whose span exceeds a sane cap. Highlighting
+  // more than 10,000 lines in a single code block is not a real use case —
+  // at that point the user almost certainly has a typo or is trying to abuse
+  // the renderer. We return an empty array (skip highlighting) rather than
+  // throwing, so the rest of the block still renders normally.
+  //
+  // The cap is intentionally much larger than any realistic code block
+  // (a 10k-line code block is itself pathological) to avoid false positives.
+  const MAX_HIGHLIGHT_LINES = 10_000;
+  let totalSpan = 0;
+
   for (const part of normalized.split(/[\s,]+/)) {
     if (!part) continue;
     const m = part.match(/^(\d+)(?:-(\d+))?$/);
@@ -295,6 +319,14 @@ function parseRanges(spec: string): number[] {
     const end = m[2] ? parseInt(m[2], 10) : start;
     const lo = Math.min(start, end);
     const hi = Math.max(start, end);
+    const span = hi - lo + 1;
+    totalSpan += span;
+    if (totalSpan > MAX_HIGHLIGHT_LINES) {
+      // Range is implausibly large — bail out and skip highlighting
+      // for this entire meta spec. The block still renders; it just
+      // won't have any line-highlighting applied.
+      return [];
+    }
     for (let n = lo; n <= hi; n++) out.add(n);
   }
   return [...out].sort((a, b) => a - b);

package/src/shiki.ts

@@ -17,6 +17,7 @@ import type { Element, Root } from 'hast';
 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 {
   transformerNotationDiff,
   transformerNotationFocus,
@@ -66,6 +67,58 @@ type ShikiHighlighter = {
 
 const highlighterCache = new Map<string, Promise<ShikiHighlighter>>();
 
+// ───────────────────────────────────────────────────────────────────────────
+// Pattern 1 (adopted from expressive-code): Mutually exclusive highlighter
+// task queue.
+//
+// All highlighter operations (createHighlighter, loadLanguage, loadTheme,
+// codeToHast, codeToHtml) are wrapped in `runHighlighterTask(() => ...)`.
+// This serializes them globally, preventing race conditions in parallel
+// static-site builds where multiple unified pipelines share the same
+// module-level highlighter cache.
+//
+// Without this queue, if pipeline A calls `loadLanguage('ts')` and pipeline
+// B calls `codeToHast(code, { lang: 'ts' })` on the same tick, B may run
+// before A's load completes and fall back to plaintext — the "issue #13"
+// class of bug. The queue makes all operations globally sequential.
+//
+// Tradeoff: slight throughput reduction in parallel builds; correctness >
+// throughput for syntax highlighting.
+// ───────────────────────────────────────────────────────────────────────────
+
+type QueueTask = { taskFn: () => Promise<unknown>; resolve: (v: unknown) => void; reject: (e: unknown) => void };
+const taskQueue: QueueTask[] = [];
+let processingQueue = false;
+
+function processQueue(): void {
+  const next = taskQueue.shift();
+  if (!next) {
+    processingQueue = false;
+    return;
+  }
+  Promise.resolve()
+    .then(() => next.taskFn())
+    .then(
+      (result) => { next.resolve(result); processQueue(); },
+      (err) => { next.reject(err); processQueue(); }
+    );
+}
+
+/**
+ * Run a task function inside the mutually exclusive highlighter queue.
+ * All calls are serialized globally — the next task starts only after the
+ * current one resolves or rejects.
+ */
+export function runHighlighterTask<T>(taskFn: () => Promise<T>): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    taskQueue.push({ taskFn: taskFn as () => Promise<unknown>, resolve: resolve as (v: unknown) => void, reject });
+    if (!processingQueue) {
+      processingQueue = true;
+      processQueue();
+    }
+  });
+}
+
 async function getHighlighter(
   themeKeys: string[],
   langs: string[],
@@ -79,7 +132,9 @@ async function getHighlighter(
   const cacheKey = `${themeKeys.join(',')}|${[...safeLangs].sort().join(',')}|${regexEngine ?? 'onig'}`;
   let promise = highlighterCache.get(cacheKey);
   if (!promise) {
-    promise = (async () => {
+    // Wrap the highlighter creation in the task queue so concurrent
+    // pipeline instances don't race on Shiki's internal singleton state.
+    promise = runHighlighterTask(async () => {
       if (userGetHighlighter) {
         return (await userGetHighlighter({ themes: themeKeys, langs: safeLangs })) as ShikiHighlighter;
       }
@@ -100,12 +155,39 @@ async function getHighlighter(
       }
       const all = await shiki.createHighlighter(createOpts as unknown as Parameters<typeof shiki.createHighlighter>[0]);
       return all as unknown as ShikiHighlighter;
-    })();
+    });
     highlighterCache.set(cacheKey, promise);
   }
   return promise;
 }
 
+/**
+ * Pattern 3 (adopted from VitePress): Dispose all cached highlighters and
+ * clear the cache. Call this in long-running dev servers when the theme
+ * changes, or during cleanup of a build pipeline, to release the WASM
+ * engine + loaded grammars + theme cache held by Shiki.
+ *
+ * After calling this, the next render will create a fresh highlighter.
+ *
+ * @example
+ *   // In a Vite dev server shutdown hook:
+ *   import { disposeHighlighter } from '@dr-ishaan/rehype-perfect-code-blocks';
+ *   server.http2.close(() => disposeHighlighter());
+ */
+export function disposeHighlighter(): void {
+  for (const promise of highlighterCache.values()) {
+    // The promise may still be pending; if so, attach a dispose-on-resolve.
+    promise.then(
+      (h) => {
+        const maybeDisposable = h as unknown as { dispose?: () => void };
+        if (typeof maybeDisposable.dispose === 'function') maybeDisposable.dispose();
+      },
+      () => { /* ignore — failed highlighters are already gone */ }
+    );
+  }
+  highlighterCache.clear();
+}
+
 /** Filter out languages that aren't bundled with Shiki (avoids sync throws). */
 function filterBundledLangs(langs: string[]): string[] {
   // Always keep plaintext variants (special — don't require a bundle).
@@ -421,17 +503,22 @@ export async function runShikiOnRawBlocks(
   // Lazily load any langs not yet loaded. Shiki's `loadLanguage` throws
   // synchronously for bundled-but-unknown langs (e.g. typos), so wrap each
   // call in its own try/catch and use Promise.allSettled to swallow rejects.
+  //
+  // Wrapped in `runHighlighterTask` so concurrent pipeline instances don't
+  // race on Shiki's internal language registry. (Pattern 1)
   const loaded = new Set(highlighter.getLoadedLanguages());
   const missing = [...langSet].filter((l) => !loaded.has(l));
   if (missing.length > 0) {
-    const results = await Promise.allSettled(
-      missing.map((l) => {
-        try {
-          return Promise.resolve(highlighter.loadLanguage(l));
-        } catch {
-          return Promise.resolve();
-        }
-      })
+    const results = await runHighlighterTask(() =>
+      Promise.allSettled(
+        missing.map((l) => {
+          try {
+            return Promise.resolve(highlighter.loadLanguage(l));
+          } catch {
+            return Promise.resolve();
+          }
+        })
+      )
     );
     // Log failed language loads (competitor analysis: EC does this, improves DX).
     const failed: string[] = [];
@@ -642,11 +729,71 @@ export async function runShikiOnRawBlocks(
         // language-* class and the Shiki lang we actually used.
         (newCode.properties as Record<string, unknown>).dataLanguage = normalizedRawLang;
       }
+
+      // Pattern 2: Apply theme-aware --pcb-* defaults as inline styles on the
+      // <pre> element. The static dist/styles.css ships its own defaults, but
+      // those are generic; the runtime overrides them here based on the loaded
+      // Shiki theme so colors look good with ANY theme out of the box.
+      //
+      // We compute the defaults once per (theme,lang) combination and cache
+      // them on a WeakMap keyed by the highlighter to avoid recomputing per block.
+      if (typeof newPre.properties === 'object' && newPre.properties !== null) {
+        const themeDefaults = getThemeAwareDefaults(highlighter, themeKeys);
+        if (themeDefaults) {
+          const existingStyle = (newPre.properties as { style?: string }).style;
+          // Prepend our defaults so user-provided inline styles (if any) win.
+          (newPre.properties as { style?: string }).style = themeDefaults + (existingStyle ? `;${existingStyle}` : '');
+        }
+      }
+
       Object.assign(pre, newPre);
     }
   }
 }
 
+// Cache theme-aware defaults per highlighter instance + theme keys, so we
+// don't recompute them for every code block on the page.
+const themeDefaultsCache = new WeakMap<object, Map<string, string>>();
+
+function getThemeAwareDefaults(highlighter: ShikiHighlighter, themeKeys: string[]): string {
+  // Use the highlighter object as the WeakMap key.
+  const hlKey = highlighter as unknown as object;
+  let perHl = themeDefaultsCache.get(hlKey);
+  if (!perHl) {
+    perHl = new Map();
+    themeDefaultsCache.set(hlKey, perHl);
+  }
+  const cacheKey = themeKeys.slice().sort().join(',');
+  let cached = perHl.get(cacheKey);
+  if (cached !== undefined) return cached;
+
+  // Get the theme object from the highlighter.
+  // Use the first theme key (typically the dark theme in dual-theme config).
+  let theme: unknown = null;
+  try {
+    // highlighter.getTheme() returns the resolved theme registration.
+    const themeName = themeKeys[0];
+    const hlAny = highlighter as unknown as { getTheme?: (name: string) => unknown };
+    if (themeName && typeof hlAny.getTheme === 'function') {
+      theme = hlAny.getTheme(themeName);
+    }
+  } catch {
+    theme = null;
+  }
+
+  let defaults = '';
+  if (theme) {
+    try {
+      defaults = computeThemeAwareDefaults(theme);
+    } catch {
+      defaults = '';
+    }
+  }
+
+  perHl.set(cacheKey, defaults);
+  return defaults;
+}
+
 function hasShikiMarker(className: unknown): boolean {
   if (!className) return false;
   const arr = Array.isArray(className) ? className : String(className).split(/\s+/);