template-studio/docs/template-pack.md

# 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,
        "reportDensity": "auto",
        "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.

### Report density

Set `reportDensity` to `"auto"`, `"comfortable"`, or `"compact"`. Auto is the default. Reports with at least 20 blocks or 4 table blocks automatically use compact density.

Compact density:
- groups consecutive KPI blocks into a three-column grid;
- tightens heading, block, KPI and table spacing;
- treats normal `pageBreakBefore` hints as soft so sections can flow into unused page space;
- still honours `forcePageBreak: true`;
- keeps headings with the following content where possible.

For long tables set `style.allowPageBreak: true`. The renderer then permits rows to continue onto the next page and repeats the table header. Use `style.compact: true` to request tight table spacing even in comfortable mode.

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


# Reusable Theme Packs

Themes are independent from template content. Applying or removing a theme replaces only `document.theme`; blocks, bindings and sample data are unchanged.

A ZIP theme pack uses:

```text
my-theme.zip
├── theme-pack.json
└── assets/
    ├── background.webp
    └── border.png
```

Minimal `theme-pack.json`:

```json
{
  "format": "template-studio-theme",
  "version": 1,
  "name": "Clean Operations",
  "appliesTo": "report",
  "theme": {
    "backgroundColor": "#eef3f7",
    "surfaceColor": "#ffffff",
    "textColor": "#172b3a",
    "mutedColor": "#607282",
    "accentColor": "#123b5d",
    "borderColor": "#d8e1e8",
    "borderRadius": 8,
    "fontFamily": "Arial",
    "reportDensity": "auto",
    "pageMarginTop": 9,
    "pageMarginRight": 9,
    "pageMarginBottom": 9,
    "pageMarginLeft": 9,
    "pagePadding": 14,
    "pageBackgroundMode": "none",
    "pageBackgroundImage": "asset://background",
    "decorativeBorder": false,
    "borderImage": "asset://border"
  },
  "assets": [
    { "key": "background", "file": "assets/background.webp" },
    { "key": "border", "file": "assets/border.png" }
  ]
}
```

For themes with no image assets, the same manifest can be uploaded directly as a `.json` file. `appliesTo` may be `"report"`, `"email"`, or `"all"`.