cdp-skill 1.0.2 → 1.0.4

package/src/capture/pdf-capture.js

@@ -0,0 +1,256 @@
+/**
+ * PDF Capture Module
+ * Generate PDF documents from page content
+ *
+ * PUBLIC EXPORTS:
+ * - createPdfCapture(session) - Factory for PDF capture
+ *
+ * @module cdp-skill/capture/pdf-capture
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Create a PDF capture utility
+ * @param {import('../types.js').CDPSession} session - CDP session
+ * @returns {Object} PDF capture interface
+ */
+export function createPdfCapture(session) {
+  /**
+   * Generate PDF from current page
+   * @param {import('../types.js').PdfOptions} [options] - PDF options
+   * @returns {Promise<Buffer>} PDF buffer
+   */
+  async function generatePdf(options = {}) {
+    const params = {
+      landscape: options.landscape || false,
+      displayHeaderFooter: options.displayHeaderFooter || false,
+      headerTemplate: options.headerTemplate || '',
+      footerTemplate: options.footerTemplate || '',
+      printBackground: options.printBackground !== false,
+      scale: options.scale || 1,
+      paperWidth: options.paperWidth || 8.5,
+      paperHeight: options.paperHeight || 11,
+      marginTop: options.marginTop || 0.4,
+      marginBottom: options.marginBottom || 0.4,
+      marginLeft: options.marginLeft || 0.4,
+      marginRight: options.marginRight || 0.4,
+      pageRanges: options.pageRanges || '',
+      preferCSSPageSize: options.preferCSSPageSize || false
+    };
+
+    const result = await session.send('Page.printToPDF', params);
+    return Buffer.from(result.data, 'base64');
+  }
+
+  function formatFileSize(bytes) {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+  }
+
+  /**
+   * Extract metadata from PDF buffer
+   * @param {Buffer} buffer - PDF buffer
+   * @returns {{fileSize: number, fileSizeFormatted: string, pageCount: number, dimensions: Object}}
+   */
+  function extractPdfMetadata(buffer) {
+    const fileSize = buffer.length;
+    const content = buffer.toString('binary');
+
+    // Count pages by looking for /Type /Page entries
+    const pageMatches = content.match(/\/Type\s*\/Page[^s]/g);
+    const pageCount = pageMatches ? pageMatches.length : 1;
+
+    // Try to extract media box dimensions (default page size)
+    let dimensions = { width: 612, height: 792 }; // Default Letter size in points
+    const mediaBoxMatch = content.match(/\/MediaBox\s*\[\s*(\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)\s*\]/);
+    if (mediaBoxMatch) {
+      dimensions = {
+        width: parseFloat(mediaBoxMatch[3]) - parseFloat(mediaBoxMatch[1]),
+        height: parseFloat(mediaBoxMatch[4]) - parseFloat(mediaBoxMatch[2])
+      };
+    }
+
+    return {
+      fileSize,
+      fileSizeFormatted: formatFileSize(fileSize),
+      pageCount,
+      dimensions: {
+        width: dimensions.width,
+        height: dimensions.height,
+        unit: 'points'
+      }
+    };
+  }
+
+  /**
+   * Validate PDF buffer
+   * @param {Buffer} buffer - PDF buffer
+   * @returns {{valid: boolean, errors: string[], warnings: string[]}}
+   */
+  function validatePdf(buffer) {
+    const content = buffer.toString('binary');
+    const errors = [];
+    const warnings = [];
+
+    // Check PDF header
+    if (!content.startsWith('%PDF-')) {
+      errors.push('Invalid PDF: missing PDF header');
+    }
+
+    // Check for EOF marker
+    if (!content.includes('%%EOF')) {
+      warnings.push('PDF may be truncated: missing EOF marker');
+    }
+
+    // Check for xref table or xref stream
+    if (!content.includes('xref') && !content.includes('/XRef')) {
+      warnings.push('PDF may have structural issues: no cross-reference found');
+    }
+
+    // Check minimum size (a valid PDF should be at least a few hundred bytes)
+    if (buffer.length < 100) {
+      errors.push('PDF file is too small to be valid');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+
+  /**
+   * Generate PDF of specific element
+   * @param {string} selector - Element selector
+   * @param {import('../types.js').PdfOptions} [options] - PDF options
+   * @param {Object} elementLocator - Element locator instance
+   * @returns {Promise<Buffer>} PDF buffer
+   */
+  async function generateElementPdf(selector, options = {}, elementLocator) {
+    if (!elementLocator) {
+      throw new Error('Element locator required for element PDF');
+    }
+
+    // Find the element
+    const element = await elementLocator.querySelector(selector);
+    if (!element) {
+      throw new Error(`Element not found: ${selector}`);
+    }
+
+    try {
+      // Get the element's HTML and create a print-optimized version
+      const elementHtml = await element.evaluate(`function() {
+        const clone = this.cloneNode(true);
+        // Create a wrapper with print-friendly styles
+        const wrapper = document.createElement('div');
+        wrapper.style.cssText = 'width: 100%; margin: 0; padding: 0;';
+        wrapper.appendChild(clone);
+        return wrapper.outerHTML;
+      }`);
+
+      // Store original body content
+      await session.send('Runtime.evaluate', {
+        expression: `
+          window.__originalBody = document.body.innerHTML;
+          window.__originalStyles = document.body.style.cssText;
+        `
+      });
+
+      // Replace body with element content for printing
+      await session.send('Runtime.evaluate', {
+        expression: `
+          document.body.innerHTML = ${JSON.stringify(elementHtml)};
+          document.body.style.cssText = 'margin: 0; padding: 20px;';
+        `
+      });
+
+      // Generate the PDF
+      const buffer = await generatePdf(options);
+
+      // Restore original body
+      await session.send('Runtime.evaluate', {
+        expression: `
+          document.body.innerHTML = window.__originalBody;
+          document.body.style.cssText = window.__originalStyles;
+          delete window.__originalBody;
+          delete window.__originalStyles;
+        `
+      });
+
+      return buffer;
+    } finally {
+      await element.dispose();
+    }
+  }
+
+  /**
+   * Save PDF to file
+   * @param {string} filePath - Destination path
+   * @param {Object} [options] - PDF options
+   * @param {string} [options.selector] - Element selector for element PDF
+   * @param {boolean} [options.validate] - Validate PDF structure
+   * @param {Object} [elementLocator] - Element locator for selector option
+   * @returns {Promise<Object>} Result with path, metadata, and optional validation
+   */
+  async function saveToFile(filePath, options = {}, elementLocator = null) {
+    let buffer;
+
+    // Support element PDF via selector
+    if (options.selector && elementLocator) {
+      buffer = await generateElementPdf(options.selector, options, elementLocator);
+    } else {
+      buffer = await generatePdf(options);
+    }
+
+    const absolutePath = path.resolve(filePath);
+    const dir = path.dirname(absolutePath);
+
+    try {
+      await fs.mkdir(dir, { recursive: true });
+    } catch (err) {
+      if (err.code === 'EACCES' || err.code === 'EPERM') {
+        throw new Error(`Permission denied: cannot create directory "${dir}"`);
+      }
+      if (err.code === 'EROFS') {
+        throw new Error(`Read-only filesystem: cannot create directory "${dir}"`);
+      }
+      throw new Error(`Failed to create directory "${dir}": ${err.message}`);
+    }
+
+    try {
+      await fs.writeFile(absolutePath, buffer);
+    } catch (err) {
+      if (err.code === 'ENOSPC') {
+        throw new Error(`Disk full: cannot write PDF to "${absolutePath}"`);
+      }
+      if (err.code === 'EACCES' || err.code === 'EPERM') {
+        throw new Error(`Permission denied: cannot write to "${absolutePath}"`);
+      }
+      if (err.code === 'EROFS') {
+        throw new Error(`Read-only filesystem: cannot write to "${absolutePath}"`);
+      }
+      throw new Error(`Failed to save PDF to "${absolutePath}": ${err.message}`);
+    }
+
+    // Extract metadata
+    const metadata = extractPdfMetadata(buffer);
+
+    // Optionally validate
+    let validation = null;
+    if (options.validate) {
+      validation = validatePdf(buffer);
+    }
+
+    return {
+      path: absolutePath,
+      ...metadata,
+      validation,
+      selector: options.selector || null
+    };
+  }
+
+  return { generatePdf, saveToFile, extractPdfMetadata, validatePdf };
+}

package/src/capture/screenshot-capture.js

@@ -0,0 +1,325 @@
+/**
+ * Screenshot Capture Module
+ * CDP-based screenshot capture for viewport, full page, and regions
+ *
+ * PUBLIC EXPORTS:
+ * - createScreenshotCapture(session, options?) - Factory for screenshot capture
+ * - captureViewport(session, options?) - Capture viewport screenshot
+ * - captureFullPage(session, options?) - Capture full page screenshot
+ * - captureRegion(session, region, options?) - Capture specific region
+ * - saveScreenshot(buffer, filePath) - Save screenshot to file
+ *
+ * @module cdp-skill/capture/screenshot-capture
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+const DEFAULT_MAX_DIMENSION = 16384;
+const VALID_FORMATS = ['png', 'jpeg', 'webp'];
+
+/**
+ * Create a screenshot capture utility
+ * @param {import('../types.js').CDPSession} session - CDP session
+ * @param {Object} [options] - Configuration options
+ * @param {number} [options.maxDimension=16384] - Maximum dimension for full page captures
+ * @returns {Object} Screenshot capture interface
+ */
+export function createScreenshotCapture(session, options = {}) {
+  const maxDimension = options.maxDimension || DEFAULT_MAX_DIMENSION;
+
+  function validateFormat(format) {
+    if (!VALID_FORMATS.includes(format)) {
+      throw new Error(
+        `Invalid screenshot format "${format}". Valid formats are: ${VALID_FORMATS.join(', ')}`
+      );
+    }
+  }
+
+  function validateQuality(quality, format) {
+    if (quality === undefined) return;
+    if (format === 'png') {
+      throw new Error('Quality option is only supported for jpeg and webp formats, not png');
+    }
+    if (typeof quality !== 'number' || quality < 0 || quality > 100) {
+      throw new Error('Quality must be a number between 0 and 100');
+    }
+  }
+
+  function validateOptions(opts = {}) {
+    const format = opts.format || 'png';
+    validateFormat(format);
+    validateQuality(opts.quality, format);
+    return { ...opts, format };
+  }
+
+  /**
+   * Capture viewport screenshot
+   * @param {import('../types.js').ScreenshotOptions} [captureOptions] - Screenshot options
+   * @returns {Promise<Buffer>} PNG/JPEG/WebP image buffer
+   */
+  async function captureViewport(captureOptions = {}) {
+    const validated = validateOptions(captureOptions);
+    const params = { format: validated.format };
+
+    if (params.format !== 'png' && validated.quality !== undefined) {
+      params.quality = validated.quality;
+    }
+
+    // Support omitBackground option
+    if (captureOptions.omitBackground) {
+      params.fromSurface = true;
+      // Enable transparent background
+      await session.send('Emulation.setDefaultBackgroundColorOverride', {
+        color: { r: 0, g: 0, b: 0, a: 0 }
+      });
+    }
+
+    // Support clip option for region capture
+    if (captureOptions.clip) {
+      params.clip = {
+        x: captureOptions.clip.x,
+        y: captureOptions.clip.y,
+        width: captureOptions.clip.width,
+        height: captureOptions.clip.height,
+        scale: captureOptions.clip.scale || 1
+      };
+    }
+
+    const result = await session.send('Page.captureScreenshot', params);
+
+    // Reset background override if we changed it
+    if (captureOptions.omitBackground) {
+      await session.send('Emulation.setDefaultBackgroundColorOverride');
+    }
+
+    return Buffer.from(result.data, 'base64');
+  }
+
+  /**
+   * Capture full page screenshot
+   * @param {import('../types.js').ScreenshotOptions} [captureOptions] - Screenshot options
+   * @returns {Promise<Buffer>} PNG/JPEG/WebP image buffer
+   */
+  async function captureFullPage(captureOptions = {}) {
+    const validated = validateOptions(captureOptions);
+
+    const metrics = await session.send('Page.getLayoutMetrics');
+    const { contentSize } = metrics;
+
+    const width = Math.ceil(contentSize.width);
+    const height = Math.ceil(contentSize.height);
+
+    if (width > maxDimension || height > maxDimension) {
+      throw new Error(
+        `Page dimensions (${width}x${height}) exceed maximum allowed (${maxDimension}x${maxDimension}). ` +
+        `Consider using captureViewport() or captureRegion() instead.`
+      );
+    }
+
+    const params = {
+      format: validated.format,
+      captureBeyondViewport: true,
+      clip: { x: 0, y: 0, width, height, scale: 1 }
+    };
+
+    if (params.format !== 'png' && validated.quality !== undefined) {
+      params.quality = validated.quality;
+    }
+
+    const result = await session.send('Page.captureScreenshot', params);
+    return Buffer.from(result.data, 'base64');
+  }
+
+  /**
+   * Capture specific region
+   * @param {import('../types.js').ClipRegion} region - Region to capture
+   * @param {import('../types.js').ScreenshotOptions} [captureOptions] - Screenshot options
+   * @returns {Promise<Buffer>} PNG/JPEG/WebP image buffer
+   */
+  async function captureRegion(region, captureOptions = {}) {
+    const validated = validateOptions(captureOptions);
+    const params = {
+      format: validated.format,
+      clip: {
+        x: region.x,
+        y: region.y,
+        width: region.width,
+        height: region.height,
+        scale: captureOptions.scale || 1
+      }
+    };
+
+    if (params.format !== 'png' && validated.quality !== undefined) {
+      params.quality = validated.quality;
+    }
+
+    const result = await session.send('Page.captureScreenshot', params);
+    return Buffer.from(result.data, 'base64');
+  }
+
+  /**
+   * Capture element by bounding box
+   * @param {import('../types.js').BoundingBox} boundingBox - Element bounding box
+   * @param {Object} [captureOptions] - Screenshot options
+   * @param {number} [captureOptions.padding=0] - Padding around element
+   * @returns {Promise<Buffer>} PNG/JPEG/WebP image buffer
+   */
+  async function captureElement(boundingBox, captureOptions = {}) {
+    const padding = captureOptions.padding || 0;
+    return captureRegion({
+      x: Math.max(0, boundingBox.x - padding),
+      y: Math.max(0, boundingBox.y - padding),
+      width: boundingBox.width + (padding * 2),
+      height: boundingBox.height + (padding * 2)
+    }, captureOptions);
+  }
+
+  /**
+   * Save buffer to file
+   * @param {Buffer} buffer - Image buffer
+   * @param {string} filePath - Destination path
+   * @returns {Promise<string>} Absolute path
+   */
+  async function saveToFile(buffer, filePath) {
+    const absolutePath = path.resolve(filePath);
+    const dir = path.dirname(absolutePath);
+
+    try {
+      await fs.mkdir(dir, { recursive: true });
+    } catch (err) {
+      if (err.code === 'EACCES' || err.code === 'EPERM') {
+        throw new Error(`Permission denied: cannot create directory "${dir}"`);
+      }
+      if (err.code === 'EROFS') {
+        throw new Error(`Read-only filesystem: cannot create directory "${dir}"`);
+      }
+      throw new Error(`Failed to create directory "${dir}": ${err.message}`);
+    }
+
+    try {
+      await fs.writeFile(absolutePath, buffer);
+    } catch (err) {
+      if (err.code === 'ENOSPC') {
+        throw new Error(`Disk full: cannot write screenshot to "${absolutePath}"`);
+      }
+      if (err.code === 'EACCES' || err.code === 'EPERM') {
+        throw new Error(`Permission denied: cannot write to "${absolutePath}"`);
+      }
+      if (err.code === 'EROFS') {
+        throw new Error(`Read-only filesystem: cannot write to "${absolutePath}"`);
+      }
+      throw new Error(`Failed to save screenshot to "${absolutePath}": ${err.message}`);
+    }
+
+    return absolutePath;
+  }
+
+  /**
+   * Capture and save to file
+   * @param {string} filePath - Destination path
+   * @param {Object} [captureOptions] - Screenshot options
+   * @param {boolean} [captureOptions.fullPage=false] - Capture full page
+   * @param {string} [captureOptions.selector] - Element selector to capture
+   * @param {Object} [elementLocator] - Element locator for selector capture
+   * @returns {Promise<string>} Absolute path
+   */
+  async function captureToFile(filePath, captureOptions = {}, elementLocator = null) {
+    let buffer;
+    let elementBox = null;
+
+    // Support element screenshot via selector
+    if (captureOptions.selector && elementLocator) {
+      const element = await elementLocator.querySelector(captureOptions.selector);
+      if (!element) {
+        throw new Error(`Element not found: ${captureOptions.selector}`);
+      }
+      const box = await element.getBoundingBox();
+      await element.dispose();
+
+      if (!box || box.width === 0 || box.height === 0) {
+        throw new Error(`Element has no visible dimensions: ${captureOptions.selector}`);
+      }
+
+      elementBox = box;
+      buffer = await captureElement(box, captureOptions);
+    } else if (captureOptions.fullPage) {
+      buffer = await captureFullPage(captureOptions);
+    } else {
+      buffer = await captureViewport(captureOptions);
+    }
+
+    return saveToFile(buffer, filePath);
+  }
+
+  /**
+   * Get viewport dimensions
+   * @returns {Promise<{width: number, height: number}>}
+   */
+  async function getViewportDimensions() {
+    const result = await session.send('Runtime.evaluate', {
+      expression: '({ width: window.innerWidth, height: window.innerHeight })',
+      returnByValue: true
+    });
+    return result.result.value;
+  }
+
+  return {
+    captureViewport,
+    captureFullPage,
+    captureRegion,
+    captureElement,
+    saveToFile,
+    captureToFile,
+    getViewportDimensions
+  };
+}
+
+/**
+ * Convenience function to capture viewport
+ * @param {import('../types.js').CDPSession} session - CDP session
+ * @param {import('../types.js').ScreenshotOptions} [options] - Screenshot options
+ * @returns {Promise<Buffer>}
+ */
+export async function captureViewport(session, options = {}) {
+  const capture = createScreenshotCapture(session, options);
+  return capture.captureViewport(options);
+}
+
+/**
+ * Convenience function to capture full page
+ * @param {import('../types.js').CDPSession} session - CDP session
+ * @param {import('../types.js').ScreenshotOptions} [options] - Screenshot options
+ * @returns {Promise<Buffer>}
+ */
+export async function captureFullPage(session, options = {}) {
+  const capture = createScreenshotCapture(session, options);
+  return capture.captureFullPage(options);
+}
+
+/**
+ * Convenience function to capture a region
+ * @param {import('../types.js').CDPSession} session - CDP session
+ * @param {import('../types.js').ClipRegion} region - Region to capture
+ * @param {import('../types.js').ScreenshotOptions} [options] - Screenshot options
+ * @returns {Promise<Buffer>}
+ */
+export async function captureRegion(session, region, options = {}) {
+  const capture = createScreenshotCapture(session, options);
+  return capture.captureRegion(region, options);
+}
+
+/**
+ * Save a screenshot buffer to file
+ * @param {Buffer} buffer - Screenshot buffer
+ * @param {string} filePath - Destination path
+ * @returns {Promise<string>} Absolute path
+ */
+export async function saveScreenshot(buffer, filePath) {
+  const absolutePath = path.resolve(filePath);
+  const dir = path.dirname(absolutePath);
+
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(absolutePath, buffer);
+  return absolutePath;
+}