# AI Template Pack ZIP format

Template Studio accepts authenticated ZIP uploads containing a manifest and raster assets.

## Layout

```text
my-pack.zip
├── template-pack.json
└── assets/
    ├── hero.webp
    ├── paper-bg.webp
    └── page-border.png
```

## Manifest

```json
{
  "format": "template-studio-pack",
  "version": 1,
  "template": {
    "name": "AI generated customer report",
    "type": "report",
    "document": {
      "theme": {
        "backgroundColor": "#f6f1e8",
        "surfaceColor": "#ffffff",
        "textColor": "#172033",
        "mutedColor": "#64748b",
        "accentColor": "#8b5e34",
        "borderColor": "#d8c7b3",
        "borderRadius": 14,
        "pageMarginTop": 12,
        "pageMarginRight": 12,
        "pageMarginBottom": 12,
        "pageMarginLeft": 12,
        "pagePadding": 18,
        "pageBackgroundImage": "asset://paper-bg",
        "pageBackgroundMode": "none",
        "pageBackgroundOpacity": 0.08,
        "decorativeBorder": false,
        "borderImage": "asset://page-border"
      },
      "blocks": [
        {
          "id": "hero-heading",
          "type": "heading",
          "props": {
            "text": "Report for {{customer.name}}"
          },
          "style": {
            "backgroundColor": "#fffaf2",
            "borderColor": "#d8c7b3",
            "borderWidth": 1,
            "borderRadius": 12,
            "padding": 18
          }
        },
        {
          "id": "hero-image",
          "type": "image",
          "props": {
            "url": "asset://hero",
            "alt": "Report hero"
          }
        }
      ]
    },
    "sampleData": {
      "customer": {
        "name": "Example Customer"
      }
    }
  },
  "assets": [
    {
      "key": "hero",
      "file": "assets/hero.webp"
    },
    {
      "key": "paper-bg",
      "file": "assets/paper-bg.webp"
    },
    {
      "key": "page-border",
      "file": "assets/page-border.png"
    }
  ]
}
```

Use `asset://KEY` anywhere in the document or sample data. Import replaces it with an opaque Template Studio media URL.

### Image layout

Image blocks support explicit report layout controls:

```json
{
  "id": "brand-logo",
  "type": "image",
  "props": {
    "url": "asset://logo",
    "alt": "Company logo",
    "variant": "logo",
    "maxWidth": 110,
    "maxHeight": 72,
    "fit": "contain"
  }
}
```

Use `variant: "logo"` for compact brand marks and `variant: "hero"` for banners/feature imagery. Hero images default to a 260px maximum height with `cover`; normal images default to 340px with `contain`. The renderer also recognises IDs/alt text containing `logo`, `mark`, `hero`, or `banner` for older packs that do not specify a variant.

For report pagination, blocks avoid splitting across pages by default. Optional block style flags are `keepWithNext`, `pageBreakBefore`, `pageBreakAfter`, and `allowPageBreak`.

### Page setup

Report themes can set A4 print margins independently in millimetres with `pageMarginTop`, `pageMarginRight`, `pageMarginBottom`, and `pageMarginLeft`. Each accepts 0–40 mm and defaults to 12 mm.

`pagePadding` is separate: it controls the internal spacing inside the rendered document/frame in pixels and defaults to 18 px.

### Page artwork

Reports default to a clean page even if the ZIP includes background or border assets. Set `pageBackgroundMode` to `"watermark"` or `"full"` to opt in to the background image. `pageBackgroundOpacity` controls artwork strength from 0 to 0.35.

Decorative border artwork is also opt-in with `decorativeBorder: true`. This prevents stationery-style page chrome from appearing automatically on operational reports.

### Styling

The constrained theme supports colors, border radius, background imagery and report border imagery. Blocks may also include a `style` object with background/text/border colors, border width/radius, padding and alignment. Arbitrary CSS/HTML/JavaScript is intentionally not supported.

### Limits

- ZIP upload: 20 MB compressed
- 100 files maximum
- 50 MB maximum expanded size
- 10 MB per image
- PNG, JPEG, WebP and GIF only
- `template-pack.json` must be at ZIP root