# `.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,
  "preview_mode": "autoscale",
  "chars_per_line": 48,
  "codepage": "CP437",
  "cut_after_print": true,
  "default_feed_before_cut": 4
}
```

| 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` |
| `default_feed_before_cut` | `number` | `4` | Feed lines before auto-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;
  default_feed_before_cut?: number;
}
```

Rust mirrors these with `serde` derive for 1:1 IPC across Tauri.
