astro-xmdx 0.0.2

package/src/transforms/shiki.test.ts

@@ -0,0 +1,289 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  highlightHtmlBlocks,
+  highlightJsxCodeBlocks,
+  rewriteAstroSetHtml,
+} from './shiki.js';
+
+// Mock highlight function that simulates Shiki output
+const mockHighlight = async (code: string, lang?: string): Promise<string> => {
+  const langAttr = lang ? ` class="language-${lang}"` : '';
+  return `<pre${langAttr}><code${langAttr}>${code.toUpperCase()}</code></pre>`;
+};
+
+describe('highlightHtmlBlocks', () => {
+  test('returns empty string for empty HTML', async () => {
+    const result = await highlightHtmlBlocks('', mockHighlight);
+    expect(result).toBe('');
+  });
+
+  test('returns HTML unchanged when no code blocks', async () => {
+    const html = '<div><p>Hello world</p></div>';
+    const result = await highlightHtmlBlocks(html, mockHighlight);
+    expect(result).toBe('<div><p>Hello world</p></div>');
+  });
+
+  test('highlights single code block without language', async () => {
+    const html = '<pre><code>const x = 1;</code></pre>';
+    const result = await highlightHtmlBlocks(html, mockHighlight);
+    expect(result).toContain('CONST X = 1;');
+    expect(result).toContain('<pre');
+    expect(result).toContain('<code');
+  });
+
+  test('highlights single code block with language', async () => {
+    const html = '<pre><code class="language-javascript">const x = 1;</code></pre>';
+    const result = await highlightHtmlBlocks(html, mockHighlight);
+    expect(result).toContain('CONST X = 1;');
+    expect(result).toContain('class="language-javascript"');
+  });
+
+  test('highlights multiple code blocks', async () => {
+    const html = `
+      <pre><code class="language-js">let a = 1;</code></pre>
+      <p>Some text</p>
+      <pre><code class="language-ts">let b: number = 2;</code></pre>
+    `;
+    const result = await highlightHtmlBlocks(html, mockHighlight);
+    expect(result).toContain('LET A = 1;');
+    expect(result).toContain('LET B: NUMBER = 2;');
+    expect(result).toContain('Some text');
+  });
+
+  test('handles nested HTML structure', async () => {
+    const html = `
+      <div>
+        <section>
+          <pre><code>hello</code></pre>
+        </section>
+      </div>
+    `;
+    const result = await highlightHtmlBlocks(html, mockHighlight);
+    expect(result).toContain('HELLO');
+    expect(result).toContain('<div>');
+    expect(result).toContain('<section>');
+  });
+
+  test('skips pre tags without code children', async () => {
+    const html = '<pre>Just text, no code tag</pre>';
+    const result = await highlightHtmlBlocks(html, mockHighlight);
+    expect(result).toBe('<pre>Just text, no code tag</pre>');
+  });
+
+  test('skips code blocks with no text content', async () => {
+    const html = '<pre><code></code></pre>';
+    const result = await highlightHtmlBlocks(html, mockHighlight);
+    // Should not call highlight for empty code
+    expect(result).toContain('<pre>');
+    expect(result).toContain('<code>');
+  });
+
+  test('extracts language from multiple classes', async () => {
+    const html = '<pre><code class="foo language-python bar">print("hi")</code></pre>';
+    const result = await highlightHtmlBlocks(html, mockHighlight);
+    expect(result).toContain('PRINT("HI")');
+    expect(result).toContain('class="language-python"');
+  });
+
+  test('trims trailing whitespace from code text', async () => {
+    const html = '<pre><code>hello   \n\n</code></pre>';
+    const result = await highlightHtmlBlocks(html, mockHighlight);
+    expect(result).toContain('HELLO');
+    // The mock uppercases, so we know trimEnd() worked if there's no trailing whitespace
+  });
+});
+
+describe('rewriteAstroSetHtml', () => {
+  test('returns unchanged when no Fragment marker found', async () => {
+    const code = `const x = 1;\nconst y = 2;`;
+    const result = await rewriteAstroSetHtml(code, mockHighlight);
+    expect(result).toBe(code);
+  });
+
+  test('returns unchanged when marker found but no closing', async () => {
+    const code = `<_Fragment set:html={"<div>hello</div>`;
+    const result = await rewriteAstroSetHtml(code, mockHighlight);
+    expect(result).toBe(code);
+  });
+
+  test('returns unchanged when literal is empty', async () => {
+    const code = `<_Fragment set:html={} />`;
+    const result = await rewriteAstroSetHtml(code, mockHighlight);
+    expect(result).toBe(code);
+  });
+
+  test('returns unchanged when JSON is invalid', async () => {
+    const code = `<_Fragment set:html={not valid json} />`;
+    const result = await rewriteAstroSetHtml(code, mockHighlight);
+    expect(result).toBe(code);
+  });
+
+  test('highlights code blocks in Fragment', async () => {
+    const code = `<_Fragment set:html={"<pre><code>const x = 1;</code></pre>"} />`;
+    const result = await rewriteAstroSetHtml(code, mockHighlight);
+    expect(result).toContain('CONST X = 1;');
+    expect(result).toContain('<_Fragment set:html={');
+    expect(result).toContain('} />');
+  });
+
+  test('highlights multiple code blocks in Fragment', async () => {
+    const html = '<pre><code class="language-js">let a;</code></pre><pre><code class="language-ts">let b;</code></pre>';
+    const code = `<_Fragment set:html={${JSON.stringify(html)}} />`;
+    const result = await rewriteAstroSetHtml(code, mockHighlight);
+    expect(result).toContain('LET A;');
+    expect(result).toContain('LET B;');
+  });
+
+  test('preserves surrounding code', async () => {
+    const code = `
+      import { Fragment } from 'astro';
+
+      <div>
+        <_Fragment set:html={"<pre><code>hello</code></pre>"} />
+      </div>
+    `;
+    const result = await rewriteAstroSetHtml(code, mockHighlight);
+    expect(result).toContain("import { Fragment }");
+    expect(result).toContain('<div>');
+    expect(result).toContain('HELLO');
+    expect(result).toContain('</div>');
+  });
+
+  test('handles HTML with no code blocks', async () => {
+    const code = `<_Fragment set:html={"<div><p>No code here</p></div>"} />`;
+    const result = await rewriteAstroSetHtml(code, mockHighlight);
+    // Should still parse and serialize, result may differ slightly
+    expect(result).toContain('<_Fragment set:html={');
+    expect(result).toContain('No code here');
+  });
+
+  test('handles escaped quotes in JSON', async () => {
+    const html = '<pre><code>const str = \\"hello\\";</code></pre>';
+    const code = `<_Fragment set:html={${JSON.stringify(html)}} />`;
+    const result = await rewriteAstroSetHtml(code, mockHighlight);
+    expect(result).toContain('CONST STR');
+  });
+
+  test('processes ALL Fragment occurrences', async () => {
+    const code = `
+      <_Fragment set:html={"<pre><code>first</code></pre>"} />
+      <_Fragment set:html={"<pre><code>second</code></pre>"} />
+    `;
+    const result = await rewriteAstroSetHtml(code, mockHighlight);
+    // Both should be highlighted now
+    expect(result).toContain('FIRST');
+    expect(result).toContain('SECOND');
+  });
+});
+
+describe('highlightJsxCodeBlocks', () => {
+  test('returns unchanged when no pre tags', async () => {
+    const code = `<div>Hello world</div>`;
+    const result = await highlightJsxCodeBlocks(code, mockHighlight);
+    expect(result).toBe(code);
+  });
+
+  test('returns unchanged for empty code', async () => {
+    const result = await highlightJsxCodeBlocks('', mockHighlight);
+    expect(result).toBe('');
+  });
+
+  test('highlights JSX code block without language', async () => {
+    const code = `<pre><code>const x = 1;</code></pre>`;
+    const result = await highlightJsxCodeBlocks(code, mockHighlight);
+    expect(result).toContain('CONST X = 1;');
+  });
+
+  test('highlights JSX code block with language', async () => {
+    const code = `<pre><code class="language-js">let a = 1;</code></pre>`;
+    const result = await highlightJsxCodeBlocks(code, mockHighlight);
+    // Result is wrapped in set:html with JSON encoding
+    expect(result).toContain('set:html=');
+    expect(result).toContain('LET A = 1;');
+    expect(result).toContain('language-js');
+  });
+
+  test('decodes JSX string expressions', async () => {
+    // After html_entities_to_jsx(), code becomes {"string"} expressions
+    const code = `<pre><code class="language-js">{"const x = 1;"}</code></pre>`;
+    const result = await highlightJsxCodeBlocks(code, mockHighlight);
+    expect(result).toContain('CONST X = 1;');
+  });
+
+  test('decodes JSX expressions with newlines', async () => {
+    const code = `<pre><code class="language-js">{"line1"}{"\\n"}{"line2"}</code></pre>`;
+    const result = await highlightJsxCodeBlocks(code, mockHighlight);
+    // Result is wrapped in set:html to avoid raw { } in JSX context
+    expect(result).toContain('set:html=');
+    expect(result).toContain('LINE1');
+    expect(result).toContain('LINE2');
+  });
+
+  test('decodes HTML entities', async () => {
+    const code = `<pre><code>&lt;div&gt;&amp;amp;&lt;/div&gt;</code></pre>`;
+    const result = await highlightJsxCodeBlocks(code, mockHighlight);
+    expect(result).toContain('<DIV>&AMP;</DIV>');
+  });
+
+  test('skips already highlighted code blocks', async () => {
+    const code = `<pre class="shiki"><code>already highlighted</code></pre>`;
+    const result = await highlightJsxCodeBlocks(code, mockHighlight);
+    expect(result).toBe(code);
+  });
+
+  test('skips code blocks with data-language', async () => {
+    const code = `<pre data-language="js"><code>already highlighted</code></pre>`;
+    const result = await highlightJsxCodeBlocks(code, mockHighlight);
+    expect(result).toBe(code);
+  });
+
+  test('highlights multiple code blocks', async () => {
+    const code = `
+      <pre><code class="language-js">first</code></pre>
+      <p>text</p>
+      <pre><code class="language-ts">second</code></pre>
+    `;
+    const result = await highlightJsxCodeBlocks(code, mockHighlight);
+    expect(result).toContain('FIRST');
+    expect(result).toContain('SECOND');
+    expect(result).toContain('<p>text</p>');
+  });
+
+  test('preserves surrounding JSX', async () => {
+    const code = `
+      <TabItem>
+        <pre><code class="language-js">code here</code></pre>
+      </TabItem>
+    `;
+    const result = await highlightJsxCodeBlocks(code, mockHighlight);
+    expect(result).toContain('<TabItem>');
+    expect(result).toContain('CODE HERE');
+    expect(result).toContain('</TabItem>');
+  });
+
+  test('handles empty code blocks', async () => {
+    const code = `<pre><code class="language-js"></code></pre>`;
+    const result = await highlightJsxCodeBlocks(code, mockHighlight);
+    // Should not crash, should preserve the structure
+    expect(result).toContain('<pre>');
+  });
+
+  test('skips pre blocks inside set:html JSON strings', async () => {
+    // Simulate a set:html containing a <pre><code> block (already handled by rewriteAstroSetHtml)
+    const innerHtml = `<pre class="astro-code"><code class="language-js">const x = 1;</code></pre>`;
+    const code = `<_Fragment set:html={${JSON.stringify(innerHtml)}} />`;
+    const result = await highlightJsxCodeBlocks(code, mockHighlight);
+    // Should NOT be modified — the pre block is inside a JSON string
+    expect(result).toBe(code);
+  });
+
+  test('handles pre tag with attributes', async () => {
+    const code = `<pre class="astro-code" tabindex="0"><code class="language-sh"># comment</code></pre>`;
+    const result = await highlightJsxCodeBlocks(code, mockHighlight);
+    // Mock uppercases the code content, showing that highlighting was applied
+    // Result is wrapped in set:html with JSON encoding
+    expect(result).toContain('set:html=');
+    expect(result).toContain('# COMMENT');
+    expect(result).toContain('language-sh');
+  });
+});

package/src/transforms/shiki.ts

@@ -0,0 +1,312 @@
+/**
+ * Shiki syntax highlighting transforms for code blocks
+ * @module transforms/shiki
+ */
+
+import { parseFragment, serialize } from 'parse5';
+import type { DocumentFragment, Node, Element, TextNode } from '../vite-plugin/types.js';
+
+/**
+ * Shiki highlighter function type.
+ */
+export type ShikiHighlighter = (code: string, lang?: string) => Promise<string>;
+
+/**
+ * Walks an HTML AST tree and applies a visitor function to each node.
+ */
+function walk(node: Node, visit: (node: Node) => void): void {
+  visit(node);
+  if ('childNodes' in node && node.childNodes) {
+    for (const child of node.childNodes) {
+      walk(child, visit);
+    }
+  }
+}
+
+/**
+ * Gets an attribute value from an HTML AST node.
+ */
+function getAttr(node: Element, name: string): string | null {
+  const attrs = node.attrs || [];
+  const found = attrs.find((attr) => attr.name === name);
+  return found ? found.value : null;
+}
+
+/**
+ * Extracts text content from an HTML AST node recursively.
+ */
+function getText(node: Node): string {
+  if (!('childNodes' in node) || !node.childNodes) return '';
+  let text = '';
+  for (const child of node.childNodes) {
+    if (child.nodeName === '#text') {
+      text += (child as TextNode).value || '';
+    } else {
+      text += getText(child);
+    }
+  }
+  return text;
+}
+
+/**
+ * Highlights code blocks in HTML using Shiki syntax highlighter.
+ */
+export async function highlightHtmlBlocks(
+  html: string,
+  highlight: ShikiHighlighter
+): Promise<string> {
+  // PERF: Early skip if no <pre> tags exist (avoids expensive parse5 parsing)
+  if (!/<pre[\s>]/.test(html)) {
+    return html;
+  }
+
+  // Suppress parse5 warnings for JSX components in HTML
+  const fragment = parseFragment(html, {
+    onParseError: (error) => {
+      // Silently ignore end-tag-mismatch errors (typically from JSX in <p> tags)
+      if ((error.code as string) === 'end-tag-mismatch') {
+        return;
+      }
+      // Log other parse errors for debugging
+      console.warn('[xmdx] parse5 warning:', error);
+    },
+  }) as DocumentFragment;
+
+  const tasks: Promise<void>[] = [];
+
+  walk(fragment, (node) => {
+    if (node.nodeName !== 'pre') return;
+    const element = node as Element;
+    const codeNode = (element.childNodes || []).find(
+      (child): child is Element => child.nodeName === 'code'
+    );
+    if (!codeNode) return;
+
+    const codeText = getText(codeNode).trimEnd();
+    if (!codeText) return;
+    const classAttr = getAttr(codeNode, 'class') || '';
+    const lang = classAttr
+      .split(/\s+/)
+      .find((value) => value.startsWith('language-'))
+      ?.slice('language-'.length);
+
+    tasks.push(
+      highlight(codeText, lang).then((shikiHtml) => {
+        const highlighted = parseFragment(shikiHtml) as DocumentFragment;
+        const pre = (highlighted.childNodes || []).find(
+          (child): child is Element => child.nodeName === 'pre'
+        );
+        if (pre) {
+          element.nodeName = pre.nodeName;
+          element.tagName = pre.tagName;
+          element.attrs = pre.attrs;
+          element.childNodes = pre.childNodes;
+        }
+      })
+    );
+  });
+
+  if (tasks.length > 0) {
+    await Promise.all(tasks);
+  }
+  return serialize(fragment);
+}
+
+/**
+ * Checks if a position in the source code is inside a set:html={"..."} JSON string.
+ * This prevents double-highlighting of code blocks that were already processed
+ * by rewriteAstroSetHtml.
+ */
+function isInsideSetHtml(code: string, pos: number): boolean {
+  // Search backwards from pos for the nearest set:html={
+  const marker = 'set:html={';
+  let searchFrom = pos;
+  while (searchFrom > 0) {
+    const idx = code.lastIndexOf(marker, searchFrom - 1);
+    if (idx === -1) return false;
+
+    // Found a set:html={, now check if pos is before its closing } />
+    const jsonStart = idx + marker.length;
+    // The JSON string starts with " — find its end by tracking quotes
+    if (code[jsonStart] === '"') {
+      // Scan for the closing " that ends the JSON string, respecting escapes
+      let i = jsonStart + 1;
+      while (i < code.length) {
+        if (code[i] === '\\') {
+          i += 2; // Skip escaped character
+          continue;
+        }
+        if (code[i] === '"') {
+          // Found end of JSON string
+          const jsonEnd = i + 1; // Position after closing "
+          if (pos >= jsonStart && pos < jsonEnd) {
+            return true; // pos is inside this JSON string
+          }
+          break;
+        }
+        i++;
+      }
+    }
+    // Try searching further back
+    searchFrom = idx;
+  }
+  return false;
+}
+
+/**
+ * Highlights code blocks that appear directly in JSX (not in set:html).
+ * Handles cases where slot content with components is embedded directly,
+ * causing code blocks to bypass the set:html path.
+ *
+ * JSX code blocks appear as: <pre><code class="language-js">{"code"}</code></pre>
+ * After html_entities_to_jsx() content may be: {"line1"}{"\n"}{"line2"}
+ */
+export async function highlightJsxCodeBlocks(
+  code: string,
+  highlight: ShikiHighlighter
+): Promise<string> {
+  if (!code || typeof code !== 'string') {
+    return code;
+  }
+
+  // Early skip if no <pre> tags in JSX context
+  if (!/<pre[\s>]/.test(code)) {
+    return code;
+  }
+
+  // Match <pre> with optional attributes followed by <code class="language-xxx">content</code></pre>
+  // Content may contain JSX expressions like {"text"} or HTML entities
+  const preCodeRegex = /<pre[^>]*><code(?:\s+class="language-([^"]*)")?>([\s\S]*?)<\/code><\/pre>/g;
+
+  // Phase 1: Collect all code blocks to highlight (no await in loop)
+  const toHighlight: Array<{
+    fullMatch: string;
+    lang: string | undefined;
+    codeText: string;
+  }> = [];
+
+  let match;
+  while ((match = preCodeRegex.exec(code)) !== null) {
+    const [fullMatch, lang, rawContent = ''] = match;
+
+    // Skip if already processed by Shiki (has shiki class or data-language)
+    if (fullMatch.includes('class="shiki') || fullMatch.includes('data-language')) {
+      continue;
+    }
+
+    // Skip if this <pre> is inside a set:html JSON string (already handled by rewriteAstroSetHtml)
+    if (isInsideSetHtml(code, match.index)) {
+      continue;
+    }
+
+    // Skip empty code blocks
+    if (!rawContent) {
+      continue;
+    }
+
+    // Decode JSX expressions back to plain text
+    // Pattern: {"string"} or {"\n"} etc.
+    let codeText = rawContent
+      // Decode JSX string expressions: {"text"} -> text
+      .replace(/\{"([^"]*)"\}/g, (_, str) => {
+        // Handle escape sequences
+        return str
+          .replace(/\\n/g, '\n')
+          .replace(/\\t/g, '\t')
+          .replace(/\\r/g, '\r')
+          .replace(/\\\\/g, '\\')
+          .replace(/\\"/g, '"');
+      })
+      // Decode HTML entities that might remain
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&amp;/g, '&')
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'")
+      .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) =>
+        String.fromCharCode(parseInt(hex, 16))
+      )
+      .replace(/&#(\d+);/g, (_, num) =>
+        String.fromCharCode(parseInt(num, 10))
+      );
+
+    // Trim trailing whitespace but preserve internal structure
+    codeText = codeText.trimEnd();
+
+    if (!codeText) {
+      continue;
+    }
+
+    toHighlight.push({ fullMatch, lang, codeText });
+  }
+
+  if (toHighlight.length === 0) {
+    return code;
+  }
+
+  // Phase 2: Highlight all code blocks in parallel
+  const highlighted = await Promise.all(
+    toHighlight.map(({ codeText, lang }) => highlight(codeText, lang || undefined))
+  );
+
+  // Phase 3: Build replacements and apply them
+  let result = code;
+  for (let i = 0; i < toHighlight.length; i++) {
+    const { fullMatch } = toHighlight[i]!;
+    const highlightedHtml = highlighted[i]!;
+    // Wrap in set:html to avoid raw { } in JSX context being parsed as expressions
+    const replacement = `<_Fragment set:html={${JSON.stringify(highlightedHtml)}} />`;
+    result = result.replace(fullMatch, replacement);
+  }
+
+  return result;
+}
+
+/**
+ * Rewrites Astro set:html fragments with Shiki-highlighted code.
+ * Searches for <_Fragment set:html={...} /> patterns and applies syntax highlighting.
+ * Processes ALL occurrences in the code, not just the first one.
+ */
+export async function rewriteAstroSetHtml(
+  code: string,
+  highlight: ShikiHighlighter
+): Promise<string> {
+  if (!code || typeof code !== 'string') {
+    return code;
+  }
+
+  const marker = '<_Fragment set:html={';
+  let result = code;
+  let searchStart = 0;
+
+  // Process ALL occurrences in a loop
+  while (true) {
+    const idx = result.indexOf(marker, searchStart);
+    if (idx === -1) break;
+
+    const start = idx + marker.length;
+    const end = result.indexOf('} />', start);
+    if (end === -1) break;
+
+    const literal = result.slice(start, end).trim();
+    if (!literal) {
+      searchStart = end;
+      continue;
+    }
+
+    let html: string;
+    try {
+      html = JSON.parse(literal) as string;
+    } catch {
+      searchStart = end;
+      continue;
+    }
+
+    const rewritten = await highlightHtmlBlocks(html, highlight);
+    const encoded = JSON.stringify(rewritten);
+    result = result.slice(0, start) + encoded + result.slice(end);
+    searchStart = start + encoded.length + 4; // Move past this occurrence
+  }
+
+  return result;
+}

package/src/types.ts

@@ -0,0 +1,92 @@
+/**
+ * Type definitions for Xmdx plugin system
+ * @module types
+ */
+
+import type { Registry } from 'xmdx/registry';
+import type { ExpressiveCodeConfig, StarlightUserConfig } from './utils/config.js';
+import type { ShikiHighlighter } from './transforms/shiki.js';
+
+/**
+ * Configuration available to transforms.
+ */
+export interface TransformConfig {
+  /** ExpressiveCode configuration or null if disabled */
+  expressiveCode: ExpressiveCodeConfig | null;
+  /** Starlight components configuration */
+  starlightComponents: boolean | StarlightUserConfig;
+  /** Shiki highlighter function or null if disabled */
+  shiki: ShikiHighlighter | null;
+}
+
+/**
+ * Transform context passed through the pipeline.
+ * Contains the current code state and metadata needed by transforms.
+ */
+export interface TransformContext {
+  /** Current JSX code being transformed */
+  code: string;
+  /** Original markdown source */
+  source: string;
+  /** Source file path */
+  filename: string;
+  /** Parsed frontmatter object */
+  frontmatter: Record<string, unknown>;
+  /** Extracted headings from the document */
+  headings: Array<{ depth: number; slug: string; text: string }>;
+  /** Component registry for import resolution */
+  registry?: Registry;
+  /** Plugin configuration for transforms */
+  config: TransformConfig;
+}
+
+/**
+ * A Xmdx plugin that can hook into the transform pipeline.
+ */
+export interface XmdxPlugin {
+  /** Plugin identifier for debugging and ordering */
+  name: string;
+  /** Execution order: 'pre' runs before built-in transforms, 'post' runs after */
+  enforce?: 'pre' | 'post';
+  /** Hook called after markdown is parsed to JSX, before any transforms */
+  afterParse?: (ctx: TransformContext) => TransformContext | Promise<TransformContext>;
+  /** Hook called before component injection transforms */
+  beforeInject?: (ctx: TransformContext) => TransformContext | Promise<TransformContext>;
+  /** Hook called after all transforms, before esbuild */
+  beforeOutput?: (ctx: TransformContext) => TransformContext | Promise<TransformContext>;
+  /** Hook to preprocess raw markdown source before parsing */
+  preprocess?: (source: string, filename: string) => string;
+}
+
+/**
+ * Collected hooks from plugins, organized by hook type.
+ */
+export interface PluginHooks {
+  afterParse: Array<(ctx: TransformContext) => TransformContext | Promise<TransformContext>>;
+  beforeInject: Array<(ctx: TransformContext) => TransformContext | Promise<TransformContext>>;
+  beforeOutput: Array<(ctx: TransformContext) => TransformContext | Promise<TransformContext>>;
+  preprocess: Array<(source: string, filename: string) => string>;
+}
+
+/**
+ * Options for handling MDX import/export statements.
+ * Allows fine-grained control over which imports are allowed vs trigger fallback.
+ */
+export interface MdxImportHandlingOptions {
+  /**
+   * Import sources to allow. Files importing only from these sources
+   * won't trigger fallback to @mdx-js/mdx.
+   * Supports glob patterns (e.g., '~/components/*').
+   * @example ['@astrojs/starlight/components', '~/components/*']
+   */
+  allowImports?: string[];
+  /**
+   * Ignore import/export patterns inside code fences when detecting fallback.
+   * @default true
+   */
+  ignoreCodeFences?: boolean;
+}
+
+// Re-export types from submodules for convenience
+export type { ExpressiveCodeConfig, StarlightUserConfig } from './utils/config.js';
+export type { ShikiHighlighter } from './transforms/shiki.js';