slotdeck 0.1.1 → 0.2.0

package/docs/layout-freedom.md

@@ -34,6 +34,8 @@ What the renderer does:
 - **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.
+- **Size:** every item keeps its drawn size, unless the row has `widen` (see "Fewer items that fill the row"
+  below).
 - Without `items`, the slide has the number of items drawn on the template slide.
 
 An `items` value outside `min` to `max` is an error:
@@ -42,6 +44,57 @@ An `items` value outside `min` to `max` is an error:
 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)).
 
+### Fewer items that fill the row
+
+By default an item keeps its drawn size, so three cards in a row drawn for four stand in the middle with room
+left at both ends. With `widen` on the `repeat`, a line that holds fewer items than the template draws has its
+items made wider, so that they fill the row:
+
+```json
+"repeat": {
+  "item": "card",
+  "slots": ["card{n}Icon", "card{n}Heading", "card{n}Text"],
+  "shapes": [["6"], ["12"], ["18"], ["24"]],
+  "min": 2,
+  "max": 4,
+  "widen": 2.2
+}
+```
+
+`widen` is the most an item may grow, as a factor on its drawn width: `1.5` lets a card become half as wide
+again, `2.2` lets two cards fill a row drawn for four. With `changeManifest`:
+`{ op: 'setRepeat', pattern: 'icon-cards', widen: 2.2 }`; `null` or `1` turns it off.
+
+- **How wide.** The items share the row's span (`span`, or the row as drawn) and keep the template's own gap
+  between them. Where that is more than the limit allows, they stop at the limit and the row is centred. In
+  the demo template a card is 21% of the slide wide; three become 29% each and two become 45%.
+- **What decides.** Only the number of items. Long text does not widen a card and short text does not narrow
+  one, so the same deck always looks the same.
+- **Inside an item** each shape is treated on its own, whether the item is a group or not:
+  - A background, a rule or a text box that spans the item grows with it and keeps its distance to both
+    sides. The text boxes of the row's own slots always grow.
+  - A picture or an icon keeps its size. So does a circle or any other outline that is not a rectangle, and
+    a slanted line. It keeps its distance to the nearer side of the item: an icon at the start of a card
+    stays at the start, and one in the middle stays in the middle.
+  - Rounded and cut corners keep the size they were drawn with.
+  - Heights do not change.
+- **Budgets.** A wider text box holds more. The character budget of the row's text slots grows by the factor
+  the items are at least wider by: the number drawn on a line divided by the number held, up to `widen`. In a
+  row drawn for four with `widen: 2.2`, a 117-character text holds 156 with three cards and 234 with two.
+  `validateDeck` uses these budgets, the planner gives them to the model for the number of items it chose,
+  and `sampleDeck` with `items: 'min'` fills them. Paragraph budgets do not change. A deck's text size is
+  applied on top.
+- **With fonts.** A template loaded with fonts measures the text of a widened item in its wider box, so a
+  text is reported, shrunk or called empty by the box it really gets (see [text-fit.md](text-fit.md)).
+  `checkManifest` then also tries the larger budgets out, one number of items at a time.
+- **Grids.** A grid has one item width, decided by its fullest line. In a three-column grid, four figures make
+  two lines of two, which widen; five make three and two, and keep their width.
+- **Both reading directions.** Positions come from the template: a right-to-left template with its icons at
+  the right edge of each card keeps them there. A deck that reads the other way gets the same shapes, with
+  its first item at the other end.
+- **Nothing else changes.** At the drawn number of items and above, and for every row without `widen`, the
+  output is byte for byte what it was.
+
 ## 2. Grids
 
 With `columns` in the `repeat`, the items form a grid. `columns` is how many items one line holds on the
@@ -72,6 +125,29 @@ or, on a brief for the planner, `textSize: 'large'` (1.25) or `'x-large'` (1.5).
   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.
+- Table text and chart labels follow the scale where the manifest states their size (`bodyText.size`,
+  `headerText.size`, `text.size`), and a table cell then holds less.
+
+### Larger text for a whole template
+
+The engine keeps the template's own font sizes. A template designed with small body text, such as 9 pt on a
+10-inch-wide slide, therefore gives decks with small body text. To change that once, for every deck, set
+`textScale` on the manifest:
+
+```json
+{ "version": 1, "name": "corporate", "direction": "rtl", "textScale": 1.3, "patterns": [ ... ] }
+```
+
+With `changeManifest`: `{ op: 'setManifest', textScale: 1.3 }`.
+
+- It works exactly like a deck's `textScale` and applies to the same slots (body text: 12 pt and under by
+  default), but for every deck made from the template.
+- Budgets shrink to match, in validation, in what the planner shows the model, and in `sampleDeck`: a slot
+  that held 240 characters holds 142 at 1.3. Render the sample deck after setting it to see that everything
+  still fits.
+- A deck's own text size goes on top. With a template at 1.3, a deck at `large` (1.25) shows body text at about
+  1.6 times the designed size.
+- A slot that should keep its size can opt out with `"scales": false`.
 
 ## 4. Derived patterns
 
@@ -102,12 +178,211 @@ Example: a text-only pattern derived from a photo pattern.
 }
 ```
 
-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).
+By hand, 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).
+For the three common variants below, the boxes are worked out as well.
+
+### Variants the code works out
+
+Three kinds of derived pattern need no box typed in. One `changeManifest` operation makes each, and
+`editManifest` lets a model ask for one by name:
+
+```ts
+changeManifest(template, [
+  { op: 'derivePattern', pattern: 'text-and-photo', variant: 'mirror' },      // text-and-photo-mirrored
+  { op: 'derivePattern', pattern: 'text-and-photo', variant: 'text-only' },   // text-and-photo-text-only
+  { op: 'derivePattern', pattern: 'text-and-photo', variant: 'without', slot: 'subtitle' }, // text-and-photo-no-subtitle
+]);
+```
+
+Each makes a new pattern next to its source. A deck uses it by its id like any other pattern, and the planner
+chooses it by its description; nothing changes in the deck format. `patternVariants(template, id)` says which
+variants a pattern allows before you ask.
+
+**How the shapes of a slide are sorted.** The code looks at the shapes that sit directly on the slide (a group
+counts as one shape) and puts each in one of these:
+
+| What | Which shapes | In a variant |
+| --- | --- | --- |
+| Locked | The logo, rules and other elements that repeat across the template's slides; page-number, date and footer placeholders; texts that are deck fields. | Never moved. |
+| The picture | The pattern's one photo, graphic or chart slot. Icons, pictures inside a row of items and pictures kept as decoration do not count. | Changes sides, or is left out. |
+| Beside the picture | Every shape that shares no width with the picture: titles, texts, panels. | Moves as one block, so edges the shapes share stay shared. |
+| With the picture | Shapes in the picture's own column: a sticker on it, a caption under it. | Goes where the picture goes. |
+| Around both | A title above the picture and its text, a caption under both, a background behind both. | Stays. |
+
+#### `mirror`
+
+The picture and the block beside it change sides.
+
+- They change places inside the room the two share, so the slide keeps its margins. A picture that runs off
+  one edge of the slide runs off the other edge instead, and the block keeps the margin it had.
+- Nothing changes size, so no budget changes. The block is moved, not flipped: text boxes that shared a left
+  edge still share one.
+- Locked shapes stay. When the picture would cover one near the top or the bottom of the slide (a full-height
+  photo landing on the logo), the picture is cut back to start a little under it, or end a little above it,
+  and the photo is cropped to the new frame.
+- Shapes that are not slots, and groups, are moved too. The operation adds a slot for each, named `moved1`,
+  `moved2`, ..., with `"empty": "keep"` and a `box`: the shape keeps its content and is shown at the box.
+- A mirrored pattern is a layout of its own that a deck or the planner picks. A deck's reading direction still
+  never moves a shape: a right-to-left deck made from `photo-stat` has its photo where the template drew it.
+
+In the demo template, `text-and-photo-mirrored`, `photo-stat-mirrored` and `list-with-photo-mirrored` were made
+this way.
+
+#### `text-only`
+
+The picture is left out and the text beside it widens.
+
+- The picture's slot stays under its name with `"empty": "drop"`, so its shape is always removed. Decoration
+  drawn on the picture is removed with it. Texts the deck writes are never removed.
+- Every text slot beside the picture grows towards the side the picture was on: up to the picture's far edge,
+  or, for a picture that ran off the slide, up to the margin the text keeps on its own side. All of them end
+  on the same edge.
+- The column is no wider than about 90 characters a line of the slot with the largest budget, because lines
+  that run the width of a slide are hard to read. It keeps the edge where the template's reading starts (the
+  left edge of a left-to-right template) and gives up room at the other.
+- A text stops short of any other shape that is in its way.
+- The budget of each widened text is measured again for its new width.
+- To enlarge the text of the new pattern, follow with `setSlot` and a `fontSize`; the budget follows.
+
+#### `without`
+
+One optional text is left out for good, and the room it took is used.
+
+- `slot` names the text. It must be optional (`"empty": "remove"`). In the variant it has `"empty": "drop"`.
+- The shapes under it in its column move up, so that the first of them starts where the text started.
+- The lowest text among them keeps its lower edge, so it becomes taller and its budget grows. This is done
+  only when its text starts at the top of its box; a text that is centred or sits at the bottom of its box is
+  moved and keeps its size, so that the text does not shift inside it.
+- When nothing sits under the text, the text above it is extended down to where the text ended, on the same
+  condition.
+- When there is nothing to move or extend, the variant is the same slide with the slot gone.
+
+Why make one when the slot is optional anyway: in `strict` layout an optional slot has to be filled, and in
+`adaptive` layout leaving it empty leaves its room empty. The variant closes the gap and lets the text under it
+say more.
+
+#### When a variant is refused
+
+`derivePattern` refuses, with the reason, when the slide does not allow the variant:
+
+| Reason | Example |
+| --- | --- |
+| The pattern has no picture of its own. | `"cover" has no photo, graphic or chart of its own, so there is nothing to change sides with` |
+| It has more than one. | `"gallery" has 2 pictures (photo1, photo2); this needs a slide with one picture beside its text` |
+| Nothing sits beside the picture. | A wide diagram under a title: `nothing sits beside the picture "diagramGraphic", ...` |
+| The picture has content on both of its sides. | A picture in the middle of the slide. |
+| A shape that keeps its place is where something would go. | `shape #9 ("Source: annual report"), which keeps its place, is where shape #7 would go` |
+| A row of items would have to move. | The renderer lays a row out again for every item count, so a box cannot place it. |
+| A table would have to move. | A table slot has no `box`. |
+| The text to widen is inside a group. | `the text beside the picture is inside a group, and a shape inside a group cannot take a box` |
+| The slot to leave out is not an optional text. | `"title" is required; only an optional text can be left out; "text-and-photo" has "subtitle"` |
+
+Render the sample deck after deriving a variant (`sampleDeck`, then `renderDeck`): it holds every pattern,
+variants included, filled to its budgets.
+
+## Another layout for the same slide
+
+The sections above are about what a deck may ask for. `slideAlternatives` answers another question: a slide
+already has its content; which other patterns could show it? It puts the content into every pattern that has a
+place for all of it and returns the slide written for each. It uses no model and changes no words, so an
+alternative says exactly what the slide said.
+
+```ts
+import { slideAlternatives } from 'slotdeck';
+
+const alternatives = slideAlternatives(manifest, deck, 5, { layout: 'adaptive' }); // slide 5 of the deck, counted from 1
+// [
+//   {
+//     pattern: 'text-only',
+//     description: 'A title, an optional supporting line and two or three short paragraphs, with no picture. ...',
+//     slide: { pattern: 'text-only', slots: { title: 'Three changes for next season', body: ['Longer hours: Bikes unlock ...', '...', '...'] } },
+//     changes: ['The 3 cards became a list of 3 points, each written as "heading: text".'],
+//     dropped: ['card1Icon', 'card2Icon', 'card3Icon'],
+//     warnings: [],
+//   },
+// ]
+
+deck.slides[4] = alternatives[0].slide; // take one, then validate and render as usual
+```
+
+| Field | Meaning |
+| --- | --- |
+| `pattern`, `description` | The pattern's id and what it is for, from the manifest. |
+| `slide` | The slide written for that pattern: put it in the deck in place of the original. |
+| `changes` | What was done to the content where it was not copied slot for slot, a sentence each. Empty for a plain copy. |
+| `dropped` | Slots of the original slide whose photo or icon the pattern has no place for. |
+| `warnings` | What `validateDeck` says about the new slide, such as `text is 30 characters; the slot fits about 20`. Empty when everything fits. |
+
+Options: `layout` (`'strict'` by default, as in `renderDeck`) and `patterns` (consider only these ids). The list
+is ordered: alternatives that fit and leave nothing out come first, then those that leave out a photo or
+icons, then those with a warning. A slide with no alternative gives `[]`.
+
+### How the content of a slide is read
+
+A manifest does not say what a slot is for, so the code tells from names and limits:
+
+| Part | Which slot |
+| --- | --- |
+| Title | The text slot whose name ends in `title` (`title`, `slideTitle`) and is not a subtitle. |
+| Subtitle | The text slot whose name ends in `subtitle` or `subheading`. |
+| Figure | A big, short text: a budget of at most 10 characters at 24 pt or more, such as `87%`. |
+| Body | Of the text slots that are left, the one with the largest budget. It counts as a list when it takes several paragraphs (`maxParagraphs`). |
+| Picture | The pattern's one photo or graphic outside its row. |
+| Items | The row or grid (`repeat`). In each item: an icon, a picture, a figure, and of its other texts the one with the smaller budget is the heading and the one with the larger is the text. |
+| Everything else | A takeaway, a footnote, a table, a chart. It keeps its name and fits only a slot of the same name and kind. |
+
+Deck fields and slots with `"empty": "keep"` or `"drop"` take no part.
+
+### What can become what
+
+- **The same part.** A title goes to the title, a subtitle to the subtitle, a figure to the figure, the body to
+  the body, a picture to a picture of the same kind.
+- **Variants of one slide.** Between a pattern and its mirror image, or any two patterns whose slots have the
+  same names, every value goes to the slot of the same name.
+- **Items to items.** Cards become columns, a row becomes a grid, when the target takes that many items.
+  Headings go to headings and texts to texts. Items with a heading and a text fit items with one text, written
+  `heading: text`; single texts written that way fit items with a heading and a text, split at the first colon
+  (or dash between spaces).
+- **Items to a list.** One point for each item, written `heading: text`, in a body that takes several
+  paragraphs. Each part of an item must be one paragraph.
+- **A list to items.** One item for each point, from two points up. For items with a heading and a text, only
+  when every point is written `heading: text`.
+- **A list to paragraphs and back.** The words are the same; whether they show as points is the new slot's own
+  formatting. `changes` says so.
+
+### When a pattern is an alternative
+
+- **Everything the slide says has a place**: every text, table, chart and supplied graphic. Nothing is cut and
+  nothing is run together, apart from `heading: text`.
+- **Everything the pattern requires can be filled** from the slide. In `strict` layout that includes its
+  optional slots; in `adaptive` layout those may stay empty. Code does not invent a subtitle, a heading, a
+  number, an icon or a photo, so a pattern that needs one the slide lacks is not offered.
+- **A photo or an icon may be left out**, because it illustrates. `dropped` names the slots.
+- **A figure stays a figure.** Figures do not become headings of cards, and headings do not become figures.
+- **A text that is too long for its new slot does not rule a pattern out.** It is reported in `warnings`, and
+  the alternative is listed after those that fit.
+
+### Limits
+
+- It judges what fits, not what suits. A section slide is offered for a cover, because both hold a title and
+  a subtitle. `description` is there for a person or a model to choose by.
+- The parts are told from slot names and limits. A title slot called `heading`, or an item with three texts,
+  is not recognised; such a slide still gets the alternatives whose slots have the same names.
+- It is not offered by the chat tools yet. Call it from your own code.
 
 ## 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.
+- Mirroring a slide because of a deck's reading direction. A mirrored layout is a separate pattern
+  (`derivePattern` with `mirror`) that a deck names or the planner chooses.
+- Deriving a variant that would move a row or grid of items, or a table.
+- Widening a picture inside an item, or making an item taller. A widened item keeps its height, and its
+  pictures keep their size.
+- Letting the length of the text decide the size of an item. Only the number of items does.
+- An alternative that needs words the slide does not have. `slideAlternatives` never writes text; ask a model
+  for that with `editDeck`.
+- A mirror or text-only variant of a slide with several pictures, or with a picture between two texts.
+- A `box` for a shape inside a group. A variant moves a group as a whole and never resizes what is in it.
 - A grid with more items than the template slide draws.
 - New kinds of slides that the template has no sample for.

package/docs/manifest-format.md

@@ -66,6 +66,8 @@ operations (`changeManifest`) or by instruction (`editManifest`), and verify it
 | `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. |
+| `textScale` | number | no | Enlarges the body text of every deck made from this template, as a factor on the designed size: `1.3` turns 9 pt into about 12 pt. For a template whose body text is too small to read comfortably. Budgets shrink to match. See "Larger text" in [layout-freedom.md](layout-freedom.md). |
+| `shrinkText` | `{ to, minSize? }` | no | Lets text that does not fit its box be set smaller: down to `to` of its size (`0.85` is 85%) and never under `minSize` points. Acts only for a template loaded with fonts. See "Shrinking text to fit" in [text-fit.md](text-fit.md). |
 
 ## `PatternDef`
 
@@ -91,6 +93,17 @@ operations (`changeManifest`) or by instruction (`editManifest`), and verify it
 
 Slots with `empty` of `keep` or `drop` are never offered to the planning model.
 
+A slot with `"empty": "keep"` and a `box` shows a part of the design in another place: the shape keeps its
+content and is put at the box. Such a slot may point at any shape that is not inside a group (a drawn shape,
+a line, a text, a group as a whole), with `"kind": "text"`, or `"kind": "image"` for a picture. When the box is
+the shape's own size, only its position changes, so nothing inside a group is rescaled. The `derivePattern`
+operation adds these slots, named `moved1`, `moved2`, ..., for shapes that a variant moves and that are not
+slots themselves:
+
+```json
+{ "name": "moved1", "kind": "text", "shapeId": "14", "empty": "keep", "box": { "x": 0.52, "y": 0.3, "w": 0.4, "h": 0.05 } }
+```
+
 ## Text slot (`kind: "text"`)
 
 | Field | Type | Meaning |
@@ -150,7 +163,8 @@ The shape must not be inside a group.
   "min": 2,
   "max": 4,
   "span": { "left": 0.04, "right": 0.96 },
-  "columns": 3
+  "columns": 3,
+  "widen": 1.5
 }
 ```
 
@@ -162,6 +176,7 @@ The shape must not be inside a group.
 | `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. |
+| `widen` | number | no | Lets items grow wider when a line holds fewer of them than the template draws, so that they fill the row and do not stand in the middle of it. The value is the most an item may grow, as a factor on its drawn width: `1.5` lets a card become half as wide again. Backgrounds and text boxes widen; pictures keep their size. The budgets of the row's texts grow to match. Left out, items keep their drawn size. |
 
 How the items are laid out for a given count is described in [layout-freedom.md](layout-freedom.md).
 
@@ -175,11 +190,13 @@ of item 4's slots, named with the next number.
 - 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.
+  point at any shape, because the shape is only ever removed; so may a slot with `"empty": "keep"` and a `box`,
+  because the shape is only ever moved.
 - 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`.
+  sit directly on the slide or all in the same group; `min` is at least 1 and not more than `max`; `widen`,
+  when set, is a number of 1 or more.
 
 It also warns about text slots without `maxChars` and about two slots that point at the same shape.
 

package/docs/preview.md

@@ -0,0 +1,217 @@
+# Slide previews
+
+A preview is a picture of each slide of a pptx, for showing a deck in an app without opening PowerPoint.
+
+slotdeck draws nothing itself. It has a small interface, `PreviewProvider`, that you fill with a renderer of
+your choice, and it calls that interface wherever a picture is wanted: for a deck you rendered, for the
+thumbnails of a template's patterns, and for every presentation the chat tools create.
+
+An adapter for one renderer, the Pagus library, comes with the package. Pagus is not a dependency of slotdeck:
+you install it and pass it in.
+
+**Read "How close the pictures are" below before relying on a preview.** No renderer that runs without
+PowerPoint was found to reproduce PowerPoint exactly. A preview shows what a deck looks like. To know whether
+a text fits its box, measure it: see [text-fit.md](text-fit.md).
+
+## Setup with Pagus
+
+```
+npm install @pagus-kit/core @pagus-kit/renderer
+```
+
+```ts
+import { readFileSync, writeFileSync } from 'node:fs';
+import * as pagusCore from '@pagus-kit/core';
+import * as pagusRenderer from '@pagus-kit/renderer';
+import { loadTemplate, pagusPreviews, previewDeck } from 'slotdeck';
+
+const preview = pagusPreviews(pagusCore, pagusRenderer);
+
+const template = loadTemplate(readFileSync('templates/demo.pptx'), manifest);
+const { pptx, previews } = await previewDeck(template, deck, preview, { assets });
+
+for (const picture of previews) {
+  writeFileSync(`out/slide-${picture.slide}.svg`, picture.data); // picture.mimeType is 'image/svg+xml'
+}
+```
+
+`previewDeck` is `renderDeck` followed by the provider. To draw a pptx you already have, call the provider
+directly:
+
+```ts
+const previews = await preview.renderSlides({ pptx });               // every slide
+const some = await preview.renderSlides({ pptx, slides: [1, 4] });   // 1-based slide numbers
+```
+
+A 15-slide deck takes about 0.2 seconds.
+
+### What a Pagus preview is
+
+- One SVG for each slide, 1280 pixels wide for a 13.33 inch slide (96 pixels to the inch). Shapes, pictures,
+  tables and native charts are drawn. Pictures are embedded, so each SVG stands on its own.
+- **The text is real text, set by the browser that shows the SVG.** The browser uses its own fonts and breaks
+  the lines itself. The picture therefore needs a browser to be seen, and it looks right only where the
+  template's fonts are installed, or where you supply substitutes (see the options).
+- It can be shown with `<img src="...">`, with a `data:` address, or by putting the SVG markup into the page.
+  This was checked in Chromium. Do not put the markup of several slides into one page: their internal names
+  collide. Use one `<img>` for each.
+- It cannot be turned into a PNG by an SVG library that has no HTML engine (the text is HTML inside the SVG).
+  For PNG, take a screenshot of the SVG with a headless browser, or use another provider.
+
+### Options
+
+```ts
+pagusPreviews(pagusCore, pagusRenderer, {
+  scale: 0.5,                                  // 640 pixels wide
+  fontSubstitutes: { Calibri: 'Carlito', Cambria: 'Caladea' },
+  fontCss: "@import url('/fonts/carlito.css');",
+});
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `scale` | `1` | Scale of the drawing. `1` gives 96 pixels to the inch. |
+| `fontSubstitutes` | none | For each of the template's typefaces, a typeface to fall back on where the viewer does not have it. |
+| `fontCss` | none | `@font-face` or `@import` rules to embed in each SVG, so that it brings its own fonts. A browser does not fetch fonts by address for an SVG shown through `<img>`: embed them as data in the rule, or put the markup into the page. |
+
+### Right-to-left text
+
+Pagus leaves the direction of a paragraph to the browser, which takes a paragraph to run left to right unless
+told otherwise. The adapter therefore marks every paragraph that starts with a right-to-left letter as running
+right to left, the same rule slotdeck's renderer uses when it writes the pptx. Without this, a Hebrew sentence
+gets its full stop on the wrong side and a line that mixes Hebrew with an address or a number comes out in the
+wrong order.
+
+## Thumbnails of a template's patterns
+
+```ts
+import { patternPreviews, previewExtension } from 'slotdeck';
+
+const pictures = await patternPreviews(template, preview);
+// { cover: SlidePreview, 'text-and-photo': SlidePreview, ... }  one for each pattern id
+
+for (const [id, picture] of Object.entries(pictures)) {
+  writeFileSync(`thumbnails/${id}.${previewExtension(picture)}`, picture.data);
+}
+```
+
+Each picture is the pattern's slide of the template's sample deck (`sampleDeck`), so a pattern derived from
+another pattern's template slide is shown as it will look, with sample words in its slots. The options of
+`sampleDeck` (`fill`, `items`, `fit`) can be passed as a third argument. Make the thumbnails once, when a
+template or its manifest changes, and serve them as files: they are what the `thumbnail` option of the chat
+tools points at (see [chat-tools.md](chat-tools.md)).
+
+The same call gives the studio a picture of a manifest's sample deck, to judge budgets by eye:
+
+```ts
+const { deck, assets } = sampleDeck(template, { items: 'max' });
+const { previews } = await previewDeck(template, deck, preview, { assets, layout: 'adaptive' });
+```
+
+## Previews from the chat tools
+
+Give `presentationTools` a provider, and every presentation that `create_presentation` or `edit_presentation`
+makes is drawn:
+
+```ts
+const tools = presentationTools({ template, llm, store, preview });
+```
+
+- The pictures are kept in the store under `preview/<presentation id>/slide-01.svg`, `slide-02.svg`, and so on
+  (`storeKeys.preview(id, slide, extension)`; the extension follows the provider's picture type).
+- The tool's `output` for the chat model lists the keys in `previews`. The pictures themselves are not given to
+  the model.
+- The `ToolResult` for your app carries them in `previews`, next to `deck` and `pptx`.
+- If the provider fails, the presentation is still created and stored. `output.preview_error` then holds the
+  message, and there is no `previews`.
+
+## Writing your own provider
+
+```ts
+import type { PreviewProvider } from 'slotdeck';
+
+const preview: PreviewProvider = {
+  async renderSlides({ pptx, slides, signal }) {
+    // Turn the pptx into pictures in any way: a service that runs PowerPoint or LibreOffice,
+    // a headless browser, another library.
+    const pngs: Uint8Array[] = await myRenderer.toPng(pptx, { signal });
+    return pngs
+      .map((data, index) => ({ slide: index + 1, mimeType: 'image/png', data }))
+      .filter((picture) => !slides || slides.includes(picture.slide));
+  },
+};
+```
+
+The contract:
+
+| Field | Meaning |
+| --- | --- |
+| `request.pptx` | The presentation's bytes. |
+| `request.slides` | 1-based numbers of the slides wanted; every slide when left out. |
+| `request.signal` | Stop when it is aborted. |
+| result | One `SlidePreview` for each slide asked for, in slide order: `{ slide, mimeType, data, width?, height? }`. `mimeType` is `image/svg+xml` or a bitmap type such as `image/png`; `data` is the SVG as UTF-8 text or the bitmap's bytes. |
+
+A service that runs PowerPoint itself, or LibreOffice, is the way to pictures that match what people will see
+in PowerPoint, and to PNG. A PNG preview also fits `draftManifest`'s `slideImage` option, which takes the same
+`{ mimeType, data }` shape.
+
+## How close the pictures are
+
+Three renderers were tried on this project's demo template and its two example decks (`examples/decks`, in
+English and in Hebrew: 22 slides with text, cards, a table, picture charts and a native chart), and compared
+with PowerPoint 16's own export of the same files. For the two that produce SVG with real text, the SVG was
+drawn by Chromium on a machine that has the template's fonts.
+
+| Renderer | Needs a browser | English | Hebrew (right to left) | Tables | Native charts |
+| --- | --- | --- | --- | --- | --- |
+| Pagus 0.1.1 (`@pagus-kit/renderer`), through the adapter | yes | Close: same typefaces and weights, same line breaks in running text | Readable, in the right order; punctuation and mixed lines right with the adapter's marking | Styling close; a right-to-left table is drawn left to right | Close: bars, values, legend, gridlines; the axis steps differ |
+| pptx-svg 0.6.8 | yes | Positions right; a title fell back to another typeface; line breaks depend on a width function you supply | Readable; full stops on the wrong side and mixed lines in the wrong order | Grid lines drawn that the template does not have; not mirrored | Drawn with another layout (legend at the top right, a frame) |
+| pptx-glimpse 5.3.1 | no (draws text as outlines, makes PNG) | Shapes and pictures right; bold and italic are lost, so lines break elsewhere | **Unreadable: the letters of every word come out in reverse order** | Styling lost; not mirrored | Bars, axis and legend; no values on the bars, no gridlines |
+
+Measured as the mean difference between the two pictures of a slide (greyscale, 760 pixels wide), Pagus was
+closest: 1.2% for the English deck and 1.3% for the Hebrew one, against 1.6% and 1.8% for pptx-glimpse and
+2.0% and 1.7% for pptx-svg. The figure says little about text: the Hebrew slides of pptx-glimpse score well
+and cannot be read.
+
+What is wrong in a Pagus preview, as seen on these decks:
+
+- **Text anchored to the bottom of its box is drawn from the top.** A cover title that sits low on the slide
+  in PowerPoint sits higher in the preview. Text anchored to the middle is placed right.
+- **A line that just fits in PowerPoint may wrap in the browser**, and the reverse. The browser measures text
+  a little differently. In running text the breaks were the same on the slides checked; a title that fills
+  its line to the last point wrapped.
+- **A right-to-left table is not mirrored:** its first column is on the left.
+- **Rounded corners of a picture are not drawn**, and a bullet sits closer to its text.
+- **A native chart's axis** has other steps, and the bars stand a little differently.
+- **Fonts.** The viewer's browser needs the template's fonts. Without them it falls back, and every line can
+  break elsewhere.
+
+Other findings worth knowing:
+
+- pptx-glimpse 5.3.1 fails outright when it is given Calibri or Cambria as font files
+  (`lookupType: 7 - substFormat: 1 is not yet supported`). Those are the fonts it finds first on a Windows
+  machine, so there it fails with its default settings. It runs with open fonts such as Carlito and Caladea,
+  and then uses one face for each family: the bold and italic files are not told apart.
+- pptx-glimpse draws a shadow under shapes for which the template turns shadows off.
+- pptx-svg in Node needs a function that gives the width of a text. It is told the typeface and the size, not
+  the weight. Given real widths from the font files (see [text-fit.md](text-fit.md)), its lines for regular
+  text were the ones PowerPoint made.
+- pptx-browser 4.1.5 draws on a canvas. In Node that needs the `canvas` package, which is native code, so it
+  was not tried.
+
+In short: Pagus in a browser is good enough to show a person what a deck looks like, in English and in Hebrew.
+None of the three can stand in for PowerPoint when the question is whether a slide is right to the line. That
+question is answered by measurement ([text-fit.md](text-fit.md)), which agrees with PowerPoint line for line.
+
+### Checking a renderer yourself
+
+The repository has what the comparison was made with. It needs Windows with PowerPoint and is not part of the
+package.
+
+```
+node examples/render-demo.ts                                    # writes out/patterns-en.pptx and out/patterns-he.pptx
+powershell -File scripts/render-pptx.ps1 -Path out/patterns-he.pptx -OutDir out/ppt-he -Width 1280
+```
+
+`render-pptx.ps1` exports PowerPoint's own picture of every slide. Draw the same file with your provider and
+put the two side by side.