@angadie/chittie-preview 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,64 @@
+# @angadie/chittie-preview
+
+Render a receipt to an **image** by parsing the ESC/POS bytes chittie emits — a
+software preview of *what the printer will actually print*. Platform-neutral: you
+inject a canvas factory, so it works in the browser (`HTMLCanvasElement`) and in
+Node (`@napi-rs/canvas`) with **no hard dependency** — the same pattern as
+[`@angadie/chittie-text`](../chittie-text)'s injected rasterizer.
+
+Handles chittie's real output: text + bold + double-size, rules, paper cut, and
+**both image modes** (column `ESC *` — the default — and raster `GS v 0`). Barcodes
+and QR codes are drawn as labelled placeholder boxes (their bytes are parsed and
+skipped cleanly, so nothing desyncs).
+
+## Install
+
+```bash
+pnpm add @angadie/chittie-preview
+```
+
+## Browser
+
+```ts
+import { renderReceipt } from '@angadie/chittie-preview';
+
+const canvas = renderReceipt(bytes, {
+  createCanvas: (w, h) => Object.assign(document.createElement('canvas'), { width: w, height: h }),
+});
+document.body.appendChild(canvas); // or canvas.toDataURL()
+```
+
+## Node
+
+```ts
+import { renderReceipt } from '@angadie/chittie-preview';
+import { createCanvas } from '@napi-rs/canvas';
+import { writeFileSync } from 'node:fs';
+
+const canvas = renderReceipt(bytes, { createCanvas });
+writeFileSync('receipt.png', canvas.toBuffer('image/png'));
+```
+
+`bytes` is the `Uint8Array` from chittie's `render()` or `encode()`.
+
+## Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `createCanvas(w, h)` | — | **required** canvas factory |
+| `columns` | `32` | characters per line (match your `<Printer width>`) |
+| `cellWidth` | `12` | px per character cell |
+| `lineHeight` | `26` | px per text line |
+| `fontFamily` | `'monospace'` | text font |
+| `padding` | `16` | outer padding px |
+
+## Prior art
+
+[`node-thermal-printer`](https://github.com/Klemen1337/node-thermal-printer) prints
+to thermal printers from Node (file/network/OS-printer), but it's Node-only
+(`fs`/`net`/`pngjs`) and has no preview. chittie-preview is platform-neutral (browser
++ node via the injected canvas) and renders the byte stream itself.
+
+## License
+
+MIT.

package/dist/index.d.mts

@@ -0,0 +1,39 @@
+//#region src/index.d.ts
+/** The 2D context methods/properties chittie-preview draws with. */
+interface PreviewContext2D {
+  fillStyle: string;
+  strokeStyle: string;
+  font: string;
+  textBaseline: string;
+  fillRect(x: number, y: number, w: number, h: number): void;
+  strokeRect(x: number, y: number, w: number, h: number): void;
+  fillText(text: string, x: number, y: number): void;
+  setLineDash(segments: number[]): void;
+  beginPath(): void;
+  moveTo(x: number, y: number): void;
+  lineTo(x: number, y: number): void;
+  stroke(): void;
+}
+interface PreviewCanvas {
+  width: number;
+  height: number;
+  getContext(type: '2d'): PreviewContext2D | null;
+}
+interface PreviewOptions {
+  /** Canvas factory. Web: `(w,h)=>Object.assign(document.createElement('canvas'),{width:w,height:h})`. Node: `@napi-rs/canvas` `createCanvas`. */
+  createCanvas: (width: number, height: number) => PreviewCanvas;
+  /** Characters per line (default 32). */
+  columns?: number;
+  /** Pixels per character cell (default 12). */
+  cellWidth?: number;
+  /** Pixels per text line (default 26). */
+  lineHeight?: number;
+  /** Font family for text (default 'monospace'). */
+  fontFamily?: string;
+  /** Outer padding in px (default 16). */
+  padding?: number;
+}
+/** Render ESC/POS bytes (from chittie `render()` / `encode()`) to a canvas. */
+declare function renderReceipt(bytes: Uint8Array, options: PreviewOptions): PreviewCanvas;
+//#endregion
+export { PreviewCanvas, PreviewContext2D, PreviewOptions, renderReceipt };

package/dist/index.mjs

@@ -0,0 +1,205 @@
+//#region src/index.ts
+const CP437_HIGH = "ÇüéâäàåçêëèïîìÄÅÉæÆôöòûùÿÖÜ¢£¥₧ƒáíóúñѪº¿⌐¬½¼¡«»░▒▓│┤╡╢╖╕╣║╗╝╜╛┐└┴┬├─┼╞╟╚╔╩╦╠═╬╧╨╤╥╙╘╒╓╫╪┘┌█▄▌▐▀αßΓπΣσµτΦΘΩδ∞φε∩≡±≥≤⌠⌡÷≈°∙·√ⁿ²■\xA0";
+const decode = (b) => b < 128 ? String.fromCharCode(b) : CP437_HIGH[b - 128] ?? "";
+function parse(bytes, cfg) {
+	const dots = cfg.columns * cfg.cellWidth;
+	const u16 = (lo, hi) => lo + hi * 256;
+	const ops = [];
+	let x = 0;
+	let y = cfg.padding;
+	let bold = false;
+	let wScale = 1;
+	let hScale = 1;
+	let lineMaxScale = 1;
+	let align = "left";
+	let suppressNextLF = false;
+	let i = 0;
+	const n = bytes.length;
+	const imgX = (w) => align === "center" ? Math.max(0, Math.round((dots - w) / 2)) : align === "right" ? Math.max(0, dots - w) : 0;
+	while (i < n) {
+		const b = bytes[i];
+		if (b === 27) {
+			const c = bytes[i + 1];
+			if (c === 64) i += 2;
+			else if (c === 69) {
+				bold = !!bytes[i + 2];
+				i += 3;
+			} else if (c === 33) {
+				const m = bytes[i + 2];
+				bold = !!(m & 8);
+				wScale = m & 32 ? 2 : 1;
+				hScale = m & 16 ? 2 : 1;
+				i += 3;
+			} else if (c === 97) {
+				const m = bytes[i + 2];
+				align = m === 1 ? "center" : m === 2 ? "right" : "left";
+				i += 3;
+			} else if (c === 74) {
+				y += bytes[i + 2] ?? 0;
+				i += 3;
+			} else if (c === 100) {
+				y += (bytes[i + 2] ?? 0) * cfg.lineHeight;
+				i += 3;
+			} else if (c === 112) i += 5;
+			else if (c === 50) i += 2;
+			else if (c === 42) {
+				const m = bytes[i + 2];
+				const cols = u16(bytes[i + 3], bytes[i + 4]);
+				const bpc = m === 0 || m === 1 ? 1 : 3;
+				const start = i + 5;
+				const data = bytes.subarray(start, start + bpc * cols);
+				const ix = imgX(cols);
+				const blacks = [];
+				for (let col = 0; col < cols; col++) for (let byte = 0; byte < bpc; byte++) {
+					const v = data[col * bpc + byte] ?? 0;
+					for (let bit = 0; bit < 8; bit++) if (v & 128 >> bit) blacks.push([ix + col, y + byte * 8 + bit]);
+				}
+				ops.push({
+					k: "img",
+					blacks
+				});
+				y += bpc * 8;
+				suppressNextLF = true;
+				i = start + bpc * cols;
+			} else if (c === 51) i += 3;
+			else if (c === 116 || c === 77 || c === 82 || c === 32 || c === 45 || c === 123 || c === 71) i += 3;
+			else i += 2;
+		} else if (b === 29) {
+			const c = bytes[i + 1];
+			if (c === 33) {
+				const m = bytes[i + 2];
+				wScale = (m >> 4 & 7) + 1;
+				hScale = (m & 7) + 1;
+				i += 3;
+			} else if (c === 86) {
+				ops.push({
+					k: "cut",
+					y
+				});
+				y += 14;
+				i += (bytes[i + 2] ?? 0) >= 65 ? 4 : 3;
+			} else if (c === 118 && bytes[i + 2] === 48) {
+				const wbytes = u16(bytes[i + 4], bytes[i + 5]);
+				const h = u16(bytes[i + 6], bytes[i + 7]);
+				const start = i + 8;
+				const w = wbytes * 8;
+				const data = bytes.subarray(start, start + wbytes * h);
+				const ix = imgX(w);
+				const blacks = [];
+				for (let row = 0; row < h; row++) for (let col = 0; col < w; col++) if (data[row * wbytes + (col >> 3)] & 128 >> (col & 7)) blacks.push([ix + col, y + row]);
+				ops.push({
+					k: "img",
+					blacks
+				});
+				y += h + 4;
+				i = start + wbytes * h;
+			} else if (c === 107) {
+				const m = bytes[i + 2];
+				let j;
+				if (m >= 65) j = i + 4 + (bytes[i + 3] ?? 0);
+				else {
+					j = i + 3;
+					while (j < n && bytes[j] !== 0) j++;
+					j++;
+				}
+				const w = Math.min(dots, 220);
+				ops.push({
+					k: "box",
+					x: imgX(w),
+					y,
+					w,
+					h: 54,
+					label: "barcode"
+				});
+				y += 60;
+				i = j;
+			} else if (c === 40 && bytes[i + 2] === 107) {
+				const dlen = u16(bytes[i + 3], bytes[i + 4]);
+				if (bytes[i + 5] === 49 && bytes[i + 6] === 80) {
+					ops.push({
+						k: "box",
+						x: imgX(96),
+						y,
+						w: 96,
+						h: 96,
+						label: "QR"
+					});
+					y += 102;
+				}
+				i = i + 5 + dlen;
+			} else if (c === 104 || c === 119 || c === 72 || c === 102 || c === 66 || c === 69) i += 3;
+			else i += 3;
+		} else if (b === 28) i += bytes[i + 1] === 46 || bytes[i + 1] === 38 ? 2 : 3;
+		else if (b === 10) {
+			if (suppressNextLF) suppressNextLF = false;
+			else {
+				y += cfg.lineHeight * lineMaxScale;
+				lineMaxScale = 1;
+			}
+			x = 0;
+			i += 1;
+		} else if (b === 13) i += 1;
+		else {
+			const ch = decode(b);
+			if (ch && ch !== " ") ops.push({
+				k: "ch",
+				x,
+				y,
+				c: ch,
+				bold,
+				scale: hScale
+			});
+			if (hScale > lineMaxScale) lineMaxScale = hScale;
+			x += cfg.cellWidth * wScale;
+			i += 1;
+		}
+	}
+	return {
+		ops,
+		height: y + cfg.padding
+	};
+}
+/** Render ESC/POS bytes (from chittie `render()` / `encode()`) to a canvas. */
+function renderReceipt(bytes, options) {
+	const cfg = {
+		columns: options.columns ?? 32,
+		cellWidth: options.cellWidth ?? 12,
+		lineHeight: options.lineHeight ?? 26,
+		padding: options.padding ?? 16
+	};
+	const fontFamily = options.fontFamily ?? "monospace";
+	const dots = cfg.columns * cfg.cellWidth;
+	const { ops, height } = parse(bytes, cfg);
+	const canvas = options.createCanvas(dots + cfg.padding * 2, height);
+	const ctx = canvas.getContext("2d");
+	if (!ctx) throw new Error("chittie-preview: createCanvas returned no 2d context");
+	ctx.fillStyle = "#fff";
+	ctx.fillRect(0, 0, canvas.width, canvas.height);
+	ctx.textBaseline = "top";
+	for (const op of ops) if (op.k === "ch") {
+		ctx.fillStyle = "#000";
+		ctx.font = `${op.bold ? "bold " : ""}${18 * op.scale}px ${fontFamily}`;
+		ctx.fillText(op.c, cfg.padding + op.x, op.y);
+	} else if (op.k === "img") {
+		ctx.fillStyle = "#000";
+		for (const [px, py] of op.blacks) ctx.fillRect(cfg.padding + px, py, 1, 1);
+	} else if (op.k === "cut") {
+		ctx.strokeStyle = "#999";
+		ctx.setLineDash([4, 4]);
+		ctx.beginPath();
+		ctx.moveTo(cfg.padding, op.y);
+		ctx.lineTo(cfg.padding + dots, op.y);
+		ctx.stroke();
+		ctx.setLineDash([]);
+	} else {
+		ctx.strokeStyle = "#000";
+		ctx.setLineDash([]);
+		ctx.strokeRect(cfg.padding + op.x, op.y, op.w, op.h);
+		ctx.fillStyle = "#666";
+		ctx.font = `12px ${fontFamily}`;
+		ctx.fillText(op.label, cfg.padding + op.x + 6, op.y + op.h / 2 - 6);
+	}
+	return canvas;
+}
+//#endregion
+export { renderReceipt };

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@angadie/chittie-preview",
+  "version": "0.1.0",
+  "description": "Render a receipt to an image by parsing the ESC/POS bytes chittie emits — a software preview of what the printer will print. Platform-neutral via an injected canvas (browser or @napi-rs/canvas).",
+  "license": "MIT",
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@canvas/image-data": "^1.1.0",
+    "@angadie/chittie": "0.1.0",
+    "@angadie/chittie-text": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx spikes/preview.spike.ts"
+  }
+}