toolshed/frontend/vendor/weblabel.mjs

/*
	libweblabel — generated bundle, do not edit.

	Built by tools/bundle.py from src/web/index.js and the modules it re-exports:
	  src/web/lib/blob.js
	  src/web/lib/bitmap.js
	  src/web/lib/text.js
	  src/web/lib/pattern.js
	  src/web/lib/ruler.js

	Edit those and rebuild. The wasm driver blobs are separate files loaded at
	runtime; see dist/blobs/.
*/

/* ---- src/web/lib/blob.js ------------------------------------------------- */

/*
	Loader for USB printer blobs (ABI v1).

	Deliberately knows nothing about P-touch printers, Brother, or libptouch.
	It loads a wasm blob, reads the device table out of the blob's manifest and
	calls the six pw_* entry points. A blob for a different vendor's printers,
	built against the same shim and exporting the same ABI, is driven by this
	file unchanged - and so is a future version of this driver that supports
	more printers, because the device table travels in the manifest rather than
	being duplicated here.

	Two classes, and the difference is smaller than it looks:

	  PrinterBlob       any blob, holding one driver or many.
	  MultiPrinterBlob  the same, seen as the set of drivers inside it: which
	                    one owns a given printer, what that one alone can do,
	                    and which of its exports to call. A merged blob
	                    (dist/blobs/libweblabel.mjs) is what makes those
	                    questions interesting; PrinterBlob drives it either
	                    way.

	The ABI is described in docs/ABI.md.
*/

/* ------------------------------------------------------------------------
   WebUSB backend

   The JS half of the shim's contract. Also vendor-neutral: it moves bytes and
   has no idea what they mean.
   ------------------------------------------------------------------------ */

export class WebUsbBackend {
	constructor({ transferTimeoutMs = 5000 } = {}) {
		this.transferTimeoutMs = transferTimeoutMs;
		this.devices = [];		/* the devices the blob is allowed to see */
		this.handles = new Map();
		this.nextHandle = 1;
	}

	/* Scope the blob to specific devices. Drivers typically open the first
	   match in the list, so passing exactly the device the user picked in the
	   chooser is what makes the selection stick. */
	setDevices(devices) {
		this.devices = devices;
	}

	async list() {
		return this.devices.map((d, index) => ({
			vendorId: d.vendorId,
			productId: d.productId,
			busNumber: 0,		/* WebUSB does not expose bus topology */
			deviceAddress: index,
		}));
	}

	async open(index) {
		const device = this.devices[index];
		if (!device) {
			return -1;
		}
		try {
			if (!device.opened) {
				await device.open();
			}
			if (device.configuration === null) {
				await device.selectConfiguration(1);
			}
		} catch (e) {
			this.lastError = e;
			return -1;
		}
		const handle = this.nextHandle++;
		this.handles.set(handle, device);
		return handle;
	}

	async close(handle) {
		const device = this.handles.get(handle);
		this.handles.delete(handle);
		if (device && device.opened) {
			try {
				await device.close();
			} catch { /* the device may already be gone */ }
		}
	}

	async claim(handle, interfaceNumber) {
		const device = this.handles.get(handle);
		if (!device) return -1;
		try {
			await device.claimInterface(interfaceNumber);
			return 0;
		} catch (e) {
			/* A driver only learns that the claim failed, not why. WebUSB's
			   own message is the useful part, and on Linux the overwhelmingly
			   likely cause is a bound kernel driver - usblp binds anything of
			   printer class - which the browser cannot detach. */
			let detail = `claimInterface(${interfaceNumber}) failed: ${e.message}`;
			if (typeof navigator !== "undefined" && /Linux/.test(navigator.userAgent || "")) {
				detail += ". On Linux this usually means a kernel driver holds the " +
					"interface (usblp claims printer-class devices) and the browser " +
					"cannot detach it. Unbind it: " +
					"echo -n <n-m:1.0> | sudo tee /sys/bus/usb/drivers/usblp/unbind " +
					"— see drivers/ptouch/README.md for the persistent udev rule";
			}
			this.lastError = new Error(detail);
			return -1;
		}
	}

	/* Hand the most recent underlying failure to the caller, once. */
	takeLastError() {
		const e = this.lastError;
		this.lastError = null;
		return e ? e.message : null;
	}

	async release(handle, interfaceNumber) {
		const device = this.handles.get(handle);
		if (!device) return -1;
		try {
			await device.releaseInterface(interfaceNumber);
			return 0;
		} catch (e) {
			this.lastError = e;
			return -1;
		}
	}

	async transferOut(handle, endpoint, bytes) {
		const device = this.handles.get(handle);
		if (!device) return -1;
		try {
			const result = await device.transferOut(endpoint, bytes);
			if (result.status !== "ok") {
				this.lastError = new Error(`transferOut: ${result.status}`);
				return -1;
			}
			return result.bytesWritten;
		} catch (e) {
			this.lastError = e;
			return -1;
		}
	}

	async transferIn(handle, endpoint, length) {
		const device = this.handles.get(handle);
		if (!device) return -1;
		/* WebUSB has no per-transfer timeout and a pending transferIn cannot be
		   cancelled, so race it against a timer. -7 is LIBUSB_ERROR_TIMEOUT to
		   the shim, which is what the driver's own timeout handling expects. */
		const TIMEOUT = Symbol("timeout");
		let timer;
		try {
			const result = await Promise.race([
				device.transferIn(endpoint, length),
				new Promise((resolve) => {
					timer = setTimeout(() => resolve(TIMEOUT), this.transferTimeoutMs);
				}),
			]);
			if (result === TIMEOUT) {
				/* The abandoned transfer would otherwise deliver its data into
				   the next read. Clearing the endpoint discards it. */
				try { await device.clearHalt("in", endpoint); } catch { /* best effort */ }
				this.lastError = new Error(`transferIn timed out after ${this.transferTimeoutMs} ms`);
				return -7;
			}
			if (result.status !== "ok") {
				this.lastError = new Error(`transferIn: ${result.status}`);
				return -1;
			}
			return new Uint8Array(result.data.buffer, result.data.byteOffset, result.data.byteLength);
		} catch (e) {
			this.lastError = e;
			return -1;
		} finally {
			clearTimeout(timer);
		}
	}
}

/* ------------------------------------------------------------------------
   Blob
   ------------------------------------------------------------------------ */

const MAX_LOG = 500;

export class PrinterBlob {
	constructor(module, backend) {
		this._module = module;
		this._backend = backend;
		this._queue = Promise.resolve();
		this.log = [];
		this.manifest = null;
		this.abiVersion = 0;
		this.openDevice = null;		/* {vendorId, productId} while open */
	}

	/*
		url       location of the blob's .mjs glue, resolved against baseUrl
		backend   anything implementing the backend contract; defaults to WebUSB
		baseUrl   base for resolving url (defaults to the document / this module)
	*/
	static async load(url, { backend, baseUrl } = {}) {
		const base = baseUrl
			|| (typeof document !== "undefined" ? document.baseURI : import.meta.url);
		const href = new URL(url, base).href;

		const usbBackend = backend || new WebUsbBackend();
		/* `new this`, so a subclass reaching this through super.load() gets an
		   instance of itself. */
		const blob = new this(null, usbBackend);

		const factory = (await import(/* @vite-ignore */ href)).default;
		blob._module = await factory({
			usbBackend,
			print: (text) => blob._record("out", text),
			printErr: (text) => blob._record("err", text),
		});

		blob.abiVersion = await blob._call("pw_abi_version", "number", [], []);
		if (blob.abiVersion !== 1) {
			throw new Error(`unsupported blob ABI version ${blob.abiVersion}, expected 1`);
		}
		const manifest = await blob._call("pw_manifest", "string", [], []);
		blob.manifest = JSON.parse(manifest);
		return blob;
	}

	_record(stream, text) {
		this.log.push({ stream, text });
		if (this.log.length > MAX_LOG) {
			this.log.shift();
		}
	}

	/* Asyncify unwinds a single wasm stack at a time, so every export call is
	   serialized. Without this, two overlapping calls corrupt each other. */
	_call(name, returnType, argTypes, args) {
		const run = () => this._module.ccall(name, returnType, argTypes, args, { async: true });
		const result = this._queue.then(run, run);
		this._queue = result.then(() => undefined, () => undefined);
		return result;
	}

	/*
		Call an export by name, through the same queue everything else uses.

		The methods below cover the ABI; this is for the exports they do not,
		which is how a caller uses the per-driver symbols that
		MultiPrinterBlob.symbolsFor() names. Going around it and calling
		Module.ccall() directly is what re-entering a suspended blob looks like.
	*/
	callExport(name, returnType = "number", argTypes = [], args = []) {
		return this._call(name, returnType, argTypes, args);
	}

	/* The driver's own explanation, plus whatever the backend knows about the
	   host-level cause. The driver only sees "the claim failed"; the backend
	   is the layer that saw the actual exception. */
	async _lastError() {
		const fromDriver = await this._call("pw_last_error", "string", [], []);
		const fromBackend = typeof this._backend.takeLastError === "function"
			? this._backend.takeLastError() : null;
		return [fromDriver, fromBackend].filter(Boolean).join(" — ") || "unknown error";
	}

	/*
		Device filters for navigator.usb.requestDevice(), straight from the
		blob. Deduplicated by USB id: a merged blob's table is several drivers'
		tables at once, and two of them may know the same printer.
	*/
	usbFilters() {
		const seen = new Set();
		const filters = [];
		for (const d of this.manifest.devices) {
			const key = `${d.vendorId}:${d.productId}`;
			if (!seen.has(key)) {
				seen.add(key);
				filters.push({ vendorId: d.vendorId, productId: d.productId });
			}
		}
		return filters;
	}

	/** What the blob knows about these USB ids, or null if it does not know them. */
	findDevice(vendorId, productId) {
		return this.manifest.devices.find(
			(d) => d.vendorId === vendorId && d.productId === productId) || null;
	}

	/** Restrict the blob's view of the bus to these WebUSB devices. */
	setDevices(devices) {
		this._backend.setDevices(devices);
	}

	async open(vendorId, productId, { timeoutSeconds = 1 } = {}) {
		const rc = await this._call("pw_open", "number",
			["number", "number", "number"], [vendorId, productId, timeoutSeconds]);
		if (rc !== 0) {
			throw new Error(await this._lastError());
		}
		this.openDevice = { vendorId, productId };
	}

	async status({ timeoutSeconds = 1 } = {}) {
		const json = await this._call("pw_status_json", "string",
			["number"], [timeoutSeconds]);
		const parsed = JSON.parse(json);
		if (parsed === null) {
			throw new Error(await this._lastError());
		}
		return parsed;
	}

	async close() {
		await this._call("pw_close", "number", [], []);
		this.openDevice = null;
	}

	/** Does the blob advertise this capability? */
	can(capability) {
		return (this.manifest.capabilities || []).includes(capability);
	}

	/*
		Print a bitmap: one byte per pixel, row-major, non-zero = a printed dot.
		width runs along the tape, height across it. The caller is responsible
		for keeping height within the print area the status reports.
	*/
	async printBitmap({ data, width, height },
		{ chain = false, precut = false, copies = 1 } = {}) {
		if (!this.can("print")) {
			throw new Error("this blob does not support printing");
		}
		if (data.length !== width * height) {
			throw new Error(`bitmap is ${data.length} bytes, expected ${width * height}`);
		}
		/* Staged into the wasm heap so the blob can read it directly. Freed
		   even if the print throws, and after the call has fully finished -
		   the pointer is live for the whole suspended-stack duration. */
		const ptr = this._module._malloc(data.length);
		if (!ptr) {
			throw new Error(`could not allocate ${data.length} bytes in the blob`);
		}
		try {
			this._module.HEAPU8.set(data, ptr);
			const rc = await this._call("pw_print", "number",
				["number", "number", "number", "number", "number", "number"],
				[ptr, width, height, chain ? 1 : 0, precut ? 1 : 0, copies]);
			if (rc !== 0) {
				throw new Error(await this._lastError());
			}
		} finally {
			this._module._free(ptr);
		}
	}
}

/* ------------------------------------------------------------------------
   Blobs seen as a set of drivers

   dist/blobs/libweblabel.mjs is every driver this build produced, in one
   module. It forwards the plain ABI to whichever driver owns the printer that
   was opened, so PrinterBlob drives it without knowing that.

   What this class covers is the part only the driver set can answer: which
   driver a given printer belongs to, what that driver alone can do, and which
   of its exports to call for it. A blob holding one driver is a set of one, so
   this works on those too and a page never has to choose between the two
   classes. See "Merged blobs" in docs/ABI.md.
   ------------------------------------------------------------------------ */

/* The ABI, as the JavaScript name for each export and the bare C name it is
   built from. A merged blob exports every one of these twice: once plain, and
   once per driver as pw_<driver>_<name>. */
const ABI_EXPORTS = {
	abiVersion: "abi_version",
	manifest: "manifest",
	devices: "devices",
	capabilities: "capabilities",
	supports: "supports",
	open: "open",
	close: "close",
	statusJson: "status_json",
	print: "print",
	lastError: "last_error",
};

export class MultiPrinterBlob extends PrinterBlob {
	/*
		Does this module hold several drivers?

		The merged blob reports them under "drivers" and reaches each one
		through prefixed exports; a single-driver blob has only the plain ones.
		It is the one thing that changes the answers below.
	*/
	get merged() {
		return Array.isArray(this.manifest.drivers);
	}

	/* The drivers inside this blob, each one's own manifest verbatim. A
	   single-driver blob's manifest has that shape already, so it is a set of
	   one rather than a special case. */
	get drivers() {
		return this.manifest.drivers || [this.manifest];
	}

	/** Their names, in the order the build linked them. */
	driverNames() {
		return this.drivers.map((d) => d.driver.name);
	}

	/** The manifest of the driver with this name, or null. */
	driver(name) {
		return this.drivers.find((d) => d.driver.name === name) || null;
	}

	/*
		The driver that owns these USB ids, or null if none does.

		Answered from the merged device table, where every entry names the
		driver it came from. pw_driver_for() inside the blob answers the same
		question from the same tables; this is the cheap synchronous way to ask
		it.
	*/
	driverFor(vendorId, productId) {
		const device = this.findDevice(vendorId, productId);
		return device ? this.driver(device.driver) : null;
	}

	/*
		Which exports to call for this printer.

		    const { driver, exports } = blob.symbolsFor(0x04f9, 0x2074);
		    await blob.callExport(exports.open, "number",
		            ["number", "number", "number"], [0x04f9, 0x2074, 1]);

		Going through the plain ABI - blob.open(), blob.status(), and the rest
		- does the same dispatch inside the blob and is what most callers want.
		This is for a caller that has a reason to address one driver directly:
		reading a second driver's manifest while a printer is open, say, or
		driving two of them without letting either one's dispatch state decide
		which is current.

		On a single-driver blob the prefix is empty and these are the plain ABI
		names, which is the truth there: the one driver is the dispatch.

		Returns null when no driver in this blob knows the device.
	*/
	symbolsFor(vendorId, productId) {
		const driver = this.driverFor(vendorId, productId);
		if (!driver) {
			return null;
		}
		const name = driver.driver.name;
		const prefix = this.merged ? `pw_${name}_` : "pw_";
		const exports = {};
		for (const [key, bare] of Object.entries(ABI_EXPORTS)) {
			exports[key] = prefix + bare;
		}
		return { driver: name, prefix, exports, capabilities: driver.capabilities };
	}

	/*
		Does a capability apply?

		With no device, the answer is the merged one: some driver in this blob
		can do it. With a device - or with one open - it is that device's
		driver alone, which is the honest answer for a control that is about to
		act on that printer. "chain" is the case that matters: the P-touch
		driver honours it and the QL driver does not.
	*/
	can(capability, device = this.openDevice) {
		if (!device) {
			return super.can(capability);
		}
		const driver = this.driverFor(device.vendorId, device.productId);
		return Boolean(driver && (driver.capabilities || []).includes(capability));
	}
}

/* ---- src/web/lib/bitmap.js ----------------------------------------------- */

/*
	Canvas ⇄ the one-byte-per-pixel bitmap the blob ABI takes.

	A printhead has one state per dot: a pin either fires or it does not. Canvas
	drawing is anti-aliased, so everything drawn there is greyscale until it is
	thresholded here. Nothing in this file knows what is being printed.
*/

/* Canvas RGBA to the bitmap: one byte per pixel, row-major, non-zero = a dot. */
export function canvasToBitmap(canvas) {
	const { width, height } = canvas;
	const rgba = canvas.getContext("2d", { willReadFrequently: true })
		.getImageData(0, 0, width, height).data;
	const data = new Uint8Array(width * height);
	for (let i = 0, p = 0; p < data.length; i += 4, ++p) {
		/* Rounded, because the coefficients do not sum to exactly 1 in binary
		   floating point: without this, a pixel at exactly mid grey flips on
		   rounding noise instead of landing consistently on one side. */
		const luminance = Math.round(0.299 * rgba[i] + 0.587 * rgba[i + 1] + 0.114 * rgba[i + 2]);
		/* Transparent counts as blank; anything darker than mid grey prints. */
		data[p] = (rgba[i + 3] > 127 && luminance < 128) ? 1 : 0;
	}
	return { data, width, height };
}

/*
	Paint a bitmap back onto its canvas, so the preview shows exactly the dots
	that will be printed, jaggies and all. canvasToBitmap() is idempotent over
	this: re-reading the canvas afterwards yields the same bytes.
*/
export function bitmapToCanvas(canvas, bitmap) {
	const ctx = canvas.getContext("2d", { willReadFrequently: true });
	const img = ctx.createImageData(bitmap.width, bitmap.height);
	for (let p = 0, i = 0; p < bitmap.data.length; ++p, i += 4) {
		const value = bitmap.data[p] ? 0 : 255;
		img.data[i] = img.data[i + 1] = img.data[i + 2] = value;
		img.data[i + 3] = 255;
	}
	ctx.putImageData(img, 0, 0);
}

/** How many dots the printhead will fire for this bitmap. */
export function countDots(bitmap) {
	let dots = 0;
	for (const b of bitmap.data) {
		dots += b;
	}
	return dots;
}

/* ---- src/web/lib/text.js ------------------------------------------------- */

/*
	Text laid out the way `ptouch-print --text` does it.

	A port of render_text() and its helpers from ptouch-print.c, which cannot be
	linked into a blob: that file is libgd and argp all the way down. The CLI
	picks a font size that makes the tallest line fill its share of the tape,
	builds an image exactly as wide as the widest line, and distributes the lines
	down the print area. Everything below mirrors that, including the integer
	arithmetic, so the same input yields the same layout.

	Verified against the real tool: for the cases in the test suite this picks
	the same point size and produces the same label width as
	`ptouch-print --force-tape-width N --text ... --write-png`.

	One deliberate difference: gd is called through gdImageStringFT_180dpi(),
	which hardcodes 180 dpi, so the CLI renders text at half the intended
	physical size on a 360 dpi model. Here the printer's real dpi is used.

	gd's brect maps onto canvas TextMetrics like this:
	  brect[1]   descent below the baseline    actualBoundingBoxDescent
	  brect[5]   -ascent above the baseline   -actualBoundingBoxAscent
	  brect[0]   left edge of the ink         -actualBoundingBoxLeft
	  brect[2]   right edge of the ink         actualBoundingBoxRight
	so height = brect[1]-brect[5], needed_width = brect[2]-brect[0] and
	offset_x = -brect[0] all carry over directly.
*/

export const MAX_LINES = 4;		/* as in ptouch-print.c */

/*
	The threshold is 50%, matching what the CLI does. ptouch-print.c renders with
	a *negative* colour (`-black`), which tells libgd to disable anti-aliasing
	and use FreeType's monochrome rasterizer - verified: the same string rendered
	with `black` produces 9 distinct palette entries, with `-black` exactly 2. So
	the CLI's text is natively 1-bit and its coverage rule is "is the pixel centre
	inside the outline", which 50% approximates.

	The one thing that cannot be reproduced is FreeType's dropout control, which
	deliberately keeps hairlines that would otherwise fall between pixel centres.
	Lowering TEXT_COVERAGE thickens stems if that ever bites.

	What stops small text turning to mush is not the threshold but the size: the
	text is scaled to the print area rather than to a fixed pixel size, so stems
	are several dots wide. fillText()'s maxWidth argument is never used - it
	condenses glyphs horizontally to fit, which destroys legibility far faster
	than omitting the element does.
*/
const TEXT_COVERAGE = 0.5;

/* DejaVu Sans is the CLI's default font, so labels come out looking the same
   either way. */
const TEXT_FONT_STACK = '"DejaVu Sans", "Liberation Sans", Arial, Helvetica, sans-serif';
const TEXT_WEIGHT = "normal";

/* Verbatim from find_fontsize(): measuring against a fixed set of ascenders and
   descenders keeps every line the same height whatever it contains. */
const COMMON_CHARS = "!\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnoprqstuvwxyz{|}~";

let measureCtx = null;

const textFont = (size) => `${TEXT_WEIGHT} ${size}px ${TEXT_FONT_STACK}`;

/* Ink box rather than advance width, so text can be packed tightly. Already
   rounded to integers, which is what FreeType reports, so the arithmetic below
   stays integer as it is in C. */
function ftMetrics(text, fontPx) {
	if (!measureCtx) {
		measureCtx = document.createElement("canvas").getContext("2d");
	}
	measureCtx.font = textFont(fontPx);
	const m = measureCtx.measureText(text);
	const left = Math.ceil(m.actualBoundingBoxLeft ?? 0);
	const right = Math.ceil(m.actualBoundingBoxRight ?? m.width);
	const ascent = Math.ceil(m.actualBoundingBoxAscent ?? fontPx * 0.8);
	const descent = Math.ceil(m.actualBoundingBoxDescent ?? fontPx * 0.2);
	return { left, width: left + right, ascent, descent, height: ascent + descent };
}

const ptToPx = (pt, dpi) => pt * dpi / 72;

/* find_fontsize(): the largest whole point size whose line height still fits. */
function findFontSizePt(wantPx, text, dpi) {
	const combined = text + COMMON_CHARS;
	let save = 0;
	for (let pt = 4; pt <= 500; ++pt) {
		if (ftMetrics(combined, ptToPx(pt, dpi)).height <= wantPx) {
			save = pt;
		} else {
			break;
		}
	}
	return save === 0 ? -1 : save;
}

/* get_baselineoffset(): how much further below the baseline this text reaches
   than a letter that sits on it. 'z' is the CLI's reference glyph. */
function baselineOffset(text, fontPx) {
	return ftMetrics(text, fontPx).descent - ftMetrics("z", fontPx).descent;
}

/* The CLI's --text splits on a literal \n as well as a real newline. */
export function parseTextLines(input) {
	return input.split(/\\n|\n/).slice(0, MAX_LINES);
}

/* render_text(): the placement of every line, or a throw carrying the same
   message the CLI prints. printWidth is the print area of the mounted tape. */
export function layoutTextLabel(lines, printWidth,
	{ align = "l", fontSizePt = 0, fontMargin = 0, dpi }) {
	let fsz = fontSizePt;
	if (fsz <= 0) {
		const wantPx = Math.floor((printWidth - 2 * fontMargin) / lines.length);
		for (const line of lines) {
			const candidate = findFontSizePt(wantPx, line, dpi);
			if (candidate < 0) {
				throw new Error("could not estimate needed font size");
			}
			if (fsz === 0 || candidate < fsz) {
				fsz = candidate;
			}
		}
	}

	const fontPx = ptToPx(fsz, dpi);
	const metrics = lines.map((line) => ftMetrics(line, fontPx));
	const width = Math.max(...metrics.map((m) => m.width));
	const maxHeight = Math.max(...metrics.map((m) => m.height));

	if (maxHeight * lines.length > printWidth) {
		throw new Error(`Font size ${fsz} too large for ${lines.length} lines`);
	}

	const unusedPx = printWidth - maxHeight * lines.length;
	const placements = lines.map((line, i) => {
		const ofs = baselineOffset(line, fontPx);
		let pos = i * Math.floor(printWidth / lines.length) + maxHeight - ofs;
		pos += Math.floor(Math.floor(unusedPx / lines.length) / 2);
		let alignOfs = 0;
		if (align === "c") {
			alignOfs = Math.floor((width - metrics[i].width) / 2);
		} else if (align === "r") {
			alignOfs = width - metrics[i].width;
		}
		return { text: line, x: metrics[i].left + alignOfs, baseline: pos };
	});

	return { fontSizePt: fsz, fontPx, width, maxHeight, placements };
}

/*
	Render the whole text block into one buffer and threshold it in a single
	pass, the way the CLI fills one gd image. The result is already 1-bit, so
	whoever composes the label can blit it 1:1 and keep it that way.
*/
export function renderTextLabel(lines, printWidth, opts) {
	const layout = layoutTextLabel(lines, printWidth, opts);

	const canvas = document.createElement("canvas");
	canvas.width = Math.max(1, layout.width);
	canvas.height = printWidth;
	const ctx = canvas.getContext("2d", { willReadFrequently: true });
	ctx.fillStyle = "#fff";
	ctx.fillRect(0, 0, canvas.width, canvas.height);
	ctx.font = textFont(layout.fontPx);
	ctx.textBaseline = "alphabetic";
	ctx.fillStyle = "#000";
	for (const p of layout.placements) {
		ctx.fillText(p.text, p.x, p.baseline);
	}

	/* Opaque white background, so coverage is luminance rather than alpha. */
	const img = ctx.getImageData(0, 0, canvas.width, canvas.height);
	const cutoff = Math.round((1 - TEXT_COVERAGE) * 255);
	for (let i = 0; i < img.data.length; i += 4) {
		const luminance = Math.round(0.299 * img.data[i] + 0.587 * img.data[i + 1]
			+ 0.114 * img.data[i + 2]);
		const value = luminance <= cutoff ? 0 : 255;
		img.data[i] = img.data[i + 1] = img.data[i + 2] = value;
		img.data[i + 3] = 255;
	}
	ctx.putImageData(img, 0, 0);
	return { canvas, layout };
}

/* ---- src/web/lib/pattern.js ---------------------------------------------- */

/*
	A test pattern for a thermal printhead.

	Everything is laid out left to right and simply omitted when the tape runs
	out. Nothing is ever scaled down to fit - a squeezed element is a misleading
	test.
*/

/*
	ctx      the label canvas, one pixel per printhead pin
	w, h     the area to fill; h is the print area of the mounted tape
	textBlock  an already-thresholded canvas to blit at the left, or null
*/
export function drawTestPattern(ctx, w, h, textBlock) {
	ctx.fillStyle = "#fff";
	ctx.fillRect(0, 0, w, h);
	ctx.fillStyle = "#000";
	ctx.strokeStyle = "#000";
	ctx.lineWidth = 1;
	/* Crisp 1px strokes need half-pixel coordinates. */
	const line = (x1, y1, x2, y2) => {
		ctx.beginPath();
		ctx.moveTo(x1 + 0.5, y1 + 0.5);
		ctx.lineTo(x2 + 0.5, y2 + 0.5);
		ctx.stroke();
	};

	/* A frame on the outermost pins: if the print comes out clipped or off
	   centre, this is the thing that shows it. */
	ctx.strokeRect(0.5, 0.5, w - 1, h - 1);

	const gap = 6;
	const margin = 5;
	let x = margin;
	const room = (need) => x + need <= w - margin;

	/* The text block comes first, rendered by the same --text layout used in
	   text-only mode, so the pattern shows real label text next to the geometry
	   rather than a second, differently-produced caption. Already 1-bit, so a
	   1:1 blit is all that is needed. */
	if (textBlock && room(textBlock.width)) {
		ctx.drawImage(textBlock, x, 0);
		x += textBlock.width + gap;
	}

	/* Vertical bars 1..4 px wide - horizontal (along-tape) resolution. */
	if (room(4 + 3 * 3 + 4)) {
		for (let bar = 1; bar <= 4; ++bar) {
			ctx.fillRect(x, 4, bar, h - 8);
			x += bar + 3;
		}
		x += gap - 3;
	}

	/* Horizontal rules at top, middle and bottom - vertical alignment. */
	const rules = 22;
	if (room(rules)) {
		line(x, 4, x + rules, 4);
		line(x, (h >> 1), x + rules, (h >> 1));
		line(x, h - 5, x + rules, h - 5);
		x += rules + gap;
	}

	/* Solid block, then a hollow one. */
	const box = Math.max(6, Math.min(24, h - 16));
	const boxTop = (h - box) >> 1;
	if (room(box)) {
		ctx.fillRect(x, boxTop, box, box);
		x += box + gap;
	}
	if (room(box)) {
		ctx.strokeRect(x + 0.5, boxTop + 0.5, box - 1, box - 1);
		x += box + gap;
	}

	/* Circle - diagonal edges and anti-aliasing, which thresholding must cope
	   with. */
	const r = Math.max(3, Math.min(box, h - 12) / 2);
	if (room(2 * r)) {
		ctx.beginPath();
		ctx.arc(x + r, h / 2, r, 0, Math.PI * 2);
		ctx.stroke();
		x += 2 * r + gap;
	}

	/* An X. */
	const d = Math.min(24, h - 12);
	const top = (h - d) >> 1;
	if (room(d)) {
		line(x, top, x + d, top + d);
		line(x, top + d, x + d, top);
		x += d + gap;
	}

	/* 2px checkerboard. */
	const check = Math.min(24, h - 12);
	if (room(check)) {
		for (let cy = 0; cy < check; cy += 2) {
			for (let cx = 0; cx < check; cx += 2) {
				if (((cx + cy) / 2) % 2 === 0) {
					ctx.fillRect(x + cx, top + cy, 2, 2);
				}
			}
		}
		x += check + gap;
	}
}

/* ---- src/web/lib/ruler.js ------------------------------------------------ */

/*
	Millimetre rulers for the label preview.

	They live on their own canvases, deliberately not on the label canvas: that
	one is the print bitmap, so anything drawn there would come out on the tape.

	One bitmap pixel is one printhead pin, so millimetres follow from the
	printer's own dpi: 1 mm = dpi/25.4 pixels, which is 7.09 px at 180 dpi and
	14.17 px at 360 dpi.
*/

export const RULER_H = 20;		/* height of the along-tape ruler, CSS px */
export const RULER_W = 26;		/* width of the across-tape ruler, CSS px */

/* Tick spacing in mm, coarsened as the preview shrinks: minor ticks need room
   to stay distinguishable, numbered ticks need room not to collide. */
function tickSteps(screenPxPerMm) {
	const candidates = [[1, 5], [2, 10], [5, 25], [10, 50], [20, 100], [50, 250]];
	for (const [minor, major] of candidates) {
		if (minor * screenPxPerMm >= 4 && major * screenPxPerMm >= 26) {
			return { minor, major };
		}
	}
	return { minor: 100, major: 500 };
}

/*
	canvas    the ruler's own canvas
	lengthPx  the ruled span in bitmap pixels
	axis      "x" along the tape (below the label), "y" across it (beside it)
	zoom      screen pixels per bitmap pixel
	dpi       the printer's resolution, which is what makes a millimetre a
	          millimetre
*/
export function drawRuler(canvas, { lengthPx, axis, zoom, dpi }) {
	const dpr = window.devicePixelRatio || 1;
	const pxPerMm = dpi / 25.4;
	const span = lengthPx * zoom;			/* CSS px along the ruled axis */
	const horizontal = axis === "x";
	const cssW = horizontal ? span : RULER_W;
	const cssH = horizontal ? RULER_H : span;

	/* Backed at device resolution so the tick labels stay sharp; the label
	   canvas next to it stays 1:1 because it is pixel data, not a drawing. */
	canvas.width = Math.round(cssW * dpr);
	canvas.height = Math.round(cssH * dpr);
	canvas.style.width = `${cssW}px`;
	canvas.style.height = `${cssH}px`;

	const ctx = canvas.getContext("2d");
	ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
	ctx.clearRect(0, 0, cssW, cssH);

	const ink = getComputedStyle(document.body).color;
	ctx.strokeStyle = ink;
	ctx.fillStyle = ink;
	ctx.globalAlpha = 0.65;
	ctx.lineWidth = 1;
	ctx.font = "9px system-ui, sans-serif";

	/* The rule itself, along the edge shared with the preview. */
	ctx.beginPath();
	if (horizontal) {
		ctx.moveTo(0, 0.5);
		ctx.lineTo(span, 0.5);
	} else {
		ctx.moveTo(0.5, 0);
		ctx.lineTo(0.5, span);
	}
	ctx.stroke();

	const totalMm = lengthPx / pxPerMm;
	const step = tickSteps(pxPerMm * zoom);
	for (let mm = 0; mm <= totalMm; mm += step.minor) {
		const at = Math.round(mm * pxPerMm * zoom) + 0.5;
		const major = mm % step.major === 0;
		const tick = major ? 8 : 4;

		ctx.globalAlpha = major ? 0.75 : 0.45;
		ctx.beginPath();
		if (horizontal) {
			ctx.moveTo(at, 0);
			ctx.lineTo(at, tick);
		} else {
			ctx.moveTo(0, at);
			ctx.lineTo(tick, at);
		}
		ctx.stroke();

		if (!major) {
			continue;
		}
		ctx.globalAlpha = 0.75;
		const text = String(mm);
		if (horizontal) {
			/* Skip a number that would run past the end of the tape. */
			if (at + ctx.measureText(text).width + 2 > span) {
				continue;
			}
			ctx.textBaseline = "top";
			ctx.fillText(text, at + 2, tick + 1);
		} else {
			if (at + 4 > span) {
				continue;
			}
			ctx.textBaseline = "middle";
			ctx.fillText(text, tick + 2, at + 4);
		}
	}
}