astro-better-declarative-screenshots 0.1.0

package/.github/workflows/check-screenshots.yml

@@ -0,0 +1,68 @@
+name: Check screenshots
+
+on:
+  schedule:
+    # every Monday at 9am UTC -- catches visual drift from app updates
+    - cron: '0 9 * * 1'
+  workflow_dispatch:
+    inputs:
+      filter:
+        description: 'Filter: only check screenshots matching this string'
+        required: false
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps webkit
+
+      - name: Check screenshots
+        run: |
+          FILTER="${{ github.event.inputs.filter }}"
+          if [ -n "$FILTER" ]; then
+            npx check-screenshots --filter="$FILTER" --diff-dir=.screenshot-diffs
+          else
+            npx check-screenshots --diff-dir=.screenshot-diffs
+          fi
+
+      - name: Upload diff artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: screenshot-diffs
+          path: .screenshot-diffs/
+          retention-days: 14
+
+      - name: Comment on PR with diff summary
+        if: failure() && github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const diffs = fs.readdirSync('.screenshot-diffs').filter(f => f.endsWith('.diff.png'));
+            const body = [
+              '## Screenshot changes detected',
+              '',
+              `${diffs.length} screenshot(s) changed:`,
+              ...diffs.map(f => `- \`${f.replace('.diff.png', '')}\``),
+              '',
+              'Download the `screenshot-diffs` artifact to review the changes.',
+              'If they are intentional, run `take-screenshots` locally to update the reference files.',
+            ].join('\n');
+            github.rest.issues.createComment({
+              ...context.repo,
+              issue_number: context.issue.number,
+              body,
+            });

package/CONFIGURATION.md

@@ -0,0 +1,251 @@
+# Configuration reference
+
+All configuration lives in `screenshot.config.mjs` at your Astro project root.
+
+```js
+export default {
+  // ...
+};
+```
+
+---
+
+## Top-level options
+
+### `baseUrl` (required)
+
+The base URL of the running app. Screenshot URLs are resolved relative to this.
+
+```js
+baseUrl: 'http://localhost:9011'
+```
+
+### `outputDir`
+
+Where to write screenshot PNGs, relative to the project root.
+
+Default: `'./src/assets/screenshots'`
+
+```js
+outputDir: 'public/screenshots'
+```
+
+Note: if you store screenshots in `public/`, they are served as static files without Astro's asset pipeline. If you store them in `src/assets/`, Astro can optimize them. Pick based on whether you want image optimization.
+
+### `browser`
+
+Playwright browser engine.
+
+Default: `'webkit'`
+
+Options: `'webkit'` | `'chromium'` | `'firefox'`
+
+WebKit gives the most accurate rendering for macOS Safari-style chrome. Use Chromium for CI environments where WebKit may not be available.
+
+### `colorScheme`
+
+Default color scheme for captured pages.
+
+Default: `'light'`
+
+Options: `'light'` | `'dark'`
+
+### `strict`
+
+When `true`, `<Screenshot>` throws at build time if the PNG file is missing. Defaults to the value of the `SCREENSHOTS_STRICT` environment variable.
+
+Default: `false`
+
+---
+
+## `window`
+
+Default viewport dimensions.
+
+```js
+window: { width: 1280, height: 800 }
+```
+
+Per-screenshot overrides are available via the `<Screenshot width height />` props.
+
+### `minWindow` / `maxWindow`
+
+Viewport size guardrails. Any per-screenshot `width`/`height` values are clamped to these bounds.
+
+```js
+minWindow: { width: 640, height: 400 },
+maxWindow: { width: 2560, height: 1600 },
+```
+
+### `maxFullPage`
+
+Maximum dimensions for full-page captures.
+
+```js
+maxFullPage: { width: 2560, height: 8000 }
+```
+
+---
+
+## `chrome`
+
+Window chrome composited over each screenshot.
+
+```js
+chrome: {
+  style:         'safari-macos',  // or 'none'
+  showUrl:       true,
+  dark:          false,
+  shadowBlur:    40,
+  shadowPadding: 48,
+}
+```
+
+### `chrome.style`
+
+`'safari-macos'` renders a macOS Safari-style title bar with traffic lights and a URL bar.
+`'none'` skips chrome entirely.
+
+### `chrome.showUrl`
+
+Whether to render the URL bar inside the chrome.
+
+### `chrome.dark`
+
+Use dark chrome regardless of page color scheme.
+
+### `chrome.shadowBlur`
+
+Drop shadow blur radius in pixels. Set to `0` to disable the shadow.
+
+### `chrome.shadowPadding`
+
+Extra padding added around the window to accommodate the shadow. Increase this if the shadow is clipped.
+
+---
+
+## `docker`
+
+Docker service configuration. The CLI boots this service before capturing screenshots and shuts it down when done.
+
+```js
+docker: {
+  compose:   'docker-compose.yml',
+  service:   'app',
+  kickstart: 'kickstart/bootstrap.json',
+  healthcheck: {
+    url:      'http://localhost:9011/api/status',
+    timeout:  60000,
+    interval: 2000,
+  },
+  env: {
+    DATABASE_PASSWORD: 'change-in-production',
+  },
+},
+```
+
+### `docker.compose`
+
+Path to a `docker-compose.yml` file, relative to the project root. The CLI runs `docker compose -f <compose> up -d [service]`.
+
+### `docker.service`
+
+The specific Docker Compose service to start. If omitted, all services in the file are started.
+
+### `docker.bootstrap`
+
+Path to a seed/bootstrap file to pass into the container, relative to the project root. Two environment variables become available inside `docker-compose.yml`:
+
+- `SCREENSHOT_BOOTSTRAP_PATH` -- absolute path to the file on the host
+- `SCREENSHOT_BOOTSTRAP_CONTENT` -- the file's full text content
+
+Wire these into your container however your app needs them. Examples:
+
+**FusionAuth** (kickstart):
+```yaml
+environment:
+  FUSIONAUTH_APP_KICKSTART_FILE: ${SCREENSHOT_BOOTSTRAP_PATH}
+```
+
+**Node.js app** (seed script via bind mount):
+```yaml
+volumes:
+  - ${SCREENSHOT_BOOTSTRAP_PATH}:/app/seed.json:ro
+```
+
+**Generic** (pass as env var for a custom entrypoint):
+```yaml
+environment:
+  APP_SEED_DATA: ${SCREENSHOT_BOOTSTRAP_CONTENT}
+```
+
+`kickstart` is accepted as a legacy alias for `bootstrap`.
+
+### `docker.postStart`
+
+Optional shell command to run after the health check passes and before `beforeAll`. Runs in the project root with the project's environment. Use for database migrations, extra seeding, or any setup that can't be bundled into the container's startup.
+
+```js
+postStart: 'node scripts/seed-extra.mjs'
+// or: 'docker exec myapp-1 npm run db:migrate'
+```
+
+### `docker.healthcheck.url`
+
+URL polled to determine when the app is ready. The CLI waits for an HTTP 200 response before proceeding.
+
+### `docker.healthcheck.timeout`
+
+Maximum time in milliseconds to wait for the health check. Default: `60000` (1 minute).
+
+### `docker.healthcheck.interval`
+
+Polling interval in milliseconds. Default: `2000`.
+
+### `docker.env`
+
+Extra environment variables merged into the container environment when running `docker compose up`.
+
+---
+
+## Hooks
+
+Hooks are async functions that let you run code at key points in the capture lifecycle.
+
+### `beforeAll`
+
+Called once before any screenshots are taken. Receives a Playwright `BrowserContext`. Use this for login flows or global app state setup.
+
+```js
+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', 'supersecret');
+  await page.click('[type=submit]');
+  await page.waitForURL('**/admin/**');
+  await page.close();
+},
+```
+
+### `beforeScreenshot`
+
+Called before each individual screenshot. Receives the Playwright `Page` (already navigated to the target URL) and a spec object `{ url, name, highlights }`. Use this to dismiss notifications, close modals, or set up per-page state.
+
+```js
+beforeScreenshot: async (page, { url, name }) => {
+  await page.evaluate(() => {
+    document.querySelectorAll('.notification').forEach(el => el.remove());
+  });
+},
+```
+
+### `afterAll`
+
+Called once after all screenshots are taken. Use for cleanup.
+
+```js
+afterAll: async () => {
+  console.log('done');
+},
+```

package/Highlight.astro

@@ -0,0 +1,31 @@
+---
+interface Props {
+  selector: string;
+  style?: 'border' | 'arrow' | 'both';
+  color?: string;
+  label?: string;
+  borderWidth?: number;
+}
+
+const {
+  selector,
+  style = 'border',
+  color = '#f60',
+  label,
+  borderWidth = 3,
+} = Astro.props;
+---
+{/*
+  Renders a hidden sentinel element that Screenshot.astro parses at build time
+  to discover which elements to highlight and how.
+  The custom element is stripped from the final HTML by the screenshot pipeline.
+*/}
+<screenshot-highlight
+  data-selector={selector}
+  data-style={style}
+  data-color={color}
+  data-label={label ?? ''}
+  data-border-width={String(borderWidth)}
+  aria-hidden="true"
+  style="display:none"
+></screenshot-highlight>

package/README.md

@@ -0,0 +1,141 @@
+# astro-better-declarative-screenshots
+
+Declarative, Docker-backed screenshots for Astro documentation sites.
+
+Define which pages to screenshot and which elements to highlight directly in your MDX. The package handles starting Docker, capturing pages with Playwright WebKit, compositing a macOS Safari-style window chrome, and writing PNGs. A CI workflow detects visual regressions by diffing new captures against committed references.
+
+## How it works
+
+1. You declare screenshots in MDX using `<Screenshot>` and `<Highlight>` components.
+2. Running `take-screenshots` scans your source files, boots Docker, opens each URL in Playwright WebKit, injects highlights, composites chrome, and writes PNGs to your output directory.
+3. You commit the PNG files. The `<Screenshot>` component renders them as `<img>` tags at build time.
+4. In CI, `check-screenshots` recaptures every page and diffs against the committed files. It exits non-zero if anything changed beyond the configured pixel threshold, and uploads diff images as build artifacts.
+
+## Quick start
+
+```sh
+npm install astro-better-declarative-screenshots
+npx playwright install --with-deps webkit
+```
+
+Add the integration to `astro.config.mjs`:
+
+```js
+import { defineConfig } from 'astro/config';
+import screenshots from 'astro-better-declarative-screenshots';
+
+export default defineConfig({
+  integrations: [screenshots()],
+});
+```
+
+Create `screenshot.config.mjs` at your project root (see [CONFIGURATION.md](./CONFIGURATION.md) for all options):
+
+```js
+export default {
+  baseUrl: 'http://localhost:9011',
+  outputDir: 'public/screenshots',
+  docker: {
+    compose:   'docker-compose.yml',
+    service:   'app',
+    kickstart: 'kickstart/bootstrap.json',
+    healthcheck: {
+      url:     'http://localhost:9011/api/status',
+      timeout: 60000,
+    },
+  },
+};
+```
+
+Use `<Screenshot>` in your MDX files:
+
+```mdx
+import Screenshot from 'astro-better-declarative-screenshots/Screenshot.astro';
+import Highlight from 'astro-better-declarative-screenshots/Highlight.astro';
+
+<Screenshot url="/admin/group/add">
+  <Highlight selector="#name" style="border" color="#f60" label="Group name" />
+</Screenshot>
+```
+
+Take screenshots:
+
+```sh
+npx take-screenshots
+```
+
+## Components
+
+### `<Screenshot>`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `url` | `string` | required | URL path (relative) or full URL to capture |
+| `id` | `string` | auto-derived | Explicit output filename (without extension) |
+| `alt` | `string` | derived from name | Alt text for the rendered image |
+| `width` | `number` | from config | Viewport width for this screenshot |
+| `height` | `number` | from config | Viewport height for this screenshot |
+| `fullPage` | `boolean` | `false` | Capture full scrollable page height |
+
+### `<Highlight>`
+
+Must be a direct child of `<Screenshot>`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `selector` | `string` | required | CSS selector for the element to highlight |
+| `style` | `'border' \| 'arrow' \| 'both'` | `'border'` | How to draw the highlight |
+| `color` | `string` | `'#f60'` | Highlight color (any CSS color) |
+| `label` | `string` | `''` | Text label drawn near the highlighted element |
+| `borderWidth` | `number` | `3` | Border thickness in pixels |
+
+## Filename derivation
+
+Screenshot filenames are derived from the URL path and highlight selectors:
+
+- `/admin/group/add` with no highlights -> `admin-group-add.png`
+- `/admin/group` with `#name` highlighted -> `admin-group-name.png`
+- Same URL, same selectors, second occurrence -> `admin-group-1.png`
+
+To avoid collision issues, set an explicit `id` prop when the same URL appears multiple times with the same highlights.
+
+## CLI reference
+
+### `take-screenshots`
+
+Captures all screenshots and writes them to `outputDir`.
+
+```sh
+npx take-screenshots [--filter <string>] [--strict]
+```
+
+Options:
+- `--filter <string>` -- only capture screenshots whose name or URL contains this string
+- `--strict` -- exit non-zero if any screenshot fails to capture
+
+### `check-screenshots`
+
+Captures all screenshots, diffs against committed references, and exits non-zero if anything changed.
+
+```sh
+npx check-screenshots [--filter <string>] [--diff-dir <path>] [--threshold <ratio>] [--fail-on-missing]
+```
+
+Options:
+- `--filter <string>` -- only check screenshots matching this string
+- `--diff-dir <path>` -- where to write diff images (default: `.screenshot-diffs`)
+- `--threshold <ratio>` -- fraction of pixels that may differ before failure (default: `0.001` = 0.1%)
+- `--fail-on-missing` -- exit non-zero if any reference file is missing
+
+## Environment variables
+
+- `SCREENSHOTS_STRICT=true` -- strict mode: the `<Screenshot>` component throws at build time if the PNG is missing
+- `SCREENSHOTS_DIR` -- override the output directory (useful for CI artifact staging)
+
+## CI setup
+
+See [`.github/workflows/check-screenshots.yml`](./.github/workflows/check-screenshots.yml) for an example weekly workflow that runs `check-screenshots` and uploads diff images as artifacts.
+
+## License
+
+MIT

package/Screenshot.astro

@@ -0,0 +1,131 @@
+---
+import { deriveName } from './src/naming.mjs';
+import { loadConfig } from './src/config.mjs';
+import { existsSync } from 'fs';
+import path from 'path';
+
+interface HighlightData {
+  selector: string;
+  style: string;
+  color: string;
+  label: string;
+  borderWidth: number;
+}
+
+interface Props {
+  url: string;
+  /** explicit filename (without extension) -- overrides auto-derived name */
+  id?: string;
+  /** alt text for the rendered image */
+  alt?: string;
+  /** override window width for this screenshot */
+  width?: number;
+  /** override window height for this screenshot */
+  height?: number;
+  /** capture the full scrollable page height */
+  fullPage?: boolean;
+  /** outputDir relative to project root; falls back to env SCREENSHOTS_DIR or 'src/assets/screenshots' */
+  outputDir?: string;
+}
+
+const {
+  url,
+  id,
+  alt,
+  width,
+  height,
+  fullPage = false,
+  outputDir,
+} = Astro.props;
+
+// parse Highlight children from the rendered slot HTML
+function parseHighlights(html: string): HighlightData[] {
+  const found: HighlightData[] = [];
+  // match <screenshot-highlight data-selector="..." ...></screenshot-highlight>
+  const tagRe = /<screenshot-highlight([^>]*)>/gi;
+  const attrRe = /data-([\w-]+)="([^"]*)"/g;
+  let tagMatch: RegExpExecArray | null;
+  while ((tagMatch = tagRe.exec(html)) !== null) {
+    const attrs: Record<string, string> = {};
+    let attrMatch: RegExpExecArray | null;
+    while ((attrMatch = attrRe.exec(tagMatch[1])) !== null) {
+      attrs[attrMatch[1]] = attrMatch[2];
+    }
+    if (attrs['selector']) {
+      found.push({
+        selector:    attrs['selector'] ?? '',
+        style:       attrs['style'] ?? 'border',
+        color:       attrs['color'] ?? '#f60',
+        label:       attrs['label'] ?? '',
+        borderWidth: parseInt(attrs['border-width'] ?? '3', 10),
+      });
+    }
+  }
+  return found;
+}
+
+const slotHtml = Astro.slots.has('default') ? await Astro.slots.render('default') : '';
+const highlights = parseHighlights(slotHtml);
+
+const name = id ?? deriveName(url, highlights);
+
+// resolve output directory: prop > env > screenshot.config.mjs > default
+let resolvedOutputDir = outputDir ?? process.env.SCREENSHOTS_DIR;
+if (!resolvedOutputDir) {
+  try {
+    const cfg = await loadConfig(process.cwd());
+    resolvedOutputDir = cfg.outputDir;
+  } catch {
+    resolvedOutputDir = 'src/assets/screenshots';
+  }
+}
+
+// resolve the public path the browser/img uses.
+// files in public/ are served from the root, so strip 'public/' prefix.
+// files in src/assets/ go through Astro's pipeline -- reference via root-relative path.
+const servePath = resolvedOutputDir
+  .replace(/^\.\//, '')
+  .replace(/^public\//, '');
+const imgPath = `/${servePath}/${name}.png`;
+
+// check whether the file exists on disk (uses full resolvedOutputDir, not stripped)
+const absolutePath = path.resolve(process.cwd(), resolvedOutputDir, `${name}.png`);
+const fileExists = existsSync(absolutePath);
+
+const strict = process.env.SCREENSHOTS_STRICT === 'true';
+if (!fileExists && strict) {
+  throw new Error(
+    `[astro-better-declarative-screenshots] Missing screenshot: ${name}.png\n` +
+    `Run \`take-screenshots\` to generate it, or set SCREENSHOTS_STRICT=false to use placeholders.`
+  );
+}
+
+// data attributes encode the screenshot spec for the CLI scanner
+// so `discover.mjs` can also pick these up from the built HTML if needed
+const specData = JSON.stringify({ url, highlights, width, height, fullPage });
+---
+<figure
+  class="screenshot-figure"
+  data-screenshot-name={name}
+  data-screenshot-spec={specData}
+>
+  {fileExists ? (
+    <img
+      src={imgPath}
+      alt={alt ?? name.replace(/-/g, ' ')}
+      loading="lazy"
+      decoding="async"
+      class="screenshot-img"
+    />
+  ) : (
+    <div
+      class="screenshot-placeholder"
+      role="img"
+      aria-label={alt ?? `Placeholder for ${name}`}
+      style={`width:${width ?? 1280}px;max-width:100%;aspect-ratio:${(width ?? 1280) / (height ?? 800)};background:#f0f0f0;display:flex;align-items:center;justify-content:center;font-family:sans-serif;color:#999;font-size:14px;border:1px dashed #ccc;`}
+    >
+      Screenshot not yet generated: {name}.png<br />
+      Run <code>take-screenshots</code> to generate it.
+    </div>
+  )}
+</figure>

package/example/groups.mdx

@@ -0,0 +1,33 @@
+---
+title: Groups
+description: Learn how FusionAuth groups work.
+---
+
+import Screenshot from 'astro-better-declarative-screenshots/Screenshot.astro';
+import Highlight from 'astro-better-declarative-screenshots/Highlight.astro';
+
+## Creating a group
+
+Navigate to **Groups** in the FusionAuth Admin UI to manage your groups.
+
+{/* Basic screenshot -- no highlights */}
+<Screenshot url="/admin/group/" />
+
+{/* Screenshot with a highlighted field */}
+<Screenshot url="/admin/group/add">
+  <Highlight selector="#name" style="border" color="#f60" label="Group name field" />
+</Screenshot>
+
+{/* Multiple highlights on one page */}
+<Screenshot url="/admin/group/add">
+  <Highlight selector="#name"        style="border" color="#f60" label="Name" />
+  <Highlight selector="#description" style="arrow"  color="#07c" label="Description" />
+</Screenshot>
+
+{/* Full-page capture with explicit window size */}
+<Screenshot
+  url="/admin/group/members"
+  width={1440}
+  height={900}
+  fullPage={true}
+/>