# CBDF Layout Catalogue (Phase II starter)

## Files

| File | Audience | Purpose |
|------|----------|---------|
| `cbdf-layout-catalog-v1.json` | Encoders / decoders | Full machine registry (legacy 0–255 + mobile pairs + 50 named desktop/mobile pairs) |
| `NAMED-LAYOUTS.md` | Humans | Readable index of named desktop layouts with pane tables and nav |
| `generate_layout_catalog.py` | Maintainers | Regenerates the JSON |
| `export_named_index.py` | Maintainers | Regenerates `NAMED-LAYOUTS.md` |

## Wire format

Styles section starts with:

```text
[LayoutID: uint16 little-endian]
```

Emit the numeric `id` from the catalogue. Do **not** invent free-form layout on the wire beyond catalogue IDs (custom experimental range `0xF000–0xFFFE` is private).

## ID map

| Range | Contents |
|-------|----------|
| `0x0000–0x00FF` | Legacy 1-byte bitfield layouts (256) |
| `0x0100–0x0131` | Named desktop starters (50) |
| `0x0200–0x02FF` | Mobile stacks for each legacy ID |
| `0x0300–0x0331` | Mobile stacks for each named desktop |
| higher | Reserved for future catalogue growth |

## Pane indices

**Default order:** Header → Left aside → Main cells (row-major) → Right aside → Footer → Overlay (last).

Each layout’s `panes[]` array is authoritative. Encoder should open `STYLE_CONTAINER` for index `0 .. pane_count-1` in order.

## Nav bar

- Host pane: `nav.pane_index` where `nav_host` is true (usually header or left).
- Markup: `ITEM_BLOCK` **type = 2** (nav), style index into Nav Bar Styles sub-table.
- Items separated by `US` (`0x1F`); typically each item is `LINK_START`…`LINK_END`.
- Mobile: follow `nav.mobile_collapse` (`hamburger_header`, `drawer_left`, `bottom_tabs`, `stack`).

## Responsive / mobile

- Prefer encoding the **desktop** `LayoutID` and let the client switch to `pair.mobile_layout_id` at `default_mobile_breakpoint_px` (768).
- Or encode a mobile-specific document using the mobile layout id directly (e.g. QMail rarely needs both).

## Regenerate

```bash
python generate_layout_catalog.py
python export_named_index.py
```