slotdeck 0.1.2 → 0.2.0

package/docs/changelog.md

@@ -3,6 +3,141 @@
 What changed in each version, newest first, with what to do when upgrading. The version you have installed is
 in `node_modules/slotdeck/package.json`.
 
+## 0.2.0
+
+Two groups of additions. The first is about seeing and checking a deck: text measured with the template's
+fonts, pictures of slides without PowerPoint, and design checks. The second is about more layouts from the
+same template: variants the studio derives by itself, rows that fill their line, and other layouts for a
+slide. Everything new is off until it is asked for.
+
+### Added
+
+- **Text is measured with the template's fonts.** Load a template with font metrics
+  (`loadTemplate(pptx, manifest, { fonts })`) and text is broken into lines at each slot's typeface and size,
+  the way PowerPoint sets it. Validation and `renderDeck` then warn by the lines a text runs over
+  (`text takes 7 lines at 18 pt; the box holds 5 (2 lines too many). Text of about 290 characters fits.`), and
+  the planner sends a draft back to the model with that sentence. On the demo template every line broke at
+  the same word as in PowerPoint in all 1,153 text slots checked at the designed sizes, in English and in
+  Hebrew, and 699 of 700 slots had PowerPoint's line count with every font size halved. See
+  [text-fit.md](text-fit.md).
+- **`fontkitMetrics(fontkit, files)`** builds the metrics from font files with the `fontkit` library, which
+  you install yourself: slotdeck does not depend on it. `FontMetrics` is the small interface behind it, for
+  using another library.
+- **`templateFonts(template)`** lists the typefaces, weights and slants a template's text is set in, and
+  **`fontFiles(fontkit, folder, typefaces)`** from `slotdeck/node` finds their files in a font folder.
+- **Shrinking text to fit.** `shrinkText: { to: 0.85, minSize: 10 }` on the manifest lets text that does not
+  fit be set smaller, in half points, down to the stated limit. `renderDeck` returns what it shrank in `shrunk`.
+- **`textMeasurer(template)`** measures any text in any text slot: lines, capacity, overflow, the lines
+  themselves. `validateDeck` takes it as the `measure` option.
+- **`measuredBudgets(template)`** says how many characters each text slot's box really holds and suggests a
+  budget, to set with `changeManifest`.
+- **`checkManifest`** tries every text budget out when the template has fonts, and warns about a budget that
+  lets text run over its box. It also names typefaces that were not supplied.
+- **`sampleDeck(template, { fit: 'box' })`** fills every text slot to what its box holds by measurement.
+- **Slide previews.** `PreviewProvider` is a new interface for a renderer that turns a pptx into one picture
+  for each slide. slotdeck draws nothing itself and depends on no renderer. `pagusPreviews(core, renderer)` is
+  an adapter for the Pagus library, which you install yourself; it gives SVG for a browser to show, with
+  Hebrew and Arabic paragraphs marked right to left. `previewDeck` renders a deck and draws it,
+  `patternPreviews` makes a thumbnail for every pattern of a template, and `presentationTools` takes a
+  `preview` option: the pictures of every presentation it makes go to the store under `preview/<id>/` and to
+  the app in `ToolResult.previews`. No renderer tried reproduces PowerPoint exactly; what was found, for
+  English, Hebrew, tables and native charts, is in [preview.md](preview.md).
+- **Design checks.** `checkDesign(template, deck)` lists problems of a deck that fits and still looks wrong,
+  from measurement alone: a box left almost empty, a card far shorter than its neighbours, a heading that ends
+  with one word on a line of its own. Every message says what length of text would put it right. See
+  [design-checks.md](design-checks.md).
+- **Reviews.** The planner takes a `review` option: a second look at every draft, whose findings go back to
+  the writing model in the repair rounds. `designReview(template)` is the design checks as a review.
+  `visionReview({ template, llm, preview })` shows a model pictures of the slides; it needs a preview provider
+  that gives bitmap pictures, and it has been tested with a scripted model only, not run against a live one.
+  Nothing reviews a draft unless `review` is set. `presentationTools` takes the same option.
+- **Variants the studio derives by itself.** A new `changeManifest` operation,
+  `{ op: 'derivePattern', pattern, variant }`, makes a second pattern from a pattern's slide and works out every
+  position and budget from the shapes of the slide. Variants: `mirror` (the picture and what sits beside it
+  change sides, including a photo that runs off the edge of the slide), `text-only` (the picture is left out
+  and the text widens over the room it leaves) and `without` (an optional text named in `slot` is left out and
+  what sits under it moves up). A variant the slide does not allow is refused with the reason. See "Variants
+  the code works out" in [layout-freedom.md](layout-freedom.md) and `derivePattern` in
+  [template-studio.md](template-studio.md).
+- **`editManifest` understands requests for a variant**, such as "add a mirrored version of the photo slides".
+  The model names the variant; it still never sets a position.
+- **`patternVariants(template, pattern)`** lists the variants a pattern allows, with the reason for each one it
+  does not, for a studio screen that offers them as buttons. `VARIANTS` is the list of variant names.
+- **`variants` on `draftManifest`** adds the mirror image and the text-only version of every drafted pattern
+  that allows one. Off by default: see "Variants in a draft" in [template-studio.md](template-studio.md).
+- **A slot can show a part of the design in another place.** A slot with `"empty": "keep"` and a `box` keeps
+  its shape's content and puts the shape at the box, and may point at any shape that is not inside a group,
+  a group as a whole included. `derivePattern` adds such slots (`moved1`, `moved2`, ...) for the shapes of a
+  variant that are not slots. See [manifest-format.md](manifest-format.md).
+- **The demo template has mirrored photo patterns**: `text-and-photo-mirrored`, `photo-stat-mirrored` and
+  `list-with-photo-mirrored`, made with the new operation.
+- **Rows that fill their line.** `widen` on a `repeat` lets the items of a row or grid grow wider when a line
+  holds fewer of them than the template draws, up to the factor given (`"widen": 1.5`), so that two or three
+  cards fill a row drawn for four. Backgrounds and text boxes widen; icons, pictures and circles keep their
+  size and their side of the item, also inside a group. The character budgets of the row's texts grow with
+  the items, in validation, in what the planner shows the model, and in `sampleDeck`. Set it by hand or with
+  `changeManifest(template, [{ op: 'setRepeat', pattern: '<id>', widen: 1.5 }])`; `editManifest` understands
+  requests such as "let two cards fill the row". See "Fewer items that fill the row" in
+  [layout-freedom.md](layout-freedom.md).
+- **The demo template's `icon-cards` and `stat-cards` use `widen`**, so the example decks with three cards
+  or four figures fill their rows.
+- **`slideAlternatives(manifest, deck, slide)`** lists the other patterns that can hold what one slide of a deck
+  says and returns the slide written for each: a row of cards as a list or as columns, a slide as its mirror
+  image, a list as paragraphs. Code only: no model call, and no word is changed. A photo or an icon the new
+  pattern has no place for is reported, and so is a text that is over its new budget. The chat tools do not
+  offer it yet. See "Another layout for the same slide" in [layout-freedom.md](layout-freedom.md).
+
+- **Measuring follows the layout.** With fonts, the text of a row that widens its items is measured in the
+  box the renderer gives it at the slide's number of items, so validation, shrinking and the design checks
+  agree with the slide: text that fits two wide cards is accepted there and reported in four narrow ones. On
+  the demo template all 22 texts in widened cards and figures broke where PowerPoint broke them, in English
+  and in Hebrew. `checkManifest` tries the larger budgets of such a row in the wider boxes, and
+  `sampleDeck(template, { fit: 'box', items: 'min' })` fills them. A mirrored pattern, whose boxes only move
+  their shapes, is checked for empty boxes against the template's own text like the pattern it mirrors.
+
+### Changed
+
+- `renderDeck` returns `shrunk` next to `pptx` and `warnings`. It is an empty array unless the manifest has
+  `shrinkText` and the template has fonts.
+- `loadTemplate` takes a third, optional argument. `Template` has an optional `fonts` field.
+- `storeKeys` has a `preview` key builder. With a `preview` provider the outputs of `create_presentation`
+  and `edit_presentation` gain `previews`, or `preview_error` when the pictures could not be made.
+- **A slot with `"empty": "keep"` and a `box` now moves its shape.** Before, the `box` of such a slot was
+  ignored unless a deck gave the slot a value. `checkManifest` no longer reports that such a slot points at a
+  shape of another kind, or that it has no character budget.
+
+### Upgrading from 0.1.2
+
+- A dependency range written for 0.1, such as `"slotdeck": "^0.1.2"`, does not take 0.2.0. Install it by
+  version: `npm install slotdeck@0.2.0`. The package itself has no new dependency; `fontkit` and the Pagus
+  packages are installed only by an app that wants measuring or previews.
+- Nothing has to change. With a manifest made before and a template loaded without fonts, every result is the
+  same as in 0.1.2: character budgets, the same warnings, the same files. There is one exception: a manifest
+  that already had a slot with both `"empty": "keep"` and a `box` now shows that shape at the box. Remove the
+  `box` to keep the shape where the template drew it.
+- To turn measuring on: `npm install fontkit`, build metrics with `fontkitMetrics`, and pass them to
+  `loadTemplate`. Code that builds a `Template` object by hand (`{ pkg, manifest }`) keeps working; add
+  `fonts` to it to measure.
+- Once a template has fonts, a text longer than its `maxChars` that fits its box is no longer reported, and a
+  text within `maxChars` that does not fit is. Code that looks for the words `characters; the slot fits` in a
+  warning should also expect `lines`.
+- Previews are off unless you pass a `preview` provider. To turn them on with Pagus:
+  `npm install @pagus-kit/core @pagus-kit/renderer` and `pagusPreviews(pagusCore, pagusRenderer)`.
+- Design checks and reviews are off unless you call `checkDesign` or pass `review`. A review can make the
+  planner use more writing calls, since a draft within its limits may now be sent back.
+- Budgets drafted without fonts are cautious. `measuredBudgets` usually suggests larger ones; setting them
+  lets the planning model write more per slide.
+- To get mirrored layouts from your own template, run
+  `changeManifest(template, [{ op: 'derivePattern', pattern: '<id>', variant: 'mirror' }])` for each pattern with
+  a picture beside its text, render `sampleDeck` to look at the result, and store the new manifest.
+  `patternVariants(template, '<id>')` says which patterns allow it.
+- A planner that is offered a pattern and its mirror image chooses between them by their descriptions. Give
+  each a description that says where the picture is.
+- Rows and grids keep the size of their items unless the manifest opts in with `widen`, and decks made from
+  a manifest without it render byte for byte as before. After opting in, a slide with fewer items than drawn
+  looks different (its items are wider) and its text budgets are larger; text that fitted before still fits.
+  Render `sampleDeck(template, { items: 'min' })` to look at it before using the manifest.
+
 ## 0.1.2
 
 ### Added

package/docs/chat-tools.md

@@ -38,7 +38,9 @@ const tools = presentationTools({
   layout: 'adaptive',                           // optional; default 'strict'
   fields: { organizationDepartment: 'Acme  |  Operations' }, // optional deck-level values every deck gets
   numberPatterns: 'from-brief',                 // optional
+  review,                                       // optional DeckReview: a second look at every draft (design-checks.md)
   thumbnail: (patternId) => `/static/thumbnails/${patternId}.png`, // optional address of a picture of each layout
+  preview,                                      // optional PreviewProvider: draws every presentation the tools make
   newId: (kind) => `${kind}_${crypto.randomUUID()}`, // optional; default is a short random id
   onProgress: (event, tool) => console.log(tool, event.stage), // optional
 });
@@ -141,6 +143,10 @@ Output:
 
 `file` is the store key of the rendered pptx. `warnings` is present only when there are any.
 
+With the `preview` option set, the output also has `"previews"`: the store keys of the pictures of the slides,
+such as `["preview/deck_851fbb9677/slide-01.svg", ...]`. If the pictures could not be made, it has
+`"preview_error"` with the reason instead, and the presentation is created all the same.
+
 ### `edit_presentation`
 
 Arguments: `presentation_id` (string, required), `instruction` (string, required).
@@ -177,9 +183,10 @@ interface BlobStore {
 | `deck/<id>.json` | A deck: all text, and for each picture its id and description | 4 KB |
 | `asset/<id>` | One generated picture | tens of KB to 1 MB |
 | `pptx/<id>.pptx` | The rendered file | hundreds of KB and up |
+| `preview/<id>/slide-01.svg` | A picture of one slide, when the tools have a `preview` provider. The extension follows the provider: `svg`, `png` | tens of KB each |
 
-`storeKeys.plan(id)`, `storeKeys.deck(id)`, `storeKeys.asset(id)` and `storeKeys.pptx(id)` build these keys, so
-your app can read what the tools saved:
+`storeKeys.plan(id)`, `storeKeys.deck(id)`, `storeKeys.asset(id)`, `storeKeys.pptx(id)` and
+`storeKeys.preview(id, slide, extension)` build these keys, so your app can read what the tools saved:
 
 ```ts
 const pptx = await store.get(storeKeys.pptx(presentationId)); // to serve a download later
@@ -219,9 +226,19 @@ const store: BlobStore = {
 
 ## Showing a plan visually
 
-A plan lists a layout per slide. To show layouts as pictures, render the template's slides to images once (with
-any tool you have), name each picture after the pattern made from that slide, and return its address from the
-`thumbnail` option. The address is passed through to the chat model's output and is not fetched by slotdeck.
+A plan lists a layout per slide. To show layouts as pictures, make one picture for each pattern once, name it
+after the pattern, and return its address from the `thumbnail` option. The address is passed through to the
+chat model's output and is not fetched by slotdeck.
+
+`patternPreviews(template, preview)` makes those pictures without PowerPoint, through a preview provider; see
+[preview.md](preview.md). Pictures of the template's own slides from any other tool work as well.
+
+## Showing a presentation
+
+Set the `preview` option to a `PreviewProvider` and every presentation the tools create or change is drawn.
+The pictures go to the store under `preview/<presentation id>/`, their keys are in the tool's output, and the
+`ToolResult` carries the pictures themselves in `previews` for your app to show. How to get a provider, and how
+close its pictures are to PowerPoint, is in [preview.md](preview.md).
 
 ## A complete loop
 

package/docs/deck-format.md

@@ -223,3 +223,9 @@ const issues = validateDeck(manifest, deck, { layout: 'adaptive', assets: ['phot
 
 Errors make `renderDeck` throw. Warnings do not. Every message is listed in
 [troubleshooting.md](troubleshooting.md).
+
+## Another pattern for a slide
+
+`slideAlternatives(manifest, deck, slideNumber)` lists the other patterns that can hold what a slide says, and
+returns the slide written for each: cards as a list, a slide as its mirror image. It changes no words and
+calls no model. See "Another layout for the same slide" in [layout-freedom.md](layout-freedom.md).

package/docs/design-checks.md

@@ -0,0 +1,216 @@
+# Design checks and reviews
+
+Validation (`validateDeck`) says whether a deck can be rendered and whether its text fits. This page is about
+what comes after that: a deck that renders and fits can still look wrong. A body of two words in a box drawn
+for a paragraph, one short card in a row of full ones, a title whose last word sits alone on a second line.
+
+There are two tools:
+
+- **`checkDesign`** finds such problems by measurement alone. No picture is made and no model is called.
+- **A review** is a second look at each draft while a deck is being written. What it finds goes back to the
+  writing model in the same repair round as the limits the draft broke. A review can be the design checks, a
+  model that looks at pictures of the slides, or a function of your own. Nothing reviews a draft unless you ask.
+
+Both need a template loaded with its fonts: see [text-fit.md](text-fit.md).
+
+## `checkDesign(template, deck, options?)`
+
+```ts
+import { checkDesign } from 'slotdeck';
+
+const problems = checkDesign(template, deck, { layout: 'adaptive' });
+// [
+//   { severity: 'warning', slide: 1, slot: 'title', kind: 'orphan',
+//     message: 'the last of its 2 lines holds one word, "Share". Text of about 24 characters ends a line sooner; a few words more fill the line.' },
+// ]
+```
+
+It is synchronous and takes a fraction of a second for a deck. It throws when the template has no fonts.
+
+### What it finds
+
+| `kind` | Problem | Message |
+| --- | --- | --- |
+| `overflow` | Text runs over its box. The same finding, with the same words, as the warning of `validateDeck` with fonts. | `text takes 7 lines at 18 pt; the box holds 5 (2 lines too many). Text of about 290 characters fits.` |
+| `empty` | Text takes a third or less of the lines the template's own text takes in that box, so the box looks empty. | `text takes 1 line where the template's own text takes 5, so its box will look empty. Text of about 45 characters fills it as designed.` |
+| `uneven` | In a row of cards, one card's text takes a third or less of the lines of its fullest neighbour. | `text takes 1 line where "card1Text" beside it takes 5, so the row will look uneven. Text of about 66 characters or more evens it out.` |
+| `orphan` | A heading ends with one word on a line of its own. | `the last of its 2 lines holds one word, "Share". Text of about 24 characters ends a line sooner; a few words more fill the line.` |
+
+Every message says what to do about it, with a length in characters. That is what the writing model can act
+on, so a message can be sent to it as it is.
+
+### The result
+
+```ts
+interface DesignIssue {
+  severity: 'warning';
+  slide: number;   // 1-based
+  slot: string;    // the slot name as the deck uses it
+  kind: 'overflow' | 'empty' | 'uneven' | 'orphan';
+  message: string;
+}
+```
+
+A `DesignIssue` is an `Issue` with a `kind`, so the list can be shown or stored together with the warnings of
+`validateDeck` and `renderDeck`.
+
+### Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `layout` | `'strict'` | As for `renderDeck`: with `'adaptive'`, optional slots may be left out. |
+| `kinds` | all four | Which problems to look for, e.g. `['empty', 'orphan']`. |
+| `emptyBelow` | `1/3` | A text is `empty` when it takes this share or less of the lines the template's own text takes; a card is `uneven` at this share or less of its fullest neighbour. |
+| `headingSize` | `20` | The font size in points from which a single paragraph counts as a heading, for `orphan`. |
+
+### How each check decides
+
+**`overflow`.** The measured text needs more height than its box gives. If the manifest has `shrinkText`, a
+text that fits once it is set smaller is not reported.
+
+**`empty`.** The reference is the template itself: the lines its own sample text takes in the slot. A slot is
+looked at only when that is three lines or more, so a title or a one-line caption is never "empty". A slot that
+the manifest resized (`box`, `fontSize`: a derived pattern) has no sample to compare with; its box is
+then taken to be meant half full. A `box` that only moves the shape, as in a mirrored pattern, keeps the
+comparison. In a row that widens its items, the reference is the item as drawn: a short text in a wide card
+takes fewer lines, so it is reported sooner, with the length that fills the wider card. A slot fed by a deck field is not checked, because that text is the app's.
+
+**`uneven`.** The slots of one kind across a row are compared: every card's text with every other card's text,
+every heading with every heading. Rows come from the pattern's `repeat` or its `sequences`. A row is looked at
+only when its fullest item takes three lines or more. Items whose text overflows are left out of the
+comparison.
+
+**`orphan`.** A text of one paragraph, set at `headingSize` or larger, on two lines or more, whose last line
+is a single word no wider than two fifths of the widest line. An address (`name@example.org`, a web address)
+on its own line is not reported: it is meant to stand there.
+
+### What it does not see
+
+- Tables, charts and pictures. Only text slots are measured.
+- Slots set in a typeface that was not supplied. They are passed over (see `missingFonts` in
+  [text-fit.md](text-fit.md)).
+- Anything that needs a picture to judge: colours, contrast, a photo that does not suit the text.
+- Whether a line break looks good in the middle of a heading. Only the last line is looked at.
+
+On this project's hand-written example deck the checks report two things, both real: the cover title ends with
+"Share" on a second line, and the title of slide 4 with "trip". PowerPoint's own picture of the deck shows
+both.
+
+## Reviews: a second look while a deck is written
+
+The planner writes a draft, validates it, and sends a draft that breaks the template's limits back to the
+model (see "How planning works" in [generating.md](generating.md)). A review adds its own findings to that
+round.
+
+```ts
+import { designReview, planDeck } from 'slotdeck';
+
+const { deck, warnings } = await planDeck(template, brief, {
+  llm,
+  review: designReview(template), // empty boxes, uneven cards, orphan words
+});
+```
+
+The `review` option is accepted wherever a deck is written: `planDeck`, `writeDeck`, `generateDeck`,
+`planEdit`, `editDeck`, and `presentationTools`.
+
+How it works:
+
+1. After each draft, validation runs as always. If the draft has no errors, the review is called with it.
+2. What validation and the review found on the slides just written goes back to the model, each as one line:
+   `- s3.title: the last of its 2 lines holds one word, ...`.
+3. This repeats up to `maxRepairs` times (2 by default). A review therefore runs up to three times for a deck.
+4. Whatever is still found after the last round is returned in `warnings`, next to the validation warnings.
+
+A review can make the planner use more model calls: a draft that was within its limits may now be sent back.
+With `designReview` the review itself costs nothing; each repair it causes is one writing call.
+
+### `designReview(template, options?)`
+
+The code-only checks as a review. It reports `empty`, `uneven` and `orphan`; `overflow` is left to validation,
+which reports it anyway. `options` are those of `checkDesign`.
+
+### A review of your own
+
+A review is a function from a draft deck to problems:
+
+```ts
+import type { DeckReview, Issue } from 'slotdeck';
+
+const review: DeckReview = async (deck, { signal }) => {
+  const problems: Issue[] = [];
+  deck.slides.forEach((slide, index) => {
+    if (typeof slide.slots.title === 'string' && slide.slots.title.endsWith(':')) {
+      problems.push({ severity: 'warning', slide: index + 1, slot: 'title', message: 'a title must not end with a colon' });
+    }
+  });
+  return problems;
+};
+```
+
+Each problem is an `Issue`: `severity`, a 1-based `slide`, a `slot` when it is about one, and a `message`
+written for the model. A problem without a `slide`, or on a slide the model was not asked to write, is not
+sent back; it is returned in `warnings` all the same.
+
+### `visionReview(options)`: a model that looks at the slides
+
+```ts
+import { planDeck, visionReview } from 'slotdeck';
+
+const review = visionReview({
+  template,
+  llm: visionModel,   // an LlmProvider whose model can look at pictures
+  preview,            // a PreviewProvider that gives PNG or JPEG
+  icons,              // optional: the app's icons and supplied pictures, drawn as they are
+  assets,
+});
+const { deck, warnings } = await planDeck(template, brief, { llm, review });
+```
+
+For each draft it:
+
+1. renders the deck, with a plain grey rectangle for every picture that does not exist yet (photos are
+   generated after planning);
+2. asks the preview provider for a picture of each slide;
+3. shows the model the pictures, six slides to a request, with the text of each slide's slots, and asks only
+   for what can be seen and fixed by changing text: text cut off or lying over something, text too small to
+   read, a box or slide left mostly empty, a heading that ends in a lone word;
+4. returns what the model reports, each as `seen in the picture of the slide: ...`, with the slot when the
+   model named one that the slide has.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `template` | required | The template the deck is made from. |
+| `llm` | required | A provider whose model accepts pictures (`JsonRequest.images`). It can be another model than the one that writes. |
+| `preview` | required | Draws the draft. It must give bitmap pictures: PNG, JPEG, WebP or GIF. |
+| `icons`, `assets` | none | Pictures the deck may use, drawn as they are instead of as rectangles. |
+| `layout` | `'adaptive'` | As for `renderDeck`. |
+| `slidesPerRequest` | `6` | How many slides are shown to the model in one request. |
+
+Each request is capped at 300 output tokens plus 200 for each slide in it. A draft that cannot be rendered is
+not looked at: its errors are validation's to report.
+
+**Read this before turning it on.**
+
+- **It is only as good as the pictures.** A model that is shown a preview which differs from PowerPoint will
+  report problems that are not there. The Pagus adapter that comes with slotdeck gives SVG, which a model
+  cannot read, and `visionReview` refuses it with an error. Use a provider whose pictures can be trusted, such
+  as PowerPoint's own export on a machine that has it. See "How close the pictures are" in
+  [preview.md](preview.md).
+- **It has not been run against a live model, or against faithful pictures.** It was built and tested with a
+  scripted model and made-up pictures: what is sent, how the answer is read, how it takes part in the repair
+  round. How well a real model judges real slides with this prompt is not known. Try it on your own decks
+  before relying on it.
+- **It costs model calls with pictures:** one request for every six slides, for every draft, so up to three
+  times a deck with the default `maxRepairs`.
+- The code-only checks already cover overflow, empty boxes, uneven cards and orphan words, exactly and at no
+  cost. A vision review is for what measurement cannot see.
+
+### Reviews in the chat tools
+
+```ts
+const tools = presentationTools({ template, llm, store, review: designReview(template) });
+```
+
+The review then runs for every deck `create_presentation` writes and for the slides `edit_presentation`
+rewrites. What it leaves unfixed is in the tool's `warnings`.

package/docs/generating.md

@@ -50,6 +50,7 @@ It runs `planDeck`, then `resolveAssets`, then `renderDeck`.
 | `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. |
+| `review` | `DeckReview` | none | A second look at every draft: design checks, a model that looks at pictures of the slides, or a function of your own. What it finds goes back to the model in the repair rounds. See [design-checks.md](design-checks.md). |
 | `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' }`. |
@@ -88,7 +89,9 @@ const { pptx, deck, warnings } = await generateDeck(
 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.
+   over-budget text go back to the model with the list of problems. For a template loaded with fonts the
+   text is measured, and the problems are stated in lines ([text-fit.md](text-fit.md)). With a `review`, what
+   the review finds on a draft goes back in the same list ([design-checks.md](design-checks.md)).
 
 Which patterns are offered depends on what you supplied: