BlueGit

timfa posprint

Sync docs and rules with multi-transport printing and current UI.

Update HELP/ARCHITECTURE/PRINTING/DSL/FILE-FORMAT/README; drop obsolete FEASIBILITY and LANGUAGE-CHOICE; align cursor rules.

Co-authored-by: Cursor <cursoragent@cursor.com>

timfa Tim Falken · pushed by timfa

Authored 2026-07-16 · 4 months ago

Hash
9e65a463e9e26ae5a4563f318c496d0c4ac86b19
Parent
2fc6ad6a
13 files changed +371 −614
.cursor/rules/architecture.mdc +10 −9
@@ -10,35 +10,36 @@ alwaysApply: true
10 10
11 11 - **Rust only** — no TypeScript/JavaScript frontend.
12 12 - **egui / eframe** for UI (`src/app.rs`, `src/main.rs`).
13 - **USB-serial printing only** — `src/print/mod.rs` via `serialport`. No Bluetooth or USB printer-class code until explicitly requested.
13 - **Printing:** USB printer-class (`rusb`), Windows spooler (Windows), and USB-serial (`serialport`) via `src/print/`.
14 14
15 15 ## Module responsibilities
16 16
17 17 | Module | Responsibility |
18 18 |--------|----------------|
19 19 | `dsl/` | Parse template text → `Document` AST |
20 | `params.rs` | Collect `${Name}` tokens; substitute at print time |
20 | `params.rs` | Collect `${Name}` tokens; substitute at print / preview |
21 21 | `escpos.rs` | AST → ESC/POS bytes (in-tree; no `escpos` crate) |
22 22 | `preview.rs` | AST → `PreviewModel` for UI canvas |
23 23 | `io/` | `PosFile` JSON load/save |
24 | `print/` | Port enumeration, `SerialTransport`, `MockTransport` |
25 | `app.rs` | All egui UI: editor, preview, help, print dialog |
24 | `print/` | Discovery + transports (USB-direct, spooler, serial, mock) |
25 | `print_dialog.rs` | Shared print UI |
26 | `app.rs` | Full designer egui UI |
26 27
27 28 Keep business logic out of `app.rs` where possible — UI should call `lib` modules.
28 29
29 30 ## Dependencies
30 31
31 Add a crate only when hand-rolling is unreasonable. Current allowed set:
32 Add a crate only when hand-rolling is unreasonable. Current set includes:
32 33
33 - `eframe`, `serde`, `serde_json`, `serialport`, `image`, `rfd`
34 - `eframe`, `serde`, `serde_json`, `serialport`, `rusb`, `image`, `rfd`, `barcoders`, `qrcode`, `clap`, `chrono`
34 35
35 36 Do **not** add `escpos`, `nusb`, `tauri`, or a JS toolchain without a deliberate stack change and doc update.
36 37
37 38 ## Preview vs print
38 39
39 - **Preview:** approximate layout; placeholders for barcode/QR/image; unresolved `${Param}` shown literally.
40 - **Print:** substitute parameters first, then encode ESC/POS, then write to serial port at **9600 baud**.
40 - **Preview:** layout from shared wrap; bitmaps for image/barcode/QR; sample or dialog params for `${Param}`.
41 - **Print:** substitute parameters, encode ESC/POS, write via the chosen transport (serial baud is probed).
41 42
42 43 ## Planned features (not in codebase yet)
43 44
44 USB printer class, Bluetooth, baud autodetect, persisted recent files/parameters, syntax highlighting. Document these only under "Planned" sections — do not implement stubs without a task.
45 Bluetooth, network TCP 9100, persisted recent files/parameters, syntax highlighting. Document these only under "Planned" sections — do not implement stubs without a task.
@@ -10,35 +10,36 @@ alwaysApply: true
10
10
11- **Rust only** — no TypeScript/JavaScript frontend.
11- **Rust only** — no TypeScript/JavaScript frontend.
12- **egui / eframe** for UI (`src/app.rs`, `src/main.rs`).
12- **egui / eframe** for UI (`src/app.rs`, `src/main.rs`).
13- **USB-serial printing only** — `src/print/mod.rs` via `serialport`. No Bluetooth or USB printer-class code until explicitly requested.
13- **Printing:** USB printer-class (`rusb`), Windows spooler (Windows), and USB-serial (`serialport`) via `src/print/`.
14
14
15## Module responsibilities
15## Module responsibilities
16
16
17| Module | Responsibility |
17| Module | Responsibility |
18|--------|----------------|
18|--------|----------------|
19| `dsl/` | Parse template text → `Document` AST |
19| `dsl/` | Parse template text → `Document` AST |
20| `params.rs` | Collect `${Name}` tokens; substitute at print time |
20| `params.rs` | Collect `${Name}` tokens; substitute at print / preview |
21| `escpos.rs` | AST → ESC/POS bytes (in-tree; no `escpos` crate) |
21| `escpos.rs` | AST → ESC/POS bytes (in-tree; no `escpos` crate) |
22| `preview.rs` | AST → `PreviewModel` for UI canvas |
22| `preview.rs` | AST → `PreviewModel` for UI canvas |
23| `io/` | `PosFile` JSON load/save |
23| `io/` | `PosFile` JSON load/save |
24| `print/` | Port enumeration, `SerialTransport`, `MockTransport` |
24| `print/` | Discovery + transports (USB-direct, spooler, serial, mock) |
25| `app.rs` | All egui UI: editor, preview, help, print dialog |
25| `print_dialog.rs` | Shared print UI |
26| `app.rs` | Full designer egui UI |
26
27
27Keep business logic out of `app.rs` where possible — UI should call `lib` modules.
28Keep business logic out of `app.rs` where possible — UI should call `lib` modules.
28
29
29## Dependencies
30## Dependencies
30
31
31Add a crate only when hand-rolling is unreasonable. Current allowed set:
32Add a crate only when hand-rolling is unreasonable. Current set includes:
32
33
33- `eframe`, `serde`, `serde_json`, `serialport`, `image`, `rfd`
34- `eframe`, `serde`, `serde_json`, `serialport`, `rusb`, `image`, `rfd`, `barcoders`, `qrcode`, `clap`, `chrono`
34
35
35Do **not** add `escpos`, `nusb`, `tauri`, or a JS toolchain without a deliberate stack change and doc update.
36Do **not** add `escpos`, `nusb`, `tauri`, or a JS toolchain without a deliberate stack change and doc update.
36
37
37## Preview vs print
38## Preview vs print
38
39
39- **Preview:** approximate layout; placeholders for barcode/QR/image; unresolved `${Param}` shown literally.
40- **Preview:** layout from shared wrap; bitmaps for image/barcode/QR; sample or dialog params for `${Param}`.
40- **Print:** substitute parameters first, then encode ESC/POS, then write to serial port at **9600 baud**.
41- **Print:** substitute parameters, encode ESC/POS, write via the chosen transport (serial baud is probed).
41
42
42## Planned features (not in codebase yet)
43## Planned features (not in codebase yet)
43
44
44USB printer class, Bluetooth, baud autodetect, persisted recent files/parameters, syntax highlighting. Document these only under "Planned" sections — do not implement stubs without a task.
45Bluetooth, network TCP 9100, persisted recent files/parameters, syntax highlighting. Document these only under "Planned" sections — do not implement stubs without a task.
.cursor/rules/development.mdc +2 −2
@@ -11,7 +11,7 @@ alwaysApply: true
11 11 - Single language: **Rust** with **egui** (eframe) for the UI.
12 12 - Prefer std library and in-house code. Add a crate only when reimplementing would be unreasonable (e.g. `serialport`, `serde`, `image`, UI framework).
13 13 - ESC/POS encoding lives in `src/escpos.rs` — do not add the `escpos` crates.io package.
14 - Printing: **USB-serial only** in v0.1.x. No Bluetooth or USB printer-class until explicitly requested.
14 - Printing: USB printer-class (`rusb`), Windows spooler, and USB-serial (`serialport`). Do not add Bluetooth or network printing until explicitly requested.
15 15
16 16 ## Testing
17 17
@@ -60,7 +60,7 @@ alwaysApply: true
60 60
61 61 ## Releases
62 62
63 - GitLab CI (`.gitlab-ci.yml`) runs tests on push.
63 - GitLab CI (`.gitlab-ci.yml`) runs tests on **merge requests**; tagged releases build artifacts.
64 64 - Tagged releases produce Windows `.exe`, Debian `.deb` (apt), and Arch `.pkg.tar.zst` (pacman).
65 65 - Debian packages use `cargo-deb` and `[package.metadata.deb]` in `Cargo.toml`.
66 66 - Arch packages use `packaging/arch/PKGBUILD` and `makepkg`.
@@ -11,7 +11,7 @@ alwaysApply: true
11- Single language: **Rust** with **egui** (eframe) for the UI.
11- Single language: **Rust** with **egui** (eframe) for the UI.
12- Prefer std library and in-house code. Add a crate only when reimplementing would be unreasonable (e.g. `serialport`, `serde`, `image`, UI framework).
12- Prefer std library and in-house code. Add a crate only when reimplementing would be unreasonable (e.g. `serialport`, `serde`, `image`, UI framework).
13- ESC/POS encoding lives in `src/escpos.rs` — do not add the `escpos` crates.io package.
13- ESC/POS encoding lives in `src/escpos.rs` — do not add the `escpos` crates.io package.
14- Printing: **USB-serial only** in v0.1.x. No Bluetooth or USB printer-class until explicitly requested.
14- Printing: USB printer-class (`rusb`), Windows spooler, and USB-serial (`serialport`). Do not add Bluetooth or network printing until explicitly requested.
15
15
16## Testing
16## Testing
17
17
@@ -60,7 +60,7 @@ alwaysApply: true
60
60
61## Releases
61## Releases
62
62
63- GitLab CI (`.gitlab-ci.yml`) runs tests on push.
63- GitLab CI (`.gitlab-ci.yml`) runs tests on **merge requests**; tagged releases build artifacts.
64- Tagged releases produce Windows `.exe`, Debian `.deb` (apt), and Arch `.pkg.tar.zst` (pacman).
64- Tagged releases produce Windows `.exe`, Debian `.deb` (apt), and Arch `.pkg.tar.zst` (pacman).
65- Debian packages use `cargo-deb` and `[package.metadata.deb]` in `Cargo.toml`.
65- Debian packages use `cargo-deb` and `[package.metadata.deb]` in `Cargo.toml`.
66- Arch packages use `packaging/arch/PKGBUILD` and `makepkg`.
66- Arch packages use `packaging/arch/PKGBUILD` and `makepkg`.
.cursor/rules/documentation.mdc +2 −2
@@ -14,8 +14,8 @@ alwaysApply: true
14 14 | System design | `docs/ARCHITECTURE.md` | — |
15 15 | DSL grammar | `docs/DSL-SPEC.md` | `docs/HELP.md` (user subset) |
16 16 | `.pos` file schema | `docs/FILE-FORMAT.md` | — |
17 | Printing / ESC/POS | `docs/PRINTING.md` | `docs/HELP.md` (USB section) |
18 | Stack choice | `docs/LANGUAGE-CHOICE.md` | `README.md` summary |
17 | Printing / ESC/POS | `docs/PRINTING.md` | `docs/HELP.md` (print section) |
18 | Build / packages | `docs/BUILD.md` | `README.md` summary |
19 19
20 20 ## When to update docs
21 21
@@ -14,8 +14,8 @@ alwaysApply: true
14| System design | `docs/ARCHITECTURE.md` | — |
14| System design | `docs/ARCHITECTURE.md` | — |
15| DSL grammar | `docs/DSL-SPEC.md` | `docs/HELP.md` (user subset) |
15| DSL grammar | `docs/DSL-SPEC.md` | `docs/HELP.md` (user subset) |
16| `.pos` file schema | `docs/FILE-FORMAT.md` | — |
16| `.pos` file schema | `docs/FILE-FORMAT.md` | — |
17| Printing / ESC/POS | `docs/PRINTING.md` | `docs/HELP.md` (USB section) |
17| Printing / ESC/POS | `docs/PRINTING.md` | `docs/HELP.md` (print section) |
18| Stack choice | `docs/LANGUAGE-CHOICE.md` | `README.md` summary |
18| Build / packages | `docs/BUILD.md` | `README.md` summary |
19
19
20## When to update docs
20## When to update docs
21
21
README.md +30 −46
@@ -1,38 +1,42 @@
1 1 # posprint
2 2
3 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.
3 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 via raw ESC/POS (USB printer-class, Windows spooler, or USB-serial).
4 4
5 5 **Target platforms:** Windows and Linux (x64).
6 6
7 7 ## Status
8 8
9 **v0.2.0** — Rust + egui app with editor, preview, help, `.pos` files, parameters, and USB-serial printing.
9 **v0.2.0** — Rust + egui app with editor, preview, help, `.pos` files, parameters, and multi-transport printing.
10 10
11 11 ## Build and run
12 12
13 13 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.
14 14
15 15 ```bash
16 cargo test # 31 unit tests
16 cargo test # unit tests
17 17 cargo run # launch the designer
18 18 cargo build --release
19 19 ```
20 20
21 **Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`
21 **Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`
22 (Interactive shells offer to install missing dependencies.)
22 23
23 24 ### Command-line printing
24 25
25 26 ```bash
26 # Windows
27 # Windows (serial or spooler queue name)
27 28 posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42
28 29
29 30 # Linux
30 31 posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42
32
33 # Embedded CLI help for this OS
34 posprint cli-help
31 35 ```
32 36
33 37 All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails.
34 38
35 **Linux:** add your user to the `dialout` group for USB-serial printer access.
39 **Linux serial:** add your user to the `dialout` group.
36 40
37 41 ## Releases (GitLab CI)
38 42
@@ -42,39 +46,22 @@ All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails
42 46 | Linux (Arch) | `.pkg.tar.zst` (x86_64) | `sudo pacman -U posprint_*_x86_64.pkg.tar.zst` |
43 47 | Windows | `posprint.exe` | Download from GitLab release job artifacts |
44 48
45 Tag a version (e.g. `v0.1.0`) to trigger release builds.
49 Tag a version (e.g. `0.2.0`) to trigger release builds.
46 50
47 51 ## Features
48 52
49 - Markdown-like template editor with live preview
50 - Page width: auto-scale or fixed width (mm)
53 - Markdown-like template editor with live preview (Design tab)
54 - Page width (mm) and calibrated preview zoom
51 55 - Save and load `.pos` files
52 - Parameter tokens (`${DocumentNumber}`) with print-time popup and value reuse
53 - Barcodes, QR codes, and images (including parameterized content)
54 - Print to USB-serial POS printers via raw ESC/POS bytes
56 - Parameter tokens (`${DocumentNumber}`) with print dialog and CLI `--set`
57 - Bullet lists, headings, `@date` / `@time`, barcodes, QR, images
58 - Print via USB-direct, Windows spooler, or serial (baud probed)
55 59 - In-app **Help** tab (from [docs/HELP.md](docs/HELP.md))
56 60
57 ## Dependencies (minimal)
58
59 | Crate | Why |
60 |-------|-----|
61 | `eframe` / `egui` | Native UI |
62 | `serde` / `serde_json` | `.pos` file format |
63 | `serialport` | USB-serial printer I/O |
64 | `image` | Load PNG/JPEG for `@image` |
65 | `rfd` | Native open/save dialogs |
66 | `barcoders` | Raster barcode rendering |
67 | `qrcode` | Raster QR rendering |
68 | `clap` | CLI `print` subcommand |
69
70 ESC/POS encoding is implemented in-tree.
71
72 ## Design documents
61 ## Documentation
73 62
74 63 | Document | Description |
75 64 |----------|-------------|
76 | [FEASIBILITY.md](docs/FEASIBILITY.md) | Feasibility assessment, complexity estimate, risks |
77 | [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) | Language and framework recommendation |
78 65 | [HELP.md](docs/HELP.md) | **User reference** (mirrored in-app Help tab) |
79 66 | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and module breakdown |
80 67 | [DSL-SPEC.md](docs/DSL-SPEC.md) | Document markup language (`.pos` body syntax) |
@@ -84,21 +71,18 @@ ESC/POS encoding is implemented in-tree.
84 71
85 72 Documentation must stay aligned with the codebase; see `.cursor/rules/documentation.mdc`.
86 73
87 ## Planned features
88
89 - Bluetooth printer support (deferred)
90
91 ## Quick feasibility summary
92
93 **Verdict: feasible** for a small team or solo developer, with the printing layer as the main engineering risk.
74 ## Dependencies (minimal)
94 75
95 | Area | Complexity | Notes |
96 |------|------------|-------|
97 | Editor + preview UI | Medium | Well-trodden path |
98 | DSL parser + renderer | Medium | Custom grammar, bounded scope |
99 | Parameters | Low | Straightforward substitution |
100 | Barcodes / QR / images | Low–Medium | Mature libraries exist |
101 | USB / BT printer I/O | **High** | OS differences, device quirks |
102 | **Overall (MVP)** | **Medium–High** | ~6–10 weeks for one experienced dev |
76 | Crate | Why |
77 |-------|-----|
78 | `eframe` / `egui` | Native UI |
79 | `serde` / `serde_json` | `.pos` file format |
80 | `serialport` | Serial printer I/O |
81 | `rusb` | USB printer-class devices |
82 | `image` | Load PNG/JPEG for `@image` |
83 | `rfd` | Native open/save dialogs |
84 | `barcoders` | Raster barcode rendering |
85 | `qrcode` | Raster QR rendering |
86 | `clap` | CLI `print` / `cli-help` |
103 87
104 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).
88 ESC/POS encoding is implemented in-tree.
@@ -1,38 +1,42 @@
1# posprint
1# posprint
2
2
3Cross-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.
3Cross-platform designer for POS (point-of-sale) receipt documents. Edit templates in a markdown-like syntax, preview output live, substitute runtime parameters, and print via raw ESC/POS (USB printer-class, Windows spooler, or USB-serial).
4
4
5**Target platforms:** Windows and Linux (x64).
5**Target platforms:** Windows and Linux (x64).
6
6
7## Status
7## Status
8
8
9**v0.2.0** — Rust + egui app with editor, preview, help, `.pos` files, parameters, and USB-serial printing.
9**v0.2.0** — Rust + egui app with editor, preview, help, `.pos` files, parameters, and multi-transport printing.
10
10
11## Build and run
11## Build and run
12
12
13Requires **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.
13Requires **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.
14
14
15```bash
15```bash
16cargo test # 31 unit tests
16cargo test # unit tests
17cargo run # launch the designer
17cargo run # launch the designer
18cargo build --release
18cargo build --release
19```
19```
20
20
21**Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`
21**Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`
22(Interactive shells offer to install missing dependencies.)
22
23
23### Command-line printing
24### Command-line printing
24
25
25```bash
26```bash
26# Windows
27# Windows (serial or spooler queue name)
27posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42
28posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42
28
29
29# Linux
30# Linux
30posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42
31posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42
32
33# Embedded CLI help for this OS
34posprint cli-help
31```
35```
32
36
33All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails.
37All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails.
34
38
35**Linux:** add your user to the `dialout` group for USB-serial printer access.
39**Linux serial:** add your user to the `dialout` group.
36
40
37## Releases (GitLab CI)
41## Releases (GitLab CI)
38
42
@@ -42,39 +46,22 @@ All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails
42| Linux (Arch) | `.pkg.tar.zst` (x86_64) | `sudo pacman -U posprint_*_x86_64.pkg.tar.zst` |
46| Linux (Arch) | `.pkg.tar.zst` (x86_64) | `sudo pacman -U posprint_*_x86_64.pkg.tar.zst` |
43| Windows | `posprint.exe` | Download from GitLab release job artifacts |
47| Windows | `posprint.exe` | Download from GitLab release job artifacts |
44
48
45Tag a version (e.g. `v0.1.0`) to trigger release builds.
49Tag a version (e.g. `0.2.0`) to trigger release builds.
46
50
47## Features
51## Features
48
52
49- Markdown-like template editor with live preview
53- Markdown-like template editor with live preview (Design tab)
50- Page width: auto-scale or fixed width (mm)
54- Page width (mm) and calibrated preview zoom
51- Save and load `.pos` files
55- Save and load `.pos` files
52- Parameter tokens (`${DocumentNumber}`) with print-time popup and value reuse
56- Parameter tokens (`${DocumentNumber}`) with print dialog and CLI `--set`
53- Barcodes, QR codes, and images (including parameterized content)
57- Bullet lists, headings, `@date` / `@time`, barcodes, QR, images
54- Print to USB-serial POS printers via raw ESC/POS bytes
58- Print via USB-direct, Windows spooler, or serial (baud probed)
55- In-app **Help** tab (from [docs/HELP.md](docs/HELP.md))
59- In-app **Help** tab (from [docs/HELP.md](docs/HELP.md))
56
60
57## Dependencies (minimal)
61## Documentation
58
59| Crate | Why |
60|-------|-----|
61| `eframe` / `egui` | Native UI |
62| `serde` / `serde_json` | `.pos` file format |
63| `serialport` | USB-serial printer I/O |
64| `image` | Load PNG/JPEG for `@image` |
65| `rfd` | Native open/save dialogs |
66| `barcoders` | Raster barcode rendering |
67| `qrcode` | Raster QR rendering |
68| `clap` | CLI `print` subcommand |
69
70ESC/POS encoding is implemented in-tree.
71
72## Design documents
73
62
74| Document | Description |
63| Document | Description |
75|----------|-------------|
64|----------|-------------|
76| [FEASIBILITY.md](docs/FEASIBILITY.md) | Feasibility assessment, complexity estimate, risks |
77| [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) | Language and framework recommendation |
78| [HELP.md](docs/HELP.md) | **User reference** (mirrored in-app Help tab) |
65| [HELP.md](docs/HELP.md) | **User reference** (mirrored in-app Help tab) |
79| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and module breakdown |
66| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and module breakdown |
80| [DSL-SPEC.md](docs/DSL-SPEC.md) | Document markup language (`.pos` body syntax) |
67| [DSL-SPEC.md](docs/DSL-SPEC.md) | Document markup language (`.pos` body syntax) |
@@ -84,21 +71,18 @@ ESC/POS encoding is implemented in-tree.
84
71
85Documentation must stay aligned with the codebase; see `.cursor/rules/documentation.mdc`.
72Documentation must stay aligned with the codebase; see `.cursor/rules/documentation.mdc`.
86
73
87## Planned features
74## Dependencies (minimal)
88
89- Bluetooth printer support (deferred)
90
91## Quick feasibility summary
92
93**Verdict: feasible** for a small team or solo developer, with the printing layer as the main engineering risk.
94
75
95| Area | Complexity | Notes |
76| Crate | Why |
96|------|------------|-------|
77|-------|-----|
97| Editor + preview UI | Medium | Well-trodden path |
78| `eframe` / `egui` | Native UI |
98| DSL parser + renderer | Medium | Custom grammar, bounded scope |
79| `serde` / `serde_json` | `.pos` file format |
99| Parameters | Low | Straightforward substitution |
80| `serialport` | Serial printer I/O |
100| Barcodes / QR / images | Low–Medium | Mature libraries exist |
81| `rusb` | USB printer-class devices |
101| USB / BT printer I/O | **High** | OS differences, device quirks |
82| `image` | Load PNG/JPEG for `@image` |
102| **Overall (MVP)** | **Medium–High** | ~6–10 weeks for one experienced dev |
83| `rfd` | Native open/save dialogs |
84| `barcoders` | Raster barcode rendering |
85| `qrcode` | Raster QR rendering |
86| `clap` | CLI `print` / `cli-help` |
103
87
104Stack: **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).
88ESC/POS encoding is implemented in-tree.
docs/ARCHITECTURE.md +90 −97
@@ -5,57 +5,73 @@
5 5 posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language, no WebView, no IPC layer.
6 6
7 7 ```
8 ┌─────────────────────────────────────────┐
9 │ posprint (Rust + egui) │
10 │ - Editor / Preview / Help tabs │
11 │ - DSL parse → AST │
12 │ - Preview layout + in-tree ESC/POS │
13 │ - USB-serial printer discovery/print │
14 │ - `.pos` JSON load/save (serde) │
15 └─────────────────────────────────────────┘
8 ┌──────────────────────────────────────────────────┐
9 │ posprint (Rust + egui) │
10 │ - Design (editor + preview) / Help │
11 │ - DSL parse → AST → preview + ESC/POS │
12 │ - USB-direct / Win spooler / serial printing │
13 │ - `.pos` JSON load/save (serde) │
14 └──────────────────────────────────────────────────┘
16 15 ```
17 16
18 17 ### Source layout
19 18
20 19 ```
21 20 src/
22 ├── main.rs # eframe entry point
23 ├── app.rs # egui UI (editor, preview, help, print dialog)
24 ├── lib.rs # crate root; exports + HELP_MARKDOWN
25 ├── dsl/ # Parser and AST (mod.rs, parser.rs)
26 ├── params.rs # Parameter collect/substitute
27 ├── escpos.rs # ESC/POS byte encoder (in-tree)
28 ├── preview.rs # Preview model for UI canvas
29 ├── io/mod.rs # .pos file format (PosFile, PosMetadata)
30 └── print/mod.rs # USB-serial discovery, SerialTransport, MockTransport
21 ├── main.rs # CLI + eframe / print-only entry
22 ├── app.rs # Full designer UI
23 ├── print_only_app.rs # Print-only window (--print)
24 ├── print_dialog.rs # Shared print dialog
25 ├── cli.rs # clap: print, cli-help
26 ├── lib.rs # crate root; HELP_MARKDOWN
27 ├── dsl/ # Parser and AST
28 ├── params.rs # Parameter collect / substitute / preview samples
29 ├── escpos.rs # ESC/POS byte encoder (in-tree)
30 ├── preview.rs # PreviewModel for UI canvas
31 ├── text_wrap.rs # Shared wrap (preview + print)
32 ├── datetime.rs # @date / @time formatting
33 ├── raster.rs # Barcode / QR bitmaps
34 ├── editor_assist.rs # @ autocomplete, Insert snippets
35 ├── help_view.rs # Markdown help renderer
36 ├── io/mod.rs # PosFile, PosMetadata
37 ├── pipeline.rs # Encode / print helpers
38 ├── print/
39 │ ├── mod.rs # list_printers, SerialTransport, MockTransport
40 │ ├── usb_direct.rs # USB printer-class (rusb)
41 │ └── win_spool.rs # Windows spooler (Windows)
42 └── shell_integration/ # OS “Print” context menu helpers
31 43 ```
32 44
33 ### External dependencies (minimal)
45 ### External dependencies
34 46
35 47 | Crate | Role |
36 48 |-------|------|
37 49 | `eframe` / `egui` | Native UI |
38 50 | `serde` / `serde_json` | `.pos` file format |
39 | `serialport` | USB-serial enumeration and I/O |
40 | `image` | Decode/resize images for `@image` raster print |
41 | `rfd` | Native open/save file dialogs |
51 | `serialport` | Serial enumeration and I/O |
52 | `rusb` | USB printer-class devices |
53 | `image` | Decode/resize images |
54 | `rfd` | Native open/save dialogs |
55 | `barcoders` / `qrcode` | Raster barcodes and QR |
56 | `clap` | CLI |
57 | `chrono` | Date/time |
58 | `pulldown-cmark` | In-app Help markdown |
42 59
43 ESC/POS command generation is **not** delegated to a third-party crate.
60 ESC/POS generation is **in-tree** (`escpos.rs`), not the `escpos` crates.io package.
44 61
45 62 ---
46 63
47 64 ## UI structure
48 65
49 | Tab / area | Module | Description |
50 |------------|--------|-------------|
51 | **Editor** | `app.rs` | Multiline `TextEdit` (monospace) for template source |
52 | **Preview** | `app.rs` + `preview.rs` | Canvas render of `PreviewModel`; auto-scale or fixed mm |
53 | **Help** | `app.rs` | Scrollable view of `docs/HELP.md` via `include_str!` |
54 | Toolbar | `app.rs` | New, Open, Save, Save As, Print |
55 | Settings | `app.rs` | Page width (mm), preview mode |
56 | Print dialog | `app.rs` | Parameter fields + USB-serial printer picker |
66 | Area | Module | Description |
67 |------|--------|-------------|
68 | **Design** | `app.rs` | Editor + side preview |
69 | **Help** | `help_view.rs` | `docs/HELP.md` via `include_str!` |
70 | Toolbar | `app.rs` | New, Open, Save, Save As, Insert, Print |
71 | Settings | `app.rs` | Page width (mm), preview zoom |
72 | Print dialog | `print_dialog.rs` | Parameters + multi-transport printer picker |
57 73
58 Bottom panel switches tabs. Top panel holds actions and settings.
74 While the print dialog is open, the main UI is disabled and editor autocomplete does not steal focus.
59 75
60 76 ---
61 77
@@ -63,117 +79,94 @@ Bottom panel switches tabs. Top panel holds actions and settings.
63 79
64 80 ### Edit loop (live preview)
65 81
66 1. User types in the Editor tab.
82 1. User edits the template on the Design tab.
67 83 2. Each frame, `parse(&body)` runs; errors show in the toolbar.
68 3. On Preview tab, `render_preview(&doc, &metadata)` builds a `PreviewModel`.
69 4. Canvas draws text lines, rules, and placeholders for barcode/QR/image.
70
71 Preview is **not debounced** — it re-parses when the Preview tab is shown (and parse runs every frame for error display).
84 3. `render_preview` builds a `PreviewModel` (text, rules, bitmaps, spacers).
85 4. Canvas draws with calibrated zoom (`PREVIEW_SCREEN_CALIBRATION`) and Font A–matched text size.
72 86
73 87 ### Save / load
74 88
75 1. **Open:** `rfd` file dialog → `PosFile::load_from_path` → populate `body`, `metadata`, `file_path`.
76 2. **Save / Save As:** `PosFile::save_to_path` writes pretty-printed JSON.
89 1. **Open:** `rfd` → `PosFile::load_from_path`.
90 2. **Save / Save As:** pretty-printed JSON.
77 91
78 Image paths in `@image` resolve relative to the `.pos` file directory on print.
92 `@image` paths resolve relative to the `.pos` directory on preview and print.
79 93
80 94 ### Print
81 95
82 1. User clicks **Print** → parse body → `collect_parameter_names(&doc)`.
83 2. Modal shows one field per unique parameter; pre-filled from `last_params` (in-memory).
84 3. User selects a USB-serial port from `list_usb_serial_printers()`.
85 4. `substitute_document` → `EscPosEncoder::encode_document` → `SerialTransport::open` (9600 baud) → `print_bytes`.
96 1. **Print** → parse → `collect_parameter_names`.
97 2. Dialog: one field per parameter; `list_printers()` for USB / spooler / serial.
98 3. `substitute_document` → `EscPosEncoder` → `open_printer` → `print_bytes`.
99 4. Serial baud is probed (`115200` first, then `9600`, …).
86 100
87 101 ---
88 102
89 103 ## Key types
90 104
91 Implemented in `dsl/mod.rs`, `io/mod.rs`, `print/mod.rs`:
92
93 105 ```rust
94 106 // dsl/
95 107 struct Document { blocks: Vec<Block> }
96
97 108 enum Block {
98 109 Paragraph { align, inlines },
99 110 List { align, items },
100 Heading { level, inlines },
101 Rule,
102 Feed(u8),
103 Cut,
104 Image { path, width: ImageWidth, align },
105 Barcode { symbology, data, height, align, show_text },
106 Qr { data, size, ecc, align },
111 Heading { level, align, inlines },
112 Rule, Feed(u8), Cut,
113 Image { path, width, align },
114 Barcode { mode, symbology, data, height, align, show_text },
115 Qr { mode, data, size, ecc, version, align },
116 Date { format, align },
117 Time { format, align },
107 118 }
119 enum Inline { Text(String), Param(String) }
108 120
109 121 // io/
110 struct PosFile { version, metadata: PosMetadata, body }
111 struct PosMetadata { title, page_width_mm, preview_mode, chars_per_line, codepage }
122 struct PosMetadata { title, page_width_mm, chars_per_line, codepage }
123 // printable_dots() = chars_per_line() * 12
112 124
113 125 // print/
114 struct PrinterDevice { id, display_name, port_name }
115 trait PrinterTransport { write_all, flush }
126 enum PrinterTarget { Serial(String), UsbDirect { … }, WinSpooler(String) }
116 127 ```
117 128
129 Legacy JSON fields `preview_mode` and `cut_after_print` are ignored if present.
130
118 131 ---
119 132
120 133 ## Preview vs print fidelity
121 134
122 135 | Aspect | Preview | Print |
123 136 |--------|---------|-------|
124 | Text font | egui monospace/proportional | Printer built-in font |
125 | Line width | From `chars_per_line()` | ESC/POS dot width from `page_width_mm` |
126 | Images | `[image: path]` placeholder | Monochrome raster (GS v 0) |
127 | Barcodes / QR | Text placeholder | Native ESC/POS commands |
128 | Alignment | Canvas positioning | ESC a |
129
130 Both paths share the same **AST**; substitution happens only at print time. Preview shows unresolved `${Param}` tokens as-is.
137 | Text | egui monospace (print-matched size) | Printer Font A |
138 | Line width | `chars_per_line` / `printable_dots` | Same wrap model |
139 | Images / barcode / QR | Raster bitmaps | ESC/POS native or GS v 0 |
140 | Blank lines | Spacer = line spacing dots | ESC d |
141 | Parameters | Sample / dialog values | Substituted values |
131 142
132 143 ---
133 144
134 ## State persistence (current)
145 ## State persistence
135 146
136 | Data | Storage | Notes |
137 |------|---------|-------|
138 | Template + metadata | `.pos` file on disk | User saves explicitly |
139 | Last parameter values | `PosPrintApp.last_params` | In-memory only; lost on quit |
140 | Recent files | — | Not implemented |
141 | Selected printer | — | Not persisted between sessions |
147 | Data | Storage |
148 |------|---------|
149 | Template + metadata | `.pos` file |
150 | Last parameter values | In-memory (`print_dialog.last_params`) |
151 | Recent files / selected printer | Not persisted |
142 152
143 153 ---
144 154
145 155 ## Testing
146 156
147 | Layer | Location | Approach |
148 |-------|----------|----------|
149 | DSL parser | `dsl/parser.rs` | Unit tests |
150 | Parameters | `params.rs` | Unit tests |
151 | ESC/POS encoder | `escpos.rs` | Byte structure tests |
152 | Preview | `preview.rs` | Unit tests |
153 | `.pos` I/O | `io/mod.rs` | Round-trip + tempfile tests |
154 | Printer I/O | `print/mod.rs` | `MockTransport`; no hardware in CI |
155 | App | `app.rs` | Default template parse/param tests |
157 | Layer | Location |
158 |-------|----------|
159 | DSL, params, ESC/POS, preview, wrap, I/O, print mocks | `src/**` unit tests |
160 | App / shell helpers | `src/main.rs` tests |
156 161
157 Run: `cargo test` (20 tests). CI runs this on Linux (Docker) and Windows (shell runner).
162 Run: `cargo test` (~100 tests). CI: tests on merge requests; release artifacts on tags.
158 163
159 164 ---
160 165
161 166 ## Build and release
162 167
163 - **CI:** GitLab (`.gitlab-ci.yml`) — `cargo test` on push; release artifacts on tags.
164 - **Linux artifact:** `.deb` via `cargo-deb` (`[package.metadata.deb]` in `Cargo.toml`).
165 - **Windows artifact:** `target/release/posprint.exe`.
166 - **Versioning:** Semver in `Cargo.toml`; `.pos` `version` field for file-format migrations.
167
168 ---
169
170 ## Planned (not implemented)
171
172 - USB printer class (bulk OUT) without serial emulation
173 - Bluetooth SPP
174 - Network printers (TCP 9100)
175 - Baud-rate autodetect / settings UI
176 - Persisted last parameters and recent files
177 - Syntax highlighting in editor
168 - **CI:** GitLab (`.gitlab-ci.yml`)
169 - **Artifacts:** Windows `.exe`, Debian `.deb`, Arch `.pkg.tar.zst`
170 - **Versioning:** Semver in `Cargo.toml`; `.pos` `version` for file-format migrations
178 171
179 See [PRINTING.md](PRINTING.md) and [DSL-SPEC.md](DSL-SPEC.md) for protocol and language details.
172 See [PRINTING.md](PRINTING.md), [DSL-SPEC.md](DSL-SPEC.md), and [BUILD.md](BUILD.md).
@@ -5,57 +5,73 @@
5posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language, no WebView, no IPC layer.
5posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language, no WebView, no IPC layer.
6
6
7```
7```
8┌─────────────────────────────────────────┐
8┌──────────────────────────────────────────────────┐
9│ posprint (Rust + egui) │
9│ posprint (Rust + egui) │
10│ - Editor / Preview / Help tabs │
10│ - Design (editor + preview) / Help │
11│ - DSL parse → AST │
11│ - DSL parse → AST → preview + ESC/POS │
12│ - Preview layout + in-tree ESC/POS │
12│ - USB-direct / Win spooler / serial printing │
13│ - USB-serial printer discovery/print │
13│ - `.pos` JSON load/save (serde) │
14│ - `.pos` JSON load/save (serde) │
14└──────────────────────────────────────────────────┘
15└─────────────────────────────────────────┘
16```
15```
17
16
18### Source layout
17### Source layout
19
18
20```
19```
21src/
20src/
22├── main.rs # eframe entry point
21├── main.rs # CLI + eframe / print-only entry
23├── app.rs # egui UI (editor, preview, help, print dialog)
22├── app.rs # Full designer UI
24├── lib.rs # crate root; exports + HELP_MARKDOWN
23├── print_only_app.rs # Print-only window (--print)
25├── dsl/ # Parser and AST (mod.rs, parser.rs)
24├── print_dialog.rs # Shared print dialog
26├── params.rs # Parameter collect/substitute
25├── cli.rs # clap: print, cli-help
27├── escpos.rs # ESC/POS byte encoder (in-tree)
26├── lib.rs # crate root; HELP_MARKDOWN
28├── preview.rs # Preview model for UI canvas
27├── dsl/ # Parser and AST
29├── io/mod.rs # .pos file format (PosFile, PosMetadata)
28├── params.rs # Parameter collect / substitute / preview samples
30└── print/mod.rs # USB-serial discovery, SerialTransport, MockTransport
29├── escpos.rs # ESC/POS byte encoder (in-tree)
30├── preview.rs # PreviewModel for UI canvas
31├── text_wrap.rs # Shared wrap (preview + print)
32├── datetime.rs # @date / @time formatting
33├── raster.rs # Barcode / QR bitmaps
34├── editor_assist.rs # @ autocomplete, Insert snippets
35├── help_view.rs # Markdown help renderer
36├── io/mod.rs # PosFile, PosMetadata
37├── pipeline.rs # Encode / print helpers
38├── print/
39│ ├── mod.rs # list_printers, SerialTransport, MockTransport
40│ ├── usb_direct.rs # USB printer-class (rusb)
41│ └── win_spool.rs # Windows spooler (Windows)
42└── shell_integration/ # OS “Print” context menu helpers
31```
43```
32
44
33### External dependencies (minimal)
45### External dependencies
34
46
35| Crate | Role |
47| Crate | Role |
36|-------|------|
48|-------|------|
37| `eframe` / `egui` | Native UI |
49| `eframe` / `egui` | Native UI |
38| `serde` / `serde_json` | `.pos` file format |
50| `serde` / `serde_json` | `.pos` file format |
39| `serialport` | USB-serial enumeration and I/O |
51| `serialport` | Serial enumeration and I/O |
40| `image` | Decode/resize images for `@image` raster print |
52| `rusb` | USB printer-class devices |
41| `rfd` | Native open/save file dialogs |
53| `image` | Decode/resize images |
54| `rfd` | Native open/save dialogs |
55| `barcoders` / `qrcode` | Raster barcodes and QR |
56| `clap` | CLI |
57| `chrono` | Date/time |
58| `pulldown-cmark` | In-app Help markdown |
42
59
43ESC/POS command generation is **not** delegated to a third-party crate.
60ESC/POS generation is **in-tree** (`escpos.rs`), not the `escpos` crates.io package.
44
61
45---
62---
46
63
47## UI structure
64## UI structure
48
65
49| Tab / area | Module | Description |
66| Area | Module | Description |
50|------------|--------|-------------|
67|------|--------|-------------|
51| **Editor** | `app.rs` | Multiline `TextEdit` (monospace) for template source |
68| **Design** | `app.rs` | Editor + side preview |
52| **Preview** | `app.rs` + `preview.rs` | Canvas render of `PreviewModel`; auto-scale or fixed mm |
69| **Help** | `help_view.rs` | `docs/HELP.md` via `include_str!` |
53| **Help** | `app.rs` | Scrollable view of `docs/HELP.md` via `include_str!` |
70| Toolbar | `app.rs` | New, Open, Save, Save As, Insert, Print |
54| Toolbar | `app.rs` | New, Open, Save, Save As, Print |
71| Settings | `app.rs` | Page width (mm), preview zoom |
55| Settings | `app.rs` | Page width (mm), preview mode |
72| Print dialog | `print_dialog.rs` | Parameters + multi-transport printer picker |
56| Print dialog | `app.rs` | Parameter fields + USB-serial printer picker |
57
73
58Bottom panel switches tabs. Top panel holds actions and settings.
74While the print dialog is open, the main UI is disabled and editor autocomplete does not steal focus.
59
75
60---
76---
61
77
@@ -63,117 +79,94 @@ Bottom panel switches tabs. Top panel holds actions and settings.
63
79
64### Edit loop (live preview)
80### Edit loop (live preview)
65
81
661. User types in the Editor tab.
821. User edits the template on the Design tab.
672. Each frame, `parse(&body)` runs; errors show in the toolbar.
832. Each frame, `parse(&body)` runs; errors show in the toolbar.
683. On Preview tab, `render_preview(&doc, &metadata)` builds a `PreviewModel`.
843. `render_preview` builds a `PreviewModel` (text, rules, bitmaps, spacers).
694. Canvas draws text lines, rules, and placeholders for barcode/QR/image.
854. Canvas draws with calibrated zoom (`PREVIEW_SCREEN_CALIBRATION`) and Font A–matched text size.
70
71Preview is **not debounced** — it re-parses when the Preview tab is shown (and parse runs every frame for error display).
72
86
73### Save / load
87### Save / load
74
88
751. **Open:** `rfd` file dialog → `PosFile::load_from_path` → populate `body`, `metadata`, `file_path`.
891. **Open:** `rfd` → `PosFile::load_from_path`.
762. **Save / Save As:** `PosFile::save_to_path` writes pretty-printed JSON.
902. **Save / Save As:** pretty-printed JSON.
77
91
78Image paths in `@image` resolve relative to the `.pos` file directory on print.
92`@image` paths resolve relative to the `.pos` directory on preview and print.
79
93
80### Print
94### Print
81
95
821. User clicks **Print** → parse body → `collect_parameter_names(&doc)`.
961. **Print** → parse → `collect_parameter_names`.
832. Modal shows one field per unique parameter; pre-filled from `last_params` (in-memory).
972. Dialog: one field per parameter; `list_printers()` for USB / spooler / serial.
843. User selects a USB-serial port from `list_usb_serial_printers()`.
983. `substitute_document` → `EscPosEncoder` → `open_printer` → `print_bytes`.
854. `substitute_document` → `EscPosEncoder::encode_document` → `SerialTransport::open` (9600 baud) → `print_bytes`.
994. Serial baud is probed (`115200` first, then `9600`, …).
86
100
87---
101---
88
102
89## Key types
103## Key types
90
104
91Implemented in `dsl/mod.rs`, `io/mod.rs`, `print/mod.rs`:
92
93```rust
105```rust
94// dsl/
106// dsl/
95struct Document { blocks: Vec<Block> }
107struct Document { blocks: Vec<Block> }
96
97enum Block {
108enum Block {
98 Paragraph { align, inlines },
109 Paragraph { align, inlines },
99 List { align, items },
110 List { align, items },
100 Heading { level, inlines },
111 Heading { level, align, inlines },
101 Rule,
112 Rule, Feed(u8), Cut,
102 Feed(u8),
113 Image { path, width, align },
103 Cut,
114 Barcode { mode, symbology, data, height, align, show_text },
104 Image { path, width: ImageWidth, align },
115 Qr { mode, data, size, ecc, version, align },
105 Barcode { symbology, data, height, align, show_text },
116 Date { format, align },
106 Qr { data, size, ecc, align },
117 Time { format, align },
107}
118}
119enum Inline { Text(String), Param(String) }
108
120
109// io/
121// io/
110struct PosFile { version, metadata: PosMetadata, body }
122struct PosMetadata { title, page_width_mm, chars_per_line, codepage }
111struct PosMetadata { title, page_width_mm, preview_mode, chars_per_line, codepage }
123// printable_dots() = chars_per_line() * 12
112
124
113// print/
125// print/
114struct PrinterDevice { id, display_name, port_name }
126enum PrinterTarget { Serial(String), UsbDirect { … }, WinSpooler(String) }
115trait PrinterTransport { write_all, flush }
116```
127```
117
128
129Legacy JSON fields `preview_mode` and `cut_after_print` are ignored if present.
130
118---
131---
119
132
120## Preview vs print fidelity
133## Preview vs print fidelity
121
134
122| Aspect | Preview | Print |
135| Aspect | Preview | Print |
123|--------|---------|-------|
136|--------|---------|-------|
124| Text font | egui monospace/proportional | Printer built-in font |
137| Text | egui monospace (print-matched size) | Printer Font A |
125| Line width | From `chars_per_line()` | ESC/POS dot width from `page_width_mm` |
138| Line width | `chars_per_line` / `printable_dots` | Same wrap model |
126| Images | `[image: path]` placeholder | Monochrome raster (GS v 0) |
139| Images / barcode / QR | Raster bitmaps | ESC/POS native or GS v 0 |
127| Barcodes / QR | Text placeholder | Native ESC/POS commands |
140| Blank lines | Spacer = line spacing dots | ESC d |
128| Alignment | Canvas positioning | ESC a |
141| Parameters | Sample / dialog values | Substituted values |
129
130Both paths share the same **AST**; substitution happens only at print time. Preview shows unresolved `${Param}` tokens as-is.
131
142
132---
143---
133
144
134## State persistence (current)
145## State persistence
135
146
136| Data | Storage | Notes |
147| Data | Storage |
137|------|---------|-------|
148|------|---------|
138| Template + metadata | `.pos` file on disk | User saves explicitly |
149| Template + metadata | `.pos` file |
139| Last parameter values | `PosPrintApp.last_params` | In-memory only; lost on quit |
150| Last parameter values | In-memory (`print_dialog.last_params`) |
140| Recent files | — | Not implemented |
151| Recent files / selected printer | Not persisted |
141| Selected printer | — | Not persisted between sessions |
142
152
143---
153---
144
154
145## Testing
155## Testing
146
156
147| Layer | Location | Approach |
157| Layer | Location |
148|-------|----------|----------|
158|-------|----------|
149| DSL parser | `dsl/parser.rs` | Unit tests |
159| DSL, params, ESC/POS, preview, wrap, I/O, print mocks | `src/**` unit tests |
150| Parameters | `params.rs` | Unit tests |
160| App / shell helpers | `src/main.rs` tests |
151| ESC/POS encoder | `escpos.rs` | Byte structure tests |
152| Preview | `preview.rs` | Unit tests |
153| `.pos` I/O | `io/mod.rs` | Round-trip + tempfile tests |
154| Printer I/O | `print/mod.rs` | `MockTransport`; no hardware in CI |
155| App | `app.rs` | Default template parse/param tests |
156
161
157Run: `cargo test` (20 tests). CI runs this on Linux (Docker) and Windows (shell runner).
162Run: `cargo test` (~100 tests). CI: tests on merge requests; release artifacts on tags.
158
163
159---
164---
160
165
161## Build and release
166## Build and release
162
167
163- **CI:** GitLab (`.gitlab-ci.yml`) — `cargo test` on push; release artifacts on tags.
168- **CI:** GitLab (`.gitlab-ci.yml`)
164- **Linux artifact:** `.deb` via `cargo-deb` (`[package.metadata.deb]` in `Cargo.toml`).
169- **Artifacts:** Windows `.exe`, Debian `.deb`, Arch `.pkg.tar.zst`
165- **Windows artifact:** `target/release/posprint.exe`.
170- **Versioning:** Semver in `Cargo.toml`; `.pos` `version` for file-format migrations
166- **Versioning:** Semver in `Cargo.toml`; `.pos` `version` field for file-format migrations.
167
168---
169
170## Planned (not implemented)
171
172- USB printer class (bulk OUT) without serial emulation
173- Bluetooth SPP
174- Network printers (TCP 9100)
175- Baud-rate autodetect / settings UI
176- Persisted last parameters and recent files
177- Syntax highlighting in editor
178
171
179See [PRINTING.md](PRINTING.md) and [DSL-SPEC.md](DSL-SPEC.md) for protocol and language details.
172See [PRINTING.md](PRINTING.md), [DSL-SPEC.md](DSL-SPEC.md), and [BUILD.md](BUILD.md).
docs/DSL-SPEC.md +86 −62
@@ -10,7 +10,7 @@ A lightweight, markdown-inspired syntax for POS receipt templates. The DSL compi
10 10
11 11 ## Document structure
12 12
13 A document is a sequence of **blocks** separated by blank lines. Blocks cannot be nested except for inline markup within text blocks.
13 A document is a sequence of **blocks**. Blank lines become paper feeds (`@feed 1`). Blocks are not nested except for `${parameters}` inside text.
14 14
15 15 ---
16 16
@@ -18,7 +18,7 @@ A document is a sequence of **blocks** separated by blank lines. Blocks cannot b
18 18
19 19 ### Paragraphs
20 20
21 Plain text with optional inline markup. One or more consecutive non-empty lines form a paragraph.
21 Plain text (and `${parameters}`). One or more consecutive non-empty lines form a paragraph. There is **no** inline bold/italic/code markup.
22 22
23 23 ```markdown
24 24 Thank you for your purchase!
@@ -132,36 +132,61 @@ Partial cut after content (if printer supports). Often placed at document end.
132 132 | `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |
133 133 | `align` | `left` (default), `center`, `right` |
134 134
135 Images are converted to monochrome raster data, dithered, and scaled to width.
135 Images are converted to monochrome raster data and scaled to width (never wider than `printable_dots`).
136
137 ### Date / time
138
139 ```markdown
140 @date
141 @date DD-MM-YYYY
142 @time
143 @time 12h
144 @time 24h
145 ```
146
147 | Directive | Behaviour |
148 |-----------|-----------|
149 | `@date` | System regional short date (`%x`) |
150 | `@date PATTERN` | Custom pattern (`YYYY`, `MM`, `DD`, …) |
151 | `@time` / `@time 24h` | 24-hour `HH:MM` |
152 | `@time 12h` | 12-hour with AM/PM |
136 153
137 154 ### Barcode
138 155
139 156 ```markdown
140 157 @barcode CODE128 ${Sku}
141 158 @barcode EAN13 ${EanCode} height=80
159 @barcode RASTER CODE128 ${Sku}
160 @barcode RASTER CODE93 ABC-1234
142 161 ```
143 162
144 163 | Field | Values |
145 164 |-------|--------|
146 | Symbology | `CODE128`, `EAN13`, `EAN8`, `CODE39` |
165 | Mode | Optional `RASTER` prefix; otherwise native ESC/POS |
166 | Symbology | Native: `CODE128`, `EAN13`, `EAN8`, `CODE39`, `UPC-A`, `UPC-E`, `ITF`, `CODABAR`. Raster-only: `CODE93`, `CODE11` |
147 167 | Data | Literal or `${Param}` |
148 | `height` | Module height in dots (default: 64) |
168 | `height` | Module / PNG height in dots (default: 64) |
149 169 | `align` | `left`, `center`, `right` |
150 | `show_text` | `true` / `false` — HRI below barcode (default: true) |
170 | `show_text` | Native only: HRI below barcode |
171
172 Raster barcodes stretch horizontally to full printable width.
151 173
152 174 ### QR code
153 175
154 176 ```markdown
155 177 @qr https://example.com/receipt/${DocumentNumber}
156 @qr ${PaymentUrl} size=6
178 @qr ${PaymentUrl} size=6 ecc=H
179 @qr RASTER ${PaymentUrl} version=5 scale=4 ecc=M
157 180 ```
158 181
159 | Attribute | Description |
160 |-----------|-------------|
161 | Data (positional) | URL or text; may include `${Param}` |
162 | `size` | Module size 1–16 (default: 4) |
163 | `ecc` | Error correction: `L`, `M`, `Q`, `H` (default: `M`) |
164 | `align` | `left`, `center`, `right` |
182 | Attribute | Native | Raster |
183 |-----------|--------|--------|
184 | Data | URL/text; may include `${Param}` | Same |
185 | `size` | Module size 1–16 (default 4) | — |
186 | `scale` | — | Pixels per module (default 4) |
187 | `version` | — | QR version 1–40 (optional) |
188 | `ecc` | `L`, `M`, `Q`, `H` (default `M`) | Same |
189 | `align` | `left`, `center`, `right` | Same |
165 190
166 191 ---
167 192
@@ -190,67 +215,38 @@ ${ParameterName}
190 215
191 216 1. Before print, scan AST for all `${...}` tokens.
192 217 2. Deduplicate by name.
193 3. Show dialog with one field per unique name.
194 4. Pre-fill from last print session (global or per-file — implementation choice).
195 5. Substitute into AST, then render/print.
218 3. Show dialog with one field per unique name (or require CLI `--set`).
219 4. Pre-fill from last print session (in-memory).
220 5. Substitute into AST, then encode/print.
196 221
197 Missing parameter at print time: block print and highlight unresolved names in UI.
222 Missing parameter at print time: block print and highlight unresolved names.
198 223
199 224 ---
200 225
201 226 ## Comments
202 227
203 228 ```markdown
204 <!-- This is a comment, not printed -->
229 <!-- this is not printed -->
205 230 ```
206 231
207 HTML-style comments are stripped at parse time.
208
209 ---
210
211 ## Example document
212
213 ```markdown
214 # ${StoreName}
215 :center:
216
217 123 Main Street
218 Tel: ${StorePhone}
219
220 ---
221 Date: ${Date} Time: ${Time}
222 Receipt: ${DocumentNumber}
223
224 Item Total
225 ${LineItems}
232 HTML-style comments are stripped before parse.
226 233
227 234 ---
228 :right:
229 **TOTAL: ${GrandTotal}**
230 235
231 @barcode CODE128 ${DocumentNumber}
232 @feed 2
233 @qr https://shop.example.com/r/${DocumentNumber}
234
235 Thank you!
236 @feed 4
237 @cut
238 ```
236 ## Blank lines
239 237
240 `${LineItems}` might be pre-formatted multi-line text passed as a single parameter (v1); structured line items are a future extension.
238 A blank line (or whitespace-only line) inserts `Feed(1)` — same paper advance as `@feed 1`. On print this becomes `ESC d 1` (reliable after raster graphics).
241 239
242 240 ---
243 241
244 ## Parse errors
242 ## Error reporting
245 243
246 The parser reports:
244 Parse errors include 1-based line and column. Typical causes:
247 245
248 - Unknown directive
249 246 - Invalid barcode symbology
250 247 - Invalid `${}` name
251 248 - Missing required directive argument
252
253 Errors include 1-based line and column for editor highlighting.
249 - Unknown `@time` format
254 250
255 251 ---
256 252
@@ -262,22 +258,50 @@ Errors include 1-based line and column for editor highlighting.
262 258 | `## heading` | Bold ON → text → OFF |
263 259 | `- item` | ASCII `* ` bullet + hanging wrap |
264 260 | `:center:` | Justification center |
265 | `@feed n` | Print and feed n lines |
261 | `@feed n` / blank line | ESC d n |
266 262 | `@cut` | GS V partial cut |
267 | `@barcode` | GS k / CODE128 native |
268 | `@qr` | GS ( k QR model 2 |
263 | `@barcode` | GS k or GS v 0 raster |
264 | `@qr` | GS ( k or GS v 0 raster |
269 265 | `@image` | GS v 0 raster bit image |
266 | `@date` / `@time` | Plain text lines |
270 267
271 Full command details live in the print encoder module; see [PRINTING.md](PRINTING.md).
268 Full command details: [PRINTING.md](PRINTING.md).
272 269
273 270 ---
274 271
275 272 ## Future extensions (not implemented)
276 273
277 274 - `@table` for columnar line items
278 - `UPC-A` barcodes
279 - Conditionals: `@if ${HasDiscount} ... @endif`
280 - Loops / repeating sections
281 - `@signature` for custom ESC/POS hex escape
282 - Multiple code pages / Unicode subset
275 - Nested lists / numbered lists
276 - Bluetooth / network printer transports
283 277 - Syntax highlighting in the editor
278
279 ---
280
281 ## Example document
282
283 ```markdown
284 # ${StoreName}
285 :center:
286
287 123 Main Street
288
289 ---
290 @date
291 @time
292 Receipt: ${DocumentNumber}
293
294 - Item one
295 - Item two
296
297 :right:
298 TOTAL: ${GrandTotal}
299
300 @barcode CODE128 ${DocumentNumber}
301 @feed 2
302 @qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
303
304 Thank you!
305 @feed 4
306 @cut
307 ```
@@ -10,7 +10,7 @@ A lightweight, markdown-inspired syntax for POS receipt templates. The DSL compi
10
10
11## Document structure
11## Document structure
12
12
13A document is a sequence of **blocks** separated by blank lines. Blocks cannot be nested except for inline markup within text blocks.
13A document is a sequence of **blocks**. Blank lines become paper feeds (`@feed 1`). Blocks are not nested except for `${parameters}` inside text.
14
14
15---
15---
16
16
@@ -18,7 +18,7 @@ A document is a sequence of **blocks** separated by blank lines. Blocks cannot b
18
18
19### Paragraphs
19### Paragraphs
20
20
21Plain text with optional inline markup. One or more consecutive non-empty lines form a paragraph.
21Plain text (and `${parameters}`). One or more consecutive non-empty lines form a paragraph. There is **no** inline bold/italic/code markup.
22
22
23```markdown
23```markdown
24Thank you for your purchase!
24Thank you for your purchase!
@@ -132,36 +132,61 @@ Partial cut after content (if printer supports). Often placed at document end.
132| `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |
132| `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |
133| `align` | `left` (default), `center`, `right` |
133| `align` | `left` (default), `center`, `right` |
134
134
135Images are converted to monochrome raster data, dithered, and scaled to width.
135Images are converted to monochrome raster data and scaled to width (never wider than `printable_dots`).
136
137### Date / time
138
139```markdown
140@date
141@date DD-MM-YYYY
142@time
143@time 12h
144@time 24h
145```
146
147| Directive | Behaviour |
148|-----------|-----------|
149| `@date` | System regional short date (`%x`) |
150| `@date PATTERN` | Custom pattern (`YYYY`, `MM`, `DD`, …) |
151| `@time` / `@time 24h` | 24-hour `HH:MM` |
152| `@time 12h` | 12-hour with AM/PM |
136
153
137### Barcode
154### Barcode
138
155
139```markdown
156```markdown
140@barcode CODE128 ${Sku}
157@barcode CODE128 ${Sku}
141@barcode EAN13 ${EanCode} height=80
158@barcode EAN13 ${EanCode} height=80
159@barcode RASTER CODE128 ${Sku}
160@barcode RASTER CODE93 ABC-1234
142```
161```
143
162
144| Field | Values |
163| Field | Values |
145|-------|--------|
164|-------|--------|
146| Symbology | `CODE128`, `EAN13`, `EAN8`, `CODE39` |
165| Mode | Optional `RASTER` prefix; otherwise native ESC/POS |
166| Symbology | Native: `CODE128`, `EAN13`, `EAN8`, `CODE39`, `UPC-A`, `UPC-E`, `ITF`, `CODABAR`. Raster-only: `CODE93`, `CODE11` |
147| Data | Literal or `${Param}` |
167| Data | Literal or `${Param}` |
148| `height` | Module height in dots (default: 64) |
168| `height` | Module / PNG height in dots (default: 64) |
149| `align` | `left`, `center`, `right` |
169| `align` | `left`, `center`, `right` |
150| `show_text` | `true` / `false` — HRI below barcode (default: true) |
170| `show_text` | Native only: HRI below barcode |
171
172Raster barcodes stretch horizontally to full printable width.
151
173
152### QR code
174### QR code
153
175
154```markdown
176```markdown
155@qr https://example.com/receipt/${DocumentNumber}
177@qr https://example.com/receipt/${DocumentNumber}
156@qr ${PaymentUrl} size=6
178@qr ${PaymentUrl} size=6 ecc=H
179@qr RASTER ${PaymentUrl} version=5 scale=4 ecc=M
157```
180```
158
181
159| Attribute | Description |
182| Attribute | Native | Raster |
160|-----------|-------------|
183|-----------|--------|--------|
161| Data (positional) | URL or text; may include `${Param}` |
184| Data | URL/text; may include `${Param}` | Same |
162| `size` | Module size 1–16 (default: 4) |
185| `size` | Module size 1–16 (default 4) | — |
163| `ecc` | Error correction: `L`, `M`, `Q`, `H` (default: `M`) |
186| `scale` | — | Pixels per module (default 4) |
164| `align` | `left`, `center`, `right` |
187| `version` | — | QR version 1–40 (optional) |
188| `ecc` | `L`, `M`, `Q`, `H` (default `M`) | Same |
189| `align` | `left`, `center`, `right` | Same |
165
190
166---
191---
167
192
@@ -190,67 +215,38 @@ ${ParameterName}
190
215
1911. Before print, scan AST for all `${...}` tokens.
2161. Before print, scan AST for all `${...}` tokens.
1922. Deduplicate by name.
2172. Deduplicate by name.
1933. Show dialog with one field per unique name.
2183. Show dialog with one field per unique name (or require CLI `--set`).
1944. Pre-fill from last print session (global or per-file — implementation choice).
2194. Pre-fill from last print session (in-memory).
1955. Substitute into AST, then render/print.
2205. Substitute into AST, then encode/print.
196
221
197Missing parameter at print time: block print and highlight unresolved names in UI.
222Missing parameter at print time: block print and highlight unresolved names.
198
223
199---
224---
200
225
201## Comments
226## Comments
202
227
203```markdown
228```markdown
204<!-- This is a comment, not printed -->
229<!-- this is not printed -->
205```
230```
206
231
207HTML-style comments are stripped at parse time.
232HTML-style comments are stripped before parse.
208
209---
210
211## Example document
212
213```markdown
214# ${StoreName}
215:center:
216
217123 Main Street
218Tel: ${StorePhone}
219
220---
221Date: ${Date} Time: ${Time}
222Receipt: ${DocumentNumber}
223
224Item Total
225${LineItems}
226
233
227---
234---
228:right:
229**TOTAL: ${GrandTotal}**
230
235
231@barcode CODE128 ${DocumentNumber}
236## Blank lines
232@feed 2
233@qr https://shop.example.com/r/${DocumentNumber}
234
235Thank you!
236@feed 4
237@cut
238```
239
237
240`${LineItems}` might be pre-formatted multi-line text passed as a single parameter (v1); structured line items are a future extension.
238A blank line (or whitespace-only line) inserts `Feed(1)` — same paper advance as `@feed 1`. On print this becomes `ESC d 1` (reliable after raster graphics).
241
239
242---
240---
243
241
244## Parse errors
242## Error reporting
245
243
246The parser reports:
244Parse errors include 1-based line and column. Typical causes:
247
245
248- Unknown directive
249- Invalid barcode symbology
246- Invalid barcode symbology
250- Invalid `${}` name
247- Invalid `${}` name
251- Missing required directive argument
248- Missing required directive argument
252
249- Unknown `@time` format
253Errors include 1-based line and column for editor highlighting.
254
250
255---
251---
256
252
@@ -262,22 +258,50 @@ Errors include 1-based line and column for editor highlighting.
262| `## heading` | Bold ON → text → OFF |
258| `## heading` | Bold ON → text → OFF |
263| `- item` | ASCII `* ` bullet + hanging wrap |
259| `- item` | ASCII `* ` bullet + hanging wrap |
264| `:center:` | Justification center |
260| `:center:` | Justification center |
265| `@feed n` | Print and feed n lines |
261| `@feed n` / blank line | ESC d n |
266| `@cut` | GS V partial cut |
262| `@cut` | GS V partial cut |
267| `@barcode` | GS k / CODE128 native |
263| `@barcode` | GS k or GS v 0 raster |
268| `@qr` | GS ( k QR model 2 |
264| `@qr` | GS ( k or GS v 0 raster |
269| `@image` | GS v 0 raster bit image |
265| `@image` | GS v 0 raster bit image |
266| `@date` / `@time` | Plain text lines |
270
267
271Full command details live in the print encoder module; see [PRINTING.md](PRINTING.md).
268Full command details: [PRINTING.md](PRINTING.md).
272
269
273---
270---
274
271
275## Future extensions (not implemented)
272## Future extensions (not implemented)
276
273
277- `@table` for columnar line items
274- `@table` for columnar line items
278- `UPC-A` barcodes
275- Nested lists / numbered lists
279- Conditionals: `@if ${HasDiscount} ... @endif`
276- Bluetooth / network printer transports
280- Loops / repeating sections
281- `@signature` for custom ESC/POS hex escape
282- Multiple code pages / Unicode subset
283- Syntax highlighting in the editor
277- Syntax highlighting in the editor
278
279---
280
281## Example document
282
283```markdown
284# ${StoreName}
285:center:
286
287123 Main Street
288
289---
290@date
291@time
292Receipt: ${DocumentNumber}
293
294- Item one
295- Item two
296
297:right:
298TOTAL: ${GrandTotal}
299
300@barcode CODE128 ${DocumentNumber}
301@feed 2
302@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
303
304Thank you!
305@feed 4
306@cut
307```
docs/FEASIBILITY.md deleted +0 −166
@@ -1,166 +0,0 @@
1 # Feasibility and complexity assessment
2
3 > **Status:** MVP (v0.1.0) **implemented** — Rust + egui, USB-serial printing, 20 unit tests. This document retains the original feasibility analysis; see [ARCHITECTURE.md](ARCHITECTURE.md) for what is built today.
4
5 ## Executive summary
6
7 | Question | Answer |
8 |----------|--------|
9 | Is it feasible? | **Yes** — all required capabilities exist in mature libraries or documented protocols |
10 | Overall complexity | **Medium–high** for a complete v1; **medium** if Bluetooth is deferred |
11 | Biggest risk | Cross-platform raw printer I/O (USB class, serial, Bluetooth SPP) |
12 | Recommended MVP scope | USB-serial printers first (**done**); USB-printer-class and Bluetooth later |
13
14 A focused MVP is realistic for one developer in roughly **6–10 weeks**. A polished v1 with broad printer compatibility is closer to **3–4 months**.
15
16 ---
17
18 ## Requirements breakdown
19
20 ### 1. Cross-platform desktop app (Windows + Linux)
21
22 | Aspect | Feasibility | Complexity |
23 |--------|-------------|------------|
24 | Single codebase, native binaries | High | Low–medium |
25 | Packaged installers (.msi/.exe, .deb/AppImage) | High | Medium |
26
27 Modern cross-platform desktop frameworks (Tauri, egui, Avalonia, Qt) all support Windows and Linux. Packaging is routine but needs CI and per-OS testing.
28
29 ### 2. Markdown-like document syntax + live preview
30
31 | Aspect | Feasibility | Complexity |
32 |--------|-------------|------------|
33 | Custom lightweight DSL | High | Medium |
34 | Live preview pane | High | Medium |
35 | Width modes (auto-scale / fixed mm) | High | Low–medium |
36
37 The DSL does not need full CommonMark — a small, POS-oriented grammar keeps the parser simple. Preview renders to a monospace layout matching printer dot width (e.g. 384 dots @ 58 mm, 576 dots @ 80 mm). Matching exact printer fonts is approximate in preview; exact fidelity is only guaranteed at print time.
38
39 ### 3. Save / load `.pos` files
40
41 | Aspect | Feasibility | Complexity |
42 |--------|-------------|------------|
43 | JSON or TOML envelope + body text | High | Low |
44
45 Trivial with serde (Rust) or equivalent. Version field supports forward-compatible evolution.
46
47 ### 4. Parameter tokens (`${Name}`)
48
49 | Aspect | Feasibility | Complexity |
50 |--------|-------------|------------|
51 | Parse and collect unique names | High | Low |
52 | Print-time modal with last-used values | High | Low |
53 | Deduplicate same name across document | High | Low |
54 | Use in text, barcodes, QR, images | High | Low–medium |
55
56 Straightforward string substitution after validation. Image parameters might reference file paths or base64 — define clearly in DSL spec.
57
58 ### 5. Barcodes, QR codes, images
59
60 | Aspect | Feasibility | Complexity |
61 |--------|-------------|------------|
62 | Generate ESC/POS barcode commands | High | Low |
63 | Generate ESC/POS QR commands | High | Low |
64 | Rasterize images to printer width | High | Medium |
65
66 ESC/POS barcode, QR, and raster image commands are implemented in `src/escpos.rs` (in-tree). Preview uses text placeholders for barcodes/QR/images.
67
68 ### 6. Direct USB / Bluetooth printing (raw bytes, no spooler)
69
70 | Aspect | Feasibility | Complexity |
71 |--------|-------------|------------|
72 | USB serial (CDC-ACM, CH340, FTDI) | **High** | Medium |
73 | USB printer class (bulk OUT) | Medium | **High** |
74 | Bluetooth Classic SPP | Medium | **High** |
75 | Enumerate devices in UI | Medium | Medium |
76 | Printer-specific quirks | Ongoing | **High** |
77
78 This is the **primary technical risk**.
79
80 #### How POS printers actually connect
81
82 Most consumer thermal printers expose one of:
83
84 1. **Virtual COM port (USB-serial)** — very common; appears as `COM3` (Windows) or `/dev/ttyUSB0` / `/dev/ttyACM0` (Linux). Raw ESC/POS bytes are written to the serial port. **Easiest path.**
85
86 2. **USB printer class (interface 7)** — bulk transfers; **not implemented**. Would need `nusb` or Windows `usbprint.sys`.
87
88 3. **Bluetooth Classic SPP** — **not implemented**; deferred.
89
90 4. **Network (TCP 9100)** — common in production but **out of scope** unless added later.
91
92 “No drivers” in practice means **no Windows print spooler / CUPS job** — the app opens the device directly and writes bytes. USB-serial devices often need only the generic CDC driver already present. USB-printer-class devices on Windows may still use `usbprint.sys`, which is a kernel driver but not a vendor-specific print driver.
93
94 #### Compatibility reality
95
96 - **MVP (done):** Epson-compatible ESC/POS over USB-serial at 9600 baud.
97 - **Future:** USB printer class, Bluetooth SPP.
98
99 Expect **per-printer testing**; some devices need init sequences, code pages, or cut commands that differ slightly.
100
101 ---
102
103 ## Complexity by subsystem
104
105 ```
106 Effort (relative)
107 Editor UI ████████░░ Medium
108 Preview renderer ███████░░░ Medium
109 DSL parser ██████░░░░ Medium
110 File I/O ██░░░░░░░░ Low
111 Parameters ███░░░░░░░ Low
112 Barcode/QR/image █████░░░░░ Low–medium
113 Printer discovery ███████░░░ Medium
114 Raw print I/O █████████░ High
115 Integration/polish ██████░░░░ Medium
116 ```
117
118 ---
119
120 ## Effort estimate (one experienced developer)
121
122 | Phase | Scope | Duration |
123 |-------|-------|----------|
124 | **0 — Design** | Specs, DSL, file format | 1 week |
125 | **1 — Core** | Parser, ESC/POS builder, preview, `.pos` I/O | 2–3 weeks |
126 | **2 — UI** | Editor, preview split, settings, parameters dialog | 2 weeks |
127 | **3 — Print MVP** | USB-serial enumeration + print | 1–2 weeks |
128 | **4 — Hardening** | USB class, BT, edge cases, packaging | 2–4 weeks |
129
130 **MVP (serial USB only):** ~6–8 weeks
131 **Full v1 (USB + BT, packaged):** ~10–14 weeks
132
133 Add 30–50% if the developer is new to Rust or ESC/POS.
134
135 ---
136
137 ## Risks and mitigations
138
139 | Risk | Impact | Mitigation |
140 |------|--------|------------|
141 | Printer hardware diversity | Prints garbled or not at all | ESC/POS subset doc; test matrix; user-selectable code page |
142 | Linux permissions (`dialout`) | Cannot open serial port | Document group membership; clear error UI |
143 | Windows USB access | Admin / driver conflicts | Prefer serial-first; use `usbprint` where applicable |
144 | Bluetooth pairing UX | Users cannot find printer | Defer BT; link to OS pairing instructions |
145 | Preview ≠ print | User confusion | Label preview as approximate; same backend for print |
146 | Image size on narrow paper | Slow print or clipped | Auto-scale to page width; warn in UI |
147
148 ---
149
150 ## Out of scope (current release)
151
152 - Bluetooth printing
153 - USB printer class (non-serial)
154 - Network printers (TCP 9100)
155 - Non-ESC/POS protocols (Star Line, ZPL)
156 - Multi-column layout engines
157 - Collaborative editing / cloud sync
158 - macOS (feasible later with same stack)
159
160 ---
161
162 ## Recommendation
163
164 **MVP delivered.** Next increments: USB printer class, baud settings, persisted parameters, hardware test matrix. Bluetooth only if explicitly needed.
165
166 See [LANGUAGE-CHOICE.md](LANGUAGE-CHOICE.md) and [ARCHITECTURE.md](ARCHITECTURE.md).
@@ -1,166 +0,0 @@
1# Feasibility and complexity assessment
2
3> **Status:** MVP (v0.1.0) **implemented** — Rust + egui, USB-serial printing, 20 unit tests. This document retains the original feasibility analysis; see [ARCHITECTURE.md](ARCHITECTURE.md) for what is built today.
4
5## Executive summary
6
7| Question | Answer |
8|----------|--------|
9| Is it feasible? | **Yes** — all required capabilities exist in mature libraries or documented protocols |
10| Overall complexity | **Medium–high** for a complete v1; **medium** if Bluetooth is deferred |
11| Biggest risk | Cross-platform raw printer I/O (USB class, serial, Bluetooth SPP) |
12| Recommended MVP scope | USB-serial printers first (**done**); USB-printer-class and Bluetooth later |
13
14A focused MVP is realistic for one developer in roughly **6–10 weeks**. A polished v1 with broad printer compatibility is closer to **3–4 months**.
15
16---
17
18## Requirements breakdown
19
20### 1. Cross-platform desktop app (Windows + Linux)
21
22| Aspect | Feasibility | Complexity |
23|--------|-------------|------------|
24| Single codebase, native binaries | High | Low–medium |
25| Packaged installers (.msi/.exe, .deb/AppImage) | High | Medium |
26
27Modern cross-platform desktop frameworks (Tauri, egui, Avalonia, Qt) all support Windows and Linux. Packaging is routine but needs CI and per-OS testing.
28
29### 2. Markdown-like document syntax + live preview
30
31| Aspect | Feasibility | Complexity |
32|--------|-------------|------------|
33| Custom lightweight DSL | High | Medium |
34| Live preview pane | High | Medium |
35| Width modes (auto-scale / fixed mm) | High | Low–medium |
36
37The DSL does not need full CommonMark — a small, POS-oriented grammar keeps the parser simple. Preview renders to a monospace layout matching printer dot width (e.g. 384 dots @ 58 mm, 576 dots @ 80 mm). Matching exact printer fonts is approximate in preview; exact fidelity is only guaranteed at print time.
38
39### 3. Save / load `.pos` files
40
41| Aspect | Feasibility | Complexity |
42|--------|-------------|------------|
43| JSON or TOML envelope + body text | High | Low |
44
45Trivial with serde (Rust) or equivalent. Version field supports forward-compatible evolution.
46
47### 4. Parameter tokens (`${Name}`)
48
49| Aspect | Feasibility | Complexity |
50|--------|-------------|------------|
51| Parse and collect unique names | High | Low |
52| Print-time modal with last-used values | High | Low |
53| Deduplicate same name across document | High | Low |
54| Use in text, barcodes, QR, images | High | Low–medium |
55
56Straightforward string substitution after validation. Image parameters might reference file paths or base64 — define clearly in DSL spec.
57
58### 5. Barcodes, QR codes, images
59
60| Aspect | Feasibility | Complexity |
61|--------|-------------|------------|
62| Generate ESC/POS barcode commands | High | Low |
63| Generate ESC/POS QR commands | High | Low |
64| Rasterize images to printer width | High | Medium |
65
66ESC/POS barcode, QR, and raster image commands are implemented in `src/escpos.rs` (in-tree). Preview uses text placeholders for barcodes/QR/images.
67
68### 6. Direct USB / Bluetooth printing (raw bytes, no spooler)
69
70| Aspect | Feasibility | Complexity |
71|--------|-------------|------------|
72| USB serial (CDC-ACM, CH340, FTDI) | **High** | Medium |
73| USB printer class (bulk OUT) | Medium | **High** |
74| Bluetooth Classic SPP | Medium | **High** |
75| Enumerate devices in UI | Medium | Medium |
76| Printer-specific quirks | Ongoing | **High** |
77
78This is the **primary technical risk**.
79
80#### How POS printers actually connect
81
82Most consumer thermal printers expose one of:
83
841. **Virtual COM port (USB-serial)** — very common; appears as `COM3` (Windows) or `/dev/ttyUSB0` / `/dev/ttyACM0` (Linux). Raw ESC/POS bytes are written to the serial port. **Easiest path.**
85
862. **USB printer class (interface 7)** — bulk transfers; **not implemented**. Would need `nusb` or Windows `usbprint.sys`.
87
883. **Bluetooth Classic SPP** — **not implemented**; deferred.
89
904. **Network (TCP 9100)** — common in production but **out of scope** unless added later.
91
92“No drivers” in practice means **no Windows print spooler / CUPS job** — the app opens the device directly and writes bytes. USB-serial devices often need only the generic CDC driver already present. USB-printer-class devices on Windows may still use `usbprint.sys`, which is a kernel driver but not a vendor-specific print driver.
93
94#### Compatibility reality
95
96- **MVP (done):** Epson-compatible ESC/POS over USB-serial at 9600 baud.
97- **Future:** USB printer class, Bluetooth SPP.
98
99Expect **per-printer testing**; some devices need init sequences, code pages, or cut commands that differ slightly.
100
101---
102
103## Complexity by subsystem
104
105```
106 Effort (relative)
107Editor UI ████████░░ Medium
108Preview renderer ███████░░░ Medium
109DSL parser ██████░░░░ Medium
110File I/O ██░░░░░░░░ Low
111Parameters ███░░░░░░░ Low
112Barcode/QR/image █████░░░░░ Low–medium
113Printer discovery ███████░░░ Medium
114Raw print I/O █████████░ High
115Integration/polish ██████░░░░ Medium
116```
117
118---
119
120## Effort estimate (one experienced developer)
121
122| Phase | Scope | Duration |
123|-------|-------|----------|
124| **0 — Design** | Specs, DSL, file format | 1 week |
125| **1 — Core** | Parser, ESC/POS builder, preview, `.pos` I/O | 2–3 weeks |
126| **2 — UI** | Editor, preview split, settings, parameters dialog | 2 weeks |
127| **3 — Print MVP** | USB-serial enumeration + print | 1–2 weeks |
128| **4 — Hardening** | USB class, BT, edge cases, packaging | 2–4 weeks |
129
130**MVP (serial USB only):** ~6–8 weeks
131**Full v1 (USB + BT, packaged):** ~10–14 weeks
132
133Add 30–50% if the developer is new to Rust or ESC/POS.
134
135---
136
137## Risks and mitigations
138
139| Risk | Impact | Mitigation |
140|------|--------|------------|
141| Printer hardware diversity | Prints garbled or not at all | ESC/POS subset doc; test matrix; user-selectable code page |
142| Linux permissions (`dialout`) | Cannot open serial port | Document group membership; clear error UI |
143| Windows USB access | Admin / driver conflicts | Prefer serial-first; use `usbprint` where applicable |
144| Bluetooth pairing UX | Users cannot find printer | Defer BT; link to OS pairing instructions |
145| Preview ≠ print | User confusion | Label preview as approximate; same backend for print |
146| Image size on narrow paper | Slow print or clipped | Auto-scale to page width; warn in UI |
147
148---
149
150## Out of scope (current release)
151
152- Bluetooth printing
153- USB printer class (non-serial)
154- Network printers (TCP 9100)
155- Non-ESC/POS protocols (Star Line, ZPL)
156- Multi-column layout engines
157- Collaborative editing / cloud sync
158- macOS (feasible later with same stack)
159
160---
161
162## Recommendation
163
164**MVP delivered.** Next increments: USB printer class, baud settings, persisted parameters, hardware test matrix. Bluetooth only if explicitly needed.
165
166See [LANGUAGE-CHOICE.md](LANGUAGE-CHOICE.md) and [ARCHITECTURE.md](ARCHITECTURE.md).
docs/FILE-FORMAT.md +32 −49
@@ -3,7 +3,7 @@
3 3 A `.pos` file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text.
4 4
5 5 **Format:** JSON envelope with a `.pos` extension (human-readable, git-friendly).
6 **MIME type (suggested):** `application/vnd.posprint+json`
6 **Installed MIME type:** `application/x-posprint` (see packaging MIME XML).
7 7
8 8 ---
9 9
@@ -21,7 +21,7 @@ A `.pos` file stores a POS print template: metadata (page settings, title) plus
21 21 |-------|------|----------|-------------|
22 22 | `version` | `number` | yes | File format version (currently `1`) |
23 23 | `metadata` | `object` | yes | Document settings |
24 | `body` | `string` | yes | DSL source (UTF-8, `\n` line endings normalized on load) |
24 | `body` | `string` | yes | DSL source (UTF-8) |
25 25
26 26 ---
27 27
@@ -38,18 +38,30 @@ A `.pos` file stores a POS print template: metadata (page settings, title) plus
38 38
39 39 | Field | Type | Default | Description |
40 40 |-------|------|---------|-------------|
41 | `title` | `string?` | `null` | Display name in app title / recent files |
42 | `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) |
43 | `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content |
44 | `chars_per_line` | `number?` | derived | Override character width for preview/print width model; derived from mm if omitted |
45 | `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text |
41 | `title` | `string?` | `null` | Display name in app title |
42 | `page_width_mm` | `number` | `80` | Physical paper width (mm) |
43 | `chars_per_line` | `number?` | derived | Override column count; derived from mm if omitted |
44 | `codepage` | `string?` | `"CP437"` | Reserved; encoder uses CP437 today |
46 45
47 ### Page width derivation
46 ### Printable width model
48 47
49 | `page_width_mm` | Effective printable dots (Font A) | Default `chars_per_line` (Font A) |
50 |-----------------|----------------------------------|-----------------------------------|
51 | 53-58 | 384 | 32 |
52 | >58 | 576 | 48 |
48 Effective print/preview width uses Font A columns:
49
50 `printable_dots = chars_per_line() × 12`
51
52 | `page_width_mm` | Default `chars_per_line` | `printable_dots` |
53 |-----------------|--------------------------|------------------|
54 | ≤ 58 | 32 | 384 |
55 | > 58 | 48 | 576 |
56
57 ### Legacy fields (ignored)
58
59 Unknown JSON keys are ignored by serde. Notably:
60
61 | Field | Former meaning | Current behaviour |
62 |-------|----------------|-------------------|
63 | `preview_mode` | autoscale / fixed preview | Ignored; UI uses zoom slider |
64 | `cut_after_print` | auto-cut after job | Ignored; use `@cut` in the template |
53 65
54 66 ---
55 67
@@ -65,19 +77,16 @@ A `.pos` file stores a POS print template: metadata (page settings, title) plus
65 77 "page_width_mm": 80,
66 78 "codepage": "CP437"
67 79 },
68 "body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\n**TOTAL: ${GrandTotal}**\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"
80 "body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\nTOTAL: ${GrandTotal}\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"
69 81 }
70 82 ```
71 83
72 For readability, the app may save `body` with literal newlines (pretty-printed JSON) when the user chooses “formatted save”; both pretty and escaped forms are valid.
73
74 84 ---
75 85
76 86 ## Asset resolution
77 87
78 - Paths in `@image` directives are resolved relative to the **directory containing the `.pos` file** unless absolute.
79 - Bundled assets: optional `assets/` subfolder next to the template.
80 - Parameterized image paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` file directory.
88 - Paths in `@image` resolve relative to the **directory containing the `.pos` file** unless absolute.
89 - Parameterized paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` directory.
81 90
82 91 ---
83 92
@@ -87,42 +96,16 @@ For readability, the app may save `body` with literal newlines (pretty-printed J
87 96 |------|-----|-----------|
88 97 | — | 1 | Initial release |
89 98
90 On load, if `version` is newer than app supports → error with upgrade message.
91 If older → run migration chain (none yet).
99 On load, if `version` is newer than the app supports → error. Older versions would migrate (none yet).
92 100
93 101 ---
94 102
95 ## Validation rules
96
97 On save:
103 ## Validation
98 104
99 - `version` must equal supported version
100 - `page_width_mm` > 0
101 - `body` must be valid UTF-8
102
103 On load:
104
105 - Parse JSON; validate schema
106 - Parse `body` with DSL parser; warnings shown in UI but file still loads
105 On save / load: JSON parse, `version == 1`, `page_width_mm > 0`, UTF-8 body. DSL parse errors show in the UI; the file can still load.
107 106
108 107 ---
109 108
110 ## TypeScript / Rust types (reference)
111
112 ```typescript
113 interface PosFile {
114 version: number;
115 metadata: PosMetadata;
116 body: string;
117 }
118
119 interface PosMetadata {
120 title?: string;
121 page_width_mm: number;
122 preview_mode: "autoscale" | "fixed";
123 chars_per_line?: number;
124 codepage?: string;
125 }
126 ```
109 ## Rust types
127 110
128 Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer).
111 Defined in `src/io/mod.rs` (`PosFile`, `PosMetadata`) with `serde` derive. Used directly by the egui app (no IPC).
@@ -3,7 +3,7 @@
3A `.pos` file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text.
3A `.pos` file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text.
4
4
5**Format:** JSON envelope with a `.pos` extension (human-readable, git-friendly).
5**Format:** JSON envelope with a `.pos` extension (human-readable, git-friendly).
6**MIME type (suggested):** `application/vnd.posprint+json`
6**Installed MIME type:** `application/x-posprint` (see packaging MIME XML).
7
7
8---
8---
9
9
@@ -21,7 +21,7 @@ A `.pos` file stores a POS print template: metadata (page settings, title) plus
21|-------|------|----------|-------------|
21|-------|------|----------|-------------|
22| `version` | `number` | yes | File format version (currently `1`) |
22| `version` | `number` | yes | File format version (currently `1`) |
23| `metadata` | `object` | yes | Document settings |
23| `metadata` | `object` | yes | Document settings |
24| `body` | `string` | yes | DSL source (UTF-8, `\n` line endings normalized on load) |
24| `body` | `string` | yes | DSL source (UTF-8) |
25
25
26---
26---
27
27
@@ -38,18 +38,30 @@ A `.pos` file stores a POS print template: metadata (page settings, title) plus
38
38
39| Field | Type | Default | Description |
39| Field | Type | Default | Description |
40|-------|------|---------|-------------|
40|-------|------|---------|-------------|
41| `title` | `string?` | `null` | Display name in app title / recent files |
41| `title` | `string?` | `null` | Display name in app title |
42| `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) |
42| `page_width_mm` | `number` | `80` | Physical paper width (mm) |
43| `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content |
43| `chars_per_line` | `number?` | derived | Override column count; derived from mm if omitted |
44| `chars_per_line` | `number?` | derived | Override character width for preview/print width model; derived from mm if omitted |
44| `codepage` | `string?` | `"CP437"` | Reserved; encoder uses CP437 today |
45| `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text |
46
45
47### Page width derivation
46### Printable width model
48
47
49| `page_width_mm` | Effective printable dots (Font A) | Default `chars_per_line` (Font A) |
48Effective print/preview width uses Font A columns:
50|-----------------|----------------------------------|-----------------------------------|
49
51| 53-58 | 384 | 32 |
50`printable_dots = chars_per_line() × 12`
52| >58 | 576 | 48 |
51
52| `page_width_mm` | Default `chars_per_line` | `printable_dots` |
53|-----------------|--------------------------|------------------|
54| ≤ 58 | 32 | 384 |
55| > 58 | 48 | 576 |
56
57### Legacy fields (ignored)
58
59Unknown JSON keys are ignored by serde. Notably:
60
61| Field | Former meaning | Current behaviour |
62|-------|----------------|-------------------|
63| `preview_mode` | autoscale / fixed preview | Ignored; UI uses zoom slider |
64| `cut_after_print` | auto-cut after job | Ignored; use `@cut` in the template |
53
65
54---
66---
55
67
@@ -65,19 +77,16 @@ A `.pos` file stores a POS print template: metadata (page settings, title) plus
65 "page_width_mm": 80,
77 "page_width_mm": 80,
66 "codepage": "CP437"
78 "codepage": "CP437"
67 },
79 },
68 "body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\n**TOTAL: ${GrandTotal}**\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"
80 "body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\nTOTAL: ${GrandTotal}\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"
69}
81}
70```
82```
71
83
72For readability, the app may save `body` with literal newlines (pretty-printed JSON) when the user chooses “formatted save”; both pretty and escaped forms are valid.
73
74---
84---
75
85
76## Asset resolution
86## Asset resolution
77
87
78- Paths in `@image` directives are resolved relative to the **directory containing the `.pos` file** unless absolute.
88- Paths in `@image` resolve relative to the **directory containing the `.pos` file** unless absolute.
79- Bundled assets: optional `assets/` subfolder next to the template.
89- Parameterized paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` directory.
80- Parameterized image paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` file directory.
81
90
82---
91---
83
92
@@ -87,42 +96,16 @@ For readability, the app may save `body` with literal newlines (pretty-printed J
87|------|-----|-----------|
96|------|-----|-----------|
88| — | 1 | Initial release |
97| — | 1 | Initial release |
89
98
90On load, if `version` is newer than app supports → error with upgrade message.
99On load, if `version` is newer than the app supports → error. Older versions would migrate (none yet).
91If older → run migration chain (none yet).
92
100
93---
101---
94
102
95## Validation rules
103## Validation
96
97On save:
98
104
99- `version` must equal supported version
105On save / load: JSON parse, `version == 1`, `page_width_mm > 0`, UTF-8 body. DSL parse errors show in the UI; the file can still load.
100- `page_width_mm` > 0
101- `body` must be valid UTF-8
102
103On load:
104
105- Parse JSON; validate schema
106- Parse `body` with DSL parser; warnings shown in UI but file still loads
107
106
108---
107---
109
108
110## TypeScript / Rust types (reference)
109## Rust types
111
112```typescript
113interface PosFile {
114 version: number;
115 metadata: PosMetadata;
116 body: string;
117}
118
119interface PosMetadata {
120 title?: string;
121 page_width_mm: number;
122 preview_mode: "autoscale" | "fixed";
123 chars_per_line?: number;
124 codepage?: string;
125}
126```
127
110
128Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer).
111Defined in `src/io/mod.rs` (`PosFile`, `PosMetadata`) with `serde` derive. Used directly by the egui app (no IPC).
docs/HELP-CLI-LINUX.md +1 −1
@@ -18,7 +18,7 @@ posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="My Shop" --set Docum
18 18
19 19 ## Rules
20 20
21 - **`--printer` / `-p`** (required): serial device path, e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`.
21 - **`--printer` / `-p`** (required): serial device path (e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`), or another printer id accepted by discovery.
22 22 - **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
23 23 - If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
24 24 - The GUI is not started when using the `print` subcommand.
@@ -18,7 +18,7 @@ posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="My Shop" --set Docum
18
18
19## Rules
19## Rules
20
20
21- **`--printer` / `-p`** (required): serial device path, e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`.
21- **`--printer` / `-p`** (required): serial device path (e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`), or another printer id accepted by discovery.
22- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
22- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
23- If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
23- If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
24- The GUI is not started when using the `print` subcommand.
24- The GUI is not started when using the `print` subcommand.
docs/HELP-CLI-WINDOWS.md +4 −4
@@ -18,7 +18,7 @@ posprint print receipt.pos -p COM3 --set StoreName="My Shop" --set DocumentNumbe
18 18
19 19 ## Rules
20 20
21 - **`--printer` / `-p`** (required): USB-serial port name, e.g. `COM3`, `COM4`.
21 - **`--printer` / `-p`** (required): serial port (`COM3`), or a Windows printer queue name for spooler printing.
22 22 - **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
23 23 - If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
24 24 - The GUI is not started when using the `print` subcommand.
@@ -35,10 +35,10 @@ posprint print C:\receipts\sale.pos -p COM3 `
35 35 --set GrandTotal=19.99
36 36 ```
37 37
38 ## Printer port
38 ## Printer target
39 39
40 - Open **Device Manager → Ports (COM & LPT)** to find the printer COM port.
41 - Install the USB-serial driver if the device is not listed.
40 - Serial: **Device Manager → Ports (COM & LPT)** for the COM port; install the USB-serial driver if needed.
41 - Spooler: use the Windows printer queue name as `-p` (same name as in Settings → Printers).
42 42 - Close other programs using the same COM port before printing.
43 43
44 44 ## Exit codes
@@ -18,7 +18,7 @@ posprint print receipt.pos -p COM3 --set StoreName="My Shop" --set DocumentNumbe
18
18
19## Rules
19## Rules
20
20
21- **`--printer` / `-p`** (required): USB-serial port name, e.g. `COM3`, `COM4`.
21- **`--printer` / `-p`** (required): serial port (`COM3`), or a Windows printer queue name for spooler printing.
22- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
22- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
23- If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
23- If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
24- The GUI is not started when using the `print` subcommand.
24- The GUI is not started when using the `print` subcommand.
@@ -35,10 +35,10 @@ posprint print C:\receipts\sale.pos -p COM3 `
35 --set GrandTotal=19.99
35 --set GrandTotal=19.99
36```
36```
37
37
38## Printer port
38## Printer target
39
39
40- Open **Device Manager → Ports (COM & LPT)** to find the printer COM port.
40- Serial: **Device Manager → Ports (COM & LPT)** for the COM port; install the USB-serial driver if needed.
41- Install the USB-serial driver if the device is not listed.
41- Spooler: use the Windows printer queue name as `-p` (same name as in Settings → Printers).
42- Close other programs using the same COM port before printing.
42- Close other programs using the same COM port before printing.
43
43
44## Exit codes
44## Exit codes
docs/HELP.md +55 −19
@@ -8,8 +8,7 @@ Built-in reference for the template editor and POS markup language.
8 8
9 9 | Tab | Purpose |
10 10 |-----|---------|
11 | **Editor** | Write and edit template source |
12 | **Preview** | Live preview of rendered output |
11 | **Design** | Side-by-side template editor and live preview |
13 12 | **Help** | This documentation |
14 13
15 14 ## Toolbar actions
@@ -19,22 +18,24 @@ Built-in reference for the template editor and POS markup language.
19 18 | **New** | Empty template with defaults |
20 19 | **Open** | Load a `.pos` file |
21 20 | **Save / Save As** | Write `.pos` file (metadata + body) |
22 | **Insert** | Menu to insert images, barcodes, QR codes, `@feed`, `@cut` |
23 | **Print** | Substitute parameters, pick USB printer, send ESC/POS bytes |
21 | **Insert** | Images, barcodes, QR, date/time, parameters, `@feed`, `@cut` |
22 | **Print** | Enter parameters, pick a printer, send ESC/POS bytes |
23
24 While the Print dialog is open, the rest of the UI (including editor autocomplete) is disabled so parameter fields keep focus.
24 25
25 26 ## Editor assistance
26 27
27 - Type `@` at the start of a line to see **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`).
28 - Type `@` at the start of a line for **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`, `date`, `time`).
28 29 - Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.
29 30
30 31 ## Page settings
31 32
32 33 | Setting | Description |
33 34 |---------|-------------|
34 | **Page width (mm)** | Paper width — set this to match your physical roll (e.g. `53`, `58`, `80`) |
35 | **Page width (mm)** | Paper width — match your physical roll (e.g. `53`, `58`, `80`) |
35 36 | **Preview zoom** | Screen zoom; `100%` is calibrated to typical receipt width on screen |
36 37
37 Preview width and text both use the same calibrated screen scale. Preview font size is bumped to match printed Font A (~same visual size as the receipt). Blank lines / `@feed` use the same line spacing as printed text. Heading `#` uses double width/height like GS `!` on the printer; `##` uses bold only.
38 Preview width and text use the same calibrated screen scale. Preview font size is bumped to match printed Font A. Blank lines / `@feed` use the same line spacing as printed text. Heading `#` uses double width/height like GS `!` on the printer; `##` uses bold only.
38 39
39 40 If the document does not end with `@cut` (ignoring blank lines after it), a red warning appears next to **Help**.
40 41
@@ -42,7 +43,7 @@ If the document does not end with `@cut` (ignoring blank lines after it), a red
42 43
43 44 ## Template language
44 45
45 A template is plain text: paragraphs, headings, directives, and inline markup.
46 A template is plain text: paragraphs, headings, lists, directives, and `${parameters}`. There is **no** inline bold/italic/code markup — asterisks and backticks print literally.
46 47
47 48 ### Paragraphs
48 49
@@ -66,7 +67,7 @@ Consecutive non-empty lines form one paragraph.
66 67 - second item
67 68 ```
68 69
69 Long items wrap with a hanging indent:
70 Long items wrap with a hanging indent (printed/previewed as ASCII `*`):
70 71
71 72 ```text
72 73 * this is a
@@ -104,6 +105,22 @@ Directives start with `@` at the beginning of a line.
104 105 @cut
105 106 ```
106 107
108 Blank lines in the editor also feed one line (same as `@feed 1`).
109
110 ### Date / time
111
112 ```markdown
113 @date
114 @date DD-MM-YYYY
115 @time
116 @time 12h
117 @time 24h
118 ```
119
120 - `@date` with no pattern uses the system regional short date.
121 - Custom patterns use tokens such as `YYYY`, `MM`, `DD`.
122 - `@time` defaults to 24-hour; use `12h` or `24h`.
123
107 124 ### Image
108 125
109 126 ```markdown
@@ -121,7 +138,7 @@ Directives start with `@` at the beginning of a line.
121 138 @barcode ITF 12345678 height=80
122 139 ```
123 140
124 **Raster** (rendered as bitmap — works with any symbology below). Raster barcodes are stretched horizontally to the full paper width for reliable scanning; height follows the `height` attribute.
141 **Raster** (bitmap). Raster barcodes stretch horizontally to full paper width; height follows `height`.
125 142
126 143 ```markdown
127 144 @barcode RASTER CODE128 ${OrderId}
@@ -137,13 +154,13 @@ Directives start with `@` at the beginning of a line.
137 154 | `ITF` | Interleaved 2 of 5; even digit count |
138 155 | `CODABAR` | Numeric + A-D start/stop |
139 156
140 | Raster-only symbology | Use `RASTER` prefix |
141 |-----------------------|---------------------|
157 | Raster-only | Use `RASTER` prefix |
158 |-------------|---------------------|
142 159 | `CODE93`, `CODE11` | No native ESC/POS in firmware |
143 160
144 161 | Attribute | Description |
145 162 |-----------|-------------|
146 | `height` | Height in dots (default `64`; raster PNG height) |
163 | `height` | Height in dots (default `64`) |
147 164 | `align` | `left`, `center`, `right` |
148 165 | `show_text` | Native only: human-readable text under barcode |
149 166
@@ -156,7 +173,7 @@ Directives start with `@` at the beginning of a line.
156 173 @qr ${Url} size=6 ecc=H align=center
157 174 ```
158 175
159 **Raster** (bitmap; supports QR versions 1–40):
176 **Raster** (bitmap; QR versions 1–40):
160 177
161 178 ```markdown
162 179 @qr RASTER https://example.com/${Id}
@@ -167,7 +184,7 @@ Directives start with `@` at the beginning of a line.
167 184 |-----------|--------|--------|
168 185 | `size` | Module dot size 1–16 | — |
169 186 | `scale` | — | Pixels per module (default `4`) |
170 | `version` | — | QR version 1–40 (optional; auto if omitted) |
187 | `version` | — | QR version 1–40 (optional) |
171 188 | `ecc` | `L`, `M`, `Q`, `H` | Same |
172 189 | `align` | `left`, `center`, `right` | Same |
173 190
@@ -189,6 +206,8 @@ Directives start with `@` at the beginning of a line.
189 206 :center:
190 207
191 208 Receipt: ${DocumentNumber}
209 @date
210 @time
192 211
193 212 @barcode CODE128 ${DocumentNumber}
194 213 @qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
@@ -199,14 +218,31 @@ Receipt: ${DocumentNumber}
199 218
200 219 ---
201 220
202 ## GUI printing (USB)
221 ## GUI printing
222
223 1. **Print** → enter parameters → choose a printer → **Print**.
203 224
204 1. **Print** → enter parameters → choose serial port → **Print**.
225 Printers may appear as:
226
227 - **USB printer-class** devices (direct bulk OUT)
228 - **Windows spooler** queues (Windows)
229 - **Serial / USB-serial** ports (`COMx`, `/dev/ttyUSB0`, …)
230
231 **Linux serial:** join the `dialout` group.
232
233 ---
234
235 ## CLI
236
237 ```bash
238 posprint print receipt.pos -p COM3 --set StoreName=Shop
239 posprint cli-help
240 ```
205 241
206 **Linux:** `dialout` group. **Windows:** printer appears as `COMx`.
242 `-p` accepts a serial port name, USB device label from discovery, or (on Windows) a spooler queue name. See platform CLI help via `posprint cli-help`.
207 243
208 244 ---
209 245
210 246 ## `.pos` file format
211 247
212 JSON with `version`, `metadata`, and `body` (template source).
248 JSON with `version`, `metadata`, and `body` (template source). See [FILE-FORMAT.md](FILE-FORMAT.md).
@@ -8,8 +8,7 @@ Built-in reference for the template editor and POS markup language.
8
8
9| Tab | Purpose |
9| Tab | Purpose |
10|-----|---------|
10|-----|---------|
11| **Editor** | Write and edit template source |
11| **Design** | Side-by-side template editor and live preview |
12| **Preview** | Live preview of rendered output |
13| **Help** | This documentation |
12| **Help** | This documentation |
14
13
15## Toolbar actions
14## Toolbar actions
@@ -19,22 +18,24 @@ Built-in reference for the template editor and POS markup language.
19| **New** | Empty template with defaults |
18| **New** | Empty template with defaults |
20| **Open** | Load a `.pos` file |
19| **Open** | Load a `.pos` file |
21| **Save / Save As** | Write `.pos` file (metadata + body) |
20| **Save / Save As** | Write `.pos` file (metadata + body) |
22| **Insert** | Menu to insert images, barcodes, QR codes, `@feed`, `@cut` |
21| **Insert** | Images, barcodes, QR, date/time, parameters, `@feed`, `@cut` |
23| **Print** | Substitute parameters, pick USB printer, send ESC/POS bytes |
22| **Print** | Enter parameters, pick a printer, send ESC/POS bytes |
23
24While the Print dialog is open, the rest of the UI (including editor autocomplete) is disabled so parameter fields keep focus.
24
25
25## Editor assistance
26## Editor assistance
26
27
27- Type `@` at the start of a line to see **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`).
28- Type `@` at the start of a line for **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`, `date`, `time`).
28- Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.
29- Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.
29
30
30## Page settings
31## Page settings
31
32
32| Setting | Description |
33| Setting | Description |
33|---------|-------------|
34|---------|-------------|
34| **Page width (mm)** | Paper width — set this to match your physical roll (e.g. `53`, `58`, `80`) |
35| **Page width (mm)** | Paper width — match your physical roll (e.g. `53`, `58`, `80`) |
35| **Preview zoom** | Screen zoom; `100%` is calibrated to typical receipt width on screen |
36| **Preview zoom** | Screen zoom; `100%` is calibrated to typical receipt width on screen |
36
37
37Preview width and text both use the same calibrated screen scale. Preview font size is bumped to match printed Font A (~same visual size as the receipt). Blank lines / `@feed` use the same line spacing as printed text. Heading `#` uses double width/height like GS `!` on the printer; `##` uses bold only.
38Preview width and text use the same calibrated screen scale. Preview font size is bumped to match printed Font A. Blank lines / `@feed` use the same line spacing as printed text. Heading `#` uses double width/height like GS `!` on the printer; `##` uses bold only.
38
39
39If the document does not end with `@cut` (ignoring blank lines after it), a red warning appears next to **Help**.
40If the document does not end with `@cut` (ignoring blank lines after it), a red warning appears next to **Help**.
40
41
@@ -42,7 +43,7 @@ If the document does not end with `@cut` (ignoring blank lines after it), a red
42
43
43## Template language
44## Template language
44
45
45A template is plain text: paragraphs, headings, directives, and inline markup.
46A template is plain text: paragraphs, headings, lists, directives, and `${parameters}`. There is **no** inline bold/italic/code markup — asterisks and backticks print literally.
46
47
47### Paragraphs
48### Paragraphs
48
49
@@ -66,7 +67,7 @@ Consecutive non-empty lines form one paragraph.
66- second item
67- second item
67```
68```
68
69
69Long items wrap with a hanging indent:
70Long items wrap with a hanging indent (printed/previewed as ASCII `*`):
70
71
71```text
72```text
72* this is a
73* this is a
@@ -104,6 +105,22 @@ Directives start with `@` at the beginning of a line.
104@cut
105@cut
105```
106```
106
107
108Blank lines in the editor also feed one line (same as `@feed 1`).
109
110### Date / time
111
112```markdown
113@date
114@date DD-MM-YYYY
115@time
116@time 12h
117@time 24h
118```
119
120- `@date` with no pattern uses the system regional short date.
121- Custom patterns use tokens such as `YYYY`, `MM`, `DD`.
122- `@time` defaults to 24-hour; use `12h` or `24h`.
123
107### Image
124### Image
108
125
109```markdown
126```markdown
@@ -121,7 +138,7 @@ Directives start with `@` at the beginning of a line.
121@barcode ITF 12345678 height=80
138@barcode ITF 12345678 height=80
122```
139```
123
140
124**Raster** (rendered as bitmap — works with any symbology below). Raster barcodes are stretched horizontally to the full paper width for reliable scanning; height follows the `height` attribute.
141**Raster** (bitmap). Raster barcodes stretch horizontally to full paper width; height follows `height`.
125
142
126```markdown
143```markdown
127@barcode RASTER CODE128 ${OrderId}
144@barcode RASTER CODE128 ${OrderId}
@@ -137,13 +154,13 @@ Directives start with `@` at the beginning of a line.
137| `ITF` | Interleaved 2 of 5; even digit count |
154| `ITF` | Interleaved 2 of 5; even digit count |
138| `CODABAR` | Numeric + A-D start/stop |
155| `CODABAR` | Numeric + A-D start/stop |
139
156
140| Raster-only symbology | Use `RASTER` prefix |
157| Raster-only | Use `RASTER` prefix |
141|-----------------------|---------------------|
158|-------------|---------------------|
142| `CODE93`, `CODE11` | No native ESC/POS in firmware |
159| `CODE93`, `CODE11` | No native ESC/POS in firmware |
143
160
144| Attribute | Description |
161| Attribute | Description |
145|-----------|-------------|
162|-----------|-------------|
146| `height` | Height in dots (default `64`; raster PNG height) |
163| `height` | Height in dots (default `64`) |
147| `align` | `left`, `center`, `right` |
164| `align` | `left`, `center`, `right` |
148| `show_text` | Native only: human-readable text under barcode |
165| `show_text` | Native only: human-readable text under barcode |
149
166
@@ -156,7 +173,7 @@ Directives start with `@` at the beginning of a line.
156@qr ${Url} size=6 ecc=H align=center
173@qr ${Url} size=6 ecc=H align=center
157```
174```
158
175
159**Raster** (bitmap; supports QR versions 1–40):
176**Raster** (bitmap; QR versions 1–40):
160
177
161```markdown
178```markdown
162@qr RASTER https://example.com/${Id}
179@qr RASTER https://example.com/${Id}
@@ -167,7 +184,7 @@ Directives start with `@` at the beginning of a line.
167|-----------|--------|--------|
184|-----------|--------|--------|
168| `size` | Module dot size 1–16 | — |
185| `size` | Module dot size 1–16 | — |
169| `scale` | — | Pixels per module (default `4`) |
186| `scale` | — | Pixels per module (default `4`) |
170| `version` | — | QR version 1–40 (optional; auto if omitted) |
187| `version` | — | QR version 1–40 (optional) |
171| `ecc` | `L`, `M`, `Q`, `H` | Same |
188| `ecc` | `L`, `M`, `Q`, `H` | Same |
172| `align` | `left`, `center`, `right` | Same |
189| `align` | `left`, `center`, `right` | Same |
173
190
@@ -189,6 +206,8 @@ Directives start with `@` at the beginning of a line.
189:center:
206:center:
190
207
191Receipt: ${DocumentNumber}
208Receipt: ${DocumentNumber}
209@date
210@time
192
211
193@barcode CODE128 ${DocumentNumber}
212@barcode CODE128 ${DocumentNumber}
194@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
213@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
@@ -199,14 +218,31 @@ Receipt: ${DocumentNumber}
199
218
200---
219---
201
220
202## GUI printing (USB)
221## GUI printing
222
2231. **Print** → enter parameters → choose a printer → **Print**.
203
224
2041. **Print** → enter parameters → choose serial port → **Print**.
225Printers may appear as:
226
227- **USB printer-class** devices (direct bulk OUT)
228- **Windows spooler** queues (Windows)
229- **Serial / USB-serial** ports (`COMx`, `/dev/ttyUSB0`, …)
230
231**Linux serial:** join the `dialout` group.
232
233---
234
235## CLI
236
237```bash
238posprint print receipt.pos -p COM3 --set StoreName=Shop
239posprint cli-help
240```
205
241
206**Linux:** `dialout` group. **Windows:** printer appears as `COMx`.
242`-p` accepts a serial port name, USB device label from discovery, or (on Windows) a spooler queue name. See platform CLI help via `posprint cli-help`.
207
243
208---
244---
209
245
210## `.pos` file format
246## `.pos` file format
211
247
212JSON with `version`, `metadata`, and `body` (template source).
248JSON with `version`, `metadata`, and `body` (template source). See [FILE-FORMAT.md](FILE-FORMAT.md).
docs/LANGUAGE-CHOICE.md deleted +0 −83
@@ -1,83 +0,0 @@
1 # Language and platform choice
2
3 ## Decision (implemented)
4
5 | Decision | Choice |
6 |----------|--------|
7 | Language | **Rust** (single codebase) |
8 | UI | **egui** via **eframe** |
9 | Print protocol | **ESC/POS** (in-tree encoder) |
10 | MVP transport | **USB-serial** via `serialport` |
11 | Packaging | GitLab CI → Linux `.deb`, Windows `.exe` |
12
13 **Rationale:** One language, small dependency surface, direct control over ESC/POS bytes, native cross-platform UI without a WebView.
14
15 ---
16
17 ## Requirements
18
19 | Requirement | How it is met |
20 |-------------|---------------|
21 | Windows + Linux | Rust + egui + GitLab CI |
22 | Raw USB-serial print (no spooler) | `serialport` crate, 9600 baud |
23 | ESC/POS generation | `src/escpos.rs` (no external ESC/POS crate) |
24 | Live preview | `src/preview.rs` + egui canvas in `app.rs` |
25 | Small distributable | No Chromium/Node; release build uses LTO + strip |
26 | Unit tests | Every module has `#[cfg(test)]` tests |
27
28 ---
29
30 ## Dependencies in use
31
32 | Crate | Role | Why not hand-roll? |
33 |-------|------|-------------------|
34 | `eframe` / `egui` | UI framework | Building a GUI toolkit is out of scope |
35 | `serde` / `serde_json` | `.pos` files | Error-prone to parse/emit JSON manually |
36 | `serialport` | Cross-platform COM/tty access | OS-specific serial APIs differ |
37 | `image` | PNG/JPEG/GIF/BMP decode | Many formats and decoders |
38 | `rfd` | Native file dialogs | OS-native UX expected |
39
40 **Not used (by design):** `escpos`, `nusb`, `rusb`, `tauri`, TypeScript frontend.
41
42 ---
43
44 ## Candidates considered (historical)
45
46 | Option | Verdict |
47 |--------|---------|
48 | Rust + Tauri 2 + TypeScript | Rejected — two languages, WebView dependency |
49 | Rust + egui | **Selected** |
50 | C# + Avalonia | Viable but weaker serial/ESC/POS ecosystem |
51 | Go + Fyne | Weaker hardware I/O ecosystem |
52 | Python + PyQt | Poor packaging for desktop release |
53 | Electron | Bundle size too large |
54 | C++ + Qt | Slower iteration for a small app |
55
56 ---
57
58 ## Platform notes
59
60 ### Windows
61
62 - Printers appear as `COMx` after USB-serial driver install.
63 - Release: `posprint.exe` from `cargo build --release`.
64 - CI requires a GitLab runner tagged `windows` + `shell`.
65
66 ### Linux
67
68 - Devices: `/dev/ttyUSB*`, `/dev/ttyACM*`, etc.
69 - User must be in the **`dialout`** group.
70 - Release: `.deb` via `cargo deb`; install with `sudo dpkg -i …`.
71 - CI uses `rust:bookworm` image with X11 dev libs for egui.
72
73 ---
74
75 ## Deferred
76
77 | Item | Notes |
78 |------|-------|
79 | USB printer class (bulk) | Would need `nusb` or Windows `usbprint` path |
80 | Bluetooth SPP | Paired devices as serial ports; add when requested |
81 | macOS | Same stack should work; not in CI yet |
82
83 This document should be updated when transport or UI choices change.
@@ -1,83 +0,0 @@
1# Language and platform choice
2
3## Decision (implemented)
4
5| Decision | Choice |
6|----------|--------|
7| Language | **Rust** (single codebase) |
8| UI | **egui** via **eframe** |
9| Print protocol | **ESC/POS** (in-tree encoder) |
10| MVP transport | **USB-serial** via `serialport` |
11| Packaging | GitLab CI → Linux `.deb`, Windows `.exe` |
12
13**Rationale:** One language, small dependency surface, direct control over ESC/POS bytes, native cross-platform UI without a WebView.
14
15---
16
17## Requirements
18
19| Requirement | How it is met |
20|-------------|---------------|
21| Windows + Linux | Rust + egui + GitLab CI |
22| Raw USB-serial print (no spooler) | `serialport` crate, 9600 baud |
23| ESC/POS generation | `src/escpos.rs` (no external ESC/POS crate) |
24| Live preview | `src/preview.rs` + egui canvas in `app.rs` |
25| Small distributable | No Chromium/Node; release build uses LTO + strip |
26| Unit tests | Every module has `#[cfg(test)]` tests |
27
28---
29
30## Dependencies in use
31
32| Crate | Role | Why not hand-roll? |
33|-------|------|-------------------|
34| `eframe` / `egui` | UI framework | Building a GUI toolkit is out of scope |
35| `serde` / `serde_json` | `.pos` files | Error-prone to parse/emit JSON manually |
36| `serialport` | Cross-platform COM/tty access | OS-specific serial APIs differ |
37| `image` | PNG/JPEG/GIF/BMP decode | Many formats and decoders |
38| `rfd` | Native file dialogs | OS-native UX expected |
39
40**Not used (by design):** `escpos`, `nusb`, `rusb`, `tauri`, TypeScript frontend.
41
42---
43
44## Candidates considered (historical)
45
46| Option | Verdict |
47|--------|---------|
48| Rust + Tauri 2 + TypeScript | Rejected — two languages, WebView dependency |
49| Rust + egui | **Selected** |
50| C# + Avalonia | Viable but weaker serial/ESC/POS ecosystem |
51| Go + Fyne | Weaker hardware I/O ecosystem |
52| Python + PyQt | Poor packaging for desktop release |
53| Electron | Bundle size too large |
54| C++ + Qt | Slower iteration for a small app |
55
56---
57
58## Platform notes
59
60### Windows
61
62- Printers appear as `COMx` after USB-serial driver install.
63- Release: `posprint.exe` from `cargo build --release`.
64- CI requires a GitLab runner tagged `windows` + `shell`.
65
66### Linux
67
68- Devices: `/dev/ttyUSB*`, `/dev/ttyACM*`, etc.
69- User must be in the **`dialout`** group.
70- Release: `.deb` via `cargo deb`; install with `sudo dpkg -i …`.
71- CI uses `rust:bookworm` image with X11 dev libs for egui.
72
73---
74
75## Deferred
76
77| Item | Notes |
78|------|-------|
79| USB printer class (bulk) | Would need `nusb` or Windows `usbprint` path |
80| Bluetooth SPP | Paired devices as serial ports; add when requested |
81| macOS | Same stack should work; not in CI yet |
82
83This document should be updated when transport or UI choices change.
docs/PRINTING.md +59 −74
@@ -1,17 +1,15 @@
1 1 # Printing subsystem
2 2
3 Direct raw-byte printing to POS thermal printers over **USB-serial** — without the Windows print spooler or CUPS.
4
5 > **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.
3 Raw ESC/POS output to POS thermal printers via **USB printer-class**, **Windows spooler** (Windows), or **USB-serial**.
6 4
7 5 ---
8 6
9 7 ## Goals
10 8
11 1. Discover serial ports (USB-serial adapters and CDC printers)
12 2. Let the user pick a port in the print dialog
9 1. Discover printers (USB-direct, Windows spooler, serial ports)
10 2. Let the user pick a target in the print dialog
13 11 3. Generate ESC/POS bytes from the AST (after parameter substitution)
14 4. Write bytes at **9600 baud** (fixed for now)
12 4. Write bytes to the chosen transport (serial baud is probed)
15 13
16 14 ---
17 15
@@ -28,12 +26,13 @@ Target **Epson ESC/POS** compatible printers (58 mm / 80 mm thermal).
28 26 | Bold | ESC E | Headings level 2 only |
29 27 | Double size | GS ! | Heading level 1 |
30 28 | Alignment | ESC a | Paragraphs, images, barcodes, QR |
31 | Line feed | LF (text lines), ESC d (`@feed` / blank lines) | Text lines end with LF; explicit feeds use ESC d |
29 | Line feed | LF (text lines), ESC d (`@feed` / blank lines) | Text ends with LF; blank/`@feed` use ESC d |
30 | Raster flush | LF after GS v 0 | Ensures spacing after images/barcodes/QR rasters |
32 31 | List bullet | ASCII `*` | `- item` lines in templates |
33 | Partial cut | GS V 66 0 | `@cut` in template |
34 | Barcode | GS k | CODE128, EAN13, EAN8, CODE39 |
35 | QR Code | GS ( k | Model 2 |
36 | Raster image | GS v 0 | `@image` via `image` crate → threshold |
32 | Partial cut | GS V 66 0 | `@cut` in template only |
33 | Barcode | GS k | Native symbologies; raster via GS v 0 |
34 | QR Code | GS ( k | Model 2; or raster GS v 0 |
35 | Raster image | GS v 0 | `@image` / raster barcode / raster QR |
37 36
38 37 Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.
39 38
@@ -51,7 +50,7 @@ substitute_document()
51 50 EscPosEncoder::encode_document()
52 51 │
53 52 ▼
54 SerialTransport::open(port, 9600)
53 open_printer(target) # USB-direct | Win spooler | serial
55 54 │
56 55 ▼
57 56 print_bytes() → write_all + flush
@@ -68,44 +67,42 @@ pub trait PrinterTransport {
68 67
69 68 | Type | Role |
70 69 |------|------|
71 | `SerialTransport` | Production — opens port via `serialport` |
70 | USB-direct (`rusb`) | USB printer-class bulk OUT (`usb_direct.rs`) |
71 | Windows spooler | Raw jobs via Win32 spooler (`win_spool.rs`, Windows only) |
72 | `SerialTransport` | USB-serial / CDC ports via `serialport` |
72 73 | `MockTransport` | Tests — records bytes in `written` vec |
73 74
74 75 ### Discovery
75 76
76 `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).
77 `list_printers()` returns, in order:
78
79 1. USB printer-class devices (`usb_direct`)
80 2. Windows spooler queues (Windows)
81 3. Serial ports (`serialport::available_ports()`, with VID/PID labels when available)
82
83 ### Serial baud rates
84
85 `SerialTransport::open` tries, in order:
86
87 `115200`, `9600`, `19200`, `38400`, `57600`, `4800`
77 88
78 89 ### `PrinterDevice`
79 90
80 91 | Field | Example |
81 92 |-------|---------|
82 | `id` | `serial:COM3` |
83 | `display_name` | `COM3 — USB 04b8:0e15` |
84 | `port_name` | `COM3` |
93 | `id` | `serial:COM3`, `usb:04b8:0e15:…`, `spool:POS-58` |
94 | `display_name` | Human-readable label |
95 | `target` | `Serial` / `UsbDirect` / `WinSpooler` |
85 96
86 97 ---
87 98
88 99 ## Print dialog (UI)
89 100
90 ```
91 ┌─────────────────────────────────────────┐
92 │ Print │
93 ├─────────────────────────────────────────┤
94 │ Parameters (one field per unique name) │
95 │ DocumentNumber: [________] │
96 │ │
97 │ USB printer │
98 │ [ Refresh ] │
99 │ ○ COM3 — USB 04b8:0e15 │
100 │ ○ /dev/ttyUSB0 — Serial │
101 │ │
102 │ [ Cancel ] [ Print ] │
103 └─────────────────────────────────────────┘
104 ```
105
106 - Parameters pre-filled from `last_params` (session memory).
107 - Same parameter name → one input, applied everywhere.
108 - Errors shown inline (parse, open port, write, barcode validation).
101 - One field per unique `${Parameter}`.
102 - Printer list: USB, spooler, and serial (Refresh button).
103 - Optional manual serial port name.
104 - While open, the main Design UI is disabled (including editor autocomplete).
105 - Errors shown inline (parse, open, write, barcode validation).
109 106
110 107 ---
111 108
@@ -118,7 +115,7 @@ Document body (DSL)
118 115 parse() → Document
119 116 │
120 117 ▼
121 collect_parameter_names() → UI dialog
118 collect_parameter_names() → UI dialog / CLI --set
122 119 │
123 120 ▼
124 121 substitute_document()
@@ -127,41 +124,31 @@ Document body (DSL)
127 124 EscPosEncoder (in-tree)
128 125 │
129 126 ▼
130 SerialTransport::write_all
127 open_printer → write_all
131 128 ```
132 129
133 ### Error handling (current)
130 ### Error handling
134 131
135 132 | Condition | Behaviour |
136 133 |-----------|-----------|
137 134 | Parse error | Block print; show in toolbar |
138 | Port open failure | `PrintError::Open` message in dialog |
139 | Write failure | `PrintError::Write` message in dialog |
140 | EAN13/EAN8 invalid length | `EscPosError::Barcode` before write |
141 | Linux permission denied | User must join `dialout` group (documented in Help) |
135 | Open failure | Message in dialog / CLI |
136 | Write failure | Message in dialog / CLI |
137 | Invalid barcode data | Error before write |
138 | Linux serial permission | Join `dialout` group |
142 139
143 140 Status polling (paper out, cover open) is **not** implemented.
144 141
145 142 ---
146 143
147 ## Images
144 ## Images and rasters
148 145
149 1. Resolve path relative to `.pos` file directory (or absolute path).
150 2. Decode with `image` crate.
151 3. Convert to luma8, resize to target width (%, dots, or full printable width), and never exceed the effective page width.
152 4. Threshold to 1-bit raster.
153 5. Emit `GS v 0` raster (`1D 76 30 00`, width/height LE, bitmap) — same format as print-bridge.
146 1. Resolve path relative to the `.pos` file (or absolute).
147 2. Decode with `image`, convert to luma, scale to printable width (`chars_per_line × 12` dots).
148 3. Threshold to 1-bit; emit `GS v 0` (`1D 76 30 00` + width/height LE + bitmap).
149 4. Append **LF** after the raster so following content (including blank-line feeds) advances correctly.
154 150
155 Preview shows `[image: path]` only — no bitmap preview yet.
156
157 ---
158
159 ## Preview vs print width
160
161 | `preview_mode` | Preview | Print |
162 |----------------|---------|-------|
163 | `autoscale` | Scales to panel width | Full effective print width |
164 | `fixed` | Scaled by dot ratio | Full effective print width |
151 Preview draws the same bitmaps on the canvas (scaled for screen).
165 152
166 153 ---
167 154
@@ -171,20 +158,7 @@ Preview shows `[image: path]` only — no bitmap preview yet.
171 158 |--------|----------|
172 159 | `MockTransport` | `print/mod.rs` tests |
173 160 | ESC/POS byte checks | `escpos.rs` tests |
174 | `cargo test` | 20 tests; no printer required |
175
176 ---
177
178 ## Planned (not implemented)
179
180 | Feature | Notes |
181 |---------|-------|
182 | USB printer class | `nusb` / Windows `usbprint` |
183 | Bluetooth SPP | Serial port after OS pairing |
184 | Baud autodetect | Try 9600, 19200, 115200 |
185 | Printer status read | DLE EOT |
186 | Network TCP 9100 | Future |
187 | Image size warning in UI | Future |
161 | `cargo test` | ~100 unit tests; no printer required |
188 162
189 163 ---
190 164
@@ -192,7 +166,18 @@ Preview shows `[image: path]` only — no bitmap preview yet.
192 166
193 167 ```toml
194 168 serialport = "4"
169 rusb = "0.9"
195 170 image = { features = ["png", "jpeg", "gif", "bmp"] }
196 171 ```
197 172
198 No `escpos`, `nusb`, or `rusb` crates.
173 On Windows, spooler access uses Win32 APIs (`winreg` / system libs as needed). No `escpos` or `nusb` crates.
174
175 ---
176
177 ## Planned (not implemented)
178
179 | Feature | Notes |
180 |---------|-------|
181 | Bluetooth SPP | After OS pairing |
182 | Network TCP 9100 | Future |
183 | Printer status read | DLE EOT |
@@ -1,17 +1,15 @@
1# Printing subsystem
1# Printing subsystem
2
2
3Direct raw-byte printing to POS thermal printers over **USB-serial** — without the Windows print spooler or CUPS.
3Raw ESC/POS output to POS thermal printers via **USB printer-class**, **Windows spooler** (Windows), or **USB-serial**.
4
5> **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.
6
4
7---
5---
8
6
9## Goals
7## Goals
10
8
111. Discover serial ports (USB-serial adapters and CDC printers)
91. Discover printers (USB-direct, Windows spooler, serial ports)
122. Let the user pick a port in the print dialog
102. Let the user pick a target in the print dialog
133. Generate ESC/POS bytes from the AST (after parameter substitution)
113. Generate ESC/POS bytes from the AST (after parameter substitution)
144. Write bytes at **9600 baud** (fixed for now)
124. Write bytes to the chosen transport (serial baud is probed)
15
13
16---
14---
17
15
@@ -28,12 +26,13 @@ Target **Epson ESC/POS** compatible printers (58 mm / 80 mm thermal).
28| Bold | ESC E | Headings level 2 only |
26| Bold | ESC E | Headings level 2 only |
29| Double size | GS ! | Heading level 1 |
27| Double size | GS ! | Heading level 1 |
30| Alignment | ESC a | Paragraphs, images, barcodes, QR |
28| Alignment | ESC a | Paragraphs, images, barcodes, QR |
31| Line feed | LF (text lines), ESC d (`@feed` / blank lines) | Text lines end with LF; explicit feeds use ESC d |
29| Line feed | LF (text lines), ESC d (`@feed` / blank lines) | Text ends with LF; blank/`@feed` use ESC d |
30| Raster flush | LF after GS v 0 | Ensures spacing after images/barcodes/QR rasters |
32| List bullet | ASCII `*` | `- item` lines in templates |
31| List bullet | ASCII `*` | `- item` lines in templates |
33| Partial cut | GS V 66 0 | `@cut` in template |
32| Partial cut | GS V 66 0 | `@cut` in template only |
34| Barcode | GS k | CODE128, EAN13, EAN8, CODE39 |
33| Barcode | GS k | Native symbologies; raster via GS v 0 |
35| QR Code | GS ( k | Model 2 |
34| QR Code | GS ( k | Model 2; or raster GS v 0 |
36| Raster image | GS v 0 | `@image` via `image` crate → threshold |
35| Raster image | GS v 0 | `@image` / raster barcode / raster QR |
37
36
38Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.
37Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.
39
38
@@ -51,7 +50,7 @@ substitute_document()
51EscPosEncoder::encode_document()
50EscPosEncoder::encode_document()
52 │
51 │
53 ▼
52 ▼
54SerialTransport::open(port, 9600)
53open_printer(target) # USB-direct | Win spooler | serial
55 │
54 │
56 ▼
55 ▼
57print_bytes() → write_all + flush
56print_bytes() → write_all + flush
@@ -68,44 +67,42 @@ pub trait PrinterTransport {
68
67
69| Type | Role |
68| Type | Role |
70|------|------|
69|------|------|
71| `SerialTransport` | Production — opens port via `serialport` |
70| USB-direct (`rusb`) | USB printer-class bulk OUT (`usb_direct.rs`) |
71| Windows spooler | Raw jobs via Win32 spooler (`win_spool.rs`, Windows only) |
72| `SerialTransport` | USB-serial / CDC ports via `serialport` |
72| `MockTransport` | Tests — records bytes in `written` vec |
73| `MockTransport` | Tests — records bytes in `written` vec |
73
74
74### Discovery
75### Discovery
75
76
76`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).
77`list_printers()` returns, in order:
78
791. USB printer-class devices (`usb_direct`)
802. Windows spooler queues (Windows)
813. Serial ports (`serialport::available_ports()`, with VID/PID labels when available)
82
83### Serial baud rates
84
85`SerialTransport::open` tries, in order:
86
87`115200`, `9600`, `19200`, `38400`, `57600`, `4800`
77
88
78### `PrinterDevice`
89### `PrinterDevice`
79
90
80| Field | Example |
91| Field | Example |
81|-------|---------|
92|-------|---------|
82| `id` | `serial:COM3` |
93| `id` | `serial:COM3`, `usb:04b8:0e15:…`, `spool:POS-58` |
83| `display_name` | `COM3 — USB 04b8:0e15` |
94| `display_name` | Human-readable label |
84| `port_name` | `COM3` |
95| `target` | `Serial` / `UsbDirect` / `WinSpooler` |
85
96
86---
97---
87
98
88## Print dialog (UI)
99## Print dialog (UI)
89
100
90```
101- One field per unique `${Parameter}`.
91┌─────────────────────────────────────────┐
102- Printer list: USB, spooler, and serial (Refresh button).
92│ Print │
103- Optional manual serial port name.
93├─────────────────────────────────────────┤
104- While open, the main Design UI is disabled (including editor autocomplete).
94│ Parameters (one field per unique name) │
105- Errors shown inline (parse, open, write, barcode validation).
95│ DocumentNumber: [________] │
96│ │
97│ USB printer │
98│ [ Refresh ] │
99│ ○ COM3 — USB 04b8:0e15 │
100│ ○ /dev/ttyUSB0 — Serial │
101│ │
102│ [ Cancel ] [ Print ] │
103└─────────────────────────────────────────┘
104```
105
106- Parameters pre-filled from `last_params` (session memory).
107- Same parameter name → one input, applied everywhere.
108- Errors shown inline (parse, open port, write, barcode validation).
109
106
110---
107---
111
108
@@ -118,7 +115,7 @@ Document body (DSL)
118 parse() → Document
115 parse() → Document
119 │
116 │
120 ▼
117 ▼
121 collect_parameter_names() → UI dialog
118 collect_parameter_names() → UI dialog / CLI --set
122 │
119 │
123 ▼
120 ▼
124 substitute_document()
121 substitute_document()
@@ -127,41 +124,31 @@ Document body (DSL)
127 EscPosEncoder (in-tree)
124 EscPosEncoder (in-tree)
128 │
125 │
129 ▼
126 ▼
130 SerialTransport::write_all
127 open_printer → write_all
131```
128```
132
129
133### Error handling (current)
130### Error handling
134
131
135| Condition | Behaviour |
132| Condition | Behaviour |
136|-----------|-----------|
133|-----------|-----------|
137| Parse error | Block print; show in toolbar |
134| Parse error | Block print; show in toolbar |
138| Port open failure | `PrintError::Open` message in dialog |
135| Open failure | Message in dialog / CLI |
139| Write failure | `PrintError::Write` message in dialog |
136| Write failure | Message in dialog / CLI |
140| EAN13/EAN8 invalid length | `EscPosError::Barcode` before write |
137| Invalid barcode data | Error before write |
141| Linux permission denied | User must join `dialout` group (documented in Help) |
138| Linux serial permission | Join `dialout` group |
142
139
143Status polling (paper out, cover open) is **not** implemented.
140Status polling (paper out, cover open) is **not** implemented.
144
141
145---
142---
146
143
147## Images
144## Images and rasters
148
145
1491. Resolve path relative to `.pos` file directory (or absolute path).
1461. Resolve path relative to the `.pos` file (or absolute).
1502. Decode with `image` crate.
1472. Decode with `image`, convert to luma, scale to printable width (`chars_per_line × 12` dots).
1513. Convert to luma8, resize to target width (%, dots, or full printable width), and never exceed the effective page width.
1483. Threshold to 1-bit; emit `GS v 0` (`1D 76 30 00` + width/height LE + bitmap).
1524. Threshold to 1-bit raster.
1494. Append **LF** after the raster so following content (including blank-line feeds) advances correctly.
1535. Emit `GS v 0` raster (`1D 76 30 00`, width/height LE, bitmap) — same format as print-bridge.
154
150
155Preview shows `[image: path]` only — no bitmap preview yet.
151Preview draws the same bitmaps on the canvas (scaled for screen).
156
157---
158
159## Preview vs print width
160
161| `preview_mode` | Preview | Print |
162|----------------|---------|-------|
163| `autoscale` | Scales to panel width | Full effective print width |
164| `fixed` | Scaled by dot ratio | Full effective print width |
165
152
166---
153---
167
154
@@ -171,20 +158,7 @@ Preview shows `[image: path]` only — no bitmap preview yet.
171|--------|----------|
158|--------|----------|
172| `MockTransport` | `print/mod.rs` tests |
159| `MockTransport` | `print/mod.rs` tests |
173| ESC/POS byte checks | `escpos.rs` tests |
160| ESC/POS byte checks | `escpos.rs` tests |
174| `cargo test` | 20 tests; no printer required |
161| `cargo test` | ~100 unit tests; no printer required |
175
176---
177
178## Planned (not implemented)
179
180| Feature | Notes |
181|---------|-------|
182| USB printer class | `nusb` / Windows `usbprint` |
183| Bluetooth SPP | Serial port after OS pairing |
184| Baud autodetect | Try 9600, 19200, 115200 |
185| Printer status read | DLE EOT |
186| Network TCP 9100 | Future |
187| Image size warning in UI | Future |
188
162
189---
163---
190
164
@@ -192,7 +166,18 @@ Preview shows `[image: path]` only — no bitmap preview yet.
192
166
193```toml
167```toml
194serialport = "4"
168serialport = "4"
169rusb = "0.9"
195image = { features = ["png", "jpeg", "gif", "bmp"] }
170image = { features = ["png", "jpeg", "gif", "bmp"] }
196```
171```
197
172
198No `escpos`, `nusb`, or `rusb` crates.
173On Windows, spooler access uses Win32 APIs (`winreg` / system libs as needed). No `escpos` or `nusb` crates.
174
175---
176
177## Planned (not implemented)
178
179| Feature | Notes |
180|---------|-------|
181| Bluetooth SPP | After OS pairing |
182| Network TCP 9100 | Future |
183| Printer status read | DLE EOT |