@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/skills/visual-qa/scripts/ansi.mjs

@@ -0,0 +1,71 @@
+const ESC = "\u001b";
+const BEL = "\u0007";
+const ST = "\u009c";
+
+function stringControl(text, start, allowBel) {
+	let index = start;
+	while (index < text.length) {
+		if ((allowBel && text[index] === BEL) || text[index] === ST) return { end: index + 1, terminated: true };
+		if (text[index] === ESC && text[index + 1] === "\\") return { end: index + 2, terminated: true };
+		index += 1;
+	}
+	return { end: text.length, terminated: false };
+}
+
+function csi(text, start) {
+	let index = start;
+	while (index < text.length) {
+		const code = text.charCodeAt(index);
+		index += 1;
+		if (code >= 0x40 && code <= 0x7e) return { end: index, terminated: true };
+	}
+	return { end: text.length, terminated: false };
+}
+
+export function analyzeAnsi(input) {
+	let output = "";
+	let hasControl = false;
+	let unterminated = false;
+	let unsafeControl = false;
+	for (let index = 0; index < input.length;) {
+		const code = input.charCodeAt(index);
+		let consumed;
+		if (input[index] === ESC && input[index + 1] === "]") consumed = stringControl(input, index + 2, true);
+		else if (code === 0x9d) consumed = stringControl(input, index + 1, true);
+		else if (input[index] === ESC && ["P", "_", "^", "X"].includes(input[index + 1])) {
+			consumed = stringControl(input, index + 2, false);
+		} else if ([0x90, 0x9f, 0x9e, 0x98].includes(code)) consumed = stringControl(input, index + 1, false);
+		else if (input[index] === ESC && input[index + 1] === "[") consumed = csi(input, index + 2);
+		else if (code === 0x9b) consumed = csi(input, index + 1);
+		else if (input[index] === ESC) consumed = {
+			end: Math.min(input.length, index + 2),
+			terminated: index + 1 < input.length,
+		};
+		else if (code >= 0x80 && code <= 0x9f) consumed = { end: index + 1, terminated: true, unsafe: true };
+		if (
+			consumed === undefined &&
+			((code >= 0x00 && code <= 0x1f && code !== 0x09 && code !== 0x0a) || code === 0x7f)
+		) {
+			hasControl = true;
+			unsafeControl = true;
+			index += 1;
+		} else if (consumed === undefined) {
+			output += input[index];
+			index += 1;
+		} else {
+			hasControl = true;
+			if (!consumed.terminated) unterminated = true;
+			if (consumed.unsafe) unsafeControl = true;
+			index = consumed.end;
+		}
+	}
+	return { text: output, hasControl, unterminated, unsafeControl };
+}
+
+export function stripAnsi(input) {
+	return analyzeAnsi(input).text;
+}
+
+export function hasAnsi(input) {
+	return analyzeAnsi(input).hasControl;
+}

package/marketplace/plugins/litcodex/skills/visual-qa/scripts/cli.mjs

@@ -0,0 +1,54 @@
+import {
+	InputError,
+	decodeUtf8,
+	readRegularBytesWithin,
+} from "./strict-input.mjs";
+import { isMain } from "./entrypoint.mjs";
+import { diffImages } from "./image-diff.mjs";
+import { decodePng } from "./png-decode.mjs";
+import { checkTui } from "./tui-grid.mjs";
+
+function tuiArgs(args) {
+	if (!(args.length === 1 || (args.length === 3 && args[1] === "--cols"))) {
+		throw new Error("usage: tui-check <capture.txt> [--cols N]");
+	}
+	const raw = args[2] ?? "80";
+	const value = Number(raw);
+	if (!Number.isInteger(value) || value < 1 || value > 1000) throw new Error("--cols requires 1..1000");
+	return { path: args[0], columns: value };
+}
+
+function bounded(path, maxBytes, code) {
+	try {
+		return readRegularBytesWithin(path, process.cwd(), maxBytes, code);
+	} catch (error) {
+		if (error instanceof InputError) throw error;
+		throw new Error(`${code}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+export function run(args) {
+	const [command, ...rest] = args;
+	if (command === "image-diff") {
+		if (rest.length !== 2) throw new Error("usage: image-diff <reference.png> <actual.png>");
+		return diffImages(
+			decodePng(bounded(rest[0], 25 * 1024 * 1024, "REFERENCE_PNG_INVALID")),
+			decodePng(bounded(rest[1], 25 * 1024 * 1024, "ACTUAL_PNG_INVALID")),
+		);
+	}
+	if (command === "tui-check") {
+		const options = tuiArgs(rest);
+		const bytes = bounded(options.path, 1024 * 1024, "TUI_CAPTURE_INVALID");
+		return checkTui(decodeUtf8(bytes, 1024 * 1024, "TUI_CAPTURE_INVALID"), options.columns);
+	}
+	throw new Error("command must be image-diff or tui-check");
+}
+
+if (isMain(import.meta.url)) {
+	try {
+		process.stdout.write(`${JSON.stringify(run(process.argv.slice(2)), null, 2)}\n`);
+	} catch (error) {
+		process.stderr.write(`VISUAL_QA_ERROR: ${error instanceof Error ? error.message : String(error)}\n`);
+		process.exitCode = 1;
+	}
+}

package/marketplace/plugins/litcodex/skills/visual-qa/scripts/east-asian-width.mjs

@@ -0,0 +1,31 @@
+const segmenter = new Intl.Segmenter("en", { granularity: "grapheme" });
+
+const WIDE_RANGES = [
+	[0x1100, 0x115f], [0x231a, 0x231b], [0x2e80, 0x303e], [0x3041, 0x33ff],
+	[0x3400, 0x4dbf], [0x4e00, 0xa4cf], [0xa960, 0xa97f], [0xac00, 0xd7a3],
+	[0xf900, 0xfaff], [0xfe10, 0xfe19], [0xfe30, 0xfe6f], [0xff00, 0xff60],
+	[0xffe0, 0xffe6], [0x1b000, 0x1b16f], [0x1f200, 0x1faff], [0x20000, 0x3fffd],
+];
+
+function wide(codePoint) {
+	return WIDE_RANGES.some(([start, end]) => codePoint >= start && codePoint <= end);
+}
+
+export function charWidth(codePoint) {
+	if (codePoint === 0 || codePoint < 0x20 || (codePoint >= 0x7f && codePoint <= 0x9f)) return 0;
+	if (codePoint === 0x200d || /\p{Mark}/u.test(String.fromCodePoint(codePoint))) return 0;
+	return wide(codePoint) ? 2 : 1;
+}
+
+function graphemeWidth(grapheme) {
+	if (/\p{Extended_Pictographic}/u.test(grapheme)) return 2;
+	let width = 0;
+	for (const char of grapheme) width += charWidth(char.codePointAt(0));
+	return width;
+}
+
+export function stringWidth(text) {
+	let total = 0;
+	for (const entry of segmenter.segment(text)) total += graphemeWidth(entry.segment);
+	return total;
+}

package/marketplace/plugins/litcodex/skills/visual-qa/scripts/entrypoint.mjs

@@ -0,0 +1 @@
+export { isMain } from "./strict-input.mjs";

package/marketplace/plugins/litcodex/skills/visual-qa/scripts/evidence-bytes.mjs

@@ -0,0 +1,61 @@
+import { canonicalJson, isRecord, sha256 } from "./strict-input.mjs";
+
+const HASH = /^[0-9a-f]{64}$/;
+const EVIDENCE_BYTES_KEYS = new Set(["manifest", "inventory", "inventory_items", "capture_base64"]);
+
+function canonicalBase64(value, label, issues) {
+	if (typeof value !== "string") {
+		issues.push(`${label} must be a base64 string`);
+		return Buffer.alloc(0);
+	}
+	const bytes = Buffer.from(value, "base64");
+	if (bytes.length === 0) issues.push(`${label} must contain nonempty evidence bytes`);
+	if (bytes.toString("base64") !== value) issues.push(`${label} is not canonical base64`);
+	return bytes;
+}
+
+export function evidenceByteHashes(value, manifest) {
+	const issues = [];
+	if (!isRecord(value)) return { issues: ["evidence_bytes must be an object"], hashes: [] };
+	for (const key of Object.keys(value)) {
+		if (!EVIDENCE_BYTES_KEYS.has(key)) issues.push(`evidence_bytes contains unknown key ${key}`);
+	}
+	if (
+		typeof value.manifest !== "string" ||
+		typeof value.inventory !== "string" ||
+		!isRecord(value.inventory_items)
+	) {
+		return { issues: [...issues, "evidence_bytes manifest, inventory, and inventory_items are invalid"], hashes: [] };
+	}
+	const expectedManifest = canonicalJson({ ...manifest, review_receipt_hashes: [] });
+	const expectedInventory = canonicalJson(manifest.inventory);
+	if (value.manifest !== expectedManifest) issues.push("manifest evidence bytes do not match the manifest");
+	if (value.inventory !== expectedInventory) issues.push("inventory evidence bytes do not match the manifest inventory");
+
+	const captured = new Map();
+	for (const entry of Array.isArray(manifest.inventory) ? manifest.inventory : []) {
+		if (isRecord(entry) && entry.status === "captured" && typeof entry.id === "string") {
+			captured.set(entry.id, entry.evidence_hash);
+		}
+	}
+	const itemIds = Object.keys(value.inventory_items).sort();
+	const expectedIds = [...captured.keys()].sort();
+	if (JSON.stringify(itemIds) !== JSON.stringify(expectedIds)) {
+		issues.push("inventory item evidence keys do not exactly match captured inventory ids");
+	}
+	for (const id of itemIds) {
+		const bytes = canonicalBase64(value.inventory_items[id], `inventory item ${id}`, issues);
+		const expectedHash = captured.get(id);
+		if (typeof expectedHash !== "string" || !HASH.test(expectedHash) || sha256(bytes) !== expectedHash) {
+			issues.push(`inventory evidence_hash does not match evidence bytes for ${id}`);
+		}
+	}
+	const capture = canonicalBase64(value.capture_base64, "capture evidence", issues);
+	const captureHash = sha256(capture);
+	if (manifest.capture_hash !== captureHash) issues.push("capture_hash does not match capture evidence bytes");
+	const inventorySubject = canonicalJson({
+		inventory: value.inventory,
+		inventory_items: value.inventory_items,
+	});
+	return { issues, hashes: [sha256(value.manifest), sha256(inventorySubject), captureHash] };
+}

package/marketplace/plugins/litcodex/skills/visual-qa/scripts/image-diff.mjs

@@ -0,0 +1,63 @@
+const GRID = 8;
+
+function rounded(value) {
+	return Math.round(value * 10000) / 10000;
+}
+
+function pixelDiff(reference, actual, refOffset, actualOffset) {
+	for (let channel = 0; channel < 4; channel += 1) {
+		if (reference[refOffset + channel] !== actual[actualOffset + channel]) return true;
+	}
+	return false;
+}
+
+export function diffImages(reference, actual) {
+	if (reference.width !== actual.width || reference.height !== actual.height) {
+		throw new Error("IMAGE_DIMENSION_MISMATCH: dimensions must match before scoring");
+	}
+	const width = Math.min(reference.width, actual.width);
+	const height = Math.min(reference.height, actual.height);
+	const columns = Math.max(1, Math.min(GRID, width));
+	const rows = Math.max(1, Math.min(GRID, height));
+	const changed = new Array(columns * rows).fill(0);
+	const totals = new Array(columns * rows).fill(0);
+	let diffPixels = 0;
+	let alphaDiffPixels = 0;
+	for (let y = 0; y < height; y += 1) {
+		for (let x = 0; x < width; x += 1) {
+			const cell = Math.min(rows - 1, Math.floor(y * rows / height)) * columns +
+				Math.min(columns - 1, Math.floor(x * columns / width));
+			totals[cell] += 1;
+			if (pixelDiff(reference.rgba, actual.rgba, (y * reference.width + x) * 4, (y * actual.width + x) * 4)) {
+				diffPixels += 1;
+				changed[cell] += 1;
+			}
+			if (reference.rgba[(y * reference.width + x) * 4 + 3] !== actual.rgba[(y * actual.width + x) * 4 + 3]) {
+				alphaDiffPixels += 1;
+			}
+		}
+	}
+	const hotspots = changed.flatMap((count, index) => count === 0 ? [] : [{
+		gridX: index % columns,
+		gridY: Math.floor(index / columns),
+		diffRatio: rounded(count / totals[index]),
+	}]).sort((left, right) => right.diffRatio - left.diffRatio);
+	const totalPixels = width * height;
+	const ratio = totalPixels === 0 ? 0 : diffPixels / totalPixels;
+	const dimensionsMatch = true;
+	return {
+		command: "image-diff",
+		dimensionsMatch,
+		reference: { width: reference.width, height: reference.height },
+		actual: { width: actual.width, height: actual.height },
+		totalPixels,
+		diffPixels,
+		diffRatio: rounded(ratio),
+		similarityScore: Math.round((1 - ratio) * 100),
+		alphaChannelIntact:
+			reference.hasAlphaChannel === actual.hasAlphaChannel &&
+			alphaDiffPixels === 0,
+		hotspots,
+		summary: `${Math.round((1 - ratio) * 100)}/100 similarity; ${diffPixels}/${totalPixels} pixels differ${dimensionsMatch ? "" : "; dimensions differ"}.`,
+	};
+}

package/marketplace/plugins/litcodex/skills/visual-qa/scripts/png-crc.mjs

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

package/marketplace/plugins/litcodex/skills/visual-qa/scripts/png-decode.mjs

@@ -0,0 +1,169 @@
+import { Buffer } from "node:buffer";
+import { inflateSync } from "node:zlib";
+import { crc32, PNG_SIGNATURE } from "./png-crc.mjs";
+
+const MAX_FILE_BYTES = 25 * 1024 * 1024;
+const MAX_DIMENSION = 16384;
+const MAX_PIXELS = 64 * 1024 * 1024;
+const MAX_DECODED_BYTES = 256 * 1024 * 1024;
+const MAX_TOTAL_ALLOCATION = 256 * 1024 * 1024;
+const KNOWN_CRITICAL = new Set(["IHDR", "PLTE", "IDAT", "IEND"]);
+
+export class PngDecodeError extends Error {
+	constructor(code, detail) {
+		super(`${code}: ${detail}`);
+		this.name = "PngDecodeError";
+		this.code = code;
+	}
+}
+
+function chunks(buffer) {
+	const result = [];
+	let offset = 8;
+	while (offset < buffer.length) {
+		if (offset + 12 > buffer.length) throw new PngDecodeError("PNG_TRUNCATED", "incomplete chunk framing");
+		const length = buffer.readUInt32BE(offset);
+		const end = offset + 12 + length;
+		if (end > buffer.length) throw new PngDecodeError("PNG_TRUNCATED", "declared chunk exceeds input");
+		const type = buffer.toString("ascii", offset + 4, offset + 8);
+		if (!/^[A-Za-z]{4}$/.test(type)) throw new PngDecodeError("PNG_CHUNK_TYPE_INVALID", type);
+		if (/^[A-Z]/.test(type) && !KNOWN_CRITICAL.has(type)) {
+			throw new PngDecodeError("PNG_CRITICAL_CHUNK_UNSUPPORTED", type);
+		}
+		const typedData = buffer.subarray(offset + 4, offset + 8 + length);
+		const expected = buffer.readUInt32BE(offset + 8 + length);
+		if (crc32(typedData) !== expected) throw new PngDecodeError("PNG_CRC_MISMATCH", type);
+		result.push({ type, data: buffer.subarray(offset + 8, offset + 8 + length) });
+		offset = end;
+		if (type === "IEND") {
+			if (offset !== buffer.length) throw new PngDecodeError("PNG_TRAILING_DATA", "bytes after IEND");
+			return result;
+		}
+	}
+	throw new PngDecodeError("PNG_TRUNCATED", "missing IEND");
+}
+
+function header(chunk) {
+	if (chunk.data.length !== 13) throw new PngDecodeError("PNG_HEADER_INVALID", "IHDR length must be 13");
+	const width = chunk.data.readUInt32BE(0);
+	const height = chunk.data.readUInt32BE(4);
+	if (width < 1 || height < 1 || width > MAX_DIMENSION || height > MAX_DIMENSION || width * height > MAX_PIXELS) {
+		throw new PngDecodeError("PNG_RESOURCE_LIMIT", "dimension exceeds 16,384 or 64 megapixels");
+	}
+	const bitDepth = chunk.data[8];
+	const colorType = chunk.data[9];
+	if (bitDepth !== 8 || ![0, 2, 4, 6].includes(colorType)) throw new PngDecodeError("PNG_FORMAT_UNSUPPORTED", "8-bit grayscale/RGB/GA/RGBA only");
+	if (chunk.data[10] !== 0 || chunk.data[11] !== 0 || chunk.data[12] !== 0) throw new PngDecodeError("PNG_FORMAT_UNSUPPORTED", "compression/filter/interlace");
+	const channels = { 0: 1, 2: 3, 4: 2, 6: 4 }[colorType];
+	return { width, height, colorType, channels };
+}
+
+function paeth(left, above, upperLeft) {
+	const estimate = left + above - upperLeft;
+	const dl = Math.abs(estimate - left);
+	const da = Math.abs(estimate - above);
+	const du = Math.abs(estimate - upperLeft);
+	return dl <= da && dl <= du ? left : da <= du ? above : upperLeft;
+}
+
+function unfilter(filter, source, previous, bytesPerPixel) {
+	const row = Buffer.alloc(source.length);
+	for (let index = 0; index < source.length; index += 1) {
+		const raw = source[index];
+		const left = index >= bytesPerPixel ? row[index - bytesPerPixel] : 0;
+		const above = previous?.[index] ?? 0;
+		const upperLeft = index >= bytesPerPixel ? previous?.[index - bytesPerPixel] ?? 0 : 0;
+		const predictor = [0, left, above, Math.floor((left + above) / 2), paeth(left, above, upperLeft)][filter];
+		if (predictor === undefined) throw new PngDecodeError("PNG_FILTER_UNSUPPORTED", String(filter));
+		row[index] = (raw + predictor) & 0xff;
+	}
+	return row;
+}
+
+function rgbaFromRows(inflated, meta) {
+	const rowBytes = meta.width * meta.channels;
+	const expected = meta.height * (rowBytes + 1);
+	if (inflated.length !== expected) throw new PngDecodeError("PNG_DATA_INVALID", "inflated byte count");
+	const rgba = new Uint8Array(meta.width * meta.height * 4);
+	let transparent = false;
+	let previous;
+	for (let y = 0; y < meta.height; y += 1) {
+		const start = y * (rowBytes + 1);
+		const row = unfilter(inflated[start], inflated.subarray(start + 1, start + 1 + rowBytes), previous, meta.channels);
+		for (let x = 0; x < meta.width; x += 1) {
+			const source = x * meta.channels;
+			const target = (y * meta.width + x) * 4;
+			const gray = row[source];
+			const values = meta.channels === 1 ? [gray, gray, gray, 255]
+				: meta.channels === 2 ? [gray, gray, gray, row[source + 1]]
+					: meta.channels === 3 ? [row[source], row[source + 1], row[source + 2], 255]
+						: [row[source], row[source + 1], row[source + 2], row[source + 3]];
+			rgba.set(values, target);
+			if (values[3] < 255) transparent = true;
+		}
+		previous = row;
+	}
+	return { rgba, transparent };
+}
+
+export function decodePng(input) {
+	if (!ArrayBuffer.isView(input)) throw new PngDecodeError("PNG_INPUT_INVALID", "expected byte array");
+	if (input.byteLength > MAX_FILE_BYTES) throw new PngDecodeError("PNG_RESOURCE_LIMIT", "file exceeds 25 MiB");
+	const buffer = Buffer.isBuffer(input)
+		? input
+		: Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+	if (buffer.length < 8 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) throw new PngDecodeError("PNG_SIGNATURE_INVALID", "not PNG");
+	const parsed = chunks(buffer);
+	if (parsed[0]?.type !== "IHDR" || parsed.at(-1)?.type !== "IEND" || parsed.filter((item) => item.type === "IHDR").length !== 1) {
+		throw new PngDecodeError("PNG_CHUNK_ORDER_INVALID", "IHDR/IEND");
+	}
+	const meta = header(parsed[0]);
+	const types = parsed.map((item) => item.type);
+	if (types.filter((type) => type === "PLTE").length > 1) {
+		throw new PngDecodeError("PNG_CHUNK_ORDER_INVALID", "duplicate PLTE");
+	}
+	const idatStart = types.indexOf("IDAT");
+	const idatEnd = types.lastIndexOf("IDAT");
+	if (types.includes("PLTE") && types.indexOf("PLTE") > idatStart) {
+		throw new PngDecodeError("PNG_CHUNK_ORDER_INVALID", "PLTE after IDAT");
+	}
+	const palette = parsed.find((item) => item.type === "PLTE");
+	if (palette !== undefined) {
+		if ([0, 4].includes(meta.colorType)) {
+			throw new PngDecodeError("PNG_FORMAT_UNSUPPORTED", "PLTE is forbidden for grayscale");
+		}
+		if (palette.data.length === 0 || palette.data.length % 3 !== 0 || palette.data.length > 256 * 3) {
+			throw new PngDecodeError("PNG_FORMAT_UNSUPPORTED", "PLTE length is invalid");
+		}
+	}
+	if (types.slice(idatStart, idatEnd + 1).some((type) => type !== "IDAT")) {
+		throw new PngDecodeError("PNG_CHUNK_ORDER_INVALID", "IDAT chunks must be contiguous");
+	}
+	if (parsed.at(-1)?.data.length !== 0) throw new PngDecodeError("PNG_CHUNK_ORDER_INVALID", "IEND must be empty");
+	if (types.includes("tRNS")) throw new PngDecodeError("PNG_FORMAT_UNSUPPORTED", "tRNS transparency");
+	const idat = parsed.filter((item) => item.type === "IDAT");
+	if (idat.length === 0) throw new PngDecodeError("PNG_DATA_INVALID", "missing IDAT");
+	const expected = meta.height * (meta.width * meta.channels + 1);
+	if (expected > MAX_DECODED_BYTES) throw new PngDecodeError("PNG_RESOURCE_LIMIT", "decoded bytes exceed 256 MiB");
+	const rgbaBytes = meta.width * meta.height * 4;
+	const compressedBytes = idat.reduce((total, item) => total + item.data.length, 0);
+	const rowBytes = meta.width * meta.channels;
+	const peakAllocation = buffer.length + compressedBytes + expected + rgbaBytes + rowBytes * 2;
+	if (peakAllocation > MAX_TOTAL_ALLOCATION) {
+		throw new PngDecodeError("PNG_RESOURCE_LIMIT", "total allocation exceeds 256 MiB");
+	}
+	let inflated;
+	try {
+		inflated = inflateSync(Buffer.concat(idat.map((item) => item.data)), { maxOutputLength: expected });
+	} catch (error) {
+		throw new PngDecodeError("PNG_DATA_INVALID", error instanceof Error ? error.message : String(error));
+	}
+	const pixels = rgbaFromRows(inflated, meta);
+	return {
+		width: meta.width,
+		height: meta.height,
+		rgba: pixels.rgba,
+		hasAlphaChannel: meta.colorType === 4 || meta.colorType === 6,
+		hasTransparentPixels: pixels.transparent,
+	};
+}