@angadie/chittie-text 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,60 @@
+# @angadie/chittie-text
+
+Smart text for chittie: print **code-page text** when the characters are representable, **auto-rasterize** complex scripts (Sinhala, Tamil, Thai, Devanagari, Arabic, …) via an **injected rasterizer**, and **never silently print `?`**.
+
+Platform-neutral and dependency-light — it never imports canvas or skia. You supply the rasterizer; this package decides *when* to use it.
+
+> Why: thermal printers have no font ROM or code page for Indic/complex scripts, and those scripts need shaping/reordering. The only correct path is to render the text to a bitmap on the host and send it as an image. chittie-text automates the decision and guards against the silent-`?` failure.
+
+## Install
+
+```bash
+pnpm add @angadie/chittie-text
+```
+
+## API
+
+### `needsRaster(text, codepage = 'cp437'): boolean`
+True if any character can't be encoded in `codepage` (it would print as `?`).
+
+```ts
+import { needsRaster } from '@angadie/chittie-text';
+needsRaster('Rs. 250');   // false
+needsRaster('ආයුබෝවන්');  // true
+```
+
+### `TextRasterizer`
+The interface **you** implement with a platform rasterizer:
+
+```ts
+interface TextRasterizer {
+  rasterize(text: string, options: RasterOptions): ImageData;
+}
+```
+
+A web implementation, for example, draws to a `<canvas>` and returns `ctx.getImageData(...)`. On React Native, use `react-native-skia` or a pre-rendered PNG decoded to `ImageData`.
+
+### `smartText(encoder, text, options): void`
+Prints `text` the right way onto a chittie-core encoder:
+
+```ts
+import { smartText } from '@angadie/chittie-text';
+
+smartText(encoder, 'මිල: Rs.250', {
+  rasterizer,            // optional TextRasterizer
+  codepage: 'cp437',     // optional
+  raster: { fontSize: 24, maxWidth: 576 }, // passed to your rasterizer
+});
+```
+
+- encodable → `encoder.text(text)`
+- not encodable + rasterizer → `encoder.image(...)`
+- not encodable + **no** rasterizer → **throws** (no silent `?`)
+
+## With chittie-react
+
+`render(tree, { rasterizer, codepage })` wires this into every `<Text>` automatically — see [`@angadie/chittie-react`](../chittie-react).
+
+## License
+
+MIT.

package/dist/index.d.mts

@@ -0,0 +1,62 @@
+import CodepageEncoder from "@angadie/chittie-codepage";
+
+//#region src/index.d.ts
+/** Code-page name accepted by the encoder — derived from the engine, not duplicated. */
+type Codepage = Parameters<typeof CodepageEncoder.encode>[1];
+/**
+ * True if `text` contains characters the target code page cannot represent
+ * (they would print as "?"). Sinhala, Tamil, and other Indic/complex scripts
+ * have no thermal-printer code page, so they always return true — those runs
+ * must be printed as a raster image (see VENDOR research: non-latin-printing).
+ */
+declare function needsRaster(text: string, codepage?: Codepage): boolean;
+/** Options handed to the injected rasterizer. */
+interface RasterOptions {
+  fontSize?: number;
+  bold?: boolean;
+  font?: string;
+  /** Max pixel width (printer dot width, e.g. 384 for 58mm, 576 for 80mm). */
+  maxWidth?: number;
+}
+/**
+ * You implement this with a platform rasterizer (web canvas, react-native-skia,
+ * or a pre-rendered PNG decoded to ImageData). chittie-text stays platform-neutral
+ * and dependency-free; it never imports canvas/skia.
+ */
+interface TextRasterizer {
+  rasterize(text: string, options: RasterOptions): ImageData;
+}
+/** Minimal slice of the encoder smartText drives (avoids depending on chittie-core). */
+interface EncoderLike {
+  text(value: string): unknown;
+  image(image: ImageData, width: number, height: number): unknown;
+}
+/**
+ * ESC/POS raster requires dimensions that are multiples of 8. Pad right/bottom
+ * with white so any image "just works". Platform-neutral: reuses the input's own
+ * ImageData constructor (browser or @canvas/image-data) — no import. Exported so
+ * chittie-react's <Image> (and others) reuse the same handling.
+ */
+declare function padTo8(img: ImageData): ImageData;
+interface SmartTextOptions {
+  rasterizer?: TextRasterizer;
+  codepage?: Codepage;
+  raster?: RasterOptions;
+}
+/**
+ * Print `text` the right way: as code-page text when it's representable, or as a
+ * rasterized image when it isn't (Sinhala/Tamil/…). If a raster is needed but no
+ * rasterizer was supplied, it throws a clear error instead of silently printing "?".
+ */
+declare function smartText(encoder: EncoderLike, text: string, options?: SmartTextOptions): void;
+/**
+ * Render a two-column row (left flush-left, right flush-right) to one
+ * printer-width image — the correct way to print non-Latin text inside a
+ * table column, since a per-cell image can't sit in a text column. chittie
+ * computes the layout; the injected rasterizer shapes each fragment.
+ */
+declare function rasterizeRow(rasterizer: TextRasterizer, left: string, right: string, options: {
+  dotWidth: number;
+} & RasterOptions): ImageData;
+//#endregion
+export { Codepage, RasterOptions, SmartTextOptions, TextRasterizer, needsRaster, padTo8, rasterizeRow, smartText };

package/dist/index.mjs

@@ -0,0 +1,82 @@
+import CodepageEncoder from "@angadie/chittie-codepage";
+//#region src/index.ts
+/**
+* True if `text` contains characters the target code page cannot represent
+* (they would print as "?"). Sinhala, Tamil, and other Indic/complex scripts
+* have no thermal-printer code page, so they always return true — those runs
+* must be printed as a raster image (see VENDOR research: non-latin-printing).
+*/
+function needsRaster(text, codepage = "cp437") {
+	for (const ch of text) {
+		if (ch === "?") continue;
+		const bytes = CodepageEncoder.encode(ch, codepage);
+		if (bytes.length > 0 && Array.from(bytes).every((b) => b === 63)) return true;
+	}
+	return false;
+}
+/**
+* ESC/POS raster requires dimensions that are multiples of 8. Pad right/bottom
+* with white so any image "just works". Platform-neutral: reuses the input's own
+* ImageData constructor (browser or @canvas/image-data) — no import. Exported so
+* chittie-react's <Image> (and others) reuse the same handling.
+*/
+function padTo8(img) {
+	const { width: w, height: h } = img;
+	const w8 = Math.ceil(w / 8) * 8;
+	const h8 = Math.ceil(h / 8) * 8;
+	if (w8 === w && h8 === h) return img;
+	const out = new Uint8ClampedArray(w8 * h8 * 4).fill(255);
+	for (let y = 0; y < h; y++) out.set(img.data.subarray(y * w * 4, y * w * 4 + w * 4), y * w8 * 4);
+	const Ctor = img.constructor;
+	return new Ctor(out, w8, h8);
+}
+/**
+* Print `text` the right way: as code-page text when it's representable, or as a
+* rasterized image when it isn't (Sinhala/Tamil/…). If a raster is needed but no
+* rasterizer was supplied, it throws a clear error instead of silently printing "?".
+*/
+function smartText(encoder, text, options = {}) {
+	if (!needsRaster(text, options.codepage ?? "cp437")) {
+		encoder.text(text);
+		return;
+	}
+	if (!options.rasterizer) throw new Error(`chittie-text: "${text}" contains characters with no code page (e.g. Sinhala/Tamil). Provide a rasterizer to print it as an image, or remove the unsupported characters. See https://github.com/octalpixel/chittie — non-Latin scripts must be rastered.`);
+	const img = padTo8(options.rasterizer.rasterize(text, options.raster ?? {}));
+	encoder.image(img, img.width, img.height);
+}
+function blank(template, width, height) {
+	const Ctor = template.constructor;
+	return new Ctor(new Uint8ClampedArray(width * height * 4).fill(255), width, height);
+}
+function blit(dst, src, dx, dy) {
+	for (let y = 0; y < src.height; y++) {
+		const drow = ((dy + y) * dst.width + dx) * 4;
+		dst.data.set(src.data.subarray(y * src.width * 4, (y + 1) * src.width * 4), drow);
+	}
+}
+/**
+* Render a two-column row (left flush-left, right flush-right) to one
+* printer-width image — the correct way to print non-Latin text inside a
+* table column, since a per-cell image can't sit in a text column. chittie
+* computes the layout; the injected rasterizer shapes each fragment.
+*/
+function rasterizeRow(rasterizer, left, right, options) {
+	const { dotWidth, ...raster } = options;
+	const l = left ? rasterizer.rasterize(left, raster) : void 0;
+	const r = right ? rasterizer.rasterize(right, raster) : void 0;
+	const template = l ?? r;
+	if (!template) return padTo8(blankImage(8, 8));
+	const height = Math.max(l?.height ?? 0, r?.height ?? 0) || 1;
+	const width = Math.max(dotWidth, (l?.width ?? 0) + (r?.width ?? 0));
+	const out = blank(template, width, height);
+	if (l) blit(out, l, 0, 0);
+	if (r) blit(out, r, width - r.width, 0);
+	return padTo8(out);
+}
+function blankImage(w, h) {
+	const Ctor = globalThis.ImageData;
+	if (!Ctor) throw new Error("chittie-text: no ImageData available for an empty row");
+	return new Ctor(new Uint8ClampedArray(w * h * 4).fill(255), w, h);
+}
+//#endregion
+export { needsRaster, padTo8, rasterizeRow, smartText };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@angadie/chittie-text",
+  "version": "0.1.0",
+  "description": "Smart text for chittie: print code-page text when representable, auto-rasterize complex scripts (Sinhala/Tamil/…) via an injected rasterizer, never silently print '?'. Platform-neutral.",
+  "license": "MIT",
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@angadie/chittie-codepage": "0.1.0"
+  },
+  "devDependencies": {
+    "@canvas/image-data": "^1.1.0",
+    "@angadie/chittie-core": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx spikes/text.spike.ts"
+  }
+}