chore(vendor): import pi 1.3.0

Imported as a linear vendor commit so forge rebases do not replay the upstream root tree.

git-subtree-dir: third_party/pi

git-subtree-split: 71023aec1546d6d677a65669c5665c0927ce0dd0

third_party/pi/packages/durable/src/images/cloudflare.ts

@@ -0,0 +1,10 @@
+// Wrangler's default `CompiledWasm` rule turns this import into a `WebAssembly.Module`; Workers cannot compile
+// WebAssembly from bytes at runtime. Other bundlers do not support it: use `createPhotonImages()` there.
+import photonWasm from "@silvia-odwyer/photon/photon_rs_bg.wasm";
+import type { ImageProcessor } from "../tools/image-processor.ts";
+import { createPhotonImages } from "./index.ts";
+
+/** `createPhotonImages()` for Cloudflare Workers and Durable Objects, built with Wrangler. */
+export function createCloudflarePhotonImages(): ImageProcessor {
+	return createPhotonImages(photonWasm);
+}

third_party/pi/packages/durable/src/images/exif.ts

@@ -0,0 +1,70 @@
+// EXIF orientation of JPEG and WebP files, read from the bytes without decoding the image.
+
+/** The EXIF orientation of a JPEG or WebP, 1 to 8; 1 when absent or unreadable. */
+export function exifOrientation(bytes: Uint8Array): number {
+	const tiff = tiffStart(bytes);
+	if (tiff < 0 || tiff + 8 > bytes.length) return 1;
+	const little = bytes[tiff] === 0x49 && bytes[tiff + 1] === 0x49;
+	const u16 = (at: number): number =>
+		little ? bytes[at]! | (bytes[at + 1]! << 8) : (bytes[at]! << 8) | bytes[at + 1]!;
+	const u32 = (at: number): number =>
+		little
+			? (bytes[at]! | (bytes[at + 1]! << 8) | (bytes[at + 2]! << 16) | (bytes[at + 3]! << 24)) >>> 0
+			: ((bytes[at]! << 24) | (bytes[at + 1]! << 16) | (bytes[at + 2]! << 8) | bytes[at + 3]!) >>> 0;
+	const directory = tiff + u32(tiff + 4);
+	if (directory + 2 > bytes.length) return 1;
+	const entries = u16(directory);
+	for (let index = 0; index < entries; index++) {
+		const entry = directory + 2 + index * 12;
+		if (entry + 12 > bytes.length) return 1;
+		// Tag 0x0112 is Orientation, a SHORT whose value sits in the entry.
+		if (u16(entry) === 0x0112) {
+			const value = u16(entry + 8);
+			return value >= 1 && value <= 8 ? value : 1;
+		}
+	}
+	return 1;
+}
+
+/** Where the TIFF header of a JPEG's APP1 or a WebP's EXIF chunk starts; -1 when there is none. */
+function tiffStart(bytes: Uint8Array): number {
+	if (bytes[0] === 0xff && bytes[1] === 0xd8) {
+		for (let offset = 2; offset + 4 <= bytes.length; ) {
+			if (bytes[offset] !== 0xff) return -1;
+			const marker = bytes[offset + 1]!;
+			if (marker === 0xff) {
+				offset++;
+				continue;
+			}
+			if (marker === 0xe1 && isExifHeader(bytes, offset + 4)) return offset + 10;
+			offset += 2 + ((bytes[offset + 2]! << 8) | bytes[offset + 3]!);
+		}
+		return -1;
+	}
+	if (ascii(bytes, 0, "RIFF") && ascii(bytes, 8, "WEBP")) {
+		for (let offset = 12; offset + 8 <= bytes.length; ) {
+			const size =
+				(bytes[offset + 4]! |
+					(bytes[offset + 5]! << 8) |
+					(bytes[offset + 6]! << 16) |
+					(bytes[offset + 7]! << 24)) >>>
+				0;
+			// Some WebP files prefix the TIFF header with "Exif\0\0".
+			if (ascii(bytes, offset, "EXIF")) return isExifHeader(bytes, offset + 8) ? offset + 14 : offset + 8;
+			// RIFF chunks are padded to an even size.
+			offset += 8 + size + (size % 2);
+		}
+	}
+	return -1;
+}
+
+function isExifHeader(bytes: Uint8Array, offset: number): boolean {
+	return ascii(bytes, offset, "Exif") && bytes[offset + 4] === 0 && bytes[offset + 5] === 0;
+}
+
+function ascii(bytes: Uint8Array, offset: number, text: string): boolean {
+	for (let index = 0; index < text.length; index++) {
+		if (bytes[offset + index] !== text.charCodeAt(index)) return false;
+	}
+	return true;
+}

third_party/pi/packages/durable/src/images/index.ts

@@ -0,0 +1,140 @@
+// The package declares only `module`, which bundlers use but Node does not: import the file itself.
+import {
+	fliph,
+	flipv,
+	initSync,
+	PhotonImage,
+	resize,
+	SamplingFilter,
+	type SyncInitInput,
+} from "@silvia-odwyer/photon/photon_rs.js";
+import type { ImageLimits, ImageProcessor, PreparedImage } from "../tools/image-processor.ts";
+import { base64Length, INLINE_IMAGE_TYPES, toBase64 } from "../tools/image-processor.ts";
+import { exifOrientation } from "./exif.ts";
+
+/** JPEG qualities tried in order. */
+const JPEG_QUALITIES = [80, 70, 55, 40];
+
+/**
+ * An `ImageProcessor` on Photon (Rust compiled to WebAssembly), for `createCodingTools({ images })`. `wasm` is
+ * Photon's `photon_rs_bg.wasm` as bytes or as a compiled module: `@earendil-works/pi-durable/images/node` reads it from
+ * the installed package, `@earendil-works/pi-durable/images/cloudflare` imports it as a Workers module. Elsewhere, such
+ * as a browser, fetch the file and pass its bytes. Photon loads once per process; later calls reuse the first `wasm`.
+ *
+ * An image already upright, in a format providers take inline, and within the limits is returned as it is, once it
+ * decodes. Otherwise it is turned upright by its EXIF orientation, scaled to the
+ * maximum width and height, and encoded as PNG or JPEG at falling qualities (JPEG first for JPEG sources), then at
+ * smaller dimensions, 3/4 at a time, until the base64 fits. Formats providers do not take inline (BMP) become PNG.
+ *
+ * The work runs on the calling thread: about a second and a half for a 12-megapixel photo. Decoding takes the image's
+ * RGBA size in WebAssembly memory, which does not shrink again; leave the processor out on memory-constrained hosts.
+ */
+export function createPhotonImages(wasm: SyncInitInput): ImageProcessor {
+	initSync({ module: wasm });
+	return { prepare: async (bytes, mimeType, limits) => prepare(bytes, mimeType, limits) };
+}
+
+function prepare(bytes: Uint8Array, mimeType: string, limits: ImageLimits): PreparedImage | undefined {
+	const orientation = exifOrientation(bytes);
+	const inline = INLINE_IMAGE_TYPES.has(mimeType);
+	let image: PhotonImage | undefined;
+	try {
+		// Decoded even when it is returned as it is: a damaged file is an error, not an image the provider rejects.
+		image = PhotonImage.new_from_byteslice(bytes);
+		if (
+			inline &&
+			orientation === 1 &&
+			image.get_width() <= limits.maxWidth &&
+			image.get_height() <= limits.maxHeight &&
+			base64Length(bytes.byteLength) <= limits.maxBytes
+		) {
+			return { data: toBase64(bytes), mimeType };
+		}
+		if (orientation >= 5) {
+			const upright = transposed(image, orientation);
+			// Freed first, so the upright copy reuses its WebAssembly memory.
+			image.free();
+			image = undefined;
+			image = new PhotonImage(upright.pixels, upright.width, upright.height);
+		} else if (orientation !== 1) {
+			if (orientation !== 4) fliph(image);
+			if (orientation !== 2) flipv(image);
+		}
+		const width = image.get_width();
+		const height = image.get_height();
+		const scale = Math.min(1, limits.maxWidth / width, limits.maxHeight / height);
+		let target = { width: Math.max(1, Math.round(width * scale)), height: Math.max(1, Math.round(height * scale)) };
+		for (;;) {
+			const encoded = encodeWithin(image, target, limits.maxBytes, mimeType === "image/jpeg");
+			if (encoded !== undefined) {
+				const resized =
+					target.width === width && target.height === height
+						? {}
+						: { resized: { from: { width, height }, to: target } };
+				const converted = encoded.mimeType === mimeType ? {} : { convertedFrom: mimeType };
+				return { ...encoded, ...converted, ...resized };
+			}
+			if (target.width === 1 && target.height === 1) return undefined;
+			target = {
+				width: Math.max(1, Math.floor(target.width * 0.75)),
+				height: Math.max(1, Math.floor(target.height * 0.75)),
+			};
+		}
+	} catch {
+		// Photon throws for bytes it cannot decode.
+		return undefined;
+	} finally {
+		image?.free();
+	}
+}
+
+/**
+ * `image` at `size` in the first encoding whose base64 fits `maxBytes`: PNG, then JPEG at falling qualities, or the
+ * JPEG qualities first when `jpegFirst`; `undefined` if none fits.
+ */
+function encodeWithin(
+	image: PhotonImage,
+	size: { readonly width: number; readonly height: number },
+	maxBytes: number,
+	jpegFirst: boolean,
+): { readonly data: string; readonly mimeType: string } | undefined {
+	const same = size.width === image.get_width() && size.height === image.get_height();
+	const scaled = same ? image : resize(image, size.width, size.height, SamplingFilter.Lanczos3);
+	try {
+		const png = { mimeType: "image/png", encode: () => scaled.get_bytes() };
+		const jpegs = JPEG_QUALITIES.map((quality) => ({
+			mimeType: "image/jpeg",
+			encode: () => scaled.get_bytes_jpeg(quality),
+		}));
+		for (const candidate of jpegFirst ? [...jpegs, png] : [png, ...jpegs]) {
+			const bytes = candidate.encode();
+			if (base64Length(bytes.byteLength) <= maxBytes) return { data: toBase64(bytes), mimeType: candidate.mimeType };
+		}
+		return undefined;
+	} finally {
+		if (!same) scaled.free();
+	}
+}
+
+/**
+ * The RGBA pixels of `image` turned upright for EXIF `orientation` 5 to 8, the orientations that swap width and
+ * height. Photon's own `rotate` drops pixels at right angles, so the pixels are moved here.
+ */
+function transposed(
+	image: PhotonImage,
+	orientation: number,
+): { readonly pixels: Uint8Array; readonly width: number; readonly height: number } {
+	const width = image.get_width();
+	const height = image.get_height();
+	const source = image.get_raw_pixels();
+	const pixels = new Uint8Array(source.length);
+	for (let y = 0; y < height; y++) {
+		for (let x = 0; x < width; x++) {
+			// Where (x, y) lands in the upright image, which is `height` wide.
+			const outX = orientation === 5 || orientation === 8 ? y : height - 1 - y;
+			const outY = orientation === 5 || orientation === 6 ? x : width - 1 - x;
+			pixels.set(source.subarray((y * width + x) * 4, (y * width + x) * 4 + 4), (outY * height + outX) * 4);
+		}
+	}
+	return { pixels, width: height, height: width };
+}

third_party/pi/packages/durable/src/images/node-worker.ts

@@ -0,0 +1,35 @@
+// The worker thread of `createNodePhotonImages()`: Photon prepares images here, off the caller's event loop.
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { parentPort } from "node:worker_threads";
+import type { ImageLimits, PreparedImage } from "../tools/image-processor.ts";
+import { createPhotonImages } from "./index.ts";
+
+/** One request: the image to prepare, and its ID for the reply. */
+export type PrepareRequest = {
+	readonly id: number;
+	readonly bytes: Uint8Array;
+	readonly mimeType: string;
+	readonly limits: ImageLimits;
+};
+
+/** The reply to a request: its result, or why it failed. */
+export type PrepareReply =
+	| { readonly id: number; readonly result: PreparedImage | undefined }
+	| { readonly id: number; readonly error: string };
+
+const port = parentPort;
+if (port === null) throw new Error("The Photon image worker needs a parent thread");
+const images = createPhotonImages(
+	readFileSync(createRequire(import.meta.url).resolve("@silvia-odwyer/photon/photon_rs_bg.wasm")),
+);
+port.on("message", (request: PrepareRequest) => {
+	void images.prepare(request.bytes, request.mimeType, request.limits).then(
+		(result) => port.postMessage({ id: request.id, result } satisfies PrepareReply),
+		(error: unknown) =>
+			port.postMessage({
+				id: request.id,
+				error: error instanceof Error ? error.message : String(error),
+			} satisfies PrepareReply),
+	);
+});

third_party/pi/packages/durable/src/images/node.ts

@@ -0,0 +1,130 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { Worker } from "node:worker_threads";
+import type { ImageLimits, ImageProcessor, PreparedImage } from "../tools/image-processor.ts";
+import { createPhotonImages } from "./index.ts";
+import type { PrepareReply, PrepareRequest } from "./node-worker.ts";
+
+export type NodePhotonImagesOptions = {
+	/**
+	 * Prepare images in a worker thread, so a large photo does not block the event loop for the second or two Photon
+	 * takes. Default `true`; `false` prepares them on the calling thread.
+	 */
+	readonly worker?: boolean;
+	/**
+	 * How long the worker stays after its last image before it exits, freeing Photon's WebAssembly memory, which never
+	 * shrinks while it lives. The next image starts a new one. Default 30 s.
+	 */
+	readonly idleMs?: number;
+};
+
+/**
+ * `createPhotonImages()` for Node and Bun, with Photon's WebAssembly read from the installed `@silvia-odwyer/photon`,
+ * by default in a worker thread that keeps the process alive only while it prepares an image. A worker that cannot
+ * start falls back to the calling thread. A single-file binary cannot resolve the package: read its own copy of
+ * `photon_rs_bg.wasm` and call `createPhotonImages()`.
+ */
+export async function createNodePhotonImages(options: NodePhotonImagesOptions = {}): Promise<ImageProcessor> {
+	if (options.worker === false) return inProcess();
+	const idleMs = options.idleMs ?? 30_000;
+	let thread: PhotonThread | undefined;
+	let fallback: Promise<ImageProcessor> | undefined;
+	return {
+		async prepare(bytes, mimeType, limits) {
+			if (fallback !== undefined) return (await fallback).prepare(bytes, mimeType, limits);
+			try {
+				thread ??= new PhotonThread(idleMs, () => {
+					thread = undefined;
+				});
+				return await thread.prepare(bytes, mimeType, limits);
+			} catch (error) {
+				if (!(error instanceof WorkerUnavailable)) throw error;
+				// No worker on this platform or build: prepare here from now on.
+				fallback = inProcess();
+				return (await fallback).prepare(bytes, mimeType, limits);
+			}
+		},
+	};
+}
+
+async function inProcess(): Promise<ImageProcessor> {
+	const path = createRequire(import.meta.url).resolve("@silvia-odwyer/photon/photon_rs_bg.wasm");
+	return createPhotonImages(await readFile(path));
+}
+
+/** The worker could not start, as opposed to failing on one image. */
+class WorkerUnavailable extends Error {}
+
+/** One worker thread and the requests it has not answered; it exits after `idleMs` without requests. */
+class PhotonThread {
+	readonly #worker: Worker;
+	readonly #pending = new Map<number, PromiseWithResolvers<PreparedImage | undefined>>();
+	readonly #idleMs: number;
+	readonly #onExit: () => void;
+	#nextId = 0;
+	#idle: ReturnType<typeof setTimeout> | undefined;
+	/** Whether the worker answered once: a failure before that means it is unavailable. */
+	#started = false;
+
+	constructor(idleMs: number, onExit: () => void) {
+		this.#idleMs = idleMs;
+		this.#onExit = onExit;
+		// Run from source under a TypeScript runtime, as in tests; built, the worker sits next to this file as JS.
+		const file = import.meta.url.endsWith(".ts") ? "./node-worker.ts" : "./node-worker.js";
+		try {
+			this.#worker = new Worker(new URL(file, import.meta.url));
+		} catch (error) {
+			throw new WorkerUnavailable("The Photon image worker cannot start", { cause: error });
+		}
+		this.#worker.unref();
+		this.#worker.on("message", (reply: PrepareReply) => {
+			this.#started = true;
+			const request = this.#pending.get(reply.id);
+			if (request === undefined) return;
+			this.#pending.delete(reply.id);
+			if ("error" in reply) request.reject(new Error(reply.error));
+			else request.resolve(reply.result);
+			this.#settled();
+		});
+		const fail = (error: unknown): void => {
+			const failure = this.#started
+				? error
+				: new WorkerUnavailable("The Photon image worker cannot start", { cause: error });
+			for (const request of this.#pending.values()) request.reject(failure);
+			this.#pending.clear();
+			this.#exit();
+		};
+		this.#worker.on("error", fail);
+		this.#worker.on("exit", (code) => fail(new Error(`The Photon image worker exited with code ${code}`)));
+	}
+
+	prepare(bytes: Uint8Array, mimeType: string, limits: ImageLimits): Promise<PreparedImage | undefined> {
+		const id = this.#nextId++;
+		const request = Promise.withResolvers<PreparedImage | undefined>();
+		this.#pending.set(id, request);
+		if (this.#idle !== undefined) clearTimeout(this.#idle);
+		this.#idle = undefined;
+		// A pending image keeps the process alive, as one prepared on the calling thread would.
+		this.#worker.ref();
+		// A copy, transferred: the caller keeps its bytes.
+		const copy = bytes.slice();
+		this.#worker.postMessage({ id, bytes: copy, mimeType, limits } satisfies PrepareRequest, [copy.buffer]);
+		return request.promise;
+	}
+
+	#settled(): void {
+		if (this.#pending.size > 0) return;
+		this.#worker.unref();
+		this.#idle = setTimeout(() => {
+			this.#exit();
+			void this.#worker.terminate();
+		}, this.#idleMs);
+		this.#idle.unref();
+	}
+
+	#exit(): void {
+		if (this.#idle !== undefined) clearTimeout(this.#idle);
+		this.#idle = undefined;
+		this.#onExit();
+	}
+}

third_party/pi/packages/durable/src/images/photon-wasm.d.ts

@@ -0,0 +1,5 @@
+// Imported by cloudflare.ts. Wrangler's default `CompiledWasm` rule makes a .wasm import a compiled module.
+declare module "@silvia-odwyer/photon/photon_rs_bg.wasm" {
+	const module: WebAssembly.Module;
+	export default module;
+}