# `.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).  
**Installed MIME type:** `application/x-posprint` (see packaging MIME XML).

---

## 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) |

---

## 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 |
| `page_width_mm` | `number` | `80` | Physical paper width (mm) |
| `chars_per_line` | `number?` | derived | Override column count; derived from mm if omitted |
| `codepage` | `string?` | `"CP437"` | Reserved; encoder uses CP437 today |

### Printable width model

Effective print/preview width uses Font A columns:

`printable_dots = chars_per_line() × 12`

| `page_width_mm` | Default `chars_per_line` | `printable_dots` |
|-----------------|--------------------------|------------------|
| ≤ 58 | 32 | 384 |
| > 58 | 48 | 576 |

### Legacy fields (ignored)

Unknown JSON keys are ignored by serde. Notably:

| Field | Former meaning | Current behaviour |
|-------|----------------|-------------------|
| `preview_mode` | autoscale / fixed preview | Ignored; UI uses zoom slider |
| `cut_after_print` | auto-cut after job | Ignored; use `@cut` in the template |

---

## 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:\nTOTAL: ${GrandTotal}\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"
}
```

---

## Asset resolution

- Paths in `@image` resolve relative to the **directory containing the `.pos` file** unless absolute.
- Parameterized paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` directory.

---

## Version migration

| From | To | Migration |
|------|-----|-----------|
| — | 1 | Initial release |

On load, if `version` is newer than the app supports → error. Older versions would migrate (none yet).

---

## Validation

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.

---

## Rust types

Defined in `src/io/mod.rs` (`PosFile`, `PosMetadata`) with `serde` derive. Used directly by the egui app (no IPC).
