oh-my-opencode 4.10.0 → 4.11.0

package/dist/skills/visual-qa/references/agent-browser-setup.md

@@ -0,0 +1,44 @@
+# agent-browser setup (Web capture fallback)
+
+Use this when the project has **no** browser tooling configured or available for the Web
+capture path in Step 2 (no playwright / dev-browser skill, no usable headless browser).
+[agent-browser](https://github.com/vercel-labs/agent-browser) is a standalone CLI that
+drives a real Chromium and can screenshot a page at a fixed viewport — exactly what the
+`image-diff` evidence step needs.
+
+Repo: https://github.com/vercel-labs/agent-browser
+
+## Install
+
+```
+bun add -g agent-browser && agent-browser install
+```
+
+`bun add -g agent-browser` installs the CLI globally; `agent-browser install` downloads the
+managed browser it drives. (Equivalent with npm: `npm install -g agent-browser && agent-browser install`.)
+
+Confirm it is ready and discover the current flags:
+
+```
+agent-browser --help
+```
+
+## Capture a screenshot at a fixed viewport
+
+Set the viewport first, then screenshot — this guarantees the ACTUAL capture matches the
+REFERENCE viewport so `image-diff` compares like-for-like:
+
+```
+agent-browser set viewport 1280 720      # width height (add a third arg, e.g. 2, for retina scale)
+agent-browser screenshot actual.png      # add --full for full-page, --screenshot-dir ./shots for a custom dir
+```
+
+Then feed the PNG into the diff exactly as in Step 2:
+
+```
+bun "$SKILL_DIR/scripts/cli.ts" image-diff <reference.png> actual.png
+```
+
+Match the viewport numbers to whatever the reference/mock was captured at; mismatched
+dimensions make `dimensionsMatch` false and inflate `diffRatio`. Run `agent-browser --help`
+for the full command set (navigation, batch, annotate, format/quality flags).

package/dist/skills/visual-qa/scripts/ansi.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test"
+
+import { hasAnsi, stripAnsi } from "./ansi"
+
+const ESC = String.fromCharCode(0x1b)
+
+describe("stripAnsi", () => {
+	test("#given an ANSI-wrapped string #when stripped #then escape codes are removed", () => {
+		// given
+		const input = `${ESC}[31mred${ESC}[0m`
+		// when
+		const stripped = stripAnsi(input)
+		// then
+		expect(stripped).toBe("red")
+	})
+
+	test("#given a plain string #when stripped #then it is unchanged", () => {
+		// given
+		const input = "plain text"
+		// when
+		const stripped = stripAnsi(input)
+		// then
+		expect(stripped).toBe("plain text")
+	})
+})
+
+describe("hasAnsi", () => {
+	test("#given a string with ANSI codes #when checked #then it is true", () => {
+		// given
+		const input = `${ESC}[1mbold${ESC}[0m`
+		// when
+		const detected = hasAnsi(input)
+		// then
+		expect(detected).toBe(true)
+	})
+
+	test("#given a plain string #when checked #then it is false", () => {
+		// given
+		const input = "no ansi here"
+		// when
+		const detected = hasAnsi(input)
+		// then
+		expect(detected).toBe(false)
+	})
+})

package/dist/skills/visual-qa/scripts/ansi.ts

@@ -0,0 +1,17 @@
+const ESC = String.fromCharCode(0x1b)
+const CSI = String.fromCharCode(0x9b)
+
+// Matches CSI/escape sequences (colors, cursor moves) without embedding raw
+// control characters in the regex source.
+const ANSI_PATTERN = new RegExp(
+	`[${ESC}${CSI}][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]`,
+	"g",
+)
+
+export function stripAnsi(input: string): string {
+	return input.replace(ANSI_PATTERN, "")
+}
+
+export function hasAnsi(input: string): boolean {
+	return stripAnsi(input) !== input
+}

package/dist/skills/visual-qa/scripts/cli.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test"
+import { mkdtempSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { run, runImageDiff, runTuiCheck } from "./cli"
+import { encodeRgbaPng, solidRgba } from "./png-synth"
+
+function tempDir(): string {
+	return mkdtempSync(join(tmpdir(), "visual-qa-"))
+}
+
+describe("runImageDiff", () => {
+	test("#given two identical PNG files #when diffed #then similarity is 100", () => {
+		// given
+		const dir = tempDir()
+		const reference = join(dir, "reference.png")
+		const actual = join(dir, "actual.png")
+		writeFileSync(reference, encodeRgbaPng(2, 2, solidRgba(2, 2, [1, 2, 3, 255])))
+		writeFileSync(actual, encodeRgbaPng(2, 2, solidRgba(2, 2, [1, 2, 3, 255])))
+		// when
+		const result = runImageDiff([reference, actual])
+		// then
+		expect(result.command).toBe("image-diff")
+		expect(result.similarityScore).toBe(100)
+		expect(result.dimensionsMatch).toBe(true)
+	})
+
+	test("#given missing arguments #when diffed #then it throws a usage error", () => {
+		// given / when / then
+		expect(() => runImageDiff([])).toThrow("usage")
+	})
+})
+
+describe("runTuiCheck", () => {
+	test("#given a CJK capture file #when checked #then widths count wide characters", () => {
+		// given
+		const dir = tempDir()
+		const file = join(dir, "capture.txt")
+		writeFileSync(file, "가나\nhello")
+		// when
+		const result = runTuiCheck([file, "--cols", "40"])
+		// then
+		expect(result.command).toBe("tui-check")
+		expect(result.expectedColumns).toBe(40)
+		expect(result.lineWidths).toEqual([4, 5])
+	})
+})
+
+describe("run dispatch", () => {
+	test("#given an unknown command #when run #then it throws", () => {
+		// given / when / then
+		expect(() => run(["bogus"])).toThrow("unknown command")
+	})
+})
+
+describe("cli entry", () => {
+	test("#given the cli is spawned for image-diff #when it runs #then it prints JSON and exits zero", () => {
+		// given
+		const dir = tempDir()
+		const reference = join(dir, "reference.png")
+		const actual = join(dir, "actual.png")
+		writeFileSync(reference, encodeRgbaPng(2, 2, solidRgba(2, 2, [0, 0, 0, 255])))
+		writeFileSync(actual, encodeRgbaPng(2, 2, solidRgba(2, 2, [255, 255, 255, 255])))
+		// when
+		const proc = Bun.spawnSync(["bun", join(import.meta.dir, "cli.ts"), "image-diff", reference, actual])
+		// then
+		expect(proc.exitCode).toBe(0)
+		const parsed: Record<string, unknown> = JSON.parse(proc.stdout.toString())
+		expect(parsed["command"]).toBe("image-diff")
+		expect(parsed["similarityScore"]).toBe(0)
+	})
+})

package/dist/skills/visual-qa/scripts/cli.ts

@@ -0,0 +1,82 @@
+import { readFileSync } from "node:fs"
+
+import { diffImages } from "./image-diff"
+import { decodePng } from "./png-decode"
+import { checkTui } from "./tui-grid"
+import type { ImageDiffResult, TuiCheckResult } from "./types"
+
+export class CliError extends Error {
+	readonly name = "CliError"
+}
+
+const DEFAULT_COLUMNS = 80
+const COLS_FLAG = "--cols"
+
+export function runImageDiff(args: readonly string[]): ImageDiffResult {
+	const referencePath = args[0]
+	const actualPath = args[1]
+	if (referencePath === undefined || actualPath === undefined) {
+		throw new CliError("usage: image-diff <reference.png> <actual.png>")
+	}
+	const reference = decodePng(readFileSync(referencePath))
+	const actual = decodePng(readFileSync(actualPath))
+	return diffImages(reference, actual)
+}
+
+function parseColumns(args: readonly string[]): number {
+	for (let index = 0; index < args.length; index++) {
+		const arg = args[index] ?? ""
+		if (arg === COLS_FLAG) {
+			const parsed = Number(args[index + 1])
+			if (!Number.isInteger(parsed) || parsed <= 0) {
+				throw new CliError(`${COLS_FLAG} requires a positive integer`)
+			}
+			return parsed
+		}
+		if (arg.startsWith(`${COLS_FLAG}=`)) {
+			const parsed = Number(arg.slice(COLS_FLAG.length + 1))
+			if (!Number.isInteger(parsed) || parsed <= 0) {
+				throw new CliError(`${COLS_FLAG} requires a positive integer`)
+			}
+			return parsed
+		}
+	}
+	return DEFAULT_COLUMNS
+}
+
+export function runTuiCheck(args: readonly string[]): TuiCheckResult {
+	const capturePath = args[0]
+	if (capturePath === undefined || capturePath.startsWith("--")) {
+		throw new CliError("usage: tui-check <capture.txt> [--cols N]")
+	}
+	const text = readFileSync(capturePath, "utf8")
+	return checkTui(text, parseColumns(args.slice(1)))
+}
+
+export function run(argv: readonly string[]): ImageDiffResult | TuiCheckResult {
+	const command = argv[0]
+	const rest = argv.slice(1)
+	switch (command) {
+		case "image-diff":
+			return runImageDiff(rest)
+		case "tui-check":
+			return runTuiCheck(rest)
+		default:
+			throw new CliError(`unknown command "${command ?? ""}"; expected "image-diff" or "tui-check"`)
+	}
+}
+
+function main(argv: readonly string[]): void {
+	try {
+		const result = run(argv)
+		process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error)
+		process.stderr.write(`visual-qa error: ${message}\n`)
+		process.exitCode = 1
+	}
+}
+
+if (import.meta.main) {
+	main(process.argv.slice(2))
+}

package/dist/skills/visual-qa/scripts/east-asian-width.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test"
+
+import { charWidth, stringWidth } from "./east-asian-width"
+
+describe("charWidth", () => {
+	test("#given an ASCII letter #when measured #then it is one column", () => {
+		// given / when / then
+		expect(charWidth(0x61)).toBe(1)
+	})
+
+	test("#given a Hangul syllable #when measured #then it is two columns", () => {
+		expect(charWidth(0xac00)).toBe(2)
+	})
+
+	test("#given a CJK ideograph #when measured #then it is two columns", () => {
+		expect(charWidth(0x4e00)).toBe(2)
+	})
+
+	test("#given a fullwidth Latin letter #when measured #then it is two columns", () => {
+		expect(charWidth(0xff21)).toBe(2)
+	})
+
+	test("#given a halfwidth katakana #when measured #then it is one column", () => {
+		expect(charWidth(0xff71)).toBe(1)
+	})
+
+	test("#given a combining diacritic #when measured #then it is zero columns", () => {
+		expect(charWidth(0x0301)).toBe(0)
+	})
+
+	test("#given a zero-width space #when measured #then it is zero columns", () => {
+		expect(charWidth(0x200b)).toBe(0)
+	})
+
+	test("#given an emoji #when measured #then it is two columns", () => {
+		expect(charWidth(0x1f600)).toBe(2)
+	})
+})
+
+describe("stringWidth", () => {
+	test("#given an ASCII string #when measured #then width equals character count", () => {
+		expect(stringWidth("hello")).toBe(5)
+	})
+
+	test("#given Hangul text #when measured #then each syllable counts as two", () => {
+		expect(stringWidth("가나다")).toBe(6)
+	})
+
+	test("#given CJK text #when measured #then each ideograph counts as two", () => {
+		expect(stringWidth("日本語")).toBe(6)
+	})
+
+	test("#given a base letter plus a combining mark #when measured #then it is one column", () => {
+		expect(stringWidth("e\u0301")).toBe(1)
+	})
+
+	test("#given mixed ASCII and CJK #when measured #then widths add up", () => {
+		expect(stringWidth("AB가")).toBe(4)
+	})
+})

package/dist/skills/visual-qa/scripts/east-asian-width.ts

@@ -0,0 +1,72 @@
+interface CodePointRange {
+	readonly start: number
+	readonly end: number
+}
+
+// Combining marks and zero-width code points advance the cursor by 0 columns.
+const ZERO_WIDTH_RANGES: readonly CodePointRange[] = [
+	{ start: 0x0300, end: 0x036f }, // combining diacritical marks
+	{ start: 0x0483, end: 0x0489 }, // combining Cyrillic
+	{ start: 0x0591, end: 0x05bd }, // Hebrew points
+	{ start: 0x0610, end: 0x061a }, // Arabic marks
+	{ start: 0x064b, end: 0x065f }, // Arabic marks
+	{ start: 0x0670, end: 0x0670 }, // Arabic superscript alef
+	{ start: 0x06d6, end: 0x06dc }, // Arabic small high marks
+	{ start: 0x1160, end: 0x11ff }, // Hangul Jamo medial/final (combining)
+	{ start: 0x200b, end: 0x200f }, // zero-width space / directional marks
+	{ start: 0x202a, end: 0x202e }, // bidi embeddings
+	{ start: 0x2060, end: 0x2064 }, // word joiner / invisible operators
+	{ start: 0x20d0, end: 0x20ff }, // combining marks for symbols
+	{ start: 0xfe20, end: 0xfe2f }, // combining half marks
+	{ start: 0xfeff, end: 0xfeff }, // zero-width no-break space (BOM)
+]
+
+// East Asian Wide + Fullwidth code points advance the cursor by 2 columns.
+const WIDE_RANGES: readonly CodePointRange[] = [
+	{ start: 0x1100, end: 0x115f }, // Hangul Jamo (leading consonants)
+	{ start: 0x231a, end: 0x231b }, // watch / hourglass
+	{ start: 0x2e80, end: 0x303e }, // CJK radicals, Kangxi, CJK symbols
+	{ start: 0x3041, end: 0x33ff }, // Kana, Bopomofo, CJK compatibility
+	{ start: 0x3400, end: 0x4dbf }, // CJK Unified Ext A
+	{ start: 0x4e00, end: 0x9fff }, // CJK Unified Ideographs
+	{ start: 0xa000, end: 0xa4cf }, // Yi syllables
+	{ start: 0xa960, end: 0xa97f }, // Hangul Jamo Ext-A
+	{ start: 0xac00, end: 0xd7a3 }, // Hangul syllables
+	{ start: 0xf900, end: 0xfaff }, // CJK compatibility ideographs
+	{ start: 0xfe10, end: 0xfe19 }, // vertical forms
+	{ start: 0xfe30, end: 0xfe6f }, // CJK compatibility / small forms
+	{ start: 0xff00, end: 0xff60 }, // fullwidth forms (halfwidth starts at 0xff61)
+	{ start: 0xffe0, end: 0xffe6 }, // fullwidth signs
+	{ start: 0x1b000, end: 0x1b16f }, // Kana supplement / extended
+	{ start: 0x1f200, end: 0x1f2ff }, // enclosed ideographic supplement
+	{ start: 0x1f300, end: 0x1faff }, // emoji and pictographs
+	{ start: 0x20000, end: 0x3fffd }, // CJK Unified Ext B and beyond
+]
+
+function inRanges(codePoint: number, ranges: readonly CodePointRange[]): boolean {
+	for (const range of ranges) {
+		if (codePoint >= range.start && codePoint <= range.end) {
+			return true
+		}
+	}
+	return false
+}
+
+export function charWidth(codePoint: number): 0 | 1 | 2 {
+	if (codePoint === 0) return 0
+	if (codePoint < 0x20) return 0 // C0 control
+	if (codePoint >= 0x7f && codePoint <= 0x9f) return 0 // DEL and C1 control
+	if (inRanges(codePoint, ZERO_WIDTH_RANGES)) return 0
+	if (inRanges(codePoint, WIDE_RANGES)) return 2
+	return 1
+}
+
+export function stringWidth(text: string): number {
+	let total = 0
+	for (const char of text) {
+		const codePoint = char.codePointAt(0)
+		if (codePoint === undefined) continue
+		total += charWidth(codePoint)
+	}
+	return total
+}

package/dist/skills/visual-qa/scripts/image-diff.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test"
+
+import { diffImages } from "./image-diff"
+import { solidRgba } from "./png-synth"
+import type { DecodedImage } from "./types"
+
+function makeImage(width: number, height: number, rgba: Uint8Array, transparent = false): DecodedImage {
+	return { width, height, rgba, hasAlphaChannel: true, hasTransparentPixels: transparent }
+}
+
+describe("diffImages", () => {
+	test("#given two identical images #when diffed #then similarity is 100 with no hotspots", () => {
+		// given
+		const ref = makeImage(4, 4, solidRgba(4, 4, [10, 20, 30, 255]))
+		const act = makeImage(4, 4, solidRgba(4, 4, [10, 20, 30, 255]))
+		// when
+		const result = diffImages(ref, act)
+		// then
+		expect(result.diffPixels).toBe(0)
+		expect(result.similarityScore).toBe(100)
+		expect(result.hotspots.length).toBe(0)
+		expect(result.dimensionsMatch).toBe(true)
+	})
+
+	test("#given two fully different images #when diffed #then similarity is 0 with hotspots", () => {
+		// given
+		const ref = makeImage(4, 4, solidRgba(4, 4, [0, 0, 0, 255]))
+		const act = makeImage(4, 4, solidRgba(4, 4, [255, 255, 255, 255]))
+		// when
+		const result = diffImages(ref, act)
+		// then
+		expect(result.diffPixels).toBe(16)
+		expect(result.similarityScore).toBe(0)
+		expect(result.hotspots.length).toBeGreaterThan(0)
+	})
+
+	test("#given images of different sizes #when diffed #then dimensionsMatch is false", () => {
+		// given
+		const ref = makeImage(4, 4, solidRgba(4, 4, [0, 0, 0, 255]))
+		const act = makeImage(2, 2, solidRgba(2, 2, [0, 0, 0, 255]))
+		// when
+		const result = diffImages(ref, act)
+		// then
+		expect(result.dimensionsMatch).toBe(false)
+	})
+
+	test("#given a transparent reference and an opaque actual #when diffed #then alpha is flagged", () => {
+		// given
+		const ref = makeImage(2, 2, solidRgba(2, 2, [0, 0, 0, 128]), true)
+		const act = makeImage(2, 2, solidRgba(2, 2, [0, 0, 0, 255]), false)
+		// when
+		const result = diffImages(ref, act)
+		// then
+		expect(result.alphaChannelIntact).toBe(false)
+	})
+
+	test("#given a single changed pixel #when diffed #then one hotspot marks its grid cell", () => {
+		// given
+		const base = solidRgba(8, 8, [0, 0, 0, 255])
+		const changed = solidRgba(8, 8, [0, 0, 0, 255])
+		changed[0] = 255
+		// when
+		const result = diffImages(makeImage(8, 8, base), makeImage(8, 8, changed))
+		// then
+		expect(result.diffPixels).toBe(1)
+		expect(result.hotspots.length).toBe(1)
+		expect(result.hotspots[0]?.gridX).toBe(0)
+		expect(result.hotspots[0]?.gridY).toBe(0)
+	})
+})

package/dist/skills/visual-qa/scripts/image-diff.ts

@@ -0,0 +1,109 @@
+import type { DecodedImage, Hotspot, ImageDiffResult } from "./types"
+
+const GRID_SIZE = 8
+
+function round4(value: number): number {
+	return Math.round(value * 10000) / 10000
+}
+
+function pixelsDiffer(ref: Uint8Array, refOffset: number, act: Uint8Array, actOffset: number): boolean {
+	return (
+		ref[refOffset] !== act[actOffset] ||
+		ref[refOffset + 1] !== act[actOffset + 1] ||
+		ref[refOffset + 2] !== act[actOffset + 2] ||
+		ref[refOffset + 3] !== act[actOffset + 3]
+	)
+}
+
+function buildHotspots(
+	cellDiff: readonly number[],
+	cellTotal: readonly number[],
+	cols: number,
+	rows: number,
+	overlapWidth: number,
+	overlapHeight: number,
+): Hotspot[] {
+	const hotspots: Hotspot[] = []
+	for (let gridY = 0; gridY < rows; gridY++) {
+		for (let gridX = 0; gridX < cols; gridX++) {
+			const index = gridY * cols + gridX
+			const diff = cellDiff[index] ?? 0
+			const total = cellTotal[index] ?? 0
+			if (diff === 0 || total === 0) continue
+			const left = Math.floor((gridX * overlapWidth) / cols)
+			const right = Math.floor(((gridX + 1) * overlapWidth) / cols)
+			const top = Math.floor((gridY * overlapHeight) / rows)
+			const bottom = Math.floor(((gridY + 1) * overlapHeight) / rows)
+			hotspots.push({
+				gridX,
+				gridY,
+				x: left,
+				y: top,
+				width: right - left,
+				height: bottom - top,
+				diffRatio: round4(diff / total),
+			})
+		}
+	}
+	hotspots.sort((a, b) => b.diffRatio - a.diffRatio)
+	return hotspots
+}
+
+function buildSummary(
+	similarityScore: number,
+	diffPixels: number,
+	totalPixels: number,
+	dimensionsMatch: boolean,
+	hotspotCount: number,
+): string {
+	const parts = [`${similarityScore}/100 similarity`, `${diffPixels}/${totalPixels} pixels differ`]
+	if (!dimensionsMatch) parts.push("dimensions differ")
+	if (hotspotCount > 0) parts.push(`${hotspotCount} hotspot region(s)`)
+	return `${parts.join("; ")}.`
+}
+
+export function diffImages(reference: DecodedImage, actual: DecodedImage): ImageDiffResult {
+	const overlapWidth = Math.min(reference.width, actual.width)
+	const overlapHeight = Math.min(reference.height, actual.height)
+	const totalPixels = overlapWidth * overlapHeight
+	const cols = Math.max(1, Math.min(GRID_SIZE, overlapWidth))
+	const rows = Math.max(1, Math.min(GRID_SIZE, overlapHeight))
+	const cellDiff = new Array<number>(cols * rows).fill(0)
+	const cellTotal = new Array<number>(cols * rows).fill(0)
+
+	let diffPixels = 0
+	for (let y = 0; y < overlapHeight; y++) {
+		const cellY = Math.min(rows - 1, Math.floor((y * rows) / overlapHeight))
+		for (let x = 0; x < overlapWidth; x++) {
+			const cellX = Math.min(cols - 1, Math.floor((x * cols) / overlapWidth))
+			const cellIndex = cellY * cols + cellX
+			cellTotal[cellIndex] = (cellTotal[cellIndex] ?? 0) + 1
+			const refOffset = (y * reference.width + x) * 4
+			const actOffset = (y * actual.width + x) * 4
+			if (pixelsDiffer(reference.rgba, refOffset, actual.rgba, actOffset)) {
+				diffPixels++
+				cellDiff[cellIndex] = (cellDiff[cellIndex] ?? 0) + 1
+			}
+		}
+	}
+
+	const diffRatio = totalPixels === 0 ? 0 : diffPixels / totalPixels
+	const similarityScore = Math.round((1 - diffRatio) * 100)
+	const hotspots = buildHotspots(cellDiff, cellTotal, cols, rows, overlapWidth, overlapHeight)
+	const dimensionsMatch = reference.width === actual.width && reference.height === actual.height
+	const alphaChannelIntact = !(reference.hasTransparentPixels && !actual.hasTransparentPixels)
+
+	return {
+		command: "image-diff",
+		dimensionsMatch,
+		reference: { width: reference.width, height: reference.height },
+		actual: { width: actual.width, height: actual.height },
+		totalPixels,
+		diffPixels,
+		diffRatio: round4(diffRatio),
+		similarityScore,
+		alphaChannelIntact,
+		hotspots,
+		summary: buildSummary(similarityScore, diffPixels, totalPixels, dimensionsMatch, hotspots.length),
+	}
+}

package/dist/skills/visual-qa/scripts/png-crc.ts

@@ -0,0 +1,27 @@
+import { Buffer } from "node:buffer"
+
+export const PNG_SIGNATURE: Buffer = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+function buildCrcTable(): Uint32Array {
+	const table = new Uint32Array(256)
+	for (let n = 0; n < 256; n++) {
+		let c = n
+		for (let k = 0; k < 8; k++) {
+			c = (c & 1) === 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+		}
+		table[n] = c >>> 0
+	}
+	return table
+}
+
+const CRC_TABLE = buildCrcTable()
+
+export function crc32(data: Buffer): number {
+	let crc = 0xffffffff
+	for (let i = 0; i < data.length; i++) {
+		const byte = data[i] ?? 0
+		const entry = CRC_TABLE[(crc ^ byte) & 0xff] ?? 0
+		crc = entry ^ (crc >>> 8)
+	}
+	return (crc ^ 0xffffffff) >>> 0
+}

package/dist/skills/visual-qa/scripts/png-decode.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test"
+import { Buffer } from "node:buffer"
+
+import { decodePng } from "./png-decode"
+import { encodeRgbaPng, solidRgba } from "./png-synth"
+
+describe("decodePng", () => {
+	test("#given an encoded RGBA image #when decoded #then dimensions and first pixel round-trip", () => {
+		// given
+		const png = encodeRgbaPng(3, 2, solidRgba(3, 2, [10, 20, 30, 255]))
+		// when
+		const decoded = decodePng(png)
+		// then
+		expect(decoded.width).toBe(3)
+		expect(decoded.height).toBe(2)
+		expect(Array.from(decoded.rgba.subarray(0, 4))).toEqual([10, 20, 30, 255])
+	})
+
+	test("#given a fully opaque image #when decoded #then it has no transparent pixels", () => {
+		// given
+		const png = encodeRgbaPng(2, 2, solidRgba(2, 2, [0, 0, 0, 255]))
+		// when
+		const decoded = decodePng(png)
+		// then
+		expect(decoded.hasAlphaChannel).toBe(true)
+		expect(decoded.hasTransparentPixels).toBe(false)
+	})
+
+	test("#given a semi-transparent image #when decoded #then it reports transparent pixels", () => {
+		// given
+		const png = encodeRgbaPng(2, 2, solidRgba(2, 2, [255, 255, 255, 128]))
+		// when
+		const decoded = decodePng(png)
+		// then
+		expect(decoded.hasTransparentPixels).toBe(true)
+	})
+
+	test("#given a non-PNG buffer #when decoded #then it throws", () => {
+		// given
+		const notPng = Buffer.from("this is not a png file")
+		// when / then
+		expect(() => decodePng(notPng)).toThrow("not a PNG")
+	})
+})