# posprint

Cross-platform designer for POS (point-of-sale) receipt documents. Edit templates in a markdown-like syntax, preview output live, substitute runtime parameters, and print directly to USB serial POS printers via raw ESC/POS bytes.

**Target platforms:** Windows and Linux (x64).

## Status

**v0.1.1** — Rust + egui app with editor, preview, help, `.pos` files, parameters, and USB-serial printing.

## Build and run

Requires **Rust 1.88+** ([rustup](https://rustup.rs/) or `pacman -S rust` on Arch). See [docs/BUILD.md](docs/BUILD.md) for OS libraries and package scripts.

```bash
cargo test          # 31 unit tests
cargo run           # launch the designer
cargo build --release
```

**Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`

### Command-line printing

```bash
# Windows
posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42

# Linux
posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42
```

All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails.

**Linux:** add your user to the `dialout` group for USB-serial printer access.

## Releases (GitLab CI)

| Platform | Artifact | Install |
|----------|----------|---------|
| Linux (Debian/Ubuntu) | `.deb` (amd64) | `sudo dpkg -i posprint_*_amd64.deb` then `sudo apt-get install -f` |
| Linux (Arch) | `.pkg.tar.zst` (x86_64) | `sudo pacman -U posprint_*_x86_64.pkg.tar.zst` |
| Windows | `posprint.exe` | Download from GitLab release job artifacts |

Tag a version (e.g. `v0.1.0`) to trigger release builds.

## Features

- Markdown-like template editor with live preview
- Page width: auto-scale or fixed width (mm)
- Save and load `.pos` files
- Parameter tokens (`${DocumentNumber}`) with print-time popup and value reuse
- Barcodes, QR codes, and images (including parameterized content)
- Print to USB-serial POS printers via raw ESC/POS bytes
- In-app **Help** tab (from [docs/HELP.md](docs/HELP.md))

## Dependencies (minimal)

| Crate | Why |
|-------|-----|
| `eframe` / `egui` | Native UI |
| `serde` / `serde_json` | `.pos` file format |
| `serialport` | USB-serial printer I/O |
| `image` | Load PNG/JPEG for `@image` |
| `rfd` | Native open/save dialogs |
| `barcoders` | Raster barcode rendering |
| `qrcode` | Raster QR rendering |
| `clap` | CLI `print` subcommand |

ESC/POS encoding is implemented in-tree.

## Design documents

| Document | Description |
|----------|-------------|
| [FEASIBILITY.md](docs/FEASIBILITY.md) | Feasibility assessment, complexity estimate, risks |
| [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) | Language and framework recommendation |
| [HELP.md](docs/HELP.md) | **User reference** (mirrored in-app Help tab) |
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and module breakdown |
| [DSL-SPEC.md](docs/DSL-SPEC.md) | Document markup language (`.pos` body syntax) |
| [FILE-FORMAT.md](docs/FILE-FORMAT.md) | `.pos` file envelope (metadata + body) |
| [PRINTING.md](docs/PRINTING.md) | Printer discovery, transport, ESC/POS pipeline |
| [BUILD.md](docs/BUILD.md) | Local build scripts and Linux package formats |

Documentation must stay aligned with the codebase; see `.cursor/rules/documentation.mdc`.

## Planned features

- Bluetooth printer support (deferred)

## Quick feasibility summary

**Verdict: feasible** for a small team or solo developer, with the printing layer as the main engineering risk.

| Area | Complexity | Notes |
|------|------------|-------|
| Editor + preview UI | Medium | Well-trodden path |
| DSL parser + renderer | Medium | Custom grammar, bounded scope |
| Parameters | Low | Straightforward substitution |
| Barcodes / QR / images | Low–Medium | Mature libraries exist |
| USB / BT printer I/O | **High** | OS differences, device quirks |
| **Overall (MVP)** | **Medium–High** | ~6–10 weeks for one experienced dev |

Stack: **Rust + egui** (single language, minimal dependencies). USB-serial printing only in v1. See [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) and [docs/HELP.md](docs/HELP.md).
