astro-better-generate-screenshots 0.4.2

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Better Static Sites
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# astro-better-generate-screenshots
+
+CLI that generates the screenshot PNGs consumed by astro-better-declarative-screenshots.
+
+## Install
+
+```sh
+npm install astro-better-generate-screenshots
+```
+
+## What it does
+
+- Starts Docker and captures pages with Playwright WebKit
+- Injects highlights and composites window chrome
+- Diffs against committed PNGs to detect drift
+
+## Documentation
+
+Full documentation, including configuration and examples, is at
+[https://better-static-sites.github.io/content/declarative-screenshots](https://better-static-sites.github.io/content/declarative-screenshots).
+
+This package is published from the [Better Static Sites monorepo](https://github.com/better-static-sites/better-static-sites.github.io); the directory it lives in has a combined README covering it and its sibling package.

package/index.mjs

@@ -0,0 +1,55 @@
+// Astro integration entry point.
+// usage in astro.config.mjs:
+//   import screenshots from 'astro-better-generate-screenshots';
+//   export default defineConfig({ integrations: [screenshots()] });
+
+import { loadConfig } from 'astro-better-declarative-screenshots';
+import path from 'path';
+
+/**
+ * @param {Partial<import('astro-better-declarative-screenshots').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, deriveName } from 'astro-better-declarative-screenshots';
+export { discoverScreenshots } from './src/discover.mjs';

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "astro-better-generate-screenshots",
+  "version": "0.4.2",
+  "description": "CLI that generates screenshot PNGs for astro-better-declarative-screenshots",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/better-static-sites/better-static-sites.github.io.git",
+    "directory": "astro-better-declarative-screenshots/generate-screenshots"
+  },
+  "homepage": "https://better-static-sites.github.io",
+  "bugs": {
+    "url": "https://github.com/better-static-sites/better-static-sites.github.io/issues"
+  },
+  "type": "module",
+  "bin": {
+    "take-screenshots": "./scripts/take-screenshots.mjs",
+    "check-screenshots": "./scripts/check-screenshots.mjs"
+  },
+  "exports": {
+    ".": "./index.mjs",
+    "./scripts/take-screenshots.mjs": "./scripts/take-screenshots.mjs",
+    "./scripts/check-screenshots.mjs": "./scripts/check-screenshots.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "src/",
+    "scripts/"
+  ],
+  "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",
+    "astro-better-declarative-screenshots": "^0.4.1"
+  },
+  "peerDependencies": {
+    "astro": ">=4.0.0"
+  }
+}

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 'astro-better-declarative-screenshots';
+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 'astro-better-declarative-screenshots';
+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' && config.chrome.renderIn !== 'css') {
+        finalBuffer = await addChrome(rawBuffer, {
+          url: fullUrl,
+          dark: config.chrome.theme === '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,112 @@
+// 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 'astro-better-declarative-screenshots';
+
+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('astro-better-declarative-screenshots').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,
+        deviceScaleFactor: 2,
+      });
+    }
+
+    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 (fullPage) {
+      // full-page captures render from y=0; scrolling first would displace sticky/fixed elements
+      await page.evaluate(() => window.scrollTo(0, 0));
+    } else 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,
+    deviceScaleFactor: 2,
+  });
+  return { browser, context };
+}

package/src/chrome.mjs

@@ -0,0 +1,166 @@
+// composes a macOS Safari-style window chrome around a screenshot buffer.
+// everything is generated programmatically via sharp + SVG -- no PNG templates.
+
+import sharp from 'sharp';
+
+const WINDOW_RADIUS = 10;
+const CHROME_HEIGHT = 52;
+const TL_CY = 26;
+const TL_X0 = 18;
+const TL_R = 7;
+const TL_GAP = 9;
+const URL_BAR_H = 28;
+const URL_BAR_Y = (CHROME_HEIGHT - URL_BAR_H) / 2;  // vertically centered
+const URL_BAR_X = 100;
+const URL_BAR_X_MARGIN_R = 20;
+const URL_BAR_RADIUS = 5;
+
+export async function addChrome(screenshotBuffer, opts = {}) {
+  const {
+    url = '',
+    dark = false,
+    showUrl = true,
+    shadowBlur = 40,
+    shadowPadding = 48,
+  } = opts;
+
+  const pageImg = sharp(screenshotBuffer);
+  const { width: pageWidth, height: pageHeight } = await pageImg.metadata();
+
+  const chromeHeight = showUrl ? CHROME_HEIGHT : Math.floor(CHROME_HEIGHT * 0.6);
+  const totalWidth = pageWidth + (shadowBlur > 0 ? shadowPadding * 2 : 0);
+  const totalHeight = pageHeight + chromeHeight + (shadowBlur > 0 ? shadowPadding * 2 : 0);
+
+  const windowX = shadowBlur > 0 ? shadowPadding : 0;
+  const windowY = shadowBlur > 0 ? shadowPadding : 0;
+  const windowWidth = pageWidth;
+  const windowHeight = pageHeight + chromeHeight;
+
+  const chromeSvg = buildChromeSvg({ windowWidth, chromeHeight, dark, showUrl, url });
+
+  const chromeBuf = await sharp(Buffer.from(chromeSvg))
+    .resize(windowWidth, chromeHeight)
+    .png()
+    .toBuffer();
+
+  // round the bottom corners of the page to match the window border radius
+  const cornerMask = `<svg xmlns="http://www.w3.org/2000/svg" width="${pageWidth}" height="${pageHeight}">
+    <path d="M 0,0 H ${pageWidth} V ${pageHeight - WINDOW_RADIUS}
+      Q ${pageWidth},${pageHeight} ${pageWidth - WINDOW_RADIUS},${pageHeight}
+      H ${WINDOW_RADIUS} Q 0,${pageHeight} 0,${pageHeight - WINDOW_RADIUS} Z"
+      fill="white"/>
+  </svg>`;
+  const maskedPage = await sharp(screenshotBuffer)
+    .composite([{ input: Buffer.from(cornerMask), blend: 'dest-in' }])
+    .png()
+    .toBuffer();
+
+  const layers = [];
+
+  if (shadowBlur > 0) {
+    const shadowSvg = buildShadowSvg({
+      totalWidth, totalHeight, windowX, windowY,
+      windowWidth, windowHeight, shadowBlur,
+    });
+    const shadowBuf = await sharp(Buffer.from(shadowSvg))
+      .resize(totalWidth, totalHeight)
+      .png()
+      .toBuffer();
+    layers.push({ input: shadowBuf, top: 0, left: 0 });
+  }
+
+  layers.push({ input: maskedPage, top: windowY + chromeHeight, left: windowX });
+  layers.push({ input: chromeBuf, top: windowY, left: windowX });
+
+  const base = {
+    create: {
+      width: totalWidth,
+      height: totalHeight,
+      channels: 4,
+      background: { r: 0, g: 0, b: 0, alpha: 0 },
+    },
+  };
+
+  return sharp(base).composite(layers).png().toBuffer();
+}
+
+function buildChromeSvg({ windowWidth, chromeHeight, dark, showUrl, url }) {
+  const bg        = dark ? '#323232' : '#e8e8e8';
+  const bgBottom  = dark ? '#2c2c2c' : '#dcdcdc';
+  const urlBarBg  = dark ? '#454547' : '#ffffff';
+  const urlBorder = dark ? '#5a5a5c' : '#cacaca';
+  const urlText   = dark ? '#f0f0f0' : '#111111';
+  const separator = dark ? '#1a1a1a' : '#b8b8b8';
+
+  const tlColors = ['#ff5f57', '#febc2e', '#28c840'];
+  const lights = tlColors.map((color, i) => {
+    const cx = TL_X0 + i * (TL_R * 2 + TL_GAP);
+    return `<circle cx="${cx}" cy="${TL_CY}" r="${TL_R}" fill="${color}"/>`;
+  }).join('\n    ');
+
+  let urlBar = '';
+  if (showUrl) {
+    const barX = URL_BAR_X;
+    const barY = URL_BAR_Y;
+    const barW = windowWidth - URL_BAR_X - URL_BAR_X_MARGIN_R;
+    const displayUrl = url.length > 90 ? url.slice(0, 87) + '...' : url;
+    urlBar = `
+    <rect x="${barX}" y="${barY}" width="${barW}" height="${URL_BAR_H}"
+      rx="${URL_BAR_RADIUS}" fill="${urlBarBg}" stroke="${urlBorder}" stroke-width="1"/>
+    <text
+      x="${barX + barW / 2}"
+      y="${barY + URL_BAR_H / 2 + 5}"
+      text-anchor="middle"
+      font-family="Arial, sans-serif"
+      font-size="13"
+      fill="${urlText}"
+    >${escapeXml(displayUrl)}</text>`;
+  }
+
+  // gradient: slightly lighter top, slightly darker bottom
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${windowWidth}" height="${chromeHeight}">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="${bg}"/>
+      <stop offset="100%" stop-color="${bgBottom}"/>
+    </linearGradient>
+  </defs>
+  <rect width="${windowWidth}" height="${chromeHeight}" fill="url(#bg)" rx="${WINDOW_RADIUS}" ry="${WINDOW_RADIUS}"/>
+  <rect x="0" y="${chromeHeight - WINDOW_RADIUS}" width="${windowWidth}" height="${WINDOW_RADIUS}" fill="${bgBottom}"/>
+  <line x1="0" y1="${chromeHeight - 0.5}" x2="${windowWidth}" y2="${chromeHeight - 0.5}"
+    stroke="${separator}" stroke-width="1"/>
+  ${lights}
+  ${urlBar}
+</svg>`;
+}
+
+function buildShadowSvg({ totalWidth, totalHeight, windowX, windowY, windowWidth, windowHeight, shadowBlur }) {
+  const halfBlur = shadowBlur / 2;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="${totalHeight}">
+  <defs>
+    <filter id="shadow" x="-50%" y="-50%" width="200%" height="200%">
+      <feDropShadow
+        dx="0" dy="${halfBlur / 2}"
+        stdDeviation="${halfBlur}"
+        flood-color="rgba(0,0,0,0.35)"
+      />
+    </filter>
+  </defs>
+  <rect
+    x="${windowX}" y="${windowY}"
+    width="${windowWidth}" height="${windowHeight}"
+    rx="${WINDOW_RADIUS}" ry="${WINDOW_RADIUS}"
+    fill="white"
+    filter="url(#shadow)"
+  />
+</svg>`;
+}
+
+function escapeXml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}

package/src/diff.mjs

@@ -0,0 +1,80 @@
+// pixel-level diff between an existing screenshot and a newly captured one.
+// used by check-screenshots to detect visual regressions in CI.
+
+import { PNG } from 'pngjs';
+import pixelmatch from 'pixelmatch';
+import { readFileSync } from 'fs';
+import sharp from 'sharp';
+
+/**
+ * @typedef {Object} DiffResult
+ * @property {number} pixels - total number of differing pixels
+ * @property {number} ratio - differing pixels / total pixels (0..1)
+ * @property {Buffer|null} diffImage - PNG buffer visualizing the diff, or null if identical
+ */
+
+/**
+ * Compare a newly captured PNG buffer against the on-disk reference file.
+ *
+ * @param {string} referencePath - absolute path to the reference PNG
+ * @param {Buffer} newBuffer - PNG buffer from a fresh capture
+ * @param {object} [opts]
+ * @param {number} [opts.threshold=0.1] - pixelmatch threshold (0 = strict, 1 = lenient)
+ * @param {boolean} [opts.writeDiff=false] - include the diff image buffer in the result
+ * @returns {Promise<DiffResult>}
+ */
+export async function diffScreenshot(referencePath, newBuffer, opts = {}) {
+  const { threshold = 0.1, writeDiff = false } = opts;
+
+  let refBuffer;
+  try {
+    refBuffer = readFileSync(referencePath);
+  } catch {
+    // reference doesn't exist -- treat as fully different
+    return { pixels: -1, ratio: 1, diffImage: null };
+  }
+
+  // normalize both images to the same dimensions before diffing
+  const [refNorm, newNorm] = await Promise.all([
+    normalizeSize(refBuffer),
+    normalizeSize(newBuffer),
+  ]);
+
+  const refPng = PNG.sync.read(refNorm);
+  const newPng = PNG.sync.read(newNorm);
+
+  // if dimensions differ after normalization, sizes changed -- treat as fully different
+  if (refPng.width !== newPng.width || refPng.height !== newPng.height) {
+    return {
+      pixels: refPng.width * refPng.height,
+      ratio: 1,
+      diffImage: null,
+    };
+  }
+
+  const { width, height } = refPng;
+  const totalPixels = width * height;
+  const diffPng = writeDiff ? new PNG({ width, height }) : null;
+
+  const diffPixels = pixelmatch(
+    refPng.data,
+    newPng.data,
+    diffPng?.data ?? null,
+    width,
+    height,
+    { threshold }
+  );
+
+  const diffImage = diffPng ? PNG.sync.write(diffPng) : null;
+
+  return {
+    pixels: diffPixels,
+    ratio: diffPixels / totalPixels,
+    diffImage,
+  };
+}
+
+async function normalizeSize(buffer) {
+  // re-encode via sharp to ensure consistent PNG format and strip metadata
+  return sharp(buffer).png().toBuffer();
+}

package/src/discover.mjs

@@ -0,0 +1,128 @@
+// scans MDX/Astro source files for Screenshot components and extracts their specs.
+// this is how the CLI knows what screenshots to take without running the full Astro build.
+
+import { readFileSync } from 'fs';
+import { glob } from 'glob';
+import path from 'path';
+import { deriveName } from 'astro-better-declarative-screenshots';
+
+/**
+ * @typedef {Object} HighlightSpec
+ * @property {string} selector
+ * @property {'border'|'arrow'|'both'} style
+ * @property {string} color
+ * @property {string} label
+ * @property {number} borderWidth
+ */
+
+/**
+ * @typedef {Object} ScreenshotSpec
+ * @property {string} url
+ * @property {string} name - derived output filename without extension
+ * @property {HighlightSpec[]} highlights
+ * @property {number|undefined} width
+ * @property {number|undefined} height
+ * @property {boolean} fullPage
+ * @property {string} sourceFile - absolute path of the file containing this Screenshot
+ */
+
+/**
+ * Scan a project's source files and return all Screenshot specs.
+ *
+ * @param {string} projectRoot - absolute path to the project root
+ * @param {string[]} [patterns] - glob patterns relative to projectRoot; default scans src/**
+ * @returns {Promise<ScreenshotSpec[]>}
+ */
+export async function discoverScreenshots(projectRoot, patterns) {
+  const defaultPatterns = ['src/**/*.mdx', 'src/**/*.md', 'src/**/*.astro'];
+  const globs = (patterns ?? defaultPatterns).map(p => path.join(projectRoot, p));
+
+  const files = (
+    await Promise.all(globs.map(pattern => glob(pattern, { absolute: true })))
+  ).flat();
+
+  const used = new Set();
+  const specs = [];
+
+  for (const file of files) {
+    const fileSpecs = parseFile(file, used);
+    specs.push(...fileSpecs);
+  }
+
+  return specs;
+}
+
+function parseFile(filePath, used) {
+  let source;
+  try {
+    source = readFileSync(filePath, 'utf8');
+  } catch {
+    return [];
+  }
+
+  const specs = [];
+
+  // find all <Screenshot ...> blocks, including multiline
+  // we look for <Screenshot, then collect attributes until we see > or />
+  // then look for Highlight children until </Screenshot>
+  const screenshotRe = /<Screenshot\b([\s\S]*?)(?:\/>|>([\s\S]*?)<\/Screenshot>)/g;
+  let match;
+
+  while ((match = screenshotRe.exec(source)) !== null) {
+    const attrBlock = match[1];
+    const childBlock = match[2] ?? '';
+
+    const url = extractProp(attrBlock, 'url');
+    if (!url) continue;
+
+    const id = extractProp(attrBlock, 'id');
+    const widthStr = extractProp(attrBlock, 'width');
+    const heightStr = extractProp(attrBlock, 'height');
+    const fullPageStr = extractProp(attrBlock, 'fullPage');
+
+    const highlights = parseHighlightChildren(childBlock);
+    const name = id ?? deriveName(url, highlights, used);
+
+    specs.push({
+      url,
+      name,
+      highlights,
+      width:    widthStr  ? parseInt(widthStr, 10)  : undefined,
+      height:   heightStr ? parseInt(heightStr, 10) : undefined,
+      fullPage: fullPageStr === 'true' || fullPageStr === '{true}',
+      sourceFile: filePath,
+    });
+  }
+
+  return specs;
+}
+
+function extractProp(attrBlock, propName) {
+  // matches: propName="value" or propName={'value'} or propName={value}
+  const re = new RegExp(
+    `${propName}\\s*=\\s*(?:"([^"]*?)"|'([^']*?)'|\\{['"](.*?)['"]}|\\{([^}]+?)\\})`,
+    's'
+  );
+  const m = re.exec(attrBlock);
+  if (!m) return undefined;
+  return (m[1] ?? m[2] ?? m[3] ?? m[4] ?? '').trim();
+}
+
+function parseHighlightChildren(childBlock) {
+  const highlights = [];
+  const highlightRe = /<Highlight\b([^>]*?)(?:\/>|>[\s\S]*?<\/Highlight>)/g;
+  let m;
+  while ((m = highlightRe.exec(childBlock)) !== null) {
+    const attrs = m[1];
+    const selector = extractProp(attrs, 'selector');
+    if (!selector) continue;
+    highlights.push({
+      selector,
+      style:       extractProp(attrs, 'style')       ?? 'border',
+      color:       extractProp(attrs, 'color')       ?? '#f60',
+      label:       extractProp(attrs, 'label')       ?? '',
+      borderWidth: parseInt(extractProp(attrs, 'borderWidth') ?? '3', 10),
+    });
+  }
+  return highlights;
+}

package/src/docker.mjs

@@ -0,0 +1,123 @@
+// manages the Docker container lifecycle for screenshot sessions.
+// starts the container, optionally loads a bootstrap/kickstart file, polls
+// a health check URL until the app is ready, then runs an optional postStart command.
+
+import { execSync } from 'child_process';
+import { readFileSync } from 'fs';
+import path from 'path';
+
+/**
+ * Start the Docker service described in config.docker and wait for it to be healthy.
+ * After the healthcheck passes, runs docker.postStart if defined.
+ *
+ * @param {import('astro-better-declarative-screenshots').DockerConfig} dockerConfig
+ * @param {string} projectRoot
+ * @returns {Promise<void>}
+ */
+export async function startDocker(dockerConfig, projectRoot) {
+  if (!dockerConfig) return;
+
+  const composePath = dockerConfig.compose
+    ? path.resolve(projectRoot, dockerConfig.compose)
+    : null;
+
+  if (composePath) {
+    // support both 'bootstrap' (preferred) and 'kickstart' (legacy alias)
+    const bootstrapPath = dockerConfig.bootstrap ?? dockerConfig.kickstart;
+    const env = buildEnv(dockerConfig.env ?? {}, bootstrapPath, projectRoot);
+    const serviceArg = dockerConfig.service ? ` ${dockerConfig.service}` : '';
+
+    console.log(`[docker] starting services via ${path.relative(projectRoot, composePath)}`);
+    execSync(
+      `docker compose -f "${composePath}" up -d${serviceArg}`,
+      { stdio: 'inherit', env: { ...process.env, ...env } }
+    );
+  }
+
+  console.log(`[docker] waiting for ${dockerConfig.healthcheck.url}`);
+  await pollHealthcheck(dockerConfig.healthcheck);
+  console.log('[docker] app is ready');
+
+  if (dockerConfig.postStart) {
+    console.log(`[docker] running postStart: ${dockerConfig.postStart}`);
+    execSync(dockerConfig.postStart, {
+      stdio: 'inherit',
+      cwd: projectRoot,
+      env: process.env,
+    });
+  }
+}
+
+/**
+ * Stop containers started for this session.
+ * Does NOT remove volumes -- use `docker compose down -v` manually to reset seed data.
+ *
+ * @param {import('astro-better-declarative-screenshots').DockerConfig} dockerConfig
+ * @param {string} projectRoot
+ */
+export function stopDocker(dockerConfig, projectRoot) {
+  if (!dockerConfig?.compose) return;
+
+  const composePath = path.resolve(projectRoot, dockerConfig.compose);
+  console.log('[docker] stopping services');
+  try {
+    execSync(`docker compose -f "${composePath}" down`, { stdio: 'inherit' });
+  } catch (e) {
+    console.warn('[docker] warning: docker compose down failed:', e.message);
+  }
+}
+
+async function pollHealthcheck({ url, timeout = 60000, interval = 2000 }) {
+  const deadline = Date.now() + timeout;
+  let lastError;
+  let attempts = 0;
+
+  while (Date.now() < deadline) {
+    attempts++;
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(interval) });
+      if (res.ok) {
+        if (attempts > 1) process.stdout.write('\n');
+        return;
+      }
+      lastError = new Error(`HTTP ${res.status}`);
+    } catch (e) {
+      lastError = e;
+    }
+    process.stdout.write('.');
+    await sleep(interval);
+  }
+
+  process.stdout.write('\n');
+  throw new Error(
+    `[docker] health check timed out after ${timeout}ms waiting for ${url}` +
+    (lastError ? `: ${lastError.message}` : '')
+  );
+}
+
+function buildEnv(extraEnv, bootstrapPath, projectRoot) {
+  const env = { ...extraEnv };
+  if (bootstrapPath) {
+    const absPath = path.resolve(projectRoot, bootstrapPath);
+    let content;
+    try {
+      content = readFileSync(absPath, 'utf8');
+    } catch {
+      throw new Error(`[docker] bootstrap file not found: ${absPath}`);
+    }
+    // expose bootstrap content and path as env vars.
+    // the docker-compose.yml can wire these into the container however it needs.
+    // for FusionAuth: set FUSIONAUTH_APP_KICKSTART_FILE to SCREENSHOT_BOOTSTRAP_PATH.
+    // for other apps: mount the file or use the content as a seed script input.
+    env.SCREENSHOT_BOOTSTRAP_CONTENT = content;
+    env.SCREENSHOT_BOOTSTRAP_PATH    = absPath;
+    // legacy alias for backward compat
+    env.SCREENSHOT_KICKSTART_CONTENT = content;
+    env.SCREENSHOT_KICKSTART_PATH    = absPath;
+  }
+  return env;
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/placeholder.mjs

@@ -0,0 +1,53 @@
+// generates a placeholder PNG for a screenshot that has not yet been taken.
+// the placeholder is gray with white centered text showing the filename.
+// sharp is used so the placeholder is a real PNG, not a data URI.
+
+import sharp from 'sharp';
+
+/**
+ * @param {object} opts
+ * @param {string} opts.name - screenshot name (without extension), shown as label
+ * @param {number} [opts.width=1280]
+ * @param {number} [opts.height=800]
+ * @returns {Promise<Buffer>} PNG buffer
+ */
+export async function generatePlaceholder({ name, width = 1280, height = 800 }) {
+  const label = name + '.png';
+  const fontSize = Math.min(20, Math.floor(width / 40));
+
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+    <rect width="${width}" height="${height}" fill="#e8e8e8"/>
+    <line x1="0" y1="0" x2="${width}" y2="${height}" stroke="#ccc" stroke-width="1"/>
+    <line x1="${width}" y1="0" x2="0" y2="${height}" stroke="#ccc" stroke-width="1"/>
+    <rect x="${width / 2 - 200}" y="${height / 2 - 40}" width="400" height="80" rx="8" fill="white" opacity="0.8"/>
+    <text
+      x="${width / 2}"
+      y="${height / 2 - 6}"
+      text-anchor="middle"
+      dominant-baseline="middle"
+      font-family="sans-serif"
+      font-size="${fontSize}"
+      fill="#666"
+    >Screenshot not generated</text>
+    <text
+      x="${width / 2}"
+      y="${height / 2 + fontSize + 4}"
+      text-anchor="middle"
+      dominant-baseline="middle"
+      font-family="monospace"
+      font-size="${Math.max(10, fontSize - 4)}"
+      fill="#999"
+    >${escapeXml(label)}</text>
+  </svg>`;
+
+  return sharp(Buffer.from(svg)).png().toBuffer();
+}
+
+function escapeXml(str) {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}