# `.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:** `application/x-posprint` (registered via `packaging/mime/posprint.xml`; claimed by `*.pos`) --- ## 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, "preview_mode": "autoscale", "chars_per_line": 48, "codepage": "CP437", "cut_after_print": true } ``` | 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; derived from mm if omitted | | `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text | | `cut_after_print` | `boolean` | `true` | Append cut command when printing if doc has no `@cut` | ### Page width derivation | `page_width_mm` | Typical dots (203 DPI) | Default `chars_per_line` (Font A) | |-----------------|------------------------|-----------------------------------| | 58 | 384 | 32 | | 80 | 576 | 48 | --- ## Example file **`receipt.pos`:** ```json { "version": 1, "metadata": { "title": "Standard Receipt", "page_width_mm": 80, "preview_mode": "autoscale", "codepage": "CP437", "cut_after_print": true }, "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). --- ## Alternative considered: two-file bundle Rejected for v1: `.pos` + sidecar `.pos.json` adds friction. Single JSON file keeps save/load atomic. A future `.poszip` could bundle images for portable templates. --- ## 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; cut_after_print?: boolean; } ``` Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer).