slotdeck 0.1.0 → 0.1.1

package/docs/generating.md

@@ -0,0 +1,218 @@
+# Generating and editing decks with a model
+
+The planner turns a brief into deck JSON by asking a language model you provide. The model never produces a
+file and never positions anything: it chooses patterns from the manifest and writes text for their slots, inside
+a JSON schema built from the manifest.
+
+```ts
+import { generateDeck, editDeck, planDeck, planOutline, editPlan, writeDeck, planEdit, resolveAssets, PlanError, DeckValidationError } from 'slotdeck';
+import type { Brief, PlanOptions, GenerateOptions, IconDef, AssetDef } from 'slotdeck';
+```
+
+All functions on this page need an `LlmProvider` (see [providers.md](providers.md)).
+
+## `generateDeck(template, brief, options)`: brief in, pptx out
+
+```ts
+const result = await generateDeck(template, brief, options);
+// result.pptx      Uint8Array   the file
+// result.deck      DeckSpec     store this: it is what gets edited and rendered again
+// result.assets    Record<string, Uint8Array>   every picture the deck uses, by asset id
+// result.warnings  Issue[]      limits the final draft still exceeds
+// result.outline   OutlineEntry[]   [{ pattern, purpose, items? }] for each slide
+```
+
+It runs `planDeck`, then `resolveAssets`, then `renderDeck`.
+
+### `Brief`
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `prompt` | string | required | What the deck is about, in the person's own words. Include every fact, figure and name that should appear: the model is told to use only what is stated. |
+| `slideCount` | number, or `{ min, max }` | 6 to 10 | A fixed number of slides, or a range. |
+| `language` | string | the template's | BCP 47 tag of the language to write in. |
+| `direction` | `"ltr"` or `"rtl"` | the language's | Reading direction. |
+| `imageDensity` | `"none"`, `"low"`, `"medium"`, `"high"` | `medium` | How many slides carry a photo: none, at most a quarter, about half, or wherever it suits. Forced to `none` by `generateDeck` when no image source and no supplied photos were given. |
+| `instructions` | string | none | Anything else to respect: audience, tone, points that must be covered. |
+| `fields` | object of strings | none | Deck-level values the template needs (see "Deck fields" in [deck-format.md](deck-format.md)). A pattern that needs a field that is not given is not offered. |
+| `textSize` | `"normal"`, `"large"`, `"x-large"` | `normal` | Size of body text. Larger text gets smaller budgets, so less is written. |
+
+### Options (`GenerateOptions`)
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `llm` | `LlmProvider` | required | The text model. |
+| `images` | `ImageProvider` | none | Makes photos from descriptions. Without it, decks are planned with no generated photos. |
+| `icons` | `IconDef[]` | none | Your icon set: `{ id, description, data }`. Patterns with icon slots are offered only when this is given. The model picks icons by `description`, so describe what each shows and what it stands for ("a clock: time, schedule"). |
+| `assets` | `AssetDef[]` | none | Pictures you already have: `{ id, kind: 'photo' | 'graphic', description, data }`. The model decides where each fits from its description. |
+| `layout` | `"strict"` or `"adaptive"` | `strict` | Whether optional slots may be left out. |
+| `patterns` | string[] | all | Restrict the deck to these pattern ids. |
+| `numberPatterns` | `"from-brief"`, `"always"`, `"never"` | `from-brief` | When patterns marked `figures` may be used. `from-brief` offers them only if the brief contains digits. |
+| `maxRepairs` | number | 2 | How many times a draft that breaks the template's limits is sent back to the model. |
+| `cache` | `Map<string, Uint8Array>` | none | Generated pictures by asset id. Pass the same map on later calls and pictures whose description did not change are reused. |
+| `imageConcurrency` | number | 3 | How many pictures to generate at once. |
+| `onProgress` | function | none | Called with `{ stage: 'outline' }`, `{ stage: 'write', slides }`, `{ stage: 'repair', attempt, issues }`, `{ stage: 'images', done, total }`, `{ stage: 'render' }`. |
+| `signal` | `AbortSignal` | none | Cancels the work. |
+
+### Example
+
+```ts
+const { pptx, deck, warnings } = await generateDeck(
+  template,
+  {
+    prompt: 'A deck for new adopters: why adopt a rescue dog, the first month at home, what it costs. We rehomed 286 dogs in 2023, 351 in 2024 and 412 in 2025.',
+    language: 'en',
+    slideCount: 9,
+    imageDensity: 'medium',
+    fields: { organizationDepartment: 'Harbor Street Shelter  |  Adoption team' },
+  },
+  {
+    llm,
+    images,
+    icons: [
+      { id: 'clock', description: 'a clock: time, schedule, duration', data: clockPng },
+      { id: 'heart', description: 'a heart: care, health, loyalty', data: heartPng },
+    ],
+    assets: [{ id: 'flow', kind: 'graphic', description: 'diagram of the adoption process in four steps', data: flowPng }],
+    layout: 'adaptive',
+    onProgress: (event) => console.log(event.stage),
+  },
+);
+```
+
+## How planning works
+
+1. **Outline** (one model call). The model sees every usable pattern with its description and slot limits, and
+   answers with one pattern per slide and the point each slide makes.
+2. **Write** (one model call). The model fills a JSON schema built for exactly that sequence of slides, so it
+   cannot invent patterns or slots.
+3. **Repair** (up to `maxRepairs` more calls). The draft is validated against the manifest. Errors and
+   over-budget text go back to the model with the list of problems.
+
+Which patterns are offered depends on what you supplied:
+
+| A pattern with | Is offered only when |
+| --- | --- |
+| a required photo slot | `imageDensity` is not `none`. `generateDeck` and the chat tools set it to `none` when there is no image source and no supplied photo. If you call `planDeck` yourself without a way to make photos, set `imageDensity: 'none'`. |
+| a required icon slot | `icons` is given |
+| a required graphic slot | `assets` has a picture of kind `graphic` |
+| a required deck field | `brief.fields` has it |
+| `figures: true` | the brief contains digits (or `numberPatterns: 'always'`) |
+
+"Required" follows the layout: in `strict` layout an optional slot (`empty: "remove"`) counts as required,
+because nothing may be removed from a slide. Slots with `empty` of `keep` or `drop` are never shown to the
+model.
+
+If nothing can be offered, `PlanError` is thrown with the reasons.
+
+### Why numbers are guarded
+
+A model given a slide built around a statistic and no data tends to invent one. So patterns marked `figures` are
+held back unless the brief itself contains figures, and chart values that the brief does not state come back as
+warnings such as `chart values not stated in the brief: 89`. Values worked out from the brief, such as a sum, are
+flagged too; treat the warning as a prompt to check.
+
+Contact details and names are not guarded. A model asked for a closing slide may invent an email address. State
+such details in the brief, or review the deck.
+
+## The steps on their own
+
+Use these when a person should see and approve a plan before the content is written.
+
+```ts
+// 1. Decide the slides. One call, quick, small result: the thing to show a person.
+const plan = await planOutline(template, brief, { llm, icons, layout: 'adaptive' });
+// plan = { version: 1, title, brief, slides: [{ pattern, purpose, items? }] }
+
+// 2. Change the plan by instruction. One call. Returns a new plan and one sentence on what changed.
+const { plan: revised, summary } = await editPlan(template, plan, 'Add a slide about pricing before the end', { llm, icons, layout: 'adaptive' });
+
+// 3. Write the content. One call plus repairs.
+const { deck, warnings, outline } = await writeDeck(template, revised, { llm, icons, layout: 'adaptive' });
+
+// 4. Pictures and file.
+const assets = await resolveAssets(template, deck, { images, icons, assets: supplied });
+const { pptx } = renderDeck(template, deck, { assets, layout: 'adaptive' });
+```
+
+`planDeck(template, brief, options)` is steps 1 and 3 in one call and returns `{ deck, warnings, outline }`.
+
+Pass the same `icons`, `assets` and `layout` to every step: the plan was made on the assumption that they are
+available.
+
+### `resolveAssets(template, deck, options?)`
+
+Collects the bytes of every picture a deck refers to: supplied icons and assets as they are, described pictures
+from `cache` or from `images`. Returns a map from asset id to bytes, ready for `renderDeck`.
+
+| Option | Meaning |
+| --- | --- |
+| `images` | The `ImageProvider` that makes described pictures. |
+| `icons`, `assets` | The same sets the deck was planned with. |
+| `cache` | A `Map` of pictures already made. New ones are added to it. |
+| `concurrency` | How many to generate at once (default 3). |
+| `onProgress`, `signal` | As above. |
+
+The image provider is asked for a picture with the aspect ratio of the frame it goes into.
+
+## Editing a deck
+
+```ts
+const edited = await editDeck(template, deck, 'Shorten slide 3 to two bullets and translate the deck to Hebrew', {
+  llm,
+  images,
+  icons,
+  assets,
+  cache, // pictures of the earlier version; see extractAssets in rendering.md
+  layout: 'adaptive',
+});
+// edited.deck       the new deck
+// edited.pptx       the new file
+// edited.assets     its pictures
+// edited.summary    one sentence from the model on what it changed
+// edited.rewritten  numbers of the slides in the new deck that were written or rewritten
+// edited.warnings
+```
+
+An edit is two model calls. The first decides what the deck looks like after the change: which slides stay,
+move, go, get rewritten or are new. The second writes only the slides that change. Reordering and deleting need
+no second call.
+
+- Slides the instruction does not touch are copied by code, so their text cannot drift.
+- A rewritten slide keeps its pictures unless the instruction is about them.
+- A slide given a different pattern takes its photo along.
+- A change of language rewrites every slide, sets the reading direction and translates deck-level fields.
+- "Make the text larger" sets `textScale` and rewrites only the slides whose text no longer fits.
+- "Use three cards instead of four" changes `items` on that slide.
+
+`planEdit(template, deck, instruction, options)` does the same without pictures or rendering and returns
+`{ deck, summary, rewritten, warnings }`.
+
+Extra options for edits (`EditOptions`):
+
+| Option | Meaning |
+| --- | --- |
+| `fields` | Replaces the deck-level values, for example a translated header text. Defaults to the deck's own. |
+| `direction` | Reading direction after the edit. Defaults to the direction of the deck's language. |
+| `imageDensity` | Whether slides added by the edit may use photo patterns. Default `medium`. |
+
+Changes made by hand in PowerPoint are not read back. The deck JSON is the source of truth.
+
+## Errors
+
+| Error | When | What to do |
+| --- | --- | --- |
+| `PlanError` | No pattern can be used with what was supplied; or the model's outline or edit plan is unusable; or the plan uses patterns that cannot be filled | Read the message: it names the patterns and reasons. Supply the missing icons, fields or images, or retry. |
+| `DeckValidationError` | After all repairs the draft still has error-level issues | `error.issues` lists them. Retry, raise `maxRepairs`, or simplify the brief. |
+| Anything your provider throws | The model call failed | Handled by you: slotdeck does not retry model calls. |
+
+Warnings (text a little over a budget, for instance) do not throw. They are returned with the result.
+
+## Cost and time
+
+For one deck: two text calls, more if repairs are needed, and one image call per generated photo. On the demo
+template with `gemini-3.8-flash`, a nine-slide deck took about 50 seconds including four pictures. An edit that
+rewrites one slide took about 15 seconds.
+
+To keep cost down: reuse `cache` across calls, set `imageDensity: 'low'` or `'none'`, and use `planOutline`
+first so a person can correct the plan before content and pictures are produced.

package/docs/getting-started.md

@@ -0,0 +1,139 @@
+# Getting started
+
+## Install
+
+```bash
+npm install slotdeck
+```
+
+- Node 22.18 or later.
+- ESM only. Your `package.json` needs `"type": "module"`, or your files need the `.mjs` extension (or you use
+  TypeScript with ESM output).
+- Two runtime dependencies come with it: `fflate` (zip) and `@xmldom/xmldom` (XML). There is no native code
+  and no office program involved.
+
+## What you need
+
+| Thing | What it is | Where it comes from |
+| --- | --- | --- |
+| Template | A `.pptx` file with sample slides | Your designer, or your organization's standard deck |
+| Manifest | JSON describing the template | Written once per template: by `draftManifest` (see [template-studio.md](template-studio.md)) or by hand (see [manifest-format.md](manifest-format.md)) |
+| Deck | JSON describing one new presentation | Written by your code, or by a model through `generateDeck` |
+| Assets | Picture bytes by id | Your icon set, your own pictures, or an image source you plug in |
+
+## 1. Render a deck from JSON (no model)
+
+```ts
+import { readFileSync, writeFileSync } from 'node:fs';
+import { loadTemplate, renderDeck } from 'slotdeck';
+import type { DeckSpec, TemplateManifest } from 'slotdeck';
+
+const manifest = JSON.parse(readFileSync('template.manifest.json', 'utf8')) as TemplateManifest;
+const template = loadTemplate(readFileSync('template.pptx'), manifest); // do this once and keep it
+
+const deck: DeckSpec = {
+  version: 1,
+  title: 'Quarterly review',
+  fields: { organizationDepartment: 'Acme  |  Operations' },
+  slides: [
+    { pattern: 'cover', slots: { title: 'Quarterly review', subtitle: 'What changed since March' } },
+    {
+      pattern: 'text-and-photo',
+      slots: {
+        title: 'Deliveries are faster',
+        body: ['Median delivery time fell from four days to three.', 'The new depot explains most of it.'],
+        photo: { asset: 'depot', alt: 'The new depot' },
+      },
+    },
+    { pattern: 'closing', slots: { title: 'Thank you' } },
+  ],
+};
+
+const { pptx, warnings } = renderDeck(template, deck, {
+  assets: { depot: readFileSync('depot.jpg') },
+  layout: 'adaptive', // optional slots that the deck leaves out are removed from the slide
+});
+for (const warning of warnings) console.log(`slide ${warning.slide} ${warning.slot ?? ''}: ${warning.message}`);
+writeFileSync('review.pptx', pptx);
+```
+
+The pattern ids (`cover`, `text-and-photo`, `closing`) and slot names (`title`, `body`, `photo`) are whatever
+the manifest defines. To list them:
+
+```ts
+for (const pattern of manifest.patterns) {
+  console.log(pattern.id, '-', pattern.description);
+  for (const slot of pattern.slots) console.log('   ', slot.name, slot.kind, slot.empty ?? 'required');
+}
+```
+
+If the deck does not fit the manifest (unknown pattern, a required slot without a value, a picture whose
+asset was not passed), `renderDeck` throws a `DeckValidationError` whose `issues` array says what is wrong. Call
+`validateDeck` first if you want the list without an exception. See [rendering.md](rendering.md).
+
+## 2. Generate a deck with a language model
+
+```ts
+import { generateDeck, loadTemplate } from 'slotdeck';
+import type { LlmProvider } from 'slotdeck';
+
+// Any model works: the only requirement is this one method. See providers.md.
+const llm: LlmProvider = {
+  async generateJson({ system, prompt, schema }) {
+    return await myModel.completeAsJson({ system, prompt, schema }); // must resolve with a parsed JSON value
+  },
+};
+
+const { pptx, deck, warnings, outline } = await generateDeck(
+  template,
+  {
+    prompt: 'Quarterly review for the operations team: deliveries got faster, returns fell, two depots opened.',
+    slideCount: 6,
+    imageDensity: 'none', // no image source was given, so plan without photos
+    fields: { organizationDepartment: 'Acme  |  Operations' },
+  },
+  { llm, layout: 'adaptive' },
+);
+```
+
+Keep the returned `deck`: it is what you store, show, edit and render again. See [generating.md](generating.md).
+
+With the included Gemini adapter instead of your own provider:
+
+```ts
+import { gemini, geminiImages } from 'slotdeck';
+
+const llm = gemini({ model: 'gemini-3.8-flash', apiKey: process.env.GEMINI_API_KEY });
+const images = geminiImages({ model: 'gemini-3.1-flash-image', apiKey: process.env.GEMINI_API_KEY });
+```
+
+## 3. Change a deck by instruction
+
+```ts
+import { editDeck } from 'slotdeck';
+
+const edited = await editDeck(template, deck, 'Shorten slide 2 and add a slide about returns before the end', { llm });
+// edited.deck, edited.pptx, edited.summary, edited.rewritten
+```
+
+## 4. Describe a new template
+
+```ts
+import { checkManifest, draftManifest, loadTemplate, renderDeck, sampleDeck } from 'slotdeck';
+
+const { manifest, skipped, issues } = await draftManifest(readFileSync('new-template.pptx'), { llm, name: 'new-template' });
+const draft = loadTemplate(readFileSync('new-template.pptx'), manifest);
+console.log(checkManifest(draft)); // [] when the manifest matches the file
+
+// A deck that uses every pattern once with every slot full: render it and look at it.
+const { deck: sample, assets } = sampleDeck(draft);
+writeFileSync('sample.pptx', renderDeck(draft, sample, { assets }).pptx);
+```
+
+A drafted manifest is a starting point that a person reviews. See [template-studio.md](template-studio.md).
+
+## Where to go next
+
+- The two JSON formats: [deck-format.md](deck-format.md), [manifest-format.md](manifest-format.md)
+- Using it inside a chat assistant: [chat-tools.md](chat-tools.md)
+- Connecting an internal model gateway: [providers.md](providers.md)

package/docs/languages.md

@@ -0,0 +1,83 @@
+# Languages and reading direction
+
+A template is designed for one reading direction (`direction` in the manifest: `ltr` or `rtl`). A deck states
+its own (`direction` in the deck, defaulting to the template's). When they differ, the text flips and the layout
+stays.
+
+This works both ways: a Hebrew or Arabic deck on a left-to-right template, and an English deck on a
+right-to-left template.
+
+## Setting language and direction
+
+In a deck:
+
+```json
+{ "version": 1, "language": "he", "direction": "rtl", "slides": [ ... ] }
+```
+
+In a brief for the planner, `language` is enough: the direction follows from it.
+
+```ts
+await generateDeck(template, { prompt: '...', language: 'he' }, options);
+```
+
+`directionOf('he')` returns `'rtl'`; `directionOf('en')` returns `'ltr'`.
+
+## What changes in a deck that reads the other way
+
+| Thing | What happens |
+| --- | --- |
+| Paragraph direction | Every paragraph gets the direction of its own text, from its first letter. A Hebrew deck may hold an English line, and that line is left to right. Text with no letters ("78%") keeps the template paragraph's direction. |
+| Alignment | Left and right alignment are swapped (`alignOnDirectionChange: "flip"`, the default). A paragraph that states no alignment counts as left-aligned. Centred text stays centred. |
+| Rows and grids of items | Filled mirror-wise within each line, so the deck's first item is where its readers start: at the right in a right-to-left deck. Shapes do not move; the values go to the mirrored positions. |
+| Tables | Run in the deck's direction, with text aligned to its start. |
+| Charts | Labels are set right to left. |
+| Run language | Right-to-left text is marked with a right-to-left language. |
+| Shapes | Do not move. A photo on the right stays on the right. Bullets and their indent follow the paragraph direction automatically. |
+
+## Keeping alignment
+
+Mirroring alignment suits templates whose text boxes are as wide as the area they belong to. It does not suit a
+template whose text boxes share one edge but not the other: flipped text would then start at uneven positions or
+run into a neighbouring shape.
+
+- For the whole template: `"alignOnDirectionChange": "keep"` in the manifest.
+- For one slot: `"alignOnDirectionChange": "keep"` (or `"flip"`) on that text slot.
+
+A common case for a per-slot `keep` is a line next to a logo: it should stay beside the logo in either
+direction.
+
+## Why runs are marked with a language
+
+PowerPoint decides where punctuation and spaces go by the language of the run they are in, not only by the
+paragraph's direction. In a run marked as English, the text
+
+```
+שאלות: name@example.org
+```
+
+is displayed with the colon on the far side of the address. slotdeck therefore marks right-to-left runs with a
+right-to-left language (`he-IL` for Hebrew, `ar-SA` for Arabic) unless the template already gave the run one.
+You do not need to do anything for this.
+
+## Fonts
+
+Text keeps the template's fonts. If the template's font has no glyphs for the deck's script, PowerPoint
+substitutes another font. For a template that will be used in two scripts, set a complex-script font on its text
+(in PowerPoint: the font for "complex scripts"), or choose fonts that cover both.
+
+## Mirrored item order in the deck JSON
+
+The deck always numbers items in its own reading order: `card1` is the first card for the reader. You do not
+reverse anything yourself. Validation messages name the slot as the deck wrote it.
+
+## Language of generated text
+
+The planner writes in `brief.language`. Slot names and pattern ids stay as the manifest defines them (they are
+identifiers, not content). Translating an existing deck is an edit:
+
+```ts
+await editDeck(template, deck, 'Translate the deck to English', { llm });
+```
+
+This rewrites every slide, sets the direction, and translates deck-level fields.

package/docs/layout-freedom.md

@@ -0,0 +1,113 @@
+# Layout freedom
+
+A deck can depart from the template slide in four bounded ways. In each, the choice is a small value in the deck
+JSON, the manifest says what is allowed, and the code moves the shapes. Nothing is ever positioned by a model.
+
+## 1. A different number of items
+
+A pattern with a `repeat` in the manifest has a row or grid of like items: cards, figures, steps. The deck says
+how many with `items`.
+
+Manifest:
+
+```json
+"repeat": {
+  "item": "card",
+  "slots": ["card{n}Icon", "card{n}Heading", "card{n}Text"],
+  "shapes": [["6"], ["12"], ["18"], ["24"]],
+  "min": 2,
+  "max": 4
+}
+```
+
+Deck:
+
+```json
+{ "pattern": "icon-cards", "items": 3, "slots": { "title": "...", "card1Icon": {"asset": "clock"}, "card1Heading": "...", "card1Text": "...", "card2Icon": {"asset": "shield"}, "card2Heading": "...", "card2Text": "...", "card3Icon": {"asset": "people"}, "card3Heading": "...", "card3Text": "..." } }
+```
+
+What the renderer does:
+
+- **Fewer items than drawn:** the surplus items' shapes are removed.
+- **More items than drawn:** the last item is copied. A copy's slots have the next numbers (`card5Icon`,
+  `card5Heading`, ...) and take the last drawn item's limits.
+- **Spacing:** the items are laid out again around the centre of the area the row occupied. They keep the
+  template's spacing when there is room and move closer together when there is not. With a `span`, the row may
+  spread out to those limits.
+- Without `items`, the slide has the number of items drawn on the template slide.
+
+An `items` value outside `min` to `max` is an error:
+`pattern "icon-cards" takes 2 to 4 cards, not 5`.
+
+How many items fit is a property of the template: `changeManifest` refuses a `max` that does not fit side by
+side and says the most that do (see [template-studio.md](template-studio.md)).
+
+## 2. Grids
+
+With `columns` in the `repeat`, the items form a grid. `columns` is how many items one line holds on the
+template slide.
+
+- Items fill lines in reading order and use as few lines as the count needs.
+- They are spread evenly over those lines: in a three-column grid, four items make two lines of two (not three
+  and one), five make three and two, three make one line.
+- Each line is centred, and a single line moves to the middle of the grid's area.
+- A grid cannot hold more items than it draws.
+
+## 3. Larger text
+
+A deck can ask for larger body text:
+
+```json
+{ "version": 1, "textScale": 1.25, "slides": [ ... ] }
+```
+
+or, on a brief for the planner, `textSize: 'large'` (1.25) or `'x-large'` (1.5). The named sizes are in
+`TEXT_SIZES`: `{ normal: 1, large: 1.25, 'x-large': 1.5 }`.
+
+- It applies to **body text**: by default, text slots whose template size is 12 pt or under and that are not
+  deck fields. Titles and large figures keep their size. A slot can opt in or out with `scales` in the
+  manifest.
+- Boxes do not grow, so larger text fits less. The character budget of a scaled slot is divided by the square
+  of the scale (a 300-character slot holds 192 at 1.25), and the paragraph budget by the scale. The planner
+  shows the model the reduced budgets, so it writes less.
+- Through `editDeck`, "make the text larger" sets the scale and rewrites only the slides whose text no longer
+  fits.
+
+## 4. Derived patterns
+
+Several patterns may point at the same template slide and use it differently. A derived pattern is made by
+copying a pattern and changing some of its slots:
+
+| Change | Manifest property | Example |
+| --- | --- | --- |
+| Remove a shape always | `"empty": "drop"` on a slot that points at it | A text-only slide from a slide with a photo |
+| Move or resize a text box | `box` on the text slot | Widen the text over the area the photo left free |
+| Set a font size | `fontSize` | Larger body text for a slide with little on it |
+| Space paragraphs | `paragraphGap` | Air between two or three short paragraphs |
+| Give a picture another area | `box` on the image slot | A wide diagram in place of a small sample chart |
+| A native chart in place of a picture | a `chart` slot on the picture's shape | The chart slide with editable data |
+
+Example: a text-only pattern derived from a photo pattern.
+
+```json
+{
+  "id": "text-only",
+  "sourceSlide": 2,
+  "description": "A title, an optional supporting line and two or three short paragraphs, with no picture.",
+  "slots": [
+    { "name": "photo", "kind": "image", "imageKind": "graphic", "shapeId": "2", "empty": "drop" },
+    { "name": "title", "kind": "text", "shapeId": "5", "size": 34, "maxChars": 83, "box": { "x": 0.0375, "y": 0.2, "w": 0.925, "h": 0.187 } },
+    { "name": "body", "kind": "text", "shapeId": "7", "size": 18, "maxChars": 331, "maxParagraphs": 3, "fontSize": 20, "paragraphGap": 12, "box": { "x": 0.0375, "y": 0.4933, "w": 0.72, "h": 0.3867 } }
+  ]
+}
+```
+
+With `changeManifest` this is three operations (`copyPattern`, `addSlot` with role `decoration`, `setSlot` with
+a `box`), and the budgets are worked out for you: see [template-studio.md](template-studio.md).
+
+## What is not possible
+
+- Moving a shape to an arbitrary place from a deck. Positions come only from the template and the manifest.
+- Swapping the side of a photo.
+- A grid with more items than the template slide draws.
+- New kinds of slides that the template has no sample for.