slotdeck 0.1.1 → 0.1.2

package/docs/chat-tools.md

@@ -86,6 +86,7 @@ Arguments:
 | `language` | string | no | BCP 47 tag, such as `he` or `en`. Defaults to the template's language. |
 | `image_density` | `none`, `low`, `medium`, `high` | no | How many slides carry a photo. Default `medium`. Forced to `none` when no photos can be made. |
 | `text_size` | `normal`, `large`, `x-large` | no | Size of body text. Default `normal`. |
+| `text_only` | boolean | no | `true` when the person asks for a presentation of text only. Every slide is then plain text: a title with paragraphs or a list, with no pictures, icons, cards, figures, tables or charts. Only the template's plain text layouts are used. |
 | `instructions` | string | no | Audience, tone and anything else to respect. |
 
 Output:
@@ -247,6 +248,9 @@ async function runTurn(messages) {
 The tool descriptions already tell the model the order to work in. It helps to add, in your own system prompt:
 
 - Put every fact, figure and name the person gave into `topic`. Numbers that are not in `topic` will not be used.
+- Pass wishes about the kind of slides on, in the person's words ("no tables", "only cards"), in `topic` or
+  `instructions`. For a presentation of text only, set `text_only: true`: "no pictures" alone
+  (`image_density: "none"`) still allows cards, tables and charts.
 - Show the plan and wait for approval before calling `create_presentation`.
 - For a change to a finished presentation, call `edit_presentation` with the person's words; do not plan again
   from scratch.

package/docs/generating.md

@@ -36,6 +36,7 @@ It runs `planDeck`, then `resolveAssets`, then `renderDeck`.
 | `instructions` | string | none | Anything else to respect: audience, tone, points that must be covered. |
 | `fields` | object of strings | none | Deck-level values the template needs (see "Deck fields" in [deck-format.md](deck-format.md)). A pattern that needs a field that is not given is not offered. |
 | `textSize` | `"normal"`, `"large"`, `"x-large"` | `normal` | Size of body text. Larger text gets smaller budgets, so less is written. |
+| `textOnly` | boolean | `false` | Plan every slide as plain text. Only the template's plain text patterns are offered. See "Asking for a kind of slide" below. |
 
 ### Options (`GenerateOptions`)
 
@@ -105,6 +106,37 @@ model.
 
 If nothing can be offered, `PlanError` is thrown with the reasons.
 
+### Asking for a kind of slide
+
+By default the planner varies the patterns across a deck. A wish about the kind of slides overrides that, and
+there are two ways to state one.
+
+**In words.** A wish in `prompt` or `instructions`, such as "text only", "no tables" or "only cards", decides
+which patterns may be used and comes before variety. The planner is told so, and the pattern list it reads marks
+each plain text pattern with the words "Plain text.".
+
+**As a flag.** `textOnly: true` is the reliable way to get a deck of text and nothing else. The planner is then
+offered only the plain text patterns, so no other kind can be chosen, and it is told that using the same pattern
+for several slides in a row is expected.
+
+```ts
+await generateDeck(template, { prompt: 'Our move to hybrid work: why, the rules, what changed', textOnly: true }, { llm });
+// for example: cover, text-only, text-only, text-only, text-only, closing
+```
+
+A pattern counts as **plain text** when a slide made from it holds running text and nothing else: all its
+slots are text (a picture that the pattern always drops does not count), it has no row or grid of items, and it
+is not marked `figures`. A cover, a closing slide, a quotation and a title-with-paragraphs slide are plain text;
+cards, tables, charts and anything with a picture or icon are not.
+
+Two things to know:
+
+- "No pictures" is a different wish. `imageDensity: 'none'` removes photos but still allows cards, tables and
+  charts.
+- A text-only deck is only as varied as the template's plain text patterns. A template without one cannot make
+  such a deck: `PlanError: Template "x" has no plain text pattern, so a text-only deck cannot be planned from it`.
+  Add one as a derived pattern (see [layout-freedom.md](layout-freedom.md)).
+
 ### Why numbers are guarded
 
 A model given a slide built around a statistic and no data tends to invent one. So patterns marked `figures` are
@@ -210,9 +242,13 @@ Warnings (text a little over a budget, for instance) do not throw. They are retu
 
 ## Cost and time
 
-For one deck: two text calls, more if repairs are needed, and one image call per generated photo. On the demo
-template with `gemini-3.8-flash`, a nine-slide deck took about 50 seconds including four pictures. An edit that
-rewrites one slide took about 15 seconds.
+For one deck: two text calls, more if repairs are needed, and one image call per generated photo. Measured on
+the demo template with `gemini-3.8-flash`: a plan takes about 5 seconds, an eight-slide deck about 30 seconds
+from brief to file (with drawn stand-in pictures), and an edit that rewrites one slide about 8 seconds.
+
+Planning calls (the outline, a change to a plan, the first step of an edit) ask the model for light reasoning,
+because they choose and arrange rather than write. This made them several times faster and removed the runaway
+answers described in [providers.md](providers.md). Writing the slides keeps the model's default.
 
 To keep cost down: reuse `cache` across calls, set `imageDensity: 'low'` or `'none'`, and use `planOutline`
 first so a person can correct the plan before content and pictures are produced.

package/docs/layout-freedom.md

@@ -72,6 +72,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
 

package/docs/manifest-format.md

@@ -66,6 +66,7 @@ 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). |
 
 ## `PatternDef`
 

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.
 
@@ -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/template-studio.md

@@ -145,9 +145,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
@@ -296,6 +299,13 @@ Smaller table text and fewer columns (the cell budget is measured for you):
 { 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

package/docs/troubleshooting.md

@@ -58,6 +58,7 @@ These do not stop rendering. `renderDeck` and the planner return them.
 | --- | --- | --- |
 | `No pattern of template "x" can be used: ...` | Nothing in the manifest can be filled with what was supplied. The reasons follow. | See the reasons below. |
 | `The model did not produce a usable outline: ...` | The model's answer did not have the expected shape. | Retry. If it repeats, check that your provider returns parsed JSON that follows the schema. |
+| `Template "x" has no plain text pattern, so a text-only deck cannot be planned from it` | `textOnly` was asked for, and no pattern of the manifest is plain text. | Add a plain text pattern to the manifest (see [layout-freedom.md](layout-freedom.md)), or plan without `textOnly`. |
 | `The plan uses patterns that cannot be filled with what was supplied: a, b` | A plan was made with icons, assets or fields that are not passed now. | Pass the same `icons`, `assets`, `fields` and `layout` to every step. |
 | `Slide 3: pattern "x" needs icons, and no icon set was supplied` | The same, for an edit. | As above. |
 
@@ -129,6 +130,10 @@ Plain `Error`s from `renderDeck`. They mean the manifest and the pptx disagree,
 | `Gemini did not answer within 180 seconds` | The request hung. Retry, or raise `timeoutMs`. |
 | `Gemini did not return valid JSON: ...` | The model's text was not JSON. Retry. |
 | `Gemini interaction ended with status "..."` | The service did not complete the request; the reason follows when it gives one. |
+| `Gemini's answer was cut off at the limit of 9552 tokens, twice. ...` | The model wrote until the output limit, twice in a row. It is nearly always a model running away inside one text field (see "Runaway answers" in [providers.md](providers.md)). Try again. If it keeps happening, set `thinkingLevel: 'low'`; if the limit is too small for a legitimately large answer, set `maxOutputTokens`. |
+| `Gemini request failed (400): Request blocked due to copyright/recitation content` | The service's recitation filter tripped on an ordinary answer. It happens at random. The adapter already sent the request twice; try again. |
+| `Gemini request failed (400): Thinking level ... is not supported for this model` | The `thinkingLevel` set on the adapter is not one the model accepts (`minimal` is refused by some models). Use `low`, or leave it unset. |
+| `Gemini request failed (429): Your project has exceeded its monthly spending cap` | The key's project reached the spending cap set for it. Nothing works until the cap is raised in the provider's console. |
 | `Gemini returned no image` | The image model answered without a picture, often because the prompt was refused. |
 
 ## The result looks wrong
@@ -141,7 +146,10 @@ Plain `Error`s from `renderDeck`. They mean the manifest and the pptx disagree,
 | Cards are in reverse order in a right-to-left deck | The pattern's items are not declared as a row. | Add a `repeat` (`setRepeat`) or `sequences`. |
 | Hebrew or Arabic text is left-aligned | The manifest keeps alignment. | Set `alignOnDirectionChange: 'flip'` on the manifest or the slot. |
 | A font changes for another script | The template's font lacks that script. | Set a complex-script font in the template. |
+| Body text looks small | The engine keeps the template's own font sizes, and the template was designed with small body text (9 pt on a 10-inch slide is common in decks exported from Google Slides). | For every deck: set `textScale` on the manifest, such as `1.3`. For one deck: `textSize: 'large'` on the brief, `text_size` in the chat tool, or `textScale` on the deck. See "Larger text" in [layout-freedom.md](layout-freedom.md). |
 | The planner never uses a pattern | It is not offered. | See "Reasons a pattern is not offered". Also check the pattern's `description`: the model chooses by it. |
+| A deck that was asked to be "text only" has cards, tables or charts | The wish did not reach the planner as a wish about slides: only "no pictures" was passed (`imageDensity: 'none'`, or `image_density` in the chat tool), which still allows cards, tables and charts. | Set `textOnly: true` on the brief, or `text_only: true` in `plan_presentation`. See "Asking for a kind of slide" in [generating.md](generating.md). |
+| A text-only deck uses one layout for every content slide | The template has one plain text pattern besides its opening and closing. | Add more plain text patterns to the manifest as derived patterns: a list without its photo, a quotation, two paragraphs side by side. |
 | A slide states a number or contact detail that nobody gave | The model invented it. | Figures are guarded only for patterns marked `figures` and for charts. State details in the brief and review the deck. |
 
 ## Known limits

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slotdeck",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Turn a PowerPoint template into new decks: a model plans the slides, the code clones the template's own slides and fills them.",
   "keywords": [
     "pptx",