portakal 0.3.0 → 0.4.0

package/README.md

@@ -30,37 +30,51 @@
 npm install portakal
 ```
 
-### Product label (text + barcode + QR + shapes)
+### Product label
 
 ```ts
-import { label } from "portakal";
+import { label } from "portakal/core";
+import { tsc } from "portakal/lang/tsc";
 
-const cmd = label({ width: 40, height: 30, unit: "mm" })
+const myLabel = label({ width: 40, height: 30, unit: "mm" })
   .text("ACME Corp", { x: 10, y: 10, size: 2 })
-  .text("SKU: PRD-00123", { x: 10, y: 35, font: "2" })
-  .barcode("123456789012", { type: "ean13", x: 10, y: 60, height: 50 })
-  .qrcode("https://acme.com/prd/123", { x: 220, y: 60, ecc: "M", size: 5 })
-  .line({ x1: 5, y1: 55, x2: 310, y2: 55, thickness: 1 })
-  .box({ x: 5, y: 5, width: 310, height: 230, thickness: 2 })
-  .toTSC();
+  .text("SKU: PRD-00123", { x: 10, y: 35 })
+  .line({ x1: 5, y1: 55, x2: 310, y2: 55 })
+  .box({ x: 5, y: 5, width: 310, height: 230, thickness: 2 });
+
+const code = tsc.compile(myLabel); // TSC/TSPL2 commands
+const svg = tsc.preview(myLabel); // SVG preview with TSC font metrics
 ```
 
-### Shipping label (multiple text fields + barcode)
+### Same label → any language
 
 ```ts
-const shipping = label({ width: 100, height: 150, unit: "mm" })
-  .text("FROM: Warehouse A", { x: 10, y: 10 })
-  .text("TO: John Doe", { x: 10, y: 30, size: 2 })
-  .text("123 Main St, New York, NY 10001", { x: 10, y: 55 })
-  .barcode("SSCC00012345678901234", { type: "code128", x: 10, y: 80, height: 80 })
-  .qrcode("https://track.example.com/PKG123", { x: 300, y: 80, size: 8 })
-  .line({ x1: 5, y1: 70, x2: 780, y2: 70, thickness: 2 })
-  .toZPL();
+import { label } from "portakal/core";
+import { tsc } from "portakal/lang/tsc";
+import { zpl } from "portakal/lang/zpl";
+import { epl } from "portakal/lang/epl";
+import { escpos } from "portakal/lang/escpos";
+
+const myLabel = label({ width: 40, height: 30, unit: "mm" }).text("Hello World", {
+  x: 10,
+  y: 10,
+  size: 2,
+});
+
+tsc.compile(myLabel); // TSC/TSPL2  — TSC, Gprinter, Xprinter, iDPRT
+zpl.compile(myLabel); // Zebra ZPL II — GK420, ZT410, ZD620
+epl.compile(myLabel); // Eltron EPL2 — LP/TLP 2824, GX420, ZD220
+escpos.compile(myLabel); // ESC/POS — Epson, Bixolon, Star, Citizen (Uint8Array)
 ```
 
-### Receipt (ESC/POS — text, barcode, QR)
+Only the imported languages enter your bundle — 100% tree-shakeable.
+
+### Receipt (ESC/POS)
 
 ```ts
+import { label } from "portakal/core";
+import { escpos } from "portakal/lang/escpos";
+
 const receipt = label({ width: 80, unit: "mm" })
   .text("MY STORE", { align: "center", bold: true, size: 2 })
   .text("123 Market St", { align: "center" })
@@ -68,88 +82,50 @@ const receipt = label({ width: 80, unit: "mm" })
   .text("Hamburger           x2    $25.98")
   .text("Cola                x1     $3.50")
   .text("================================")
-  .text("TOTAL                     $29.48", { bold: true, size: 2 })
-  .barcode("INV-20260402-001", { type: "code128", height: 60 })
-  .qrcode("https://receipt.example.com/inv/001")
-  .toESCPOS(); // Uint8Array (binary)
-```
-
-### Logo / image printing
+  .text("TOTAL                     $29.48", { bold: true, size: 2 });
 
-```ts
-const cmd = label({ width: 40, height: 30, unit: "mm" })
-  .image(myLogoBitmap, { x: 10, y: 10, width: 100 })
-  .text("Company Name", { x: 120, y: 20, size: 2 })
-  .toTSC();
+const bytes = escpos.compile(receipt); // Uint8Array
+const svg = escpos.preview(receipt); // Receipt-style SVG
 ```
 
-### Same label → any printer language
+### Each module: compile + parse + preview + validate
 
 ```ts
-const myLabel = label({ width: 40, height: 30, unit: "mm" })
-  .text("Hello World", { x: 10, y: 10, size: 2 })
-  .barcode("123456789", { type: "code128", x: 10, y: 50, height: 60 });
+import { tsc } from "portakal/lang/tsc";
 
-myLabel.toTSC(); // TSC/TSPL2  — TSC, Gprinter, Xprinter, iDPRT
-myLabel.toZPL(); // Zebra ZPL II — GK420, ZT410, ZD620
-myLabel.toEPL(); // Eltron EPL2 — LP/TLP 2824, GX420, ZD220
-myLabel.toESCPOS(); // ESC/POS — Epson, Bixolon, Star, Citizen
-```
+// Compile: label → printer commands
+tsc.compile(myLabel);
 
-### Tree Shaking
+// Preview: label → SVG (per-language font metrics)
+tsc.preview(myLabel);
 
-Import only what you need — each module is a separate entry point:
+// Parse: printer commands → structured data
+tsc.parse(tscCode); // { commands, elements, widthDots, ... }
 
-```ts
-import { compileToTSC } from "portakal/tsc";
-import { compileToZPL } from "portakal/zpl";
-import { compileToEPL } from "portakal/epl";
-import { compileToESCPOS } from "portakal/escpos";
-import { compileToCPCL } from "portakal/cpcl";
-import { compileToDPL } from "portakal/dpl";
-import { compileToSBPL } from "portakal/sbpl";
-import { compileToStarPRNT } from "portakal/starprnt";
-import { compileToIPL } from "portakal/ipl";
-import { imageToMonochrome } from "portakal/image";
-import { formatPair, separator } from "portakal/receipt";
-import { encodeTextForPrinter } from "portakal/encoding";
-import { getProfile } from "portakal/profiles";
-import { chunkedWrite } from "portakal/transport";
-import { renderPreview } from "portakal/preview";
+// Validate: check for errors
+tsc.validate(tscCode); // { valid, errors, issues }
 ```
 
-### Software-rendered barcode/QR (with etiket)
+Available: `tsc`, `zpl`, `epl`, `cpcl`, `dpl`, `sbpl`, `escpos`, `starprnt`, `ipl`
 
-For pixel-perfect output, styled QR codes, or when the printer doesn't support a format natively:
+### Barcode/QR via etiket
 
-```sh
-npm install portakal etiket
-```
+Use [`etiket`](https://github.com/productdevbook/etiket) for barcode/QR generation, then embed as image:
 
 ```ts
-import { label } from "portakal";
+import { label } from "portakal/core";
+import { tsc } from "portakal/lang/tsc";
 import { barcodePNG, qrcodePNG } from "etiket";
 
-// etiket renders barcode/QR as PNG → portakal sends it as an image to the printer
-const cmd = label({ width: 40, height: 30, unit: "mm" })
+const myLabel = label({ width: 40, height: 30, unit: "mm" })
   .text("Product Label", { x: 10, y: 5 })
   .image(barcodePNG("123456789", { type: "code128" }), { x: 10, y: 40, width: 200 })
-  .image(qrcodePNG("https://example.com"), { x: 220, y: 40, width: 80 })
-  .toZPL();
-```
+  .image(qrcodePNG("https://example.com"), { x: 220, y: 40, width: 80 });
 
-### When to use which?
+const code = tsc.compile(myLabel);
+```
 
-|                                       | Printer-native (`.barcode()` / `.qrcode()`) | Software-rendered (`.image()` + `etiket`) |
-| :------------------------------------ | :------------------------------------------ | :---------------------------------------- |
-| **Dependencies**                      | None                                        | `etiket` (you install it)                 |
-| **Speed**                             | Fast (only sends command text)              | Slower (sends pixel data)                 |
-| **Data size**                         | Small (~50 bytes)                           | Larger (bitmap data)                      |
-| **Consistency**                       | Varies by printer model                     | Identical on every printer                |
-| **Format support**                    | Depends on printer (10-20 types)            | 40+ barcode types, styled QR              |
-| **Styled QR** (dots, gradients, logo) | Not possible                                | Full support via etiket                   |
-| **Works on cheap printers**           | May not support QR/PDF417                   | Always works (it's just an image)         |
-| **Best for**                          | Simple labels, fast printing                | Pixel-perfect, guaranteed output          |
+| **Best for** | Simple labels, fast printing | Pixel-perfect, guaranteed output |
 
 ## API
 
@@ -187,56 +163,6 @@ builder.text("Hello", {
 });
 ```
 
-### `.barcode(data, options)`
-
-Printer-native barcode (uses the printer's built-in encoder):
-
-```ts
-builder.barcode("123456789", {
-  type: "code128", // Symbology (see table below)
-  x: 10,
-  y: 50, // Position
-  height: 80, // Bar height in dots
-  narrowWidth: 2, // Narrow bar width
-  wideWidth: 4, // Wide bar width
-  readable: true, // Show human-readable text
-  readablePosition: "below", // "none" | "above" | "below" | "both"
-  rotation: 0, // 0 | 90 | 180 | 270
-});
-```
-
-**Supported barcode types:**
-
-| Type                                 | Description            |
-| :----------------------------------- | :--------------------- |
-| `code128`                            | Code 128 (auto subset) |
-| `code128a` / `code128b` / `code128c` | Code 128 subsets       |
-| `code39`                             | Code 39                |
-| `code93`                             | Code 93                |
-| `ean13` / `ean8`                     | EAN-13 / EAN-8         |
-| `upca` / `upce`                      | UPC-A / UPC-E          |
-| `itf` / `itf14`                      | Interleaved 2 of 5     |
-| `codabar`                            | Codabar                |
-| `msi`                                | MSI Plessey            |
-| `plessey`                            | Plessey                |
-| `code11`                             | Code 11                |
-| `postnet` / `planet`                 | USPS Postnet / Planet  |
-| `gs1_128`                            | GS1-128                |
-| `gs1_databar`                        | GS1 DataBar            |
-
-### `.qrcode(data, options?)`
-
-```ts
-builder.qrcode("https://example.com", {
-  x: 10,
-  y: 100, // Position
-  ecc: "M", // "L" | "M" | "Q" | "H"
-  size: 6, // Module size 1-10
-  model: 2, // QR model 1 | 2
-  rotation: 0, // 0 | 90 | 180 | 270
-});
-```
-
 ### `.image(bitmap, options?)`
 
 ```ts
@@ -277,20 +203,16 @@ builder.raw("^FO10,10^FDCustom^FS"); // ZPL
 builder.raw(new Uint8Array([0x1b, 0x70, 0x00, 0x32, 0x32])); // ESC/POS cash drawer
 ```
 
-### Output Methods
-
-| Method          | Output       | Target                          |
-| :-------------- | :----------- | :------------------------------ |
-| `.toTSC()`      | `string`     | TSC/TSPL2 label printers        |
-| `.toZPL()`      | `string`     | Zebra ZPL II printers           |
-| `.toEPL()`      | `string`     | Eltron EPL2 printers            |
-| `.toCPCL()`     | `string`     | Zebra mobile printers           |
-| `.toDPL()`      | `string`     | Honeywell/Datamax printers      |
-| `.toSBPL()`     | `string`     | SATO printers                   |
-| `.toESCPOS()`   | `Uint8Array` | ESC/POS receipt printers        |
-| `.toStarPRNT()` | `Uint8Array` | Star Micronics printers         |
-| `.toIPL()`      | `string`     | Intermec/Honeywell printers     |
-| `.toPreview()`  | `string`     | SVG preview (no printer needed) |
+### Language Module Methods
+
+Each language module (`tsc`, `zpl`, `epl`, `cpcl`, `dpl`, `sbpl`, `escpos`, `starprnt`, `ipl`) has:
+
+| Method                | Output                   | Description                              |
+| :-------------------- | :----------------------- | :--------------------------------------- |
+| `lang.compile(label)` | `string` or `Uint8Array` | Compile to printer commands              |
+| `lang.preview(label)` | `string`                 | SVG preview with language-specific fonts |
+| `lang.parse(code)`    | `object`                 | Parse printer commands → structured data |
+| `lang.validate(code)` | `object`                 | Validate commands for errors/warnings    |
 
 ### Image Processing
 
@@ -303,7 +225,7 @@ const bitmap = imageToMonochrome(rgbaPixels, width, height, {
   dither: "floyd-steinberg", // "threshold" | "floyd-steinberg" | "atkinson" | "ordered"
 });
 
-label({ width: 40, height: 30 }).image(bitmap, { x: 10, y: 10 }).toTSC();
+tsc.compile(label({ width: 40, height: 30 }).image(bitmap, { x: 10, y: 10 }));
 ```
 
 ### Receipt Layout
@@ -334,6 +256,60 @@ formatTable(
 );
 ```
 
+### Cross-Compiler
+
+Convert between any printer languages — world's first thermal printer translator:
+
+```ts
+import { convert } from "portakal";
+
+// TSC → ZPL
+const { output } = convert(tscCode, "tsc", "zpl");
+
+// ZPL → ESC/POS
+const { output } = convert(zplCode, "zpl", "escpos");
+
+// EPL → CPCL
+const { output } = convert(eplCode, "epl", "cpcl");
+```
+
+7 source × 9 target = **63 conversion paths**.
+
+### Validation
+
+Check printer commands for errors before sending to printer:
+
+```ts
+import { validate } from "portakal";
+
+const result = validate(code, "tsc");
+// { valid: false, errors: 1, warnings: 2, issues: [
+//   { level: "error", message: "CLS must appear before label elements" },
+//   { level: "warning", message: "No PRINT command found" },
+// ]}
+```
+
+TSC validation: SIZE order, CLS before elements, PRINT required, DENSITY 0-15, SPEED 1-18.
+ZPL validation: ^XA/^XZ required, ^FD without ^FO, ^PW range.
+
+### Printer Profiles
+
+Auto-configure DPI, paper width, and capabilities based on printer model:
+
+```ts
+import { label, getProfile, findByVendorId } from "portakal";
+
+// Auto-DPI from profile
+label({ width: 40, height: 30, printer: "tsc-te310" }); // 300 DPI
+label({ width: 80, printer: "epson-tm-t88vi" }); // 203 DPI
+
+// Lookup profiles
+getProfile("zebra-zd420"); // { name, dpi, paperWidth, ... }
+findByVendorId(0x04b8); // All Epson printers
+```
+
+20 built-in profiles: Epson, Star, Bixolon, Citizen, TSC, Zebra, SATO, Honeywell, Generic.
+
 ## Supported Printer Languages
 
 | Language        | Printers                                       | Status             |
@@ -355,24 +331,23 @@ formatTable(
 portakal generates commands only — it does **not** handle printer connections. Send the output over any transport you choose:
 
 ```ts
-import { label } from "portakal";
+import { label } from "portakal/core";
+import { tsc } from "portakal/lang/tsc";
+import { escpos } from "portakal/lang/escpos";
 import net from "node:net";
 
-const commands = label({ width: 40, height: 30 }).text("Hello", { x: 10, y: 10 }).toTSC();
+const myLabel = label({ width: 40, height: 30 }).text("Hello", { x: 10, y: 10 });
+const commands = tsc.compile(myLabel);
 
 // TCP (port 9100)
 const socket = net.createConnection({ host: "192.168.1.100", port: 9100 });
 socket.write(commands);
 socket.end();
 
-// USB (via serialport)
-import { SerialPort } from "serialport";
-const port = new SerialPort({ path: "/dev/usb/lp0", baudRate: 9600 });
-port.write(commands);
-
 // ESC/POS (binary) over WebUSB
-const escpos = label({ width: 80 }).text("Receipt").toESCPOS();
-await usbDevice.transferOut(endpointNumber, escpos);
+const receipt = label({ width: 80 }).text("Receipt");
+const bytes = escpos.compile(receipt);
+await usbDevice.transferOut(endpointNumber, bytes);
 ```
 
 ## Comparison
@@ -390,6 +365,10 @@ await usbDevice.transferOut(endpointNumber, escpos);
 | Image dithering              |       :white_check_mark:       |                                    :x:                                     |                       :x:                       |                       :x:                       |
 | Receipt layout engine        |       :white_check_mark:       |                                  Partial                                   |                       :x:                       |                       :x:                       |
 | SVG preview                  |       :white_check_mark:       |                                    :x:                                     |                       :x:                       |                       :x:                       |
+| Command parser (reverse)     |  :white_check_mark: 9 parsers  |                                    :x:                                     |                       :x:                       |                       :x:                       |
+| Cross-compiler (translate)   |  :white_check_mark: 63 paths   |                                    :x:                                     |                       :x:                       |                       :x:                       |
+| Command validation           |       :white_check_mark:       |                                    :x:                                     |                       :x:                       |                       :x:                       |
+| Printer profiles             |     :white_check_mark: 20      |                                    :x:                                     |                       :x:                       |                       :x:                       |
 | Works in browser             |       :white_check_mark:       |                                    :x:                                     |                       :x:                       |               :white_check_mark:                |
 | No native modules (no gyp)   |       :white_check_mark:       |                                    :x:                                     |                       :x:                       |               :white_check_mark:                |
 | Pure ESM                     |       :white_check_mark:       |                                 :x: (CJS)                                  |                    :x: (CJS)                    |                    :x: (CJS)                    |
@@ -407,24 +386,32 @@ await usbDevice.transferOut(endpointNumber, escpos);
 - Fluent builder API — one label definition compiles to any language
 - **Image processing** — RGBA → monochrome with 4 dithering algorithms (Floyd-Steinberg, Atkinson, ordered, threshold)
 - **Receipt layout engine** — same-line left+right alignment, tables, word-wrap, separators
-- **SVG preview** — `.toPreview()` renders labels without a physical printer
+- **SVG preview** — `lang.preview(label)` renders labels without a physical printer
+- **9 parsers** — reverse-parse printer commands back to structured data (TSC, ZPL, EPL, CPCL, ESC/POS, DPL, SBPL, Star PRNT, IPL)
 - Drawing primitives — box, line, circle, diagonal
 - Raw command passthrough for advanced/unsupported features
 - Optional [`etiket`](https://github.com/productdevbook/etiket) integration for barcode/QR images (40+ formats)
 - Works in browser, Node.js, Deno, Bun, Electron
 - **UTF-8 encoding engine** — auto code page selection (CP437, CP858, CP1252, CP866, CP857)
-- 184 tests across 15 test files
+- **Cross-compiler** — convert between any languages (63 paths: TSC↔ZPL↔EPL↔CPCL↔DPL↔SBPL↔IPL↔ESC/POS↔Star)
+- **Real validation** — parameter ranges, command order, structure checks
+- **20 printer profiles** — auto-DPI, auto-width by model (Epson, Star, Zebra, TSC, SATO, etc.)
+- **Language modules** — each language is a standalone module (compile + parse + preview + validate)
+- **Per-language SVG preview** — TSC fonts differ from ZPL fonts, ESC/POS renders receipt-style
+- 447 tests across 28 test files
 
 ## Contributing
 
 Contributions are welcome! Here are areas where help is especially appreciated:
 
-- **IPL, Fingerprint, Argox PPLA/PPLB** compiler implementations
-- UTF-8 encoding engine (auto code page selection)
-- Arabic/Hebrew RTL support (bidi + shaping)
-- Printer capability profiles (auto-detect features per model)
-- Transport layer implementations (WebUSB, WebSerial, Web Bluetooth)
-- Star TSP100 raster-only mode
+- **Arabic/Hebrew RTL** support (bidi algorithm + Arabic shaping)
+- **GS1/UDI label standards** (SSCC, GTIN, FMD, DSCSA templates)
+- **Star TSP100** raster-only text rendering
+- **CJK encoding** (GB18030, Shift_JIS, Big5, EUC-KR)
+- **Fingerprint** (Honeywell BASIC-like) compiler
+- **WebUSB/WebSerial/Web Bluetooth** transport adapters
+- Additional printer profiles
+- Parser validation rules for more languages
 
 ```bash
 pnpm install    # Install dependencies

package/dist/_chunks/types.d.mts

@@ -9,6 +9,8 @@ type Alignment = "left" | "center" | "right";
 type DitherAlgorithm = "threshold" | "floyd-steinberg" | "atkinson" | "ordered";
 /** Label configuration */
 interface LabelConfig {
+  /** Printer profile ID (e.g., "epson-tm-t88vi", "zebra-zd420"). Overrides width, dpi, etc. */
+  printer?: string;
   /** Label width */
   width: number;
   /** Label height (optional for receipt/continuous mode) */
@@ -122,6 +124,28 @@ interface MonochromeBitmap {
   /** Bytes per row = ceil(width / 8) */
   bytesPerRow: number;
 }
+/** Ellipse element options */
+interface EllipseOptions {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  thickness?: number;
+}
+/** Reverse region options (invert black/white) */
+interface ReverseOptions {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/** Erase region options (clear to white) */
+interface EraseOptions {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
 /** Internal label element union type */
 type LabelElement = {
   type: "text";
@@ -140,6 +164,15 @@ type LabelElement = {
 } | {
   type: "circle";
   options: CircleOptions;
+} | {
+  type: "ellipse";
+  options: EllipseOptions;
+} | {
+  type: "reverse";
+  options: ReverseOptions;
+} | {
+  type: "erase";
+  options: EraseOptions;
 } | {
   type: "raw";
   content: string | Uint8Array;
@@ -166,4 +199,4 @@ interface ResolvedLabel {
   elements: LabelElement[];
 }
 //#endregion
-export { ImageOptions as a, LineOptions as c, Rotation as d, TextOptions as f, DitherAlgorithm as i, MonochromeBitmap as l, BoxOptions as n, LabelConfig as o, Unit as p, CircleOptions as r, LabelElement as s, Alignment as t, ResolvedLabel as u };
+export { EllipseOptions as a, LabelConfig as c, MonochromeBitmap as d, ResolvedLabel as f, Unit as g, TextOptions as h, DitherAlgorithm as i, LabelElement as l, Rotation as m, BoxOptions as n, EraseOptions as o, ReverseOptions as p, CircleOptions as r, ImageOptions as s, Alignment as t, LineOptions as u };

package/dist/image.d.mts

@@ -1,4 +1,4 @@
-import { i as DitherAlgorithm, l as MonochromeBitmap } from "./_chunks/types.mjs";
+import { d as MonochromeBitmap, i as DitherAlgorithm } from "./_chunks/types.mjs";
 
 //#region src/image.d.ts
 /** Convert RGBA pixel data to grayscale (BT.601 luminance, alpha composited on white) */