byte-codec 1.3.0 → 1.4.0

package/README.md

@@ -42,16 +42,16 @@ To run a single test file, pass its path to vitest directly, e.g. `pnpm exec vit
 
 ## What it provides
 
-| Module             | Exports                                                                                                     |
-| ------------------ | ----------------------------------------------------------------------------------------------------------- |
-| `bytes/writer`     | `ByteWriter` (chunked growable byte-output builder), `concatBytes`                                          |
-| `bytes/reader`     | `ByteReader` (sequential big/little-endian byte reader), `isAsciiWhitespace`                                |
-| `bytes/crc32`      | `crc32` (IEEE 802.3 / ZIP / PNG polynomial table-driven CRC-32)                                             |
-| `bytes/flate`      | `deflate`, `inflate`, `inflateTolerant` (fflate-backed DEFLATE compression/decompression with a safety cap) |
-| `image/png-encode` | `encodePng` (raw RGB/RGBA pixels → PNG bytes)                                                               |
-| `image/png-decode` | `decodePng` (PNG bytes → raw pixels), `RawImage`                                                            |
-| `image/png-filter` | `filterScanlines`, `unfilterScanlines` (the five PNG scanline filters)                                      |
-| `image/jpeg-info`  | `readJpegInfo` (JPEG header reader: dimensions, components, progressive flag — no sample decoding)          |
+| Module             | Exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `bytes/writer`     | `ByteWriter` (chunked growable byte-output builder), `concatBytes`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `bytes/reader`     | `ByteReader` (sequential big/little-endian byte reader), `isAsciiWhitespace`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `bytes/crc32`      | `crc32` (IEEE 802.3 / ZIP / PNG polynomial table-driven CRC-32)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `bytes/flate`      | `deflate`, `inflate`, `inflateTolerant` (fflate-backed DEFLATE compression/decompression with a safety cap)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `image/png-encode` | `encodePng` (raw RGB/RGBA pixels → PNG bytes; a truecolour source image whose pixels reduce to 256 or fewer distinct colours is encoded both as indexed colour, PNG colour type 3 with a PLTE and, where needed, a tRNS chunk, and as plain truecolour, and whichever comes out smaller is returned -- indexed colour wins for the large flat-colour images typical of diagrams and screenshots, but the PLTE/tRNS chunk overhead can make it larger for small images, so the encoder measures rather than assumes, at the cost of a full second encode for every eligible image; throws if either `width` or `height` is not a positive integer no greater than the PNG spec's own IHDR limit, or if their product exceeds a practical per-call pixel-count ceiling, since PNG's IHDR chunk has no valid encoding for zero, negative, fractional, or non-finite dimensions and this bounds an otherwise-unbounded encode to a fixed worst case) |
+| `image/png-decode` | `decodePng` (PNG bytes → raw pixels, handling every PNG colour type including indexed/palette via its own PLTE/tRNS lookup), `RawImage`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `image/png-filter` | `filterScanlines`, `unfilterScanlines` (the five PNG scanline filters)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `image/jpeg-info`  | `readJpegInfo` (JPEG header reader: dimensions, components, progressive flag — no sample decoding)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 ## Conventions
 

package/dist/index.cjs

@@ -258,6 +258,9 @@ const PNG_SIGNATURE$1 = new Uint8Array([
 	26,
 	10
 ]);
+const MAX_PALETTE_ENTRIES = 256;
+const PNG_MAX_DIMENSION = 2147483647;
+const PNG_MAX_PIXELS = 1e8;
 function u32be(value) {
 	const bytes = /* @__PURE__ */ new Uint8Array(4);
 	new DataView(bytes.buffer).setUint32(0, value);
@@ -270,11 +273,73 @@ function writeChunk(writer, type, data) {
 	writer.writeBytes(data);
 	writer.writeBytes(u32be(crc32(concatBytes([typeBytes, data]))));
 }
+function writeIhdr(writer, width, height, colorType) {
+	const ihdr = /* @__PURE__ */ new Uint8Array(13);
+	const ihdrView = new DataView(ihdr.buffer);
+	ihdrView.setUint32(0, width);
+	ihdrView.setUint32(4, height);
+	ihdr[8] = 8;
+	ihdr[9] = colorType;
+	ihdr[10] = 0;
+	ihdr[11] = 0;
+	ihdr[12] = 0;
+	writeChunk(writer, "IHDR", ihdr);
+}
 function colorTypeFor(image) {
 	if (image.channels === 1) return image.alpha === void 0 ? 0 : 4;
 	return image.alpha === void 0 ? 2 : 6;
 }
-function encodePng(image, options = {}) {
+function detectPalette(image) {
+	const { width, height, data, alpha } = image;
+	const pixelCount = width * height;
+	const colorToIndex = /* @__PURE__ */ new Map();
+	const indices = new Uint8Array(pixelCount);
+	const paletteRgb = [];
+	const paletteAlpha = [];
+	for (let i = 0; i < pixelCount; i++) {
+		const base = i * 3;
+		const r = data[base] ?? 0;
+		const g = data[base + 1] ?? 0;
+		const b = data[base + 2] ?? 0;
+		const a = alpha === void 0 ? 255 : alpha[i] ?? 0;
+		const key = r + g * 256 + b * 65536 + a * 16777216;
+		let index = colorToIndex.get(key);
+		if (index === void 0) {
+			if (colorToIndex.size >= MAX_PALETTE_ENTRIES) return;
+			index = colorToIndex.size;
+			colorToIndex.set(key, index);
+			paletteRgb.push(r, g, b);
+			paletteAlpha.push(a);
+		}
+		indices[i] = index;
+	}
+	const palette = Uint8Array.from(paletteRgb);
+	if (alpha === void 0) return {
+		indices,
+		palette
+	};
+	let trnsLength = paletteAlpha.length;
+	while (trnsLength > 1 && paletteAlpha[trnsLength - 1] === 255) trnsLength--;
+	return {
+		indices,
+		palette,
+		trns: Uint8Array.from(paletteAlpha.slice(0, trnsLength))
+	};
+}
+function buildPng(writeBody) {
+	const writer = new ByteWriter();
+	writer.writeBytes(PNG_SIGNATURE$1);
+	writeBody(writer);
+	writeChunk(writer, "IEND", /* @__PURE__ */ new Uint8Array(0));
+	return writer.toBytes();
+}
+function writeIndexedPng(writer, width, height, encoding, options) {
+	writeIhdr(writer, width, height, 3);
+	writeChunk(writer, "PLTE", encoding.palette);
+	if (encoding.trns !== void 0) writeChunk(writer, "tRNS", encoding.trns);
+	writeChunk(writer, "IDAT", deflate(filterScanlines(encoding.indices, height, width, 1, options.filter ?? "adaptive")));
+}
+function writeTruecolorPng(writer, image, options) {
 	const { width, height, channels, data, alpha } = image;
 	const outChannels = alpha === void 0 ? channels : channels + 1;
 	const bytesPerRow = width * outChannels;
@@ -286,22 +351,24 @@ function encodePng(image, options = {}) {
 		for (let c = 0; c < channels; c++) interleaved[dstBase + c] = data[srcBase + c];
 		if (alpha !== void 0) interleaved[dstBase + channels] = alpha[i];
 	}
-	const compressed = deflate(filterScanlines(interleaved, height, bytesPerRow, outChannels, options.filter ?? "adaptive"));
-	const ihdr = /* @__PURE__ */ new Uint8Array(13);
-	const ihdrView = new DataView(ihdr.buffer);
-	ihdrView.setUint32(0, width);
-	ihdrView.setUint32(4, height);
-	ihdr[8] = 8;
-	ihdr[9] = colorTypeFor(image);
-	ihdr[10] = 0;
-	ihdr[11] = 0;
-	ihdr[12] = 0;
-	const writer = new ByteWriter();
-	writer.writeBytes(PNG_SIGNATURE$1);
-	writeChunk(writer, "IHDR", ihdr);
-	writeChunk(writer, "IDAT", compressed);
-	writeChunk(writer, "IEND", /* @__PURE__ */ new Uint8Array(0));
-	return writer.toBytes();
+	writeIhdr(writer, width, height, colorTypeFor(image));
+	writeChunk(writer, "IDAT", deflate(filterScanlines(interleaved, height, bytesPerRow, outChannels, options.filter ?? "adaptive")));
+}
+function encodePng(image, options = {}) {
+	if (!Number.isInteger(image.width) || image.width <= 0 || image.width > 2147483647 || !Number.isInteger(image.height) || image.height <= 0 || image.height > 2147483647) throw new Error(`cannot encode a PNG with an invalid dimension (width=${image.width}, height=${image.height}); the PNG spec's IHDR section requires both width and height to be positive integers no greater than ${PNG_MAX_DIMENSION}`);
+	const pixelCount = image.width * image.height;
+	if (pixelCount > 1e8) throw new Error(`cannot encode a PNG with ${pixelCount} pixels (width=${image.width}, height=${image.height}); each dimension is individually within the PNG spec's own limit, but this encoder bounds their product to ${PNG_MAX_PIXELS} to avoid an unbounded per-pixel scan and allocation`);
+	const paletteEncoding = image.channels === 3 ? detectPalette(image) : void 0;
+	if (paletteEncoding === void 0) return buildPng((writer) => {
+		writeTruecolorPng(writer, image, options);
+	});
+	const indexed = buildPng((writer) => {
+		writeIndexedPng(writer, image.width, image.height, paletteEncoding, options);
+	});
+	const truecolor = buildPng((writer) => {
+		writeTruecolorPng(writer, image, options);
+	});
+	return indexed.length <= truecolor.length ? indexed : truecolor;
 }
 //#endregion
 //#region src/image/png-decode.ts
@@ -550,6 +617,8 @@ function readJpegInfo(bytes) {
 exports.ByteReader = ByteReader;
 exports.ByteWriter = ByteWriter;
 exports.MAX_INFLATE_OUTPUT_BYTES = MAX_INFLATE_OUTPUT_BYTES;
+exports.PNG_MAX_DIMENSION = PNG_MAX_DIMENSION;
+exports.PNG_MAX_PIXELS = PNG_MAX_PIXELS;
 exports.concatBytes = concatBytes;
 exports.crc32 = crc32;
 exports.decodePng = decodePng;

package/dist/index.d.cts

@@ -57,6 +57,8 @@ interface PngDecodeOptions {
 declare function decodePng(bytes: Uint8Array<ArrayBuffer>, options?: PngDecodeOptions): RawImage;
 //#endregion
 //#region src/image/png-encode.d.ts
+declare const PNG_MAX_DIMENSION = 2147483647;
+declare const PNG_MAX_PIXELS = 100000000;
 interface PngEncodeOptions {
   readonly filter?: "none" | "adaptive";
 }
@@ -78,4 +80,4 @@ interface JpegInfo {
 }
 declare function readJpegInfo(bytes: Uint8Array<ArrayBuffer>): JpegInfo;
 //#endregion
-export { ByteReader, ByteWriter, DeflateLevel, InflateResult, JpegInfo, MAX_INFLATE_OUTPUT_BYTES, PngDecodeOptions, PngEncodeOptions, PngFilterType, RawImage, concatBytes, crc32, decodePng, deflate, encodePng, filterScanlines, inflate, inflateTolerant, isAsciiWhitespace, readJpegInfo, unfilterScanlines };
+export { ByteReader, ByteWriter, DeflateLevel, InflateResult, JpegInfo, MAX_INFLATE_OUTPUT_BYTES, PNG_MAX_DIMENSION, PNG_MAX_PIXELS, PngDecodeOptions, PngEncodeOptions, PngFilterType, RawImage, concatBytes, crc32, decodePng, deflate, encodePng, filterScanlines, inflate, inflateTolerant, isAsciiWhitespace, readJpegInfo, unfilterScanlines };

package/dist/index.d.ts

@@ -57,6 +57,8 @@ interface PngDecodeOptions {
 declare function decodePng(bytes: Uint8Array<ArrayBuffer>, options?: PngDecodeOptions): RawImage;
 //#endregion
 //#region src/image/png-encode.d.ts
+declare const PNG_MAX_DIMENSION = 2147483647;
+declare const PNG_MAX_PIXELS = 100000000;
 interface PngEncodeOptions {
   readonly filter?: "none" | "adaptive";
 }
@@ -78,4 +80,4 @@ interface JpegInfo {
 }
 declare function readJpegInfo(bytes: Uint8Array<ArrayBuffer>): JpegInfo;
 //#endregion
-export { ByteReader, ByteWriter, DeflateLevel, InflateResult, JpegInfo, MAX_INFLATE_OUTPUT_BYTES, PngDecodeOptions, PngEncodeOptions, PngFilterType, RawImage, concatBytes, crc32, decodePng, deflate, encodePng, filterScanlines, inflate, inflateTolerant, isAsciiWhitespace, readJpegInfo, unfilterScanlines };
+export { ByteReader, ByteWriter, DeflateLevel, InflateResult, JpegInfo, MAX_INFLATE_OUTPUT_BYTES, PNG_MAX_DIMENSION, PNG_MAX_PIXELS, PngDecodeOptions, PngEncodeOptions, PngFilterType, RawImage, concatBytes, crc32, decodePng, deflate, encodePng, filterScanlines, inflate, inflateTolerant, isAsciiWhitespace, readJpegInfo, unfilterScanlines };

package/dist/index.js

@@ -257,6 +257,9 @@ const PNG_SIGNATURE$1 = new Uint8Array([
 	26,
 	10
 ]);
+const MAX_PALETTE_ENTRIES = 256;
+const PNG_MAX_DIMENSION = 2147483647;
+const PNG_MAX_PIXELS = 1e8;
 function u32be(value) {
 	const bytes = /* @__PURE__ */ new Uint8Array(4);
 	new DataView(bytes.buffer).setUint32(0, value);
@@ -269,11 +272,73 @@ function writeChunk(writer, type, data) {
 	writer.writeBytes(data);
 	writer.writeBytes(u32be(crc32(concatBytes([typeBytes, data]))));
 }
+function writeIhdr(writer, width, height, colorType) {
+	const ihdr = /* @__PURE__ */ new Uint8Array(13);
+	const ihdrView = new DataView(ihdr.buffer);
+	ihdrView.setUint32(0, width);
+	ihdrView.setUint32(4, height);
+	ihdr[8] = 8;
+	ihdr[9] = colorType;
+	ihdr[10] = 0;
+	ihdr[11] = 0;
+	ihdr[12] = 0;
+	writeChunk(writer, "IHDR", ihdr);
+}
 function colorTypeFor(image) {
 	if (image.channels === 1) return image.alpha === void 0 ? 0 : 4;
 	return image.alpha === void 0 ? 2 : 6;
 }
-function encodePng(image, options = {}) {
+function detectPalette(image) {
+	const { width, height, data, alpha } = image;
+	const pixelCount = width * height;
+	const colorToIndex = /* @__PURE__ */ new Map();
+	const indices = new Uint8Array(pixelCount);
+	const paletteRgb = [];
+	const paletteAlpha = [];
+	for (let i = 0; i < pixelCount; i++) {
+		const base = i * 3;
+		const r = data[base] ?? 0;
+		const g = data[base + 1] ?? 0;
+		const b = data[base + 2] ?? 0;
+		const a = alpha === void 0 ? 255 : alpha[i] ?? 0;
+		const key = r + g * 256 + b * 65536 + a * 16777216;
+		let index = colorToIndex.get(key);
+		if (index === void 0) {
+			if (colorToIndex.size >= MAX_PALETTE_ENTRIES) return;
+			index = colorToIndex.size;
+			colorToIndex.set(key, index);
+			paletteRgb.push(r, g, b);
+			paletteAlpha.push(a);
+		}
+		indices[i] = index;
+	}
+	const palette = Uint8Array.from(paletteRgb);
+	if (alpha === void 0) return {
+		indices,
+		palette
+	};
+	let trnsLength = paletteAlpha.length;
+	while (trnsLength > 1 && paletteAlpha[trnsLength - 1] === 255) trnsLength--;
+	return {
+		indices,
+		palette,
+		trns: Uint8Array.from(paletteAlpha.slice(0, trnsLength))
+	};
+}
+function buildPng(writeBody) {
+	const writer = new ByteWriter();
+	writer.writeBytes(PNG_SIGNATURE$1);
+	writeBody(writer);
+	writeChunk(writer, "IEND", /* @__PURE__ */ new Uint8Array(0));
+	return writer.toBytes();
+}
+function writeIndexedPng(writer, width, height, encoding, options) {
+	writeIhdr(writer, width, height, 3);
+	writeChunk(writer, "PLTE", encoding.palette);
+	if (encoding.trns !== void 0) writeChunk(writer, "tRNS", encoding.trns);
+	writeChunk(writer, "IDAT", deflate(filterScanlines(encoding.indices, height, width, 1, options.filter ?? "adaptive")));
+}
+function writeTruecolorPng(writer, image, options) {
 	const { width, height, channels, data, alpha } = image;
 	const outChannels = alpha === void 0 ? channels : channels + 1;
 	const bytesPerRow = width * outChannels;
@@ -285,22 +350,24 @@ function encodePng(image, options = {}) {
 		for (let c = 0; c < channels; c++) interleaved[dstBase + c] = data[srcBase + c];
 		if (alpha !== void 0) interleaved[dstBase + channels] = alpha[i];
 	}
-	const compressed = deflate(filterScanlines(interleaved, height, bytesPerRow, outChannels, options.filter ?? "adaptive"));
-	const ihdr = /* @__PURE__ */ new Uint8Array(13);
-	const ihdrView = new DataView(ihdr.buffer);
-	ihdrView.setUint32(0, width);
-	ihdrView.setUint32(4, height);
-	ihdr[8] = 8;
-	ihdr[9] = colorTypeFor(image);
-	ihdr[10] = 0;
-	ihdr[11] = 0;
-	ihdr[12] = 0;
-	const writer = new ByteWriter();
-	writer.writeBytes(PNG_SIGNATURE$1);
-	writeChunk(writer, "IHDR", ihdr);
-	writeChunk(writer, "IDAT", compressed);
-	writeChunk(writer, "IEND", /* @__PURE__ */ new Uint8Array(0));
-	return writer.toBytes();
+	writeIhdr(writer, width, height, colorTypeFor(image));
+	writeChunk(writer, "IDAT", deflate(filterScanlines(interleaved, height, bytesPerRow, outChannels, options.filter ?? "adaptive")));
+}
+function encodePng(image, options = {}) {
+	if (!Number.isInteger(image.width) || image.width <= 0 || image.width > 2147483647 || !Number.isInteger(image.height) || image.height <= 0 || image.height > 2147483647) throw new Error(`cannot encode a PNG with an invalid dimension (width=${image.width}, height=${image.height}); the PNG spec's IHDR section requires both width and height to be positive integers no greater than ${PNG_MAX_DIMENSION}`);
+	const pixelCount = image.width * image.height;
+	if (pixelCount > 1e8) throw new Error(`cannot encode a PNG with ${pixelCount} pixels (width=${image.width}, height=${image.height}); each dimension is individually within the PNG spec's own limit, but this encoder bounds their product to ${PNG_MAX_PIXELS} to avoid an unbounded per-pixel scan and allocation`);
+	const paletteEncoding = image.channels === 3 ? detectPalette(image) : void 0;
+	if (paletteEncoding === void 0) return buildPng((writer) => {
+		writeTruecolorPng(writer, image, options);
+	});
+	const indexed = buildPng((writer) => {
+		writeIndexedPng(writer, image.width, image.height, paletteEncoding, options);
+	});
+	const truecolor = buildPng((writer) => {
+		writeTruecolorPng(writer, image, options);
+	});
+	return indexed.length <= truecolor.length ? indexed : truecolor;
 }
 //#endregion
 //#region src/image/png-decode.ts
@@ -546,4 +613,4 @@ function readJpegInfo(bytes) {
 	throw new Error("no SOF marker found in JPEG file");
 }
 //#endregion
-export { ByteReader, ByteWriter, MAX_INFLATE_OUTPUT_BYTES, concatBytes, crc32, decodePng, deflate, encodePng, filterScanlines, inflate, inflateTolerant, isAsciiWhitespace, readJpegInfo, unfilterScanlines };
+export { ByteReader, ByteWriter, MAX_INFLATE_OUTPUT_BYTES, PNG_MAX_DIMENSION, PNG_MAX_PIXELS, concatBytes, crc32, decodePng, deflate, encodePng, filterScanlines, inflate, inflateTolerant, isAsciiWhitespace, readJpegInfo, unfilterScanlines };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byte-codec",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Generic byte-level primitives (ByteWriter, ByteReader, CRC-32, deflate/inflate) and PNG/JPEG image encoding/decoding with zero PDF knowledge — the shared utility package for the documents.js family.",
   "type": "module",
   "repository": {