astro-better-declarative-screenshots 0.1.0 → 0.2.1

package/index.mjs

@@ -1,56 +1,3 @@
-// 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';
+export { loadConfig, ConfigSchema, DockerSchema } from './src/config.mjs';
+export { injectHighlights, scrollIntoView } from './src/highlight.mjs';

package/package.json

@@ -1,36 +1,16 @@
 {
   "name": "astro-better-declarative-screenshots",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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/src/config.mjs

@@ -82,13 +82,13 @@ const ConfigSchema = z.object({
   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(),
+  beforeAll: z.function().optional(),
 
   // called before each individual screenshot
-  beforeScreenshot: z.function().args(z.any(), z.any()).returns(z.promise(z.any())).optional(),
+  beforeScreenshot: z.function().optional(),
 
   // called once after all screenshots are taken
-  afterAll: z.function().returns(z.promise(z.any())).optional(),
+  afterAll: z.function().optional(),
 });
 
 export async function loadConfig(projectRoot) {

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

@@ -1,68 +0,0 @@
-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

@@ -1,251 +0,0 @@
-# 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/README.md

@@ -1,141 +0,0 @@
-# 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/example/groups.mdx

@@ -1,33 +0,0 @@
----
-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}
-/>

package/example/screenshot.config.mjs

@@ -1,72 +0,0 @@
-// 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());
-    });
-  },
-};