pdf-raster-cpu 0.0.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Mearman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# pdf-raster-cpu
+
+[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/documents.js/tree/main/packages/pdf-raster-cpu) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/pdf-raster-cpu) [![npm version](https://img.shields.io/npm/v/pdf-raster-cpu)](https://www.npmjs.com/package/pdf-raster-cpu) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/documents.js/ci.yml?branch=main)](https://github.com/ExaDev/documents.js/actions)
+
+> The pure-software reference backend for [pdf-codec](../pdf-codec/README.md)'s `PageRasteriser` port ([#1198](https://github.com/ExaDev/documents.js/issues/1198)): renders a PDF page, or one located region of one, to PNG bytes with a scanline rasteriser that has no canvas dependency at all and runs identically under Node, a browser Worker, and workerd.
+
+`pdf-codec`'s `renderPdfPage` defines the contract — it walks a page's content through the same read machinery `readPdf` runs and drives a caller-supplied rasteriser with device-space draw operations — and deliberately does not pick an implementation. This package is the family's own answer: correct and deterministic first, fast second. It exists so a consumer that needs pixels (OCR input, a vision model, a thumbnail) can get them on any runtime with nothing but `pdf-codec` and arithmetic; a runtime with a real canvas (a browser, or Cloudflare Browser Rendering) supplies its own backend through the same port and none of this code ships.
+
+```mermaid
+graph TD
+    bytecodec("byte-codec")
+    pdfcodec("pdf-codec")
+    cpuraster("pdf-raster-cpu")
+
+    bytecodec --> pdfcodec
+    pdfcodec --> cpuraster
+    bytecodec --> cpuraster
+
+    click bytecodec "https://github.com/ExaDev/documents.js/tree/main/packages/byte-codec" "byte-codec"
+    click pdfcodec "https://github.com/ExaDev/documents.js/tree/main/packages/pdf-codec" "pdf-codec"
+    click cpuraster "https://github.com/ExaDev/documents.js/tree/main/packages/pdf-raster-cpu" "pdf-raster-cpu"
+
+    style cpuraster fill:#f9a825,stroke:#333,stroke-width:3px
+```
+
+## Getting started
+
+Requires Node.js `>=20` and pnpm `11.6.0` (pinned via `packageManager` in `package.json`).
+
+```sh
+pnpm install
+pnpm build         # tsdown (ESM + CJS + .d.ts)
+pnpm typecheck     # tsc -p tsconfig.json + tsconfig.node.json
+pnpm lint          # eslint . --fix --cache --max-warnings 0
+pnpm test          # vitest run
+pnpm test:workers  # vitest run --config vitest.workers.config.ts, inside a real Cloudflare Workers (workerd) isolate
+```
+
+Rendering a page:
+
+```ts
+import { renderPdfPage } from "pdf-codec/raster";
+import { createCpuRasteriser } from "pdf-raster-cpu";
+
+const pngBytes = renderPdfPage(
+  pdfBytes,
+  0, // page index
+  { dpi: 200 }, // or { scale: 2 }; exactly one of the two
+  createCpuRasteriser(),
+);
+
+// Just a located figure region, in the same point coordinates
+// segmentPdfRegions' bounds (and LayoutFrame) use:
+const figurePng = renderPdfPage(
+  pdfBytes,
+  0,
+  {
+    dpi: 200,
+    clipPt: {
+      xPt: region.bounds.xPt,
+      yPt: region.bounds.yPt,
+      widthPt: region.bounds.widthPt,
+      heightPt: region.bounds.heightPt,
+    },
+  },
+  createCpuRasteriser(),
+);
+```
+
+One `CpuRasteriser` instance renders any number of pages sequentially — `renderPdfPage` drives it `beginPage` → `draw` … → `finish` per page, and each page starts from a cleared canvas. The factory also takes this backend's own options:
+
+```ts
+import { createCpuRasteriser } from "pdf-raster-cpu";
+
+const rasteriser = createCpuRasteriser({
+  onDiagnostic: (d) => console.warn(d.code, d.message),
+  // "raster-cpu/jpeg-image-undecoded" -- the one refusal this backend
+  // reports: a JPEG image op, which it declines rather than misrenders
+});
+```
+
+## What renders and what refuses
+
+Everything below is pinned by tests on decoded output pixels, not on intermediate structures.
+
+- **Rectangle fills** paint with exact analytic coverage: for an axis-aligned rectangle each pixel's covered fraction is computable in closed form, so crisp table rules on integer boundaries paint whole pixels and fractional edges blend at exactly their overlap fraction — slightly more accurate than any supersample could state.
+- **Vector paths** (arbitrary curves, ellipses, chart lines, and every glyph outline) fill through a sub-scanline sweep at 4×4 supersamples per pixel (a 1/16 coverage quantum), honouring both winding rules across all of a path's subpaths at once — the same pass that makes an evenodd hole a hole makes overlapping stroke pieces union rather than double-paint.
+- **Strokes** render as geometry: each flattened centreline segment becomes an offset quad, each join the wedge that fills the notch on the outside of the turn — a miter (PDF's own default limit, 10.0) that falls back to a bevel past it — with butt caps, width-relative dash arrays exactly as the port recovers them, and a zero-width stroke clamped to one device pixel per the format's own "thinnest possible width" rule. The port converts dotted strokes to filled squares before they arrive, so no round-cap primitive is ever needed. One documented approximation: a join landing exactly on a dash boundary takes the boundary's butt ends rather than its wedge, a sub-stroke-width difference at dash scale.
+- **Images** sample bilinearly under their own placement quad's coverage, so a rotated placement antialiases exactly like every other edge. PNG image ops (everything the port decoded) draw through byte-codec's decoder, cached per page by content. **JPEG (DCTDecode) image ops are declined by name** — `raster-cpu/jpeg-image-undecoded` through `onDiagnostic` — because byte-codec carries no DCT decoder and approximating a scan's pixels would silently misrender it. A canvas-owning backend draws these natively instead; the compressed bytes remain available through the port's op (and through `readPdf`'s image recovery) for consumers that want them.
+- **Text** arrives from the port already resolved: each run's embedded TrueType outlines as filled path ops, placed at the run's own text matrices. Faces that state no sfnt outlines (CFF programs, standard-14 faces with nothing embedded, Type 3 glyph procedures) are refused by the port itself, through pdf-codec's own sink (`raster/text-cff-outlines`, `raster/text-outlines-unavailable`), never approximated here.
+
+## Runtime boundaries
+
+- **Worker-isomorphic**: published `src/` imports no `node:*` builtins, no `Buffer`, no DOM, no canvas, and makes no network calls — enforced by the same lint rule every foundation package in this workspace opts into and proved at runtime by a workerd test suite that renders a page inside a real Cloudflare Workers isolate and asserts the node suite's own pinned pixels. No OCR, no vision, anywhere: this package hands a caller pixels and stops.
+- **Deterministic**: the supersample factor is a fixed constant, curve flattening is a tolerance-bounded recursion, and every blend rounds once — so two renders of the same page produce byte-identical PNGs on every runtime, which the workerd suite pins directly.
+- **Opaque white background**: a PDF page is notionally painted on white and the port deliberately specifies no background, so this backend clears each canvas to opaque white (what a viewer displays). Output PNGs therefore carry colour channels only — there is no alpha to encode, since source-over compositing onto an opaque base stays opaque.
+- **Correct before fast**: a page of text at OCR-friendly 150–300 dpi renders in seconds, not milliseconds; the coverage passes visit every pixel row a shape touches. A runtime with a hardware-accelerated canvas should wrap it as its own backend through the same port rather than tolerate this one's speed.
+
+## Conventions
+
+- Worker-isomorphic (see [the family-wide convention](../../README.md#conventions)); `isomorphic: true` in `packageLintConfig`, with a `test:workers` suite proving it at runtime.
+- No non-null assertions, no type assertions: this package is new enough to hold none of the indexed-access debt the older packages carry a burn-down exemption for.
+- Conventional commits, enforced via commitlint + husky, workspace-wide.
+
+## Install
+
+```sh
+pnpm add pdf-raster-cpu
+# or
+npm install pdf-raster-cpu
+```
+
+Peer expectations: `pdf-codec` (the port this implements) and `byte-codec` (the PNG codec) are declared as ordinary pinned dependencies — install this package and they arrive with it.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,563 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let byte_codec = require("byte-codec");
+var CoverageMask = class {
+	widthPx;
+	heightPx;
+	counts;
+	constructor(widthPx, heightPx) {
+		this.widthPx = widthPx;
+		this.heightPx = heightPx;
+		this.counts = new Uint16Array(widthPx * heightPx);
+	}
+	reset() {
+		this.counts.fill(0);
+	}
+	countAt(pixelIndex) {
+		return this.counts[pixelIndex] ?? 0;
+	}
+	fillPolygons(polygons, fillRule) {
+		if (polygons.length === 0) return;
+		let minY = Infinity;
+		let maxY = -Infinity;
+		for (const polygon of polygons) {
+			if (polygon.length < 3) continue;
+			for (const point of polygon) {
+				minY = Math.min(minY, point.y);
+				maxY = Math.max(maxY, point.y);
+			}
+		}
+		if (maxY <= minY) return;
+		const rowMin = Math.max(0, Math.ceil(minY * 4 - .5));
+		const rowMax = Math.min(4 * this.heightPx - 1, Math.floor(maxY * 4 - .5));
+		const crossings = [];
+		for (let row = rowMin; row <= rowMax; row++) {
+			const y = (row + .5) / 4;
+			crossings.length = 0;
+			for (const polygon of polygons) for (let i = 0; i < polygon.length; i++) {
+				const a = polygon[i];
+				const b = polygon[(i + 1) % polygon.length];
+				if (a === void 0 || b === void 0) continue;
+				if (a.y <= y === b.y <= y) continue;
+				const t = (y - a.y) / (b.y - a.y);
+				crossings.push({
+					x: a.x + t * (b.x - a.x),
+					dir: b.y > a.y ? 1 : -1
+				});
+			}
+			if (crossings.length === 0) continue;
+			crossings.sort((p, q) => p.x - q.x);
+			const pixelRowBase = Math.floor(row / 4) * this.widthPx;
+			let spanStartX;
+			let winding = 0;
+			for (const crossing of crossings) {
+				if (fillRule === "evenodd") {
+					if (spanStartX === void 0) spanStartX = crossing.x;
+					else {
+						this.markSpan(pixelRowBase, spanStartX, crossing.x);
+						spanStartX = void 0;
+					}
+					continue;
+				}
+				const previous = winding;
+				winding += crossing.dir;
+				if (previous === 0 && winding !== 0) spanStartX = crossing.x;
+				else if (spanStartX !== void 0 && winding === 0) {
+					this.markSpan(pixelRowBase, spanStartX, crossing.x);
+					spanStartX = void 0;
+				}
+			}
+		}
+	}
+	markSpan(pixelRowBase, startX, endX) {
+		if (endX <= startX) return;
+		const columnFirst = Math.max(0, Math.ceil(startX * 4 - .5));
+		const columnLast = Math.min(4 * this.widthPx - 1, Math.floor(endX * 4 - .5));
+		for (let c = columnFirst; c <= columnLast; c++) {
+			const cellIndex = pixelRowBase + Math.floor(c / 4);
+			const cell = this.counts[cellIndex];
+			if (cell !== void 0) this.counts[cellIndex] = cell + 1;
+		}
+	}
+};
+function flattenCubic(p0, c1, c2, p1) {
+	const points = [];
+	const flatten = (a, b, c, d, depth) => {
+		const chordX = d.x - a.x;
+		const chordY = d.y - a.y;
+		const chordLength = Math.hypot(chordX, chordY) || 1;
+		const dist1 = Math.abs((b.x - a.x) * chordY - (b.y - a.y) * chordX) / chordLength;
+		const dist2 = Math.abs((c.x - a.x) * chordY - (c.y - a.y) * chordX) / chordLength;
+		if (depth >= 16 || Math.max(dist1, dist2) <= .05) {
+			points.push(d);
+			return;
+		}
+		const ab = {
+			x: (a.x + b.x) / 2,
+			y: (a.y + b.y) / 2
+		};
+		const bc = {
+			x: (b.x + c.x) / 2,
+			y: (b.y + c.y) / 2
+		};
+		const cd = {
+			x: (c.x + d.x) / 2,
+			y: (c.y + d.y) / 2
+		};
+		const abc = {
+			x: (ab.x + bc.x) / 2,
+			y: (ab.y + bc.y) / 2
+		};
+		const bcd = {
+			x: (bc.x + cd.x) / 2,
+			y: (bc.y + cd.y) / 2
+		};
+		const mid = {
+			x: (abc.x + bcd.x) / 2,
+			y: (abc.y + bcd.y) / 2
+		};
+		flatten(a, ab, abc, mid, depth + 1);
+		flatten(mid, bcd, cd, d, depth + 1);
+	};
+	flatten(p0, c1, c2, p1, 0);
+	return points;
+}
+function flattenSubpath(subpath) {
+	const points = [{
+		x: subpath.startXPx,
+		y: subpath.startYPx
+	}];
+	for (const segment of subpath.segments) {
+		if (segment.kind === "line") {
+			points.push({
+				x: segment.xPx,
+				y: segment.yPx
+			});
+			continue;
+		}
+		const previous = points[points.length - 1];
+		if (previous === void 0) continue;
+		points.push(...flattenCubic(previous, {
+			x: segment.c1xPx,
+			y: segment.c1yPx
+		}, {
+			x: segment.c2xPx,
+			y: segment.c2yPx
+		}, {
+			x: segment.xPx,
+			y: segment.yPx
+		}));
+	}
+	return {
+		points,
+		closed: subpath.closed
+	};
+}
+function strokeOutlinePolygons(subpaths, widthPx, dashPx) {
+	const half = Math.max(widthPx, 1) / 2;
+	const polygons = [];
+	const emitPiece = (piece) => {
+		for (let i = 0; i + 1 < piece.length; i++) {
+			const p = piece[i];
+			const q = piece[i + 1];
+			if (p === void 0 || q === void 0) continue;
+			const d = unitDirection(p, q);
+			if (d === void 0) continue;
+			const n = {
+				x: -d.y,
+				y: d.x
+			};
+			polygons.push([
+				{
+					x: p.x + n.x * half,
+					y: p.y + n.y * half
+				},
+				{
+					x: q.x + n.x * half,
+					y: q.y + n.y * half
+				},
+				{
+					x: q.x - n.x * half,
+					y: q.y - n.y * half
+				},
+				{
+					x: p.x - n.x * half,
+					y: p.y - n.y * half
+				}
+			]);
+		}
+		for (let i = 1; i + 1 < piece.length; i++) {
+			const vertex = piece[i];
+			const before = piece[i - 1];
+			const after = piece[i + 1];
+			if (vertex === void 0 || before === void 0 || after === void 0) continue;
+			emitJoinWedge(polygons, vertex, before, after, half);
+		}
+	};
+	if (dashPx === void 0) {
+		for (const subpath of subpaths) {
+			const first = subpath.points[0];
+			if (first === void 0) continue;
+			emitPiece(subpath.closed ? [...subpath.points, first] : subpath.points);
+			if (subpath.closed && subpath.points.length >= 3) {
+				const last = subpath.points[subpath.points.length - 1];
+				const second = subpath.points[1];
+				if (last !== void 0 && second !== void 0) emitJoinWedge(polygons, first, last, second, half);
+			}
+		}
+		return polygons;
+	}
+	for (const subpath of subpaths) for (const piece of dashPolyline(subpath, dashPx)) emitPiece(piece);
+	return polygons;
+}
+function emitJoinWedge(polygons, vertex, before, after, half) {
+	const d1 = unitDirection(before, vertex);
+	const d2 = unitDirection(vertex, after);
+	if (d1 === void 0 || d2 === void 0) return;
+	const cross = d1.x * d2.y - d1.y * d2.x;
+	if (Math.abs(cross) < 1e-12) return;
+	const side = cross > 0 ? -1 : 1;
+	const n1 = {
+		x: -d1.y * side,
+		y: d1.x * side
+	};
+	const n2 = {
+		x: -d2.y * side,
+		y: d2.x * side
+	};
+	const a1 = {
+		x: vertex.x + n1.x * half,
+		y: vertex.y + n1.y * half
+	};
+	const a2 = {
+		x: vertex.x + n2.x * half,
+		y: vertex.y + n2.y * half
+	};
+	const dot = n1.x * n2.x + n1.y * n2.y;
+	const denominator = 1 + dot;
+	let wedge;
+	if (denominator > 1e-12 && miterRatio(dot) <= 10) {
+		const scale = half / denominator;
+		wedge = [
+			a1,
+			{
+				x: vertex.x + (n1.x + n2.x) * scale,
+				y: vertex.y + (n1.y + n2.y) * scale
+			},
+			a2,
+			vertex
+		];
+	} else wedge = [
+		a1,
+		vertex,
+		a2
+	];
+	polygons.push(polygonSignedArea(wedge) < 0 ? [...wedge] : [...wedge].reverse());
+}
+function miterRatio(dot) {
+	return Math.sqrt(2 + 2 * dot) / (1 + dot);
+}
+function polygonSignedArea(polygon) {
+	let area = 0;
+	for (let i = 0; i < polygon.length; i++) {
+		const a = polygon[i];
+		const b = polygon[(i + 1) % polygon.length];
+		if (a === void 0 || b === void 0) continue;
+		area += a.x * b.y - b.x * a.y;
+	}
+	return area;
+}
+function unitDirection(p, q) {
+	const dx = q.x - p.x;
+	const dy = q.y - p.y;
+	const length = Math.hypot(dx, dy);
+	if (length === 0) return;
+	return {
+		x: dx / length,
+		y: dy / length
+	};
+}
+function dashPolyline(subpath, dashPx) {
+	if (!dashPx.some((length) => length > 0)) return [];
+	const pattern = dashPx.length % 2 === 1 ? [...dashPx, ...dashPx] : dashPx;
+	const points = subpath.closed ? [...subpath.points, subpath.points[0]] : subpath.points;
+	const start = points[0];
+	if (start === void 0) return [];
+	const pieces = [];
+	const endOnPiece = () => {
+		if (current.length >= 2) pieces.push(current);
+		current = [];
+	};
+	const atBoundary = () => {
+		if (index % 2 === 0) endOnPiece();
+		for (;;) {
+			index = (index + 1) % pattern.length;
+			const entry = pattern[index];
+			if (entry !== void 0 && entry > 0) {
+				remaining = entry;
+				break;
+			}
+		}
+		if (index % 2 === 0) current = [cursor];
+	};
+	let index = 0;
+	let remaining = 0;
+	let cursor = start;
+	let current = [];
+	const firstEntry = pattern[0];
+	if (firstEntry !== void 0 && firstEntry > 0) {
+		remaining = firstEntry;
+		current = [cursor];
+	} else atBoundary();
+	for (let i = 0; i + 1 < points.length; i++) {
+		const from = points[i];
+		const to = points[i + 1];
+		if (from === void 0 || to === void 0) continue;
+		const direction = unitDirection(from, to);
+		if (direction === void 0) continue;
+		cursor = from;
+		let segmentRemaining = Math.hypot(to.x - from.x, to.y - from.y);
+		while (segmentRemaining > 0 && remaining > 0) {
+			const step = Math.min(segmentRemaining, remaining);
+			cursor = {
+				x: cursor.x + direction.x * step,
+				y: cursor.y + direction.y * step
+			};
+			segmentRemaining -= step;
+			remaining -= step;
+			if (current.length > 0) current.push(cursor);
+			if (remaining === 0) atBoundary();
+		}
+	}
+	if (current.length > 0) endOnPiece();
+	return pieces;
+}
+//#endregion
+//#region src/rasteriser.ts
+function createCpuRasteriser(options = {}) {
+	return new CpuRasteriser(options);
+}
+var CpuRasteriser = class {
+	onDiagnostic;
+	buffers;
+	decodedImages = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.onDiagnostic = options.onDiagnostic;
+	}
+	beginPage(geometry) {
+		this.buffers = {
+			geometry,
+			canvas: new Uint8Array(geometry.widthPx * geometry.heightPx * 3).fill(255),
+			mask: new CoverageMask(geometry.widthPx, geometry.heightPx)
+		};
+		this.decodedImages.clear();
+	}
+	draw(op) {
+		if (op.kind === "fillRect") {
+			this.fillRectOp(op);
+			return;
+		}
+		if (op.kind === "path") {
+			this.pathOp(op);
+			return;
+		}
+		this.imageOp(op);
+	}
+	finish() {
+		const { geometry, canvas } = this.requirePage("finish");
+		const png = (0, byte_codec.encodePng)({
+			width: geometry.widthPx,
+			height: geometry.heightPx,
+			channels: 3,
+			data: canvas
+		});
+		this.buffers = void 0;
+		return png;
+	}
+	requirePage(operation) {
+		if (this.buffers === void 0) throw new Error(`CpuRasteriser.${operation}() was called before beginPage(); renderPdfPage (or the caller) drives one page at a time through beginPage, draw..., finish`);
+		return this.buffers;
+	}
+	fillRectOp(op) {
+		const { geometry, canvas } = this.requirePage("draw");
+		const left = Math.max(op.xPx, 0);
+		const right = Math.min(op.xPx + op.widthPx, geometry.widthPx);
+		const top = Math.max(op.yPx, 0);
+		const bottom = Math.min(op.yPx + op.heightPx, geometry.heightPx);
+		if (right <= left || bottom <= top) return;
+		const colour = colourBytes(op.color);
+		const columnStart = Math.floor(left);
+		const columnEnd = Math.ceil(right);
+		const rowStart = Math.floor(top);
+		const rowEnd = Math.ceil(bottom);
+		for (let row = rowStart; row < rowEnd; row++) {
+			const coverageY = pixelOverlap(row, top, bottom);
+			if (coverageY === 0) continue;
+			const rowBase = row * geometry.widthPx;
+			for (let column = columnStart; column < columnEnd; column++) {
+				const coverage = coverageY * pixelOverlap(column, left, right);
+				if (coverage === 0) continue;
+				this.blendPixel(canvas, rowBase + column, colour, coverage);
+			}
+		}
+	}
+	pathOp(op) {
+		const { canvas, mask } = this.requirePage("draw");
+		const flattened = op.subpaths.map(flattenSubpath);
+		if (op.fill !== void 0) {
+			const polygons = flattened.map((subpath) => subpath.points).filter((points) => points.length >= 3);
+			mask.reset();
+			mask.fillPolygons(polygons, op.fill.fillRule);
+			this.blendMask(canvas, mask, op.fill.color);
+		}
+		if (op.stroke !== void 0) {
+			const polygons = strokeOutlinePolygons(flattened, op.stroke.widthPx, op.stroke.dashPx);
+			mask.reset();
+			mask.fillPolygons(polygons, "nonzero");
+			this.blendMask(canvas, mask, op.stroke.color);
+		}
+	}
+	imageOp(op) {
+		const { geometry, canvas, mask } = this.requirePage("draw");
+		if (op.format === "jpeg") {
+			this.onDiagnostic?.({
+				code: "raster-cpu/jpeg-image-undecoded",
+				message: "a JPEG (DCTDecode) image placement was not drawn: this backend decodes PNG images only (byte-codec has no DCT decoder), and approximating the scan's pixels would misrender it; the op's bytes remain available to the caller through the port"
+			});
+			return;
+		}
+		const source = this.decodeCached(op.bytes);
+		const quad = quadCorners(op.matrix);
+		mask.reset();
+		mask.fillPolygons([quad], "nonzero");
+		const inverse = invertMatrix(op.matrix);
+		const rowStart = Math.max(0, Math.floor(Math.min(...quad.map((corner) => corner.y))));
+		const rowEnd = Math.min(geometry.heightPx, Math.ceil(Math.max(...quad.map((corner) => corner.y))));
+		const columnStart = Math.max(0, Math.floor(Math.min(...quad.map((corner) => corner.x))));
+		const columnEnd = Math.min(geometry.widthPx, Math.ceil(Math.max(...quad.map((corner) => corner.x))));
+		for (let row = rowStart; row < rowEnd; row++) {
+			const rowBase = row * geometry.widthPx;
+			for (let column = columnStart; column < columnEnd; column++) {
+				const samples = mask.countAt(rowBase + column);
+				if (samples === 0) continue;
+				const [u, v] = inverse(column + .5, row + .5);
+				const [r, g, b, a] = sampleBilinear(source, u, v);
+				this.blendPixel(canvas, rowBase + column, {
+					r,
+					g,
+					b
+				}, samples / 16 * a);
+			}
+		}
+	}
+	decodeCached(bytes) {
+		const key = `${bytes.length}:${(0, byte_codec.crc32)(bytes)}`;
+		const cached = this.decodedImages.get(key);
+		if (cached !== void 0) return cached;
+		const decoded = (0, byte_codec.decodePng)(bytes);
+		this.decodedImages.set(key, decoded);
+		return decoded;
+	}
+	blendMask(canvas, mask, color) {
+		const colour = colourBytes(color);
+		const pixels = mask.widthPx * mask.heightPx;
+		for (let i = 0; i < pixels; i++) {
+			const samples = mask.countAt(i);
+			if (samples === 0) continue;
+			this.blendPixel(canvas, i, colour, samples / 16);
+		}
+	}
+	blendPixel(canvas, pixelIndex, colour, alpha) {
+		const base = pixelIndex * 3;
+		canvas[base] = Math.round((canvas[base] ?? 0) + (colour.r - (canvas[base] ?? 0)) * alpha);
+		canvas[base + 1] = Math.round((canvas[base + 1] ?? 0) + (colour.g - (canvas[base + 1] ?? 0)) * alpha);
+		canvas[base + 2] = Math.round((canvas[base + 2] ?? 0) + (colour.b - (canvas[base + 2] ?? 0)) * alpha);
+	}
+};
+function colourBytes(color) {
+	return {
+		r: Math.round(color.r * 255),
+		g: Math.round(color.g * 255),
+		b: Math.round(color.b * 255)
+	};
+}
+function pixelOverlap(index, edgeLow, edgeHigh) {
+	return Math.max(0, Math.min(index + 1, edgeHigh) - Math.max(index, edgeLow));
+}
+function quadCorners(matrix) {
+	const [a, b, c, d, e, f] = matrix;
+	const at = (u, v) => ({
+		x: a * u + c * v + e,
+		y: b * u + d * v + f
+	});
+	return [
+		at(0, 0),
+		at(1, 0),
+		at(1, 1),
+		at(0, 1)
+	];
+}
+function invertMatrix(matrix) {
+	const [a, b, c, d, e, f] = matrix;
+	const determinant = a * d - b * c;
+	return (xPx, yPx) => {
+		const dx = xPx - e;
+		const dy = yPx - f;
+		return [(d * dx - c * dy) / determinant, (-b * dx + a * dy) / determinant];
+	};
+}
+function sampleBilinear(source, u, v) {
+	const clampedU = Math.min(Math.max(u, 0), 1);
+	const clampedV = Math.min(Math.max(v, 0), 1);
+	const sx = Math.min(Math.max(clampedU * source.width - .5, 0), source.width - 1);
+	const sy = Math.min(Math.max(clampedV * source.height - .5, 0), source.height - 1);
+	const x0 = Math.floor(sx);
+	const y0 = Math.floor(sy);
+	const x1 = Math.min(x0 + 1, source.width - 1);
+	const y1 = Math.min(y0 + 1, source.height - 1);
+	const fx = sx - x0;
+	const fy = sy - y0;
+	const channelCount = source.channels === 1 ? 1 : 3;
+	const sample = (x, y, channel) => {
+		const index = (y * source.width + x) * channelCount + channel;
+		return source.data[index] ?? 0;
+	};
+	const lerpChannel = (channel) => {
+		const top0 = sample(x0, y0, channel);
+		const top1 = sample(x1, y0, channel);
+		const bottom0 = sample(x0, y1, channel);
+		const bottom1 = sample(x1, y1, channel);
+		const top = top0 + (top1 - top0) * fx;
+		return top + (bottom0 + (bottom1 - bottom0) * fx - top) * fy;
+	};
+	let r;
+	let g;
+	let b;
+	if (channelCount === 1) {
+		r = lerpChannel(0);
+		g = r;
+		b = r;
+	} else {
+		r = lerpChannel(0);
+		g = lerpChannel(1);
+		b = lerpChannel(2);
+	}
+	const alpha = source.alpha;
+	if (alpha === void 0) return [
+		r,
+		g,
+		b,
+		1
+	];
+	const alphaAt = (x, y) => alpha[y * source.width + x] ?? 0;
+	const alphaTop = alphaAt(x0, y0) + (alphaAt(x1, y0) - alphaAt(x0, y0)) * fx;
+	const alphaBottom = alphaAt(x0, y1) + (alphaAt(x1, y1) - alphaAt(x0, y1)) * fx;
+	return [
+		r,
+		g,
+		b,
+		(alphaTop + (alphaBottom - alphaTop) * fy) / 255
+	];
+}
+//#endregion
+exports.CpuRasteriser = CpuRasteriser;
+exports.createCpuRasteriser = createCpuRasteriser;