# Printing subsystem

Direct raw-byte printing to POS thermal printers over **USB-serial** — without the Windows print spooler or CUPS.

> **Implementation status (v0.1.0):** USB-serial only. In-tree ESC/POS encoder in `src/escpos.rs`. USB printer class and Bluetooth are **not** implemented.

---

## Goals

1. Discover serial ports (USB-serial adapters and CDC printers)
2. Let the user pick a port in the print dialog
3. Generate ESC/POS bytes from the AST (after parameter substitution)
4. Write bytes at **9600 baud** (fixed for now)

---

## Protocol: ESC/POS

Target **Epson ESC/POS** compatible printers (58 mm / 80 mm thermal).

### Implemented commands

| Feature | ESC/POS | Source |
|---------|---------|--------|
| Initialize | ESC @ | `escpos.rs` |
| Code page | ESC t 0 (CP437) | Always CP437 today; metadata field reserved |
| Bold | ESC E | Headings level 2, `**text**` flattened at encode |
| Double size | GS ! | Heading level 1 |
| Alignment | ESC a | Paragraphs, images, barcodes, QR |
| Line feed | LF, ESC d | Text lines, `@feed` |
| Partial cut | GS V 66 0 | `@cut`, auto-cut after print |
| Barcode | GS k | CODE128, EAN13, EAN8, CODE39 |
| QR Code | GS ( k | Model 2 |
| Raster image | GS v 0 | `@image` via `image` crate → threshold |

Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.

---

## Transport (implemented)

```
Print button
     │
     ▼
substitute_document()
     │
     ▼
EscPosEncoder::encode_document()
     │
     ▼
SerialTransport::open(port, 9600)
     │
     ▼
print_bytes() → write_all + flush
```

### `PrinterTransport` trait

```rust
pub trait PrinterTransport {
    fn write_all(&mut self, data: &[u8]) -> io::Result<()>;
    fn flush(&mut self) -> io::Result<()>;
}
```

| Type | Role |
|------|------|
| `SerialTransport` | Production — opens port via `serialport` |
| `MockTransport` | Tests — records bytes in `written` vec |

### Discovery

`list_usb_serial_printers()` calls `serialport::available_ports()` and labels USB ports with VID/PID when available. All serial ports are listed (no POS-specific filter).

### `PrinterDevice`

| Field | Example |
|-------|---------|
| `id` | `serial:COM3` |
| `display_name` | `COM3 — USB 04b8:0e15` |
| `port_name` | `COM3` |

---

## Print dialog (UI)

```
┌─────────────────────────────────────────┐
│  Print                                  │
├─────────────────────────────────────────┤
│  Parameters (one field per unique name) │
│  DocumentNumber: [________]             │
│                                         │
│  USB printer                            │
│  [ Refresh ]                            │
│  ○ COM3 — USB 04b8:0e15                 │
│  ○ /dev/ttyUSB0 — Serial                │
│                                         │
│  [ Cancel ]              [ Print ]      │
└─────────────────────────────────────────┘
```

- Parameters pre-filled from `last_params` (session memory).
- Same parameter name → one input, applied everywhere.
- Errors shown inline (parse, open port, write, barcode validation).

---

## Print pipeline

```
Document body (DSL)
        │
        ▼
   parse() → Document
        │
        ▼
 collect_parameter_names() → UI dialog
        │
        ▼
 substitute_document()
        │
        ▼
 EscPosEncoder (in-tree)
        │
        ▼
 SerialTransport::write_all
```

### Error handling (current)

| Condition | Behaviour |
|-----------|-----------|
| Parse error | Block print; show in toolbar |
| Port open failure | `PrintError::Open` message in dialog |
| Write failure | `PrintError::Write` message in dialog |
| EAN13/EAN8 invalid length | `EscPosError::Barcode` before write |
| Linux permission denied | User must join `dialout` group (documented in Help) |

Status polling (paper out, cover open) is **not** implemented.

---

## Images

1. Resolve path relative to `.pos` file directory (or absolute path).
2. Decode with `image` crate.
3. Convert to luma8, resize to target width (%, dots, or full printable width).
4. Threshold to 1-bit raster.
5. Emit GS v 0.

Preview shows `[image: path]` only — no bitmap preview yet.

---

## Preview vs print width

| `preview_mode` | Preview | Print |
|----------------|---------|-------|
| `autoscale` | Scales to panel width | Full paper width from metadata |
| `fixed` | Scaled by mm ratio | Full paper width |

---

## Testing without hardware

| Method | Location |
|--------|----------|
| `MockTransport` | `print/mod.rs` tests |
| ESC/POS byte checks | `escpos.rs` tests |
| `cargo test` | 20 tests; no printer required |

---

## Planned (not implemented)

| Feature | Notes |
|---------|-------|
| USB printer class | `nusb` / Windows `usbprint` |
| Bluetooth SPP | Serial port after OS pairing |
| Baud autodetect | Try 9600, 19200, 115200 |
| Printer status read | DLE EOT |
| Network TCP 9100 | Future |
| Image size warning in UI | Future |

---

## Dependencies

```toml
serialport = "4"
image = { features = ["png", "jpeg", "gif", "bmp"] }
```

No `escpos`, `nusb`, or `rusb` crates.
