thermalkit 0.1.0

package/dist/index.js

@@ -0,0 +1,317 @@
+import { loadIcon, loadIcons } from "./chunks/icons-C1OFHE6u.js";
+import { dither } from "./chunks/dither-DyIl72tE.js";
+
+//#region src/svg.ts
+const escapeXml = (s) => String(s ?? "").replace(/[<>&"']/g, (c) => ({
+	"<": "&lt;",
+	">": "&gt;",
+	"&": "&amp;",
+	"\"": "&quot;",
+	"'": "&apos;"
+})[c]);
+/**
+* Resolve a shorthand `family` value (e.g. `'georgia'`) to a CSS font-family stack.
+* Pass-through anything that looks like a real stack already.
+*/
+function resolveFontFamily(family, fallback) {
+	if (!family) return fallback;
+	if (family.includes(",")) return family;
+	const map = {
+		georgia: "Georgia, 'Times New Roman', serif",
+		serif: "Georgia, 'Times New Roman', serif",
+		helvetica: "Helvetica, Arial, sans-serif",
+		sans: "Helvetica, Arial, sans-serif",
+		mono: "Menlo, Consolas, 'Courier New', monospace"
+	};
+	return map[family.toLowerCase()] ?? family;
+}
+/** Naive proportional-font width estimate, good enough for wrap decisions at 10–24 px. */
+function approxWidth(text, size, opts = {}) {
+	const bold = (opts.weight ?? 400) >= 600;
+	const serif = /serif|Georgia/i.test(opts.family ?? "");
+	const factor = bold ? .56 : serif ? .5 : .52;
+	return text.length * size * factor;
+}
+/** Word-wrap text to fit within a given pixel width. */
+function wrapByWidth(text, maxWidth, size, opts = {}) {
+	const words = String(text).split(/\s+/).filter(Boolean);
+	const lines = [];
+	let line = "";
+	for (const w of words) {
+		const test = line ? line + " " + w : w;
+		if (approxWidth(test, size, opts) > maxWidth && line) {
+			lines.push(line);
+			line = w;
+		} else line = test;
+	}
+	if (line) lines.push(line);
+	return lines;
+}
+function buildTextFragment(s, y, defaultFamily, o = { defaultX: 0 }) {
+	const x = o.x ?? o.defaultX;
+	const yy = o.y ?? y;
+	const anchor = o.anchor ? ` text-anchor="${o.anchor}"` : "";
+	const family = resolveFontFamily(o.family, defaultFamily);
+	const size = o.size ?? 14;
+	const weight = o.weight ?? 400;
+	const style = o.style ? ` font-style="${o.style}"` : "";
+	const sp = o.spacing ? ` letter-spacing="${o.spacing}"` : "";
+	const fill = o.fill ?? "#000";
+	return `<text x="${x}" y="${yy}"${anchor} font-family="${family}" font-size="${size}" font-weight="${weight}"${style}${sp} fill="${fill}">${escapeXml(s)}</text>`;
+}
+function buildRuleFragment(y, contentX1, contentX2, o = {}) {
+	const x1 = o.x1 ?? contentX1;
+	const x2 = o.x2 ?? contentX2;
+	const stroke = o.stroke ?? 1;
+	const dash = o.dasharray ? ` stroke-dasharray="${o.dasharray}"` : "";
+	return `<line x1="${x1}" y1="${y}" x2="${x2}" y2="${y}" stroke="#000" stroke-width="${stroke}"${dash}/>`;
+}
+function buildIconFragment(content, x, y, size, fill = "#000") {
+	const scale = size / 256;
+	return `<g transform="translate(${x}, ${y}) scale(${scale.toFixed(4)})" fill="${fill}">${content}</g>`;
+}
+
+//#endregion
+//#region src/page.ts
+const DEFAULT_FONT = "Helvetica, Arial, sans-serif";
+var Page = class {
+	/** Output width in pixels. */
+	width;
+	/** Horizontal padding on left/right. */
+	padding;
+	/** Width available for content (width - 2*padding). */
+	contentWidth;
+	/** Current vertical cursor (mutable). */
+	y = 0;
+	parts = [];
+	icons;
+	defaultFontFamily;
+	constructor(opts = {}) {
+		this.width = opts.width ?? 504;
+		if (this.width % 8 !== 0) throw new Error(`Page width must be a multiple of 8 (got ${this.width})`);
+		this.padding = opts.padding ?? 22;
+		this.contentWidth = this.width - 2 * this.padding;
+		this.defaultFontFamily = opts.defaultFontFamily ?? DEFAULT_FONT;
+		if (Array.isArray(opts.icons)) this.icons = loadIcons(opts.icons);
+		else if (opts.icons && typeof opts.icons === "object") this.icons = { ...opts.icons };
+		else this.icons = {};
+	}
+	/** Move the Y cursor down by `delta` pixels (negative values move up). */
+	advance(delta) {
+		this.y += delta;
+		return this;
+	}
+	/** Alias for `advance` with a documented default of 12 px. */
+	spacer(amount = 12) {
+		this.y += amount;
+		return this;
+	}
+	/**
+	* Draw text at the current Y baseline (or at `opts.y` if given).
+	* Does NOT advance the cursor — the caller controls vertical rhythm.
+	*/
+	text(content, opts = {}) {
+		this.parts.push(buildTextFragment(content, this.y, this.defaultFontFamily, {
+			...opts,
+			defaultX: opts.x ?? this.padding
+		}));
+		return this;
+	}
+	/**
+	* Draw a Phosphor icon (must be pre-loaded into the page's icon map).
+	* Icon top-left is placed at (x, y + dy). Common pattern when placing an
+	* icon next to text is `dy: -size * 0.8` to visually align with the text baseline.
+	*/
+	icon(name, size = 16, opts = {}) {
+		const content = this.icons[name];
+		if (!content) return this;
+		const x = opts.x ?? this.padding;
+		const dy = opts.dy ?? 0;
+		this.parts.push(buildIconFragment(content, x, this.y + dy, size, opts.fill ?? "#000"));
+		return this;
+	}
+	/** Horizontal rule at the current Y. */
+	rule(opts = {}) {
+		this.parts.push(buildRuleFragment(this.y, this.padding, this.width - this.padding, opts));
+		return this;
+	}
+	/** Append a raw SVG fragment at the current Y (escape hatch). */
+	push(fragment) {
+		this.parts.push(fragment);
+		return this;
+	}
+	/**
+	* Embed a PNG buffer at (x, y) sized to (width, height). The PNG is
+	* encoded as a base64 data URI inside an `<image>` element.
+	*
+	* NOTE: at render time sharp downsamples the SVG, which would smear an
+	* already-dithered raster. For halftone posters use the dedicated
+	* `poster()` helper (which composites onto the final raster) — `image()`
+	* is for sharp text / vector content already binarised.
+	*/
+	image(pngBuffer, opts = {}) {
+		const x = opts.x ?? this.padding;
+		const y = opts.y ?? this.y;
+		const w = opts.width;
+		const h = opts.height;
+		const sizeAttrs = [w != null ? `width="${w}"` : "", h != null ? `height="${h}"` : ""].filter(Boolean).join(" ");
+		const b64 = pngBuffer.toString("base64");
+		this.parts.push(`<image x="${x}" y="${y}" ${sizeAttrs} preserveAspectRatio="xMidYMid meet" href="data:image/png;base64,${b64}"/>`);
+		return this;
+	}
+	/**
+	* Run `fn` in a "row context": the cursor is preserved on exit, so any
+	* `text()` / `icon()` calls inside land on the same baseline. Optionally
+	* advance the cursor after.
+	*/
+	row(fn, opts = {}) {
+		const startY = this.y;
+		fn();
+		this.y = startY + (opts.advance ?? 0);
+		return this;
+	}
+	/**
+	* Big centered title with optional italic subtitle below.
+	* Advances the cursor past the block.
+	*/
+	title(text, opts = {}) {
+		const size = opts.size ?? 50;
+		this.text(text, {
+			x: this.width / 2,
+			anchor: "middle",
+			family: opts.family ?? "georgia",
+			size,
+			weight: 700,
+			spacing: opts.spacing ?? 10
+		});
+		if (opts.subtitle) {
+			this.y += Math.round(size * .5);
+			this.text(opts.subtitle, {
+				x: this.width / 2,
+				anchor: "middle",
+				size: 14,
+				style: "italic",
+				spacing: 3
+			});
+		}
+		this.y += Math.round(size * .5);
+		return this;
+	}
+	/**
+	* Section header: optional icon to the left + caps-tracked label.
+	* Advances the cursor past the block.
+	*/
+	section(label, opts = {}) {
+		const size = opts.size ?? 14;
+		const iconSize = opts.iconSize ?? Math.round(size * 1.8);
+		let textX = this.padding;
+		if (opts.icon && this.icons[opts.icon]) {
+			this.icon(opts.icon, iconSize, { dy: -Math.round(iconSize * .75) });
+			textX = this.padding + iconSize + 8;
+		}
+		this.text(label, {
+			x: textX,
+			size,
+			weight: 700,
+			spacing: 3
+		});
+		this.y += Math.round(size * 1.6);
+		return this;
+	}
+	approxWidth(text, size, opts = {}) {
+		return approxWidth(text, size, {
+			family: resolveFontFamily(opts.family, this.defaultFontFamily),
+			weight: opts.weight
+		});
+	}
+	wrapByWidth(text, maxWidth, size, opts = {}) {
+		return wrapByWidth(text, maxWidth, size, {
+			family: resolveFontFamily(opts.family, this.defaultFontFamily),
+			weight: opts.weight
+		});
+	}
+	escapeXml = escapeXml;
+	/** Serialise to a complete SVG document at the current Y as height. */
+	toSvg() {
+		const h = this.y;
+		return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="${this.width}" height="${h}" viewBox="0 0 ${this.width} ${h}">
+<rect width="${this.width}" height="${h}" fill="#fff"/>
+${this.parts.join("\n")}
+</svg>`;
+	}
+	/**
+	* Rasterise the page to a 1-bit-style PNG, ready for the thermal printer.
+	* Renders at high density (so anti-aliasing produces good edges), downsamples
+	* to the final width, then thresholds to pure B&W.
+	*/
+	async toPng(opts = {}) {
+		const { default: sharp } = await import("sharp");
+		return sharp(Buffer.from(this.toSvg()), { density: opts.density ?? 240 }).resize({
+			width: opts.width ?? this.width,
+			fit: "inside"
+		}).flatten({ background: "#ffffff" }).greyscale().threshold(opts.threshold ?? 140).png().toBuffer();
+	}
+	/**
+	* Like `toPng`, but composites a list of already-dithered raster images
+	* onto the thresholded base at exact pixel positions. Use for halftone
+	* posters that would otherwise be smeared by the master rasterisation.
+	*/
+	async toPngWithImages(images, opts = {}) {
+		const { default: sharp } = await import("sharp");
+		const base = await this.toPng(opts);
+		if (!images.length) return base;
+		return sharp(base).composite(images.map((im) => ({
+			input: im.data,
+			left: Math.round(im.x),
+			top: Math.round(im.y)
+		}))).png().toBuffer();
+	}
+	/** Inspect the accumulated SVG fragments (for testing/debugging). */
+	get fragments() {
+		return this.parts;
+	}
+};
+
+//#endregion
+//#region src/poster.ts
+const DEFAULT_USER_AGENT = "thermalkit/0.1";
+async function preparePoster(url, opts = {}) {
+	const { default: sharp } = await import("sharp");
+	const res = await fetch(url, { headers: { "User-Agent": opts.userAgent ?? DEFAULT_USER_AGENT } });
+	if (!res.ok) throw new Error(`Poster HTTP ${res.status} (${url})`);
+	const buf = Buffer.from(await res.arrayBuffer());
+	const meta = await sharp(buf).metadata();
+	const ratio = (meta.height ?? 1) / (meta.width ?? 1);
+	const displayW = opts.width ?? 100;
+	const displayH = Math.round(displayW * ratio);
+	let pipeline = sharp(buf).resize({
+		width: displayW,
+		height: displayH,
+		fit: "fill"
+	}).greyscale();
+	const contrast = opts.contrast ?? "clahe";
+	if (contrast === "clahe") pipeline = pipeline.clahe({
+		width: 8,
+		height: 8,
+		maxSlope: 3
+	}).normalize();
+	else if (contrast === "normalize") pipeline = pipeline.normalize();
+	const { data: grey, info } = await pipeline.raw().toBuffer({ resolveWithObject: true });
+	const algo = opts.dither ?? "atkinson";
+	const dithered = dither(algo, grey, info.width, info.height);
+	const { data, info: outInfo } = await sharp(Buffer.from(dithered.buffer), { raw: {
+		width: info.width,
+		height: info.height,
+		channels: 1
+	} }).png({ compressionLevel: 9 }).toBuffer({ resolveWithObject: true });
+	return {
+		data,
+		width: outInfo.width,
+		height: outInfo.height
+	};
+}
+
+//#endregion
+export { Page, approxWidth, escapeXml, loadIcon, loadIcons, preparePoster, wrapByWidth };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["s: unknown","family: string | undefined","fallback: string","map: Record<string, string>","text: string","size: number","opts: { family?: string; weight?: number }","maxWidth: number","lines: string[]","s: string","y: number","defaultFamily: string","o: TextOptions & { defaultX: number }","contentX1: number","contentX2: number","o: RuleOptions","content: string","x: number","opts: PageOptions","delta: number","content: string","opts: TextOptions","name: string","opts: IconOptions","opts: RuleOptions","fragment: string","pngBuffer: Buffer","opts: ImageOptions","fn: () => void","opts: RowOptions","text: string","opts: { subtitle?: string; size?: number; family?: string; spacing?: number }","label: string","opts: { icon?: string; iconSize?: number; size?: number; spacing?: number }","size: number","maxWidth: number","opts: RenderOptions","images: Array<{ data: Buffer; x: number; y: number }>","url: string","opts: PosterOptions"],"sources":["../src/svg.ts","../src/page.ts","../src/poster.ts"],"sourcesContent":["/**\n * SVG-fragment helpers used internally by Page. Exposed for callers who want\n * to inject custom shapes via `page.push(rawSvg)`.\n */\nimport type { TextOptions, RuleOptions } from './types.js';\n\nexport const escapeXml = (s: unknown): string =>\n  String(s ?? '').replace(/[<>&\"']/g, (c) =>\n    ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '\"': '&quot;', \"'\": '&apos;' }[c] as string));\n\n/**\n * Resolve a shorthand `family` value (e.g. `'georgia'`) to a CSS font-family stack.\n * Pass-through anything that looks like a real stack already.\n */\nexport function resolveFontFamily(family: string | undefined, fallback: string): string {\n  if (!family) return fallback;\n  if (family.includes(',')) return family;\n  const map: Record<string, string> = {\n    georgia: \"Georgia, 'Times New Roman', serif\",\n    serif: \"Georgia, 'Times New Roman', serif\",\n    helvetica: 'Helvetica, Arial, sans-serif',\n    sans: 'Helvetica, Arial, sans-serif',\n    mono: \"Menlo, Consolas, 'Courier New', monospace\",\n  };\n  return map[family.toLowerCase()] ?? family;\n}\n\n/** Naive proportional-font width estimate, good enough for wrap decisions at 10–24 px. */\nexport function approxWidth(\n  text: string,\n  size: number,\n  opts: { family?: string; weight?: number } = {},\n): number {\n  const bold = (opts.weight ?? 400) >= 600;\n  const serif = /serif|Georgia/i.test(opts.family ?? '');\n  const factor = bold ? 0.56 : (serif ? 0.50 : 0.52);\n  return text.length * size * factor;\n}\n\n/** Word-wrap text to fit within a given pixel width. */\nexport function wrapByWidth(\n  text: string,\n  maxWidth: number,\n  size: number,\n  opts: { family?: string; weight?: number } = {},\n): string[] {\n  const words = String(text).split(/\\s+/).filter(Boolean);\n  const lines: string[] = [];\n  let line = '';\n  for (const w of words) {\n    const test = line ? line + ' ' + w : w;\n    if (approxWidth(test, size, opts) > maxWidth && line) {\n      lines.push(line);\n      line = w;\n    } else {\n      line = test;\n    }\n  }\n  if (line) lines.push(line);\n  return lines;\n}\n\nexport function buildTextFragment(\n  s: string,\n  y: number,\n  defaultFamily: string,\n  o: TextOptions & { defaultX: number } = { defaultX: 0 },\n): string {\n  const x = o.x ?? o.defaultX;\n  const yy = o.y ?? y;\n  const anchor = o.anchor ? ` text-anchor=\"${o.anchor}\"` : '';\n  const family = resolveFontFamily(o.family, defaultFamily);\n  const size = o.size ?? 14;\n  const weight = o.weight ?? 400;\n  const style = o.style ? ` font-style=\"${o.style}\"` : '';\n  const sp = o.spacing ? ` letter-spacing=\"${o.spacing}\"` : '';\n  const fill = o.fill ?? '#000';\n  return `<text x=\"${x}\" y=\"${yy}\"${anchor} font-family=\"${family}\" font-size=\"${size}\" font-weight=\"${weight}\"${style}${sp} fill=\"${fill}\">${escapeXml(s)}</text>`;\n}\n\nexport function buildRuleFragment(\n  y: number,\n  contentX1: number,\n  contentX2: number,\n  o: RuleOptions = {},\n): string {\n  const x1 = o.x1 ?? contentX1;\n  const x2 = o.x2 ?? contentX2;\n  const stroke = o.stroke ?? 1;\n  const dash = o.dasharray ? ` stroke-dasharray=\"${o.dasharray}\"` : '';\n  return `<line x1=\"${x1}\" y1=\"${y}\" x2=\"${x2}\" y2=\"${y}\" stroke=\"#000\" stroke-width=\"${stroke}\"${dash}/>`;\n}\n\nexport function buildIconFragment(\n  content: string,\n  x: number,\n  y: number,\n  size: number,\n  fill = '#000',\n): string {\n  const scale = size / 256; // Phosphor uses a 256x256 viewBox\n  return `<g transform=\"translate(${x}, ${y}) scale(${scale.toFixed(4)})\" fill=\"${fill}\">${content}</g>`;\n}\n","/**\n * The Page class — a thermal-receipt-oriented vertical layout builder.\n *\n * Conceptual model: a strip of paper (default 504 px wide for the TM-T88VI)\n * with a Y cursor you push down as you append content. Most calls advance\n * the cursor automatically; reach for `advance()` / `spacer()` when you need\n * manual control.\n */\nimport { loadIcons as loadPhosphorIcons } from './icons.js';\nimport {\n  approxWidth,\n  wrapByWidth,\n  resolveFontFamily,\n  escapeXml,\n  buildTextFragment,\n  buildRuleFragment,\n  buildIconFragment,\n} from './svg.js';\nimport type {\n  PageOptions,\n  TextOptions,\n  IconOptions,\n  RuleOptions,\n  RowOptions,\n  ImageOptions,\n  RenderOptions,\n} from './types.js';\n\nconst DEFAULT_FONT = 'Helvetica, Arial, sans-serif';\n\nexport class Page {\n  /** Output width in pixels. */\n  readonly width: number;\n  /** Horizontal padding on left/right. */\n  readonly padding: number;\n  /** Width available for content (width - 2*padding). */\n  readonly contentWidth: number;\n  /** Current vertical cursor (mutable). */\n  y = 0;\n\n  private readonly parts: string[] = [];\n  private readonly icons: Record<string, string>;\n  private readonly defaultFontFamily: string;\n\n  constructor(opts: PageOptions = {}) {\n    this.width = opts.width ?? 504;\n    if (this.width % 8 !== 0) {\n      // ESC/POS GS v 0 requires the bitmap width to be a multiple of 8.\n      throw new Error(`Page width must be a multiple of 8 (got ${this.width})`);\n    }\n    this.padding = opts.padding ?? 22;\n    this.contentWidth = this.width - 2 * this.padding;\n    this.defaultFontFamily = opts.defaultFontFamily ?? DEFAULT_FONT;\n\n    if (Array.isArray(opts.icons)) {\n      this.icons = loadPhosphorIcons(opts.icons);\n    } else if (opts.icons && typeof opts.icons === 'object') {\n      this.icons = { ...opts.icons };\n    } else {\n      this.icons = {};\n    }\n  }\n\n  // ------------------------------------------------------------------\n  //   Cursor control\n  // ------------------------------------------------------------------\n\n  /** Move the Y cursor down by `delta` pixels (negative values move up). */\n  advance(delta: number): this {\n    this.y += delta;\n    return this;\n  }\n\n  /** Alias for `advance` with a documented default of 12 px. */\n  spacer(amount = 12): this {\n    this.y += amount;\n    return this;\n  }\n\n  // ------------------------------------------------------------------\n  //   Primitives\n  // ------------------------------------------------------------------\n\n  /**\n   * Draw text at the current Y baseline (or at `opts.y` if given).\n   * Does NOT advance the cursor — the caller controls vertical rhythm.\n   */\n  text(content: string, opts: TextOptions = {}): this {\n    this.parts.push(\n      buildTextFragment(content, this.y, this.defaultFontFamily, {\n        ...opts,\n        defaultX: opts.x ?? this.padding,\n      }),\n    );\n    return this;\n  }\n\n  /**\n   * Draw a Phosphor icon (must be pre-loaded into the page's icon map).\n   * Icon top-left is placed at (x, y + dy). Common pattern when placing an\n   * icon next to text is `dy: -size * 0.8` to visually align with the text baseline.\n   */\n  icon(name: string, size = 16, opts: IconOptions = {}): this {\n    const content = this.icons[name];\n    if (!content) return this; // graceful no-op\n    const x = opts.x ?? this.padding;\n    const dy = opts.dy ?? 0;\n    this.parts.push(buildIconFragment(content, x, this.y + dy, size, opts.fill ?? '#000'));\n    return this;\n  }\n\n  /** Horizontal rule at the current Y. */\n  rule(opts: RuleOptions = {}): this {\n    this.parts.push(\n      buildRuleFragment(this.y, this.padding, this.width - this.padding, opts),\n    );\n    return this;\n  }\n\n  /** Append a raw SVG fragment at the current Y (escape hatch). */\n  push(fragment: string): this {\n    this.parts.push(fragment);\n    return this;\n  }\n\n  /**\n   * Embed a PNG buffer at (x, y) sized to (width, height). The PNG is\n   * encoded as a base64 data URI inside an `<image>` element.\n   *\n   * NOTE: at render time sharp downsamples the SVG, which would smear an\n   * already-dithered raster. For halftone posters use the dedicated\n   * `poster()` helper (which composites onto the final raster) — `image()`\n   * is for sharp text / vector content already binarised.\n   */\n  image(pngBuffer: Buffer, opts: ImageOptions = {}): this {\n    const x = opts.x ?? this.padding;\n    const y = opts.y ?? this.y;\n    const w = opts.width;\n    const h = opts.height;\n    const sizeAttrs = [\n      w != null ? `width=\"${w}\"` : '',\n      h != null ? `height=\"${h}\"` : '',\n    ].filter(Boolean).join(' ');\n    const b64 = pngBuffer.toString('base64');\n    this.parts.push(\n      `<image x=\"${x}\" y=\"${y}\" ${sizeAttrs} preserveAspectRatio=\"xMidYMid meet\" href=\"data:image/png;base64,${b64}\"/>`,\n    );\n    return this;\n  }\n\n  // ------------------------------------------------------------------\n  //   Composition helpers\n  // ------------------------------------------------------------------\n\n  /**\n   * Run `fn` in a \"row context\": the cursor is preserved on exit, so any\n   * `text()` / `icon()` calls inside land on the same baseline. Optionally\n   * advance the cursor after.\n   */\n  row(fn: () => void, opts: RowOptions = {}): this {\n    const startY = this.y;\n    fn();\n    this.y = startY + (opts.advance ?? 0);\n    return this;\n  }\n\n  // ------------------------------------------------------------------\n  //   Higher-level patterns\n  // ------------------------------------------------------------------\n\n  /**\n   * Big centered title with optional italic subtitle below.\n   * Advances the cursor past the block.\n   */\n  title(text: string, opts: { subtitle?: string; size?: number; family?: string; spacing?: number } = {}): this {\n    const size = opts.size ?? 50;\n    this.text(text, {\n      x: this.width / 2,\n      anchor: 'middle',\n      family: opts.family ?? 'georgia',\n      size,\n      weight: 700,\n      spacing: opts.spacing ?? 10,\n    });\n    if (opts.subtitle) {\n      this.y += Math.round(size * 0.5);\n      this.text(opts.subtitle, {\n        x: this.width / 2,\n        anchor: 'middle',\n        size: 14,\n        style: 'italic',\n        spacing: 3,\n      });\n    }\n    this.y += Math.round(size * 0.5);\n    return this;\n  }\n\n  /**\n   * Section header: optional icon to the left + caps-tracked label.\n   * Advances the cursor past the block.\n   */\n  section(\n    label: string,\n    opts: { icon?: string; iconSize?: number; size?: number; spacing?: number } = {},\n  ): this {\n    const size = opts.size ?? 14;\n    const iconSize = opts.iconSize ?? Math.round(size * 1.8);\n    let textX = this.padding;\n    if (opts.icon && this.icons[opts.icon]) {\n      this.icon(opts.icon, iconSize, { dy: -Math.round(iconSize * 0.75) });\n      textX = this.padding + iconSize + 8;\n    }\n    this.text(label, {\n      x: textX,\n      size,\n      weight: 700,\n      spacing: 3,\n    });\n    this.y += Math.round(size * 1.6);\n    return this;\n  }\n\n  // ------------------------------------------------------------------\n  //   Text-measurement helpers (proxied to the standalone fns)\n  // ------------------------------------------------------------------\n\n  approxWidth(text: string, size: number, opts: TextOptions = {}): number {\n    return approxWidth(text, size, { family: resolveFontFamily(opts.family, this.defaultFontFamily), weight: opts.weight });\n  }\n\n  wrapByWidth(text: string, maxWidth: number, size: number, opts: TextOptions = {}): string[] {\n    return wrapByWidth(text, maxWidth, size, { family: resolveFontFamily(opts.family, this.defaultFontFamily), weight: opts.weight });\n  }\n\n  // Re-exposed for users assembling raw fragments via `page.push(...)`.\n  escapeXml = escapeXml;\n\n  // ------------------------------------------------------------------\n  //   Serialization\n  // ------------------------------------------------------------------\n\n  /** Serialise to a complete SVG document at the current Y as height. */\n  toSvg(): string {\n    const h = this.y;\n    return `<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"${this.width}\" height=\"${h}\" viewBox=\"0 0 ${this.width} ${h}\">\n<rect width=\"${this.width}\" height=\"${h}\" fill=\"#fff\"/>\n${this.parts.join('\\n')}\n</svg>`;\n  }\n\n  /**\n   * Rasterise the page to a 1-bit-style PNG, ready for the thermal printer.\n   * Renders at high density (so anti-aliasing produces good edges), downsamples\n   * to the final width, then thresholds to pure B&W.\n   */\n  async toPng(opts: RenderOptions = {}): Promise<Buffer> {\n    const { default: sharp } = await import('sharp');\n    return sharp(Buffer.from(this.toSvg()), { density: opts.density ?? 240 })\n      .resize({ width: opts.width ?? this.width, fit: 'inside' })\n      .flatten({ background: '#ffffff' })\n      .greyscale()\n      .threshold(opts.threshold ?? 140)\n      .png()\n      .toBuffer();\n  }\n\n  /**\n   * Like `toPng`, but composites a list of already-dithered raster images\n   * onto the thresholded base at exact pixel positions. Use for halftone\n   * posters that would otherwise be smeared by the master rasterisation.\n   */\n  async toPngWithImages(\n    images: Array<{ data: Buffer; x: number; y: number }>,\n    opts: RenderOptions = {},\n  ): Promise<Buffer> {\n    const { default: sharp } = await import('sharp');\n    const base = await this.toPng(opts);\n    if (!images.length) return base;\n    return sharp(base)\n      .composite(images.map(im => ({\n        input: im.data,\n        left: Math.round(im.x),\n        top: Math.round(im.y),\n      })))\n      .png()\n      .toBuffer();\n  }\n\n  /** Inspect the accumulated SVG fragments (for testing/debugging). */\n  get fragments(): readonly string[] {\n    return this.parts;\n  }\n}\n","/**\n * Halftone poster pipeline: URL → 1-bit dithered PNG, ready to composite onto\n * a rasterised page.\n *\n * Steps:\n *   1. Download bytes (with optional User-Agent).\n *   2. Resize to the exact target display size (no scaling during render).\n *   3. CLAHE for local contrast (rescues dark posters), then normalize.\n *   4. Dither (Atkinson by default).\n *   5. Re-encode as a clean greyscale PNG with exactly 0 / 255 values.\n *\n * The output PNG is at the EXACT pixel dimensions you'll display it at on\n * the page — no further scaling. That's the trick that keeps the dot\n * pattern crisp through the master rasterisation step (use `page.toPngWithImages`).\n */\nimport { dither as runDither } from './dither.js';\nimport type { PosterOptions, PreparedImage } from './types.js';\n\nconst DEFAULT_USER_AGENT = 'thermalkit/0.1';\n\nexport async function preparePoster(\n  url: string,\n  opts: PosterOptions = {},\n): Promise<PreparedImage> {\n  const { default: sharp } = await import('sharp');\n\n  const res = await fetch(url, {\n    headers: { 'User-Agent': opts.userAgent ?? DEFAULT_USER_AGENT },\n  });\n  if (!res.ok) throw new Error(`Poster HTTP ${res.status} (${url})`);\n  const buf = Buffer.from(await res.arrayBuffer());\n\n  // Compute the exact target H/W from the source aspect ratio.\n  const meta = await sharp(buf).metadata();\n  const ratio = (meta.height ?? 1) / (meta.width ?? 1);\n  const displayW = opts.width ?? 100;\n  const displayH = Math.round(displayW * ratio);\n\n  let pipeline = sharp(buf)\n    .resize({ width: displayW, height: displayH, fit: 'fill' })\n    .greyscale();\n\n  const contrast = opts.contrast ?? 'clahe';\n  if (contrast === 'clahe') {\n    pipeline = pipeline.clahe({ width: 8, height: 8, maxSlope: 3 }).normalize();\n  } else if (contrast === 'normalize') {\n    pipeline = pipeline.normalize();\n  }\n\n  const { data: grey, info } = await pipeline.raw().toBuffer({ resolveWithObject: true });\n\n  const algo = opts.dither ?? 'atkinson';\n  const dithered = runDither(algo, grey, info.width, info.height);\n\n  const { data, info: outInfo } = await sharp(Buffer.from(dithered.buffer), {\n    raw: { width: info.width, height: info.height, channels: 1 },\n  })\n    .png({ compressionLevel: 9 })\n    .toBuffer({ resolveWithObject: true });\n\n  return { data, width: outInfo.width, height: outInfo.height };\n}\n"],"mappings":"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"}

package/dist/page.d.ts

@@ -0,0 +1,94 @@
+import type { PageOptions, TextOptions, IconOptions, RuleOptions, RowOptions, ImageOptions, RenderOptions } from './types.js';
+export declare class Page {
+    /** Output width in pixels. */
+    readonly width: number;
+    /** Horizontal padding on left/right. */
+    readonly padding: number;
+    /** Width available for content (width - 2*padding). */
+    readonly contentWidth: number;
+    /** Current vertical cursor (mutable). */
+    y: number;
+    private readonly parts;
+    private readonly icons;
+    private readonly defaultFontFamily;
+    constructor(opts?: PageOptions);
+    /** Move the Y cursor down by `delta` pixels (negative values move up). */
+    advance(delta: number): this;
+    /** Alias for `advance` with a documented default of 12 px. */
+    spacer(amount?: number): this;
+    /**
+     * Draw text at the current Y baseline (or at `opts.y` if given).
+     * Does NOT advance the cursor — the caller controls vertical rhythm.
+     */
+    text(content: string, opts?: TextOptions): this;
+    /**
+     * Draw a Phosphor icon (must be pre-loaded into the page's icon map).
+     * Icon top-left is placed at (x, y + dy). Common pattern when placing an
+     * icon next to text is `dy: -size * 0.8` to visually align with the text baseline.
+     */
+    icon(name: string, size?: number, opts?: IconOptions): this;
+    /** Horizontal rule at the current Y. */
+    rule(opts?: RuleOptions): this;
+    /** Append a raw SVG fragment at the current Y (escape hatch). */
+    push(fragment: string): this;
+    /**
+     * Embed a PNG buffer at (x, y) sized to (width, height). The PNG is
+     * encoded as a base64 data URI inside an `<image>` element.
+     *
+     * NOTE: at render time sharp downsamples the SVG, which would smear an
+     * already-dithered raster. For halftone posters use the dedicated
+     * `poster()` helper (which composites onto the final raster) — `image()`
+     * is for sharp text / vector content already binarised.
+     */
+    image(pngBuffer: Buffer, opts?: ImageOptions): this;
+    /**
+     * Run `fn` in a "row context": the cursor is preserved on exit, so any
+     * `text()` / `icon()` calls inside land on the same baseline. Optionally
+     * advance the cursor after.
+     */
+    row(fn: () => void, opts?: RowOptions): this;
+    /**
+     * Big centered title with optional italic subtitle below.
+     * Advances the cursor past the block.
+     */
+    title(text: string, opts?: {
+        subtitle?: string;
+        size?: number;
+        family?: string;
+        spacing?: number;
+    }): this;
+    /**
+     * Section header: optional icon to the left + caps-tracked label.
+     * Advances the cursor past the block.
+     */
+    section(label: string, opts?: {
+        icon?: string;
+        iconSize?: number;
+        size?: number;
+        spacing?: number;
+    }): this;
+    approxWidth(text: string, size: number, opts?: TextOptions): number;
+    wrapByWidth(text: string, maxWidth: number, size: number, opts?: TextOptions): string[];
+    escapeXml: (s: unknown) => string;
+    /** Serialise to a complete SVG document at the current Y as height. */
+    toSvg(): string;
+    /**
+     * Rasterise the page to a 1-bit-style PNG, ready for the thermal printer.
+     * Renders at high density (so anti-aliasing produces good edges), downsamples
+     * to the final width, then thresholds to pure B&W.
+     */
+    toPng(opts?: RenderOptions): Promise<Buffer>;
+    /**
+     * Like `toPng`, but composites a list of already-dithered raster images
+     * onto the thresholded base at exact pixel positions. Use for halftone
+     * posters that would otherwise be smeared by the master rasterisation.
+     */
+    toPngWithImages(images: Array<{
+        data: Buffer;
+        x: number;
+        y: number;
+    }>, opts?: RenderOptions): Promise<Buffer>;
+    /** Inspect the accumulated SVG fragments (for testing/debugging). */
+    get fragments(): readonly string[];
+}
+//# sourceMappingURL=page.d.ts.map

package/dist/page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../src/page.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,WAAW,EACX,WAAW,EACX,UAAU,EACV,YAAY,EACZ,aAAa,EACd,MAAM,YAAY,CAAC;AAIpB,qBAAa,IAAI;IACf,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,yCAAyC;IACzC,CAAC,SAAK;IAEN,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAC/C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAE/B,IAAI,GAAE,WAAgB;IAuBlC,0EAA0E;IAC1E,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK5B,8DAA8D;IAC9D,MAAM,CAAC,MAAM,SAAK,GAAG,IAAI;IASzB;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,IAAI;IAUnD;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAK,EAAE,IAAI,GAAE,WAAgB,GAAG,IAAI;IAS3D,wCAAwC;IACxC,IAAI,CAAC,IAAI,GAAE,WAAgB,GAAG,IAAI;IAOlC,iEAAiE;IACjE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAK5B;;;;;;;;OAQG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,IAAI;IAoBvD;;;;OAIG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,IAAI,GAAE,UAAe,GAAG,IAAI;IAWhD;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,IAAI;IAwB7G;;;OAGG;IACH,OAAO,CACL,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/E,IAAI;IAsBP,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,MAAM;IAIvE,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,MAAM,EAAE;IAK3F,SAAS,yBAAa;IAMtB,uEAAuE;IACvE,KAAK,IAAI,MAAM;IASf;;;;OAIG;IACG,KAAK,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAWtD;;;;OAIG;IACG,eAAe,CACnB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,EACrD,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,MAAM,CAAC;IAclB,qEAAqE;IACrE,IAAI,SAAS,IAAI,SAAS,MAAM,EAAE,CAEjC;CACF"}

package/dist/poster.d.ts

@@ -0,0 +1,3 @@
+import type { PosterOptions, PreparedImage } from './types.js';
+export declare function preparePoster(url: string, opts?: PosterOptions): Promise<PreparedImage>;
+//# sourceMappingURL=poster.d.ts.map

package/dist/poster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poster.d.ts","sourceRoot":"","sources":["../src/poster.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI/D,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,aAAa,CAAC,CAsCxB"}

package/dist/printer.d.ts

@@ -0,0 +1,49 @@
+export interface EpsonPrinterOptions {
+    /** Hostname or IP. */
+    host: string;
+    /** TCP port (default 9100 — the JetDirect/raw port). */
+    port?: number;
+    /** TCP timeout in milliseconds. Default 15000. */
+    timeout?: number;
+}
+export interface PrintOptions {
+    /**
+     * Persistent print-density adjustment (-50..+50, percent offset from factory).
+     * Sent as `GS | n` (level 0..8). NB: this setting persists in the printer's
+     * memory across power cycles until changed again — use `0` to reset.
+     */
+    density?: number;
+    /** Issue a paper cut at the end. Default true. */
+    cut?: boolean;
+    /** Alignment for the embedded raster. Default 'center'. */
+    align?: 'left' | 'center' | 'right';
+}
+/**
+ * Build the ESC/POS bytes for the `GS | n` print-density command.
+ *   n=0 → -50%, n=4 → 0% (factory default), n=8 → +50%.
+ */
+export declare function setPrintDensityBytes(percent: number): Buffer;
+/**
+ * Epson TM-T88VI and compatible thermal printers over TCP/IP.
+ * Reuse one instance across multiple prints if you want.
+ */
+export declare class EpsonPrinter {
+    readonly host: string;
+    readonly port: number;
+    readonly timeout: number;
+    constructor(opts: EpsonPrinterOptions);
+    private build;
+    /** Probe connectivity (TCP connect). */
+    isReachable(): Promise<boolean>;
+    /**
+     * Send a rasterised PNG to the printer. Optionally adjusts persistent density
+     * and / or aligns the image. Always followed by a blank line and (by default)
+     * a paper cut.
+     */
+    print(png: Buffer, opts?: PrintOptions): Promise<void>;
+    /** Send arbitrary ESC/POS bytes. Useful for one-off commands. */
+    raw(bytes: Buffer): Promise<void>;
+    /** Convenience: change density without printing anything. Persistent. */
+    setDensity(percent: number): Promise<void>;
+}
+//# sourceMappingURL=printer.d.ts.map

package/dist/printer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"printer.d.ts","sourceRoot":"","sources":["../src/printer.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,mBAAmB;IAClC,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;CACrC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI5D;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,IAAI,EAAE,mBAAmB;IAMrC,OAAO,CAAC,KAAK;IASb,wCAAwC;IAClC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAQrC;;;;OAIG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBhE,iEAAiE;IAC3D,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvC,yEAAyE;IACnE,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGjD"}

package/dist/printer.js

@@ -0,0 +1,77 @@
+import { printer, types } from "node-thermal-printer";
+
+//#region src/printer.ts
+/**
+* Build the ESC/POS bytes for the `GS | n` print-density command.
+*   n=0 → -50%, n=4 → 0% (factory default), n=8 → +50%.
+*/
+function setPrintDensityBytes(percent) {
+	const clamped = Math.max(-50, Math.min(50, Math.round(percent)));
+	const level = Math.round((clamped + 50) / 100 * 8);
+	return Buffer.from([
+		29,
+		124,
+		level
+	]);
+}
+/**
+* Epson TM-T88VI and compatible thermal printers over TCP/IP.
+* Reuse one instance across multiple prints if you want.
+*/
+var EpsonPrinter = class {
+	host;
+	port;
+	timeout;
+	constructor(opts) {
+		this.host = opts.host;
+		this.port = opts.port ?? 9100;
+		this.timeout = opts.timeout ?? 15e3;
+	}
+	build() {
+		return new printer({
+			type: types.EPSON,
+			interface: `tcp://${this.host}:${this.port}`,
+			width: 42,
+			options: { timeout: this.timeout }
+		});
+	}
+	/** Probe connectivity (TCP connect). */
+	async isReachable() {
+		try {
+			return await this.build().isPrinterConnected();
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Send a rasterised PNG to the printer. Optionally adjusts persistent density
+	* and / or aligns the image. Always followed by a blank line and (by default)
+	* a paper cut.
+	*/
+	async print(png, opts = {}) {
+		const printer$1 = this.build();
+		if (!await printer$1.isPrinterConnected()) throw new Error(`Printer unreachable at ${this.host}:${this.port}`);
+		if (opts.density != null) await printer$1.raw(setPrintDensityBytes(opts.density));
+		const align = opts.align ?? "center";
+		if (align === "left") printer$1.alignLeft();
+		else if (align === "right") printer$1.alignRight();
+		else printer$1.alignCenter();
+		await printer$1.printImageBuffer(png);
+		printer$1.println("");
+		if (opts.cut !== false) printer$1.cut();
+		await printer$1.execute();
+	}
+	/** Send arbitrary ESC/POS bytes. Useful for one-off commands. */
+	async raw(bytes) {
+		const printer$1 = this.build();
+		await printer$1.raw(bytes);
+	}
+	/** Convenience: change density without printing anything. Persistent. */
+	async setDensity(percent) {
+		await this.raw(setPrintDensityBytes(percent));
+	}
+};
+
+//#endregion
+export { EpsonPrinter, setPrintDensityBytes };
+//# sourceMappingURL=printer.js.map

package/dist/printer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"printer.js","names":["percent: number","opts: EpsonPrinterOptions","ThermalPrinter","PrinterTypes","png: Buffer","opts: PrintOptions","printer","bytes: Buffer"],"sources":["../src/printer.ts"],"sourcesContent":["/**\n * Thin TCP wrapper around node-thermal-printer, with a few thermal-kit\n * conveniences (density command, raw escape hatch).\n *\n * Imported as `thermalkit/printer` so it's optional — pure image-generation\n * users don't pay for `node-thermal-printer`.\n */\nimport { printer as ThermalPrinter, types as PrinterTypes } from 'node-thermal-printer';\n\nexport interface EpsonPrinterOptions {\n  /** Hostname or IP. */\n  host: string;\n  /** TCP port (default 9100 — the JetDirect/raw port). */\n  port?: number;\n  /** TCP timeout in milliseconds. Default 15000. */\n  timeout?: number;\n}\n\nexport interface PrintOptions {\n  /**\n   * Persistent print-density adjustment (-50..+50, percent offset from factory).\n   * Sent as `GS | n` (level 0..8). NB: this setting persists in the printer's\n   * memory across power cycles until changed again — use `0` to reset.\n   */\n  density?: number;\n  /** Issue a paper cut at the end. Default true. */\n  cut?: boolean;\n  /** Alignment for the embedded raster. Default 'center'. */\n  align?: 'left' | 'center' | 'right';\n}\n\n/**\n * Build the ESC/POS bytes for the `GS | n` print-density command.\n *   n=0 → -50%, n=4 → 0% (factory default), n=8 → +50%.\n */\nexport function setPrintDensityBytes(percent: number): Buffer {\n  const clamped = Math.max(-50, Math.min(50, Math.round(percent)));\n  const level = Math.round(((clamped + 50) / 100) * 8);\n  return Buffer.from([0x1d, 0x7c, level]);\n}\n\n/**\n * Epson TM-T88VI and compatible thermal printers over TCP/IP.\n * Reuse one instance across multiple prints if you want.\n */\nexport class EpsonPrinter {\n  readonly host: string;\n  readonly port: number;\n  readonly timeout: number;\n\n  constructor(opts: EpsonPrinterOptions) {\n    this.host = opts.host;\n    this.port = opts.port ?? 9100;\n    this.timeout = opts.timeout ?? 15000;\n  }\n\n  private build(): InstanceType<typeof ThermalPrinter> {\n    return new ThermalPrinter({\n      type: PrinterTypes.EPSON,\n      interface: `tcp://${this.host}:${this.port}`,\n      width: 42,\n      options: { timeout: this.timeout },\n    });\n  }\n\n  /** Probe connectivity (TCP connect). */\n  async isReachable(): Promise<boolean> {\n    try {\n      return await this.build().isPrinterConnected();\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Send a rasterised PNG to the printer. Optionally adjusts persistent density\n   * and / or aligns the image. Always followed by a blank line and (by default)\n   * a paper cut.\n   */\n  async print(png: Buffer, opts: PrintOptions = {}): Promise<void> {\n    const printer = this.build();\n    if (!(await printer.isPrinterConnected())) {\n      throw new Error(`Printer unreachable at ${this.host}:${this.port}`);\n    }\n    if (opts.density != null) {\n      await printer.raw(setPrintDensityBytes(opts.density));\n    }\n    const align = opts.align ?? 'center';\n    if (align === 'left')        printer.alignLeft();\n    else if (align === 'right')  printer.alignRight();\n    else                         printer.alignCenter();\n\n    await printer.printImageBuffer(png);\n    printer.println('');\n    if (opts.cut !== false) printer.cut();\n    await printer.execute();\n  }\n\n  /** Send arbitrary ESC/POS bytes. Useful for one-off commands. */\n  async raw(bytes: Buffer): Promise<void> {\n    const printer = this.build();\n    await printer.raw(bytes);\n  }\n\n  /** Convenience: change density without printing anything. Persistent. */\n  async setDensity(percent: number): Promise<void> {\n    await this.raw(setPrintDensityBytes(percent));\n  }\n}\n"],"mappings":";;;;;;;AAmCA,SAAgB,qBAAqBA,SAAyB;CAC5D,MAAM,UAAU,KAAK,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,MAAM,QAAQ,CAAC,CAAC;CAChE,MAAM,QAAQ,KAAK,OAAQ,UAAU,MAAM,MAAO,EAAE;AACpD,QAAO,OAAO,KAAK;EAAC;EAAM;EAAM;CAAM,EAAC;AACxC;;;;;AAMD,IAAa,eAAb,MAA0B;CACxB,AAAS;CACT,AAAS;CACT,AAAS;CAET,YAAYC,MAA2B;AACrC,OAAK,OAAO,KAAK;AACjB,OAAK,OAAO,KAAK,QAAQ;AACzB,OAAK,UAAU,KAAK,WAAW;CAChC;CAED,AAAQ,QAA6C;AACnD,SAAO,IAAIC,QAAe;GACxB,MAAMC,MAAa;GACnB,YAAY,QAAQ,KAAK,KAAK,GAAG,KAAK,KAAK;GAC3C,OAAO;GACP,SAAS,EAAE,SAAS,KAAK,QAAS;EACnC;CACF;;CAGD,MAAM,cAAgC;AACpC,MAAI;AACF,UAAO,MAAM,KAAK,OAAO,CAAC,oBAAoB;EAC/C,QAAO;AACN,UAAO;EACR;CACF;;;;;;CAOD,MAAM,MAAMC,KAAaC,OAAqB,CAAE,GAAiB;EAC/D,MAAMC,YAAU,KAAK,OAAO;AAC5B,OAAM,MAAM,UAAQ,oBAAoB,CACtC,OAAM,IAAI,OAAO,yBAAyB,KAAK,KAAK,GAAG,KAAK,KAAK;AAEnE,MAAI,KAAK,WAAW,KAClB,OAAM,UAAQ,IAAI,qBAAqB,KAAK,QAAQ,CAAC;EAEvD,MAAM,QAAQ,KAAK,SAAS;AAC5B,MAAI,UAAU,OAAe,WAAQ,WAAW;WACvC,UAAU,QAAU,WAAQ,YAAY;MACpB,WAAQ,aAAa;AAElD,QAAM,UAAQ,iBAAiB,IAAI;AACnC,YAAQ,QAAQ,GAAG;AACnB,MAAI,KAAK,QAAQ,MAAO,WAAQ,KAAK;AACrC,QAAM,UAAQ,SAAS;CACxB;;CAGD,MAAM,IAAIC,OAA8B;EACtC,MAAMD,YAAU,KAAK,OAAO;AAC5B,QAAM,UAAQ,IAAI,MAAM;CACzB;;CAGD,MAAM,WAAWN,SAAgC;AAC/C,QAAM,KAAK,IAAI,qBAAqB,QAAQ,CAAC;CAC9C;AACF"}

package/dist/svg.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SVG-fragment helpers used internally by Page. Exposed for callers who want
+ * to inject custom shapes via `page.push(rawSvg)`.
+ */
+import type { TextOptions, RuleOptions } from './types.js';
+export declare const escapeXml: (s: unknown) => string;
+/**
+ * Resolve a shorthand `family` value (e.g. `'georgia'`) to a CSS font-family stack.
+ * Pass-through anything that looks like a real stack already.
+ */
+export declare function resolveFontFamily(family: string | undefined, fallback: string): string;
+/** Naive proportional-font width estimate, good enough for wrap decisions at 10–24 px. */
+export declare function approxWidth(text: string, size: number, opts?: {
+    family?: string;
+    weight?: number;
+}): number;
+/** Word-wrap text to fit within a given pixel width. */
+export declare function wrapByWidth(text: string, maxWidth: number, size: number, opts?: {
+    family?: string;
+    weight?: number;
+}): string[];
+export declare function buildTextFragment(s: string, y: number, defaultFamily: string, o?: TextOptions & {
+    defaultX: number;
+}): string;
+export declare function buildRuleFragment(y: number, contentX1: number, contentX2: number, o?: RuleOptions): string;
+export declare function buildIconFragment(content: string, x: number, y: number, size: number, fill?: string): string;
+//# sourceMappingURL=svg.d.ts.map

package/dist/svg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"svg.d.ts","sourceRoot":"","sources":["../src/svg.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE3D,eAAO,MAAM,SAAS,GAAI,GAAG,OAAO,KAAG,MAEqD,CAAC;AAE7F;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWtF;AAED,0FAA0F;AAC1F,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9C,MAAM,CAKR;AAED,wDAAwD;AACxD,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9C,MAAM,EAAE,CAeV;AAED,wBAAgB,iBAAiB,CAC/B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,aAAa,EAAE,MAAM,EACrB,CAAC,GAAE,WAAW,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAoB,GACtD,MAAM,CAWR;AAED,wBAAgB,iBAAiB,CAC/B,CAAC,EAAE,MAAM,EACT,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,CAAC,GAAE,WAAgB,GAClB,MAAM,CAMR;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,IAAI,EAAE,MAAM,EACZ,IAAI,SAAS,GACZ,MAAM,CAGR"}