slotdeck 0.1.1 → 0.2.0

package/docs/api-reference.md

@@ -16,10 +16,11 @@ every field.
 ### `loadTemplate`
 
 ```ts
-function loadTemplate(pptx: Uint8Array, manifest: TemplateManifest): Template;
+function loadTemplate(pptx: Uint8Array, manifest: TemplateManifest, options?: TemplateOptions): Template;
 ```
 
-Unzips a template once. Reuse the result.
+Unzips a template once. Reuse the result. `options.fonts` gives it font metrics, which turns on text measuring
+everywhere the template is used (see "Measuring text" below).
 
 ### `renderDeck`
 
@@ -45,6 +46,26 @@ function extractAssets(template: Template, deck: DeckSpec, pptx: Uint8Array): Re
 
 Reads a deck's pictures back from a pptx rendered from it, by asset id.
 
+### `slideAlternatives`
+
+```ts
+function slideAlternatives(manifest: TemplateManifest, deck: DeckSpec, slide: number, options?: AlternativesOptions): SlideAlternative[];
+
+interface AlternativesOptions { layout?: LayoutMode; patterns?: string[] }
+interface SlideAlternative {
+  pattern: string;      // a pattern that has a place for everything the slide says
+  description: string;  // what that pattern is for
+  slide: SlideSpec;     // the slide written for that pattern
+  changes: string[];    // what was done where the content was not copied slot for slot
+  dropped: string[];    // slots of the original whose photo or icon has no place
+  warnings: Issue[];    // what validateDeck says about the new slide
+}
+```
+
+The other patterns that can hold what slide number `slide` (from 1) of a deck says, with the slide written for
+each. Synchronous, no model, no words changed. Throws a `RangeError` when the deck has no such slide. See
+"Another layout for the same slide" in [layout-freedom.md](layout-freedom.md).
+
 ### `DeckValidationError`
 
 ```ts
@@ -66,13 +87,18 @@ Tell the kinds of slot value apart when walking a deck.
 ### Types
 
 ```ts
-interface Template { pkg: PptxPackage; manifest: TemplateManifest }
+interface Template { pkg: PptxPackage; manifest: TemplateManifest; fonts?: FontMetrics }
+interface TemplateOptions { fonts?: FontMetrics }
 
 interface RenderOptions { assets?: Record<string, Uint8Array>; layout?: LayoutMode }
-interface RenderResult { pptx: Uint8Array; warnings: Issue[] }
+interface RenderResult {
+  pptx: Uint8Array;
+  warnings: Issue[];
+  shrunk: Array<{ slide: number; slot: string; size: number; scale: number }>; // texts set smaller to fit; empty without shrinkText
+}
 
 type LayoutMode = 'strict' | 'adaptive';
-interface ValidateOptions { layout?: LayoutMode; assets?: Iterable<string> }
+interface ValidateOptions { layout?: LayoutMode; assets?: Iterable<string>; measure?: TextMeasurer }
 interface Issue { severity: 'error' | 'warning'; slide?: number; slot?: string; message: string }
 
 interface DeckSpec {
@@ -172,6 +198,14 @@ function directionOf(language: string): Direction;
 
 The reading direction of a BCP 47 language tag.
 
+### `isPlainText`
+
+```ts
+function isPlainText(pattern: PatternDef): boolean;
+```
+
+Whether a slide made from the pattern is running text and nothing else: the patterns a text-only deck may use.
+
 ### `PlanError`
 
 ```ts
@@ -199,6 +233,7 @@ interface Brief {
   instructions?: string;
   fields?: Record<string, string>;
   textSize?: TextSize;
+  textOnly?: boolean; // every slide plain text: only the template's plain text patterns are offered
 }
 type ImageDensity = 'none' | 'low' | 'medium' | 'high';
 
@@ -210,6 +245,7 @@ interface PlanOptions {
   patterns?: string[];
   numberPatterns?: 'from-brief' | 'always' | 'never';
   maxRepairs?: number;
+  review?: DeckReview; // a second look at every draft; see "Design checks and reviews"
   onProgress?: (event: PlanProgress) => void;
   signal?: AbortSignal;
 }
@@ -287,6 +323,7 @@ const storeKeys: {
   deck(id: string): string;  // 'deck/<id>.json'
   pptx(id: string): string;  // 'pptx/<id>.pptx'
   asset(id: string): string; // 'asset/<id>'
+  preview(id: string, slide: number, extension: string): string; // 'preview/<id>/slide-03.svg'
 };
 ```
 
@@ -322,7 +359,9 @@ interface PresentationToolsOptions {
   layout?: LayoutMode;
   fields?: Record<string, string>;
   numberPatterns?: 'from-brief' | 'always' | 'never';
+  review?: DeckReview; // a second look at every draft the tools write
   thumbnail?: (patternId: string) => string | undefined;
+  preview?: PreviewProvider; // draws every presentation the tools create or change
   newId?: (kind: 'plan' | 'deck') => string;
   onProgress?: (event: GenerateProgress, tool: string) => void;
 }
@@ -331,7 +370,7 @@ interface PresentationTools {
   call(name: string, args: unknown, context?: { signal?: AbortSignal }): Promise<ToolResult>;
 }
 interface ToolDefinition { name: string; description: string; parameters: JsonSchema }
-interface ToolResult { output: Record<string, unknown>; plan?: DeckPlan; deck?: DeckSpec; pptx?: Uint8Array }
+interface ToolResult { output: Record<string, unknown>; plan?: DeckPlan; deck?: DeckSpec; pptx?: Uint8Array; previews?: SlidePreview[] }
 ```
 
 ## Providers
@@ -366,6 +405,8 @@ interface JsonRequest {
   system: string;
   prompt: string;
   schema: JsonSchema;
+  maxOutputTokens?: number; // a ceiling on the answer's size, reasoning not counted; pass it on as an output limit
+  effort?: 'low'; // a short structural request: use light reasoning if the model has a setting for it
   images?: Array<{ mimeType: string; data: Uint8Array }>;
   signal?: AbortSignal;
 }
@@ -428,6 +469,17 @@ function changeManifest(template: Template, changes: ManifestChange[]): ChangeRe
 function editManifest(template: Template, instruction: string, options: ManifestEditOptions): Promise<ManifestEditResult>;
 ```
 
+### `patternVariants`, `VARIANTS`
+
+```ts
+function patternVariants(template: Template, pattern: string): VariantOption[];
+const VARIANTS: readonly ['mirror', 'text-only', 'without'];
+type PatternVariant = (typeof VARIANTS)[number];
+```
+
+The variants of a pattern that `changeManifest` can derive with `{ op: 'derivePattern' }`, each with whether
+the pattern's slide allows it. See [template-studio.md](template-studio.md).
+
 ### `describeManifest`, `describeSlot`
 
 ```ts
@@ -482,6 +534,7 @@ interface DraftOptions {
   name?: string;
   slideImage?: (slide: number) => SlidePicture | undefined | Promise<SlidePicture | undefined>;
   slides?: number[];
+  variants?: Array<'mirror' | 'text-only'>; // also add these variants of every pattern that allows them
   concurrency?: number;
   onProgress?: (event: { done: number; total: number; slide: number }) => void;
   signal?: AbortSignal;
@@ -489,18 +542,19 @@ interface DraftOptions {
 interface DraftResult { manifest: TemplateManifest; skipped: Array<{ slide: number; reason: string }>; issues: ManifestIssue[] }
 
 interface ManifestIssue { severity: 'error' | 'warning'; pattern?: string; slot?: string; message: string }
-interface SampleOptions { fill?: number; items?: 'drawn' | 'max' | 'min' }
+interface SampleOptions { fill?: number; items?: 'drawn' | 'max' | 'min'; fit?: 'budget' | 'box' }
 
 type ManifestChange =
-  | { op: 'setManifest'; name?: string; language?: string; direction?: Direction; alignOnDirectionChange?: AlignPolicy }
+  | { op: 'setManifest'; name?: string; language?: string; direction?: Direction; alignOnDirectionChange?: AlignPolicy; textScale?: number | null }
   | { op: 'addPattern'; slide: number; id: string; description?: string }
   | { op: 'copyPattern'; pattern: string; id: string; description?: string }
+  | { op: 'derivePattern'; pattern: string; variant: PatternVariant; slot?: string; id?: string; description?: string }
   | { op: 'removePattern'; pattern: string }
   | { op: 'setPattern'; pattern: string; id?: string; description?: string; figures?: boolean }
   | { op: 'addSlot'; pattern: string; shape: string; role: Role; name?: string; optional?: boolean }
   | { op: 'removeSlot'; pattern: string; slot: string }
   | ({ op: 'setSlot'; pattern: string; slot: string } & SlotPatch)
-  | { op: 'setRepeat'; pattern: string; min?: number; max?: number; item?: string; span?: { left: number; right: number } | null }
+  | { op: 'setRepeat'; pattern: string; min?: number; max?: number; item?: string; span?: { left: number; right: number } | null; widen?: number | null }
   | { op: 'removeRepeat'; pattern: string };
 
 interface SlotPatch {
@@ -536,6 +590,7 @@ interface ChangeResult {
   rejected: Array<{ index: number; change: ManifestChange; reason: string }>;
   issues: ManifestIssue[];
 }
+interface VariantOption { variant: PatternVariant; slot?: string; available: boolean; note: string }
 interface ManifestEditOptions { llm: LlmProvider; signal?: AbortSignal }
 interface ManifestEditResult extends ChangeResult { note: string }
 
@@ -571,6 +626,230 @@ interface SlideInfo { number: number; part: string; layout: string; shapes: Shap
 interface TemplateInfo { slideWidth: number; slideHeight: number; defaultFontSize: number; slides: SlideInfo[] }
 ```
 
+## Design checks and reviews
+
+Explained in [design-checks.md](design-checks.md). Both need a template loaded with fonts.
+
+### `checkDesign`
+
+```ts
+function checkDesign(template: Template, deck: DeckSpec, options?: DesignOptions): DesignIssue[];
+```
+
+Lists design problems that follow from measurement alone: text that runs over its box, boxes and cards left
+mostly empty, headings that end in a lone word. Synchronous, no model, no picture.
+
+### `designReview`
+
+```ts
+function designReview(template: Template, options?: DesignOptions): DeckReview;
+```
+
+The design checks as a review for the planner's `review` option. Reports `empty`, `uneven` and `orphan`.
+
+### `visionReview`
+
+```ts
+function visionReview(options: VisionReviewOptions): DeckReview;
+```
+
+A review by a model that looks at pictures of the draft's slides, drawn by a `PreviewProvider` that gives
+bitmap pictures. Not run against a live model; see the cautions in [design-checks.md](design-checks.md).
+
+### Types
+
+```ts
+type DesignKind = 'overflow' | 'empty' | 'uneven' | 'orphan';
+interface DesignIssue { severity: 'warning'; slide: number; slot: string; kind: DesignKind; message: string } // an Issue with a kind
+interface DesignOptions {
+  layout?: LayoutMode;
+  kinds?: DesignKind[];  // default: all four
+  emptyBelow?: number;   // default 1/3
+  headingSize?: number;  // points; default 20
+}
+
+// A second look at a draft deck: problems to send back to the writing model.
+type DeckReview = (deck: DeckSpec, context: { signal?: AbortSignal }) => Issue[] | Promise<Issue[]>;
+
+interface VisionReviewOptions {
+  template: Template;
+  llm: LlmProvider;         // a model that accepts pictures
+  preview: PreviewProvider; // must give PNG, JPEG, WebP or GIF
+  icons?: IconDef[];
+  assets?: AssetDef[];
+  layout?: LayoutMode;       // default 'adaptive'
+  slidesPerRequest?: number; // default 6
+}
+```
+
+## Slide previews
+
+Explained in [preview.md](preview.md). slotdeck draws nothing itself: a `PreviewProvider` is a renderer you plug in.
+
+### `pagusPreviews`
+
+```ts
+function pagusPreviews(core: PagusCore, renderer: PagusRenderer, options?: PagusOptions): PreviewProvider;
+
+interface PagusCore { parse(data: ArrayBuffer): Promise<{ slides: readonly unknown[]; slideSize: unknown }> } // the `@pagus-kit/core` module
+interface PagusRenderer { renderSlide(slide: never, slideSize: never, options?: never): { svg: string; width: number; height: number } } // the `@pagus-kit/renderer` module
+interface PagusOptions { scale?: number; fontSubstitutes?: Record<string, string>; fontCss?: string }
+```
+
+A provider that draws slides with the Pagus library, which you install and pass in:
+`pagusPreviews(pagusCore, pagusRenderer)` after `import * as pagusCore from '@pagus-kit/core'` and
+`import * as pagusRenderer from '@pagus-kit/renderer'`. One SVG for each slide, with the text as real text for a
+browser to set. Paragraphs that start with a right-to-left letter are marked as running right to left.
+
+### `previewDeck`
+
+```ts
+function previewDeck(template: Template, deck: DeckSpec, preview: PreviewProvider, options?: PreviewDeckOptions): Promise<{ pptx: Uint8Array; previews: SlidePreview[] }>;
+```
+
+`renderDeck`, then the provider: the pptx and a picture of each of its slides.
+
+### `patternPreviews`
+
+```ts
+function patternPreviews(template: Template, preview: PreviewProvider, options?: SampleOptions & { signal?: AbortSignal }): Promise<Record<string, SlidePreview>>;
+```
+
+A picture of every pattern, by pattern id: each pattern's slide of the template's sample deck.
+
+### `previewExtension`
+
+```ts
+function previewExtension(preview: { mimeType: string }): string; // 'svg', 'png', 'jpg', ...
+```
+
+The file extension for a preview's type, for naming it in a store or on disk.
+
+### Types
+
+```ts
+// What slotdeck needs from a slide renderer. Implement it to plug in any renderer.
+interface PreviewProvider {
+  renderSlides(request: PreviewRequest): Promise<SlidePreview[]>; // one picture for each slide asked for, in slide order
+}
+interface PreviewRequest {
+  pptx: Uint8Array;
+  slides?: number[]; // 1-based; every slide when left out
+  signal?: AbortSignal;
+}
+interface SlidePreview {
+  slide: number;    // 1-based
+  mimeType: string; // 'image/svg+xml', 'image/png'
+  data: Uint8Array; // SVG as UTF-8 text, or the bitmap's bytes
+  width?: number;   // pixels
+  height?: number;
+}
+interface PreviewDeckOptions { assets?: Record<string, Uint8Array>; layout?: LayoutMode; signal?: AbortSignal }
+```
+
+## Measuring text
+
+Explained in [text-fit.md](text-fit.md). All of it is optional: without fonts nothing here is used.
+
+### `fontkitMetrics`
+
+```ts
+function fontkitMetrics(fontkit: FontkitModule, files: FontFiles): FontMetrics;
+
+type FontFiles = Record<string, Uint8Array | Uint8Array[]>; // typeface name as the template states it -> its font files
+interface FontkitModule { create(buffer: never, postscriptName?: string): unknown } // the `fontkit` module itself
+```
+
+Font metrics from font files, read with the `fontkit` library, which you install and pass in:
+`fontkitMetrics(fontkit, { Calibri: [regularBytes, boldBytes] })` after `import * as fontkit from 'fontkit'`.
+Reads TrueType, OpenType, collections, WOFF and WOFF2.
+
+### `fontFiles` (from `slotdeck/node`)
+
+```ts
+function fontFiles(fontkit: FontkitModule, directory: string, typefaces: Iterable<string>): FontFiles;
+```
+
+Finds the font files of the given typefaces in a folder, such as the system's font folder, by the family name
+each file states. Typefaces with no file there are left out.
+
+### `templateFonts`
+
+```ts
+function templateFonts(template: Template, language?: string): TemplateFont[];
+```
+
+The typefaces a template's text slots are set in, with the weights and slants used: the font files to supply.
+`language` (default: the manifest's) adds the typeface that text of that language is set in.
+
+### `textMeasurer`
+
+```ts
+function textMeasurer(template: Template, fonts?: FontMetrics): TextMeasurer;
+```
+
+A measurer for a template. `fonts` defaults to the fonts the template was loaded with; it throws when there
+are none. Pass the result to `validateDeck` as `measure`, or call `fit` yourself.
+
+### `measuredBudgets`
+
+```ts
+function measuredBudgets(template: Template, options?: BudgetOptions): MeasuredBudget[];
+```
+
+How many characters each text slot's box holds, as measured, with a budget to set. The template must have
+fonts.
+
+### Types
+
+```ts
+// What slotdeck needs from a font library. Implement it to use a library other than fontkit.
+interface FontMetrics {
+  face(typeface: string, style: FontStyle): FontFace | undefined; // undefined: the typeface was not supplied
+  fallback?(codePoint: number, style: FontStyle): FontFace | undefined; // a face for a character the chosen one lacks
+}
+interface FontStyle { bold: boolean; italic: boolean }
+interface FontFace {
+  has(codePoint: number): boolean;
+  advances(text: string, kerning: boolean): number[]; // the advance of each glyph after shaping, in ems
+  substitute?: boolean; // stands in for a weight or slant that was not supplied
+}
+
+interface TemplateFont { typeface: string; bold: boolean; italic: boolean }
+
+interface TextMeasurer {
+  fit(pattern: string | PatternDef, slot: string | TextSlotDef, text: string | string[], options?: FitOptions): TextFit | undefined;
+  missingFonts(): TemplateFont[];
+}
+interface FitOptions {
+  textScale?: number;   // the factor on body text the deck is rendered with; default 1
+  shrink?: ShrinkLimit; // allow the text to be set smaller when it does not fit
+  items?: number;       // for a slot of a row of items: how many items the slide has
+}
+interface ShrinkLimit { to: number; minSize?: number } // the shape of the manifest's shrinkText
+interface TextFit {
+  fits: boolean;
+  lines: number;       // lines the text takes
+  capacity: number;    // lines of this text the box holds
+  overflow: number;    // lines that do not fit
+  height: number;      // points the text takes
+  room: number;        // points the box gives
+  widthRatio: number;  // for a box that does not wrap: longest line / box width
+  size: number;        // font size of the first paragraph, in points
+  sizes: number[];     // font size of each paragraph
+  scale: number;       // the factor the text was shrunk by; 1 when it was not
+  fitsChars: number;   // about how many characters of such text the box holds
+  paragraphs: string[][]; // the lines of each paragraph
+  widths: number[][];     // the width of each of those lines, in points
+  lineRoom: number[];     // the width a line of each paragraph may take, in points
+  sampleLines: number;    // lines the template's own sample text takes in the slot; 0 when there is none to compare with
+  approximate: boolean;   // a typeface, weight or outline was stood in for
+}
+
+interface BudgetOptions { sample?: string; margin?: number } // margin defaults to 0.9
+interface MeasuredBudget { pattern: string; slot: string; maxChars?: number; fits: number; suggested: number }
+```
+
 ## Manifest types
 
 Described field by field in [manifest-format.md](manifest-format.md).
@@ -589,6 +868,8 @@ interface TemplateManifest {
   language?: string;
   direction: Direction;
   alignOnDirectionChange?: AlignPolicy;
+  textScale?: number; // enlarges body text in every deck made from the template
+  shrinkText?: { to: number; minSize?: number }; // lets text that does not fit be set smaller; needs fonts
   patterns: PatternDef[];
 }
 interface PatternDef {
@@ -608,6 +889,7 @@ interface RepeatDef {
   max?: number;
   span?: { left: number; right: number };
   columns?: number;
+  widen?: number; // fewer items on a line than drawn grow up to this factor to fill the row
 }
 type SlotDef = TextSlotDef | ImageSlotDef | TableSlotDef | ChartSlotDef;
 

package/docs/changelog.md

@@ -0,0 +1,242 @@
+# Changelog
+
+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
+
+- **Text-only decks.** `textOnly: true` on a brief, or `text_only: true` in the `plan_presentation` tool, plans
+  every slide as plain text: a title with paragraphs or a list, and no pictures, icons, cards, figures, tables
+  or charts. The planner is then offered only the template's plain text patterns, so no other kind can be
+  chosen. See "Asking for a kind of slide" in [generating.md](generating.md).
+- **Wishes about the kind of slides are honoured.** A wish stated in words in the brief or in an edit
+  instruction ("text only", "no tables", "only cards") now decides which patterns may be used and comes before
+  variety. It works when planning, when changing a plan, and when changing a finished deck. The pattern list
+  the model reads marks each plain text pattern with "Plain text.".
+- **`isPlainText(pattern)`** tells whether a pattern is plain text, for an app that wants to show or check
+  which layouts a text-only deck can use.
+- **Larger body text for a whole template.** `textScale` on the manifest enlarges the body text of every deck
+  made from the template (`1.3` turns 9 pt into about 12 pt). Budgets shrink to match in validation, in what
+  the planner shows the model, and in `sampleDeck`. Set it by hand or with
+  `changeManifest(template, [{ op: 'setManifest', textScale: 1.3 }])`; `editManifest` understands requests such
+  as "make body text 20 percent larger". See "Larger text for a whole template" in
+  [layout-freedom.md](layout-freedom.md).
+- **`maxOutputTokens` on requests to the model.** The planner passes a ceiling for each answer with every
+  request it makes. See "Runaway answers" in [providers.md](providers.md).
+- **`effort: 'low'` on planning requests.** Calls that choose and arrange rather than write (the outline, a
+  change to a plan, the first step of an edit) ask for light reasoning.
+
+### Changed
+
+- **Table text and chart labels follow the text scale**, where the manifest states their size
+  (`bodyText.size`, `headerText.size`, `text.size`). This applies to a deck's own text size (`textScale`,
+  `textSize`, `text_size`) as well as to the new template scale, and a table cell then holds fewer characters.
+  Before, tables and charts kept their size when a deck asked for larger text.
+- **The Gemini adapter limits the output of every request.** The limit is the request's estimate plus 8,192
+  tokens for reasoning, or 24,576 when the request has none, or the adapter's `maxOutputTokens` when set.
+  Before, a request had no limit unless `maxOutputTokens` was set.
+- **The Gemini adapter sends a request once more** when the answer was cut off at the limit, after a server
+  error (500 to 504), and when the service's recitation filter blocks an ordinary answer. A bad key, a quota or
+  a bad request is not repeated.
+- **The Gemini adapter uses thinking level `low` for requests with `effort: 'low'`**, unless `thinkingLevel`
+  is set on the adapter. Planning calls became several times faster: a plan takes about 5 seconds.
+- The per-slide sentence of a plan is asked for as "a single sentence of at most 25 words".
+
+### Fixed
+
+- **A request for a text-only presentation gave cards and tables.** The planner was told to vary the layouts
+  and nothing said that a wish about the kind of slides comes first; and "no pictures" was the most that
+  reached it. Fixed by the two additions above.
+- **A model call could hang for minutes.** With its default reasoning the model sometimes ran away inside one
+  text field of a planning answer and wrote tens of thousands of tokens. Measured on a text-only plan: 6 of 24
+  calls with default reasoning, none of 18 with light reasoning. Planning calls now use light reasoning, every
+  call has an output limit, and a cut-off answer is asked for once more.
+
+### Upgrading from 0.1.1
+
+No code has to change. To benefit:
+
+- **Chat assistants:** `plan_presentation` has a new optional argument, `text_only`. It is in
+  `tools.definitions`, so it reaches the chat model when the definitions are passed as before. If your system
+  prompt lists the tool's arguments, add it, and tell the model that "no pictures" (`image_density: "none"`)
+  still allows cards, tables and charts.
+- **Small body text:** if decks from your template have body text that is too small, add `"textScale": 1.3`
+  (or another factor) to the manifest, render `sampleDeck` once to see that everything still fits, and keep the
+  manifest. A manifest with `textScale` is ignored by 0.1.1 and earlier, which show the designed size.
+- **Your own `LlmProvider`:** requests now carry two optional fields, `maxOutputTokens` and `effort`. A provider
+  that ignores them keeps working. To get the protection and the speed, pass `maxOutputTokens` on as your
+  model's output limit (adding room for reasoning tokens if your model counts them in the same limit), use
+  light reasoning when `effort` is `'low'`, and retry once when an answer is cut off. See "Runaway answers" in
+  [providers.md](providers.md).
+- **Tables with larger text:** a deck that asks for larger text now enlarges table text too, where the
+  manifest states its size, and gives cells a smaller budget. A deck stored with `textScale` renders with
+  larger table text than before.
+
+## 0.1.1
+
+### Added
+
+- **Documentation inside the package.** The `docs/` folder ships with the npm package
+  (`node_modules/slotdeck/docs/`), in plain Markdown with no links to the internet, so it can be read where
+  there is no network access. Start at [README.md](README.md).
+
+### Changed
+
+- **Unknown chart format.** `validateDeck` warns about a chart `format` other than `"number"` or `"percent"`
+  (`chart format "x" is not known and is ignored`). Before, it was ignored silently.
+
+### Upgrading from 0.1.0
+
+Nothing to change.
+
+## 0.1.0
+
+First release.
+
+- **Renderer:** `loadTemplate`, `renderDeck`, `validateDeck`, `extractAssets`. Text, pictures, tables and
+  native charts; rows and grids with a variable number of items; larger text on request; derived patterns.
+- **Planner and editor:** `generateDeck`, `planDeck`, `planOutline`, `editPlan`, `writeDeck`, `editDeck`,
+  `planEdit`, `resolveAssets`, with any model through `LlmProvider` and `ImageProvider`.
+- **Chat tools:** `presentationTools` with `plan_presentation`, `edit_presentation_plan`,
+  `create_presentation` and `edit_presentation`, and stores (`memoryStore`, `directoryStore`).
+- **Gemini adapters:** `gemini`, `geminiImages`, `vertexEndpoint`.
+- **Reading direction:** right-to-left decks on left-to-right templates and the reverse.
+- **Template studio:** `draftManifest`, `checkManifest`, `sampleDeck`, `changeManifest`, `editManifest`,
+  `studioView`, `describeManifest`, `inspectTemplate`.