@tycoworks/tycoslide 0.10.1 → 0.11.0

package/dist/markdown/schema/themeConfigSchema.js

@@ -21,9 +21,12 @@ import { strict } from "./strict.js";
  * `z.record`, open by design); strictness lands on their leaf entries.
  */
 // Reuse the const-object enums as runtime values — no third copy of the literals.
-const acceptTypeSchema = z.enum(Object.values(AcceptType));
 const assetTypeSchema = z.enum(Object.values(AssetType));
 const variantSchema = z.enum(Object.values(Variant));
+// A table specimen's repeatable row range: `[start, end]`, 0-based inclusive,
+// non-negative integers. The range is validated against the specimen's actual row
+// count at fill time, where the row count is known.
+const bodyRowsSchema = z.tuple([z.number().int().nonnegative(), z.number().int().nonnegative()]);
 // Re-declared here (not imported from the engine) so the schema layer never
 // depends on the engine — mirrors engine `Frame`, guarded by `_drift`.
 const FrameSchema = strict({
@@ -32,16 +35,10 @@ const FrameSchema = strict({
     cx: z.number(),
     cy: z.number(),
 });
-const LimitSchema = strict({
-    maxChars: z.number().optional(),
-    maxLines: z.number().optional(),
-    maxItems: z.number().optional(),
-});
 const AssetEntrySchema = strict({
     path: z.string(),
     type: assetTypeSchema,
     description: z.string(),
-    whenToUse: z.string().optional(),
 });
 // AssetCatalog: `{ category: { name: AssetEntry } }`. The two record levels are
 // OPEN (names are user-defined); only the leaf entry is strict.
@@ -68,7 +65,6 @@ const ThemeFontSchema = strict({
 });
 const TemplateParamSchema = strict({
     shapeName: z.string(),
-    limit: LimitSchema.optional(),
     required: z.boolean().optional(),
     type: z.literal(ParameterType.Template),
     template: z.string(),
@@ -80,25 +76,38 @@ const ImageParamSchema = strict({
     type: z.literal(ParameterType.Image),
 });
 const ParameterSchema = z.discriminatedUnion("type", [TemplateParamSchema, ImageParamSchema]);
-const BlockSchema = strict({
-    type: acceptTypeSchema,
+// One arm per accept type, discriminated by `type`, mirroring `CompilerBlock`:
+// `startAt` lives only on the text arm, and `bodyRows` only on the table arm (a
+// table block MUST declare its repeatable-row range; text/image arms have no
+// `bodyRows` field, so a stray one is an unknown key the `strict` arm rejects).
+const TextBlockSchema = strict({
+    type: z.literal(AcceptType.Text),
     sourceSlide: z.number(),
     shapeName: z.string(),
     startAt: z.number().optional(),
 });
+const TableBlockSchema = strict({
+    type: z.literal(AcceptType.Table),
+    sourceSlide: z.number(),
+    shapeName: z.string(),
+    bodyRows: bodyRowsSchema,
+});
+const ImageBlockSchema = strict({
+    type: z.literal(AcceptType.Image),
+    sourceSlide: z.number(),
+    shapeName: z.string(),
+});
+const BlockSchema = z.discriminatedUnion("type", [TextBlockSchema, TableBlockSchema, ImageBlockSchema]);
 const SlotSchema = strict({
     key: z.string(),
     accepts: z.array(BlockSchema),
     frame: FrameSchema.optional(),
-    limit: LimitSchema.optional(),
     required: z.boolean().optional(),
 });
 const LayoutSchema = strict({
     name: z.string(),
     slideNumber: z.number(),
     description: z.string().optional(),
-    whenToUse: z.string().optional(),
-    whenNotToUse: z.string().optional(),
     variant: variantSchema.optional(),
     parameters: z.array(ParameterSchema),
     slots: z.array(SlotSchema),
@@ -107,7 +116,6 @@ export const ThemeConfigSchema = strict({
     layouts: z.array(LayoutSchema),
     assets: AssetCatalogSchema,
     template: z.string(),
-    outputDir: z.string().optional(),
     mermaid: MermaidConfigSchema.optional(),
     fonts: z.array(ThemeFontSchema).optional(),
     codeTheme: z.union([z.string(), strict({ light: z.string().min(1), dark: z.string().min(1) })]).optional(),

package/dist/markdown/slideParser.d.ts

@@ -1,7 +1,6 @@
 export interface RawSlide {
     index: number;
     frontmatter: Record<string, unknown>;
-    body: string;
     slots: Record<string, string>;
 }
 export interface ParsedDocument {

package/dist/markdown/slideParser.js

@@ -123,8 +123,11 @@ function splitIntoSlides(text) {
 // ============================================
 function buildSlide(index, fmString, rawContent) {
     const frontmatter = parseFrontmatter(fmString, index);
-    const { defaultSlot, slots } = extractSlots(rawContent);
-    return { index, frontmatter, body: defaultSlot, slots };
+    const { leading, slots } = extractSlots(rawContent);
+    if (leading.trim()) {
+        throw new Error(`Slide ${index + 1}: text found outside a ::slot:: marker`);
+    }
+    return { index, frontmatter, slots };
 }
 export class FrontmatterParseError extends Error {
     constructor(slideIndex, yamlSource, cause) {
@@ -185,12 +188,12 @@ function extractSlots(content) {
             slotLines.get(currentSlot).push(line);
         }
     }
-    const defaultSlot = slotLines.get(null).join("\n").trim();
+    const leading = slotLines.get(null).join("\n").trim();
     const slots = {};
     for (const [name, sLines] of slotLines) {
         if (name !== null) {
             slots[name] = sLines.join("\n").trim();
         }
     }
-    return { defaultSlot, slots };
+    return { leading, slots };
 }

package/dist/markdown/types.d.ts

@@ -1,6 +1,7 @@
 import type { RootContent } from "mdast";
-import { type Frame, type ImageFill, type TableFill, type TemplateFill, type TextFill } from "../engine/index.js";
+import { type BodyRows, type Frame, type ImageFill, type TableFill, type TemplateFill, type TextFill } from "../engine/index.js";
 import type { MermaidConfig } from "./blocks/mermaidTheme.js";
+export type { BodyRows };
 /**
  * An asset's scaling/cropping tolerance, declared in the theme catalog. The
  * compiler maps it to the engine's object-fit `fit`. `icon`: never enlarge,
@@ -23,7 +24,6 @@ export type AssetEntry = {
     /** Required — a missing type is a fail-fast error. */
     type: AssetType;
     description: string;
-    whenToUse?: string;
 };
 /** Two-level catalog: `{ category: { name: AssetEntry } }`. */
 export type AssetCatalog = Record<string, Record<string, AssetEntry>>;
@@ -83,8 +83,8 @@ export type BlockFill = TextFill | TableFill | ImageFill;
  * asset resolver, the diagnostic context to name the offending layout/slide/slot
  * when a region's markdown shape is illegal (a stray standalone block mixed into
  * prose), and the theme-level `config` — from which code/mermaid compile read
- * their one-per-theme style (`codeTheme`, `mermaid`, `mermaidVariant`,
- * `outputDir`), not the slot.
+ * their one-per-theme style (`codeTheme`, `mermaid`, `mermaidVariant`), not the
+ * slot.
  *
  * Lives in types.ts (not in `blocks/registry.ts`, which re-exports it) so a
  * per-kind block file can import it without importing the registry — the registry
@@ -111,7 +111,7 @@ export type BlockContext = {
  * build (`compile`) live together — a new content kind is one file, one registry
  * row. Non-generic like the engine's `Filler`: the array can't correlate a
  * per-element type guard with `compile`'s param, so each handler narrows the node
- * internally with a single-hop cast. Mirrors the old sdk's `SyntaxHandler`.
+ * internally with a single-hop cast.
  */
 export type BlockHandler = {
     match(node: RootContent): boolean;
@@ -138,20 +138,10 @@ export type CompilerDeckStep = {
  */
 export type CompilerDeck = {
     theme: string;
+    /** Output path, set by the caller (the CLI, or a programmatic `buildDeck`), not from frontmatter. */
     output?: string;
     steps: CompilerDeckStep[];
 };
-/**
- * Markdown-flavored measurement hints on a slot or template parameter: caps on
- * expanded run text, line count, or list items. All optional — a missing cap is
- * "no limit." Advisory metadata surfaced in the manifest; the fill never enforces
- * it.
- */
-export type Limit = {
-    maxChars?: number;
-    maxLines?: number;
-    maxItems?: number;
-};
 /**
  * Template parameter: a styled text shape filled by expanding a `template` into the
  * shape's paragraphs via fillTemplate. The template is one string with `{key}`
@@ -162,11 +152,11 @@ export type Limit = {
  */
 export type CompilerTemplateParameter = {
     shapeName: string;
-    limit?: Limit;
     /**
      * Whether the parameter may be omitted from a slide. Optional (defaults to
      * false): a required one with no value causes the compiler to throw with
-     * layout + key names.
+     * layout + key names; an optional one left unfilled has its shape removed
+     * from the slide.
      */
     required?: boolean;
     type: typeof ParameterType.Template;
@@ -174,14 +164,14 @@ export type CompilerTemplateParameter = {
     template: string;
 };
 /** Image parameter: one frontmatter path filled by fillImage. Sizing/crop
- * behaviour comes from the resolved asset's `type`, not the slot. Carries no
- * `limit` — measuring an image path against char/line caps is meaningless. */
+ * behaviour comes from the resolved asset's `type`, not the slot. */
 export type CompilerImageParameter = {
     shapeName: string;
     /**
      * Whether the parameter may be omitted from a slide. Optional (defaults to
      * false): a required one with no value causes the compiler to throw with
-     * layout + key names.
+     * layout + key names; an optional one left unfilled has its shape removed
+     * from the slide.
      */
     required?: boolean;
     key: string;
@@ -193,63 +183,72 @@ export type CompilerImageParameter = {
  */
 export type CompilerParameter = CompilerTemplateParameter | CompilerImageParameter;
 /**
- * Reserved keys in a deck's frontmatter — global (theme, output) and per-slide
- * (layout, body). Exported so callers (e.g. cli.ts) reference the constants
+ * Reserved keys in a deck's frontmatter — global (theme) and per-slide
+ * (layout). Exported so callers (e.g. cli.ts) reference the constants
  * instead of literal strings.
  */
 export declare const RESERVED_KEY: {
     readonly LAYOUT: "layout";
-    readonly BODY: "body";
-    readonly OUTPUT: "output";
     readonly THEME: "theme";
     readonly NOTES: "notes";
 };
 /**
  * A kind of content a slot accepts, and the real template shape that realizes
- * it — the compiler mirror of the engine's `Block`. `type` is an engine content
- * type (`text` | `table` | `image`); `shapeName` names the shape on
- * `sourceSlide` carrying the specimen styling. When `sourceSlide` equals the
+ * it — the compiler mirror of the engine's `Block`, a union discriminated by
+ * `type` (an engine content type: `text` | `table` | `image`) so each variant
+ * carries only its own specimen options. `shapeName` names the shape on
+ * `sourceSlide` carrying the specimen styling; when `sourceSlide` equals the
  * layout's `slideNumber` the shape is already on the cloned slide (fill in
- * place); otherwise it is transplanted into the slot's `frame`. `startAt` is a
- * text-specimen concern (leave the first N specimen paragraphs untouched), only
- * meaningful on a text block. Named `CompilerBlock` to stay distinct from the
- * engine's `Block` and the compiler's `BlockHandler`.
+ * place), otherwise it is transplanted into the slot's `frame`. A text block may
+ * pin `startAt` (leave the first N specimen paragraphs untouched); a table block
+ * MUST declare its `bodyRows` range (the repeatable `<a:tbl>` specimen rows); an
+ * image block carries neither. There is no `Template` variant — `AcceptType` excludes
+ * it (a parameter, not a body block). Named `CompilerBlock` to stay distinct from
+ * the engine's `Block` and the compiler's `BlockHandler`.
  */
-export type CompilerBlock = {
-    type: AcceptType;
+export type CompilerTextBlock = {
+    type: typeof AcceptType.Text;
     sourceSlide: number;
     shapeName: string;
     startAt?: number;
 };
+export type CompilerTableBlock = {
+    type: typeof AcceptType.Table;
+    sourceSlide: number;
+    shapeName: string;
+    bodyRows: BodyRows;
+};
+export type CompilerImageBlock = {
+    type: typeof AcceptType.Image;
+    sourceSlide: number;
+    shapeName: string;
+};
+export type CompilerBlock = CompilerTextBlock | CompilerTableBlock | CompilerImageBlock;
 /**
- * Compiler-facing slot. A layout's body region (the default region, or a
- * `::name::` region), no longer welded to one shape+type: it `accepts` a set of
- * `CompilerBlock`s and owns a `frame` (real observed EMU coordinates, never
+ * Compiler-facing slot. A layout's body region (a `::name::` region): it
+ * `accepts` a set of `CompilerBlock`s and owns a `frame` (real observed EMU coordinates, never
  * computed). The author's markdown shape selects which accepted block a region
  * routes to; a type the slot does not accept fails fast. `frame` is required
  * only when a slot has a transplant block (a block whose `sourceSlide` differs
  * from the layout's `slideNumber`); a base-only slot fills in place and needs
- * none. Adds markdown-flavored `limit` hints on top of the engine's minimal
- * Slot; per-slot `codeTheme` / `mermaidVariant` moved to the theme level.
+ * none.
  */
 export type CompilerSlot = {
     key: string;
     accepts: CompilerBlock[];
     frame?: Frame;
-    limit?: Limit;
     /**
      * Whether the slot may be omitted from a slide. Optional (defaults to false):
-     * a required slot with no content throws with layout + key names.
+     * a required slot with no content throws with layout + key names; an optional
+     * slot left unfilled has its shape removed from the slide.
      */
     required?: boolean;
 };
 export type CompilerLayout = {
     name: string;
     slideNumber: number;
-    /** Optional prose — a layout is a shape, not a purpose (agent-guidance descoped). */
+    /** Optional prose — a neutral description of the arrangement (a layout is a shape, not a purpose). */
     description?: string;
-    whenToUse?: string;
-    whenNotToUse?: string;
     /**
      * The layout's tonal surface. Selects the arm of a `{ light, dark }` `codeTheme`
      * pair for code fences on this layout. Required when `codeTheme` is a pair.
@@ -257,7 +256,7 @@ export type CompilerLayout = {
     variant?: Variant;
     /** Frontmatter inputs (template, image) — one value per `key: value` line. */
     parameters: CompilerParameter[];
-    /** Body regions — the default body or `::name::` regions; each `accepts` blocks. */
+    /** Body regions — `::name::` regions; each `accepts` blocks. */
     slots: CompilerSlot[];
 };
 /**
@@ -286,7 +285,6 @@ export type CompilerThemeConfig = {
     layouts: CompilerLayout[];
     assets: AssetCatalog;
     template: string;
-    outputDir?: string;
     mermaid?: MermaidConfig;
     /**
      * Brand fonts injected as `@font-face` when rendering mermaid, so diagram text

package/dist/markdown/types.js

@@ -49,14 +49,12 @@ export const Variant = {
     Dark: "dark",
 };
 /**
- * Reserved keys in a deck's frontmatter — global (theme, output) and per-slide
- * (layout, body). Exported so callers (e.g. cli.ts) reference the constants
+ * Reserved keys in a deck's frontmatter — global (theme) and per-slide
+ * (layout). Exported so callers (e.g. cli.ts) reference the constants
  * instead of literal strings.
  */
 export const RESERVED_KEY = {
     LAYOUT: "layout",
-    BODY: "body",
-    OUTPUT: "output",
     THEME: "theme",
     NOTES: "notes",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tycoworks/tycoslide",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Create editable, on-brand PowerPoint slides from markdown.",
   "type": "module",
   "main": "dist/index.js",

package/syntax.md

@@ -2,6 +2,8 @@
 
 This document covers the detailed syntax for writing slide content in tycoslide deck files. For an overview of how to create slides, see [SKILL.md](SKILL.md).
 
+> **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 here (`Body`, `TwoColumn`, `hero`, `::left::`, etc.) exists in your theme.
+
 ---
 
 ## Global frontmatter
@@ -11,25 +13,27 @@ Every deck file starts with a global frontmatter block declaring the theme:
 ```markdown
 ---
 theme: ./theme.json
-output: my-deck.pptx
 ---
 ```
 
 - **`theme`** (required) -- path to the theme config file, relative to the deck file.
-- **`output`** -- output filename. Defaults to the deck filename with a `.pptx` extension.
+
+The output `.pptx` is written next to the deck file, named after it (`deck.md` → `deck.pptx`).
 
 ---
 
-## Body content (body slots)
+## Body content
 
-Everything after a slide's closing `---` and before the next slide separator is body content. It maps to the `body` slot as a string array.
+A slide's body is split into named regions with `::name::` markers. Each region fills the slot whose key matches the marker name.
 
 ```markdown
 ---
-layout: Body
+layout: Body            # ← placeholder; use a real layout from your manifest.json
 title: Key Achievements
 ---
 
+::body::
+
 We exceeded targets across all metrics.
 
 - Revenue up 23% quarter-over-quarter
@@ -37,9 +41,9 @@ We exceeded targets across all metrics.
 - Three major product launches completed
 ```
 
-Write body content as paragraphs and bullets:
+Write each region as paragraphs and bullets:
 - `- ` starts a **bullet**; indent **2 spaces per level** to nest (`  - ` = level 1).
-- A line with no marker is a **paragraph** (a lead-in / prose line).
+- A line without a `- ` bullet is a **paragraph** (a lead-in / prose line).
 - Blank lines are ignored (they're visual separators, not content).
 - Do NOT put headings in body content -- the heading is the slide's `title` slot, and a subheading is the `subtitle` slot. Body is paragraphs + bullets only.
 
@@ -77,13 +81,13 @@ title: Before & After
 - Zero-downtime deploys
 ```
 
-Content before the first `::name::` marker goes to the `body` slot. Content after a marker goes to the slot matching that name. The marker names must match the layout's slot keys.
+Content after a marker goes to the slot matching that name. The marker names must match the layout's slot keys.
 
 ---
 
 ## Parameters and slots (in `manifest.json`)
 
-A layout advertises two kinds of author-facing input, split by one rule: **a parameter is one value on a frontmatter line; a slot is a multi-line region in the body** (the default region, or a `::name::` region). In `manifest.json` each layout carries two lists, `parameters` and `slots`:
+A layout advertises two kinds of author-facing input, split by one rule: **a parameter is one value on a frontmatter line; a slot is a multi-line region in the body** (a `::name::` region). In `manifest.json` each layout carries two lists, `parameters` and `slots`:
 
 ```jsonc
 {
@@ -94,8 +98,8 @@ A layout advertises two kinds of author-facing input, split by one rule: **a par
     { "key": "logo",     "type": "image", "required": true }
   ],
   "slots": [
-    { "key": "body", "type": "text" },
-    { "key": "code", "type": "code", "codeTheme": "github-dark" }
+    { "key": "body", "accepts": ["text"] },
+    { "key": "diagram", "accepts": ["image"] }
   ]
 }
 ```
@@ -119,13 +123,11 @@ Fill a parameter by putting a value under its key in the slide's frontmatter.
   hero: assets/diagrams/architecture.png
   ```
 
-### Slot types (body regions)
+### Body content shapes
 
-Fill a slot by writing a region in the body: the default (unmarked) region maps to the `body` slot; a `::name::` marker maps to the slot of that name.
+Fill a slot by writing a `::name::` region in the body; the marker maps to the slot of that name. A slot's manifest entry lists which content types it `accepts` (`text`, `table`, `image`) -- write content whose shape matches one of them:
 
-- **`text`** -- a body block, written as markdown paragraphs and bullets. Paragraphs are rebuilt from the template's specimen paragraph styles. Set it as body content after the closing `---`, or as a named slot with `::name::` markers.
-- **`table`** -- a GFM table. Write it in the slot region between `|`-delimited headers and rows; cells inherit inline formatting (bold, italic, links).
-- **`code`** -- a syntax-highlighted code block. Write a fenced code block with a language tag in the slot region:
+- **text** (slots that accept `text`) -- markdown paragraphs and bullets, rebuilt from the template's specimen paragraph styles. A fenced code block also routes here:
   ````markdown
   ::code::
 
@@ -135,16 +137,15 @@ Fill a slot by writing a region in the body: the default (unmarked) region maps
   WHERE created_at > now() - INTERVAL '5 minutes';
   ```
   ````
-  The language tag (e.g. `sql`, `python`, `typescript`) is required -- it drives syntax highlighting. Colors are applied as native text runs in the output, not images.
-- **`mermaid`** -- a mermaid diagram rendered as a themed PNG (see below). Written as a fenced `mermaid` region; the resulting PNG is shown contained (in its entirety).
+  The language tag (e.g. `sql`, `python`, `typescript`) is required -- it drives syntax highlighting, using the theme's `codeTheme` (set once in `theme.json`, not per slot). Colors are applied as native text runs in the output, not images.
+- **table** (slots that accept `table`) -- a GFM table. Write it in the slot region between `|`-delimited headers and rows; cells inherit inline formatting (bold, italic, links).
+- **image** (slots that accept `image`) -- a picture. A fenced `mermaid` block renders to a themed PNG and fills it (see below).
 
 ---
 
 ## Mermaid diagrams
 
-Mermaid diagrams are rendered as themed PNGs and delivered to any slot declared with `type: mermaid`. Write a fenced code block with the `mermaid` language tag in a named slot whose layout declares that slot as `type: mermaid` (with a `mermaidVariant` naming the theme's color variant). The resulting PNG behaves like any other image in the slot -- always shown in its entirety.
-
-To let the same physical slide accept either an image or a diagram, the theme author declares two layouts with the same `slideNumber` -- one exposing the fill as an `image` parameter (frontmatter path), one as a `mermaid` slot (a fenced region). Authors pick between them by naming the layout in frontmatter; the compiler routes content based on the layout's declaration, so there is no ambiguity.
+Write a fenced code block with the `mermaid` language tag in a named slot that accepts `image`. It renders to a themed PNG and behaves like any other image in the slot -- always shown in its entirety. The color variant comes from the theme's `mermaidVariant` (set once in `theme.json`, not per slot).
 
 ````markdown
 ---
@@ -212,13 +213,13 @@ hero: assets/diagrams/architecture.png
 ```
 
 Each parameter or slot in the layout definition may declare:
-- **`type`** (required) -- parameters: `template`, `image`; slots: `text`, `table`, `code`, `mermaid`.
+- **`type`** (parameters, required) -- `template` or `image`.
+- **`accepts`** (slots, required) -- an array of `text`, `table`, `image`.
 - **`required: true`** -- the slide has no usable default and the build fails if the parameter/slot has no value (e.g. team-member photos, icon-grid icons, the quote logo). If you don't have a suitable image, ask the user for one.
+- **optional (the default)** -- a parameter or slot you leave unfilled is dropped from the slide (its shape is removed), so a layout with numbered slots (e.g. up to six sections, up to four stats) renders only the ones you fill.
 - **image sizing** -- each catalog asset declares a `type` (`icon` | `image` | `background`) that determines how it is scaled and cropped: `icon` never enlarges past native and never crops; `image` fits the whole picture (no crop, may scale); `background` fills and center-crops. Mermaid renders as `image` (contained).
-- **`codeTheme`** -- code slots only (required): the Shiki theme id used to syntax-highlight fenced code that lands in this slot (e.g. `"github-dark"`).
-- **`mermaidVariant`** -- mermaid slots only (required): names the color variant from `theme.mermaid` (e.g. `"dark"`). See [Mermaid diagrams](#mermaid-diagrams) above.
 
-Each layout also declares a `slideNumber` pointing at the physical slide in the theme's template. **`slideNumber` may repeat across layouts**: two (or more) manifest entries with the same `slideNumber` back a single physical slide, distinguished only by which parameter/slot types they declare -- e.g. an "image" variant and a "mermaid" variant on the same full-bleed slide. The compiler enforces that shared-`slideNumber` layouts agree on keys and shape names; the only allowed cross-type variation is `{image, mermaid}` on the same key.
+Each layout also declares a `slideNumber` pointing at the physical slide in the theme's template -- unique per layout (one layout maps to one physical slide).
 
 ---
 
@@ -274,6 +275,8 @@ layout: Body
 title: Your First Week
 ---
 
+::body::
+
 Here is what to expect in your first week.
 
 - Day 1: Laptop setup and HR orientation