@fragments-sdk/cli 0.2.2

package/src/service/browser-pool.ts

@@ -0,0 +1,339 @@
+import { chromium, type Browser, type BrowserContext } from "playwright";
+import { BRAND, DEFAULTS, type Viewport } from "../core/index.js";
+
+/**
+ * Browser pool configuration
+ */
+export interface BrowserPoolConfig {
+  /** Number of browser contexts to keep warm */
+  poolSize?: number;
+
+  /** Idle timeout before shutdown (ms) */
+  idleTimeoutMs?: number;
+
+  /** Default viewport for contexts */
+  viewport?: Viewport;
+
+  /** Enable headless mode (default: true) */
+  headless?: boolean;
+}
+
+/**
+ * Manages a pool of warm browser contexts for fast screenshot capture.
+ *
+ * Key features:
+ * - Lazy initialization (browser starts on first request)
+ * - Pre-warmed contexts for instant capture
+ * - Auto-shutdown after idle period
+ * - Graceful degradation
+ */
+export class BrowserPool {
+  private browser: Browser | null = null;
+  private contexts: BrowserContext[] = [];
+  private available: BrowserContext[] = [];
+  private waitingQueue: Array<(ctx: BrowserContext) => void> = [];
+  private idleTimeout: NodeJS.Timeout | null = null;
+  private initPromise: Promise<void> | null = null;
+  private isShuttingDown = false;
+
+  private readonly poolSize: number;
+  private readonly idleTimeoutMs: number;
+  private readonly viewport: Viewport;
+  private readonly headless: boolean;
+
+  constructor(config: BrowserPoolConfig = {}) {
+    this.poolSize = config.poolSize ?? DEFAULTS.poolSize;
+    this.idleTimeoutMs = config.idleTimeoutMs ?? DEFAULTS.idleTimeoutMs;
+    this.viewport = config.viewport ?? DEFAULTS.viewport;
+    this.headless = config.headless ?? true;
+  }
+
+  /**
+   * Check if the pool is initialized and ready
+   */
+  get isReady(): boolean {
+    return this.browser !== null && !this.isShuttingDown;
+  }
+
+  /**
+   * Get the current pool size
+   */
+  get size(): number {
+    return this.poolSize;
+  }
+
+  /**
+   * Get number of available contexts
+   */
+  get availableCount(): number {
+    return this.available.length;
+  }
+
+  /**
+   * Acquire a browser context from the pool.
+   * Will initialize the pool on first call.
+   * If all contexts are busy, will wait for one to become available.
+   */
+  async acquire(): Promise<BrowserContext> {
+    if (this.isShuttingDown) {
+      throw new BrowserPoolError(
+        "Cannot acquire context while pool is shutting down",
+        "POOL_SHUTTING_DOWN"
+      );
+    }
+
+    // Lazy initialization
+    if (!this.browser) {
+      await this.initialize();
+    }
+
+    // Reset idle timer
+    this.resetIdleTimer();
+
+    // Return available context if one exists
+    if (this.available.length > 0) {
+      return this.available.pop()!;
+    }
+
+    // All contexts busy - wait for one to free up
+    return this.waitForAvailable();
+  }
+
+  /**
+   * Release a context back to the pool after use.
+   * Clears context state for next user.
+   */
+  async release(context: BrowserContext): Promise<void> {
+    if (this.isShuttingDown) {
+      return;
+    }
+
+    // Clear context state (cookies, local storage, etc.)
+    await this.clearContext(context);
+
+    // If someone is waiting, give them this context directly
+    if (this.waitingQueue.length > 0) {
+      const resolve = this.waitingQueue.shift()!;
+      resolve(context);
+      return;
+    }
+
+    // Otherwise, return to available pool
+    this.available.push(context);
+  }
+
+  /**
+   * Pre-warm the browser pool.
+   * Call this during dev server startup for instant captures.
+   */
+  async warmup(): Promise<void> {
+    if (this.browser) {
+      return; // Already initialized
+    }
+    await this.initialize();
+  }
+
+  /**
+   * Gracefully shut down the pool, closing all contexts and browser.
+   */
+  async shutdown(): Promise<void> {
+    if (this.isShuttingDown || !this.browser) {
+      return;
+    }
+
+    this.isShuttingDown = true;
+
+    // Clear idle timer
+    if (this.idleTimeout) {
+      clearTimeout(this.idleTimeout);
+      this.idleTimeout = null;
+    }
+
+    // Reject any waiting requests
+    for (const resolve of this.waitingQueue) {
+      // We can't reject directly since we're using resolve, so we'll just let them timeout
+    }
+    this.waitingQueue = [];
+
+    // Close all contexts
+    for (const context of this.contexts) {
+      try {
+        await context.close();
+      } catch {
+        // Ignore errors during shutdown
+      }
+    }
+
+    // Close browser
+    try {
+      await this.browser.close();
+    } catch {
+      // Ignore errors during shutdown
+    }
+
+    // Reset state
+    this.browser = null;
+    this.contexts = [];
+    this.available = [];
+    this.initPromise = null;
+    this.isShuttingDown = false;
+  }
+
+  /**
+   * Initialize the browser and create the context pool.
+   */
+  private async initialize(): Promise<void> {
+    // Prevent multiple concurrent initializations
+    if (this.initPromise) {
+      return this.initPromise;
+    }
+
+    this.initPromise = this.doInitialize();
+    return this.initPromise;
+  }
+
+  private async doInitialize(): Promise<void> {
+    this.browser = await chromium.launch({
+      headless: this.headless,
+      args: [
+        "--disable-gpu",
+        "--disable-dev-shm-usage",
+        "--disable-extensions",
+        "--no-sandbox",
+        "--disable-setuid-sandbox",
+      ],
+    });
+
+    // Pre-create contexts
+    const contextPromises = Array.from({ length: this.poolSize }, () =>
+      this.createContext()
+    );
+
+    const contexts = await Promise.all(contextPromises);
+    this.contexts = contexts;
+    this.available = [...contexts];
+
+    // Start idle timer
+    this.resetIdleTimer();
+  }
+
+  /**
+   * Create a new browser context with default settings.
+   */
+  private async createContext(): Promise<BrowserContext> {
+    if (!this.browser) {
+      throw new BrowserPoolError(
+        "Browser not initialized",
+        "BROWSER_NOT_INITIALIZED"
+      );
+    }
+
+    return this.browser.newContext({
+      viewport: this.viewport,
+      deviceScaleFactor: this.viewport.deviceScaleFactor ?? 1,
+      // Disable animations for consistent screenshots
+      reducedMotion: "reduce",
+    });
+  }
+
+  /**
+   * Clear context state between uses.
+   */
+  private async clearContext(context: BrowserContext): Promise<void> {
+    try {
+      // Clear cookies
+      await context.clearCookies();
+
+      // Close all pages except one (keep one warm)
+      const pages = context.pages();
+      for (let i = 1; i < pages.length; i++) {
+        await pages[i].close();
+      }
+
+      // Navigate first page to blank if it exists
+      if (pages.length > 0) {
+        await pages[0].goto("about:blank");
+      }
+    } catch {
+      // Ignore errors during cleanup
+    }
+  }
+
+  /**
+   * Wait for an available context.
+   */
+  private waitForAvailable(): Promise<BrowserContext> {
+    return new Promise((resolve, reject) => {
+      // Add timeout to prevent indefinite waiting
+      const timeout = setTimeout(() => {
+        const index = this.waitingQueue.indexOf(resolve);
+        if (index > -1) {
+          this.waitingQueue.splice(index, 1);
+        }
+        reject(
+          new BrowserPoolError(
+            "Timeout waiting for available browser context",
+            "ACQUIRE_TIMEOUT"
+          )
+        );
+      }, 30000); // 30 second timeout
+
+      // Wrap resolve to clear timeout
+      const wrappedResolve = (ctx: BrowserContext) => {
+        clearTimeout(timeout);
+        resolve(ctx);
+      };
+
+      this.waitingQueue.push(wrappedResolve);
+    });
+  }
+
+  /**
+   * Reset the idle shutdown timer.
+   */
+  private resetIdleTimer(): void {
+    if (this.idleTimeout) {
+      clearTimeout(this.idleTimeout);
+    }
+
+    this.idleTimeout = setTimeout(() => {
+      this.shutdown();
+    }, this.idleTimeoutMs);
+  }
+}
+
+/**
+ * Error class for browser pool errors
+ */
+export class BrowserPoolError extends Error {
+  constructor(message: string, public readonly code: string) {
+    super(message);
+    this.name = `${BRAND.name}BrowserPoolError`;
+  }
+}
+
+/**
+ * Singleton instance for shared browser pool
+ */
+let sharedPool: BrowserPool | null = null;
+
+/**
+ * Get the shared browser pool instance.
+ * Creates one if it doesn't exist.
+ */
+export function getSharedPool(config?: BrowserPoolConfig): BrowserPool {
+  if (!sharedPool) {
+    sharedPool = new BrowserPool(config);
+  }
+  return sharedPool;
+}
+
+/**
+ * Shutdown and clear the shared pool instance.
+ */
+export async function shutdownSharedPool(): Promise<void> {
+  if (sharedPool) {
+    await sharedPool.shutdown();
+    sharedPool = null;
+  }
+}

package/src/service/capture.ts

@@ -0,0 +1,267 @@
+import type { Page } from 'playwright';
+import {
+  BRAND,
+  DEFAULTS,
+  type Screenshot,
+  type ScreenshotMetadata,
+  type Viewport,
+  type Theme,
+} from '../core/index.js';
+import { BrowserPool, BrowserPoolError } from './browser-pool.js';
+import { ServiceError, Timer, computeHash, sleep } from './utils.js';
+
+/**
+ * Options for capturing a screenshot
+ */
+export interface CaptureOptions {
+  /** Override default viewport */
+  viewport?: Viewport;
+
+  /** Theme to capture */
+  theme?: Theme;
+
+  /** Wait for specific selector before capture */
+  waitForSelector?: string;
+
+  /** Additional delay after render (ms) */
+  delay?: number;
+
+  /** Timeout for font loading (ms) */
+  fontTimeout?: number;
+
+  /** Whether to disable animations (default: true) */
+  disableAnimations?: boolean;
+
+  /** Clip capture to specific element */
+  clipSelector?: string;
+}
+
+/**
+ * CSS to inject for disabling animations
+ */
+const DISABLE_ANIMATIONS_CSS = `
+*, *::before, *::after {
+  animation-duration: 0s !important;
+  animation-delay: 0s !important;
+  transition-duration: 0s !important;
+  transition-delay: 0s !important;
+}
+`;
+
+/**
+ * Capture engine for taking screenshots of component variants.
+ */
+export class CaptureEngine {
+  constructor(
+    private readonly pool: BrowserPool,
+    private readonly baseUrl: string
+  ) {}
+
+  /**
+   * Capture a single variant screenshot
+   */
+  async captureVariant(
+    component: string,
+    variant: string,
+    options: CaptureOptions = {}
+  ): Promise<Screenshot> {
+    const timer = new Timer();
+    const context = await this.pool.acquire();
+
+    try {
+      const page = await context.newPage();
+
+      try {
+        // Build the URL for isolated variant rendering
+        const url = this.buildVariantUrl(component, variant, options.theme);
+
+        // Navigate and capture
+        const { renderTimeMs, data, captureTimeMs } = await this.navigateAndCapture(
+          page,
+          url,
+          options
+        );
+
+        // Build screenshot object
+        const screenshot: Screenshot = {
+          data,
+          hash: computeHash(data),
+          viewport: options.viewport ?? DEFAULTS.viewport,
+          capturedAt: new Date(),
+          metadata: {
+            component,
+            variant,
+            theme: options.theme ?? DEFAULTS.theme,
+            renderTimeMs,
+            captureTimeMs,
+          },
+        };
+
+        return screenshot;
+      } finally {
+        await page.close();
+      }
+    } finally {
+      await this.pool.release(context);
+    }
+  }
+
+  /**
+   * Capture all variants for a component
+   */
+  async captureComponent(
+    component: string,
+    variants: string[],
+    options: CaptureOptions = {}
+  ): Promise<Screenshot[]> {
+    const results: Screenshot[] = [];
+
+    // Capture in parallel up to pool size
+    const batchSize = this.pool.size;
+
+    for (let i = 0; i < variants.length; i += batchSize) {
+      const batch = variants.slice(i, i + batchSize);
+      const batchPromises = batch.map((variant) =>
+        this.captureVariant(component, variant, options)
+      );
+      const batchResults = await Promise.all(batchPromises);
+      results.push(...batchResults);
+    }
+
+    return results;
+  }
+
+  /**
+   * Build the URL for a variant
+   */
+  private buildVariantUrl(
+    component: string,
+    variant: string,
+    theme?: Theme
+  ): string {
+    const params = new URLSearchParams({
+      component,
+      variant,
+      isolated: 'true',
+    });
+
+    if (theme) {
+      params.set('theme', theme);
+    }
+
+    return `${this.baseUrl}?${params.toString()}`;
+  }
+
+  /**
+   * Navigate to URL and capture screenshot
+   */
+  private async navigateAndCapture(
+    page: Page,
+    url: string,
+    options: CaptureOptions
+  ): Promise<{ renderTimeMs: number; data: Buffer; captureTimeMs: number }> {
+    const renderTimer = new Timer();
+
+    // Inject animation disabling CSS if needed
+    if (options.disableAnimations !== false) {
+      await page.addStyleTag({ content: DISABLE_ANIMATIONS_CSS });
+    }
+
+    // Navigate to the page
+    await page.goto(url, {
+      waitUntil: 'domcontentloaded',
+      timeout: 30000,
+    });
+
+    // Wait for network to be idle (all resources loaded)
+    await page.waitForLoadState('networkidle', { timeout: 10000 }).catch(() => {
+      // Ignore timeout, continue with capture
+    });
+
+    // Wait for fonts to load
+    await this.waitForFonts(page, options.fontTimeout ?? DEFAULTS.fontTimeoutMs);
+
+    // Wait for specific selector if provided
+    if (options.waitForSelector) {
+      await page.waitForSelector(options.waitForSelector, { timeout: 5000 });
+    }
+
+    // Additional delay if specified
+    if (options.delay ?? DEFAULTS.captureDelayMs) {
+      await sleep(options.delay ?? DEFAULTS.captureDelayMs);
+    }
+
+    const renderTimeMs = renderTimer.elapsed();
+
+    // Capture screenshot
+    const captureTimer = new Timer();
+    const data = await this.takeScreenshot(page, options);
+    const captureTimeMs = captureTimer.elapsed();
+
+    return { renderTimeMs, data: Buffer.from(data), captureTimeMs };
+  }
+
+  /**
+   * Wait for fonts to be loaded
+   */
+  private async waitForFonts(page: Page, timeout: number): Promise<void> {
+    try {
+      await page.evaluate(async (timeoutMs) => {
+        // Wait for document.fonts.ready
+        await Promise.race([
+          document.fonts.ready,
+          new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+        ]);
+      }, timeout);
+    } catch {
+      // Ignore errors, continue with capture
+    }
+  }
+
+  /**
+   * Take the actual screenshot
+   */
+  private async takeScreenshot(
+    page: Page,
+    options: CaptureOptions
+  ): Promise<Uint8Array> {
+    // If clip selector is provided, clip to that element
+    if (options.clipSelector) {
+      const element = page.locator(options.clipSelector);
+      const boundingBox = await element.boundingBox();
+
+      if (boundingBox) {
+        return page.screenshot({
+          type: 'png',
+          clip: boundingBox,
+        });
+      }
+    }
+
+    // Full page screenshot
+    return page.screenshot({
+      type: 'png',
+      fullPage: false,
+    });
+  }
+}
+
+/**
+ * Error class for capture errors
+ */
+export class CaptureError extends ServiceError {
+  constructor(message: string, code: string, suggestion?: string) {
+    super(message, code, suggestion);
+    this.name = `${BRAND.name}CaptureError`;
+  }
+}
+
+/**
+ * Create a capture engine with the shared browser pool
+ */
+export function createCaptureEngine(
+  pool: BrowserPool,
+  baseUrl: string
+): CaptureEngine {
+  return new CaptureEngine(pool, baseUrl);
+}