markdownfly 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -2,7 +2,17 @@
  * Configuration type definitions
  */
 interface MarkdownFlyConfig {
+    /**
+     * Theme name for `getTheme` / CLI `-t`.
+     * Resolves ThemePreset first (e.g. 'blue'), then ColorScheme (e.g. 'ocean').
+     */
     theme: string;
+    /** ColorScheme override (frontmatter `color_scheme`) — overrides theme's color slot */
+    colorScheme?: string;
+    /** TextScheme override (frontmatter `text_scheme`) — overrides theme's text slot */
+    textScheme?: string;
+    /** LayoutScheme override (frontmatter `layout_scheme`) — overrides theme's layout slot */
+    layoutScheme?: string;
     author?: string;
     date?: string;
     footer?: string;
@@ -18,7 +28,7 @@ interface MarkdownFlyConfig {
  */
 
 /** Available slide layouts */
-type SlideLayout = 'title' | 'section' | 'content' | 'two-column' | 'code' | 'quote' | 'blank' | 'closing';
+type SlideLayout = 'title' | 'section' | 'content' | 'two-column' | 'code' | 'quote' | 'blank' | 'closing' | 'image-single' | 'image-double' | 'image-triple';
 /** A layout marker inside a slide: starts a new row (===) or column (<->) */
 interface BreakElement {
     type: 'break';
@@ -121,9 +131,74 @@ interface Presentation {
  */
 declare function parseMarkdown(markdown: string): Presentation;
 
+/**
+ * Text-set types — three layers: registry → TextScheme → shared FontStyleEntry.
+ *
+ * Policy (user decision): one scheme uses ONE typeface for Chinese and
+ * English alike. No sentence-level dual fonts, no OOXML a:ea rewrite.
+ * `cjkFace` remains only as an optional bridge hint for diagrams (`fonts.cjk`);
+ * when omitted, diagrams fall back to `face`.
+ *
+ * Compatibility: additive on Theme; existing fields unchanged.
+ * Entries carry no color (ColorScheme owns color) and no text transform.
+ */
+/** One font-style entry. `face` is the typeface used for all scripts. */
+interface FontStyleEntry {
+    /** Typeface for this position (pptxgenjs `fontFace`) */
+    face: string;
+    /**
+     * Optional CJK hint for diagram bridge (`theme.fonts.cjk`).
+     * Omit for uniform schemes — bridge uses `face`.
+     */
+    cjkFace?: string;
+    size: number;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    letterSpacing?: number;
+    lineSpacing?: number;
+}
+/** Fixed position keys — every TextScheme must supply all six. */
+type TextSchemePositionKey = 'coverTitle' | 'slideTitle' | 'body' | 'quote' | 'code' | 'small';
+declare const TEXT_SCHEME_POSITION_KEYS: readonly ["coverTitle", "slideTitle", "body", "quote", "code", "small"];
+type TextSchemePositions = Record<TextSchemePositionKey, FontStyleEntry>;
+interface TextScheme {
+    name: string;
+    /** Fixed six positions → FontStyleEntry (object references for sharing) */
+    positions: TextSchemePositions;
+    /** Documentation only */
+    note?: string;
+}
+declare const DEFAULT_TEXT_SCHEME_NAME = "system";
+interface UniformTextSchemeOptions {
+    name: string;
+    /** Single typeface for titles, body, quote, small (CN + EN) */
+    face: string;
+    /** Code face; defaults to Consolas */
+    codeFace?: string;
+    /** Reuse a shared code entry (object identity) instead of creating one */
+    codeEntry?: FontStyleEntry;
+    sizes?: Partial<Record<TextSchemePositionKey, number>>;
+    /** Defaults: coverTitle + slideTitle bold */
+    bold?: Partial<Record<TextSchemePositionKey, boolean>>;
+    /** Defaults: quote italic */
+    italic?: Partial<Record<TextSchemePositionKey, boolean>>;
+    note?: string;
+}
+/**
+ * Build a complete TextScheme from one typeface — the happy path for
+ * adding a scheme: one file + one registry line.
+ */
+declare function defineUniformTextScheme(options: UniformTextSchemeOptions): TextScheme;
+
 /**
  * Theme type definitions
+ *
+ * Compatibility: existing fields are never renamed, retyped, or removed.
+ * New capabilities are added as optional fields only; consumers fall back
+ * with `?? legacyField`. Deprecated fields keep a `@deprecated` JSDoc tag.
  */
+
 interface ThemeGradient {
     /** Gradient start color (hex, without '#') */
     from: string;
@@ -150,12 +225,30 @@ interface ThemeColors {
      * `background` stays as the flat fallback and drives dark/light detection for diagrams.
      */
     backgroundGradient?: ThemeGradient;
+    /** Accent color group; prefer `accents[0]` over the legacy `accent` when both are set */
+    accents?: string[];
+    /** Subtitle text color; falls back to `secondary` */
+    subtitle?: string;
+    /** Divider / decoration-bar color; falls back to `primary` */
+    divider?: string;
+    /** Muted text (footnotes, annotations); falls back to `secondary` */
+    muted?: string;
+    /** Table header background; falls back to `primary` */
+    tableHeader?: string;
+    /** Table zebra-row background; falls back to `background` */
+    tableZebra?: string;
 }
 interface ThemeFonts {
     heading: string;
     body: string;
     code: string;
     cjk: string;
+    /** Cover-title face; falls back to `heading` */
+    title?: string;
+    /** Subtitle face; falls back to `heading` */
+    subtitle?: string;
+    /** Quote face; falls back to `body` */
+    quote?: string;
 }
 interface ThemeFontSizes {
     title: number;
@@ -163,6 +256,98 @@ interface ThemeFontSizes {
     body: number;
     code: number;
     small: number;
+    /** Subtitle size; falls back to `body` */
+    subtitle?: number;
+    /** Caption / table-note size; falls back to `small` */
+    caption?: number;
+}
+/** Layout parameters shared by all themes (data-parameter style, not coordinates) */
+interface ThemeLayoutSpec {
+    /** Variant name interpreted by each layout function */
+    variant?: string;
+    titleAlign?: 'left' | 'center' | 'right';
+    /** Decoration-bar position; use 'none' to hide */
+    accentBar?: 'left' | 'bottom' | 'top' | 'none';
+    /** Title-zone height in inches */
+    titleHeight?: number;
+    /** Content-zone padding in inches */
+    contentPadding?: number;
+    /** Page margin in inches (overrides the layout's built-in MARGIN) */
+    margin?: number;
+    /** Whether to draw the footer divider line */
+    footerDivider?: boolean;
+    /** Free-form extras interpreted by individual layout functions */
+    extra?: Record<string, string | number | boolean>;
+}
+interface ThemeLayouts {
+    title?: ThemeLayoutSpec;
+    section?: ThemeLayoutSpec;
+    content?: ThemeLayoutSpec;
+    code?: ThemeLayoutSpec;
+    quote?: ThemeLayoutSpec;
+    closing?: ThemeLayoutSpec;
+    imageSingle?: ThemeLayoutSpec;
+    imageDouble?: ThemeLayoutSpec;
+    imageTriple?: ThemeLayoutSpec;
+    /** Footer geometry / divider (consumed by layouts/index.ts) */
+    footer?: ThemeLayoutSpec;
+}
+interface ThemeStyles {
+    /** Code-block corner radius in pt */
+    codeRadius?: number;
+    /** Code-block border color */
+    codeBorder?: string;
+    /** Whether the cover shows a corner badge / logo slot */
+    coverBadge?: boolean;
+    /** Section-page accent-bar width in inches */
+    sectionBarWidth?: number;
+    /** Whether non-cover pages draw a footer divider line */
+    footerDivider?: boolean;
+}
+/** Per-role text style; every property overrides the matching legacy field */
+interface ThemeTextStyle {
+    face?: string;
+    size?: number;
+    color?: string;
+    bold?: boolean;
+    italic?: boolean;
+    /** Letter spacing in pt (pptxgenjs `charSpacing`) */
+    letterSpacing?: number;
+    /** Line-spacing multiplier (1.0 = single) */
+    lineSpacing?: number;
+    textTransform?: 'upper' | 'lower' | 'none';
+}
+/** Typographic styles organized by role; layout falls back to fonts/fontSize/colors */
+interface ThemeTypography {
+    title?: ThemeTextStyle;
+    subtitle?: ThemeTextStyle;
+    heading?: ThemeTextStyle;
+    body?: ThemeTextStyle;
+    bodyStrong?: ThemeTextStyle;
+    bodyEm?: ThemeTextStyle;
+    code?: ThemeTextStyle;
+    inlineCode?: ThemeTextStyle;
+    quote?: ThemeTextStyle;
+    caption?: ThemeTextStyle;
+    footer?: ThemeTextStyle;
+    tableHeader?: ThemeTextStyle;
+    tableCell?: ThemeTextStyle;
+}
+/** Background resource: flat color, gradient, or image with optional overlay */
+interface ThemeBackground {
+    type: 'color' | 'gradient' | 'image';
+    /** Used when type === 'color'; falls back to `colors.background` */
+    color?: string;
+    /** Used when type === 'gradient'; falls back to `colors.backgroundGradient` */
+    gradient?: ThemeGradient;
+    /** Used when type === 'image'; overlay keeps text readable */
+    image?: {
+        src: string;
+        /** Overlay hex color (e.g. 'FFFFFF' / '000000') */
+        overlay?: string;
+        /** Overlay opacity 0~1, default 0.35 */
+        overlayOpacity?: number;
+    };
 }
 interface Theme {
     name: string;
@@ -170,43 +355,375 @@ interface Theme {
     fonts: ThemeFonts;
     fontSize: ThemeFontSizes;
     shikiTheme?: string;
+    /** Per-layout visual parameters (optional; layouts fall back to built-in values) */
+    layouts?: ThemeLayouts;
+    /** Decoration / code-block styling knobs */
+    styles?: ThemeStyles;
+    /** Role-based typography overrides */
+    typography?: ThemeTypography;
+    /** Background resource pool (color / gradient / image+overlay) */
+    background?: ThemeBackground;
+    /** Reverse design traps for this theme (documentation only, not rendered) */
+    avoid?: string[];
+    /** Activated TextScheme name (e.g. 'system' / 'academic') */
+    textSet?: string;
+    /** Resolved TextScheme */
+    textScheme?: TextScheme;
+    /** Position → FontStyleEntry from the scheme (object references) */
+    textStyles?: Partial<Record<TextSchemePositionKey, FontStyleEntry>>;
+    /** Activated LayoutScheme name (e.g. 'folio' / 'legacy') */
+    layoutSet?: string;
+    /** Activated ThemePreset name when resolved via `preset` (e.g. 'tech-share') */
+    presetSet?: string;
 }
 
-declare const cleanTheme: Theme;
+/**
+ * ColorScheme — minimal user-facing palette for the PPT design system.
+ *
+ * A scheme is exactly four slots:
+ *   ink      — text (titles, body)
+ *   paper    — page background
+ *   primary  — main decoration bars / large color blocks
+ *   secondary— auxiliary elements / secondary info
+ *
+ * Emphasis is expressed by weight, size, rules, and whitespace — not by an
+ * extra chromatic slot. `ThemeColors.accent` is still produced for legacy
+ * renderers, derived from primary (deeper mix toward ink).
+ *
+ * Built-in presets and user customs share this exact shape.
+ */
+type ColorSchemeMode = 'light' | 'dark';
+interface ColorScheme {
+    /** Stable id, e.g. 'ocean' */
+    name: string;
+    /**
+     * Surface polarity hint (drives shiki default). Optional — inferred from
+     * paper luminance when omitted. Does NOT swap ink/paper: ink is always
+     * text, paper is always background.
+     */
+    mode?: ColorSchemeMode;
+    /** Text color: titles + body */
+    ink: string;
+    /** Page background */
+    paper: string;
+    /** Primary: main decoration bars, large color blocks */
+    primary: string;
+    /** Secondary: auxiliary elements, secondary information */
+    secondary: string;
+}
+/** Chromatic slots exposed on ThemeColors.accents[] (emphasis is non-chromatic) */
+declare const CHROMATIC_SLOTS: readonly ["primary", "secondary"];
+/** light/dark from paper luminance (explicit mode wins); ink/paper are never swapped */
+declare function resolveSchemeMode(scheme: ColorScheme): ColorSchemeMode;
+
+/**
+ * LayoutScheme — named package of layout parameters (placement only).
+ *
+ * Parallel to ColorScheme / TextScheme: registry → scheme → Theme.
+ * Does not carry fonts or colors; those stay in text-schemes / color-schemes.
+ */
+
+interface LayoutScheme {
+    /** Stable id, e.g. 'default' */
+    name: string;
+    /** Per-page-type placement parameters */
+    layouts: ThemeLayouts;
+    /** Decoration knobs shared across pages */
+    styles?: ThemeStyles;
+    /** Documentation only */
+    note?: string;
+}
+declare const DEFAULT_LAYOUT_SCHEME_NAME = "folio";
 
-declare const academicTheme: Theme;
+/**
+ * ThemePreset — named package selecting one ColorScheme × TextScheme × LayoutScheme.
+ *
+ * User-facing theme names resolve via `theme` / `-t`:
+ *   ThemePreset first, then ColorScheme (legacy color-only path).
+ */
+interface ThemePreset {
+    /** Stable id used as the user-facing theme name, e.g. 'blue' */
+    name: string;
+    /** Registered ColorScheme name */
+    colorScheme: string;
+    /** Registered TextScheme name */
+    textScheme: string;
+    /** Registered LayoutScheme name */
+    layoutScheme: string;
+    /** Reserved for step 4 background-set — not consumed yet */
+    backgroundScheme?: string;
+    /** Documentation only */
+    note?: string;
+}
+/** Default theme when `-t` / frontmatter `theme` is omitted. */
+declare const DEFAULT_THEME_NAME = "blue";
+/** @deprecated Use DEFAULT_THEME_NAME; kept as alias for older imports. */
+declare const DEFAULT_PRESET_NAME = "blue";
 
-declare const darkTheme: Theme;
+/**
+ * Resolve a compact ColorScheme (ink/paper/primary/secondary) into ThemeColors.
+ *
+ * Compatibility: output uses only current ThemeColors fields. Renderer and
+ * diagrams/theme.ts (isDarkTheme → colors.background) keep working unchanged.
+ * background is always a bare hex without '#'.
+ *
+ * Role contract (author-facing, never swapped):
+ *   paper → colors.background
+ *   ink   → colors.text
+ *
+ * `accent` is required on ThemeColors but is NOT a ColorScheme slot — it is
+ * derived (primary mixed toward ink) so existing accent consumers keep working
+ * while the authored palette stays at four colors.
+ */
 
-declare const businessTheme: Theme;
+declare function resolveColorScheme(scheme: ColorScheme): ThemeColors;
 
-declare const warmTheme: Theme;
+/**
+ * Build a full Theme from a ColorScheme (+ optional font / text-set overrides).
+ *
+ * Text-set layer is the only font source: `textScheme` (default `system`)
+ * bridges into Theme.fonts / Theme.fontSize. Explicit `options.fonts` /
+ * `options.fontSize` still win when provided.
+ *
+ * The legacy `font-sets/` folder has been removed; do not reintroduce it.
+ */
 
-declare const defaultTheme: Theme;
+interface ThemeFromSchemeOptions {
+    fonts?: ThemeFonts;
+    fontSize?: ThemeFontSizes;
+    shikiTheme?: string;
+    layouts?: Theme['layouts'];
+    styles?: Theme['styles'];
+    typography?: Theme['typography'];
+    avoid?: string[];
+    /** Color scheme name or object; defaults to the `scheme` argument */
+    colorScheme?: string | ColorScheme;
+    /** Text scheme name or object; defaults to `system` */
+    textScheme?: string | TextScheme;
+    /** Layout scheme name or object; omitted → layouts/styles stay unset (legacy) */
+    layoutScheme?: string | LayoutScheme;
+    /** ThemePreset name for provenance (`theme.presetSet`); does not drive slots here */
+    presetSet?: string;
+}
+/** Resolve preset option → object; unknown name warns and returns undefined. */
+declare function resolveThemePresetOption(input?: string | ThemePreset): ThemePreset | undefined;
+declare function createThemeFromScheme(scheme: ColorScheme, options?: ThemeFromSchemeOptions): Theme;
 
-declare const themes: Record<string, Theme>;
-declare function getTheme(name?: string): Theme;
+/**
+ * Ocean（海洋）— 单色克制蓝。
+ * ink 深海墨蓝作文字，paper 近白海沫作底，primary 亮蓝主装饰，
+ * secondary 中蓝辅助。强调靠字重/字号/线条，不额外占彩槽。
+ */
+declare const oceanScheme: ColorScheme;
+
+/**
+ * Ocean Dark（深海）— ocean 的暗色对位。
+ * paper 深海作底，ink 浅沫作字；primary/secondary 提亮以保证深底对比。
+ * 代码块底为派生深色面板 + github-dark 高亮。
+ */
+declare const oceanDarkScheme: ColorScheme;
+
+/**
+ * Built-in ColorScheme registry.
+ *
+ * Convention: one scheme per file in this folder (`kebab-case.ts`), each
+ * exporting a single `ColorScheme`. To add a built-in scheme:
+ *   1. create `color-schemes/<name>.ts` exporting `{name}Scheme`
+ *   2. import it below and append to `builtInSchemes`
+ *
+ * Step 2 is the only registry touch; values never live in this file.
+ * `test/color-schemes-folder.test.ts` fails if a scheme file is not registered.
+ */
+
+declare function getColorScheme(name?: string): ColorScheme | undefined;
+declare function listColorSchemes(): ColorScheme[];
+declare function registerColorScheme(scheme: ColorScheme): void;
+
+/**
+ * academic TextScheme — uniform typeface: 宋体.
+ * Titles sized up for the `blue` theme package (user request).
+ */
+declare const academicTextScheme: TextScheme;
+
+/**
+ * system TextScheme — default. Uniform typeface: 微软雅黑.
+ * code 位置使用共享 Consolas 条目。
+ */
+declare const systemTextScheme: TextScheme;
+
+/**
+ * kai TextScheme — uniform typeface: KaiTi（楷体）.
+ */
+declare const kaiTextScheme: TextScheme;
+
+/**
+ * source-han-serif TextScheme — uniform typeface: 思源宋体.
+ * 本机安装名也可能是 Source Han Serif SC / Noto Serif CJK SC，不一致时改 face。
+ */
+declare const sourceHanSerifTextScheme: TextScheme;
+
+/**
+ * Built-in TextScheme registry.
+ *
+ * Add a scheme (two steps):
+ *   1. create `text-schemes/<name>.ts` exporting a TextScheme
+ *      (usually via `defineUniformTextScheme({ name, face, codeEntry: sharedCode })`)
+ *   2. import it below and append to `builtInTextSchemes`
+ *
+ * `test/text-schemes-folder.test.ts` fails if a scheme file is not registered.
+ */
+
+declare const textSchemes: Record<string, TextScheme>;
+declare function getTextScheme(name?: string): TextScheme | undefined;
+declare function listTextSchemes(): TextScheme[];
+declare function registerTextScheme(scheme: TextScheme): void;
+
+/**
+ * folio LayoutScheme — 编辑册页风（创新版式，不仿 legacy）。
+ *
+ * 设计语言：杂志/技术报告册页
+ * - 封面：左侧书脊色带 + 左对齐标题 + 标题下短横线 + 元信息沉底
+ * - 章节：无侧边条；上下双横线夹住标题带
+ * - 正文：不对称页边距（左宽右窄）+ 标题下粗线（次级色）
+ * - 代码：近满幅「图版」式
+ * - 引用：左侧竖条 pull-quote，无大引号，出处左对齐
+ * - 页脚：分割线 + 居中
+ * - 结尾：Thank you 上下短线
+ * - 图文：与正文同款不对称边距
+ */
+
+declare const folioLayoutScheme: LayoutScheme;
+
+/**
+ * legacy LayoutScheme — 旧版版式（改造前写死在 layout 函数里的那套）。
+ *
+ * 仅覆盖旧有基础页：封面 / 章节 / 正文 / 代码 / 引用 + 页脚。
+ * 不含结尾页、图文页——使用本方案时，新页型走 layout 函数内硬编码默认。
+ */
+
+declare const legacyLayoutScheme: LayoutScheme;
+
+/**
+ * Built-in LayoutScheme registry — 主题体系中的版式集。
+ *
+ * 数据流与色彩集 / 文字集相同：
+ *   layout-schemes/<name>/  →  getTheme(..., { layoutScheme })  →  Theme.layouts/styles
+ *
+ * 一套版式方案 = 一个文件夹。内置：
+ *   - legacy：旧版（改造前写死摆法）
+ *   - folio：编辑册页（创新版式，不仿 legacy）
+ *   - golden：黄金比例（右对齐留白 + 黄金分割横线）
+ *   - minimal：极简档案（统一 0.83 边距 + 线性装饰 + 超大章序号）
+ *
+ * `test/layout-schemes-folder.test.ts`：文件夹 ↔ 注册表一致性。
+ */
+
+declare const layoutSchemes: Record<string, LayoutScheme>;
+declare function getLayoutScheme(name?: string): LayoutScheme | undefined;
+declare function listLayoutSchemes(): LayoutScheme[];
+declare function registerLayoutScheme(scheme: LayoutScheme): void;
+
+/** blue：ocean + academic + legacy */
+declare const bluePreset: ThemePreset;
+
+/**
+ * Built-in ThemePreset registry — 主题预设（色彩 × 文字 × 版式 组合包）。
+ *
+ * 数据流：
+ *   presets/<name>.ts → getTheme(..., { preset }) / convert(..., { preset }) → Theme
+ *
+ * 契约（第 5 步拍板）：
+ *   - `-t` / frontmatter `theme:` 仍只表示 ColorScheme 名
+ *   - 预设走独立入口 `preset` / `--preset`；不传 = 现网行为（不自动套默认预设）
+ *   - 显式 textScheme / layoutScheme / theme 覆盖预设对应槽位
+ *
+ * 内置 4 套预设（色彩 × 文字 × 版式，各集不重复按顺序组合）：
+ *   - blue    = ocean  + academic          + legacy
+ *   - emerald = forest + system            + folio
+ *   - gold    = champagne + kai            + golden
+ *   - slate   = graphite + source-han-serif + minimal
+ *   （ocean-dark 为 ocean 的反色，与 ocean 共用文字/版式，不单列）
+ */
+
+declare const themePresets: Record<string, ThemePreset>;
+declare function getThemePreset(name?: string): ThemePreset | undefined;
+declare function listThemePresets(): ThemePreset[];
+declare function registerThemePreset(preset: ThemePreset): void;
+declare function themePresetNames(): string[];
+declare function hasThemePreset(name?: string): boolean;
+
+/** Color-only fallback when a ColorScheme name is unknown */
+declare const DEFAULT_SCHEME_NAME = "ocean";
+interface GetThemeOptions {
+    /** Color scheme name or resolved ColorScheme (overrides preset slot) */
+    colorScheme?: string | ColorScheme;
+    /** Text scheme name or resolved TextScheme (overrides preset slot) */
+    textScheme?: string | TextScheme;
+    /** Layout scheme name or resolved LayoutScheme (overrides preset slot) */
+    layoutScheme?: string | LayoutScheme;
+    /**
+     * Optional ThemePreset object for advanced callers.
+     * The user-facing path is the `name` argument (`-t` / frontmatter `theme`).
+     */
+    preset?: string | ThemePreset;
+}
+/**
+ * Build a Theme from a user-facing theme name.
+ *
+ * - `blue` (or any ThemePreset) → full package (color × text × layout)
+ * - `ocean` / `ocean-dark` (ColorScheme only) → color path; text `system`;
+ *   layouts stay unset unless `options.layoutScheme` is passed
+ * - omitted / unknown → default theme `blue` (unknown warns)
+ *
+ * Non-string `name` values still throw (CLI contract).
+ */
+declare function getTheme(name?: string, options?: GetThemeOptions): Theme;
+/** User-facing theme names: presets first, then color-only schemes. */
+declare function themeNames(): string[];
+/** Whether `name` is a known user-facing theme (preset or color scheme). */
+declare function hasTheme(name?: string): boolean;
+
+/** Check if a code block language is a diagram type. */
+declare function isDiagramLanguage(language: string): boolean;
 
 /**
  * Diagram Registry
  * Unified entry point for all diagram renderers
  */
 
-/** Check if a code block language is a diagram type */
-declare function isDiagramLanguage(language: string): boolean;
 /**
  * Render a diagram code block to PNG
  * @returns PNG image as Buffer
  */
 declare function renderDiagram(language: string, code: string, theme?: Theme): Promise<Buffer>;
 
+/**
+ * PPTX Renderer
+ * Orchestrates pptxgenjs to produce .pptx files from Presentation
+ */
+
+/**
+ * Render a Presentation to a .pptx file
+ */
+declare function renderPresentation(presentation: Presentation, theme: Theme, outputPath: string, inputPath?: string): Promise<void>;
+
 /**
  * MarkdownFly — Main orchestration
  * Public API: convert(inputPath, options) → outputPath
  */
 interface ConvertOptions {
     output?: string;
+    /**
+     * User-facing theme name (same as CLI `-t` / frontmatter `theme`).
+     * ThemePreset first (e.g. 'blue'), then ColorScheme (e.g. 'ocean').
+     */
     theme?: string;
+    /** ColorScheme override (CLI `--color` / frontmatter `color_scheme`) */
+    colorScheme?: string;
+    /** TextScheme override (CLI `--text` / frontmatter `text_scheme`) */
+    textScheme?: string;
+    /** LayoutScheme override (CLI `--layout` / frontmatter `layout_scheme`) */
+    layoutScheme?: string;
 }
 /**
  * Convert a Markdown file to PPTX
@@ -214,4 +731,4 @@ interface ConvertOptions {
  */
 declare function convert(inputPath: string, options?: ConvertOptions): Promise<string>;
 
-export { type ConvertOptions, type MarkdownFlyConfig, type Presentation, type SlideElement, type SlideNode, type Theme, academicTheme, businessTheme, cleanTheme, convert, darkTheme, defaultTheme, getTheme, isDiagramLanguage, parseMarkdown, renderDiagram, themes, warmTheme };
+export { CHROMATIC_SLOTS, type ColorScheme, type ColorSchemeMode, type ConvertOptions, DEFAULT_LAYOUT_SCHEME_NAME, DEFAULT_PRESET_NAME, DEFAULT_SCHEME_NAME, DEFAULT_TEXT_SCHEME_NAME, DEFAULT_THEME_NAME, type FontStyleEntry, type LayoutScheme, type MarkdownFlyConfig, type Presentation, type SlideElement, type SlideNode, TEXT_SCHEME_POSITION_KEYS, type TextScheme, type TextSchemePositionKey, type Theme, type ThemePreset, type UniformTextSchemeOptions, academicTextScheme, bluePreset, convert, createThemeFromScheme, defineUniformTextScheme, folioLayoutScheme, getColorScheme, getLayoutScheme, getTextScheme, getTheme, getThemePreset, hasTheme, hasThemePreset, isDiagramLanguage, kaiTextScheme, layoutSchemes, legacyLayoutScheme, listColorSchemes, listLayoutSchemes, listTextSchemes, listThemePresets, oceanDarkScheme, oceanScheme, parseMarkdown, registerColorScheme, registerLayoutScheme, registerTextScheme, registerThemePreset, renderDiagram, renderPresentation, resolveColorScheme, resolveSchemeMode, resolveThemePresetOption, sourceHanSerifTextScheme, systemTextScheme, textSchemes, themeNames, themePresetNames, themePresets };