# Browser setup (Web capture)

Capture with omowright from the js-eval kernel. The library is staged inside the `browser` skill;
load it once per session:

```js
const { loadOmowright } = await import("<browser-skill-root>/scripts/omowright.mjs")
const { omowright } = await loadOmowright()
```

## Owned engine (default for QA)

A browser your code launches, with a task-owned profile, pinned viewport and no user state.
`connectPipe` opens no listening port and reaps the process on `close()`.

```js
// js-eval cell; url and pngPath belong to this QA run.
const { mkdtempSync, rmSync } = await import("node:fs")
const profile = mkdtempSync(`${(await import("node:os")).tmpdir()}/visual-qa-`)
const browser = await omowright.connectPipe({
  browserPath: chromeBinary,                      // installed Chrome, Chromium, CloakBrowser or chrome-headless-shell
  browserArgs: ["--headless", "--no-first-run", `--user-data-dir=${profile}`],
  storageRoot: profile,
})
try {
  const page = await browser.newTab("about:blank")
  await omowright.emulate(page, { width: 1280, height: 720, deviceScaleFactor: 1, mobile: false, hasTouch: false })
  await page.goto(url, { waitUntil: "load" })
  await Bun.write(pngPath, await page.screenshot())
  console.log(pngPath)
} finally {
  await browser.close()
  rmSync(profile, { recursive: true, force: true })
}
```

Chrome must already be installed; report an absent executable rather than downloading a managed
browser. For bot-scored or WAF targets use `connectCloakProfile({ profileDir })` (CloakBrowser
with a pinned fingerprint seed) — the `browser` skill's `references/owned-engine/README.md`
covers it.

## Attached engine (authenticated pages)

When the capture needs the user's login, drive the browser they are signed into instead of
cloning its profile:

```js
const session = await omowright.connectBrowserSkill({ name: "visual-qa capture", focused: false })
try {
  await session.navigate(url, { waitUntil: "load" })
  await session.resize(1280, 720)
  const shot = await session.screenshot()            // { buffer, width, height }
  await Bun.write(pngPath, shot.buffer)
} finally {
  await session.stop()
}
```

NEVER launch anything against, or clear cookies/cache/site data from, the user's live profile;
the attached engine is the only sanctioned way to a signed-in page. If no extension is connected,
run the `browser` skill's `scripts/browser-install.mjs` for the browser the user actually uses
(from memory, or its detection; on `needsChoice` ask them and pass `--browser=<id>`), relay its
one human step, and wait — do
not fall back to the owned engine for an authenticated criterion.

## Capture a screenshot at a fixed viewport

Match CSS viewport AND PNG dimensions: pin `deviceScaleFactor` through `emulate` (owned) or
`resize` (attached) instead of resizing the PNG to force a pass. Wait for the specific page state
(a locator, a `waitForURL`, a `createNetworkSnoop(page).waitFor(...)`), not a sleep, then compare:

```sh
node "$SKILL_DIR/scripts/visual-qa.mjs" image-diff reference.png actual.png
```

Inspect `dimensionsMatch` and `diffRatio`, then inspect the image. Close every browser and session
and the fixture server, even on a failed capture; remove the owned profile in the same `finally`.

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)
	})
})

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
}

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 Node bundle is spawned for image-diff without Bun on PATH #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])))
		const nodePath = Bun.which("node")
		if (nodePath === null) throw new Error("node not found on PATH")
		// when
		const proc = Bun.spawnSync({
			cmd: [nodePath, join(import.meta.dir, "visual-qa.mjs"), "image-diff", reference, actual],
			env: { ...process.env, PATH: "/usr/bin:/bin" },
		})
		// 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)
	})
})

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))
}

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)
	})
})

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
}

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)
	})
})

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),
	}
}

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
}

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")
	})
})

import { Buffer } from "node:buffer"
import { inflateSync } from "node:zlib"

import { PNG_SIGNATURE } from "./png-crc"
import type { DecodedImage } from "./types"

export class PngDecodeError extends Error {
	readonly name = "PngDecodeError"
}

interface PngHeader {
	readonly width: number
	readonly height: number
	readonly bitDepth: number
	readonly colorType: number
	readonly channels: number
}

interface PngChunk {
	readonly type: string
	readonly data: Buffer
}

function readChunks(buffer: Buffer): readonly PngChunk[] {
	const chunks: PngChunk[] = []
	let offset = 8
	while (offset + 8 <= buffer.length) {
		const length = buffer.readUInt32BE(offset)
		const type = buffer.toString("ascii", offset + 4, offset + 8)
		const dataStart = offset + 8
		const dataEnd = dataStart + length
		if (dataEnd + 4 > buffer.length) break
		chunks.push({ type, data: buffer.subarray(dataStart, dataEnd) })
		offset = dataEnd + 4
	}
	return chunks
}

function channelsForColorType(colorType: number): number {
	switch (colorType) {
		case 0:
			return 1
		case 2:
			return 3
		case 4:
			return 2
		case 6:
			return 4
		default:
			throw new PngDecodeError(`unsupported color type ${colorType}`)
	}
}

function parseHeader(data: Buffer): PngHeader {
	if (data.length < 13) {
		throw new PngDecodeError("invalid IHDR chunk length")
	}
	const colorType = data[9] ?? 0
	return {
		width: data.readUInt32BE(0),
		height: data.readUInt32BE(4),
		bitDepth: data[8] ?? 0,
		colorType,
		channels: channelsForColorType(colorType),
	}
}

function paeth(a: number, b: number, c: number): number {
	const p = a + b - c
	const pa = Math.abs(p - a)
	const pb = Math.abs(p - b)
	const pc = Math.abs(p - c)
	if (pa <= pb && pa <= pc) return a
	if (pb <= pc) return b
	return c
}

function unfilterRow(filterType: number, row: Buffer, prev: Buffer | null, bpp: number): Buffer {
	const out = Buffer.alloc(row.length)
	for (let i = 0; i < row.length; i++) {
		const raw = row[i] ?? 0
		const a = i >= bpp ? (out[i - bpp] ?? 0) : 0
		const b = prev ? (prev[i] ?? 0) : 0
		const c = i >= bpp && prev ? (prev[i - bpp] ?? 0) : 0
		switch (filterType) {
			case 0:
				out[i] = raw
				break
			case 1:
				out[i] = (raw + a) & 0xff
				break
			case 2:
				out[i] = (raw + b) & 0xff
				break
			case 3:
				out[i] = (raw + ((a + b) >> 1)) & 0xff
				break
			case 4:
				out[i] = (raw + paeth(a, b, c)) & 0xff
				break
			default:
				throw new PngDecodeError(`unsupported filter type ${filterType}`)
		}
	}
	return out
}

function decodePixels(idat: Buffer, width: number, height: number, bpp: number): Buffer {
	const inflated = inflateSync(idat)
	const rowBytes = width * bpp
	if (inflated.length < height * (rowBytes + 1)) {
		throw new PngDecodeError("truncated image data")
	}
	const pixels = Buffer.alloc(width * height * bpp)
	let prev: Buffer | null = null
	for (let y = 0; y < height; y++) {
		const rowStart = y * (rowBytes + 1)
		const filterType = inflated[rowStart] ?? 0
		const filtered = inflated.subarray(rowStart + 1, rowStart + 1 + rowBytes)
		const row = unfilterRow(filterType, filtered, prev, bpp)
		row.copy(pixels, y * rowBytes)
		prev = row
	}
	return pixels
}

function normalizeToRgba(
	pixels: Buffer,
	pixelCount: number,
	channels: number,
): { readonly rgba: Uint8Array; readonly hasTransparent: boolean } {
	const rgba = new Uint8Array(pixelCount * 4)
	let hasTransparent = false
	for (let i = 0; i < pixelCount; i++) {
		const src = i * channels
		let r = 0
		let g = 0
		let b = 0
		let a = 255
		switch (channels) {
			case 1: {
				const v = pixels[src] ?? 0
				r = v
				g = v
				b = v
				break
			}
			case 2: {
				const v = pixels[src] ?? 0
				r = v
				g = v
				b = v
				a = pixels[src + 1] ?? 255
				break
			}
			case 3: {
				r = pixels[src] ?? 0
				g = pixels[src + 1] ?? 0
				b = pixels[src + 2] ?? 0
				break
			}
			default: {
				r = pixels[src] ?? 0
				g = pixels[src + 1] ?? 0
				b = pixels[src + 2] ?? 0
				a = pixels[src + 3] ?? 255
			}
		}
		const dst = i * 4
		rgba[dst] = r
		rgba[dst + 1] = g
		rgba[dst + 2] = b
		rgba[dst + 3] = a
		if (a < 255) hasTransparent = true
	}
	return { rgba, hasTransparent }
}

export function decodePng(buffer: Buffer): DecodedImage {
	if (buffer.length < 8 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) {
		throw new PngDecodeError("not a PNG file (bad signature)")
	}
	const chunks = readChunks(buffer)
	const ihdr = chunks.find((chunk) => chunk.type === "IHDR")
	if (ihdr === undefined) {
		throw new PngDecodeError("missing IHDR chunk")
	}
	const header = parseHeader(ihdr.data)
	if (header.bitDepth !== 8) {
		throw new PngDecodeError(`unsupported bit depth ${header.bitDepth}`)
	}
	const idatChunks = chunks.filter((chunk) => chunk.type === "IDAT")
	if (idatChunks.length === 0) {
		throw new PngDecodeError("missing IDAT chunk")
	}
	const idat = Buffer.concat(idatChunks.map((chunk) => chunk.data))
	const pixels = decodePixels(idat, header.width, header.height, header.channels)
	const normalized = normalizeToRgba(pixels, header.width * header.height, header.channels)
	return {
		width: header.width,
		height: header.height,
		rgba: normalized.rgba,
		hasAlphaChannel: header.colorType === 4 || header.colorType === 6,
		hasTransparentPixels: normalized.hasTransparent,
	}
}

import { Buffer } from "node:buffer"
import { deflateSync } from "node:zlib"

import { crc32, PNG_SIGNATURE } from "./png-crc"

const BIT_DEPTH_8 = 8
const COLOR_TYPE_RGBA = 6
const FILTER_NONE = 0
const RGBA_CHANNELS = 4

function pngChunk(type: string, data: Buffer): Buffer {
	const typeBuffer = Buffer.from(type, "ascii")
	const length = Buffer.alloc(4)
	length.writeUInt32BE(data.length, 0)
	const crcBuffer = Buffer.alloc(4)
	crcBuffer.writeUInt32BE(crc32(Buffer.concat([typeBuffer, data])), 0)
	return Buffer.concat([length, typeBuffer, data, crcBuffer])
}

export function encodeRgbaPng(width: number, height: number, rgba: Uint8Array): Buffer {
	const rowBytes = width * RGBA_CHANNELS
	const raw = Buffer.alloc(height * (rowBytes + 1))
	for (let y = 0; y < height; y++) {
		const rowStart = y * (rowBytes + 1)
		raw[rowStart] = FILTER_NONE
		for (let x = 0; x < rowBytes; x++) {
			raw[rowStart + 1 + x] = rgba[y * rowBytes + x] ?? 0
		}
	}
	const header = Buffer.alloc(13)
	header.writeUInt32BE(width, 0)
	header.writeUInt32BE(height, 4)
	header[8] = BIT_DEPTH_8
	header[9] = COLOR_TYPE_RGBA
	return Buffer.concat([
		PNG_SIGNATURE,
		pngChunk("IHDR", header),
		pngChunk("IDAT", deflateSync(raw)),
		pngChunk("IEND", Buffer.alloc(0)),
	])
}

export function solidRgba(
	width: number,
	height: number,
	color: readonly [number, number, number, number],
): Uint8Array {
	const rgba = new Uint8Array(width * height * RGBA_CHANNELS)
	for (let pixel = 0; pixel < width * height; pixel++) {
		const offset = pixel * RGBA_CHANNELS
		rgba[offset] = color[0]
		rgba[offset + 1] = color[1]
		rgba[offset + 2] = color[2]
		rgba[offset + 3] = color[3]
	}
	return rgba
}

import { describe, expect, test } from "bun:test"

import { checkTui } from "./tui-grid"

const ESC = String.fromCharCode(0x1b)

describe("checkTui", () => {
	test("#given ASCII lines within the width #when checked #then there is no overflow", () => {
		// given / when
		const result = checkTui("hello\nworld", 80)
		// then
		expect(result.lineCount).toBe(2)
		expect(result.lineWidths).toEqual([5, 5])
		expect(result.maxWidth).toBe(5)
		expect(result.overflowLines.length).toBe(0)
		expect(result.hasAnsi).toBe(false)
	})

	test("#given a line wider than the expected columns #when checked #then it is flagged as overflow", () => {
		// given / when
		const result = checkTui("short\nthis line is definitely too long", 10)
		// then
		expect(result.overflowLines.length).toBe(1)
		expect(result.overflowLines[0]?.line).toBe(2)
		expect(result.maxWidth).toBeGreaterThan(10)
	})

	test("#given CJK text #when checked #then wide characters count as two columns", () => {
		// given / when
		const result = checkTui("가나다", 80)
		// then
		expect(result.lineWidths).toEqual([6])
		expect(result.wideCharColumns).toEqual([0, 2, 4])
	})

	test("#given a box whose CJK content is wider than its border #when checked #then borders are misaligned", () => {
		// given / when
		const result = checkTui("┌──┐\n│가가│\n└──┘", 80)
		// then
		expect(result.borderMisaligned).toBe(true)
	})

	test("#given a well-formed box #when checked #then borders are aligned", () => {
		// given / when
		const result = checkTui("┌──┐\n│ab│\n└──┘", 80)
		// then
		expect(result.borderMisaligned).toBe(false)
	})

	test("#given text with ANSI color codes #when checked #then ANSI is detected and ignored for width", () => {
		// given / when
		const result = checkTui(`${ESC}[31mred${ESC}[0m`, 80)
		// then
		expect(result.hasAnsi).toBe(true)
		expect(result.lineWidths).toEqual([3])
	})
})

import { hasAnsi, stripAnsi } from "./ansi"
import { charWidth, stringWidth } from "./east-asian-width"
import type { OverflowLine, TuiCheckResult } from "./types"

const BOX_DRAWING_START = 0x2500
const BOX_DRAWING_END = 0x257f
const MAX_WIDE_COLUMNS = 64

function splitLines(text: string): string[] {
	const lines = text.split(/\r?\n/)
	if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop()
	return lines
}

function isFrameLine(plain: string): boolean {
	for (const char of plain) {
		const codePoint = char.codePointAt(0)
		if (codePoint !== undefined && codePoint >= BOX_DRAWING_START && codePoint <= BOX_DRAWING_END) {
			return true
		}
	}
	return false
}

function wideStartColumns(plain: string): number[] {
	const columns: number[] = []
	let column = 0
	for (const char of plain) {
		const codePoint = char.codePointAt(0)
		if (codePoint === undefined) continue
		const width = charWidth(codePoint)
		if (width === 2) columns.push(column)
		column += width
	}
	return columns
}

function summarize(
	lineCount: number,
	maxWidth: number,
	expectedColumns: number,
	overflowCount: number,
	borderMisaligned: boolean,
	containsAnsi: boolean,
): string {
	const parts = [`${lineCount} line(s)`, `max width ${maxWidth}/${expectedColumns}`]
	if (overflowCount > 0) parts.push(`${overflowCount} overflow line(s)`)
	if (borderMisaligned) parts.push("borders misaligned")
	if (containsAnsi) parts.push("contains ANSI")
	return `${parts.join("; ")}.`
}

export function checkTui(text: string, expectedColumns: number): TuiCheckResult {
	const lines = splitLines(text)
	const lineWidths: number[] = []
	const overflowLines: OverflowLine[] = []
	const wideColumns = new Set<number>()
	const frameWidths = new Set<number>()

	for (let index = 0; index < lines.length; index++) {
		const plain = stripAnsi(lines[index] ?? "")
		const width = stringWidth(plain)
		lineWidths.push(width)
		if (expectedColumns > 0 && width > expectedColumns) {
			overflowLines.push({ line: index + 1, width })
		}
		if (isFrameLine(plain)) frameWidths.add(width)
		for (const column of wideStartColumns(plain)) {
			if (wideColumns.size < MAX_WIDE_COLUMNS) wideColumns.add(column)
		}
	}

	const maxWidth = lineWidths.reduce((max, width) => (width > max ? width : max), 0)
	const borderMisaligned = frameWidths.size > 1
	const containsAnsi = hasAnsi(text)
	return {
		command: "tui-check",
		expectedColumns,
		lineCount: lines.length,
		lineWidths,
		maxWidth,
		overflowLines,
		borderMisaligned,
		wideCharColumns: [...wideColumns].sort((a, b) => a - b),
		hasAnsi: containsAnsi,
		summary: summarize(lines.length, maxWidth, expectedColumns, overflowLines.length, borderMisaligned, containsAnsi),
	}
}

export interface DecodedImage {
	readonly width: number
	readonly height: number
	readonly rgba: Uint8Array
	readonly hasAlphaChannel: boolean
	readonly hasTransparentPixels: boolean
}

export interface Hotspot {
	readonly gridX: number
	readonly gridY: number
	readonly x: number
	readonly y: number
	readonly width: number
	readonly height: number
	readonly diffRatio: number
}

export interface ImageDimensions {
	readonly width: number
	readonly height: number
}

export interface ImageDiffResult {
	readonly command: "image-diff"
	readonly dimensionsMatch: boolean
	readonly reference: ImageDimensions
	readonly actual: ImageDimensions
	readonly totalPixels: number
	readonly diffPixels: number
	readonly diffRatio: number
	readonly similarityScore: number
	readonly alphaChannelIntact: boolean
	readonly hotspots: readonly Hotspot[]
	readonly summary: string
}

export interface OverflowLine {
	readonly line: number
	readonly width: number
}

export interface TuiCheckResult {
	readonly command: "tui-check"
	readonly expectedColumns: number
	readonly lineCount: number
	readonly lineWidths: readonly number[]
	readonly maxWidth: number
	readonly overflowLines: readonly OverflowLine[]
	readonly borderMisaligned: boolean
	readonly wideCharColumns: readonly number[]
	readonly hasAnsi: boolean
	readonly summary: string
}