@tycoworks/tycoslide 0.10.0 → 0.11.0

package/README.md

@@ -35,6 +35,8 @@ layout: Body
 title: Highlights
 ---
 
+::body::
+
 - Revenue up 12% quarter-over-quarter
 - Three major product launches completed
 ```
@@ -50,7 +52,7 @@ npx tycoslide build deck.md               # → deck.pptx
 ```bash
 npx tycoslide build deck.md       # markdown → PPTX (theme resolved from deck frontmatter)
 npx tycoslide build deck.md --no-notes   # omit speaker notes from the output
-npx tycoslide package             # generate the Agent Skill (skill.md, syntax.md, manifest.json at the theme root) + an uploadable <package-name>.zip
+npx tycoslide package             # regenerate skill.md/syntax.md/manifest.json + zip the whole theme into a self-contained <package-name>.zip
 ```
 
 ## Theme Structure

package/SKILL.md

@@ -21,8 +21,6 @@ This installs the tycoslide engine and its dependencies. You only need to do thi
 
 This skill builds on-brand decks from a markdown deck file. The theme provides slide layouts that control design. Your job: pick the right layouts, fill them with content, and build. You never restyle the layout; the engine clones the real slides, so brand, layout, fonts, and chrome come for free.
 
-For brand voice and naming guidelines, read `brand.md` if it exists alongside this skill.
-
 ## Quick Reference
 
 | Task | Guide |
@@ -37,21 +35,25 @@ For brand voice and naming guidelines, read `brand.md` if it exists alongside th
 
 Before writing anything, read `manifest.json`. It contains:
 
-- **layouts** -- for each: `name`, `description`, `parameters` (frontmatter inputs) and `slots` (body regions), each with `type` and optionally `required`, `limit`, `codeTheme`, `mermaidVariant` (plus, for assets, a `type` of `icon`/`image`/`background`), plus documentation (`whenToUse`, `whenNotToUse`)
-- **assets** -- brand logos, client logos, illustrations, and icons (`description`, `whenToUse`)
+- **layouts** -- for each: `name`, `description`, `parameters` (frontmatter inputs) and `slots` (body regions), each with `accepts` and optionally `required` (plus, for assets, a `type` of `icon`/`image`/`background`)
+- **assets** -- brand logos, client logos, illustrations, and icons (`description`)
 
 A layout's inputs split two ways (see [syntax.md](syntax.md) for details):
 - **parameters** -- one value on a frontmatter line. Types: `template`, `image`. Fill by putting a value under the parameter's key in the slide frontmatter.
-- **slots** -- a multi-line region in the body. Types: `text`, `table`, `code`, `mermaid`. Fill as the default body region (after the closing `---`) or a `::name::` region.
+- **slots** -- a multi-line region in the body. Accept types: `text`, `table`, `image`. Fill as a `::name::` region; a fenced code block routes to a `text` slot, a fenced mermaid block to an `image` slot.
+
+A slot may accept more than one content type -- the manifest lists each slot's `accepts`, and the shape of the content you write selects which one.
 
-A single physical slide may back multiple layouts. When two manifest entries share the same `slideNumber`, they render into the same underlying PPTX shapes but declare their fill differently -- e.g. one layout exposing the fill as an `image` parameter and a sibling exposing it as a `mermaid` slot. Pick between them by naming the layout you want in frontmatter (`layout: Full bleed diagram` vs `layout: Full bleed image`); the declaration is unambiguous per layout, so the compiler always knows how to interpret the content you provide.
+Parameters and slots you leave unfilled are dropped from the slide, so a layout with numbered slots (several sections, stats, columns) renders only the ones you fill -- fill as many as you have.
 
-Study each layout's `slots` and `limit`s before writing any slides.
+Study each layout's `slots` before writing any slides.
 
 ---
 
 ## Creating Slides
 
+> **Every layout, parameter, and slot name in the examples below is a placeholder.** Your theme's real names live in `manifest.json` — read it first, and never assume a name shown in an example exists in your theme.
+
 Write a deck file in markdown. The file starts with a global frontmatter block declaring the theme, followed by slides separated by `---`.
 
 ```markdown
@@ -60,8 +62,8 @@ theme: ./theme.json
 ---
 
 ---
-layout: Title
-title: Q2 Business Review
+layout: Title             # ← a layout from your manifest.json
+title: Q2 Business Review # ← a parameter that layout declares
 subtitle: Engineering Division
 ---
 
@@ -80,7 +82,7 @@ A text shape that holds several lines (e.g. an attribution with a name over a ti
 
 A deck file has three parts:
 
-1. **Global frontmatter** (required) -- the first `---`-delimited block. Must contain `theme:` pointing to the theme config file. May also contain `output:` to set the filename (defaults to `deck.md` → `deck.pptx`).
+1. **Global frontmatter** (required) -- the first `---`-delimited block. Must contain `theme:` pointing to the theme config file. The output `.pptx` is written next to the deck, named after it (`deck.md` → `deck.pptx`).
 2. **Slides** -- each begins with a `---` separator. A slide's frontmatter sits between `---` delimiters. Body content follows the closing `---`.
 3. **Slide separators** -- a `---` on its own line separates slides.
 
@@ -98,53 +100,49 @@ subtitle: This Quarter
 
 - `layout` is required and consumed by the compiler (not forwarded as content).
 - All other frontmatter keys fill parameters: `title` fills the `title` template parameter, `subtitle` fills the `subtitle` parameter, `hero` fills the `hero` image parameter, etc. A multi-line text shape surfaces as several keys (e.g. `name` + `jobTitle`); fill each as its own scalar line.
-- Slots (`text`, `table`, `code`, `mermaid`) are filled by body regions, not frontmatter -- see below.
+- Slots (accepting `text`, `table`, `image`) are filled by body regions, not frontmatter -- see below.
 - A slide may also carry a `notes:` block in frontmatter -- plain-text speaker notes for the slide's notes page (see [syntax.md](syntax.md#speaker-notes)). It is slide-level metadata, not a parameter or slot.
 
 ### Body content, slots, and formatting
 
-See [syntax.md](syntax.md) for the full syntax reference: body content (paragraphs, bullets, nesting), inline formatting (bold, italic, strikethrough, underline, hyperlinks), named slots (`::name::` markers), the parameter/slot split (parameters: template, image; slots: text, table, code, mermaid), and image parameters.
+See [syntax.md](syntax.md) for the full syntax reference: body content (paragraphs, bullets, nesting), inline formatting (bold, italic, strikethrough, underline, hyperlinks), named slots (`::name::` markers), the parameter/slot split (parameters: template, image; slots accept: text, table, image), and image parameters.
 
 ### Build
 
-Run the command from `manifest.json`'s `build.command`:
+Build the deck (replace `<deck.md>` with your deck file):
 
 ```bash
-# e.g.: npx tycoslide build deck.md
+npx tycoslide build <deck.md>
 ```
 
-The deck is written to your current working directory (not inside the skill).
+The `.pptx` is written next to your deck file (same directory as `<deck.md>`).
 
 ---
 
 ## Layout Selection
 
-**Don't create boring decks.** Repeating the same layout on every slide makes a forgettable presentation. Use variety and match content shape to layout purpose.
+**Don't create boring decks.** Repeating the same layout on every slide makes a forgettable presentation. Use variety and match content shape to the layout's slots.
 
 ### Before Starting
 
-1. **Read the manifest thoroughly.** Each layout has `whenToUse`, `whenNotToUse`, and `limit`s. Respect all three.
-2. **Match content shape to layout purpose.** A comparison belongs in a two/three-column layout, quantified proof belongs in stat blocks, a customer voice belongs in a quote or testimonial layout. Don't force content into the wrong layout.
-3. **Plan narrative arc first.** Decide the sequence of ideas before picking layouts. Then assign each idea to its best-fit layout from the manifest. Keep one variant (all dark or all light) across the deck.
+1. **Read the manifest thoroughly.** Each layout declares its `slots` (and the `accepts` types each one takes) -- the shape of what it can hold. Respect them.
+2. **Match content shape to the layout's slots.** A comparison fits a layout with two or three text columns; quantified proof fits one with stat slots; a customer voice fits a quote slot. The slots tell you what fits -- don't force content into the wrong shape.
+3. **Assign each idea to its best-fit layout** from the manifest. Some layouts come in more than one variant (e.g. a dark and a light version, shown in the name) — consider which suits the deck.
 
 ### For Each Slide
 
-**Every slide communicates one idea.** If you're writing more than 5 bullets or 3 paragraphs, split into two slides. Put the takeaway in the headline, then support it.
+**Every slide communicates one idea.** Put the takeaway in the headline, then support it.
 
-Check each layout's `limit` in the manifest for content density constraints. When content overflows, split across slides.
+Keep each slot's content to what its region comfortably holds. When content overflows, split it across slides.
 
 ### Avoid (Common Mistakes)
 
 - **Don't repeat the same layout** -- vary layouts for visual rhythm
-- **Don't dump all content on one slide** -- two clear slides beat one crowded slide
-- **Don't ignore layout limits** -- if a slot says max 4 stats, use 4 or fewer
-- **Don't open with a body/content layout** -- use the Title layout for impact
-- **Don't skip section dividers** -- for decks over 5 slides, use Section title layouts to group sections
+- **Don't overstuff a slot** -- keep content to what its region comfortably holds; split across slides when there's too much
 - **Don't restyle the layout** -- the theme owns all design; you only fill slots
 - **Don't use an image that's wrong for the slot** -- a small slot wants a simple icon, not a dense illustration; if the build warns an image shrank to a small %, swap it for a simpler one
 - **Don't invent layout or asset names** -- only use what exists in the manifest
 - **Don't leave required parameters or slots empty** -- and don't leave a placeholder logo or dummy text in an image parameter you care about
-- **Don't mix dark and light** -- keep one variant across the deck
 
 ---
 
@@ -154,15 +152,7 @@ Check each layout's `limit` in the manifest for content density constraints. Whe
 
 Your first draft almost never comes out clean. Approach QA as a debugging session, not a confirmation step. If you haven't run at least one build-fix cycle, you're not done.
 
-### Build
-
-Run the command from `manifest.json`'s `build.command`:
-
-```bash
-# e.g.: npx tycoslide build deck.md
-```
-
-Read output carefully. Common errors and fixes:
+Build the deck again ([Build](#build)) and read the output carefully. Common errors and fixes:
 
 | Error | Fix |
 |-------|-----|
@@ -172,7 +162,7 @@ Read output carefully. Common errors and fixes:
 | YAML parse error | Fix the YAML syntax in the slide's frontmatter |
 | `Skipped setting relation target` | The asset image couldn't be placed; check the path and file |
 | `forbidden style directive` | Remove `style`, `classDef`, `linkStyle`, or `%%{init}` from your mermaid block -- use `class` for grouping instead |
-| `mermaid-cli is required` | Install mermaid-cli: `npm i -D @mermaid-js/mermaid-cli` |
+| `Mermaid render failed` | The engine renders diagrams with Playwright's Chromium; install it once with `npx playwright install chromium` |
 | `no "mermaid" block` | The theme has no mermaid color config -- add a `mermaid` section to theme.json |
 
 ### Verification Loop
@@ -213,12 +203,9 @@ After a successful build, spawn a subagent:
 Review this deck. Assume there are issues -- find them.
 
 Check for:
-- Slides that are too dense (>7 bullets, >5 paragraphs, too many stats/rows)
+- Slides where content overflows its slot (more bullets/stats/rows than the region holds)
 - Same layout repeated multiple times with no variety
-- Content that doesn't match layout purpose (check whenToUse in manifest.json)
-- Narrative that doesn't flow logically
-- Missing opening (Title) or closing (Thank you) slide
-- Slides that are too sparse (a single bullet doesn't need its own slide)
+- Content that doesn't match the layout's slots (check `accepts` in manifest.json)
 - Leftover placeholder logos or dummy text in the rendered images
 
 For each issue, suggest a specific fix.
@@ -234,16 +221,3 @@ If the subagent finds issues, fix them and rebuild.
 ## Full Example
 
 See [syntax.md](syntax.md#full-example) for a complete multi-slide deck example.
-
----
-
-## Core Commands
-
-```bash
-# Build a deck (use command from manifest.json's build.command)
-# e.g.: npx tycoslide build deck.md
-
-# Render to images for visual QA
-soffice --headless --convert-to pdf --outdir . <deck>.pptx
-pdftoppm -png -r 96 <deck>.pdf <name>
-```

package/dist/cli.js

@@ -5,14 +5,13 @@ import { Command } from "commander";
 import { buildDeck } from "./index.js";
 import { generateManifest } from "./manifest.js";
 import { compileDeck, loadThemeConfig, parseSlideDocument, RESERVED_KEY } from "./markdown/index.js";
-import { renameSkill, zipSkill } from "./skillZip.js";
+import { renameSkill, zipDir } from "./skillZip.js";
 const DEFAULT_CONFIG = "theme.json";
 const MANIFEST_FILE = "manifest.json";
 // The theme skill is written as lowercase skill.md (copied from tycoslide's own
 // SKILL.md), so the skill folder can live at the theme repo root.
 const SKILL_FILE = "skill.md";
 const SYNTAX_FILE = "syntax.md";
-const BUILD_COMMAND = "npx tycoslide build";
 const sdkDir = dirname(fileURLToPath(import.meta.url));
 const skillMdPath = resolve(sdkDir, "..", "SKILL.md");
 const syntaxMdPath = resolve(sdkDir, "..", SYNTAX_FILE);
@@ -45,8 +44,9 @@ program
     }
     const config = loadThemeConfig(absConfigPath);
     const deck = await compileDeck(doc, config);
-    if (!deck.output)
-        deck.output = basename(deckPath).replace(/\.md$/, ".pptx");
+    // Always write the .pptx next to the input deck, named after it.
+    const outName = basename(deckPath).replace(/\.md$/, ".pptx");
+    deck.output = resolve(dirname(absDeckPath), outName);
     await buildDeck(deck, config, { excludeNotes: !opts.notes });
 });
 program
@@ -61,7 +61,7 @@ program
     }
     // basename drops any npm scope, e.g. "@acme/mz-slides" -> "mz-slides".
     const skillName = basename(themePkg.name);
-    const manifestJson = `${generateManifest(config, { build: { command: BUILD_COMMAND } })}\n`;
+    const manifestJson = `${generateManifest(config)}\n`;
     writeFileSync(resolve(process.cwd(), MANIFEST_FILE), manifestJson);
     console.log(`WROTE ${MANIFEST_FILE}`);
     let skillMd;
@@ -76,13 +76,10 @@ program
     const syntaxMd = readFileSync(syntaxMdPath, "utf-8");
     writeFileSync(resolve(process.cwd(), SYNTAX_FILE), syntaxMd);
     console.log(`WROTE ${SYNTAX_FILE}`);
+    // Bundle the WHOLE theme so the skill is self-contained: unzip ->
+    // `npm install` (pulls the engine + its deps) -> `npx tycoslide build`.
     const zipFile = `${skillName}.zip`;
-    const zipBuf = await zipSkill(skillName, [
-        { name: SKILL_FILE, content: skillMd },
-        { name: SYNTAX_FILE, content: syntaxMd },
-        { name: MANIFEST_FILE, content: manifestJson },
-    ]);
-    writeFileSync(resolve(process.cwd(), zipFile), zipBuf);
+    writeFileSync(resolve(process.cwd(), zipFile), await zipDir(process.cwd(), skillName));
     console.log(`WROTE ${zipFile}`);
 });
 await program.parseAsync(process.argv);

package/dist/engine/fillers/filler.d.ts

@@ -15,16 +15,42 @@
  * Element-level geometry lives in the `fillX` primitives; cross-shape concerns
  * (media pre-swap for images) live in the callbacks here.
  */
-import { SlotType } from "../types.js";
-/** The shape a filler targets, plus its slot-level options (startAt for text). */
-export type FillTarget = {
+import { type BodyRows, SlotType } from "../types.js";
+/**
+ * The shape a filler targets — a union discriminated by `type` (mirroring the
+ * `Block` variants), so each filler's callback sees only its own specimen
+ * options. Every target carries a `shapeName` and a human `label` for
+ * diagnostics (the author-facing "slide N, layout …, slot …" a filler prints in
+ * advisory warnings instead of the raw PPTX shape id); a text target may carry
+ * `startAt`, and a table target carries its required `bodyRows` range.
+ */
+export type TemplateFillTarget = {
+    type: typeof SlotType.Template;
+    shapeName: string;
+    label: string;
+};
+export type TextFillTarget = {
+    type: typeof SlotType.Text;
     shapeName: string;
+    label: string;
     startAt?: number;
 };
+export type TableFillTarget = {
+    type: typeof SlotType.Table;
+    shapeName: string;
+    label: string;
+    bodyRows: BodyRows;
+};
+export type ImageFillTarget = {
+    type: typeof SlotType.Image;
+    shapeName: string;
+    label: string;
+};
+export type FillTarget = TemplateFillTarget | TextFillTarget | TableFillTarget | ImageFillTarget;
 /** A pptx-automizer element-modify callback: `(element, relation) => void`. */
 export type ShapeCallback = (element: any, relation: any) => unknown;
-export interface Filler<T> {
+export interface Filler<T, Tgt extends FillTarget = FillTarget> {
     matches(v: unknown): v is T;
-    callbacks(value: T, target: FillTarget): ShapeCallback[];
+    callbacks(value: T, target: Tgt): ShapeCallback[];
 }
 export declare const FILLERS: Record<SlotType, Filler<any>>;

package/dist/engine/fillers/filler.js

@@ -22,26 +22,34 @@ import { fillImage, isImageFill } from "./image.js";
 import { fillTable, isTableFill } from "./table.js";
 import { fillTemplate, isTemplateFill } from "./template.js";
 import { fillText, isTextFill } from "./text.js";
+const templateFiller = {
+    matches: isTemplateFill,
+    callbacks: (v, t) => [(el) => fillTemplate(el, v, t.shapeName)],
+};
+const textFiller = {
+    matches: isTextFill,
+    callbacks: (v, t) => [
+        (el, relation) => fillText(el, v, { startAt: t.startAt ?? 0, relation, shapeName: t.shapeName }),
+    ],
+};
+// `t` is a TableFillTarget, so `t.bodyRows` is a guaranteed `BodyRows` tuple.
+// `targetOf` builds this target from a `TableBlock`, whose `bodyRows` is required,
+// and the Zod theme schema rejects a table block without a `bodyRows` range; a
+// table filler therefore cannot be reached without one.
+const tableFiller = {
+    matches: isTableFill,
+    callbacks: (v, t) => [(el) => fillTable(el, v, t.shapeName, t.bodyRows)],
+};
+const imageFiller = {
+    matches: isImageFill,
+    callbacks: (v, t) => [
+        ModifyImageHelper.setRelationTarget(basename(v.path)),
+        (el) => fillImage(el, v, t.shapeName, t.label),
+    ],
+};
 export const FILLERS = {
-    [SlotType.Template]: {
-        matches: isTemplateFill,
-        callbacks: (v, t) => [(el) => fillTemplate(el, v, t.shapeName)],
-    },
-    [SlotType.Text]: {
-        matches: isTextFill,
-        callbacks: (v, t) => [
-            (el, relation) => fillText(el, v, { startAt: t.startAt ?? 0, relation, shapeName: t.shapeName }),
-        ],
-    },
-    [SlotType.Table]: {
-        matches: isTableFill,
-        callbacks: (v, t) => [(el) => fillTable(el, v, t.shapeName)],
-    },
-    [SlotType.Image]: {
-        matches: isImageFill,
-        callbacks: (v, t) => [
-            ModifyImageHelper.setRelationTarget(basename(v.path)),
-            (el) => fillImage(el, v, t.shapeName),
-        ],
-    },
+    [SlotType.Template]: templateFiller,
+    [SlotType.Text]: textFiller,
+    [SlotType.Table]: tableFiller,
+    [SlotType.Image]: imageFiller,
 };

package/dist/engine/fillers/image.d.ts

@@ -42,7 +42,7 @@ export type GeometryResult = {
  * `image.path` is assumed absolute — the compiler / caller resolves it before the
  * ImageFill reaches the engine.
  */
-export declare function fillImage(shape: any, image: ImageFill, shapeName?: string): void;
+export declare function fillImage(shape: any, image: ImageFill, shapeName: string, label: string): void;
 /**
  * Pure fit geometry — no DOM, so it is trivially unit-testable in isolation.
  * `fit` picks the strategy: `cover` scales to the larger axis ratio and

package/dist/engine/fillers/image.js

@@ -30,7 +30,7 @@ const MIN_SCALE = 0.2;
  * `image.path` is assumed absolute — the compiler / caller resolves it before the
  * ImageFill reaches the engine.
  */
-export function fillImage(shape, image, shapeName = "") {
+export function fillImage(shape, image, shapeName, label) {
     const dims = imageSize(new Uint8Array(readFileSync(image.path)));
     if (!dims.width || !dims.height) {
         throw new Error(`Image shape "${shapeName}": could not read image dimensions from "${image.path}".`);
@@ -49,7 +49,7 @@ export function fillImage(shape, image, shapeName = "") {
     };
     const { geometry, warnings } = computeGeometry(frame, dims.width, dims.height, image.fit);
     for (const w of warnings)
-        console.warn(`Image "${shapeName}": ${w}`);
+        console.warn(`Image ${label}: ${w}`);
     if (geometry.placement === Placement.Crop) {
         // fill: symmetric crop on the overflowing axis, written as srcRect insets.
         applySrcRect(shape, blipFill, geometry.left, geometry.top, geometry.left, geometry.top);

package/dist/engine/fillers/table.d.ts

@@ -1,22 +1,39 @@
 /**
- * Table fill — clones the template's specimen rows in `<a:tbl>` (row 0 header,
- * row 1 data, optional row 2 zebra) and fills each cell's first paragraph with
- * the corresponding StyledParagraph. Cells and `<a:gridCol>` entries are cloned
- * or trimmed to the header count, sharing the template's total width. Row, cell,
- * and grid cloning stay engine-side because they need pptx-automizer DOM access.
+ * Table fill — composes a variable number of output rows from a fixed table
+ * specimen in `<a:tbl>` by cloning specimen rows around one contiguous `bodyRows`
+ * range, then fills each cell's first paragraph with the corresponding
+ * StyledParagraph. Row 0 styles the header; the rows before the range are top
+ * fixed rows (rendered once — the under-header row lives here, never looped, so
+ * its divider survives); the `[start, end]` range is the repeatable body, cycled
+ * to fill the deck's data; the rows after it are bottom fixed rows (rendered once
+ * — a decorated total row lives here). `<a:tcPr>` (fill, borders, margins) is
+ * preserved per row — only the cell text is rebuilt. Cells and `<a:gridCol>`
+ * entries are cloned or trimmed to the header count, sharing the template's total
+ * width. Row, cell, and grid cloning stay engine-side because they need
+ * pptx-automizer DOM access.
  */
-import type { TableFill } from "../types.js";
+import type { BodyRows, TableFill } from "../types.js";
 /**
- * Fill a table shape by cloning specimen rows.
- *
- * Row layout in the template's `<a:tbl>`:
- *   - Row 0: header specimen
- *   - Row 1: data specimen
- *   - Row 2 (optional): alternating-data specimen (zebra striping)
- *
- * Each cell's first paragraph is rebuilt from the corresponding
- * StyledParagraph, so tables inherit rich-run/bullet support for free.
+ * Validate a `bodyRows = [start, end]` range against a specimen's actual row
+ * count `R`, then compose the `K` specimen-row picks that back the deck's `K` data
+ * rows (row 0 always styles the header, so it is not a pick). Everything outside
+ * the range is a fixed row rendered once: rows `[1, start-1]` (top — the
+ * under-header row, never looped, so its divider survives) back the first data
+ * rows; the `[start, end]` range cycles to fill the middle; rows `[end+1, R-1]`
+ * (bottom — a decorated total row) back the last data rows. Throws (naming the
+ * shape) when the range is out of bounds or the deck supplies too few rows to fill
+ * the fixed rows.
  */
-export declare function fillTable(shape: any, table: TableFill, shapeName?: string): void;
+export declare function resolveRowPlan(bodyRows: BodyRows, R: number, K: number, shapeName: string): {
+    headerIdx: number;
+    picks: number[];
+};
+/**
+ * Fill a table shape by composing its specimen rows per the body-range plan (see
+ * `resolveRowPlan`). Each output cell's first paragraph is rebuilt from the
+ * corresponding StyledParagraph, so tables inherit rich-run/bullet support for
+ * free; the specimen row's `<a:tcPr>` is carried over untouched.
+ */
+export declare function fillTable(shape: any, table: TableFill, shapeName: string, bodyRows: BodyRows): void;
 /** Discriminator for TableFill values. */
 export declare function isTableFill(v: unknown): v is TableFill;

package/dist/engine/fillers/table.js

@@ -1,9 +1,16 @@
 /**
- * Table fill — clones the template's specimen rows in `<a:tbl>` (row 0 header,
- * row 1 data, optional row 2 zebra) and fills each cell's first paragraph with
- * the corresponding StyledParagraph. Cells and `<a:gridCol>` entries are cloned
- * or trimmed to the header count, sharing the template's total width. Row, cell,
- * and grid cloning stay engine-side because they need pptx-automizer DOM access.
+ * Table fill — composes a variable number of output rows from a fixed table
+ * specimen in `<a:tbl>` by cloning specimen rows around one contiguous `bodyRows`
+ * range, then fills each cell's first paragraph with the corresponding
+ * StyledParagraph. Row 0 styles the header; the rows before the range are top
+ * fixed rows (rendered once — the under-header row lives here, never looped, so
+ * its divider survives); the `[start, end]` range is the repeatable body, cycled
+ * to fill the deck's data; the rows after it are bottom fixed rows (rendered once
+ * — a decorated total row lives here). `<a:tcPr>` (fill, borders, margins) is
+ * preserved per row — only the cell text is rebuilt. Cells and `<a:gridCol>`
+ * entries are cloned or trimmed to the header count, sharing the template's total
+ * width. Row, cell, and grid cloning stay engine-side because they need
+ * pptx-automizer DOM access.
  */
 import { Attr, collectElements, isPlainObject, rebuildParagraphs, Tag } from "../dom.js";
 const EMPTY_CELL = { runs: [{ text: "" }] };
@@ -50,30 +57,58 @@ function reconcileGrid(tbl, n) {
     }
 }
 /**
- * Fill a table shape by cloning specimen rows.
- *
- * Row layout in the template's `<a:tbl>`:
- *   - Row 0: header specimen
- *   - Row 1: data specimen
- *   - Row 2 (optional): alternating-data specimen (zebra striping)
- *
- * Each cell's first paragraph is rebuilt from the corresponding
- * StyledParagraph, so tables inherit rich-run/bullet support for free.
+ * Validate a `bodyRows = [start, end]` range against a specimen's actual row
+ * count `R`, then compose the `K` specimen-row picks that back the deck's `K` data
+ * rows (row 0 always styles the header, so it is not a pick). Everything outside
+ * the range is a fixed row rendered once: rows `[1, start-1]` (top — the
+ * under-header row, never looped, so its divider survives) back the first data
+ * rows; the `[start, end]` range cycles to fill the middle; rows `[end+1, R-1]`
+ * (bottom — a decorated total row) back the last data rows. Throws (naming the
+ * shape) when the range is out of bounds or the deck supplies too few rows to fill
+ * the fixed rows.
  */
-export function fillTable(shape, table, shapeName = "") {
+export function resolveRowPlan(bodyRows, R, K, shapeName) {
+    const [start, end] = bodyRows;
+    // Row 0 is the header, so the body must start at 1 or later; the range must be
+    // non-empty and stay within the specimen's rows.
+    if (!(start >= 1 && start <= end && end <= R - 1)) {
+        throw new Error(`Table shape "${shapeName}": bodyRows [${start}, ${end}] is out of range; require 1 <= start <= end <= ${R - 1} (row 0 is the header).`);
+    }
+    const topFixed = start - 1; // rows [1, start-1]
+    const bottomFixed = R - 1 - end; // rows [end+1, R-1]
+    const bodyCount = K - topFixed - bottomFixed;
+    const span = end - start + 1;
+    // The deck must supply enough data rows to back every fixed row (top + bottom);
+    // below that there is nothing to cycle the body over and the total row goes unfilled.
+    if (bodyCount < 0) {
+        throw new Error(`Table shape "${shapeName}": deck supplies ${K} data row(s) but the specimen's fixed rows need at least ${topFixed + bottomFixed}.`);
+    }
+    const picks = [];
+    for (let r = 1; r <= start - 1; r++)
+        picks.push(r); // top fixed
+    for (let i = 0; i < bodyCount; i++)
+        picks.push(start + (i % span)); // body, cycled
+    for (let r = end + 1; r <= R - 1; r++)
+        picks.push(r); // bottom fixed
+    return { headerIdx: 0, picks };
+}
+/**
+ * Fill a table shape by composing its specimen rows per the body-range plan (see
+ * `resolveRowPlan`). Each output cell's first paragraph is rebuilt from the
+ * corresponding StyledParagraph, so tables inherit rich-run/bullet support for
+ * free; the specimen row's `<a:tcPr>` is carried over untouched.
+ */
+export function fillTable(shape, table, shapeName, bodyRows) {
     const tbl = shape.getElementsByTagName(Tag.TABLE)[0];
     if (!tbl) {
         throw new Error(`Table shape "${shapeName}": has no <a:tbl> element (is it actually a table?).`);
     }
-    const rows = collectElements(tbl, Tag.TABLE_ROW);
-    if (rows.length < 2) {
-        throw new Error(`fillTable: template table has ${rows.length} row(s), need at least 2 (header + data specimen)`);
+    const specimenRows = collectElements(tbl, Tag.TABLE_ROW);
+    const R = specimenRows.length;
+    if (R < 2) {
+        throw new Error(`fillTable: template table has ${R} row(s), need at least 2 (header + data specimen)`);
     }
-    const headerTpl = rows[0];
-    // Only rows 0-2 are specimens (header, data, optional zebra); any further
-    // template rows are intentionally dropped — the specimen rows are re-cloned
-    // per data row below.
-    const dataTpls = rows.length > 2 ? [rows[1], rows[2]] : [rows[1]];
+    const { headerIdx, picks } = resolveRowPlan(bodyRows, R, table.rows.length, shapeName);
     // Headers are the source of truth for column count; every row is normalized to
     // it, and short/long data rows are padded/truncated to match.
     const n = table.headers.length;
@@ -88,15 +123,15 @@ export function fillTable(shape, table, shapeName = "") {
         return clone;
     };
     const built = [];
-    built.push(fillRow(headerTpl, table.headers));
-    for (let r = 0; r < table.rows.length; r++) {
-        built.push(fillRow(dataTpls[r % dataTpls.length], table.rows[r]));
+    built.push(fillRow(specimenRows[headerIdx], table.headers));
+    for (let r = 0; r < picks.length; r++) {
+        built.push(fillRow(specimenRows[picks[r]], table.rows[r]));
     }
     // Column invariant: grid `<a:gridCol>` count must equal every row's `<a:tc>`
     // count (both == n). `normalizeCellCount` (in fillRow) holds the per-row half;
     // `reconcileGrid` holds the grid half. Run the grid half once, table-global.
     reconcileGrid(tbl, n);
-    for (const row of rows)
+    for (const row of specimenRows)
         tbl.removeChild(row);
     for (const row of built)
         tbl.appendChild(row);

package/dist/engine/generate.d.ts

@@ -26,7 +26,7 @@
  *
  * `generate()` is first below; its helpers follow (function declarations hoist).
  */
-import type { Config, Deck, DeckStep, Layout } from "./types.js";
+import { type Config, type Deck, type DeckStep, type Layout } from "./types.js";
 /** Options for `generate` / `buildDeck`. */
 export type GenerateOptions = {
     /**
@@ -53,12 +53,13 @@ export declare function generate(deck: Deck, config: Config, options?: GenerateO
 /**
  * Fill one cloned slide. Per slot the step supplies a value for: resolve WHICH
  * shape realizes it (`resolveBlock`), build WHAT to write (`FILLERS[…].callbacks`),
- * and place it WHERE/HOW (`applyBlock`). Every ambiguity fails fast, naming layout
- * + slot.
+ * and place it WHERE/HOW (`applyBlock`). A slot the step leaves unfilled has its
+ * base-slide shape removed, so a layout with numbered slots renders exactly the
+ * ones supplied. Every ambiguity fails fast, naming layout + slot.
  *
  * Exported for tests; `generate()` calls it inside the `addSlide` callback.
  */
-export declare function fillSlide(slide: any, layout: Layout, step: DeckStep, sourceAlias: string): void;
+export declare function fillSlide(slide: any, layout: Layout, step: DeckStep, sourceAlias: string, slideNumber: number): void;
 /**
  * Reject a slot whose `accepts` lists two blocks of the same type — the
  * value→block lookup would silently pick the first. Called once per layout at