@casomoltd/tooling 0.22.5 → 0.23.1

package/README.md

@@ -25,7 +25,7 @@ Shared linting, formatting, commit config, and CLI tools for Casomo Ltd's repos.
 | `pre-commit` | Husky pre-commit hook — runs `npm run check` |
 | `commit-msg` | Husky commit-msg hook — runs commitlint |
 | `readability` | Measure reading difficulty of page content |
-| `screenshot` | Capture a dev server page via Puppeteer |
+| `screenshot` | Capture a dev server page via Playwright — an agent's visual feedback loop |
 | `build-report` | Compile a Typst client report to PDF with the house template |
 
 ## Install
@@ -43,9 +43,31 @@ npm i -D @casomoltd/tooling
 
 The package is public, so installs need no token or `.npmrc`. The `files`
 allowlist plus the `verify-pack` leak-gate keep the published surface to
-configs/CLI only. `puppeteer` (used by the `screenshot` bin) is an
-**optional peer dependency** — add it yourself (`npm i -D puppeteer`) in
-repos that run `screenshot`.
+configs/CLI only.
+
+**Installing this package never installs a browser.** The `screenshot`
+bin needs one and `build-report` needs the `typst` CLI, but neither is
+declared here — see [External prerequisites](#external-prerequisites).
+
+## External prerequisites
+
+Two bins need something npm cannot sensibly deliver: `screenshot` needs
+a Chromium build, `build-report` needs the `typst` CLI and the IBM Plex
+fonts. **Neither is declared — not as a dependency, and not as an
+optional peer.** Both load their prerequisite lazily and fail with an
+install instruction when it is missing, so a consumer that never runs
+those bins carries nothing for them.
+
+The rule, for anything added later: a heavyweight prerequisite only some
+consumers need is documented here, never declared. An optional peer
+looks free because npm installs nothing for it, but it resolves into a
+consumer's lockfile as soon as anything pulls it in, and npm will not
+prune a satisfied optional peer afterwards — not on `npm install`, not
+on `npm install --package-lock-only`, not on `npm uninstall`. That is
+how one dev-only browser put the `extract-zip` advisory
+(GHSA-jmr9-qjv8-65gv) into four repos that never took a screenshot, and
+why clearing it needed a release of this package rather than a fix in
+each of them.
 
 ## Husky hooks
 
@@ -104,7 +126,20 @@ version that ships the config.
 
 ## Screenshot tool
 
-Capture the running dev server for visual inspection:
+A visual feedback loop for coding agents. Claude captures the page it
+just changed, reads the PNG back and checks its own work, instead of
+waiting for someone to look and paste a screen grab. That is what the
+bin is for, and why its output lands under `.claude/`; a person wanting
+a screenshot already has a browser open.
+
+It needs a Chromium build, which this package does not install (see
+[External prerequisites](#external-prerequisites)):
+
+```bash
+npm i -D playwright && npx playwright install chromium
+```
+
+Then capture the running dev server:
 
 ```bash
 npm run ss              # 1280×800 desktop capture
@@ -175,10 +210,9 @@ after is the body. From a consumer repo the import goes through
 `report/example.typ` is a lorem-ipsum reference report exercising every
 feature the template styles — compile it to see the house style.
 
-Two prerequisites are external to npm (like puppeteer for
-`screenshot`, they are deliberately not dependencies): the **`typst`
-CLI** on PATH (`snap install typst` / `cargo install typst-cli`) and
-the **IBM Plex Sans / IBM Plex Mono** fonts
+Two [external prerequisites](#external-prerequisites) apply here: the
+**`typst` CLI** on PATH (`snap install typst` / `cargo install
+typst-cli`) and the **IBM Plex Sans / IBM Plex Mono** fonts
 ([github.com/IBM/plex](https://github.com/IBM/plex)) — `build-report`
 fails loud on the former and warns on the latter.
 

package/bin/build-report.mjs

@@ -83,11 +83,11 @@ function findRoot(from) {
 }
 const root = values.root ? path.resolve(values.root) : findRoot(input);
 
-// typst is an external native binary (like puppeteer for screenshot, it is
-// deliberately not an npm dependency). One probe does double duty: ENOENT
-// means typst is missing; otherwise the output feeds the font check. Missing
-// fonts don't fail a Typst compile — it silently falls back and the PDF comes
-// out off-brand — so warn loud up front.
+// typst is an external native binary (like playwright's browsers for
+// screenshot, it is deliberately not an npm dependency). One probe does
+// double duty: ENOENT means typst is missing; otherwise the output feeds
+// the font check. Missing fonts don't fail a Typst compile — it silently
+// falls back and the PDF comes out off-brand — so warn loud up front.
 const fonts = spawnSync("typst", ["fonts"], {encoding: "utf8"});
 if (fonts.error) {
   fail(

package/bin/screenshot.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * Capture a screenshot of the running dev server.
+ * Capture a screenshot of a running dev server.
  *
  * Usage:
  *   npm run ss [page] [--width <n>] [--height <n>]
@@ -25,37 +25,38 @@
  *
  * Environment:
  *   SCREENSHOT_URL  Base URL to capture (default: http://localhost:3000)
+ *   SCREENSHOT_DIR  Output directory (default: <cwd>/.claude/screenshots)
  *
  * Output:
- *   .claude/screenshots/{page}-{timestamp}.png  Timestamped capture
- *   .claude/screenshots/latest.png              Always the most recent capture
+ *   {dir}/{page}-{timestamp}.png  Timestamped capture
+ *   {dir}/latest.png              Always the most recent capture
  */
 
 import { parseArgs } from "node:util";
 import path from "path";
 import fs from "fs";
 
-// puppeteer is an optional peer dependency (it pulls Chromium, ~200MB), so
-// consumers that never screenshot don't install it. Load it lazily and fail
-// loud if the screenshot bin is invoked without it.
-async function loadPuppeteer() {
+// playwright is an external prerequisite, not a dependency of this package.
+// A declared optional peer resolves into every consumer's lockfile and npm
+// will not prune it again, so a browser nobody screenshots with becomes a
+// standing advisory. Load it lazily and fail loud when it is absent.
+async function loadChromium() {
   try {
-    return (await import("puppeteer")).default;
+    return (await import("playwright")).chromium;
   } catch {
     throw new Error(
-      "puppeteer is not installed — add it as a devDependency " +
-        "(npm i -D puppeteer) to use the screenshot bin.",
+      "playwright is not installed — add it as a devDependency " +
+        "(npm i -D playwright && npx playwright install chromium) " +
+        "to use the screenshot bin.",
     );
   }
 }
 
 const BASE_URL =
   process.env.SCREENSHOT_URL || "http://localhost:3000";
-const OUTPUT_DIR = path.join(
-  process.cwd(),
-  ".claude",
-  "screenshots",
-);
+const OUTPUT_DIR =
+  process.env.SCREENSHOT_DIR ||
+  path.join(process.cwd(), ".claude", "screenshots");
 
 const PRESETS = {
   mobile: { width: 390, height: 844 },
@@ -111,15 +112,16 @@ async function screenshot() {
 
   fs.mkdirSync(OUTPUT_DIR, { recursive: true });
 
-  const puppeteer = await loadPuppeteer();
-  const browser = await puppeteer.launch({
+  const chromium = await loadChromium();
+  const browser = await chromium.launch({
     headless: true,
     args: ["--no-sandbox", "--disable-setuid-sandbox"],
   });
 
   try {
-    const page = await browser.newPage();
-    await page.setViewport({ width, height });
+    const page = await browser.newPage({
+      viewport: { width, height },
+    });
 
     const url =
       pageName === "base"
@@ -128,7 +130,7 @@ async function screenshot() {
     console.log(`Navigating to ${url}...`);
 
     await page.goto(url, {
-      waitUntil: "networkidle0",
+      waitUntil: "networkidle",
       timeout: 30000,
     });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casomoltd/tooling",
-  "version": "0.22.5",
+  "version": "0.23.1",
   "description": "Casomo's shared dev config: ESLint, Prettier, commitlint, knip & jscpd presets and dev CLIs (git hooks, readability, screenshots)",
   "license": "MIT",
   "repository": {
@@ -55,13 +55,7 @@
     "eslint-config-next": ">=16",
     "eslint-plugin-sonarjs": ">=3",
     "jscpd": ">=4",
-    "knip": ">=5",
-    "puppeteer": ">=24"
-  },
-  "peerDependenciesMeta": {
-    "puppeteer": {
-      "optional": true
-    }
+    "knip": ">=5"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",