slotdeck 0.1.0 → 0.1.1

package/docs/template-studio.md

@@ -0,0 +1,369 @@
+# Template studio
+
+The studio functions cover everything needed to turn a new `.pptx` into a usable template: drafting its
+manifest with a model, checking it, seeing whether its budgets hold, and changing it by hand or by instruction.
+
+```ts
+import {
+  draftManifest, checkManifest, sampleDeck, changeManifest, editManifest,
+  studioView, describeManifest, describeSlot, inspectTemplate, ROLES, PptxPackage, loadTemplate, renderDeck,
+} from 'slotdeck';
+import type { ManifestChange, SlotPatch, ChangeResult, ManifestIssue, Role, StudioView } from 'slotdeck';
+```
+
+## The workflow
+
+1. **Draft** with `draftManifest`. A model labels the shapes; the code measures everything.
+2. **Check** with `checkManifest`. It should report nothing.
+3. **Look** at a sample: `sampleDeck` then `renderDeck`, and open the file. Every slot is filled to its budget,
+   so text that overflows here will overflow in real decks, and shapes that should not be there are easy to see.
+4. **Change** what is wrong: `changeManifest` with operations, or `editManifest` with an instruction.
+5. Repeat 2 to 4 until the sample looks right. Store the manifest as JSON next to the pptx.
+
+A draft is a starting point for review, not a finished manifest. What a draft does not contain, and a person
+adds: budgets tuned by eye, derived patterns (a text-only variant, a native chart), wider rows, picture areas,
+chart colours, and alignment choices for decks that read the other way.
+
+## `draftManifest(pptx, options)`
+
+```ts
+const { manifest, skipped, issues } = await draftManifest(pptxBytes, {
+  llm,                                           // required: an LlmProvider
+  name: 'marketing',                             // optional name for the manifest; default 'template'
+  slideImage: (slide) => thumbnails.get(slide),  // optional: { mimeType, data } of a picture of slide N (1-based); may be async
+  slides: [1, 2, 5],                             // optional: only these slides; default all
+  concurrency: 4,                                // optional: slides sent to the model at once; default 4
+  onProgress: ({ done, total, slide }) => {},    // optional
+  signal,                                        // optional
+});
+// manifest: TemplateManifest
+// skipped:  [{ slide, reason }]   slides that did not become patterns, and why
+// issues:   ManifestIssue[]       what checkManifest finds in the draft
+```
+
+Model calls: one about the deck as a whole, then one per slide.
+
+What the code works out without the model:
+
+- Every shape's id, kind, position, size, font size and sample text.
+- **Frame elements**: whatever sits in the same place on many slides (a logo, a rule), and page-number, date,
+  footer and header placeholders. They are left alone and not shown to the model. (Spotting what repeats needs
+  a template of at least six slides; with fewer, only the placeholders are treated as frame.)
+- **Deck fields**: texts that appear on many slides become one value for the whole deck.
+- The reading direction, from the letters of the sample text.
+- A character budget for each text box, from its size and font size, and never less than its sample text.
+- A table's columns and rows, and how many characters fit a cell before the table leaves the slide.
+- Rows and grids of like items, from numbered slot names (`card1Heading`, `card2Heading`).
+
+What the model decides, for each slide:
+
+- Whether the slide is a reusable layout at all. A sheet of brand assets or a broken slide is skipped, with a
+  reason.
+- An id and a description for the pattern, and whether it is built around numbers.
+- A role, a name and "optional or not" for each shape.
+
+A label for a shape that is not on the slide is discarded, so the model cannot make the manifest point at
+something that does not exist.
+
+`slideImage` is optional. With it, the model sees the slide; without it, it judges from the measurements alone.
+Any PNG or JPEG of the slide works; 480 pixels wide is enough.
+
+To redo one slide after changing the pptx, call `draftManifest` with `slides: [n]` and add the pattern it
+returns to your manifest.
+
+### Roles
+
+`ROLES` lists them. A role says what a shape is for and decides the kind of slot it becomes.
+
+| Role | For | Becomes |
+| --- | --- | --- |
+| `title`, `subtitle` | The headings of the slide | Text slot |
+| `text` | A paragraph, or a short label | Text slot |
+| `list` | A bulleted or multi-line list, one paragraph per item | Text slot with `maxParagraphs` |
+| `number` | A large figure | Text slot whose budget is its sample's length |
+| `caption` | A few words under a figure, icon or picture | Text slot |
+| `photo` | A photograph to replace | Image slot, `imageKind: "photo"` |
+| `icon` | A small pictogram to replace | Image slot, `imageKind: "icon"` |
+| `graphic` | A chart, diagram or screenshot picture to replace | Image slot, `imageKind: "graphic"` |
+| `chart` | A native chart in place of a picture (not offered by the drafter; set it yourself) | Chart slot |
+| `table` | A table | Table slot |
+| `decoration` | Something drawn for the sample content, to remove from every slide made with the pattern | Slot with `empty: "drop"` |
+| `fixed` | Part of the design that stays exactly as it is | No slot |
+
+Which roles a shape can take depends on what it is: a text box can be any text role or a decoration; a picture
+can be `photo`, `icon`, `graphic`, `chart` or `decoration`; a table only `table`; a line, a group or a drawn shape
+without text only `decoration`.
+
+## `checkManifest(template)`
+
+```ts
+const issues = checkManifest(loadTemplate(pptxBytes, manifest));
+// [{ severity: 'error' | 'warning', pattern?: string, slot?: string, message: string }]
+```
+
+No model. It verifies that the manifest matches the pptx: slides and shapes exist, slots point at the right
+kind of shape, names are unique, rows are consistent. The rules are listed in
+[manifest-format.md](manifest-format.md). Run it when a template is loaded, so a template that someone changed
+shows up there and not in the middle of a render.
+
+## `sampleDeck(template, options?)`
+
+```ts
+const { deck, assets } = sampleDeck(template, { fill: 0.95, items: 'max' });
+const { pptx } = renderDeck(template, deck, { assets, layout: 'adaptive' });
+```
+
+Builds a deck that uses every pattern once and fills every slot close to its limit, with the template's own
+filler words and plain coloured rectangles for pictures.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `fill` | `0.95` | How full to make each text slot, as a share of its budget. |
+| `items` | `'drawn'` | For patterns with a row or grid: `'drawn'` uses the template's number, `'max'` the most allowed, `'min'` the fewest. |
+
+## `changeManifest(template, changes)`
+
+```ts
+const result = changeManifest(template, [
+  { op: 'setSlot', pattern: 'cover', slot: 'title', maxChars: 40 },
+  { op: 'setRepeat', pattern: 'icon-cards', max: 5 },
+]);
+// result.manifest  the new manifest; the template that was passed in is not touched
+// result.applied   [{ index, change, message }]   what was done, each with a sentence saying what is now true
+// result.rejected  [{ index, change, reason }]    what was refused, and why
+// result.issues    checkManifest on the result
+```
+
+No model. Changes are applied in order. One that cannot be made, or that would leave the manifest pointing at
+something the pptx does not have, is refused with a reason and skipped; the rest are still applied. To continue
+from the result, load it: `loadTemplate(pptxBytes, result.manifest)` or `{ pkg: template.pkg, manifest: result.manifest }`.
+
+### Operations
+
+Every change is an object with `op`. `pattern` is a pattern id, `slot` a slot name, `shape` a shape id (string).
+
+#### `setManifest`
+
+```ts
+{ op: 'setManifest', name?: string, language?: string, direction?: 'ltr' | 'rtl', alignOnDirectionChange?: 'flip' | 'keep' }
+```
+
+#### `addPattern`
+
+```ts
+{ op: 'addPattern', slide: number, id: string, description?: string }
+```
+
+Makes a slide a pattern with no content slots yet. Texts that other patterns already treat as deck fields are
+filled in as deck-field slots. Follow it with `addSlot` operations, or use `draftManifest` with `slides: [n]`
+instead to get a complete pattern.
+
+#### `copyPattern`
+
+```ts
+{ op: 'copyPattern', pattern: string, id: string, description?: string }
+```
+
+A second pattern from the same slide, to turn into a variant with further operations.
+
+#### `removePattern`
+
+```ts
+{ op: 'removePattern', pattern: string }
+```
+
+The last pattern cannot be removed.
+
+#### `setPattern`
+
+```ts
+{ op: 'setPattern', pattern: string, id?: string, description?: string, figures?: boolean }
+```
+
+`id` renames the pattern. `figures: true` offers it only for briefs that contain numbers.
+
+#### `addSlot`
+
+```ts
+{ op: 'addSlot', pattern: string, shape: string, role: Role, name?: string, optional?: boolean }
+```
+
+Makes a shape a slot in a role, with limits measured from the shape (budget from the box and font, table limits
+from the table). On a shape that already is a slot, it replaces that slot, keeping its name unless `name` is
+given: this is how a role is changed. Role `fixed` removes the slot. `name` defaults to the role.
+
+#### `removeSlot`
+
+```ts
+{ op: 'removeSlot', pattern: string, slot: string }
+```
+
+The shape goes back to being part of the design.
+
+#### `setSlot`
+
+```ts
+{ op: 'setSlot', pattern: string, slot: string, ...SlotPatch }
+```
+
+`SlotPatch` properties (all optional; `null` clears an optional setting):
+
+| Property | Applies to | Meaning |
+| --- | --- | --- |
+| `name` | any | Renames the slot. |
+| `description` | any | Guidance for the planning model. |
+| `empty` | any | `error` (required), `remove` (optional), `keep`, `drop`. |
+| `maxChars`, `maxParagraphs` | text | Budgets. |
+| `deckField` | text | Ties the text to a deck-level field. |
+| `alignOnDirectionChange` | text | `flip` or `keep` for this slot. |
+| `styleRun` | text | `first` or `last`. |
+| `fontSize` | text | A font size in points other than the template's. |
+| `paragraphGap` | text | Space after each paragraph, in points. |
+| `scales` | text | Whether a deck's text size applies. |
+| `box` | text, image, chart | Another area for the shape: `{ x, y, w, h }` as fractions of the slide. |
+| `imageKind`, `fit` | image | `photo`, `icon` or `graphic`; `cover` or `contain`. |
+| `maxColumns`, `maxRows`, `maxCellChars` | table | Limits. |
+| `headerText`, `bodyText` | table | `{ size?, bold?, color?, font? }`, merged into what is already set. |
+| `maxCategories`, `maxSeries`, `colors`, `text`, `lineColor` | chart | Limits and styling. |
+
+A property that does not apply to the slot's kind is refused (`"title" is a text slot; maxColumns does not apply to it`).
+
+#### `setRepeat`
+
+```ts
+{ op: 'setRepeat', pattern: string, min?: number, max?: number, item?: string, span?: { left: number, right: number } | null }
+```
+
+Sets how many items a row or grid takes. When the pattern has no row yet, it is found from numbered slot names:
+name the slots of each item alike with a number (`card1Heading`, `card1Text`, `card2Heading`, `card2Text`) and
+they become a row.
+
+#### `removeRepeat`
+
+```ts
+{ op: 'removeRepeat', pattern: string }
+```
+
+The items stop being a row whose number can change.
+
+### What the code adds to each change
+
+- **Budgets follow.** After a new `fontSize` or `box` on a text slot, or a new text size, column count or row
+  count on a table, the character budget is worked out again, unless the same change states one. The message
+  says so: `maxChars follows at 324`.
+- **Rows are checked for room.** Asking for more items than the row draws widens the row as far as the slide
+  allows: out to the slide's margin, or to the next shape beside the row. Asking for more than fit is refused
+  with the most that do: `5 cards do not fit side by side: each is 21% of the slide wide and the row has 93%. The most is 4`.
+- **Row items stay alike.** A `setSlot` on one item's slot (`card1Icon`) is made to that slot of every item.
+  Slots of a row cannot be renamed, moved or removed one by one; remove the row first.
+- **Nothing is left broken.** After each change the manifest is checked against the pptx. A change that
+  introduces a new error is refused.
+
+### Recipes
+
+The pattern ids, slot names and shape ids below are those of the demo template in the package's repository;
+with your template, use your own.
+
+Remove a shape from every slide made with a pattern (a sticker, a stray page number, an ornament):
+
+```ts
+{ op: 'addSlot', pattern: 'quote', shape: '5', role: 'decoration' }
+```
+
+A native chart in place of a sample chart picture, as a second pattern:
+
+```ts
+[
+  { op: 'copyPattern', pattern: 'chart-with-takeaway', id: 'chart-native', description: 'A native, editable chart with a short explanation.' },
+  { op: 'addSlot', pattern: 'chart-native', shape: '6', role: 'chart', name: 'chart' },
+  { op: 'setSlot', pattern: 'chart-native', slot: 'chart', colors: ['0E7C7B', 'F4A259'], text: { size: 12, color: '5C6B73' } },
+]
+```
+
+A text-only slide from a slide with a photo:
+
+```ts
+[
+  { op: 'copyPattern', pattern: 'text-and-photo', id: 'text-only' },
+  { op: 'addSlot', pattern: 'text-only', shape: '2', role: 'decoration' },              // the photo
+  { op: 'setSlot', pattern: 'text-only', slot: 'body', box: { x: 0.04, y: 0.49, w: 0.72, h: 0.39 }, fontSize: 20, maxParagraphs: 3 },
+]
+```
+
+Smaller table text and fewer columns (the cell budget is measured for you):
+
+```ts
+{ op: 'setSlot', pattern: 'table', slot: 'table', maxColumns: 5, bodyText: { size: 9 }, headerText: { size: 10, bold: true } }
+```
+
+Mirror alignment for right-to-left decks, but keep the line beside the logo where it is:
+
+```ts
+[
+  { op: 'setManifest', alignOnDirectionChange: 'flip' },
+  { op: 'setSlot', pattern: 'cover', slot: 'organizationDepartment', alignOnDirectionChange: 'keep' },
+]
+```
+
+## `editManifest(template, instruction, options)`
+
+```ts
+const result = await editManifest(template, 'Let the cards take up to six and make the subtitle optional everywhere', { llm, signal });
+// the same fields as changeManifest's result, plus:
+// result.note   what the model could not do or needs to know, in the person's language; often ''
+```
+
+The model reads the manifest next to the measured shapes of each pattern's slide and answers with operations
+for `changeManifest`. It writes no manifest itself, so its answer goes through the same checks as a change made
+by hand. One model call, and a second when some operations were refused, so the model can correct them.
+
+- Instructions can be in any language.
+- A person may refer to a slide by number or to a pattern by id.
+- The model cannot set positions: `box` and `span` exist only for changes made by hand.
+- An operation the model got wrong shows up in `rejected` with the reason; nothing of it is applied.
+
+`describeManifest(template)` returns the text the model reads: every pattern with its slots and limits, and the
+shapes of its slide that are not slots. An app can show it to its own chat model, or print it for review.
+
+## `studioView(template)`
+
+For a screen that edits a manifest by hand.
+
+```ts
+const view = studioView(template);
+// view.aspectRatio            slide width divided by height
+// view.slides[i].slide        1-based slide number
+// view.slides[i].patterns     ids of the patterns made from this slide ([] when unused)
+// view.slides[i].shapes[j]:
+//   id        the id a change names the shape by
+//   kind      'text' | 'picture' | 'shape' | 'line' | 'group' | 'table' | 'other'
+//   box       { x, y, w, h } as fractions of the slide: lay it over a picture of the slide
+//   groupId   the group the shape sits in, when it does
+//   text      sample text, when it has some
+//   fontSize  largest font size of the sample text, in points
+//   frame     true when the shape repeats across slides (logo, page number): rarely content
+//   roles     the roles addSlot accepts for this shape
+//   slots     [{ pattern, name, kind, empty, summary }] slots that point at the shape
+```
+
+A typical screen draws a picture of the slide, lays a rectangle over each shape from `box`, colours the ones
+that are slots, and on a click offers the shape's `roles` (sending `addSlot`) or the slot's settings (sending
+`setSlot`). Nothing is stored in the view: call it again after every change.
+
+`describeSlot(slot)` gives a slot in a few words, such as `text, up to 40 characters, required`.
+
+## `inspectTemplate(pkg)`
+
+```ts
+const info = inspectTemplate(PptxPackage.load(pptxBytes));
+// info.slideWidth, info.slideHeight   in EMU (914400 per inch)
+// info.defaultFontSize                points
+// info.slides[i] = { number, part, layout, shapes: ShapeInfo[] }
+```
+
+The raw list of shapes, without a manifest. `studioView` is this joined with a manifest.
+
+## Storing a manifest
+
+A manifest is plain JSON. Keep it next to the pptx it describes, and keep the two in step: if the pptx is
+edited in PowerPoint, shape ids can change, and `checkManifest` will say which slots no longer match.

package/docs/troubleshooting.md

@@ -0,0 +1,166 @@
+# Troubleshooting
+
+Every message slotdeck produces, what it means, and what to do. Then the known limits.
+
+## Setup problems
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `ERR_REQUIRE_ESM`, or `require() of ES Module` | The package is ESM only. | Use `import`. Set `"type": "module"` in your `package.json`, or use `.mjs` files, or `await import('slotdeck')` from CommonJS. |
+| `Cannot find module 'slotdeck/node'` in a bundler | `slotdeck/node` uses `node:fs` and is for Node only. | Import it only in server code. Everything else is in `slotdeck`. |
+| `Not an Office Open XML package: [Content_Types].xml is missing` | The bytes passed to `loadTemplate` are not a `.pptx` (an old `.ppt`, a PDF, an HTML error page saved as a file). | Pass the bytes of a real `.pptx`. Save a `.ppt` as `.pptx` in PowerPoint first. |
+| Types are not found | TypeScript module resolution is too old for package `exports`. | Use `"moduleResolution": "bundler"`, `"node16"` or `"nodenext"`. |
+
+## Deck errors
+
+These make `renderDeck` throw `DeckValidationError` and are returned by `validateDeck` with `severity: 'error'`.
+Each has the slide number and usually the slot name.
+
+| Message | Meaning | Fix |
+| --- | --- | --- |
+| `the deck has no slides` | `slides` is missing or empty. | Give at least one slide. |
+| `unknown pattern "x" (available: a, b, c)` | The slide names a pattern the manifest does not have. | Use one of the listed ids. |
+| `pattern "x" takes 2 to 4 cards, not 5` | `items` is outside the pattern's range. | Use a count in the range, or raise `max` in the manifest if the template has room. |
+| `this slot is required` | A required slot has no value (or an empty string), or a required deck field was not given. | Give the slot a value, or add the field to `deck.fields`. |
+| `leaving this slot empty needs layout: 'adaptive'` | An optional slot was left out in `strict` layout. | Render with `layout: 'adaptive'`, or fill the slot. |
+| `expected text` | A text slot got a picture, table or chart value. | Give a string or an array of strings. |
+| `expected an image reference such as { "asset": "id" }` | An image slot got something else. | Give `{ "asset": "<id>" }`. |
+| `expected a table such as { "header": [...], "rows": [[...]] }` | A table slot got something else. | Give a `header` array and a `rows` array of arrays. |
+| `the table has no columns` | `header` is empty. | Give at least one column heading. |
+| `row 2 has 3 cells; the table has 4 columns` | A row's length differs from the header's. | Give every row one cell per column. Use `""` for an empty cell. |
+| `expected a chart such as { "type": "column", ... }` | A chart slot got something else. | Give `type`, `categories` and `series`. |
+| `unknown chart type "x"` | `type` is not `column`, `bar`, `line` or `pie`. | Use one of the four. |
+| `the chart has no categories` / `the chart has no series` | An empty array. | Give at least one of each. |
+| `series "x" has 3 values; the chart has 4 categories` | A series' length differs from the categories'. | One value per category. |
+| `series "x" has a value that is not a number` | A value is `null`, a string that is not a number, or missing. | Give numbers. |
+| `a pie chart takes exactly one series` | A pie with several series. | Give one series, or use another type. |
+| `asset "x" was not provided` | The deck refers to a picture whose bytes were not passed. | Add it to `options.assets` under that id. With the planner, pass the same `icons` and `assets` to rendering as to planning, or use `resolveAssets`. |
+
+## Deck warnings
+
+These do not stop rendering. `renderDeck` and the planner return them.
+
+| Message | Meaning | What to do |
+| --- | --- | --- |
+| `text is 230 characters; the slot fits about 211` | Text over the slot's `maxChars`. It is rendered and may overflow its box. | Shorten the text, or raise the budget in the manifest if the sample deck shows room. |
+| `text has 5 paragraphs; the slot fits 4` | Over `maxParagraphs`. | Fewer paragraphs. |
+| `the table has 6 columns; the slot fits 5` (also rows) | Over the table's limits. The table may leave the slide. | A smaller table. |
+| `a cell is 40 characters; cells fit about 22` | A long cell makes its row taller. | Shorter cells. |
+| `the chart has 12 categories; the slot fits 8` (also series) | Over the chart's limits. Labels may crowd. | Fewer categories. |
+| `pattern "x" has no such slot; ignored` | The slide gives a slot name the pattern does not have. | Check the name against the manifest. With `items`, slots of items beyond the count are reported this way. |
+| `pattern "x" has a fixed number of items; "items" is ignored` | `items` on a pattern without a `repeat`. | Remove `items`. |
+| `chart format "x" is not known and is ignored; use "number" or "percent"` | An unknown `format`. | Use one of the two, or leave it out. |
+| `chart values not stated in the brief: 89` | (Planner only.) The model charted a number the brief does not contain. It may be invented, or worked out from the brief. | Check the number. Put the figures you want charted into the brief. |
+
+## Planner errors (`PlanError`)
+
+| Message | Meaning | Fix |
+| --- | --- | --- |
+| `No pattern of template "x" can be used: ...` | Nothing in the manifest can be filled with what was supplied. The reasons follow. | See the reasons below. |
+| `The model did not produce a usable outline: ...` | The model's answer did not have the expected shape. | Retry. If it repeats, check that your provider returns parsed JSON that follows the schema. |
+| `The plan uses patterns that cannot be filled with what was supplied: a, b` | A plan was made with icons, assets or fields that are not passed now. | Pass the same `icons`, `assets`, `fields` and `layout` to every step. |
+| `Slide 3: pattern "x" needs icons, and no icon set was supplied` | The same, for an edit. | As above. |
+
+Reasons a pattern is not offered:
+
+| Reason | Fix |
+| --- | --- |
+| `is built around numbers, and the brief gives none` | Put figures in the brief, or set `numberPatterns: 'always'`. |
+| `needs a photo, and images are turned off` | Give an `ImageProvider` or photo assets, and an `imageDensity` other than `none`. |
+| `needs icons, and no icon set was supplied` | Pass `icons`. |
+| `needs a graphic asset, and none was supplied` | Pass an asset of kind `graphic`. |
+| `needs the deck field "x"` | Add it to `brief.fields`. |
+
+## Manifest problems (`checkManifest`)
+
+| Message | Fix |
+| --- | --- |
+| `points at slide 9, but the template has 5 slides` | Correct `sourceSlide`, or the pptx lost slides. |
+| `points at shape #99, which is not on slide 1` | The shape id is wrong, or the slide was edited. List ids with `inspectTemplate` or `studioView`. |
+| `is an image slot, but shape #6 is a text box` (and similar) | The slot's kind does not match the shape. Change the kind or the shape id. |
+| `another pattern has the same id` / `another slot of the pattern has the same name` | Rename one. |
+| `has a box, but its shape is inside a group` | A `box` only works for a shape placed directly on the slide. Remove the `box`, or ungroup in the template. |
+| `is a chart slot, but its shape is inside a group` | A native chart cannot replace a picture inside a group. Ungroup in the template. |
+| `repeat expects a slot named "card1Text"` | A row's name template has no matching slot for one of the drawn items. Add the slot or correct the template name. |
+| `repeat item 2 points at shape #77, which is not on slide 4` | Correct the shape ids in `repeat.shapes`. |
+| `repeat items must all sit directly on the slide, or all in the same group` | Items in different groups cannot be laid out together. |
+| `repeat range 3 to 2 is not valid` | `min` must be at least 1 and not more than `max`. |
+| warning: `has no character budget, so nothing stops text that does not fit` | Add `maxChars`. |
+| warning: `points at the same shape as "x"` | Two slots on one shape: usually a mistake. |
+| warning: `a grid cannot hold more items than it draws` | Lower `max` to the number drawn. |
+
+## Refusals from `changeManifest`
+
+`rejected[i].reason` is one of the manifest messages above, or one of these:
+
+| Reason | Meaning |
+| --- | --- |
+| `there is no pattern "x"` / `"p" has no slot "x"` / `slide 4 has no shape #99` | The change names something that does not exist. |
+| `5 cards do not fit side by side: each is 21% of the slide wide and the row has 93%. The most is 4` | The row cannot hold that many. Use the stated maximum. |
+| `a grid holds at most the 6 cards it draws; 8 would need a new line of them` | A grid's `max` is the number drawn. |
+| `"title" is a text slot; maxColumns does not apply to it` | A setting for another kind of slot. |
+| `maxChars must be a whole number of 1 or more` | A budget of zero, a fraction or a negative number. |
+| `"card1Text" is part of the row of cards, so it cannot be renamed, moved or tied to a deck field; remove the row first` | Row slots must stay alike. Use `removeRepeat` first if you really need to. |
+| `shape #4 is a picture; it can be photo, icon, graphic, chart, decoration` | The role does not suit the shape. |
+| `"x" has no row of like items. Name the slots of each item alike with a number ...` | `setRepeat` found no numbered slots to make a row from. |
+| `another pattern is already called "x"` | Choose another id. |
+| `a template needs at least one pattern` | The last pattern cannot be removed. |
+
+## Rendering errors that are not about the deck
+
+Plain `Error`s from `renderDeck`. They mean the manifest and the pptx disagree, or a picture is not usable.
+`checkManifest` catches the first group ahead of time.
+
+| Message | Fix |
+| --- | --- |
+| `Pattern "x": slot "y" points at shape #12, which is not on template slide 3` | Fix the manifest (see above). |
+| `Pattern "x" points at slide 9, but the template has 5 slides` | Fix `sourceSlide`. |
+| `Unsupported image format: expected PNG, JPEG or GIF` | Convert the picture (WebP, SVG, HEIC and others are not supported). |
+| `sample tables with merged cells are not supported` | The template's sample table has merged cells. Unmerge them in the template. |
+| `a chart slot must point at a shape that is not inside a group` | Ungroup the sample picture in the template. |
+
+## Gemini adapter errors (`GeminiError`)
+
+| Message | Meaning |
+| --- | --- |
+| `Gemini request failed (401): ...` | The key or token is wrong or missing. `error.status` has the HTTP status. |
+| `Gemini request failed (429): ...` | Rate limit or quota. Retry later. |
+| `Gemini request failed (400): The specified schema produces a constraint that has too many states for serving` | The service rejected a schema as too complex. This was seen during development with length limits on nested arrays, which the shipped schemas do not use. If it appears with a long deck, asking for fewer slides may help. |
+| `Gemini did not answer within 180 seconds` | The request hung. Retry, or raise `timeoutMs`. |
+| `Gemini did not return valid JSON: ...` | The model's text was not JSON. Retry. |
+| `Gemini interaction ended with status "..."` | The service did not complete the request; the reason follows when it gives one. |
+| `Gemini returned no image` | The image model answered without a picture, often because the prompt was refused. |
+
+## The result looks wrong
+
+| Observation | Likely cause | Fix |
+| --- | --- | --- |
+| Text runs out of its box or over a neighbour | The slot's budget is too generous, or the deck ignored a budget warning. | Render `sampleDeck` to see every slot at its budget, then lower `maxChars` with `changeManifest`. |
+| A leftover sample element appears (a sticker, a second page number, a sample caption) | The shape is not a slot, so it is copied as it is. | Mark it as a decoration: `{ op: 'addSlot', pattern, shape, role: 'decoration' }`. |
+| A picture is cropped badly | `cover` crops to the frame. | Supply a picture closer to the frame's proportions, or set `fit: 'contain'` on the slot. |
+| Cards are in reverse order in a right-to-left deck | The pattern's items are not declared as a row. | Add a `repeat` (`setRepeat`) or `sequences`. |
+| Hebrew or Arabic text is left-aligned | The manifest keeps alignment. | Set `alignOnDirectionChange: 'flip'` on the manifest or the slot. |
+| A font changes for another script | The template's font lacks that script. | Set a complex-script font in the template. |
+| The planner never uses a pattern | It is not offered. | See "Reasons a pattern is not offered". Also check the pattern's `description`: the model chooses by it. |
+| A slide states a number or contact detail that nobody gave | The model invented it. | Figures are guarded only for patterns marked `figures` and for charts. State details in the brief and review the deck. |
+
+## Known limits
+
+- **Shapes need their own position.** The engine measures the shapes on a slide. A shape that takes its position
+  and font size from a layout placeholder, without stating them on the slide, is filled correctly but measured
+  as empty: a drafted budget for it is only as long as its sample text, and `box` cannot be applied to it. Decks
+  exported from Google Slides and decks built from free-standing text boxes work as they are.
+- **Budgets are estimates.** A character budget cannot see lines lost to wrapping. Leave room in budgets for
+  slots with several paragraphs.
+- **Text boxes do not resize.** Text longer than its box overflows.
+- **Charts:** `column`, `bar`, `line` and `pie` only. No stacked or combined charts.
+- **Tables:** the sample table must not have merged cells.
+- **Pictures:** PNG, JPEG and GIF only.
+- **Not carried over from the template:** speaker notes, named sections and revision history.
+- **Animations** on template slides were not tested. A slide whose animated shape is removed may make PowerPoint
+  offer to repair the file; use templates without animations, or keep animated shapes out of optional slots.
+- **Not read back:** changes made to a rendered file in PowerPoint. The deck JSON is the source of truth.
+- **Not possible:** swapping the side of a photo; positioning a shape from a deck.
+- **What was tested.** Output was checked by rendering in PowerPoint on Windows. Other programs that open pptx
+  files were not tested. The Gemini adapters were run against the Gemini Developer API; the Vertex AI endpoint
+  is supported but was not run live.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slotdeck",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Turn a PowerPoint template into new decks: a model plans the slides, the code clones the template's own slides and fills them.",
   "keywords": [
     "pptx",
@@ -43,7 +43,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs/*.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",