# `.pos` file format A `.pos` file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text. **Format:** JSON envelope with a `.pos` extension (human-readable, git-friendly). **MIME type (suggested):** `application/vnd.posprint+json` --- ## Top-level schema ```json { "version": 1, "metadata": { ... }, "body": "..." } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `version` | `number` | yes | File format version (currently `1`) | | `metadata` | `object` | yes | Document settings | | `body` | `string` | yes | DSL source (UTF-8, `\n` line endings normalized on load) | --- ## Metadata schema (version 1) ```json { "title": "Sales Receipt", "page_width_mm": 80, "chars_per_line": 48, "codepage": "CP437" } ``` | Field | Type | Default | Description | |-------|------|---------|-------------| | `title` | `string?` | `null` | Display name in app title / recent files | | `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) | | `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content | | `chars_per_line` | `number?` | derived | Override character width for preview/print width model; derived from mm if omitted | | `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text | ### Page width derivation | `page_width_mm` | Effective printable dots (Font A) | Default `chars_per_line` (Font A) | |-----------------|----------------------------------|-----------------------------------| | 53-58 | 384 | 32 | | >58 | 576 | 48 | --- ## Example file **`receipt.pos`:** ```json { "version": 1, "metadata": { "title": "Standard Receipt", "page_width_mm": 80, "codepage": "CP437" }, "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" } ``` 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. --- ## Asset resolution - Paths in `@image` directives are resolved relative to the **directory containing the `.pos` file** unless absolute. - Bundled assets: optional `assets/` subfolder next to the template. - Parameterized image paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` file directory. --- ## Version migration | From | To | Migration | |------|-----|-----------| | — | 1 | Initial release | On load, if `version` is newer than app supports → error with upgrade message. If older → run migration chain (none yet). --- ## Validation rules On save: - `version` must equal supported version - `page_width_mm` > 0 - `body` must be valid UTF-8 On load: - Parse JSON; validate schema - Parse `body` with DSL parser; warnings shown in UI but file still loads --- ## TypeScript / Rust types (reference) ```typescript interface PosFile { version: number; metadata: PosMetadata; body: string; } interface PosMetadata { title?: string; page_width_mm: number; preview_mode: "autoscale" | "fixed"; chars_per_line?: number; codepage?: string; } ``` Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer).