@hcu-lab.me/mcp-device 1.0.0

package/dist/tools/pdf/extract-images.js

@@ -0,0 +1,132 @@
+import { getDocumentProxy, extractImages } from 'unpdf';
+/**
+ * Optimized image extraction from PDF using unpdf's built-in extractImages method
+ * @param pdfBuffer PDF file as Uint8Array
+ * @param pageNumbers Optional array of specific page numbers to process
+ * @param compressionOptions Image compression settings
+ * @returns Record of page numbers to extracted images
+ */
+export async function extractImagesFromPdf(pdfBuffer, pageNumbers, compressionOptions = {}) {
+    const pdfDocument = await getDocumentProxy(pdfBuffer);
+    const pagesToProcess = pageNumbers || Array.from({ length: pdfDocument.numPages }, (_, i) => i + 1);
+    const pageResults = {};
+    try {
+        // Process pages in parallel batches for better performance
+        const batchSize = 5; // Process 5 pages at a time
+        const batches = [];
+        for (let i = 0; i < pagesToProcess.length; i += batchSize) {
+            batches.push(pagesToProcess.slice(i, i + batchSize));
+        }
+        for (let batchIndex = 0; batchIndex < batches.length; batchIndex++) {
+            const batch = batches[batchIndex];
+            const batchPromises = batch.map(async (pageNum) => {
+                if (pageNum < 1 || pageNum > pdfDocument.numPages) {
+                    return { pageNum, images: [] };
+                }
+                try {
+                    // Use unpdf's built-in extractImages
+                    const extractedImages = await extractImages(pdfDocument, pageNum);
+                    const pageImages = [];
+                    for (let index = 0; index < extractedImages.length; index++) {
+                        const img = extractedImages[index];
+                        const originalSize = img.data.length;
+                        try {
+                            const compressionResult = await convertRawImageToBase64(img.data, img.width, img.height, img.channels, compressionOptions);
+                            if (compressionResult) {
+                                pageImages.push({
+                                    objId: index, // Use index as objId since unpdf doesn't provide original objId
+                                    width: img.width,
+                                    height: img.height,
+                                    data: compressionResult.data,
+                                    mimeType: compressionResult.mimeType,
+                                    originalSize,
+                                    compressedSize: Math.round(compressionResult.data.length * 0.75) // Approximate base64 overhead
+                                });
+                            }
+                        }
+                        catch (err) {
+                            // Ignore conversion errors as requested
+                            console.warn(`Failed to convert image ${index} on page ${pageNum}:`, err instanceof Error ? err.message : String(err));
+                        }
+                    }
+                    return { pageNum, images: pageImages };
+                }
+                catch (error) {
+                    console.warn(`Failed to extract images from page ${pageNum}:`, error instanceof Error ? error.message : String(error));
+                    return { pageNum, images: [] };
+                }
+            });
+            // Wait for the current batch to complete
+            const batchResults = await Promise.all(batchPromises);
+            // Store results
+            for (const { pageNum, images } of batchResults) {
+                pageResults[pageNum] = images;
+            }
+        }
+    }
+    finally {
+        // Clean up document
+        try {
+            if (typeof pdfDocument.cleanup === 'function') {
+                await pdfDocument.cleanup(false);
+            }
+        }
+        catch (e) { /* Ignore cleanup errors */ }
+        try {
+            if (typeof pdfDocument.destroy === 'function') {
+                await pdfDocument.destroy();
+            }
+        }
+        catch (e) { /* Ignore cleanup errors */ }
+    }
+    return pageResults;
+}
+/**
+ * Convert raw image data to compressed base64 using sharp
+ */
+async function convertRawImageToBase64(data, width, height, channels, options = {}) {
+    const { format = 'webp', quality = 85, maxDimension = 1200 } = options;
+    // Smart resizing - only resize large images
+    let targetWidth = width;
+    let targetHeight = height;
+    if (width > maxDimension || height > maxDimension) {
+        const scale = maxDimension / Math.max(width, height);
+        targetWidth = Math.round(width * scale);
+        targetHeight = Math.round(height * scale);
+    }
+    try {
+        // Try to dynamically import sharp
+        const sharp = (await import('sharp')).default;
+        // sharp takes Buffer, Uint8Array, etc.
+        // unpdf returns Uint8ClampedArray, which works with Buffer.from()
+        let pipeline = sharp(Buffer.from(data), {
+            raw: {
+                width,
+                height,
+                channels: channels
+            }
+        });
+        if (targetWidth !== width || targetHeight !== height) {
+            pipeline = pipeline.resize(targetWidth, targetHeight);
+        }
+        let outputBuffer;
+        let mimeType;
+        if (format === 'jpeg') {
+            outputBuffer = await pipeline.jpeg({ quality }).toBuffer();
+            mimeType = 'image/jpeg';
+        }
+        else {
+            // Default to webp
+            outputBuffer = await pipeline.webp({ quality }).toBuffer();
+            mimeType = 'image/webp';
+        }
+        return {
+            data: outputBuffer.toString('base64'),
+            mimeType
+        };
+    }
+    catch (error) {
+        console.warn('Image conversion failed (likely missing sharp or invalid data):', error instanceof Error ? error.message : String(error));
+        return null;
+    }
+}

package/dist/tools/pdf/index.d.ts

@@ -0,0 +1,6 @@
+export { editPdf } from './manipulations.js';
+export type { PdfOperations, PdfInsertOperation, PdfDeleteOperation } from './manipulations.js';
+export { parsePdfToMarkdown, parseMarkdownToPdf } from './markdown.js';
+export type { PdfMetadata, PdfPageItem } from './lib/pdf2md.js';
+export { extractImagesFromPdf } from './extract-images.js';
+export type { ImageInfo, PageImages } from './extract-images.js';

package/dist/tools/pdf/index.js

@@ -0,0 +1,3 @@
+export { editPdf } from './manipulations.js';
+export { parsePdfToMarkdown, parseMarkdownToPdf } from './markdown.js';
+export { extractImagesFromPdf } from './extract-images.js';

package/dist/tools/pdf/lib/pdf2md.d.ts

@@ -0,0 +1,36 @@
+import { ImageInfo } from '../extract-images.js';
+/**
+ * PDF metadata structure
+ */
+export interface PdfMetadata {
+    fileSize?: number;
+    totalPages: number;
+    title?: string;
+    author?: string;
+    creator?: string;
+    producer?: string;
+    version?: string;
+    creationDate?: string;
+    modificationDate?: string;
+    isEncrypted?: boolean;
+}
+export interface PdfPageItem {
+    text: string;
+    images: ImageInfo[];
+    pageNumber: number;
+}
+export interface PdfParseResult {
+    pages: PdfPageItem[];
+    metadata: PdfMetadata;
+}
+export type PageRange = {
+    offset: number;
+    length: number;
+};
+/**
+ * Reads a PDF and converts it to Markdown, returning structured data.
+ * @param pdfBuffer The PDF buffer to convert.
+ * @param pageNumbers The page numbers to extract. If empty, all pages are extracted.
+ * @returns A Promise that resolves to a PdfParseResult object containing the parsed data.
+ */
+export declare function pdf2md(pdfBuffer: Uint8Array, pageNumbers?: number[] | PageRange): Promise<PdfParseResult>;

package/dist/tools/pdf/lib/pdf2md.js

@@ -0,0 +1,76 @@
+import { createRequire } from 'module';
+import { generatePageNumbers } from '../utils.js';
+import { extractImagesFromPdf } from '../extract-images.js';
+const require = createRequire(import.meta.url);
+const { parse } = require('@opendocsg/pdf2md/lib/util/pdf');
+const { makeTransformations, transform } = require('@opendocsg/pdf2md/lib/util/transformations');
+/**
+ * Extracts metadata from a PDF document.
+ * @param pdfDocument The PDF document to extract metadata from.
+ * @returns A PdfMetadata object containing the extracted metadata.
+ */
+const extractMetadata = ({ pdfDocument, metadata }) => ({
+    totalPages: pdfDocument.numPages,
+    title: metadata.Title,
+    author: metadata.Author,
+    creator: metadata.Creator,
+    producer: metadata.Producer,
+    version: metadata.PDFFormatVersion,
+    creationDate: metadata.CreationDate,
+    modificationDate: metadata.ModDate,
+    isEncrypted: metadata.IsEncrypted,
+});
+/**
+ * Reads a PDF and converts it to Markdown, returning structured data.
+ * @param pdfBuffer The PDF buffer to convert.
+ * @param pageNumbers The page numbers to extract. If empty, all pages are extracted.
+ * @returns A Promise that resolves to a PdfParseResult object containing the parsed data.
+ */
+export async function pdf2md(pdfBuffer, pageNumbers = []) {
+    const result = await parse(pdfBuffer);
+    const { fonts, pages, pdfDocument } = result;
+    // Calculate which pages to process
+    const filterPageNumbers = Array.isArray(pageNumbers) ?
+        pageNumbers :
+        generatePageNumbers(pageNumbers.offset, pageNumbers.length, pages.length);
+    // Filter and transform pages
+    const pagesToProcess = filterPageNumbers.length === 0 ?
+        pages :
+        pages.filter((_, index) => filterPageNumbers.includes(index + 1));
+    const pageNumberMap = filterPageNumbers.length === 0 ?
+        pages.map((_, index) => index + 1) :
+        filterPageNumbers.filter(pageNum => pageNum >= 1 && pageNum <= pages.length);
+    const transformations = makeTransformations(fonts.map);
+    const parseResult = transform(pagesToProcess, transformations);
+    // Extract images
+    const imagesByPage = await extractImagesFromPdf(pdfBuffer, pageNumberMap, { format: 'webp', quality: 85 });
+    // Create pages without images for now
+    const processedPages = parseResult.pages.map((page, index) => {
+        const pageNumber = pageNumberMap[index];
+        return {
+            pageNumber,
+            text: page.items.join('\n') + '\n',
+            images: imagesByPage[pageNumber] || [],
+        };
+    });
+    const metadata = extractMetadata(result);
+    try {
+        return { pages: processedPages, metadata };
+    }
+    finally {
+        if (pdfDocument) {
+            try {
+                if (typeof pdfDocument.cleanup === 'function') {
+                    await pdfDocument.cleanup(false);
+                }
+            }
+            catch (e) { }
+            try {
+                if (typeof pdfDocument.destroy === 'function') {
+                    await pdfDocument.destroy();
+                }
+            }
+            catch (e) { }
+        }
+    }
+}

package/dist/tools/pdf/manipulations.d.ts

@@ -0,0 +1,13 @@
+import type { PdfInsertOperationSchema, PdfDeleteOperationSchema, PdfOperationSchema } from '../schemas.js';
+import { z } from 'zod';
+type PdfInsertOperation = z.infer<typeof PdfInsertOperationSchema>;
+type PdfDeleteOperation = z.infer<typeof PdfDeleteOperationSchema>;
+type PdfOperations = z.infer<typeof PdfOperationSchema>;
+export type { PdfOperations, PdfInsertOperation, PdfDeleteOperation };
+/**
+ * Edit an existing PDF by deleting or inserting pages
+ * @param pdfPath Path to the PDF file to edit
+ * @param operations List of operations to perform
+ * @returns The modified PDF as a Uint8Array
+ */
+export declare function editPdf(pdfPath: string, operations: PdfOperations[]): Promise<Uint8Array>;

package/dist/tools/pdf/manipulations.js

@@ -0,0 +1,99 @@
+import fs from 'fs/promises';
+import { createRequire } from 'module';
+import { normalizePageIndexes } from './utils.js';
+import { parseMarkdownToPdf } from './markdown.js';
+// Use createRequire to load pdf-lib as CJS (works around Node 25 ESM resolution issues)
+const require = createRequire(import.meta.url);
+const { PDFDocument } = require('pdf-lib');
+async function loadPdfDocumentFromBuffer(filePathOrBuffer) {
+    const buffer = typeof filePathOrBuffer === 'string' ? await fs.readFile(filePathOrBuffer) : filePathOrBuffer;
+    const pdfBytes = new Uint8Array(buffer);
+    return await PDFDocument.load(pdfBytes);
+}
+/**
+ * Delete pages from a PDF document
+ * @param pdfDoc PDF document to delete pages from
+ * @param pageIndexes Page indices to delete, negative indices are from end
+ */
+function deletePages(pdfDoc, pageIndexes) {
+    const pageCount = pdfDoc.getPageCount();
+    // Transform negative indices to absolute and filter valid ones
+    const normalizedIndexes = normalizePageIndexes(pageIndexes, pageCount).sort((a, b) => b - a);
+    for (const pageIndex of normalizedIndexes) {
+        pdfDoc.removePage(pageIndex);
+    }
+    return pdfDoc;
+}
+function getPageLayout(page) {
+    const { width, height } = page.getSize();
+    const mediaBox = page.getMediaBox(); // Full page area
+    const cropBox = page.getCropBox(); // Visible area (may indicate margins)
+    // Calculate margins (if CropBox differs from MediaBox)
+    let marginLeft = cropBox.x - mediaBox.x;
+    let marginBottom = cropBox.y - mediaBox.y;
+    let marginRight = (mediaBox.x + mediaBox.width) - (cropBox.x + cropBox.width);
+    let marginTop = (mediaBox.y + mediaBox.height) - (cropBox.y + cropBox.height);
+    if (marginLeft === 0 && marginRight === 0 && marginTop === 0 && marginBottom === 0) {
+        marginLeft = 72;
+        marginBottom = 72;
+        marginRight = 72;
+        marginTop = 72;
+    }
+    // Convert points to inches (1 inch = 72 points)
+    // Puppeteer requires standard units and doesn't accept decimal points
+    const pointsToInches = (pts) => (pts / 72).toFixed(4);
+    return {
+        format: undefined, // Explicitly disable format to use custom dimensions
+        width: `${pointsToInches(width)}in`,
+        height: `${pointsToInches(height)}in`,
+        margin: {
+            top: `${pointsToInches(marginTop)}in`,
+            right: `${pointsToInches(marginRight)}in`,
+            bottom: `${pointsToInches(marginBottom)}in`,
+            left: `${pointsToInches(marginLeft)}in`
+        }
+    };
+}
+async function insertPages(destPdfDocument, pageIndex, sourcePdfDocument) {
+    let insertPosition = pageIndex < 0 ? destPdfDocument.getPageCount() + pageIndex : pageIndex;
+    if (insertPosition < 0 || insertPosition > destPdfDocument.getPageCount()) {
+        throw new Error('Invalid page index');
+    }
+    const copiedPages = await destPdfDocument.copyPages(sourcePdfDocument, sourcePdfDocument.getPageIndices());
+    for (let i = 0; i < copiedPages.length; i++) {
+        destPdfDocument.insertPage(insertPosition + i, copiedPages[i]);
+    }
+    return destPdfDocument;
+}
+/**
+ * Edit an existing PDF by deleting or inserting pages
+ * @param pdfPath Path to the PDF file to edit
+ * @param operations List of operations to perform
+ * @returns The modified PDF as a Uint8Array
+ */
+export async function editPdf(pdfPath, operations) {
+    const pdfDoc = await loadPdfDocumentFromBuffer(pdfPath);
+    // Get page layout from the ORIGINAL first page
+    const pageLayout = pdfDoc.getPageCount() > 0 ? getPageLayout(pdfDoc.getPage(0)) : undefined;
+    for (const op of operations) {
+        if (op.type === 'delete') {
+            deletePages(pdfDoc, op.pageIndexes);
+        }
+        else if (op.type == 'insert') {
+            let sourcePdfDocument;
+            if (op.markdown !== undefined) {
+                const pdfOptions = pageLayout ? { pdf_options: pageLayout } : undefined;
+                const pdfBuffer = await parseMarkdownToPdf(op.markdown, pdfOptions);
+                sourcePdfDocument = await loadPdfDocumentFromBuffer(pdfBuffer);
+            }
+            else if (op.sourcePdfPath) {
+                sourcePdfDocument = await loadPdfDocumentFromBuffer(op.sourcePdfPath);
+            }
+            else {
+                throw new Error('No source provided for insert operation');
+            }
+            await insertPages(pdfDoc, op.pageIndex, sourcePdfDocument);
+        }
+    }
+    return await pdfDoc.save();
+}

package/dist/tools/pdf/markdown.d.ts

@@ -0,0 +1,26 @@
+import type { PageRange } from './lib/pdf2md.js';
+import { PdfParseResult } from './lib/pdf2md.js';
+interface CachedPuppeteerChrome {
+    executablePath: string;
+}
+/**
+ * Find Chrome in puppeteer's cache directory
+ * Returns the executable path if found, undefined otherwise
+ */
+export declare function findPuppeteerChrome(cacheDir?: string): CachedPuppeteerChrome | undefined;
+/**
+ * Remove stale Puppeteer Chrome builds while preserving the active build.
+ */
+export declare function pruneOldPuppeteerChromeBuilds(activeExecutablePath: string, cacheDir?: string): Promise<void>;
+/**
+ * Preemptively ensure Chrome is available for PDF generation.
+ * Call this at server startup to trigger download in background if needed.
+ * Returns immediately, download happens in background.
+ */
+export declare function ensureChromeAvailable(): void;
+/**
+ * Convert PDF to Markdown using @opendocsg/pdf2md
+ */
+export declare function parsePdfToMarkdown(source: string, pageNumbers?: number[] | PageRange): Promise<PdfParseResult>;
+export declare function parseMarkdownToPdf(markdown: string, options?: any): Promise<Buffer>;
+export {};

package/dist/tools/pdf/markdown.js

@@ -0,0 +1,275 @@
+import fs from 'fs/promises';
+import { existsSync, readdirSync } from 'fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'path';
+import { mdToPdf } from 'md-to-pdf';
+import { pdf2md } from './lib/pdf2md.js';
+import { CONFIG_FILE } from '../../config.js';
+const isUrl = (source) => source.startsWith('http://') || source.startsWith('https://');
+// Cached Chrome path to avoid repeated lookups
+let cachedChromePath = null; // null = not checked yet
+let chromeCheckPromise = null;
+/**
+ * Get Desktop Commander's private Puppeteer cache directory.
+ */
+function getPuppeteerCacheDir() {
+    return join(dirname(CONFIG_FILE), 'puppeteer-cache');
+}
+/**
+ * Get the cache path where Puppeteer stores Chrome for Testing builds.
+ */
+function getPuppeteerChromeDir(cacheDir = getPuppeteerCacheDir()) {
+    return join(cacheDir, 'chrome');
+}
+/**
+ * Find the platform-specific executable within a cached Chrome build directory.
+ */
+function getChromeExecutablePath(chromeDir, version) {
+    const chromePath = process.platform === 'win32'
+        ? join(chromeDir, version, 'chrome-win64', 'chrome.exe')
+        : process.platform === 'darwin'
+            ? join(chromeDir, version, 'chrome-mac-x64', 'Google Chrome for Testing.app', 'Contents', 'MacOS', 'Google Chrome for Testing')
+            : join(chromeDir, version, 'chrome-linux64', 'chrome');
+    if (existsSync(chromePath)) {
+        return chromePath;
+    }
+    // Also check for arm64 mac
+    if (process.platform === 'darwin') {
+        const armPath = join(chromeDir, version, 'chrome-mac-arm64', 'Google Chrome for Testing.app', 'Contents', 'MacOS', 'Google Chrome for Testing');
+        if (existsSync(armPath)) {
+            return armPath;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve the cached Chrome build directory that owns an executable path.
+ */
+function getCachedChromeBuildDir(chromeDir, executablePath) {
+    const relativePath = relative(chromeDir, executablePath);
+    if (relativePath === '..' || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
+        return undefined;
+    }
+    const [buildDir] = relativePath.split(sep);
+    return buildDir ? join(chromeDir, buildDir) : undefined;
+}
+/**
+ * Find Chrome in puppeteer's cache directory
+ * Returns the executable path if found, undefined otherwise
+ */
+export function findPuppeteerChrome(cacheDir = getPuppeteerCacheDir()) {
+    const chromeDir = getPuppeteerChromeDir(cacheDir);
+    if (!existsSync(chromeDir)) {
+        return undefined;
+    }
+    try {
+        // Look for chrome directories (e.g., win64-143.0.7499.169)
+        const versions = readdirSync(chromeDir, { withFileTypes: true })
+            .filter(entry => entry.isDirectory())
+            .map(entry => entry.name)
+            .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+        for (const version of versions) {
+            const executablePath = getChromeExecutablePath(chromeDir, version);
+            if (executablePath) {
+                return { executablePath };
+            }
+        }
+    }
+    catch {
+        // Ignore errors reading cache directory
+    }
+    return undefined;
+}
+/**
+ * Remove stale Puppeteer Chrome builds while preserving the active build.
+ */
+export async function pruneOldPuppeteerChromeBuilds(activeExecutablePath, cacheDir = getPuppeteerCacheDir()) {
+    const chromeDir = getPuppeteerChromeDir(cacheDir);
+    const activeBuildDir = getCachedChromeBuildDir(chromeDir, activeExecutablePath);
+    if (!activeBuildDir) {
+        return;
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(chromeDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    await Promise.all(entries
+        .filter(entry => entry.isDirectory())
+        .map(async (entry) => {
+        const buildDir = join(chromeDir, entry.name);
+        if (resolve(buildDir) === resolve(activeBuildDir)) {
+            return;
+        }
+        try {
+            await fs.rm(buildDir, { recursive: true, force: true });
+        }
+        catch (error) {
+            console.error(`Failed to remove old Chrome cache build at ${buildDir}:`, error);
+        }
+    }));
+}
+/**
+ * Find system-installed Chrome/Chromium browser
+ * Returns the executable path if found, undefined otherwise
+ */
+function findSystemChrome() {
+    const paths = process.platform === 'win32'
+        ? [
+            'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+            'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+            `${process.env.LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`,
+            'C:\\Program Files\\Chromium\\Application\\chrome.exe',
+            'C:\\Program Files (x86)\\Chromium\\Application\\chrome.exe',
+        ]
+        : process.platform === 'darwin'
+            ? [
+                '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+                '/Applications/Chromium.app/Contents/MacOS/Chromium',
+                '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+            ]
+            : [
+                // Linux paths
+                '/usr/bin/google-chrome',
+                '/usr/bin/google-chrome-stable',
+                '/usr/bin/chromium',
+                '/usr/bin/chromium-browser',
+                '/snap/bin/chromium',
+            ];
+    return paths.find(p => existsSync(p));
+}
+/**
+ * Download and install Chrome using @puppeteer/browsers
+ * Returns the executable path after installation
+ */
+async function installChrome() {
+    // Dynamic import to avoid loading if not needed
+    const { install, Browser, detectBrowserPlatform, resolveBuildId } = await import('@puppeteer/browsers');
+    const cacheDir = getPuppeteerCacheDir();
+    const platform = detectBrowserPlatform();
+    const buildId = await resolveBuildId(Browser.CHROME, platform, 'stable');
+    console.error('Downloading Chrome for PDF generation (this may take a few minutes)...');
+    await fs.mkdir(cacheDir, { recursive: true });
+    const installedBrowser = await install({
+        browser: Browser.CHROME,
+        buildId,
+        cacheDir,
+        downloadProgressCallback: (downloadedBytes, totalBytes) => {
+            const percent = Math.round((downloadedBytes / totalBytes) * 100);
+            process.stderr.write(`\rDownloading Chrome: ${percent}%`);
+        },
+    });
+    console.error('\nChrome download complete.');
+    return {
+        executablePath: installedBrowser.executablePath,
+    };
+}
+/**
+ * Find or install Chrome for PDF generation
+ * Priority: 1. Puppeteer cache, 2. System Chrome, 3. Install Chrome
+ * Results are cached to avoid repeated lookups
+ */
+async function getChromePath() {
+    // Return cached result if available
+    if (cachedChromePath !== null) {
+        return cachedChromePath;
+    }
+    // If a check is already in progress, wait for it
+    if (chromeCheckPromise) {
+        return chromeCheckPromise;
+    }
+    // Start the check
+    chromeCheckPromise = (async () => {
+        // 1. Check puppeteer cache first (exact compatible version)
+        const cachedChrome = findPuppeteerChrome();
+        if (cachedChrome) {
+            await pruneOldPuppeteerChromeBuilds(cachedChrome.executablePath);
+            cachedChromePath = cachedChrome.executablePath;
+            return cachedChrome.executablePath;
+        }
+        // 2. Check system Chrome
+        const systemChrome = findSystemChrome();
+        if (systemChrome) {
+            cachedChromePath = systemChrome;
+            return systemChrome;
+        }
+        // 3. Install Chrome as last resort
+        try {
+            const installedChrome = await installChrome();
+            await pruneOldPuppeteerChromeBuilds(installedChrome.executablePath);
+            cachedChromePath = installedChrome.executablePath;
+            return installedChrome.executablePath;
+        }
+        catch (error) {
+            console.error('Failed to install Chrome:', error);
+            cachedChromePath = undefined;
+            return undefined;
+        }
+    })();
+    const result = await chromeCheckPromise;
+    chromeCheckPromise = null;
+    return result;
+}
+/**
+ * Preemptively ensure Chrome is available for PDF generation.
+ * Call this at server startup to trigger download in background if needed.
+ * Returns immediately, download happens in background.
+ */
+export function ensureChromeAvailable() {
+    // Don't await - let it run in background
+    getChromePath().catch((error) => {
+        console.error('Background Chrome check failed:', error);
+    });
+}
+async function loadPdfToBuffer(source) {
+    if (isUrl(source)) {
+        const response = await fetch(source);
+        return await response.arrayBuffer();
+    }
+    else {
+        return await fs.readFile(source);
+    }
+}
+/**
+ * Convert PDF to Markdown using @opendocsg/pdf2md
+ */
+export async function parsePdfToMarkdown(source, pageNumbers = []) {
+    try {
+        const data = await loadPdfToBuffer(source);
+        // @ts-ignore: Type definition mismatch for ESM usage
+        return await pdf2md(new Uint8Array(data), pageNumbers);
+    }
+    catch (error) {
+        console.error("Error converting PDF to Markdown (v3):", error);
+        throw error;
+    }
+}
+export async function parseMarkdownToPdf(markdown, options = {}) {
+    try {
+        // Find Chrome: puppeteer cache -> system Chrome -> install
+        const chromePath = await getChromePath();
+        if (chromePath) {
+            options = {
+                ...options,
+                launch_options: {
+                    ...options.launch_options,
+                    executablePath: chromePath,
+                }
+            };
+        }
+        const pdf = await mdToPdf({ content: markdown }, options);
+        return pdf.content;
+    }
+    catch (error) {
+        // Provide helpful error message if Chrome is not found
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (errorMessage.includes('Could not find Chrome')) {
+            throw new Error('PDF generation requires Chrome or Chromium browser. ' +
+                'Please install Google Chrome from https://www.google.com/chrome/ ' +
+                'or Chromium, then try again.');
+        }
+        console.error('Error creating PDF:', error);
+        throw error;
+    }
+}