astro-better-declarative-screenshots 0.1.0

package/src/chrome.mjs

@@ -0,0 +1,153 @@
+// 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 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();
+
+  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: screenshotBuffer, 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="10" ry="10"/>
+  <rect x="0" y="${chromeHeight - 10}" width="${windowWidth}" height="10" 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="10" ry="10"
+    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/config.mjs

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+import { pathToFileURL } from 'url';
+import { existsSync } from 'fs';
+import path from 'path';
+
+const WindowSizeSchema = z.object({
+  width: z.number().int().positive(),
+  height: z.number().int().positive(),
+});
+
+const DockerSchema = z.object({
+  // path to a docker-compose file
+  compose: z.string().optional(),
+  // specific service to start (omit to start all services in the compose file)
+  service: z.string().optional(),
+  // health check URL -- polled until 200 or timeout
+  healthcheck: z.object({
+    url: z.string().url(),
+    timeout: z.number().int().positive().default(60000),
+    interval: z.number().int().positive().default(2000),
+  }),
+  // path to a bootstrap/seed file to pass into the container.
+  // exposed to docker-compose.yml as env vars SCREENSHOT_BOOTSTRAP_PATH and
+  // SCREENSHOT_BOOTSTRAP_CONTENT. wire these into your container however it needs
+  // (e.g. FUSIONAUTH_APP_KICKSTART_FILE=SCREENSHOT_BOOTSTRAP_PATH for FusionAuth,
+  //  or mount the path as a volume for other apps).
+  bootstrap: z.string().optional(),
+  // legacy alias for bootstrap -- 'kickstart' still works
+  kickstart: z.string().optional(),
+  // shell command to run after the health check passes and before beforeAll.
+  // runs in the project root. useful for database migrations, seed scripts, etc.
+  // example: 'node scripts/seed.js' or 'docker exec app npm run db:seed'
+  postStart: z.string().optional(),
+  // arbitrary env vars merged into the container environment when running compose up
+  env: z.record(z.string()).optional(),
+});
+
+const ChromeSchema = z.object({
+  // 'safari-macos' | 'none'
+  style: z.enum(['safari-macos', 'none']).default('safari-macos'),
+  // show the URL bar in the chrome
+  showUrl: z.boolean().default(true),
+  // dark chrome (title bar) regardless of page dark mode
+  dark: z.boolean().default(false),
+  // drop shadow radius in pixels; 0 to disable
+  shadowBlur: z.number().int().min(0).default(40),
+  // extra padding around the window to make room for the shadow
+  shadowPadding: z.number().int().min(0).default(48),
+});
+
+const ConfigSchema = z.object({
+  // base URL of the running app
+  baseUrl: z.string().url(),
+
+  // where to write screenshot PNGs -- relative to the project root
+  outputDir: z.string().default('./src/assets/screenshots'),
+
+  // default window dimensions
+  window: WindowSizeSchema.default({ width: 1280, height: 800 }),
+
+  // minimum and maximum window dimensions enforced globally
+  minWindow: WindowSizeSchema.default({ width: 640, height: 400 }),
+  maxWindow: WindowSizeSchema.default({ width: 2560, height: 1600 }),
+
+  // maximum dimensions for full-page captures
+  maxFullPage: WindowSizeSchema.default({ width: 2560, height: 8000 }),
+
+  // window chrome style
+  chrome: ChromeSchema.default({}),
+
+  // browser engine -- webkit gives the most Safari-accurate render
+  browser: z.enum(['webkit', 'chromium', 'firefox']).default('webkit'),
+
+  // default color scheme
+  colorScheme: z.enum(['light', 'dark']).default('light'),
+
+  // docker service configuration -- optional when the app is already running
+  docker: DockerSchema.optional(),
+
+  // strict mode -- fail the build when a screenshot file is missing
+  // defaults to true when SCREENSHOTS_STRICT=true env var is set
+  strict: z.boolean().default(process.env.SCREENSHOTS_STRICT === 'true'),
+
+  // called once before all screenshots are taken (good for login flows)
+  beforeAll: z.function().args(z.any()).returns(z.promise(z.any())).optional(),
+
+  // called before each individual screenshot
+  beforeScreenshot: z.function().args(z.any(), z.any()).returns(z.promise(z.any())).optional(),
+
+  // called once after all screenshots are taken
+  afterAll: z.function().returns(z.promise(z.any())).optional(),
+});
+
+export async function loadConfig(projectRoot) {
+  const candidates = [
+    path.join(projectRoot, 'screenshot.config.mjs'),
+    path.join(projectRoot, 'screenshot.config.js'),
+  ];
+
+  const configPath = candidates.find(existsSync);
+  if (!configPath) {
+    throw new Error(
+      `No screenshot.config.mjs found in ${projectRoot}. ` +
+      `Create one -- see the README for the full config reference.`
+    );
+  }
+
+  const raw = await import(/* @vite-ignore */ pathToFileURL(configPath).href);
+  const config = raw.default ?? raw;
+
+  const result = ConfigSchema.safeParse(config);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map(i => `  ${i.path.join('.')}: ${i.message}`)
+      .join('\n');
+    throw new Error(`screenshot.config.mjs is invalid:\n${issues}`);
+  }
+
+  return result.data;
+}
+
+export { ConfigSchema, DockerSchema };

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 './naming.mjs';
+
+/**
+ * @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('./config.mjs').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('./config.mjs').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));
+}