# Formato del deck

> Referencia del formato deck.json v1 de Live Deck: deck, presets de tema, diapositivas, fondos y mensajes de validación, con cada regla y límite.

Fuente de verdad: `shared/deck.ts`. Todos los objetos son estrictos: las claves desconocidas no pasan la validación.

## Deck

| Campo | Tipo | Reglas |
| --- | --- | --- |
| `version` | `1` | Obligatorio, literal 1. |
| `title` | string | Obligatorio, 1–200 caracteres. Se muestra en las listas y en el resumen. |
| `theme` | object | Opcional. Por defecto `{ background: "#10131a", foreground: "#f4f1ea", accent: "#ff7a45", muted: "#9aa3b2" }`. Es preferible `{ "preset": "<name>" }`. |
| `slides` | Slide[] | Obligatorio, 1–200. Los ids de las diapositivas son únicos. |

## Tema

Los colores van en hex: `#` + 3–8 dígitos hexadecimales.

| Campo | Tipo | Reglas |
| --- | --- | --- |
| `preset` | `"estudio"` \| `"editorial"` \| `"neon"` \| `"papel"` \| `"brutalista"` \| `"corporativo"` | Opcional. Trae colores, fuentes (display/body/mono), fondo de diapositiva (degradado y/o patrón), estilo de tarjeta, estilo de títulos y paleta de gráficos. Ver `themes.md`. |
| `background` | hex | Obligatorio sin `preset`; con uno, es un reemplazo opcional. |
| `foreground` | hex | Obligatorio sin `preset`; con uno, es un reemplazo opcional. |
| `accent` | hex | Obligatorio sin `preset`; con uno, es un reemplazo opcional. |
| `muted` | hex | Opcional. |
| `surface` | hex | Opcional. Reemplaza el color de tarjeta/superficie (tarjetas, texto con `card: true`, separaciones del gráfico de dona). |

- Con un preset, reemplaza colores solo cuando la marca del usuario lo exija: `{ "preset": "corporativo", "accent": "#0057b8" }`.
- Sin preset se mantienen exactamente las reglas de antes: `background`, `foreground` y `accent` son obligatorios, `muted` es opcional.

## Diapositiva

| Campo | Tipo | Reglas |
| --- | --- | --- |
| `id` | string | Obligatorio, `[A-Za-z0-9_-]{1,40}`, único en el deck. |
| `layout` | `"free"` \| `"quiz"` | Opcional, por defecto free. `"quiz"` requiere `quiz`, y `quiz` requiere `"quiz"`. |
| `background` | hex \| Background | Opcional, reemplaza el fondo del tema. Ver más abajo. |
| `notes` | string | Opcional (ponlo siempre), máximo 5000 caracteres. Solo para quien presenta; nunca se envía al público. |
| `elements` | Element[] | Obligatorio (usa `[]` en las diapositivas de quiz), máximo 60. Los ids de los elementos son únicos por diapositiva. |
| `quiz` | Quiz | Solo con `layout: "quiz"`. |

### Objeto de fondo de la diapositiva

Un string hex sigue funcionando (`"background": "#0b0d12"`). La forma de objeto (todos los campos opcionales, estricta):

| Campo | Tipo | Reglas |
| --- | --- | --- |
| `color` | hex | Color base sólido. |
| `gradient` | `{ "from": hex, "to": hex, "angle"?: number }` | Degradado lineal; `angle` 0–360 (grados). |
| `image` | asset src | Mismas reglas que el `src` de una imagen (`https://…` o `assets/<file>`, sin `..`). Cubre toda la diapositiva. |
| `dim` | number 0–0.9 | Oscurece la imagen para que el texto siga siendo legible. Usa 0.4–0.6 debajo de texto. |
| `pattern` | `"dots"` \| `"grid"` \| `"lines"` \| `"noise"` | Textura sutil sobre el color/degradado. |

```json
{ "background": { "gradient": { "from": "#1b1f3a", "to": "#0b0d12", "angle": 135 }, "pattern": "dots" } }
```

Omite `background` en la mayoría de diapositivas: el preset ya trae uno. Usa el objeto para aperturas, separadores de sección y cierres.

Las diapositivas importadas (`live-deck import`) usan exactamente este campo: `"background": { "image": "assets/slide-01.png" }` sin un layout nuevo; encima pueden ir elementos como el `qr` para unirse.

## Mensajes de validación

La CLI imprime `path: message`, donde path es la ruta dentro del JSON (`slides.2.quiz.correctIndex: correctIndex must point to an option`). Corrige en esa ruta y vuelve a ejecutar.