# Template — LLM Reference

A **template** is the complete structure of an email document. It is the top-level JSON object that the builder reads, renders, and exports. Every template is a plain object with three top-level fields: `bodyStyle`, `tree`, and an optional `dataLayer`. The `tree` is an array of exactly three `Section` nodes — `header`, `content`, and `footer` — in that order, always.

> **Note:** `Html`, `Head`, and `Body` are not part of the document object. They are internal rendering concerns handled by the builder. The document you author and store contains only `bodyStyle`, `dataLayer`, and `tree`.

---

## Document Shape

```
{
  bodyStyle:  { … }          ← Body styling: width, background, padding, font
  dataLayer:  { … }          ← (optional) data for bindings
  tree: [
    Section (sectionType: "header")    ← always index 0, never moves
    Section (sectionType: "content")   ← always index 1, never moves
    Section (sectionType: "footer")    ← always index 2, never moves
  ]
}
```

The three Sections are **fixed structural slots**. They are not added or removed — they are always present. Their order is immutable. The builder uses `sectionType` to identify each slot; the slots themselves are not interchangeable.

---

## Full Document JSON Structure

```json
{
  "bodyStyle": {
    "backgroundColor": "#ffffff",
    "fontFamily": "sans-serif"
  },
  "dataLayer": {},
  "tree": [
    {
      "id": "section-header",
      "type": "SectionComponent",
      "config": {
        "sectionType": "header",
        "backgroundColor": "#ffffff",
        "padding": "0"
      },
      "children": []
    },
    {
      "id": "section-content",
      "type": "SectionComponent",
      "config": {
        "sectionType": "content",
        "backgroundColor": "#ffffff",
        "padding": "0"
      },
      "children": []
    },
    {
      "id": "section-footer",
      "type": "SectionComponent",
      "config": {
        "sectionType": "footer",
        "backgroundColor": "#f9fafb",
        "padding": "0"
      },
      "children": []
    }
  ]
}
```

---

## Nesting Rules

These rules are absolute. Violating them produces invalid templates.

### Section
- There are **exactly three** Sections per template: `header`, `content`, `footer`.
- **`sectionType` is mandatory** — every Section must declare `"sectionType": "header" | "content" | "footer"` in its `config`.
- Sections **cannot be nested** inside each other or inside any other component.
- Sections **cannot be added or removed** — they are always present.
- Sections **cannot be reordered** — `header` is always first, `content` second, `footer` last.
- The only **allowed children** of a Section are `Container` nodes.

### Container
- A `Container` is always a **direct child of a Section**.
- Containers **cannot be nested** inside another Container, directly or indirectly.
- Multiple Containers can exist inside one Section — they stack **vertically**.
- The only **allowed parent** of a Container is a Section.

### Column and Row
- `Column` and `Row` live **inside a Container** cell, below the Container level.
- `Column` and `Row` **can nest freely and infinitely** inside each other.
- Neither `Column` nor `Row` can be a direct child of a Section.

### Leaf components
- `Text`, `Image`, `Button`, `Heading`, `Icon`, `Divider`, `Spacer` are leaf nodes.
- They live inside `Column`, `Row`, or directly in a `Container` cell.
- They cannot have structural children.

---

## Component Hierarchy Summary

```
tree (array of 3)
└── Section                        ← exactly 3; fixed positions
    └── Container                  ← direct child of Section only; no nesting
        └── Column / Row           ← freely nestable
            └── Text / Image / Button / Heading / Icon / Divider / Spacer
```

| Component | Allowed parent | Can nest itself? | Children |
|---|---|---|---|
| `Section` | `tree` (root array) | ✗ No | `Container` only |
| `Container` | `Section` only | ✗ No | `Column`, `Row`, leaf nodes |
| `Column` | `Container`, `Column`, `Row` | ✓ Yes | `Column`, `Row`, leaf nodes |
| `Row` | `Container`, `Column`, `Row` | ✓ Yes | `Column`, `Row`, leaf nodes |
| Leaf nodes | `Column`, `Row`, `Container` | ✗ No | None |

---

## The Three Sections

### `header`
- Always the first Section in `tree` (index 0).
- Intended for: logo, brand bar, navigation, pre-header text.
- Contains one or more `Container` children stacked vertically.

### `content`
- Always the second Section in `tree` (index 1).
- Intended for: all email body content — hero, product rows, articles, CTAs, dividers.
- Multiple `Container` children stack vertically to build up the content area.
- This is where the bulk of the email lives.

### `footer`
- Always the third Section in `tree` (index 2).
- Intended for: unsubscribe link, legal text, social icons, mailing address.
- Contains one or more `Container` children stacked vertically.

---

## Top-Level Fields

### `bodyStyle`
Controls the email canvas appearance. All properties are optional.

| Property | Type | Description |
|---|---|---|
| `color` | `string` | Default text color |
| `fontSize` | `string` | Default font size |
| `backgroundColor` | `string` | Background color of the email canvas |
| `lineHeight` | `string` | Default line height |
| `fontFamily` | `string` | Default font family |
| `backgroundImage.src` | `string` | Background image URL |
| `backgroundImage.repeat` | `string` | CSS `background-repeat` value |
| `backgroundImage.size` | `string` | CSS `background-size` value |
| `backgroundImage.position` | `string` | CSS `background-position` value |

### `dataLayer`
An optional plain JSON object passed to the renderer at render time. It is the single source of truth for all dynamic values used by `bindings`. See **SECTION: DATA-BINDING** for the full reference. Omit or set to `{}` when the template has no dynamic content.

### `tree`
An array of exactly three `Section` nodes in fixed order: `header`, `content`, `footer`. This is the entire component tree of the email body. Each `Section` holds `Container` children which in turn hold the layout and leaf components.

---

## Rules & Constraints

- **One document = one flat object.** There is no `Html`, `Head`, or `Body` node in the document — those are internal rendering details handled by the builder.
- **`tree` has exactly three items.** The three Sections are the only entries in `tree`. They cannot be added, removed, or reordered.
- **Sections are immovable.** Their `sectionType` values and order are fixed: index 0 = `header`, index 1 = `content`, index 2 = `footer`.
- **Containers do not nest.** Any container-inside-container structure is invalid regardless of depth.
- **`Column` and `Row` are the only freely nestable structural components.** Use them to build any layout complexity below the Container level.
- **Leaf nodes are terminal.** They cannot contain other components.
- **`bodyStyle` is not a `ComponentNode`.** It is a plain config object, not a node with `id`, `type`, or `children`.