Configuration and Frontmatter

/**
 * Main Slidev configuration interface combining headmatter with resolved options
 */
interface SlidevConfig extends 
  Omit<Required<HeadmatterConfig>, keyof ResolvedSlidevConfigSub>,
  ResolvedSlidevConfigSub {}

interface ResolvedSlidevConfigSub {
  export: ResolvedExportOptions;
  drawings: ResolvedDrawingsOptions;
  fonts: ResolvedFontOptions;
  aspectRatio: number;
}

/**
 * Configuration interface for presentation headmatter
 */
interface HeadmatterConfig extends TransitionOptions {
  /** Title of the slides */
  title?: string;
  /** String template to compose title */
  titleTemplate?: string;
  /** Theme to use for the slides */
  theme?: string;
  /** List of Slidev addons */
  addons?: string[];
  /** Download remote assets in local using vite-plugin-remote-assets */
  remoteAssets?: boolean | 'dev' | 'build';
  /** Show a download button in the SPA build */
  download?: boolean | string;
  /** Show a copy button in code blocks */
  codeCopy?: boolean;
  /** The author of the slides */
  author?: string;
  /** Information shows on the built SPA */
  info?: string | boolean;
  /** Prefer highlighter */
  highlighter?: 'shiki';
  /** Enable Twoslash */
  twoslash?: boolean | 'dev' | 'build';
  /** Show line numbers in code blocks */
  lineNumbers?: boolean;
  /** Force slides color schema */
  colorSchema?: 'dark' | 'light' | 'all' | 'auto';
  /** Router mode for vue-router */
  routerMode?: 'hash' | 'history';
  /** Aspect ratio for slides */
  aspectRatio?: number | string;
  /** The actual width for slides canvas */
  canvasWidth?: number;
  /** Controls whether texts in slides are selectable */
  selectable?: boolean;
  /** Configure for themes */
  themeConfig?: SlidevThemeConfig;
  /** Configure fonts for the slides and app */
  fonts?: FontOptions;
  /** Configure the icon for app */
  favicon?: string;
  /** Options for drawings */
  drawings?: DrawingsOptions;
  /** URL of PlantUML server used to render diagrams */
  plantUmlServer?: string;
  /** Enable slides recording */
  record?: boolean | 'dev' | 'build';
  /** Expose the server to inbound requests */
  remote?: string | boolean;
  /** Engine for Atomic CSS */
  css?: 'unocss';
  /** Enable presenter mode */
  presenter?: boolean | 'dev' | 'build';
  /** Enable browser exporter */
  browserExporter?: boolean | 'dev' | 'build';
  /** Attributes to apply to the HTML element */
  htmlAttrs?: Record<string, string>;
  /** Support MDC syntax */
  mdc?: boolean;
  /** Enable built-in editor */
  editor?: boolean;
  /** Enable context menu */
  contextMenu?: boolean | 'dev' | 'build' | null;
  /** Enable wake lock */
  wakeLock?: boolean | 'dev' | 'build';
  /** Force the filename used when exporting the presentation */
  exportFilename?: string | null;
  /** Enable Monaco */
  monaco?: boolean | 'dev' | 'build';
  /** Where to load monaco types from */
  monacoTypesSource?: 'cdn' | 'local' | 'none';
  /** Additional node packages to load as monaco types */
  monacoTypesAdditionalPackages?: string[];
  /** Packages to ignore when loading monaco types */
  monacoTypesIgnorePackages?: string[];
  /** Additional local modules to load as dependencies of monaco runnable */
  monacoRunAdditionalDeps?: string[];
  /** Seo meta tags settings */
  seoMeta?: SeoMeta;
}

/**
 * Configuration interface for individual slide frontmatter
 */
interface Frontmatter extends TransitionOptions {
  /** Slide layout to use */
  layout?: BuiltinLayouts | string;
  /** Custom class added to the slide root element */
  class?: string | string[] | Record<string, unknown>;
  /** Manually specified the total clicks needed to this slide */
  clicks?: number;
  /** Manually specified the total clicks needed to this slide to start */
  clicksStart?: number;
  /** Preload the slide when the previous slide is active */
  preload?: boolean;
  /** Completely hide and disable the slide */
  hide?: boolean;
  /** Same as hide, completely hide and disable the slide */
  disabled?: boolean;
  /** Hide the slide for the Toc components */
  hideInToc?: boolean;
  /** Override the title for the TitleRenderer and Toc components */
  title?: string;
  /** Override the title level for the TitleRenderer and Toc components */
  level?: number;
  /** Create a route alias that can be used in the URL or with the Link component */
  routeAlias?: string;
  /** Custom zoom level for the slide */
  zoom?: number;
  /** Store the positions of draggable elements */
  dragPos?: Record<string, string>;
  /** Includes a markdown file */
  src?: string;
}

/**
 * Font configuration interface
 */
interface FontOptions {
  /** Sans serif fonts (default fonts for most text) */
  sans?: string | string[];
  /** Serif fonts */
  serif?: string | string[];
  /** Monospace fonts, for code blocks and etc. */
  mono?: string | string[];
  /** Load webfonts for custom CSS */
  custom?: string | string[];
  /** Weights for fonts */
  weights?: string | (string | number)[];
  /** Import italic fonts */
  italic?: boolean;
  /** Font provider */
  provider?: 'none' | 'google' | 'coollabs';
  /** Specify web fonts names */
  webfonts?: string[];
  /** Specify local fonts names, be excluded from webfonts */
  local?: string[];
  /** Use fonts fallback */
  fallbacks?: boolean;
}

interface ResolvedFontOptions {
  sans: string[];
  mono: string[];
  serif: string[];
  weights: string[];
  italic: boolean;
  provider: 'none' | 'google' | 'coollabs';
  webfonts: string[];
  local: string[];
}

/**
 * Drawing configuration interface
 */
interface DrawingsOptions {
  /** Persist the drawings to disk */
  persist?: boolean | string;
  /** Enable drawing functionality */
  enabled?: boolean | 'dev' | 'build';
  /** Only allow drawing from presenter mode */
  presenterOnly?: boolean;
  /** Sync drawing for all instances */
  syncAll?: boolean;
}

interface ResolvedDrawingsOptions {
  persist: string | false;
  enabled: boolean | 'dev' | 'build';
  presenterOnly: boolean;
  syncAll: boolean;
}

/**
 * Transition configuration interface
 */
interface TransitionOptions {
  /** Page transition, powered by Vue's TransitionGroup */
  transition?: BuiltinSlideTransition | string | TransitionGroupProps | null;
}

interface TransitionGroupProps {
  appear?: boolean;
  persisted?: boolean;
  tag?: string;
  moveClass?: string;
  css?: boolean;
  duration?: number | {
    enter: number;
    leave: number;
  };
  enterFromClass?: string;
  enterActiveClass?: string;
  enterToClass?: string;
  appearFromClass?: string;
  appearActiveClass?: string;
  appearToClass?: string;
  leaveFromClass?: string;
  leaveActiveClass?: string;
  leaveToClass?: string;
}

type BuiltinSlideTransition = 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right' | 'fade' | 'zoom' | 'none';

/**
 * SEO metadata configuration interface
 */
interface SeoMeta {
  ogTitle?: string;
  ogDescription?: string;
  ogImage?: string;
  ogUrl?: string;
  twitterCard?: 'summary' | 'summary_large_image' | 'app' | 'player';
  twitterSite?: string;
  twitterTitle?: string;
  twitterDescription?: string;
  twitterImage?: string;
  twitterUrl?: string;
}

/**
 * Built-in slide layout types
 */
type BuiltinLayouts =
  | '404'
  | 'center'
  | 'cover'
  | 'default'
  | 'end'
  | 'error'
  | 'fact'
  | 'full'
  | 'iframe-left'
  | 'iframe-right'
  | 'iframe'
  | 'image-left'
  | 'image-right'
  | 'image'
  | 'intro'
  | 'none'
  | 'quote'
  | 'section'
  | 'statement'
  | 'two-cols-header'
  | 'two-cols';

type SlidevThemeConfig = Record<string, string | number>;

/**
 * Headmatter interface combining configuration with defaults
 */
interface Headmatter extends HeadmatterConfig, Omit<Frontmatter, 'title'> {
  /** Default frontmatter options applied to all slides */
  defaults?: Frontmatter;
}

interface ResolvedExportOptions extends Omit<ExportArgs, 'entry' | 'theme'> {
  withClicks?: boolean;
  executablePath?: string;
  withToc?: boolean;
}