astro-xmdx 0.0.2

package/src/vite-plugin/shiki-manager.ts

@@ -0,0 +1,53 @@
+/**
+ * Manages Shiki highlighter lifecycle as a lazy singleton.
+ * @module vite-plugin/shiki-manager
+ */
+
+import { createShikiHighlighter } from './shiki-highlighter.js';
+import type { ShikiHighlighter } from '../transforms/shiki.js';
+
+export class ShikiManager {
+  private instance: Promise<ShikiHighlighter> | undefined;
+  private enabled: boolean;
+
+  constructor(enabled: boolean) {
+    this.enabled = enabled;
+  }
+
+  /**
+   * Returns the Shiki highlighter promise, initializing on first call.
+   * Returns null if Shiki is disabled or code has no `<pre>` tags.
+   */
+  async getFor(code: string): Promise<ShikiHighlighter | null> {
+    if (!this.enabled || !ShikiManager.hasCodeBlocks(code)) return null;
+    if (!this.instance) {
+      this.instance = createShikiHighlighter();
+    }
+    return this.instance.catch(() => null);
+  }
+
+  /**
+   * Eagerly initializes the highlighter (e.g. in buildStart).
+   * Returns the resolved highlighter or null.
+   */
+  async init(): Promise<ShikiHighlighter | null> {
+    if (!this.enabled) return null;
+    if (!this.instance) {
+      this.instance = createShikiHighlighter();
+    }
+    return this.instance.catch(() => null);
+  }
+
+  /**
+   * Returns the already-resolved highlighter for code with pre tags,
+   * using a pre-resolved instance to avoid extra awaits in hot paths.
+   */
+  forCode(code: string, resolved: ShikiHighlighter | null): ShikiHighlighter | null {
+    if (!this.enabled || !resolved || !ShikiManager.hasCodeBlocks(code)) return null;
+    return resolved;
+  }
+
+  static hasCodeBlocks(code: string): boolean {
+    return /<pre[\s>]/.test(code);
+  }
+}

package/src/vite-plugin/types.ts

@@ -0,0 +1,189 @@
+/**
+ * Type definitions for the Xmdx Vite plugin
+ * @module vite-plugin/types
+ */
+
+import type { DefaultTreeAdapterMap } from 'parse5';
+import type { ComponentLibrary } from 'xmdx/registry';
+import type { XmdxPlugin, MdxImportHandlingOptions } from '../types.js';
+
+// Parse5 DOM types
+export type DocumentFragment = DefaultTreeAdapterMap['documentFragment'];
+export type Node = DefaultTreeAdapterMap['node'];
+export type Element = DefaultTreeAdapterMap['element'];
+export type TextNode = DefaultTreeAdapterMap['textNode'];
+
+/**
+ * Native NAPI binding interface for Xmdx compiler.
+ */
+export interface XmdxBinding {
+  createCompiler?: (config: Record<string, unknown>) => XmdxCompiler;
+  XmdxCompiler?: new (config: Record<string, unknown>) => XmdxCompiler;
+  compileBatch: (
+    inputs: Array<{ id: string; source: string; filepath?: string }>,
+    options: { continueOnError: boolean; config: Record<string, unknown> }
+  ) => BatchCompileResult;
+  compileBatchToModule: (
+    inputs: Array<{ id: string; source: string; filepath?: string }>,
+    options: { continueOnError: boolean; config: Record<string, unknown> }
+  ) => ModuleBatchCompileResult;
+  compileMdxBatch: (
+    inputs: Array<{ id: string; source: string; filepath?: string }>,
+    options: { continueOnError: boolean; config: Record<string, unknown> }
+  ) => MdxBatchCompileResult;
+  parseBlocks: (
+    source: string,
+    options: { enable_directives: boolean }
+  ) => ParseBlocksResult;
+  parseFrontmatter: (source: string) => { frontmatter: Record<string, unknown> };
+}
+
+/**
+ * Compiler instance for single-file compilation.
+ */
+export interface XmdxCompiler {
+  compile: (
+    source: string,
+    filename: string,
+    options: { file?: string; url?: string }
+  ) => CompileResult;
+}
+
+/**
+ * Result from single-file compilation.
+ */
+export interface CompileResult {
+  code: string;
+  map?: unknown;
+  frontmatter_json?: string;
+  headings?: Array<{ depth: number; slug: string; text: string }>;
+  imports?: Array<{ path: string }>;
+  diagnostics?: {
+    warnings?: Array<{ line: number; message: string }>;
+  };
+}
+
+/**
+ * Export specification from Rust compiler.
+ */
+export interface ExportSpec {
+  source: string;
+  isDefault: boolean;
+}
+
+/**
+ * Result from batch compilation.
+ */
+export interface BatchCompileResult {
+  results: Array<{
+    id: string;
+    result?: {
+      html: string;
+      frontmatterJson?: string;
+      headings?: Array<{ depth: number; slug: string; text: string }>;
+      hoistedImports?: Array<{ source: string; kind: string }>;
+      hoistedExports?: ExportSpec[];
+      hasUserDefaultExport?: boolean;
+    };
+  }>;
+  stats: {
+    succeeded: number;
+    total: number;
+    processingTimeMs: number;
+  };
+}
+
+/**
+ * Result from batch compilation to complete Astro modules.
+ * Unlike BatchCompileResult which returns IR, this returns complete module code.
+ */
+export interface ModuleBatchCompileResult {
+  results: Array<{
+    id: string;
+    result?: {
+      /** Complete Astro module code ready for esbuild */
+      code: string;
+      /** Source map (if available) */
+      map?: unknown;
+      /** Frontmatter as JSON string */
+      frontmatterJson: string;
+      /** Extracted headings */
+      headings: Array<{ depth: number; slug: string; text: string }>;
+      /** Imported modules */
+      imports: Array<{ path: string; kind: string }>;
+      /** Parse diagnostics */
+      diagnostics?: {
+        warnings?: Array<{ line: number; message: string }>;
+      };
+    };
+    error?: string;
+  }>;
+  stats: {
+    succeeded: number;
+    total: number;
+    failed: number;
+    processingTimeMs: number;
+  };
+}
+
+/**
+ * Result from MDX batch compilation using mdxjs-rs.
+ */
+export interface MdxBatchCompileResult {
+  results: Array<{
+    id: string;
+    result?: {
+      /** Compiled JavaScript code (full module with MDXContent) */
+      code: string;
+      /** Frontmatter as JSON string */
+      frontmatterJson: string;
+      /** Extracted headings */
+      headings: Array<{ depth: number; slug: string; text: string }>;
+    };
+    error?: string;
+  }>;
+  stats: {
+    succeeded: number;
+    total: number;
+    failed: number;
+    processingTimeMs: number;
+  };
+}
+
+/**
+ * Result from parsing blocks.
+ */
+/** A render block from the Rust compiler. */
+export interface RenderBlockData {
+  type: 'html' | 'component' | 'code';
+  content?: string;
+  name?: string;
+  props?: Record<string, unknown>;
+  slotChildren?: RenderBlockData[];
+  code?: string;
+  lang?: string;
+  meta?: string;
+}
+
+export interface ParseBlocksResult {
+  blocks: RenderBlockData[];
+  headings: Array<{ depth: number; slug: string; text: string }>;
+}
+
+/**
+ * Plugin options for the Xmdx Vite plugin.
+ */
+export interface XmdxPluginOptions {
+  include?: (id: string) => boolean;
+  libraries?: ComponentLibrary[];
+  starlightComponents?: boolean | { enabled?: boolean; components?: string[]; module?: string };
+  expressiveCode?: boolean | { enabled?: boolean; component?: string; module?: string };
+  compiler?: {
+    jsx?: {
+      code_sample_components?: string[];
+    };
+  };
+  plugins?: XmdxPlugin[];
+  binding?: XmdxBinding;
+  mdx?: MdxImportHandlingOptions;
+}