slotdeck 0.1.0 → 0.1.1

package/docs/manifest-format.md

@@ -0,0 +1,207 @@
+# Manifest format
+
+A manifest is a JSON object of type `TemplateManifest`. It describes one template: which of its slides are
+reusable patterns and which shapes on them are slots.
+
+```ts
+import type { TemplateManifest, PatternDef, SlotDef, TextSlotDef, ImageSlotDef, TableSlotDef, ChartSlotDef, RepeatDef } from 'slotdeck';
+```
+
+A manifest is written once per template. You can have a model draft it (`draftManifest`), change it with
+operations (`changeManifest`) or by instruction (`editManifest`), and verify it (`checkManifest`): see
+[template-studio.md](template-studio.md). This page is the reference for what the JSON means.
+
+## Example
+
+```json
+{
+  "version": 1,
+  "name": "demo",
+  "language": "en",
+  "direction": "ltr",
+  "alignOnDirectionChange": "flip",
+  "patterns": [
+    {
+      "id": "cover",
+      "sourceSlide": 1,
+      "description": "Opening slide with the presentation's title and a subtitle.",
+      "slots": [
+        { "name": "title", "kind": "text", "shapeId": "5", "size": 50, "maxChars": 36 },
+        { "name": "subtitle", "kind": "text", "shapeId": "6", "size": 20, "maxChars": 86, "empty": "remove" },
+        { "name": "organizationDepartment", "kind": "text", "shapeId": "7", "size": 13, "maxChars": 61, "deckField": "organizationDepartment", "alignOnDirectionChange": "keep" }
+      ]
+    },
+    {
+      "id": "icon-cards",
+      "sourceSlide": 5,
+      "description": "A row of cards, each with an icon, a heading and a short text.",
+      "slots": [
+        { "name": "title", "kind": "text", "shapeId": "5", "size": 34, "maxChars": 41 },
+        { "name": "card1Icon", "kind": "image", "imageKind": "icon", "shapeId": "9" },
+        { "name": "card1Heading", "kind": "text", "shapeId": "10", "size": 19, "maxChars": 15 },
+        { "name": "card1Text", "kind": "text", "shapeId": "11", "size": 15, "maxChars": 117 },
+        { "name": "card2Icon", "kind": "image", "imageKind": "icon", "shapeId": "15" },
+        { "name": "card2Heading", "kind": "text", "shapeId": "16", "size": 19, "maxChars": 15 },
+        { "name": "card2Text", "kind": "text", "shapeId": "17", "size": 15, "maxChars": 117 }
+      ],
+      "repeat": {
+        "item": "card",
+        "slots": ["card{n}Icon", "card{n}Heading", "card{n}Text"],
+        "shapes": [["6"], ["12"]],
+        "min": 2,
+        "max": 4
+      }
+    }
+  ]
+}
+```
+
+## `TemplateManifest`
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `version` | `1` | yes | Always 1. |
+| `name` | string | yes | A name for the template. Used in messages. |
+| `direction` | `"ltr"` or `"rtl"` | yes | The reading direction the template was designed for. |
+| `patterns` | `PatternDef[]` | yes | The reusable layouts. |
+| `language` | string | no | BCP 47 tag of the template's sample text. Decks default to it. |
+| `alignOnDirectionChange` | `"flip"` or `"keep"` | no | What happens to left and right paragraph alignment in a deck that reads the other way. `flip` (default) mirrors it. `keep` leaves it as designed. A text slot can override this. |
+
+## `PatternDef`
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `id` | string | yes | What decks call the pattern. Unique in the manifest. Lower-case words joined by hyphens is the convention. |
+| `sourceSlide` | integer | yes | Number of the template slide the pattern is cloned from, counted from 1. |
+| `description` | string | yes | What the pattern is for. The planning model reads it to choose patterns, so write it for an author: what the slide holds and when to use it. |
+| `slots` | `SlotDef[]` | yes | The shapes a deck fills. |
+| `figures` | boolean | no | The pattern is built around numbers. The planner offers it only when the brief contains figures, so a model is not led to invent statistics. |
+| `repeat` | `RepeatDef` | no | A row or grid of like items whose number a deck may choose. See below. |
+| `sequences` | string[][][] | no | Rows of items with a fixed count, for mirroring in decks that read the other way. Each row lists its items first to last in the template's direction, and each item lists its slot names. Not needed for slots covered by `repeat`. |
+
+## Slots: properties every kind has
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `name` | string | yes | What decks call the slot. Unique within the pattern. Letters and digits, starting with a lower-case letter. |
+| `kind` | `"text"`, `"image"`, `"table"` or `"chart"` | yes | What the slot holds. |
+| `shapeId` | string | yes | The id of the shape on the source slide (the `id` attribute of the shape's `p:cNvPr` element, as a string). `inspectTemplate` and `studioView` list them. |
+| `description` | string | no | Guidance for the planning model about this slot, such as "One line". |
+| `empty` | `"error"`, `"remove"`, `"keep"` or `"drop"` | no | What happens without a value. Default `error` (required). See [concepts.md](concepts.md). |
+
+Slots with `empty` of `keep` or `drop` are never offered to the planning model.
+
+## Text slot (`kind: "text"`)
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `maxChars` | integer | Soft limit on the total characters of the slot. Exceeding it gives a warning. |
+| `maxParagraphs` | integer | Soft limit on the number of paragraphs. When it is more than 1, the planner asks the model for a list of paragraphs. |
+| `deckField` | string | Take the value from `deck.fields[deckField]` when the slide does not set it. |
+| `size` | number | Font size of the slot's text on the template slide, in points. Informational: it decides whether a deck's `textScale` applies (see `scales`). |
+| `scales` | boolean | Whether a deck's `textScale` applies to this slot. Default: yes for text of 12 pt and under that is not a deck field. |
+| `fontSize` | number | Sets the font size outright, in points. For a derived pattern that uses the shape differently. |
+| `box` | `{ x, y, w, h }` | Moves and resizes the text box, as fractions of the slide (0 to 1). Only for a shape that is not inside a group. |
+| `paragraphGap` | number | Space after each paragraph, in points. |
+| `alignOnDirectionChange` | `"flip"` or `"keep"` | Overrides the manifest's setting for this slot. |
+| `styleRun` | `"first"` or `"last"` | Which run of the template paragraph supplies the formatting, when the template paragraph mixes styles (a bold label followed by plain text). Default `first`. |
+
+## Image slot (`kind: "image"`)
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `imageKind` | `"photo"`, `"icon"` or `"graphic"` | Required. `photo`: a generated or supplied photo. `icon`: one of the app's icon set. `graphic`: a picture the app supplies, such as a diagram. |
+| `fit` | `"cover"` or `"contain"` | `cover` crops the picture to fill the frame. `contain` shows the whole picture inside the frame's area. Default: `cover` for photos, `contain` for icons and graphics. |
+| `box` | `{ x, y, w, h }` | The area the picture may use, when other than the sample picture's frame. Fractions of the slide. Only for a picture that is not inside a group. |
+
+## Table slot (`kind: "table"`)
+
+The shape must be a table.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `maxColumns` | integer | Soft limit on columns. |
+| `maxRows` | integer | Soft limit on body rows (the header row is not counted). |
+| `maxCellChars` | integer | Soft limit on the characters in one cell. |
+| `headerText` | `{ size?, bold?, color?, font? }` | Formatting for header cells, where the sample table defines none or it should differ. `color` is hex without `#`. |
+| `bodyText` | `{ size?, bold?, color?, font? }` | The same for body cells. |
+
+## Chart slot (`kind: "chart"`)
+
+The shape is the sample picture of a chart. At render time it is replaced by a native chart in the same place.
+The shape must not be inside a group.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `box` | `{ x, y, w, h }` | The area the chart may use, when other than the sample picture's frame. |
+| `maxCategories` | integer | Soft limit on categories. |
+| `maxSeries` | integer | Soft limit on series. |
+| `colors` | string[] | Series colours in order, hex without `#`. They repeat when there are more series. |
+| `text` | `{ size?, bold?, color?, font? }` | Formatting of axis labels, data labels and the legend. |
+| `lineColor` | string | Colour of gridlines and axis lines, hex without `#`. |
+
+## `RepeatDef`: a row or grid of items
+
+```json
+"repeat": {
+  "item": "card",
+  "slots": ["card{n}Icon", "card{n}Heading", "card{n}Text"],
+  "shapes": [["6"], ["12"], ["18"], ["24"]],
+  "min": 2,
+  "max": 4,
+  "span": { "left": 0.04, "right": 0.96 },
+  "columns": 3
+}
+```
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `item` | string | yes | What one item is called in prompts, such as `card` or `figure`. |
+| `slots` | string[] | yes | Slot name templates of one item. `{n}` stands for the item number, from 1. For every item drawn on the slide the pattern must have a slot with each of these names (`card1Icon`, `card2Icon`, ...). |
+| `shapes` | string[][] | yes | For each item drawn on the template slide, first in reading order first: the ids of the shapes that move together as that item. Usually the group around a card. A background shape that sits outside the group belongs in the list too. |
+| `min`, `max` | integer | no | Fewest and most items a deck may ask for. Both default to the number drawn. |
+| `span` | `{ left, right }` | no | Left and right limits of the row, as fractions of the slide width. Defaults to the row as drawn. Needed when `max` is more than the drawn items can fit in the drawn width. Only applies to shapes placed directly on the slide. |
+| `columns` | integer | no | For a grid: how many items one line holds on the template slide. Leave it out for a single row. A grid cannot hold more items than it draws. |
+
+How the items are laid out for a given count is described in [layout-freedom.md](layout-freedom.md).
+
+Slots of copied items do not appear in the manifest. They are derived: item 5 of a row that draws 4 gets copies
+of item 4's slots, named with the next number.
+
+## Rules a manifest must satisfy
+
+`checkManifest(template)` reports violations of these:
+
+- Every `sourceSlide` exists in the pptx.
+- Every `shapeId` is a shape on that slide, and is the right kind of shape for the slot (a text slot points at
+  a shape with text, an image slot at a picture, a table slot at a table). A slot with `"empty": "drop"` may
+  point at any shape, because the shape is only ever removed.
+- Pattern ids are unique. Slot names are unique within a pattern.
+- A `box` is not set on a shape inside a group. A chart slot's shape is not inside a group.
+- For a `repeat`: a slot exists for every name template and every drawn item; every shape id exists; all items
+  sit directly on the slide or all in the same group; `min` is at least 1 and not more than `max`.
+
+It also warns about text slots without `maxChars` and about two slots that point at the same shape.
+
+## Finding shape ids
+
+```ts
+import { inspectTemplate, PptxPackage } from 'slotdeck';
+
+const info = inspectTemplate(PptxPackage.load(pptxBytes));
+for (const shape of info.slides[4].shapes) {
+  // slide 5: index 4
+  console.log(shape.id, shape.kind, shape.box, shape.groupId ?? '', shape.paragraphs?.join(' / ') ?? '');
+}
+```
+
+`shape.box` is `{ x, y, w, h }` as fractions of the slide, already worked out through any groups. `shape.kind`
+is `text`, `picture`, `shape` (a drawn shape without text), `line`, `group`, `table` or `other`.
+
+## Writing good descriptions
+
+The planning model chooses a pattern by its `description` and its slots' names and limits. A description should
+say what the slide holds and when to use it, in one or two sentences, without numbers that the deck may change:
+
+- Good: "A row of cards, each with an icon, a heading and a short text: features, steps or categories."
+- Poor: "Four cards." (the count can vary, and it does not say what the cards are for)

package/docs/providers.md

@@ -0,0 +1,236 @@
+# Model providers
+
+slotdeck does not know any model service. It defines two small interfaces, and you pass objects that implement
+them. This is how it works with a public API, a cloud account, or a gateway inside a network with no internet
+access.
+
+```ts
+import type { LlmProvider, JsonRequest, JsonSchema, ImageProvider, ImageRequest } from 'slotdeck';
+```
+
+## `LlmProvider`: the text model
+
+```ts
+interface LlmProvider {
+  /** Resolves with the parsed JSON value. */
+  generateJson(request: JsonRequest): Promise<unknown>;
+}
+
+interface JsonRequest {
+  system: string;       // the system prompt: the role and the rules
+  prompt: string;       // the user message: the brief, the manifest's patterns, what to answer
+  schema: JsonSchema;   // the JSON Schema the answer must follow
+  images?: Array<{ mimeType: string; data: Uint8Array }>; // pictures to look at; only draftManifest sends them
+  signal?: AbortSignal; // pass it to your HTTP call so work can be cancelled
+}
+```
+
+The contract:
+
+- Resolve with the **parsed** value (an object), not a string of JSON.
+- The value should follow `schema`. slotdeck checks what it gets back against the template's manifest and asks
+  again when content breaks a limit, but it expects the overall shape the schema describes.
+- Reject (throw) when the call fails. slotdeck does not retry failed calls; add retries in your provider if you
+  want them.
+- One call is one request and one answer. There is no conversation state: every request carries everything it
+  needs.
+
+### What the schemas contain
+
+Only a small, widely supported subset of JSON Schema:
+
+- `type`: `object`, `array`, `string`, `integer`, `number`, `boolean`
+- `properties`, `required`, `items`, `enum`, `description`
+- in a few places `minItems`, `maxItems`, `minimum`, `maximum`
+
+There is no `anyOf`, `oneOf`, `$ref`, `pattern` or `format`. If your backend rejects the length or range
+keywords, your provider can delete them from the schema before sending it: the result is checked by code in any
+case.
+
+### A provider for a backend with structured output
+
+Most hosted models and gateways accept a JSON Schema and return JSON that follows it. The adapter is then a
+single HTTP call. The request and response fields below are placeholders: use the ones your gateway documents.
+
+```ts
+import type { LlmProvider } from 'slotdeck';
+
+export function gatewayModel(options: { url: string; model: string; token: () => Promise<string> }): LlmProvider {
+  return {
+    async generateJson({ system, prompt, schema, signal }) {
+      const response = await fetch(options.url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${await options.token()}` },
+        body: JSON.stringify({
+          model: options.model,
+          messages: [
+            { role: 'system', content: system },
+            { role: 'user', content: prompt },
+          ],
+          // However your gateway asks for JSON that follows a schema:
+          response_format: { type: 'json_schema', json_schema: { name: 'answer', schema } },
+        }),
+        signal,
+      });
+      if (!response.ok) throw new Error(`Model gateway answered ${response.status}: ${(await response.text()).slice(0, 300)}`);
+      const body = await response.json();
+      const text = body.choices[0].message.content; // wherever your gateway puts the answer text
+      return JSON.parse(text);
+    },
+  };
+}
+```
+
+### A provider for a model without structured output
+
+Put the schema into the prompt and parse what comes back. Models often wrap JSON in a code fence or add a
+sentence around it, so extract the JSON before parsing.
+
+```ts
+export function plainTextModel(complete: (system: string, prompt: string, signal?: AbortSignal) => Promise<string>): LlmProvider {
+  return {
+    async generateJson({ system, prompt, schema, signal }) {
+      const instruction =
+        `${prompt}\n\nAnswer with one JSON value that follows this JSON Schema, and nothing else:\n${JSON.stringify(schema)}`;
+      const text = await complete(system, instruction, signal);
+      const start = text.indexOf('{');
+      const end = text.lastIndexOf('}');
+      if (start < 0 || end <= start) throw new Error(`The model did not answer with JSON: ${text.slice(0, 200)}`);
+      return JSON.parse(text.slice(start, end + 1));
+    },
+  };
+}
+```
+
+Every top-level answer slotdeck asks for is a JSON object, so looking for the outermost braces is safe.
+
+### Choosing a model
+
+- The requests are small. Measured on the demo template (15 patterns): the outline request is a system prompt
+  of about 600 characters, a prompt of about 3,600 characters and a schema of about 700 characters. The writing
+  request for a 15-slide deck is a prompt of about 1,500 characters and a schema of about 9,800 characters. Any
+  current general-purpose model handles this.
+- Writing a deck is a single call that returns all slides, so the model needs enough output room for the whole
+  deck. The JSON of a nine-slide deck is about 6 KB.
+- `editManifest` sends the whole manifest with the measured shapes of every pattern's slide: about 58,000
+  characters for a template with 24 patterns.
+- `draftManifest` can send a picture of each slide (`images`). A provider for a model that cannot see may ignore
+  them; the draft then relies on measurements alone.
+
+### Timeouts and cancellation
+
+slotdeck passes `signal` through when the caller gave one. Your provider should pass it to its HTTP call, and
+should have a time limit of its own: a model call can hang without failing.
+
+```ts
+const limit = AbortSignal.timeout(180_000);
+const combined = signal ? AbortSignal.any([signal, limit]) : limit;
+await fetch(url, { ...init, signal: combined });
+```
+
+### Logging and auditing
+
+A provider is the one place every model call passes through, so it is where to count calls, log prompts or
+enforce a budget:
+
+```ts
+const counted: LlmProvider = {
+  async generateJson(request) {
+    const started = Date.now();
+    try {
+      return await inner.generateJson(request);
+    } finally {
+      log({ promptChars: request.prompt.length, ms: Date.now() - started });
+    }
+  },
+};
+```
+
+## `ImageProvider`: the picture source
+
+```ts
+interface ImageProvider {
+  /** Resolves with PNG, JPEG or GIF bytes. */
+  generateImage(request: ImageRequest): Promise<Uint8Array>;
+}
+
+interface ImageRequest {
+  prompt: string;       // a description of the picture, written by the planning model
+  kind: 'photo' | 'icon' | 'graphic'; // what the slot holds; generated pictures are photos
+  aspectRatio: number;  // width divided by height of the frame the picture goes into
+  signal?: AbortSignal;
+}
+```
+
+It does not have to be an image model. A stock library, an internal picture search or a fixed set of brand
+photos all fit: return the bytes of the picture that best matches `prompt`.
+
+```ts
+const brandPhotos: ImageProvider = {
+  async generateImage({ prompt, aspectRatio }) {
+    const hit = await photoLibrary.search(prompt, { orientation: aspectRatio >= 1 ? 'landscape' : 'portrait' });
+    return new Uint8Array(await hit.download());
+  },
+};
+```
+
+The picture is cropped to the frame when the slot's fit is `cover`, so any proportions work; matching
+`aspectRatio` just loses less of the picture.
+
+Without an `ImageProvider`, leave `images` out. `generateDeck` and the chat tools then plan decks with no
+generated photos (patterns that need a photo are not offered), unless you supply photos as `assets`.
+
+## The included Gemini adapters
+
+```ts
+import { gemini, geminiImages, vertexEndpoint, GeminiError, GEMINI_DEVELOPER_ENDPOINT } from 'slotdeck';
+
+const llm = gemini({ model: 'gemini-3.8-flash', apiKey });
+const images = geminiImages({ model: 'gemini-3.1-flash-image', apiKey });
+```
+
+They call Google's Interactions API with plain `fetch`, so they need network access to that API. Inside a
+network without it, write a provider for your own gateway as shown above.
+
+Options of both:
+
+| Option | Meaning |
+| --- | --- |
+| `model` | Model id. Required. |
+| `apiKey` | Gemini Developer API key, sent as the `x-goog-api-key` header. |
+| `endpoint` | Interactions endpoint. Defaults to `GEMINI_DEVELOPER_ENDPOINT`. Use `vertexEndpoint(project, location?)` for Vertex AI, or the address of a proxy. |
+| `headers` | Extra headers, or a function returning them (may be async), for example a fresh `Authorization: Bearer` token. |
+| `fetch` | A custom `fetch`, for proxies and tests. |
+| `timeoutMs` | Gives up on a request after this long. Default 180000 (3 minutes). `0` waits for ever. |
+
+Only for `gemini`: `thinkingLevel` (`minimal`, `low`, `medium`, `high`) and `maxOutputTokens`.
+
+Only for `geminiImages`: `imageSize` (`512`, `1K`, `2K`, `4K`; default `1K`) and `style`, a sentence appended to
+every prompt, such as a house photo style.
+
+Failures throw `GeminiError`, which has the HTTP `status` when there was one.
+
+Vertex AI:
+
+```ts
+const llm = gemini({
+  model: 'gemini-3.8-flash',
+  endpoint: vertexEndpoint('my-project'), // location defaults to 'global'
+  headers: async () => ({ Authorization: `Bearer ${await getAccessToken()}` }),
+});
+```
+
+The adapters were run live against the Gemini Developer API. The Vertex endpoint is supported by the adapter
+but has not been run live.
+
+## Testing without a model
+
+A scripted provider makes tests deterministic and free:
+
+```ts
+const scripted: LlmProvider = {
+  async generateJson({ prompt, schema }) {
+    return cannedAnswers.shift(); // objects shaped like the schema
+  },
+};
+```

package/docs/rendering.md

@@ -0,0 +1,172 @@
+# Rendering
+
+Rendering turns a deck (JSON) into a `.pptx` using a template. It uses no model and no network, and it is
+deterministic: the same template, deck and assets give the same bytes.
+
+```ts
+import { loadTemplate, renderDeck, validateDeck, extractAssets, DeckValidationError } from 'slotdeck';
+```
+
+## `loadTemplate(pptx, manifest)`
+
+```ts
+function loadTemplate(pptx: Uint8Array, manifest: TemplateManifest): Template;
+```
+
+Unzips the template once. The result is `{ pkg, manifest }`. Keep it and reuse it for every render; rendering
+does not change it. Loading reads the whole file, so do it once at start-up rather than per request. A render
+is fast: a 15-slide deck from the demo template takes about 100 ms.
+
+It does not verify the manifest. Call `checkManifest(template)` when a template or manifest is loaded if you
+want to catch a manifest that no longer matches its file (see [template-studio.md](template-studio.md)).
+
+## `renderDeck(template, deck, options?)`
+
+```ts
+function renderDeck(template: Template, deck: DeckSpec, options?: RenderOptions): RenderResult;
+
+interface RenderOptions {
+  assets?: Record<string, Uint8Array>; // picture bytes by asset id
+  layout?: 'strict' | 'adaptive';      // default 'strict'
+}
+
+interface RenderResult {
+  pptx: Uint8Array;
+  warnings: Issue[]; // non-blocking findings, such as text over a slot's budget
+}
+```
+
+What it does, for each slide of the deck:
+
+1. Clones the template slide of the slide's pattern, with its layout, background and every shape.
+2. For a pattern with a row or grid of items, removes or copies items to match `items` and spaces them out.
+3. Fills each slot: text into text shapes, pictures into picture frames, rows into tables, a native chart in
+   place of a chart slot's sample picture.
+4. Removes shapes whose slot is left out (optional slots in `adaptive` layout, and slots with `empty: "drop"`).
+5. Sets the page number where the template has one.
+
+Then it writes a new package that contains only what the new slides use: template slides, pictures and other
+parts that are not referenced any more are left out, so the output is not bloated by the template's sample
+content. Speaker notes, named sections and revision history of the template are not carried over, because they
+describe the template's own slides.
+
+### Assets
+
+Every `ImageRef` in the deck names an asset id. `options.assets` must have bytes under that id, or the deck is
+invalid (`asset "x" was not provided`). The same bytes may be used by several slides; they are stored in the
+file once.
+
+```ts
+renderDeck(template, deck, {
+  assets: {
+    clock: clockPngBytes,
+    'photo-commute': photoJpegBytes,
+    'gen-68db256a51fa6c83': generatedPhotoBytes,
+  },
+});
+```
+
+When a deck was made by the planner, `resolveAssets` or `generateDeck` builds this map for you
+(see [generating.md](generating.md)).
+
+### Errors
+
+`renderDeck` validates first. If the deck has any error-level issue it throws:
+
+```ts
+try {
+  renderDeck(template, deck, { assets });
+} catch (error) {
+  if (error instanceof DeckValidationError) {
+    for (const issue of error.issues) console.log(issue.severity, issue.slide, issue.slot, issue.message);
+  } else {
+    throw error; // the manifest does not match the template, or an image format is not supported
+  }
+}
+```
+
+Other exceptions mean the manifest and the pptx disagree (for example
+`Pattern "x": slot "y" points at shape #12, which is not on template slide 3`). `checkManifest` finds these
+ahead of time.
+
+## `validateDeck(manifest, deck, options?)`
+
+```ts
+function validateDeck(manifest: TemplateManifest, deck: DeckSpec, options?: ValidateOptions): Issue[];
+
+interface ValidateOptions {
+  layout?: 'strict' | 'adaptive';
+  assets?: Iterable<string>; // ids that will be available at render time; when given, image references are checked
+}
+
+interface Issue {
+  severity: 'error' | 'warning';
+  slide?: number; // 1-based; absent for deck-level issues
+  slot?: string;
+  message: string;
+}
+```
+
+It takes the manifest, not the loaded template, so it can run where the pptx is not available (in a browser,
+or before a job is queued). It uses exactly the same rules as the renderer.
+
+- **Errors** block rendering: unknown pattern, a required slot without a value, a value of the wrong kind, a
+  table whose rows do not match its header, a chart whose series do not match its categories, an item count
+  outside the pattern's range, an asset that was not provided.
+- **Warnings** do not: text, tables or charts over a slot's soft limits; a slot name the pattern does not have;
+  `items` on a pattern with a fixed number of items; an unknown chart `format`.
+
+All messages are listed in [troubleshooting.md](troubleshooting.md).
+
+## `extractAssets(template, deck, pptx)`
+
+```ts
+function extractAssets(template: Template, deck: DeckSpec, pptx: Uint8Array): Record<string, Uint8Array>;
+```
+
+Reads the pictures of a deck back out of a pptx that was rendered from that deck, keyed by asset id. With it,
+the deck JSON and its pptx are all you have to store between edits: generated photos are read back instead of
+being generated, and paid for, again.
+
+```ts
+const cache = new Map(Object.entries(extractAssets(template, deck, previousPptx)));
+const edited = await editDeck(template, deck, 'Shorten slide 3', { llm, images, cache });
+```
+
+Only slides that still match the deck are used. If the file was changed by hand (slides added, removed or
+reordered, or a title retyped), those slides are skipped.
+
+## Layout modes in practice
+
+```ts
+// The deck leaves out the optional "subtitle" slot.
+renderDeck(template, deck, { layout: 'strict' });   // throws: leaving this slot empty needs layout: 'adaptive'
+renderDeck(template, deck, { layout: 'adaptive' }); // renders; the subtitle shape is removed
+```
+
+Use `adaptive` unless you need a guarantee that every slide looks exactly like the template slide with
+different words.
+
+## What the output is
+
+- A `.pptx` that PowerPoint opens without a repair prompt. Output was checked by rendering in PowerPoint on
+  Windows; other programs were not tested.
+- Charts are native charts with their data in an embedded workbook.
+- Text keeps the template's formatting. Text boxes are not resized: text that is longer than its box overflows
+  it, which is why budgets exist.
+- The output has no dependency on slotdeck. It is an ordinary file.
+
+## Serving a file from a web server
+
+```ts
+app.post('/decks', async (request, response) => {
+  const deck = request.body as DeckSpec;
+  const issues = validateDeck(template.manifest, deck, { layout: 'adaptive', assets: Object.keys(assets) });
+  if (issues.some((issue) => issue.severity === 'error')) return response.status(400).json({ issues });
+  const { pptx } = renderDeck(template, deck, { assets, layout: 'adaptive' });
+  response
+    .setHeader('Content-Type', 'application/vnd.openxmlformats-officedocument.presentationml.presentation')
+    .setHeader('Content-Disposition', 'attachment; filename="deck.pptx"')
+    .send(Buffer.from(pptx));
+});
+```