freshshot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Hanko
+
+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,137 @@
+# 📸 freshshot
+
+**Keep your README screenshots fresh.** Capture them, compare them *perceptually*, and commit only the ones that truly changed.
+
+![license](https://img.shields.io/badge/license-MIT-9f8aff)
+![node](https://img.shields.io/badge/node-%E2%89%A518-46c98b)
+![status](https://img.shields.io/badge/status-v0.1-ffb259)
+
+---
+
+## The problem
+
+README screenshots rot. You add one the day you launch; the UI moves a week later; now your README quietly lies to everyone who lands on it. A stale screenshot makes a project look abandoned.
+
+The obvious fix is to regenerate them in CI. But naive screenshot automation commits a **new image on every run** — fonts anti-alias differently, animations land on different frames, a random value nudges a pixel. Your git history fills with binary noise and the diffs become worthless. So most people just... don't.
+
+## How freshshot fixes it
+
+Two ideas, working together:
+
+**1. Determinism.** freshshot serves your site locally, optionally seeds `Math.random`, freezes animations, and waits for web fonts. The same UI renders the same way every run.
+
+**2. Perceptual diff.** A freshly captured shot replaces the committed one *only* if more than a threshold of pixels **genuinely** moved. Sub-pixel anti-aliasing and blur jitter is ignored. Real changes are not.
+
+Run it in CI on every change and it commits a screenshot **only when the UI actually changed.** No noise. The README stays honest on its own.
+
+## Quick start
+
+```bash
+npm install --save-dev freshshot
+npx playwright install chromium
+```
+
+Add a `freshshot.config.json` at your project root:
+
+```json
+{
+  "serve": "site",
+  "outDir": "screenshots",
+  "shots": [
+    { "name": "home", "steps": [ { "goto": "/index.html" } ] }
+  ]
+}
+```
+
+Run it:
+
+```bash
+npx freshshot
+```
+
+```
+freshshot: 1 shot(s) from freshshot.config.json
+  = home  unchanged (0.000%)
+
+No changes - every screenshot is already current.
+```
+
+freshshot captures each shot, compares it to the committed PNG, and rewrites only what meaningfully changed. Embed the results in your README with plain `<img>` tags and you're done.
+
+## Configuration
+
+A `freshshot.config.json` has a few top-level keys and a list of `shots`.
+
+**Top level**
+
+- `serve` — a local folder to serve and screenshot, **or**
+- `baseUrl` — an already-running URL to screenshot instead
+- `outDir` — where screenshots are written (default `screenshots`)
+- `viewport` — `{ "width", "height" }` (default `1280x800`)
+- `deviceScaleFactor` — e.g. `2` for retina-crisp images (default `1`)
+- `diffRatio` — how much must change before a rewrite (default `0.0015`, i.e. 0.15%)
+- `seedRandom` — replace `Math.random` with a fixed seed for determinism (default `false`)
+- `settleMs` — pause after fonts load, before capture (default `200`)
+- `shots` — the screenshots to take
+
+**Each shot**
+
+- `name` — output filename (`<name>.png`)
+- `steps` — actions that drive the page into the state you want
+- `screenshot` — Playwright screenshot options, e.g. `{ "animations": "disabled" }`
+
+**Steps**
+
+- `{ "goto": "/path" }`
+- `{ "click": "<selector>", "times": 1 }`
+- `{ "fill": "<selector>", "value": "text" }`
+- `{ "waitFor": "<selector>" }`
+- `{ "wait": 500 }` — milliseconds
+- `{ "eval": "<javascript>" }` — escape hatch for app-specific tweaks (force an element visible, pause an animation, and so on)
+
+Shots run **in order on one browser session**, so a shot whose steps don't start with `goto` simply continues from the previous shot's state. That makes multi-step flows — open a menu, play a turn, reach a result screen — easy to capture.
+
+See [`examples/freshshot.config.json`](examples/freshshot.config.json) for a complete, real-world config.
+
+## In CI
+
+```yaml
+name: Screenshots
+on:
+  push:
+    branches: [main]
+    paths: ['site/**']
+permissions:
+  contents: write
+jobs:
+  freshshot:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - uses: mphinance/freshshot@v1
+```
+
+The action captures, perceptual-diffs, and commits back **only** the screenshots that changed. An unchanged UI produces zero commits.
+
+## `--check` mode
+
+```bash
+npx freshshot --check
+```
+
+Captures and compares but writes nothing; exits non-zero if any screenshot is stale. Useful as a pull-request gate.
+
+## Why "perceptual"?
+
+Byte-for-byte screenshot comparison is a trap: two visually **identical** captures routinely differ at the byte level, because anti-aliasing and filter effects render with tiny variations. Compare bytes, and you commit noise forever. freshshot compares *pixels* with [pixelmatch](https://github.com/mapbox/pixelmatch) — sub-pixel jitter is filtered out, genuine changes are caught. That single decision is what makes screenshot automation actually usable.
+
+## Origin
+
+freshshot was extracted from [Third Settler](https://github.com/mphinance/third-settler), a board-game app whose README screenshots had to stay honest while the UI changed by the hour. The pattern worked well enough that it wanted to be its own tool.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/action.yml

@@ -0,0 +1,54 @@
+name: 'freshshot'
+description: 'Keep README screenshots fresh - capture, perceptual-diff, and commit only real changes.'
+branding:
+  icon: 'camera'
+  color: 'purple'
+
+inputs:
+  config:
+    description: 'Path to the freshshot config file.'
+    required: false
+    default: 'freshshot.config.json'
+  commit:
+    description: 'Commit refreshed screenshots back to the branch.'
+    required: false
+    default: 'true'
+  commit-message:
+    description: 'Commit message used when screenshots change.'
+    required: false
+    default: 'Refresh screenshots [skip ci]'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Install freshshot
+      shell: bash
+      working-directory: ${{ github.action_path }}
+      run: npm install --omit=dev --no-audit --no-fund
+
+    - name: Install Chromium
+      shell: bash
+      working-directory: ${{ github.action_path }}
+      run: npx playwright install --with-deps chromium
+
+    - name: Run freshshot
+      shell: bash
+      run: node "${{ github.action_path }}/bin/freshshot.mjs" --config "${{ inputs.config }}"
+
+    - name: Commit refreshed screenshots
+      if: ${{ inputs.commit == 'true' }}
+      shell: bash
+      run: |
+        out=$(node -e "console.log(JSON.parse(require('fs').readFileSync(process.argv[1],'utf8')).outDir||'screenshots')" "${{ inputs.config }}")
+        git add "$out"
+        if git diff --cached --quiet; then
+          echo "Screenshots are already up to date."
+          exit 0
+        fi
+        git config user.name "github-actions[bot]"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        git commit -m "${{ inputs.commit-message }}"
+        # Rebase onto anything that landed while the job ran, so the push
+        # always fast-forwards.
+        git pull --rebase origin "${GITHUB_REF_NAME}"
+        git push

package/bin/freshshot.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// freshshot - keep your README screenshots fresh.
+
+import { loadConfig } from '../src/config.mjs';
+import { capture } from '../src/capture.mjs';
+
+const HELP = `freshshot - keep your README screenshots fresh
+
+Usage:
+  freshshot [--config <path>] [--check]
+
+Options:
+  --config <path>   Config file to use (default: freshshot.config.json)
+  --check           Report stale screenshots without writing; exit 1 if any.
+  --help, -h        Show this help.
+`;
+
+function flagValue(name) {
+  const i = process.argv.indexOf(name);
+  return i > -1 ? process.argv[i + 1] : null;
+}
+
+async function main() {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  const check = process.argv.includes('--check');
+  const configPath = flagValue('--config') || 'freshshot.config.json';
+
+  const cfg = loadConfig(configPath);
+  console.log(`freshshot: ${cfg.shots.length} shot(s) from ${configPath}`);
+
+  const results = await capture(cfg, { check });
+
+  let stale = 0;
+  for (const r of results) {
+    const pct = `${(r.ratio * 100).toFixed(3)}%`;
+    if (r.status === 'new') {
+      stale++;
+      console.log(`  + ${r.name}  new`);
+    } else if (r.status === 'changed') {
+      stale++;
+      console.log(`  ~ ${r.name}  changed (${pct})`);
+    } else {
+      console.log(`  = ${r.name}  unchanged (${pct})`);
+    }
+  }
+
+  if (check) {
+    if (stale > 0) {
+      console.error(`\n${stale} screenshot(s) are out of date. Run freshshot to refresh them.`);
+      process.exit(1);
+    }
+    console.log('\nAll screenshots are current.');
+    return;
+  }
+  console.log(stale > 0
+    ? `\n${stale} screenshot(s) refreshed.`
+    : '\nNo changes - every screenshot is already current.');
+}
+
+main().catch((err) => {
+  console.error('freshshot: ' + err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "freshshot",
+  "version": "0.1.0",
+  "description": "Keep your README screenshots fresh: capture, perceptual-diff, and commit only the ones that truly changed.",
+  "type": "module",
+  "bin": {
+    "freshshot": "bin/freshshot.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "action.yml"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "freshshot": "node bin/freshshot.mjs",
+    "test": "node --test"
+  },
+  "keywords": [
+    "screenshots",
+    "readme",
+    "playwright",
+    "documentation",
+    "ci",
+    "visual-regression"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mphinance/freshshot.git"
+  },
+  "homepage": "https://github.com/mphinance/freshshot#readme",
+  "bugs": "https://github.com/mphinance/freshshot/issues",
+  "dependencies": {
+    "pixelmatch": "^7.0.0",
+    "playwright": "^1.49.0",
+    "pngjs": "^7.0.0"
+  }
+}

package/src/capture.mjs

@@ -0,0 +1,94 @@
+// The capture engine: drive each configured shot through Playwright, then
+// keep the result only if it differs meaningfully from the committed one.
+
+import { chromium } from 'playwright';
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { serve } from './server.mjs';
+import { diffRatio } from './compare.mjs';
+
+// mulberry32 - a seeded PRNG injected to replace Math.random, so anything
+// random in the page (generated content, dice, confetti) renders the same
+// way every run.
+const SEED_SCRIPT = `(function () {
+  var s = 0x9e3779b9;
+  Math.random = function () {
+    s = (s + 0x6D2B79F5) | 0;
+    var t = Math.imul(s ^ (s >>> 15), 1 | s);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+})();`;
+
+async function runStep(page, step, base) {
+  if (step.goto !== undefined) {
+    await page.goto(base + step.goto, { waitUntil: 'networkidle' });
+  } else if (step.click !== undefined) {
+    const times = step.times || 1;
+    for (let i = 0; i < times; i++) await page.click(step.click);
+  } else if (step.fill !== undefined) {
+    await page.fill(step.fill, String(step.value ?? ''));
+  } else if (step.waitFor !== undefined) {
+    await page.waitForSelector(step.waitFor, { state: step.state || 'attached' });
+  } else if (step.wait !== undefined) {
+    await page.waitForTimeout(step.wait);
+  } else if (step.eval !== undefined) {
+    await page.evaluate(step.eval);
+  } else {
+    throw new Error(`Unknown step: ${JSON.stringify(step)}`);
+  }
+}
+
+function decide(name, dest, buf, threshold, write) {
+  if (!existsSync(dest)) {
+    if (write) writeFileSync(dest, buf);
+    return { name, status: 'new', ratio: 1 };
+  }
+  const ratio = diffRatio(readFileSync(dest), buf);
+  if (ratio > threshold) {
+    if (write) writeFileSync(dest, buf);
+    return { name, status: 'changed', ratio };
+  }
+  return { name, status: 'unchanged', ratio };
+}
+
+// Runs every shot in the config. With { check: true } nothing is written;
+// the returned statuses just report what would change.
+export async function capture(cfg, { check = false } = {}) {
+  mkdirSync(cfg.outDir, { recursive: true });
+
+  let base = cfg.baseUrl;
+  let server = null;
+  if (cfg.serve) {
+    server = await serve(cfg.serve);
+    base = server.url;
+  }
+
+  const browser = await chromium.launch();
+  const page = await browser.newPage({
+    viewport: cfg.viewport,
+    deviceScaleFactor: cfg.deviceScaleFactor
+  });
+  if (cfg.seedRandom) await page.addInitScript(SEED_SCRIPT);
+
+  const results = [];
+  try {
+    for (const shot of cfg.shots) {
+      try {
+        for (const step of shot.steps) await runStep(page, step, base);
+        // Let any web fonts finish, then settle, for a stable capture.
+        await page.evaluate(() => (document.fonts ? document.fonts.ready : null));
+        await page.waitForTimeout(cfg.settleMs);
+        const buf = await page.screenshot(shot.screenshot || {});
+        const dest = join(cfg.outDir, `${shot.name}.png`);
+        results.push(decide(shot.name, dest, buf, cfg.diffRatio, !check));
+      } catch (e) {
+        throw new Error(`shot "${shot.name}" failed: ${e.message}`);
+      }
+    }
+  } finally {
+    await browser.close();
+    if (server) server.close();
+  }
+  return results;
+}

package/src/compare.mjs

@@ -0,0 +1,18 @@
+// Perceptual image comparison. Returns the fraction of pixels that
+// genuinely changed, ignoring the sub-pixel anti-aliasing and filter
+// jitter that makes byte-for-byte screenshot comparison useless.
+
+import pixelmatch from 'pixelmatch';
+import pngjs from 'pngjs';
+
+const { PNG } = pngjs;
+
+// Fraction (0..1) of pixels that meaningfully differ between two PNG buffers.
+// Differently sized images count as fully different.
+export function diffRatio(pngBufferA, pngBufferB) {
+  const a = PNG.sync.read(pngBufferA);
+  const b = PNG.sync.read(pngBufferB);
+  if (a.width !== b.width || a.height !== b.height) return 1;
+  const moved = pixelmatch(a.data, b.data, null, a.width, a.height, { threshold: 0.1 });
+  return moved / (a.width * a.height);
+}

package/src/config.mjs

@@ -0,0 +1,44 @@
+// Loads, defaults, and validates a freshshot config file.
+
+import { readFileSync, existsSync } from 'fs';
+
+const DEFAULTS = {
+  serve: null,        // a local folder to serve, OR
+  baseUrl: null,      // an existing URL to capture
+  outDir: 'screenshots',
+  viewport: { width: 1280, height: 800 },
+  deviceScaleFactor: 1,
+  diffRatio: 0.0015,  // rewrite a shot only if >0.15% of pixels moved
+  seedRandom: false,  // replace Math.random with a fixed seed
+  settleMs: 200,      // pause after fonts load, before the screenshot
+  shots: []
+};
+
+export function loadConfig(path) {
+  if (!existsSync(path)) {
+    throw new Error(`Config file not found: ${path}`);
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (e) {
+    throw new Error(`Config is not valid JSON (${path}): ${e.message}`);
+  }
+  const cfg = { ...DEFAULTS, ...raw };
+  // Deep-merge nested objects so a partial "viewport" keeps its defaults.
+  cfg.viewport = { ...DEFAULTS.viewport, ...(raw.viewport || {}) };
+
+  if (!cfg.serve && !cfg.baseUrl) {
+    throw new Error('Config must set "serve" (a local folder) or "baseUrl" (a URL).');
+  }
+  if (!Array.isArray(cfg.shots) || cfg.shots.length === 0) {
+    throw new Error('Config must define a non-empty "shots" array.');
+  }
+  cfg.shots.forEach((shot, i) => {
+    if (!shot.name) throw new Error(`shots[${i}] is missing "name".`);
+    if (!Array.isArray(shot.steps)) {
+      throw new Error(`shot "${shot.name}" is missing a "steps" array.`);
+    }
+  });
+  return cfg;
+}

package/src/server.mjs

@@ -0,0 +1,53 @@
+// A tiny static file server, so captures can run against a local folder
+// with no separate dev server and no dependency on a live deploy.
+
+import { createServer } from 'http';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join, extname, resolve, sep } from 'path';
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript',
+  '.mjs': 'text/javascript',
+  '.css': 'text/css',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.json': 'application/json',
+  '.webmanifest': 'application/manifest+json',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2'
+};
+
+// Serves `dir` on a random free port. Resolves { url, close }.
+export function serve(dir) {
+  const root = resolve(dir);
+  return new Promise((ok) => {
+    const server = createServer((req, res) => {
+      let path = decodeURIComponent(req.url.split('?')[0]);
+      if (path.endsWith('/')) path += 'index.html';
+      const file = resolve(join(root, path));
+      // Stay inside the served folder. The trailing separator stops a
+      // sibling like "site-other" from matching a root of "site".
+      if (!file.startsWith(root + sep) || !existsSync(file) || !statSync(file).isFile()) {
+        res.writeHead(404);
+        res.end('not found');
+        return;
+      }
+      res.writeHead(200, {
+        'Content-Type': MIME[extname(file).toLowerCase()] || 'application/octet-stream'
+      });
+      res.end(readFileSync(file));
+    });
+    server.listen(0, () => {
+      ok({
+        url: `http://localhost:${server.address().port}`,
+        close: () => server.close()
+      });
+    });
+  });
+}