@stll/scan-engine 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# `@stll/scan-engine`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Document scan cleanup engine implemented in Rust and compiled to WebAssembly:
+deskew, content crop and grayscale or binary output for one rasterized page at
+a time, plus an engine-independent review state machine for accepting or
+rejecting the result page by page.
+
+## Usage
+
+```ts
+import { createScanEngine } from "@stll/scan-engine";
+
+const engine = createScanEngine();
+
+const result = await engine.clean(
+  {
+    pixels, // Uint8ClampedArray of RGBA pixels, e.g. ImageData.data
+    width,
+    height,
+    pageSize: { widthPoints: 595, heightPoints: 842 },
+    dpi: 150,
+    rotation: 0, // 0 | 90 | 180 | 270
+  },
+  { output: "binary", contentCrop: "on", deskew: "on" },
+);
+
+if (result.isErr()) {
+  // ScanEngineError: { type: "engine-failure" | "engine-timeout", message }
+} else if (result.value.type === "cleaned") {
+  const { image, skewDegrees, contentBox, appliedQuad } = result.value;
+  // image.pixels holds one byte per pixel (image.width × image.height).
+} else {
+  // { type: "unrecognized", reason }, e.g. "no-content" for a blank page.
+}
+```
+
+`clean` returns a `better-result` `Result` and never throws. Where `Worker`
+exists (browsers, Bun), the engine runs in a module worker that it creates on
+the first call; requests are serialized, and a request that takes longer than
+10 seconds terminates the worker and fails with `engine-timeout`. The next call
+starts a fresh worker. `createScanEngine(undefined, { requestTimeoutMs })`
+changes the timeout. `scanEngine` is a shared instance of the default engine.
+
+Options:
+
+- `output`: `"grayscale"` or `"binary"` (pixels are strictly `0` or `255`).
+- `contentCrop`: `"on"` crops to the detected content; `contentBox` gives
+  its bounds in the output image either way.
+- `deskew`: `"on"` rotates the page straight; `skewDegrees` reports the
+  detected angle, and deskewing grows the output to contain the rotated page.
+
+Types (`RasterizedScanPage`, `ScanOptions`, `CleanScanResult`, `ScanEngine`,
+`ScanEngineError`, …) are exported from `@stll/scan-engine/types`.
+
+## Review
+
+`@stll/scan-engine/review` tracks each page through `pending`, `preview`,
+`applied`, `rejected` and `unrecognized`, with undo. It works with any
+`ScanEngine`.
+
+```ts
+import {
+  applyAll,
+  applyOne,
+  createCleanScanReview,
+  rejectOne,
+  reviewPage,
+  setPageReview,
+  targetPageBox,
+  undoCleanScanReview,
+} from "@stll/scan-engine/review";
+
+let review = createCleanScanReview(["page-1", "page-2"]);
+
+const pageReview = await reviewPage({
+  engine,
+  pageId: "page-1",
+  page,
+  options,
+});
+if (pageReview.isOk()) {
+  review = setPageReview(review, pageReview.value); // preview or unrecognized
+}
+review = applyOne(review, "page-1"); // or rejectOne, or applyAll
+review = undoCleanScanReview(review);
+```
+
+Every transition returns a new review; one that changes nothing returns the
+same object and records no undo step. `targetPageBox(pageSize, rotation)`
+gives the page box, in points, to place a cleaned image into.
+
+## Bundlers
+
+The package loads `dist/scan-engine.worker.js` and
+`generated/scan_engine_bg.wasm` with `new URL(…, import.meta.url)`, so the
+bundler has to see those expressions in the installed package. Vite 8 rewrites
+them in both `vite dev` and `vite build` with no configuration. If an older
+Vite's dependency pre-bundling leaves them pointing into its cache directory
+(the worker or the `.wasm` then fails to load in `vite dev` only), exclude the
+package so the URLs resolve against its own files:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  optimizeDeps: { exclude: ["@stll/scan-engine"] },
+});
+```
+
+## Development
+
+Run `bun run build:wasm` to build the WebAssembly target and its web bindings
+(it fetches crates and the pinned `wasm-bindgen` CLI first unless
+`CARGO_NET_OFFLINE=true`). To verify the committed copy, build into a scratch
+directory and compare:
+
+```sh
+export SCAN_ENGINE_WASM_OUT_DIR="$(mktemp -d)"
+bun run build:wasm && bun run check:wasm --check
+```
+
+Generated bindings in `generated/` are committed and ship in the package next
+to `dist/`.

package/dist/review.d.ts

@@ -0,0 +1,50 @@
+import { CleanScanResult, PhysicalPageSize, RasterizedScanPage, ScanEngine, ScanEngineError, ScanOptions, ScanPageRotation } from "./types.js";
+import { Result } from "better-result";
+//#region src/review.d.ts
+type CleanedScan = Extract<CleanScanResult, {
+  type: "cleaned";
+}>;
+export type CleanScanPageReview = {
+  type: "pending";
+  pageId: string;
+} | {
+  type: "preview";
+  pageId: string;
+  scan: CleanedScan;
+} | {
+  type: "applied";
+  pageId: string;
+  scan: CleanedScan;
+} | {
+  type: "rejected";
+  pageId: string;
+  scan: CleanedScan;
+} | {
+  type: "unrecognized";
+  pageId: string;
+  reason: string;
+};
+export type CleanScanReview = {
+  pages: readonly CleanScanPageReview[];
+  past: readonly (readonly CleanScanPageReview[])[];
+};
+type ReviewPageOptions = {
+  engine: ScanEngine;
+  pageId: string;
+  page: RasterizedScanPage;
+  options: ScanOptions;
+};
+export declare const reviewPage: ({ engine, pageId, page, options }: ReviewPageOptions) => Promise<Result<CleanScanPageReview, ScanEngineError>>;
+export declare const createCleanScanReview: (pageIds: readonly string[]) => CleanScanReview;
+export declare const applyOne: (review: CleanScanReview, pageId: string) => CleanScanReview;
+export declare const applyAll: (review: CleanScanReview) => CleanScanReview;
+export declare const rejectOne: (review: CleanScanReview, pageId: string) => CleanScanReview;
+export declare const setPageReview: (review: CleanScanReview, pageReview: CleanScanPageReview) => CleanScanReview;
+export declare const undoCleanScanReview: (review: CleanScanReview) => CleanScanReview;
+export type TargetPageBox = PhysicalPageSize & {
+  xPoints: 0;
+  yPoints: 0;
+  rotation: ScanPageRotation;
+};
+export declare const targetPageBox: (pageSize: PhysicalPageSize, rotation: ScanPageRotation) => TargetPageBox;
+//#endregion

package/dist/review.js

@@ -0,0 +1,82 @@
+import { Result, panic } from "better-result";
+//#region src/review.ts
+const reviewPage = async ({ engine, pageId, page, options }) => {
+	const result = await engine.clean(page, options);
+	if (result.isErr()) return Result.err(result.error);
+	switch (result.value.type) {
+		case "cleaned": return Result.ok({
+			type: "preview",
+			pageId,
+			scan: result.value
+		});
+		case "unrecognized": return Result.ok({
+			type: "unrecognized",
+			pageId,
+			reason: result.value.reason
+		});
+		default: return panic("Unhandled scan result", result.value);
+	}
+};
+const createCleanScanReview = (pageIds) => ({
+	pages: pageIds.map((pageId) => ({
+		type: "pending",
+		pageId
+	})),
+	past: []
+});
+const applyPage = (page) => {
+	switch (page.type) {
+		case "preview": return {
+			type: "applied",
+			pageId: page.pageId,
+			scan: page.scan
+		};
+		case "pending":
+		case "applied":
+		case "rejected":
+		case "unrecognized": return page;
+		default: return panic("Unhandled clean scan review state", page);
+	}
+};
+const rejectPage = (page) => {
+	switch (page.type) {
+		case "preview": return {
+			type: "rejected",
+			pageId: page.pageId,
+			scan: page.scan
+		};
+		case "pending":
+		case "applied":
+		case "rejected":
+		case "unrecognized": return page;
+		default: return panic("Unhandled clean scan review state", page);
+	}
+};
+const recordTransition = (review, pages) => {
+	if (pages.every((page, index) => page === review.pages[index])) return review;
+	return {
+		pages,
+		past: [...review.past, review.pages]
+	};
+};
+const applyOne = (review, pageId) => recordTransition(review, review.pages.map((page) => page.pageId === pageId ? applyPage(page) : page));
+const applyAll = (review) => recordTransition(review, review.pages.map(applyPage));
+const rejectOne = (review, pageId) => recordTransition(review, review.pages.map((page) => page.pageId === pageId ? rejectPage(page) : page));
+const setPageReview = (review, pageReview) => recordTransition(review, review.pages.map((page) => page.pageId === pageReview.pageId ? pageReview : page));
+const undoCleanScanReview = (review) => {
+	const pages = review.past.at(-1);
+	if (!pages) return review;
+	return {
+		pages,
+		past: review.past.slice(0, -1)
+	};
+};
+const targetPageBox = (pageSize, rotation) => ({
+	xPoints: 0,
+	yPoints: 0,
+	widthPoints: pageSize.widthPoints,
+	heightPoints: pageSize.heightPoints,
+	rotation
+});
+//#endregion
+export { applyAll, applyOne, createCleanScanReview, rejectOne, reviewPage, setPageReview, targetPageBox, undoCleanScanReview };

package/dist/scan-engine.d.ts

@@ -0,0 +1,57 @@
+import { RasterizedScanPage, ScanEngine, ScanOptions } from "./types.js";
+//#region src/worker-protocol.d.ts
+type SerializedWasmResult = {
+  status: string;
+  reason: string;
+  pixels: Uint8Array;
+  width: number;
+  height: number;
+  skew_degrees: number;
+  /** Content bounds in the returned output image. */
+  content_box: Uint32Array;
+  /** Detected page corners in the source image, clockwise from top-left. */
+  applied_quad: Float32Array;
+};
+type WorkerRequest = {
+  page: Omit<RasterizedScanPage, "pixels">;
+  pixels: ArrayBuffer;
+  options: ScanOptions;
+};
+type WorkerResponse = {
+  type: "result";
+  result: SerializedWasmResult;
+} | {
+  type: "error";
+  errorType: "runtime-trap" | "failure";
+  message: string;
+};
+//#endregion
+//#region src/scan-engine.d.ts
+type WasmScanResult = {
+  free: () => void;
+  readonly status: string;
+  readonly reason: string;
+  readonly pixels: Uint8Array;
+  readonly width: number;
+  readonly height: number;
+  readonly skew_degrees: number;
+  readonly content_box: Uint32Array;
+  readonly applied_quad: Float32Array;
+};
+type WasmBindings = {
+  clean_scan_rgba: (...args: [width: number, height: number, pixels: Uint8Array, dpi: number, output: string, contentCrop: boolean, deskew: boolean]) => WasmScanResult;
+};
+type WasmLoader = () => Promise<WasmBindings>;
+type WorkerClient = {
+  addEventListener: (type: "message" | "error", listener: (event: MessageEvent<WorkerResponse> | ErrorEvent) => void) => void;
+  removeEventListener: (type: "message" | "error", listener: (event: MessageEvent<WorkerResponse> | ErrorEvent) => void) => void;
+  postMessage: (message: WorkerRequest, transfer: ArrayBuffer[]) => void;
+  terminate: () => void;
+};
+type WorkerEngineOptions = {
+  createWorker?: () => WorkerClient;
+  requestTimeoutMs?: number;
+};
+export declare const createScanEngine: (load?: WasmLoader, workerOptions?: WorkerEngineOptions) => ScanEngine;
+export declare const scanEngine: ScanEngine;
+//#endregion

package/dist/scan-engine.js

@@ -0,0 +1,223 @@
+import { ScanEngineError } from "./types.js";
+import { Result } from "better-result";
+import { fetchWithTimeout } from "@stll/fetch";
+import { clean_scan_rgba, initSync } from "../generated/scan_engine.js";
+//#region src/scan-engine.ts
+const WASM_LOAD_TIMEOUT_MS = 1e4;
+const WORKER_REQUEST_TIMEOUT_MS = 1e4;
+const loadWasmBindings = async () => {
+	const response = await fetchWithTimeout(new URL("../generated/scan_engine_bg.wasm", import.meta.url), { timeout: {
+		type: "idle",
+		ms: WASM_LOAD_TIMEOUT_MS
+	} });
+	const module = await WebAssembly.compile(await response.arrayBuffer());
+	initSync({ module });
+	return { clean_scan_rgba };
+};
+const createWorkerEngine = ({ createWorker = () => new Worker(new URL("scan-engine.worker.js", import.meta.url), { type: "module" }), requestTimeoutMs = WORKER_REQUEST_TIMEOUT_MS } = {}) => {
+	let worker;
+	let queue = Promise.resolve();
+	const reset = () => {
+		worker?.terminate();
+		worker = void 0;
+	};
+	const clean = async (page, options) => {
+		const run = async () => {
+			worker ??= createWorker();
+			const activeWorker = worker;
+			const pixels = page.pixels.slice().buffer;
+			const request = {
+				page: {
+					width: page.width,
+					height: page.height,
+					pageSize: page.pageSize,
+					dpi: page.dpi,
+					rotation: page.rotation
+				},
+				pixels,
+				options
+			};
+			return await new Promise((resolve, reject) => {
+				let settled = false;
+				const settle = (complete) => {
+					if (settled) return;
+					settled = true;
+					clearTimeout(timeout);
+					activeWorker.removeEventListener("message", onMessage);
+					activeWorker.removeEventListener("error", onError);
+					complete();
+				};
+				const onMessage = (event) => {
+					if (!(event instanceof MessageEvent)) return;
+					const { data } = event;
+					if (data.type === "result") {
+						settle(() => {
+							try {
+								resolve(convertResult({
+									...data.result,
+									free: () => void 0
+								}, options.output));
+							} catch (error) {
+								reject(error instanceof ScanEngineError ? error : new ScanEngineError({
+									type: "engine-failure",
+									message: "The scan engine returned an invalid result"
+								}));
+							}
+						});
+						return;
+					}
+					reset();
+					settle(() => reject(data.errorType === "runtime-trap" ? new WebAssembly.RuntimeError(data.message) : new ScanEngineError({
+						type: "engine-failure",
+						message: data.message
+					})));
+				};
+				const onError = (event) => {
+					if (!(event instanceof ErrorEvent)) return;
+					reset();
+					settle(() => reject(new ScanEngineError({
+						type: "engine-failure",
+						message: event.message
+					})));
+				};
+				const timeout = setTimeout(() => {
+					reset();
+					settle(() => reject(new ScanEngineError({
+						type: "engine-timeout",
+						message: "The scan engine request timed out"
+					})));
+				}, requestTimeoutMs);
+				activeWorker.addEventListener("message", onMessage);
+				activeWorker.addEventListener("error", onError);
+				activeWorker.postMessage(request, [pixels]);
+			});
+		};
+		const result = queue.then(run, run);
+		queue = result.then(() => void 0, () => void 0);
+		return await Result.tryPromise({
+			try: async () => await result,
+			catch: (cause) => cause instanceof ScanEngineError ? cause : new ScanEngineError({
+				type: "engine-failure",
+				message: "The scan engine could not clean the page",
+				cause
+			})
+		});
+	};
+	return { clean };
+};
+const readContentBox = (values) => {
+	const x = values.at(0);
+	const y = values.at(1);
+	const width = values.at(2);
+	const height = values.at(3);
+	if (values.length !== 4 || x === void 0 || y === void 0 || width === void 0 || height === void 0) throw new ScanEngineError({
+		type: "engine-failure",
+		message: "The scan engine returned an invalid content box"
+	});
+	return {
+		x,
+		y,
+		width,
+		height
+	};
+};
+const readQuad = (values) => {
+	if (values.length === 0) return null;
+	const coordinates = Array.from(values);
+	if (coordinates.length !== 8 || coordinates.some((value) => !Number.isFinite(value))) throw new ScanEngineError({
+		type: "engine-failure",
+		message: "The scan engine returned an invalid page quadrilateral"
+	});
+	const [x0, y0, x1, y1, x2, y2, x3, y3] = coordinates;
+	if (x0 === void 0 || y0 === void 0 || x1 === void 0 || y1 === void 0 || x2 === void 0 || y2 === void 0 || x3 === void 0 || y3 === void 0) throw new ScanEngineError({
+		type: "engine-failure",
+		message: "The scan engine returned an invalid page quadrilateral"
+	});
+	return {
+		topLeft: {
+			x: x0,
+			y: y0
+		},
+		topRight: {
+			x: x1,
+			y: y1
+		},
+		bottomRight: {
+			x: x2,
+			y: y2
+		},
+		bottomLeft: {
+			x: x3,
+			y: y3
+		}
+	};
+};
+const convertResult = (result, output) => {
+	if (result.status === "unrecognized") {
+		if (result.reason.length === 0) throw new ScanEngineError({
+			type: "engine-failure",
+			message: "The scan engine returned an unrecognized page without a reason"
+		});
+		return {
+			type: "unrecognized",
+			reason: result.reason
+		};
+	}
+	if (result.status !== "cleaned") throw new ScanEngineError({
+		type: "engine-failure",
+		message: `The scan engine returned an unknown status: ${result.status}`
+	});
+	if (result.pixels.length !== result.width * result.height) throw new ScanEngineError({
+		type: "engine-failure",
+		message: "The scan engine returned an invalid pixel buffer"
+	});
+	return {
+		type: "cleaned",
+		image: {
+			pixels: result.pixels,
+			width: result.width,
+			height: result.height,
+			format: output
+		},
+		appliedQuad: readQuad(result.applied_quad),
+		skewDegrees: result.skew_degrees,
+		contentBox: readContentBox(result.content_box)
+	};
+};
+const createScanEngine = (load, workerOptions) => {
+	if (load === void 0 && typeof Worker !== "undefined") return createWorkerEngine(workerOptions);
+	const resolvedLoad = load ?? loadWasmBindings;
+	let bindings;
+	return { clean: async (page, options) => await Result.tryPromise({
+		try: async () => {
+			if (bindings === void 0) {
+				const pending = resolvedLoad().catch((error) => {
+					if (bindings === pending) bindings = void 0;
+					throw error;
+				});
+				bindings = pending;
+			}
+			const wasm = await bindings;
+			try {
+				let result;
+				try {
+					result = wasm.clean_scan_rgba(page.width, page.height, new Uint8Array(page.pixels.buffer, page.pixels.byteOffset, page.pixels.byteLength), page.dpi, options.output, options.contentCrop === "on", options.deskew === "on");
+					return convertResult(result, options.output);
+				} finally {
+					result?.free();
+				}
+			} catch (error) {
+				if (error instanceof WebAssembly.RuntimeError) bindings = void 0;
+				throw error;
+			}
+		},
+		catch: (cause) => cause instanceof ScanEngineError ? cause : new ScanEngineError({
+			type: "engine-failure",
+			message: "The scan engine could not clean the page",
+			cause
+		})
+	}) };
+};
+const scanEngine = createScanEngine();
+//#endregion
+export { createScanEngine, scanEngine };

package/dist/scan-engine.worker.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/scan-engine.worker.js

@@ -0,0 +1,60 @@
+import { fetchWithTimeout } from "@stll/fetch";
+import initWasm, { clean_scan_rgba } from "../generated/scan_engine.js";
+//#region src/scan-engine.worker.ts
+const WASM_LOAD_TIMEOUT_MS = 1e4;
+const post = (response, transfer = []) => {
+	Reflect.apply(postMessage, globalThis, [response, transfer]);
+};
+let initialized;
+const initialize = async () => {
+	initialized ??= fetchWithTimeout(new URL("../generated/scan_engine_bg.wasm", import.meta.url), { timeout: {
+		type: "idle",
+		ms: WASM_LOAD_TIMEOUT_MS
+	} }).then(async (response) => await response.arrayBuffer()).then(async (module_or_path) => {
+		await initWasm({ module_or_path });
+	});
+	await initialized;
+};
+const handle = async ({ data }) => {
+	try {
+		await initialize();
+		let result;
+		try {
+			result = clean_scan_rgba(data.page.width, data.page.height, new Uint8Array(data.pixels), data.page.dpi, data.options.output, data.options.contentCrop === "on", data.options.deskew === "on");
+			const response = {
+				type: "result",
+				result: {
+					status: result.status,
+					reason: result.reason,
+					pixels: result.pixels,
+					width: result.width,
+					height: result.height,
+					skew_degrees: result.skew_degrees,
+					content_box: result.content_box,
+					applied_quad: result.applied_quad
+				}
+			};
+			const buffer = response.result.pixels.buffer;
+			post(response, buffer instanceof ArrayBuffer ? [buffer] : []);
+		} finally {
+			result?.free();
+		}
+	} catch (error) {
+		const response = {
+			type: "error",
+			errorType: error instanceof WebAssembly.RuntimeError ? "runtime-trap" : "failure",
+			message: error instanceof Error ? error.message : "Unknown worker failure"
+		};
+		post(response);
+	}
+};
+addEventListener("message", (event) => {
+	handle(event).catch((error) => {
+		post({
+			type: "error",
+			errorType: "failure",
+			message: error instanceof Error ? error.message : "Unknown worker failure"
+		});
+	});
+});
+//#endregion

package/dist/types.d.ts

@@ -0,0 +1,72 @@
+import { Result } from "better-result";
+//#region src/types.d.ts
+export type ScanPageRotation = 0 | 90 | 180 | 270;
+export type PhysicalPageSize = {
+  widthPoints: number;
+  heightPoints: number;
+};
+export type RasterizedScanPage = {
+  pixels: Uint8ClampedArray;
+  width: number;
+  height: number;
+  pageSize: PhysicalPageSize;
+  dpi: number;
+  rotation: ScanPageRotation;
+};
+export type ScanOptions = {
+  output: "grayscale" | "binary";
+  contentCrop: "on" | "off";
+  deskew: "on" | "off";
+};
+export type ContentBox = {
+  /** Bounds of the detected content in the returned output image. */
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+export type CleanedScanImage = {
+  pixels: Uint8Array;
+  /** Deskewing expands these dimensions to contain the complete rotated page. */
+  width: number;
+  height: number;
+  format: ScanOptions["output"];
+};
+export type CleanScanResult = {
+  type: "cleaned";
+  image: CleanedScanImage;
+  /** Corners of the detected page in the input image, clockwise from top-left. */
+  appliedQuad: {
+    topLeft: {
+      x: number;
+      y: number;
+    };
+    topRight: {
+      x: number;
+      y: number;
+    };
+    bottomRight: {
+      x: number;
+      y: number;
+    };
+    bottomLeft: {
+      x: number;
+      y: number;
+    };
+  } | null;
+  skewDegrees: number;
+  contentBox: ContentBox;
+} | {
+  type: "unrecognized";
+  reason: string;
+};
+declare const ScanEngineError_base: import("better-result").TaggedErrorClass<"ScanEngineError">;
+export declare class ScanEngineError extends ScanEngineError_base<{
+  type: "engine-failure" | "engine-timeout";
+  message: string;
+  cause?: unknown;
+}> {}
+export type ScanEngine = {
+  clean: (page: RasterizedScanPage, options: ScanOptions) => Promise<Result<CleanScanResult, ScanEngineError>>;
+};
+//#endregion

package/dist/types.js

@@ -0,0 +1,5 @@
+import { TaggedError } from "better-result";
+//#region src/types.ts
+var ScanEngineError = class extends TaggedError("ScanEngineError") {};
+//#endregion
+export { ScanEngineError };

package/generated/scan_engine.d.ts

@@ -0,0 +1,91 @@
+/* tslint:disable */
+
+export class WasmScanResult {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  readonly applied_quad: Float32Array;
+  readonly content_box: Uint32Array;
+  readonly height: number;
+  readonly pixels: Uint8Array;
+  readonly reason: string;
+  readonly skew_degrees: number;
+  readonly status: string;
+  readonly width: number;
+}
+
+export function clean_scan_rgba(
+  width: number,
+  height: number,
+  pixels: Uint8Array,
+  dpi: number,
+  output: string,
+  content_crop: boolean,
+  deskew: boolean,
+): WasmScanResult;
+
+export type InitInput =
+  RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+  readonly memory: WebAssembly.Memory;
+  readonly __wbg_wasmscanresult_free: (a: number, b: number) => void;
+  readonly clean_scan_rgba: (
+    a: number,
+    b: number,
+    c: number,
+    d: number,
+    e: number,
+    f: number,
+    g: number,
+    h: number,
+    i: number,
+    j: number,
+  ) => void;
+  readonly wasmscanresult_applied_quad: (a: number, b: number) => void;
+  readonly wasmscanresult_content_box: (a: number, b: number) => void;
+  readonly wasmscanresult_pixels: (a: number, b: number) => void;
+  readonly wasmscanresult_reason: (a: number, b: number) => void;
+  readonly wasmscanresult_status: (a: number, b: number) => void;
+  readonly wasmscanresult_height: (a: number) => number;
+  readonly wasmscanresult_skew_degrees: (a: number) => number;
+  readonly wasmscanresult_width: (a: number) => number;
+  readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+  readonly __wbindgen_export: (a: number, b: number) => number;
+  readonly __wbindgen_export2: (
+    a: number,
+    b: number,
+    c: number,
+    d: number,
+  ) => number;
+  readonly __wbindgen_export3: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(
+  module: { module: SyncInitInput } | SyncInitInput,
+): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init(
+  module_or_path?:
+    | { module_or_path: InitInput | Promise<InitInput> }
+    | InitInput
+    | Promise<InitInput>,
+): Promise<InitOutput>;

package/generated/scan_engine.js

@@ -0,0 +1,489 @@
+/* @ts-self-types="./scan_engine.d.ts" */
+
+export class WasmScanResult {
+  static __wrap(ptr) {
+    const obj = Object.create(WasmScanResult.prototype);
+    obj.__wbg_ptr = ptr;
+    WasmScanResultFinalization.register(obj, obj.__wbg_ptr, obj);
+    return obj;
+  }
+  __destroy_into_raw() {
+    const ptr = this.__wbg_ptr;
+    this.__wbg_ptr = 0;
+    WasmScanResultFinalization.unregister(this);
+    return ptr;
+  }
+  free() {
+    const ptr = this.__destroy_into_raw();
+    wasm.__wbg_wasmscanresult_free(ptr, 0);
+  }
+  /**
+   * @returns {Float32Array}
+   */
+  get applied_quad() {
+    try {
+      const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+      wasm.wasmscanresult_applied_quad(retptr, this.__wbg_ptr);
+      var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+      var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+      var v1 = getArrayF32FromWasm0(r0, r1).slice();
+      wasm.__wbindgen_export3(r0, r1 * 4, 4);
+      return v1;
+    } finally {
+      wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+  }
+  /**
+   * @returns {Uint32Array}
+   */
+  get content_box() {
+    try {
+      const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+      wasm.wasmscanresult_content_box(retptr, this.__wbg_ptr);
+      var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+      var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+      var v1 = getArrayU32FromWasm0(r0, r1).slice();
+      wasm.__wbindgen_export3(r0, r1 * 4, 4);
+      return v1;
+    } finally {
+      wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+  }
+  /**
+   * @returns {number}
+   */
+  get height() {
+    const ret = wasm.wasmscanresult_height(this.__wbg_ptr);
+    return ret >>> 0;
+  }
+  /**
+   * @returns {Uint8Array}
+   */
+  get pixels() {
+    try {
+      const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+      wasm.wasmscanresult_pixels(retptr, this.__wbg_ptr);
+      var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+      var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+      var v1 = getArrayU8FromWasm0(r0, r1).slice();
+      wasm.__wbindgen_export3(r0, r1 * 1, 1);
+      return v1;
+    } finally {
+      wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+  }
+  /**
+   * @returns {string}
+   */
+  get reason() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+      const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+      wasm.wasmscanresult_reason(retptr, this.__wbg_ptr);
+      var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+      var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+      deferred1_0 = r0;
+      deferred1_1 = r1;
+      return getStringFromWasm0(r0, r1);
+    } finally {
+      wasm.__wbindgen_add_to_stack_pointer(16);
+      wasm.__wbindgen_export3(deferred1_0, deferred1_1, 1);
+    }
+  }
+  /**
+   * @returns {number}
+   */
+  get skew_degrees() {
+    const ret = wasm.wasmscanresult_skew_degrees(this.__wbg_ptr);
+    return ret;
+  }
+  /**
+   * @returns {string}
+   */
+  get status() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+      const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+      wasm.wasmscanresult_status(retptr, this.__wbg_ptr);
+      var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+      var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+      deferred1_0 = r0;
+      deferred1_1 = r1;
+      return getStringFromWasm0(r0, r1);
+    } finally {
+      wasm.__wbindgen_add_to_stack_pointer(16);
+      wasm.__wbindgen_export3(deferred1_0, deferred1_1, 1);
+    }
+  }
+  /**
+   * @returns {number}
+   */
+  get width() {
+    const ret = wasm.wasmscanresult_width(this.__wbg_ptr);
+    return ret >>> 0;
+  }
+}
+if (Symbol.dispose)
+  WasmScanResult.prototype[Symbol.dispose] = WasmScanResult.prototype.free;
+
+/**
+ * @param {number} width
+ * @param {number} height
+ * @param {Uint8Array} pixels
+ * @param {number} dpi
+ * @param {string} output
+ * @param {boolean} content_crop
+ * @param {boolean} deskew
+ * @returns {WasmScanResult}
+ */
+export function clean_scan_rgba(
+  width,
+  height,
+  pixels,
+  dpi,
+  output,
+  content_crop,
+  deskew,
+) {
+  try {
+    const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+    const ptr0 = passArray8ToWasm0(pixels, wasm.__wbindgen_export);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(
+      output,
+      wasm.__wbindgen_export,
+      wasm.__wbindgen_export2,
+    );
+    const len1 = WASM_VECTOR_LEN;
+    wasm.clean_scan_rgba(
+      retptr,
+      width,
+      height,
+      ptr0,
+      len0,
+      dpi,
+      ptr1,
+      len1,
+      content_crop,
+      deskew,
+    );
+    var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+    var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+    var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+    if (r2) {
+      throw takeObject(r1);
+    }
+    return WasmScanResult.__wrap(r0);
+  } finally {
+    wasm.__wbindgen_add_to_stack_pointer(16);
+  }
+}
+function __wbg_get_imports() {
+  const import0 = {
+    __proto__: null,
+    __wbg___wbindgen_throw_344f42d3211c4765: function (arg0, arg1) {
+      throw new Error(getStringFromWasm0(arg0, arg1));
+    },
+    __wbindgen_cast_0000000000000001: function (arg0, arg1) {
+      // Cast intrinsic for `Ref(String) -> Externref`.
+      const ret = getStringFromWasm0(arg0, arg1);
+      return addHeapObject(ret);
+    },
+  };
+  return {
+    __proto__: null,
+    "./scan_engine_bg.js": import0,
+  };
+}
+
+const WasmScanResultFinalization =
+  typeof FinalizationRegistry === "undefined"
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry((ptr) => wasm.__wbg_wasmscanresult_free(ptr, 1));
+
+function addHeapObject(obj) {
+  if (heap_next === heap.length) heap.push(heap.length + 1);
+  const idx = heap_next;
+  heap_next = heap[idx];
+
+  heap[idx] = obj;
+  return idx;
+}
+
+function dropObject(idx) {
+  if (idx < 1028) return;
+  heap[idx] = heap_next;
+  heap_next = idx;
+}
+
+function getArrayF32FromWasm0(ptr, len) {
+  ptr = ptr >>> 0;
+  return getFloat32ArrayMemory0().subarray(ptr / 4, ptr / 4 + len);
+}
+
+function getArrayU32FromWasm0(ptr, len) {
+  ptr = ptr >>> 0;
+  return getUint32ArrayMemory0().subarray(ptr / 4, ptr / 4 + len);
+}
+
+function getArrayU8FromWasm0(ptr, len) {
+  ptr = ptr >>> 0;
+  return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+  if (
+    cachedDataViewMemory0 === null ||
+    cachedDataViewMemory0.buffer.detached === true ||
+    (cachedDataViewMemory0.buffer.detached === undefined &&
+      cachedDataViewMemory0.buffer !== wasm.memory.buffer)
+  ) {
+    cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+  }
+  return cachedDataViewMemory0;
+}
+
+let cachedFloat32ArrayMemory0 = null;
+function getFloat32ArrayMemory0() {
+  if (
+    cachedFloat32ArrayMemory0 === null ||
+    cachedFloat32ArrayMemory0.byteLength === 0
+  ) {
+    cachedFloat32ArrayMemory0 = new Float32Array(wasm.memory.buffer);
+  }
+  return cachedFloat32ArrayMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+  return decodeText(ptr >>> 0, len);
+}
+
+let cachedUint32ArrayMemory0 = null;
+function getUint32ArrayMemory0() {
+  if (
+    cachedUint32ArrayMemory0 === null ||
+    cachedUint32ArrayMemory0.byteLength === 0
+  ) {
+    cachedUint32ArrayMemory0 = new Uint32Array(wasm.memory.buffer);
+  }
+  return cachedUint32ArrayMemory0;
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+  if (
+    cachedUint8ArrayMemory0 === null ||
+    cachedUint8ArrayMemory0.byteLength === 0
+  ) {
+    cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+  }
+  return cachedUint8ArrayMemory0;
+}
+
+function getObject(idx) {
+  return heap[idx];
+}
+
+let heap = new Array(1024).fill(undefined);
+heap.push(undefined, null, true, false);
+
+let heap_next = heap.length;
+
+function passArray8ToWasm0(arg, malloc) {
+  const ptr = malloc(arg.length * 1, 1) >>> 0;
+  getUint8ArrayMemory0().set(arg, ptr / 1);
+  WASM_VECTOR_LEN = arg.length;
+  return ptr;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+  if (realloc === undefined) {
+    const buf = cachedTextEncoder.encode(arg);
+    const ptr = malloc(buf.length, 1) >>> 0;
+    getUint8ArrayMemory0()
+      .subarray(ptr, ptr + buf.length)
+      .set(buf);
+    WASM_VECTOR_LEN = buf.length;
+    return ptr;
+  }
+
+  let len = arg.length;
+  let ptr = malloc(len, 1) >>> 0;
+
+  const mem = getUint8ArrayMemory0();
+
+  let offset = 0;
+
+  for (; offset < len; offset++) {
+    const code = arg.charCodeAt(offset);
+    if (code > 0x7f) break;
+    mem[ptr + offset] = code;
+  }
+  if (offset !== len) {
+    if (offset !== 0) {
+      arg = arg.slice(offset);
+    }
+    ptr = realloc(ptr, len, (len = offset + arg.length * 3), 1) >>> 0;
+    const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+    const ret = cachedTextEncoder.encodeInto(arg, view);
+
+    offset += ret.written;
+    ptr = realloc(ptr, len, offset, 1) >>> 0;
+  }
+
+  WASM_VECTOR_LEN = offset;
+  return ptr;
+}
+
+function takeObject(idx) {
+  const ret = getObject(idx);
+  dropObject(idx);
+  return ret;
+}
+
+let cachedTextDecoder = new TextDecoder("utf-8", {
+  ignoreBOM: true,
+  fatal: true,
+});
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+  numBytesDecoded += len;
+  if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+    cachedTextDecoder = new TextDecoder("utf-8", {
+      ignoreBOM: true,
+      fatal: true,
+    });
+    cachedTextDecoder.decode();
+    numBytesDecoded = len;
+  }
+  return cachedTextDecoder.decode(
+    getUint8ArrayMemory0().subarray(ptr, ptr + len),
+  );
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!("encodeInto" in cachedTextEncoder)) {
+  cachedTextEncoder.encodeInto = function (arg, view) {
+    const buf = cachedTextEncoder.encode(arg);
+    view.set(buf);
+    return {
+      read: arg.length,
+      written: buf.length,
+    };
+  };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+let wasmModule, wasmInstance, wasm;
+function __wbg_finalize_init(instance, module) {
+  wasmInstance = instance;
+  wasm = instance.exports;
+  wasmModule = module;
+  cachedDataViewMemory0 = null;
+  cachedFloat32ArrayMemory0 = null;
+  cachedUint32ArrayMemory0 = null;
+  cachedUint8ArrayMemory0 = null;
+  return wasm;
+}
+
+async function __wbg_load(module, imports) {
+  if (typeof Response === "function" && module instanceof Response) {
+    if (typeof WebAssembly.instantiateStreaming === "function") {
+      try {
+        return await WebAssembly.instantiateStreaming(module, imports);
+      } catch (e) {
+        const validResponse = module.ok && expectedResponseType(module.type);
+
+        if (
+          validResponse &&
+          module.headers.get("Content-Type") !== "application/wasm"
+        ) {
+          console.warn(
+            "`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n",
+            e,
+          );
+        } else {
+          throw e;
+        }
+      }
+    }
+
+    const bytes = await module.arrayBuffer();
+    return await WebAssembly.instantiate(bytes, imports);
+  } else {
+    const instance = await WebAssembly.instantiate(module, imports);
+
+    if (instance instanceof WebAssembly.Instance) {
+      return { instance, module };
+    } else {
+      return instance;
+    }
+  }
+
+  function expectedResponseType(type) {
+    switch (type) {
+      case "basic":
+      case "cors":
+      case "default":
+        return true;
+    }
+    return false;
+  }
+}
+
+function initSync(module) {
+  if (module !== undefined) {
+    if (Object.getPrototypeOf(module) === Object.prototype) {
+      ({ module } = module);
+    } else {
+      console.warn(
+        "using deprecated parameters for `initSync()`; pass a single object instead",
+      );
+    }
+  }
+
+  const imports = __wbg_get_imports();
+  if (!(module instanceof WebAssembly.Module)) {
+    module = new WebAssembly.Module(module);
+  }
+  const instance = new WebAssembly.Instance(module, imports);
+  return __wbg_finalize_init(instance, module);
+}
+
+async function __wbg_init(module_or_path) {
+  if (module_or_path !== undefined) {
+    if (Object.getPrototypeOf(module_or_path) === Object.prototype) {
+      ({ module_or_path } = module_or_path);
+    } else {
+      console.warn(
+        "using deprecated parameters for the initialization function; pass a single object instead",
+      );
+    }
+  }
+
+  if (module_or_path === undefined) {
+    module_or_path = new URL("scan_engine_bg.wasm", import.meta.url);
+  }
+  const imports = __wbg_get_imports();
+
+  if (
+    typeof module_or_path === "string" ||
+    (typeof Request === "function" && module_or_path instanceof Request) ||
+    (typeof URL === "function" && module_or_path instanceof URL)
+  ) {
+    module_or_path = fetch(module_or_path);
+  }
+
+  const { instance, module } = await __wbg_load(await module_or_path, imports);
+
+  return __wbg_finalize_init(instance, module);
+}
+
+export { initSync, __wbg_init as default };

package/generated/scan_engine_bg.wasm.d.ts

@@ -0,0 +1,32 @@
+/* tslint:disable */
+export const memory: WebAssembly.Memory;
+export const __wbg_wasmscanresult_free: (a: number, b: number) => void;
+export const clean_scan_rgba: (
+  a: number,
+  b: number,
+  c: number,
+  d: number,
+  e: number,
+  f: number,
+  g: number,
+  h: number,
+  i: number,
+  j: number,
+) => void;
+export const wasmscanresult_applied_quad: (a: number, b: number) => void;
+export const wasmscanresult_content_box: (a: number, b: number) => void;
+export const wasmscanresult_pixels: (a: number, b: number) => void;
+export const wasmscanresult_reason: (a: number, b: number) => void;
+export const wasmscanresult_status: (a: number, b: number) => void;
+export const wasmscanresult_height: (a: number) => number;
+export const wasmscanresult_skew_degrees: (a: number) => number;
+export const wasmscanresult_width: (a: number) => number;
+export const __wbindgen_add_to_stack_pointer: (a: number) => number;
+export const __wbindgen_export: (a: number, b: number) => number;
+export const __wbindgen_export2: (
+  a: number,
+  b: number,
+  c: number,
+  d: number,
+) => number;
+export const __wbindgen_export3: (a: number, b: number, c: number) => void;

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@stll/scan-engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Document scan cleanup engine (Rust, WebAssembly): deskew, content crop and binarization off the main thread, plus a per-page review state machine",
+  "keywords": [
+    "binarization",
+    "deskew",
+    "document",
+    "scan",
+    "wasm",
+    "webassembly",
+    "worker"
+  ],
+  "homepage": "https://github.com/stella/stella/tree/main/packages/scan-engine",
+  "bugs": {
+    "url": "https://github.com/stella/stella/issues"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stella/stella.git",
+    "directory": "packages/scan-engine"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "generated"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/scan-engine.d.ts",
+      "import": "./dist/scan-engine.js"
+    },
+    "./review": {
+      "types": "./dist/review.d.ts",
+      "import": "./dist/review.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "git clean -xdf dist target .cache .turbo node_modules",
+    "build": "tsdown",
+    "pack:dry-run": "bun pm pack --dry-run",
+    "test": "bun run test:bun && cargo test",
+    "test:bun": "bun test src",
+    "typecheck": "bun check --no-pretty --all --project=tsconfig.json",
+    "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --type-aware --type-check packages/scan-engine",
+    "lint:fix": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --type-aware --fix packages/scan-engine",
+    "format:rust": "cargo fmt",
+    "build:wasm": "bash scripts/build-wasm.sh",
+    "check:wasm": "bun --preload ../../scripts/offline-network-preload.ts scripts/check-wasm.ts",
+    "generate:fixtures": "bun scripts/generate-fixtures.ts",
+    "check:fixtures": "bun scripts/generate-fixtures.ts --check",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "@stll/fetch": "^0.1.0",
+    "better-result": "3.0.1"
+  },
+  "devDependencies": {
+    "@stll/typescript-config": "0.0.0",
+    "bun-types": "1.4.4",
+    "tsdown": "0.23.0"
+  },
+  "main": "./dist/scan-engine.js",
+  "types": "./dist/scan-engine.d.ts"
+}