slotdeck 0.1.1 → 0.2.0

package/docs/providers.md

@@ -20,6 +20,8 @@ interface JsonRequest {
   system: string;       // the system prompt: the role and the rules
   prompt: string;       // the user message: the brief, the manifest's patterns, what to answer
   schema: JsonSchema;   // the JSON Schema the answer must follow
+  maxOutputTokens?: number; // a ceiling on the answer's size in tokens, reasoning not counted; see "Runaway answers"
+  effort?: 'low';       // set on short structural requests: use light reasoning if your model has a setting for it
   images?: Array<{ mimeType: string; data: Uint8Array }>; // pictures to look at; only draftManifest sends them
   signal?: AbortSignal; // pass it to your HTTP call so work can be cancelled
 }
@@ -30,8 +32,8 @@ The contract:
 - Resolve with the **parsed** value (an object), not a string of JSON.
 - The value should follow `schema`. slotdeck checks what it gets back against the template's manifest and asks
   again when content breaks a limit, but it expects the overall shape the schema describes.
-- Reject (throw) when the call fails. slotdeck does not retry failed calls; add retries in your provider if you
-  want them.
+- Reject (throw) when the call fails. The planner does not retry failed calls; retries belong in the provider,
+  which knows which failures pass by themselves (see "Runaway answers" and the Gemini adapter below).
 - One call is one request and one answer. There is no conversation state: every request carries everything it
   needs.
 
@@ -106,7 +108,7 @@ Every top-level answer slotdeck asks for is a JSON object, so looking for the ou
 
 ### Choosing a model
 
-- The requests are small. Measured on the demo template (15 patterns): the outline request is a system prompt
+- The requests are small. Measured on the demo template when it had 15 patterns: the outline request is a system prompt
   of about 600 characters, a prompt of about 3,600 characters and a schema of about 700 characters. The writing
   request for a 15-slide deck is a prompt of about 1,500 characters and a schema of about 9,800 characters. Any
   current general-purpose model handles this.
@@ -117,6 +119,47 @@ Every top-level answer slotdeck asks for is a JSON object, so looking for the ou
 - `draftManifest` can send a picture of each slide (`images`). A provider for a model that cannot see may ignore
   them; the draft then relies on measurements alone.
 
+### Runaway answers: always set an output limit
+
+Now and then a model runs away inside one text field of its answer: it keeps adding sentence fragments to a
+single string until something stops it. This was seen with a planning request whose proper answer is about 200
+tokens: the model wrote more than 27,000 tokens into one field. Without a limit such a call takes minutes, costs
+tens of thousands of output tokens, and ends in a timeout. It is a matter of chance: the same request usually
+works the next time.
+
+It was tied to reasoning. With the model's default reasoning, a request for a text-only plan ran away in 6 of
+24 calls. With light reasoning it did not run away in 18 calls, and each took 4 seconds instead of about 35.
+That is why planning requests carry `effort: 'low'`.
+
+So a provider should do three things:
+
+1. **Use light reasoning when a request says `effort: 'low'`**, if your model has such a setting.
+2. **Limit the output of every call.** The planner passes `maxOutputTokens` with its requests: a generous
+   ceiling for that answer (for an outline of six slides, 1,360 tokens). Pass it to your model as its output
+   limit. If your model counts reasoning tokens against the same limit, add room for them. When a request
+   carries no estimate, use a default of your own rather than no limit.
+3. **Ask once more when an answer is cut off at the limit.** A cut-off answer is not valid JSON. Retry the same
+   request once, and throw if it is cut off again.
+
+```ts
+async generateJson({ system, prompt, schema, maxOutputTokens, effort, signal }) {
+  const limit = (maxOutputTokens ?? 16_000) + 8_000; // room for reasoning, if your model counts it here
+  const reasoning = effort === 'low' ? 'low' : undefined; // whatever your model calls its light setting
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    const answer = await callModel({ system, prompt, schema, limit, reasoning, signal });
+    if (!answer.cutOffAtLimit) return JSON.parse(answer.text);
+  }
+  throw new Error(`The model's answer was cut off at ${limit} tokens twice`);
+}
+```
+
+The included Gemini adapter does all three. Its limit is the request's estimate plus 8,192 tokens for reasoning
+(24,576 when there is no estimate, or its own `maxOutputTokens` option when set). It sends a cut-off request
+once more. It uses thinking level `low` for requests with `effort: 'low'`, unless `thinkingLevel` is set on the
+adapter, which then applies to every request. It also sends a request once more after a server error (500 to
+504) or when the service's recitation filter blocks an ordinary answer, which happens at random; a bad key, a
+quota or a bad request is not repeated.
+
 ### Timeouts and cancellation
 
 slotdeck passes `signal` through when the caller gave one. Your provider should pass it to its HTTP call, and
@@ -203,7 +246,9 @@ Options of both:
 | `fetch` | A custom `fetch`, for proxies and tests. |
 | `timeoutMs` | Gives up on a request after this long. Default 180000 (3 minutes). `0` waits for ever. |
 
-Only for `gemini`: `thinkingLevel` (`minimal`, `low`, `medium`, `high`) and `maxOutputTokens`.
+Only for `gemini`: `thinkingLevel` (`minimal`, `low`, `medium`, `high`) and `maxOutputTokens`, the output limit
+of a request with reasoning included. By default the limit is the request's own estimate plus 8,192 tokens, or
+24,576 when the request has none.
 
 Only for `geminiImages`: `imageSize` (`512`, `1K`, `2K`, `4K`; default `1K`) and `style`, a sentence appended to
 every prompt, such as a house photo style.

package/docs/rendering.md

@@ -20,6 +20,12 @@ is fast: a 15-slide deck from the demo template takes about 100 ms.
 It does not verify the manifest. Call `checkManifest(template)` when a template or manifest is loaded if you
 want to catch a manifest that no longer matches its file (see [template-studio.md](template-studio.md)).
 
+To get a picture of each slide of the result without PowerPoint, see [preview.md](preview.md).
+
+A third argument, `{ fonts }`, gives the template the metrics of its fonts. Text is then measured as it will
+be set: warnings say how many lines a text runs over, and text can be shrunk to fit. See
+[text-fit.md](text-fit.md).
+
 ## `renderDeck(template, deck, options?)`
 
 ```ts
@@ -33,6 +39,7 @@ interface RenderOptions {
 interface RenderResult {
   pptx: Uint8Array;
   warnings: Issue[]; // non-blocking findings, such as text over a slot's budget
+  shrunk: Array<{ slide: number; slot: string; size: number; scale: number }>; // see text-fit.md; empty unless the manifest has shrinkText
 }
 ```
 
@@ -97,6 +104,7 @@ function validateDeck(manifest: TemplateManifest, deck: DeckSpec, options?: Vali
 interface ValidateOptions {
   layout?: 'strict' | 'adaptive';
   assets?: Iterable<string>; // ids that will be available at render time; when given, image references are checked
+  measure?: TextMeasurer;    // measures text with the template's fonts: see text-fit.md
 }
 
 interface Issue {

package/docs/template-studio.md

@@ -5,10 +5,10 @@ manifest with a model, checking it, seeing whether its budgets hold, and changin
 
 ```ts
 import {
-  draftManifest, checkManifest, sampleDeck, changeManifest, editManifest,
+  draftManifest, checkManifest, sampleDeck, changeManifest, editManifest, patternVariants, VARIANTS,
   studioView, describeManifest, describeSlot, inspectTemplate, ROLES, PptxPackage, loadTemplate, renderDeck,
 } from 'slotdeck';
-import type { ManifestChange, SlotPatch, ChangeResult, ManifestIssue, Role, StudioView } from 'slotdeck';
+import type { ManifestChange, SlotPatch, ChangeResult, ManifestIssue, PatternVariant, Role, StudioView, VariantOption } from 'slotdeck';
 ```
 
 ## The workflow
@@ -21,8 +21,8 @@ import type { ManifestChange, SlotPatch, ChangeResult, ManifestIssue, Role, Stud
 5. Repeat 2 to 4 until the sample looks right. Store the manifest as JSON next to the pptx.
 
 A draft is a starting point for review, not a finished manifest. What a draft does not contain, and a person
-adds: budgets tuned by eye, derived patterns (a text-only variant, a native chart), wider rows, picture areas,
-chart colours, and alignment choices for decks that read the other way.
+adds: budgets tuned by eye, derived patterns (a mirrored or text-only variant, a native chart), wider rows,
+picture areas, chart colours, and alignment choices for decks that read the other way.
 
 ## `draftManifest(pptx, options)`
 
@@ -32,6 +32,7 @@ const { manifest, skipped, issues } = await draftManifest(pptxBytes, {
   name: 'marketing',                             // optional name for the manifest; default 'template'
   slideImage: (slide) => thumbnails.get(slide),  // optional: { mimeType, data } of a picture of slide N (1-based); may be async
   slides: [1, 2, 5],                             // optional: only these slides; default all
+  variants: ['mirror', 'text-only'],             // optional: also add these variants of every pattern that allows them; default none
   concurrency: 4,                                // optional: slides sent to the model at once; default 4
   onProgress: ({ done, total, slide }) => {},    // optional
   signal,                                        // optional
@@ -71,6 +72,18 @@ Any PNG or JPEG of the slide works; 480 pixels wide is enough.
 To redo one slide after changing the pptx, call `draftManifest` with `slides: [n]` and add the pattern it
 returns to your manifest.
 
+### Variants in a draft
+
+With `variants`, the draft also gets the mirror image and the text-only version of every drafted pattern whose
+slide allows one (see `derivePattern` below). They are worked out by code after the model has labelled the
+slides, so they cost no model call. A pattern that allows no variant simply gets none.
+
+This is off by default, for three reasons. Every variant is one more layout to review in the sample deck.
+Whether a mirrored slide suits a design is for a person to say. And a variant is only as good as the labels it
+is derived from, which a draft has not had reviewed yet. The usual order is therefore: draft, review, then add
+the variants you want with `derivePattern`. Use `variants` when a studio should show everything a template can
+do in one pass. The `without` variant is never added by a draft, because it needs a slot to be named.
+
 ### Roles
 
 `ROLES` lists them. A role says what a shape is for and decides the kind of slot it becomes.
@@ -106,6 +119,12 @@ kind of shape, names are unique, rows are consistent. The rules are listed in
 [manifest-format.md](manifest-format.md). Run it when a template is loaded, so a template that someone changed
 shows up there and not in the middle of a render.
 
+For a template loaded with fonts it also tries every text budget out and warns about one that lets text run
+over its box. A row with `widen` gives its texts a larger budget when a slide has fewer items; that budget is
+tried in the wider box, for each number of items that widens the row, and a warning then says which
+(`on a slide with 2 of its 4 items`). See "The studio: checking and setting budgets" in
+[text-fit.md](text-fit.md).
+
 ## `sampleDeck(template, options?)`
 
 ```ts
@@ -120,6 +139,10 @@ filler words and plain coloured rectangles for pictures.
 | --- | --- | --- |
 | `fill` | `0.95` | How full to make each text slot, as a share of its budget. |
 | `items` | `'drawn'` | For patterns with a row or grid: `'drawn'` uses the template's number, `'max'` the most allowed, `'min'` the fewest. |
+| `fit` | `'budget'` | What "full" means for a text slot: `'budget'` is its character budget; `'box'` is what its box holds as measured with the template's fonts (see [text-fit.md](text-fit.md)). |
+
+To look at the sample deck without opening PowerPoint, draw it with a preview provider:
+`previewDeck(template, deck, preview, { assets, layout: 'adaptive' })`. See [preview.md](preview.md).
 
 ## `changeManifest(template, changes)`
 
@@ -145,9 +168,12 @@ Every change is an object with `op`. `pattern` is a pattern id, `slot` a slot na
 #### `setManifest`
 
 ```ts
-{ op: 'setManifest', name?: string, language?: string, direction?: 'ltr' | 'rtl', alignOnDirectionChange?: 'flip' | 'keep' }
+{ op: 'setManifest', name?: string, language?: string, direction?: 'ltr' | 'rtl', alignOnDirectionChange?: 'flip' | 'keep', textScale?: number | null }
 ```
 
+`textScale` enlarges the body text of every deck made from the template (`1.3` for 30% larger); `null` or `1`
+returns to the designed size.
+
 #### `addPattern`
 
 ```ts
@@ -164,7 +190,38 @@ instead to get a complete pattern.
 { op: 'copyPattern', pattern: string, id: string, description?: string }
 ```
 
-A second pattern from the same slide, to turn into a variant with further operations.
+A second pattern from the same slide, to turn into a variant by hand with further operations. For the mirror
+image, a text-only version or a version without an optional line, use `derivePattern`, which works out the
+positions.
+
+#### `derivePattern`
+
+```ts
+{ op: 'derivePattern', pattern: string, variant: 'mirror' | 'text-only' | 'without', slot?: string, id?: string, description?: string }
+```
+
+A second pattern from the same slide, laid out by the code. You name the variant; every position and budget is
+worked out from the shapes of the slide. `VARIANTS` lists the variant names.
+
+| Variant | What it makes | Default id |
+| --- | --- | --- |
+| `mirror` | The picture and what sits beside it change sides. | `<pattern>-mirrored` |
+| `text-only` | The picture is left out, and the text beside it widens over the room it leaves. | `<pattern>-text-only` |
+| `without` | The optional text named in `slot` is left out, and what sits under it moves up. | `<pattern>-no-<slot>` |
+
+- `slot` is needed for `without` only, and must name an optional text slot (`"empty": "remove"`).
+- `id` and `description` replace the defaults. The default description is the source's with a sentence added,
+  such as `Mirrored: here the picture is on the left and the text on the right. Alternate it with "photo-stat" for variety.`
+  Write your own when the source's description names a side ("a photo on the right"), so that the planner
+  reads one clear statement.
+- The new pattern is placed right after its source. The source is not changed.
+- A variant can be derived from a variant: the mirror image, then that without its subtitle.
+- A variant the slide does not allow is refused with the reason, such as
+  `"cover" has no photo, graphic or chart of its own, so there is nothing to change sides with`.
+
+How each variant is worked out, what it leaves alone and when it is refused is described under "Variants the
+code works out" in [layout-freedom.md](layout-freedom.md). `patternVariants` (below) says in advance which
+variants a pattern allows.
 
 #### `removePattern`
 
@@ -231,13 +288,18 @@ A property that does not apply to the slot's kind is refused (`"title" is a text
 #### `setRepeat`
 
 ```ts
-{ 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 }
 ```
 
 Sets how many items a row or grid takes. When the pattern has no row yet, it is found from numbered slot names:
 name the slots of each item alike with a number (`card1Heading`, `card1Text`, `card2Heading`, `card2Text`) and
 they become a row.
 
+`widen` lets the items grow wider when a line holds fewer of them than the template draws, so that two or
+three cards fill a row drawn for four. It is the most an item may grow, as a factor on its drawn width,
+between 1 and 4; `null` or `1` turns it off. See "Fewer items that fill the row" in
+[layout-freedom.md](layout-freedom.md). Render `sampleDeck(template, { items: 'min' })` to look at the result.
+
 #### `removeRepeat`
 
 ```ts
@@ -256,6 +318,8 @@ The items stop being a row whose number can change.
   with the most that do: `5 cards do not fit side by side: each is 21% of the slide wide and the row has 93%. The most is 4`.
 - **Row items stay alike.** A `setSlot` on one item's slot (`card1Icon`) is made to that slot of every item.
   Slots of a row cannot be renamed, moved or removed one by one; remove the row first.
+- **Variants are laid out.** `derivePattern` moves and resizes the shapes of a variant by itself, measures
+  the budgets of every text that changed size, and writes a description the planner can choose the variant by.
 - **Nothing is left broken.** After each change the manifest is checked against the pptx. A change that
   introduces a new error is refused.
 
@@ -280,22 +344,47 @@ A native chart in place of a sample chart picture, as a second pattern:
 ]
 ```
 
-A text-only slide from a slide with a photo:
+The mirror image of a slide with a photo, for variety in a deck with several such slides:
+
+```ts
+{ op: 'derivePattern', pattern: 'photo-stat', variant: 'mirror', description: 'One key figure with a title and a short explanation on the left, and a photo on the right.' }
+```
+
+A text-only slide from a slide with a photo, then larger text with room for three paragraphs (the budget
+follows the new size):
 
 ```ts
 [
-  { op: 'copyPattern', pattern: 'text-and-photo', id: 'text-only' },
-  { op: 'addSlot', pattern: 'text-only', shape: '2', role: 'decoration' },              // the photo
-  { op: 'setSlot', pattern: 'text-only', slot: 'body', box: { x: 0.04, y: 0.49, w: 0.72, h: 0.39 }, fontSize: 20, maxParagraphs: 3 },
+  { op: 'derivePattern', pattern: 'text-and-photo', variant: 'text-only', id: 'text-only' },
+  { op: 'setSlot', pattern: 'text-only', slot: 'body', fontSize: 20, maxParagraphs: 3, paragraphGap: 12 },
 ]
 ```
 
+The same slide for decks that have no subtitle, with the body moved up into its place:
+
+```ts
+{ op: 'derivePattern', pattern: 'text-and-photo', variant: 'without', slot: 'subtitle' }
+```
+
+Two or three cards that fill a row drawn for four, each holding more text:
+
+```ts
+{ op: 'setRepeat', pattern: 'icon-cards', widen: 2.2 }
+```
+
 Smaller table text and fewer columns (the cell budget is measured for you):
 
 ```ts
 { op: 'setSlot', pattern: 'table', slot: 'table', maxColumns: 5, bodyText: { size: 9 }, headerText: { size: 10, bold: true } }
 ```
 
+Larger body text in every deck, for a template whose own body text is small (render the sample deck afterwards
+to see that everything still fits):
+
+```ts
+{ op: 'setManifest', textScale: 1.3 }
+```
+
 Mirror alignment for right-to-left decks, but keep the line beside the logo where it is:
 
 ```ts
@@ -319,7 +408,10 @@ by hand. One model call, and a second when some operations were refused, so the
 
 - Instructions can be in any language.
 - A person may refer to a slide by number or to a pattern by id.
-- The model cannot set positions: `box` and `span` exist only for changes made by hand.
+- The model cannot set positions: `box` and `span` exist only for changes made by hand. It can ask for a
+  variant by name ("add a mirrored version of the photo slides", "a version of slide 2 without the picture"),
+  which becomes a `derivePattern` operation: the model names the variant, and the code works out where
+  everything goes.
 - An operation the model got wrong shows up in `rejected` with the reason; nothing of it is applied.
 
 `describeManifest(template)` returns the text the model reads: every pattern with its slots and limits, and the
@@ -352,6 +444,23 @@ that are slots, and on a click offers the shape's `roles` (sending `addSlot`) or
 
 `describeSlot(slot)` gives a slot in a few words, such as `text, up to 40 characters, required`.
 
+## `patternVariants(template, pattern)`
+
+```ts
+const options = patternVariants(template, 'text-and-photo');
+// [
+//   { variant: 'mirror',    available: true, note: 'the mirror image of "text-and-photo", with the picture on the left and what sat beside it on the right. ...' },
+//   { variant: 'text-only', available: true, note: '"text-and-photo" without its picture "photo". Widened over the freed area, with budgets to match: ...' },
+//   { variant: 'without', slot: 'subtitle', available: true, note: '"text-and-photo" without "subtitle": body moves up and has more room (431 characters).' },
+// ]
+```
+
+No model, and nothing is changed. It lists the variants `derivePattern` could make from a pattern: the mirror
+image, the text-only version, and one `without` for each optional text slot. An entry with `available: false`
+carries the reason in `note`; an available one says there what the variant would do. A studio screen can show
+the available ones as buttons that send `{ op: 'derivePattern', pattern, variant, slot }`. It throws when the
+template has no pattern of that id.
+
 ## `inspectTemplate(pkg)`
 
 ```ts