@afixt/screenshot-utils 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.9.0] - 2026-05-22
+
+First published release. Phases 0–4 of `PLAN.md` are complete: the full
+public API surface from `spec.md` § 8 is implemented and tested (221
+tests). Released as `0.9.0` rather than `1.0.0` because the v1.0.0
+acceptance bar in `spec.md` § 23 is not yet fully met — OpenSeadragon
+end-to-end integration, 80% coverage thresholds, the performance suite
+running green in CI, and live Playwright/CDP integration tests remain.
+The API is expected to stay stable through to `1.0.0`.
+
+### Added
+
+- Phase 0 bootstrap: package.json, ESLint flat config, Prettier, Husky hooks (pre-commit / commit-msg / pre-push / post-merge), commitlint, jscpd, JSDoc setup, GitHub Actions workflows (`ci`, `pr-check`, `security`, `docs`).
+- Build pipeline producing dual CJS / ESM bundles via `tsup`, with `.d.ts` emitted from JSDoc via `tsc`.
+- Phase 1 M1.1 — full error hierarchy per spec § 14.1 (25 classes: `ScreenshotUtilsError` + `CaptureError` tree + `TransformError` tree + `ComposeError` tree + `TileError` tree + `RedactionError` tree + `AdapterError` tree + `OptionalDependencyMissingError`). Every class carries a stable `code`, optional `reason`, optional `cause`, optional `context`, and a `retriable` boolean per spec § 14.2 — § 14.4.
+- Phase 1 M1.1 — comprehensive TypeScript type definitions in `src/types/index.d.ts` covering geometry, capture / transform / compose / tile / redact options and results, the `PageAdapter` contract, and the error shape (spec §§ 8, 9, 10, 14).
+- Expanded `defaults` to match spec § 11.1 exactly (`format`, `quality`, `fullPage`, `timeout`, `padding`, `stripHeight`, `tileSize`, `tileOverlap`, `tileFormat`, `tileQuality`, `waitForStable`).
+- Public surface re-exports every error class alongside `defaults` and `version`.
+
+- Phase 1 M1.2 — `fromPuppeteerPage(page, options?)` adapter wrapping a Puppeteer `Page` into the package's `PageAdapter` interface. Validates the page object up-front (throws `AdapterContractError` listing missing methods), wraps every browser call so failures surface as `BrowserApiError` with operation context, and reports Chromium-default capabilities (16384 max screenshot height, viewport-emulation + CDP support). No top-level `require('puppeteer')` — the consumer owns the install.
+- Phase 1 M1.2 — reusable adapter contract suite at `test/adapters/contract.js`. Any adapter (mock, Puppeteer, future Playwright + CDP) must pass the same assertions: required-method coverage, capability shape, screenshot returns Buffer, getMetrics returns PageMetrics with ISO-8601 capturedAt, scroll/setViewport/evaluate resolve cleanly.
+- Phase 1 M1.2 — test-only mock adapter at `test/_helpers/mock-adapter.js` (not exported from the package) for unit-testing capture functions without launching a browser.
+- Phase 1 M1.2 — Puppeteer integration test that launches headless Chromium, navigates to `test/fixtures/simple.html`, runs the contract suite, and verifies PNG magic bytes on a real screenshot.
+- Phase 1 M1.3 — `capturePage(adapter, options?)` implementing spec § 8.1.1. Returns a `CaptureResult` with `format`, `bytes` (Buffer or Readable stream), `page` metrics, `timing` (`settleMs`/`captureMs`/`encodeMs`/`totalMs`), and `warnings`. `sharp` is lazy-loaded only on the re-encode path (webp output). Emits `capture:start` and `capture:complete` events on the optional `events` sink. `timeout` enforced via a `CaptureTimeoutError`-throwing race. `UnsupportedFormatError` thrown for non-`png|jpeg|webp` formats.
+- Phase 1 M1.4 — `waitForStable(adapter, options?)` implementing spec § 8.1.6. Awaits `document.fonts.ready`, image `load`/`error` events, CSS animations (per `animations: 'reduce' | 'wait' | 'ignore'`), and `requestIdleCallback` + idle ms settle. Runs entirely in the page context via a single `adapter.evaluate()` call to avoid Node↔browser round-trips. Returns `StabilityReport { fonts, images, animations, totalMs }`. Integrated into `capturePage`: when the `waitForStable` option is set, the timing.settleMs reflects the wait and any timeouts surface as `warnings` on the result.
+
+### Changed
+
+- Coverage provider switched from `istanbul` to `v8` so cross-file `instanceof` checks track correctly through the CJS+ESM bridge in Vitest.
+- ESLint test override now declares Vitest globals (describe, it, expect, beforeAll, afterAll, etc.) so `.js` test helpers can rely on them without importing from `vitest` (Vitest is ESM-only and cannot be required from CJS test helpers).

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) AFixt. All rights reserved.
+
+This software and its source code are proprietary and confidential. No license,
+express or implied, is granted to any third party. Possession of this source
+does not convey any right to use, copy, modify, merge, publish, distribute,
+sublicense, or sell copies of this software, in whole or in part, except as
+authorized in writing by AFixt.
+
+Internal AFixt / Revenant platform users may use this package within the
+platform's scope under the terms of their employment, contractor, or
+licensing agreement with AFixt.
+
+For licensing inquiries, contact: karl.groves@afixt.com

package/README.md

@@ -0,0 +1,132 @@
+# @afixt/screenshot-utils
+
+> Screenshot capture, transform, compose, tile, and redact utilities for the AFixt/Revenant accessibility platform.
+
+Status: **0.9.0** — Phases 0–4 of [`PLAN.md`](./PLAN.md) are complete; the full public API from [`spec.md`](./spec.md) § 8 is implemented and tested. Pre-1.0 while the v1.0.0 acceptance bar in `spec.md` § 23 is finished (OpenSeadragon e2e, 80% coverage, perf suite in CI). The API is expected to stay stable through to 1.0.0.
+
+This package owns **all** screenshot operations for the AFixt/Revenant platform: full-page, viewport, element, long-page strip-stitch, multi-viewport capture; crop / resize / convert / normalize transforms; annotate / heatmap / diff / composite; DZI tile pyramids; and PII redaction. It is being extracted from `@afixt/afixt-engine`; the engine will become a consumer.
+
+---
+
+## Quickstart
+
+```bash
+npm install @afixt/screenshot-utils
+# optional peers — install only what you use
+npm install puppeteer pixelmatch pngjs
+```
+
+```js
+const { capturePage, crop, fromPuppeteerPage } = require('@afixt/screenshot-utils');
+
+const adapter = fromPuppeteerPage(page);
+const { bytes, page: metrics, timing } = await capturePage(adapter, { fullPage: true });
+const thumbnail = await crop(bytes, { x: 0, y: 0, width: 400, height: 300 });
+```
+
+Adapter factories, capture functions, transforms, compose, tile, and redact
+are all exported from the package root. See `spec.md` § 8 for the full API
+and `docs/consumer-cookbook.md` for end-to-end recipes.
+
+## Why this exists
+
+Screenshot work was scattered across `afixt-engine`, `mortise`, and ad-hoc consumer scripts. Pulling it into one package gives us:
+
+- One canonical implementation of long-page stitching, element capture, and DZI tiling.
+- A browser-agnostic surface via the `PageAdapter` interface — `puppeteer`, `playwright`, and CDP all work.
+- A stable error contract with named classes, stable `code`s, and `retriable` hints.
+- Predictable, conservative defaults (PNG, lossless, full-page) that consumers can opt out of.
+- No upward dependency on the engine — every other team can adopt it without a circular import.
+
+## Install
+
+| Dependency          | Status                                         | Why you'd want it                      |
+| ------------------- | ---------------------------------------------- | -------------------------------------- |
+| `sharp`             | Required runtime dep — installed automatically | All raster operations                  |
+| `puppeteer` >=23    | Optional peer                                  | `fromPuppeteerPage` adapter            |
+| `playwright` >=1.40 | Optional peer                                  | `fromPlaywrightPage` adapter (Phase 2) |
+| `pixelmatch`        | Optional peer                                  | `diff()` function (Phase 4)            |
+| `pngjs`             | Optional peer                                  | `pixelmatch` co-dependency             |
+| `@napi-rs/canvas`   | Deferred to v1.1                               | Advanced annotation strokes            |
+
+Node `>=22.22.1` is required (`engine-strict=true`).
+
+## PageAdapter
+
+The capture functions never import a browser. Consumers wrap their `Page`-like object:
+
+```js
+const { fromPuppeteerPage } = require('@afixt/screenshot-utils/adapters/puppeteer');
+const adapter = fromPuppeteerPage(page);
+```
+
+Anything that satisfies the `PageAdapter` interface works — write your own for CDP-only runtimes. See `docs/adapters.md` (Phase 4) for the contract.
+
+## Capture functions
+
+- `capturePage(adapter, opts)` — full page or viewport
+- `captureViewport(adapter, opts)` — just what's currently scrolled into view
+- `captureElement(adapter, selector | rect, opts)` — single element (deprecated path; prefer `cropMany`)
+- `captureLongPage(adapter, opts)` — strip-and-stitch for very tall pages
+- `captureResponsive(adapter, viewports, opts)` — capture once per viewport
+- `waitForStable(adapter, opts)` — fonts ready, images complete, animation policy honored
+
+## Transform & compose
+
+- `crop(buffer, rect, opts)` / `cropMany(buffer, rectsByKey, opts)` — extract one or many sub-images
+- `convert(buffer, format, opts)` — re-encode
+- `resize(buffer, opts)` — fit, contain, cover
+- `normalize(buffer, opts)` — strip metadata, fix orientation
+- `annotate(buffer, annotations, opts)` — boxes, labels, severities (Phase 4)
+- `heatmap(buffer, points, opts)` — kernel-density overlay (Phase 4)
+- `diff(a, b, opts)` — pixelmatch-backed visual diff (Phase 4)
+
+## Tiling
+
+- `tileDzi(buffer, outDir | 'buffers', opts)` — produce a Deep Zoom Image pyramid (Phase 2)
+
+## Redaction
+
+- `redact(buffer, regions, mode, opts)` — blur, mask, or pixelate PII regions (Phase 4)
+- `applyPiiPolicy(buffer, policy)` — apply a policy bundle for repeatable redaction
+
+## CLI (Phase 4)
+
+```bash
+npx @afixt/screenshot-utils crop input.png --rect 0,0,400,300 --out thumb.png
+npx @afixt/screenshot-utils tile input.png --out ./tiles
+npx @afixt/screenshot-utils diff before.png after.png --out diff.png
+```
+
+## Performance tips
+
+- Pass `encoding: 'stream'` for memory-sensitive pipelines.
+- Use `cropMany` rather than calling `crop` in a loop — internally bounded parallelism is faster and uses less memory.
+- For long pages, prefer `captureLongPage` over a giant viewport — sharp handles strips better than 30 000-px-tall buffers.
+- See `docs/performance.md` (Phase 4) for ceilings.
+
+## Errors
+
+Every failure is a named class with a stable `code`, a structured `reason` enum, and a `retriable: boolean` hint. Hierarchy in `spec.md` § 14.1. Catalog in `docs/error-codes.md` (Phase 4).
+
+## Versioning & non-goals
+
+The `src/index.js` tagged exports are the **only** semver-protected API. Deep imports are unstable. v1.0.0 ships AVIF, `@napi-rs/canvas` annotations, and streaming DZI as v1.1 follow-ups.
+
+This package is intentionally **not** responsible for:
+
+- Storage, network transport, auth, retention, or encryption
+- Accessibility-test logic (skip rules, severity assignment, etc.)
+- Browser launching or pooling
+- Mutable global state
+
+See `spec.md` § 4.2 for the full non-goals list.
+
+## Contributing
+
+This is an internal AFixt package — issue tracker and PRs at [github.com/AFixt/screenshot-utils](https://github.com/AFixt/screenshot-utils).
+
+- Branching: Git Flow. PRs target `develop`.
+- Tests-first (TDD). 2–3 tests per batch; never commit failing tests.
+- Conventional Commits enforced by `commitlint`.
+- See `CLAUDE.md` for the rules every change must satisfy.

package/bin/afixt-screenshot

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+'use strict';
+
+const { main } = require('../src/cli/index.js');
+
+main(process.argv.slice(2)).then(
+    code => {
+        process.exit(code);
+    },
+    error => {
+        process.stderr.write(`Fatal: ${error?.stack ?? error}\n`);
+        process.exit(1);
+    }
+);