astro-better-declarative-screenshots 0.1.0

package/example/screenshot.config.mjs

@@ -0,0 +1,72 @@
+// example screenshot.config.mjs for the FusionAuth docs site
+// place at your Astro project root
+
+export default {
+  // base URL of the running app (local or in Docker)
+  baseUrl: 'http://localhost:9011',
+
+  // where to write screenshots; relative to project root
+  outputDir: 'public/screenshots',
+
+  // default viewport
+  window: { width: 1280, height: 800 },
+
+  // Playwright browser engine
+  browser: 'webkit',
+
+  // macOS Safari-style chrome with drop shadow
+  chrome: {
+    style:         'safari-macos',
+    showUrl:       true,
+    dark:          false,
+    shadowBlur:    40,
+    shadowPadding: 48,
+  },
+
+  // docker setup -- start the app and wait for it to be healthy
+  docker: {
+    compose:  'screenshots/docker-compose.yml',
+    service:  'fusionauth',
+
+    // bootstrap seeds initial data. the file path is passed to docker-compose.yml
+    // as SCREENSHOT_BOOTSTRAP_PATH and its content as SCREENSHOT_BOOTSTRAP_CONTENT.
+    // wire those env vars into your container however it needs.
+    // for FusionAuth: FUSIONAUTH_APP_KICKSTART_FILE: ${SCREENSHOT_BOOTSTRAP_PATH}
+    // for other apps: mount the path as a volume or use the content as a seed script
+    bootstrap: 'screenshots/kickstart/kickstart.json',
+
+    healthcheck: {
+      url:      'http://localhost:9011/api/status',
+      timeout:  120000,
+      interval: 3000,
+    },
+
+    // optional shell command to run after health check passes.
+    // runs in the project root. use for migrations, extra seeding, etc.
+    // postStart: 'node scripts/extra-seed.mjs',
+
+    env: {
+      DATABASE_PASSWORD: 'change-in-production',
+    },
+  },
+
+  // called once before any screenshot is taken -- log in, set up app state, etc.
+  beforeAll: async (context) => {
+    const page = await context.newPage();
+    await page.goto('http://localhost:9011/admin/login');
+    await page.fill('#loginId', 'admin@example.com');
+    await page.fill('#password', 'password');
+    await page.click('[type=submit]');
+    await page.waitForURL('**/admin/**');
+    await page.close();
+  },
+
+  // called before each individual screenshot -- navigate or set up state
+  beforeScreenshot: async (page, { url, name }) => {
+    // page is already navigated to url by this point
+    // close any open modals, dismiss notifications, etc.
+    await page.evaluate(() => {
+      document.querySelectorAll('.notification, .toast').forEach(el => el.remove());
+    });
+  },
+};

package/index.mjs

@@ -0,0 +1,56 @@
+// Astro integration entry point.
+// usage in astro.config.mjs:
+//   import screenshots from 'astro-better-declarative-screenshots';
+//   export default defineConfig({ integrations: [screenshots()] });
+
+import { loadConfig } from './src/config.mjs';
+import path from 'path';
+
+/**
+ * @param {Partial<import('./src/config.mjs').ConfigSchema['_type']>} [integrationConfig]
+ * @returns {import('astro').AstroIntegration}
+ */
+export default function screenshotsIntegration(integrationConfig = {}) {
+  let resolvedConfig;
+
+  return {
+    name: 'astro-better-declarative-screenshots',
+
+    hooks: {
+      'astro:config:setup': async ({ config: astroConfig, addWatchFile, logger }) => {
+        const projectRoot = astroConfig.root
+          ? new URL(astroConfig.root).pathname
+          : process.cwd();
+
+        // load and validate the screenshot.config.mjs
+        try {
+          resolvedConfig = await loadConfig(projectRoot);
+        } catch (e) {
+          if (integrationConfig.strict === false) {
+            logger.warn(`[astro-better-declarative-screenshots] ${e.message}`);
+            resolvedConfig = null;
+          } else {
+            throw e;
+          }
+        }
+
+        // watch the config file so the dev server restarts when it changes
+        const configFile = path.join(projectRoot, 'screenshot.config.mjs');
+        addWatchFile(configFile);
+      },
+
+      'astro:build:done': async ({ logger }) => {
+        if (!resolvedConfig) return;
+        logger.info(
+          '[astro-better-declarative-screenshots] build done. ' +
+          'Run `take-screenshots` to update screenshots.'
+        );
+      },
+    },
+  };
+}
+
+// re-export utilities consumers may want
+export { loadConfig } from './src/config.mjs';
+export { discoverScreenshots } from './src/discover.mjs';
+export { deriveName } from './src/naming.mjs';

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "astro-better-declarative-screenshots",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Declarative, Docker-backed screenshots for Astro docs. Define the page and the elements to highlight, and this produces a screenshot.",
+  "exports": {
+    ".": "./index.mjs",
+    "./Screenshot.astro": "./Screenshot.astro",
+    "./Highlight.astro": "./Highlight.astro"
+  },
+  "bin": {
+    "take-screenshots": "./scripts/take-screenshots.mjs",
+    "check-screenshots": "./scripts/check-screenshots.mjs"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "astro": ">=4.0.0"
+  },
+  "dependencies": {
+    "playwright": "^1.45.0",
+    "sharp": "^0.33.0",
+    "pixelmatch": "^6.0.0",
+    "pngjs": "^7.0.0",
+    "glob": "^11.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0",
+    "astro": "^4.0.0"
+  },
+  "keywords": ["astro", "screenshots", "declarative", "docs", "playwright", "integration"],
+  "license": "MIT"
+}

package/scripts/check-screenshots.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// CLI: check-screenshots
+// captures all screenshots and diffs them against the committed references.
+// exits non-zero if any screenshot exceeds the diff threshold.
+// designed for CI -- does NOT overwrite the committed files.
+
+import path from 'path';
+import { mkdirSync, writeFileSync } from 'fs';
+import { loadConfig } from '../src/config.mjs';
+import { discoverScreenshots } from '../src/discover.mjs';
+import { startDocker, stopDocker } from '../src/docker.mjs';
+import { capturePage, createBrowserContext } from '../src/capture.mjs';
+import { addChrome } from '../src/chrome.mjs';
+import { diffScreenshot } from '../src/diff.mjs';
+
+const projectRoot = process.cwd();
+
+// default: 0.1% of pixels may differ before it's a failure
+const DEFAULT_THRESHOLD_RATIO = 0.001;
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const config = await loadConfig(projectRoot).catch(e => {
+    console.error(e.message);
+    process.exit(1);
+  });
+
+  const outputDir = path.resolve(projectRoot, config.outputDir);
+  const diffDir = path.resolve(projectRoot, args.diffDir ?? '.screenshot-diffs');
+  mkdirSync(diffDir, { recursive: true });
+
+  const specs = await discoverScreenshots(projectRoot);
+
+  if (specs.length === 0) {
+    console.log('[check-screenshots] no Screenshot components found.');
+    return;
+  }
+
+  const filter = args.filter;
+  const toCheck = filter
+    ? specs.filter(s => s.name.includes(filter) || s.url.includes(filter))
+    : specs;
+
+  console.log(`[check-screenshots] checking ${toCheck.length} screenshots...`);
+
+  if (config.docker) {
+    await startDocker(config.docker, projectRoot).catch(e => {
+      console.error('[check-screenshots] docker start failed:', e.message);
+      process.exit(1);
+    });
+  }
+
+  // create one browser context shared across beforeAll and all captures
+  const { browser, context } = await createBrowserContext({
+    browser: config.browser,
+    width: config.window.width,
+    height: config.window.height,
+    colorScheme: config.colorScheme,
+  });
+
+  if (config.beforeAll) {
+    await config.beforeAll(context).catch(e => {
+      console.error('[check-screenshots] beforeAll hook failed:', e.message);
+      browser.close();
+      process.exit(1);
+    });
+  }
+
+  const failures = [];
+  const missing = [];
+  let passed = 0;
+
+  for (const spec of toCheck) {
+    const fullUrl = spec.url.startsWith('http')
+      ? spec.url
+      : `${config.baseUrl.replace(/\/$/, '')}${spec.url}`;
+
+    const referencePath = path.join(outputDir, `${spec.name}.png`);
+    process.stdout.write(`  ${spec.name} ... `);
+
+    try {
+      const rawBuffer = await capturePage({
+        url: fullUrl,
+        name: spec.name,
+        highlights: spec.highlights,
+        width: spec.width ?? config.window.width,
+        height: spec.height ?? config.window.height,
+        fullPage: spec.fullPage,
+        browser: config.browser,
+        colorScheme: config.colorScheme,
+        beforeScreenshot: config.beforeScreenshot,
+        context,
+      });
+
+      let newBuffer = rawBuffer;
+      if (config.chrome.style !== 'none') {
+        newBuffer = await addChrome(rawBuffer, {
+          url: fullUrl,
+          dark: config.chrome.dark,
+          showUrl: config.chrome.showUrl,
+          shadowBlur: config.chrome.shadowBlur,
+          shadowPadding: config.chrome.shadowPadding,
+        });
+      }
+
+      const result = await diffScreenshot(referencePath, newBuffer, {
+        threshold: args.pixelThreshold ?? 0.1,
+        writeDiff: true,
+      });
+
+      if (result.pixels === -1) {
+        // reference file was missing
+        process.stdout.write('MISSING\n');
+        missing.push(spec.name);
+        // save the new capture as the diff artifact
+        writeFileSync(path.join(diffDir, `${spec.name}.new.png`), newBuffer);
+      } else if (result.ratio > (args.thresholdRatio ?? DEFAULT_THRESHOLD_RATIO)) {
+        process.stdout.write(`CHANGED (${(result.ratio * 100).toFixed(2)}% pixels differ)\n`);
+        failures.push({ name: spec.name, ratio: result.ratio, pixels: result.pixels });
+        if (result.diffImage) {
+          writeFileSync(path.join(diffDir, `${spec.name}.diff.png`), result.diffImage);
+        }
+        writeFileSync(path.join(diffDir, `${spec.name}.new.png`), newBuffer);
+      } else {
+        process.stdout.write('ok\n');
+        passed++;
+      }
+    } catch (e) {
+      process.stdout.write(`ERROR: ${e.message}\n`);
+      failures.push({ name: spec.name, ratio: 1, pixels: -1, error: e.message });
+    }
+  }
+
+  if (config.afterAll) {
+    await config.afterAll().catch(e => console.warn('[check-screenshots] afterAll hook failed:', e.message));
+  }
+
+  await browser.close();
+
+  if (config.docker) {
+    stopDocker(config.docker, projectRoot);
+  }
+
+  console.log(`\n[check-screenshots] ${passed} passed, ${failures.length} changed, ${missing.length} missing`);
+
+  if (missing.length > 0) {
+    console.log('\nMissing screenshots (run take-screenshots to generate):');
+    for (const name of missing) console.log(`  - ${name}`);
+  }
+
+  if (failures.length > 0) {
+    console.log('\nChanged screenshots (review diffs in ' + args.diffDir + '):');
+    for (const f of failures) {
+      if (f.error) console.log(`  - ${f.name}: error (${f.error})`);
+      else console.log(`  - ${f.name}: ${(f.ratio * 100).toFixed(2)}% pixels changed`);
+    }
+    console.log('\nIf changes are intentional, run take-screenshots to update the reference files.');
+    process.exit(1);
+  }
+
+  if (missing.length > 0 && args.failOnMissing) {
+    process.exit(1);
+  }
+}
+
+function parseArgs(argv) {
+  const args = {
+    filter: null,
+    diffDir: '.screenshot-diffs',
+    thresholdRatio: DEFAULT_THRESHOLD_RATIO,
+    pixelThreshold: 0.1,
+    failOnMissing: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--fail-on-missing') args.failOnMissing = true;
+    if (argv[i] === '--filter' && argv[i + 1]) args.filter = argv[++i];
+    if (argv[i].startsWith('--filter=')) args.filter = argv[i].slice(9);
+    if (argv[i].startsWith('--diff-dir=')) args.diffDir = argv[i].slice(11);
+    if (argv[i] === '--diff-dir' && argv[i + 1]) args.diffDir = argv[++i];
+    if (argv[i].startsWith('--threshold=')) args.thresholdRatio = parseFloat(argv[i].slice(12));
+  }
+  return args;
+}
+
+main().catch(e => {
+  console.error('[check-screenshots] fatal:', e);
+  process.exit(1);
+});

package/scripts/take-screenshots.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// CLI: take-screenshots
+// discovers Screenshot components in the project, starts Docker, captures
+// each page via Playwright, composites chrome, and writes PNGs to outputDir.
+
+import path from 'path';
+import { mkdirSync, writeFileSync } from 'fs';
+import { loadConfig } from '../src/config.mjs';
+import { discoverScreenshots } from '../src/discover.mjs';
+import { startDocker, stopDocker } from '../src/docker.mjs';
+import { capturePage, createBrowserContext } from '../src/capture.mjs';
+import { addChrome } from '../src/chrome.mjs';
+import { generatePlaceholder } from '../src/placeholder.mjs';
+
+const projectRoot = process.cwd();
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const config = await loadConfig(projectRoot).catch(e => {
+    console.error(e.message);
+    process.exit(1);
+  });
+
+  const outputDir = path.resolve(projectRoot, config.outputDir);
+  mkdirSync(outputDir, { recursive: true });
+
+  // discover all Screenshot components in the source
+  console.log(`[screenshots] scanning ${projectRoot} for Screenshot components...`);
+  const specs = await discoverScreenshots(projectRoot);
+
+  if (specs.length === 0) {
+    console.log('[screenshots] no Screenshot components found.');
+    return;
+  }
+
+  const filter = args.filter;
+  const toCapture = filter
+    ? specs.filter(s => s.name.includes(filter) || s.url.includes(filter))
+    : specs;
+
+  console.log(`[screenshots] found ${specs.length} screenshots, capturing ${toCapture.length}`);
+
+  // start Docker if configured
+  if (config.docker) {
+    await startDocker(config.docker, projectRoot).catch(e => {
+      console.error('[screenshots] docker start failed:', e.message);
+      process.exit(1);
+    });
+  }
+
+  // create one browser context shared across beforeAll and all captures so
+  // session cookies from login are preserved throughout
+  const { browser, context } = await createBrowserContext({
+    browser: config.browser,
+    width: config.window.width,
+    height: config.window.height,
+    colorScheme: config.colorScheme,
+  });
+
+  if (config.beforeAll) {
+    console.log('[screenshots] running beforeAll hook');
+    await config.beforeAll(context).catch(e => {
+      console.error('[screenshots] beforeAll hook failed:', e.message);
+      browser.close();
+      process.exit(1);
+    });
+  }
+
+  const errors = [];
+  let captured = 0;
+
+  for (const spec of toCapture) {
+    const fullUrl = spec.url.startsWith('http')
+      ? spec.url
+      : `${config.baseUrl.replace(/\/$/, '')}${spec.url}`;
+
+    const outputPath = path.join(outputDir, `${spec.name}.png`);
+    process.stdout.write(`  [${++captured}/${toCapture.length}] ${spec.name} ... `);
+
+    try {
+      const rawBuffer = await capturePage({
+        url: fullUrl,
+        name: spec.name,
+        highlights: spec.highlights,
+        width: spec.width ?? config.window.width,
+        height: spec.height ?? config.window.height,
+        fullPage: spec.fullPage,
+        browser: config.browser,
+        colorScheme: config.colorScheme,
+        beforeScreenshot: config.beforeScreenshot,
+        context,
+      });
+
+      let finalBuffer = rawBuffer;
+
+      if (config.chrome.style !== 'none') {
+        finalBuffer = await addChrome(rawBuffer, {
+          url: fullUrl,
+          dark: config.chrome.dark,
+          showUrl: config.chrome.showUrl,
+          shadowBlur: config.chrome.shadowBlur,
+          shadowPadding: config.chrome.shadowPadding,
+        });
+      }
+
+      writeFileSync(outputPath, finalBuffer);
+      process.stdout.write('done\n');
+    } catch (e) {
+      process.stdout.write(`FAILED: ${e.message}\n`);
+      errors.push({ spec, error: e });
+
+      if (args.strict || config.strict) {
+        // write a placeholder so the build doesn't break
+        try {
+          const placeholder = await generatePlaceholder({
+            name: spec.name,
+            width: spec.width ?? config.window.width,
+            height: spec.height ?? config.window.height,
+          });
+          writeFileSync(outputPath, placeholder);
+        } catch {}
+      }
+    }
+  }
+
+  if (config.afterAll) {
+    await config.afterAll().catch(e => {
+      console.warn('[screenshots] afterAll hook failed:', e.message);
+    });
+  }
+
+  await browser.close();
+
+  if (config.docker) {
+    stopDocker(config.docker, projectRoot);
+  }
+
+  if (errors.length > 0) {
+    console.error(`\n[screenshots] ${errors.length} screenshot(s) failed:`);
+    for (const { spec, error } of errors) {
+      console.error(`  - ${spec.name}: ${error.message}`);
+    }
+    if (args.strict) process.exit(1);
+  } else {
+    console.log(`\n[screenshots] all ${captured} screenshots saved to ${config.outputDir}`);
+  }
+}
+
+function parseArgs(argv) {
+  const args = { strict: false, filter: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--strict') args.strict = true;
+    if (argv[i] === '--filter' && argv[i + 1]) args.filter = argv[++i];
+    if (argv[i].startsWith('--filter=')) args.filter = argv[i].slice(9);
+  }
+  return args;
+}
+
+main().catch(e => {
+  console.error('[screenshots] fatal:', e);
+  process.exit(1);
+});

package/src/capture.mjs

@@ -0,0 +1,108 @@
+// Playwright-based page capture. opens the page, runs beforeScreenshot hooks,
+// injects highlights, takes the screenshot, then cleans up.
+
+import { chromium, firefox, webkit } from 'playwright';
+import { injectHighlights, scrollIntoView } from './highlight.mjs';
+
+const BROWSERS = { webkit, chromium, firefox };
+
+/**
+ * @typedef {Object} CaptureOptions
+ * @property {string} url - full URL including host
+ * @property {string} name - screenshot name (for logging)
+ * @property {Array<import('./highlight.mjs').HighlightSpec>} highlights
+ * @property {number} [width=1280]
+ * @property {number} [height=800]
+ * @property {boolean} [fullPage=false]
+ * @property {'webkit'|'chromium'|'firefox'} [browser='webkit']
+ * @property {'light'|'dark'} [colorScheme='light']
+ * @property {Function} [beforeScreenshot]
+ * @property {import('playwright').BrowserContext} [context] - reuse an existing context
+ */
+
+/**
+ * Capture a single screenshot and return the PNG buffer.
+ *
+ * @param {CaptureOptions} opts
+ * @returns {Promise<Buffer>}
+ */
+export async function capturePage(opts) {
+  const {
+    url,
+    name,
+    highlights = [],
+    width = 1280,
+    height = 800,
+    fullPage = false,
+    browser: browserName = 'webkit',
+    colorScheme = 'light',
+    beforeScreenshot,
+    context: existingContext,
+  } = opts;
+
+  let browser;
+  let context = existingContext;
+  let page;
+
+  try {
+    if (!context) {
+      browser = await BROWSERS[browserName].launch({ headless: true });
+      context = await browser.newContext({
+        viewport: { width, height },
+        colorScheme,
+      });
+    }
+
+    page = await context.newPage();
+    await page.setViewportSize({ width, height });
+
+    await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 });
+
+    if (beforeScreenshot) {
+      await beforeScreenshot(page, { url, name, highlights });
+    }
+
+    // if there are highlights, scroll the first target into view
+    if (highlights.length > 0 && highlights[0].selector) {
+      await scrollIntoView(page, highlights[0].selector).catch(() => {});
+    }
+
+    const cleanup = await injectHighlights(page, highlights);
+
+    // small pause to let any CSS transitions finish after highlight injection
+    await page.waitForTimeout(150);
+
+    const buffer = await page.screenshot({
+      type: 'png',
+      fullPage,
+      animations: 'disabled',
+    });
+
+    await cleanup();
+    await page.close();
+
+    return buffer;
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+  }
+}
+
+/**
+ * Create a persistent browser context for taking multiple screenshots.
+ * Caller is responsible for calling context.close() when done.
+ *
+ * @param {object} opts
+ * @param {'webkit'|'chromium'|'firefox'} [opts.browser='webkit']
+ * @param {number} [opts.width=1280]
+ * @param {number} [opts.height=800]
+ * @param {'light'|'dark'} [opts.colorScheme='light']
+ * @returns {Promise<{browser: import('playwright').Browser, context: import('playwright').BrowserContext}>}
+ */
+export async function createBrowserContext({ browser: browserName = 'webkit', width = 1280, height = 800, colorScheme = 'light' } = {}) {
+  const browser = await BROWSERS[browserName].launch({ headless: true });
+  const context = await browser.newContext({
+    viewport: { width, height },
+    colorScheme,
+  });
+  return { browser, context };
+}