slidev-theme-practicum 0.2.0 → 0.4.0

package/composables/layout-shorthands.ts

@@ -8,6 +8,7 @@ export type LayoutShorthandComponents = {
   Image: Component
   Person: Component
   Slot: Component
+  StepsGrid: Component
   Text: Component
   Timeline: Component
 }
@@ -117,10 +118,64 @@ function readHeadingText(children: VNode[], label: string) {
   failMarkdownContract(label, 'ожидает один markdown heading внутри default slot.')
 }
 
+function readRichHeadingChildren(node: VNode | null | undefined): Array<string | VNode> | null {
+  if (!node || !isHeadingNode(node))
+    return null
+
+  if (typeof node.children === 'string')
+    return [node.children]
+  if (!Array.isArray(node.children))
+    return null
+
+  return node.children.filter(child => isVNode(child) || typeof child === 'string') as Array<string | VNode>
+}
+
+function readRichNodeChildren(node: VNode | null | undefined): Array<string | VNode> | null {
+  if (!node || typeof node.children === 'string')
+    return null
+
+  if (!Array.isArray(node.children))
+    return null
+
+  return node.children.filter(child => isVNode(child) || typeof child === 'string') as Array<string | VNode>
+}
+
+function readHeadingSlotContent(node: VNode | null | undefined, textFallback: string) {
+  const richChildren = readRichHeadingChildren(node) ?? readRichNodeChildren(node)
+  return richChildren ?? readRichTextWithLineBreaks(textFallback)
+}
+
+function readParagraphSlotContent(node: VNode | null | undefined, textFallback: string) {
+  const richChildren = readRichNodeChildren(node)
+  return richChildren ?? readRichTextWithLineBreaks(textFallback)
+}
+
+function readRichTextWithLineBreaks(text: string): string | Array<string | VNode> {
+  const matches = text.split(/(<br\s*\/?>)/i)
+  if (matches.length === 1)
+    return text
+
+  return matches.flatMap<string | VNode>((value): Array<string | VNode> => {
+    if (!value.trim())
+      return []
+    if (/^<br\s*\/?>$/i.test(value))
+      return [h('br')]
+    return [value]
+  })
+}
+
+function hasRichSlotContent(content: Array<string | VNode>) {
+  return content.some(item => typeof item === 'string' ? item.trim() : isVNode(item))
+}
+
 function readParagraphText(children: VNode[]) {
   const paragraph = children.find(isParagraphNode)
   if (paragraph)
-    return { node: paragraph, text: readInlineText(paragraph) }
+    return {
+      node: paragraph,
+      text: readInlineText(paragraph),
+      content: readParagraphSlotContent(paragraph, readInlineText(paragraph)),
+    }
 
   return null
 }
@@ -129,7 +184,7 @@ function hText(
   context: LayoutShorthandContext,
   as: string,
   size: ThemeTextSizeInput,
-  content: string,
+  content: string | VNode | Array<string | VNode>,
   options: {
     muted?: boolean
     maxSize?: boolean
@@ -171,10 +226,12 @@ function hText(
   if (options.typography)
     textProps['data-typography'] = options.typography
 
+  const slotChildren = Array.isArray(content) ? content : [content]
+
   return h(context.components.Text, {
     ...textProps,
   }, {
-    default: withCtx(() => [content]),
+    default: withCtx(() => slotChildren),
   })
 }
 
@@ -250,15 +307,26 @@ function readListItemText(li: VNode) {
   return normalizeInlineText(parts.join(' '))
 }
 
-function readListItems(list: VNode, label: string) {
-  if (!Array.isArray(list.children))
-    failMarkdownContract(label, 'ожидает list items с текстом.')
+function readListItemSlotContent(li: VNode): Array<string | VNode> {
+  if (typeof li.children === 'string') {
+    const text = li.children
+    return text.trim() ? [text] : []
+  }
 
-  return list.children
-    .filter(isVNode)
-    .filter(node => node.type === 'li')
-    .map(readListItemText)
-    .filter(Boolean)
+  if (!Array.isArray(li.children))
+    return []
+
+  return li.children.flatMap<string | VNode>((child): Array<string | VNode> => {
+    if (!isVNode(child)) {
+      const text = String(child)
+      return text.trim() ? [text] : []
+    }
+
+    if (child.type === 'ul' || child.type === 'ol')
+      return []
+
+    return [cloneVNode(child)]
+  })
 }
 
 function readListItemNodes(list: VNode, label: string) {
@@ -295,7 +363,7 @@ function readListItemContent(li: VNode): VNode[] {
   if (!Array.isArray(li.children))
     return []
 
-  return li.children.flatMap((child) => {
+  return li.children.flatMap<VNode>((child): VNode[] => {
     if (!isVNode(child)) {
       const text = String(child).trim()
       return text ? [h('p', text)] : []
@@ -305,7 +373,10 @@ function readListItemContent(li: VNode): VNode[] {
   })
 }
 
-type NestedListItem = { value: string, label: string }
+type NestedListItem = {
+  value: Array<string | VNode>
+  label: Array<string | VNode>
+}
 
 function readNestedListItems(list: VNode, label: string): NestedListItem[] {
   if (!Array.isArray(list.children))
@@ -316,46 +387,38 @@ function readNestedListItems(list: VNode, label: string): NestedListItem[] {
     .filter(node => node.type === 'li')
     .map((li) => {
       if (!Array.isArray(li.children)) {
-        const text = typeof li.children === 'string' ? normalizeInlineText(li.children) : ''
-        return { value: text, label: '' }
+        const text = typeof li.children === 'string' ? li.children : ''
+        const value = text.trim() ? [text] : []
+        return { value, label: [] }
       }
 
-      const valueParts: string[] = []
       let nestedList: VNode | undefined
-
-      for (const child of li.children) {
+      const value = li.children.flatMap<string | VNode>((child): Array<string | VNode> => {
         if (!isVNode(child)) {
-          const text = String(child ?? '').trim()
-          if (text)
-            valueParts.push(text)
-          continue
+          const text = String(child)
+          return text.trim() ? [text] : []
         }
 
         if (child.type === 'ul' || child.type === 'ol') {
           nestedList = child
-          continue
+          return []
         }
 
-        const text = readInlineText(child).trim()
-        if (text)
-          valueParts.push(text)
-      }
-
-      const value = normalizeInlineText(valueParts.join(' '))
+        return [cloneVNode(child)]
+      })
 
-      let label = ''
-      if (nestedList && Array.isArray(nestedList.children)) {
-        const firstNestedLi = nestedList.children
+      const nestedLabel = nestedList && Array.isArray(nestedList.children)
+        ? nestedList.children
           .filter(isVNode)
           .find(node => node.type === 'li')
+        : null
 
-        if (firstNestedLi)
-          label = readListItemText(firstNestedLi)
+      return {
+        value,
+        label: nestedLabel ? readListItemSlotContent(nestedLabel) : [],
       }
-
-      return { value, label }
     })
-    .filter(item => item.value)
+    .filter(item => hasRichSlotContent(item.value))
 }
 
 const FACTS_VARIANT_COUNTS: Record<string, number> = {
@@ -539,6 +602,7 @@ function buildQuoteChildren(children: VNode[], context: LayoutShorthandContext)
 
 function buildCenteredChildren(children: VNode[], context: LayoutShorthandContext) {
   const title = readHeadingText(children, 'message:centered')
+  const titleContent = readHeadingSlotContent(title.node, title.text)
 
   ensureOnlySupportedChildren('message:centered', children, node =>
     node === title.node
@@ -547,7 +611,7 @@ function buildCenteredChildren(children: VNode[], context: LayoutShorthandContex
 
   return [
     hSlot(context, 'primary', 'slide-message-centered-primary', { centered: true }, [
-      hText(context, 'h1', '7', title.text, { align: 'middle' }),
+      hText(context, 'h1', '7-12', titleContent, { align: 'middle' }),
     ]),
   ]
 }
@@ -555,6 +619,7 @@ function buildCenteredChildren(children: VNode[], context: LayoutShorthandContex
 function buildClosingChildren(children: VNode[], context: LayoutShorthandContext) {
   const title = readHeadingText(children, 'message:closing')
   const paragraph = readParagraphText(children)
+  const titleContent = readHeadingSlotContent(title.node, title.text)
 
   ensureOnlySupportedChildren('message:closing', children, node =>
     node === title.node
@@ -564,9 +629,9 @@ function buildClosingChildren(children: VNode[], context: LayoutShorthandContext
 
   return [
     hSlot(context, 'primary', 'slide-message-closing-primary', { centered: true }, [
-      hText(context, 'h1', '7', title.text, { align: 'middle' }),
+      hText(context, 'h1', '7', titleContent, { align: 'middle' }),
       ...(paragraph
-        ? [hText(context, 'p', '3', paragraph.text, { muted: true })]
+        ? [hText(context, 'p', '3', paragraph.content, { muted: true })]
         : []),
     ]),
   ]
@@ -574,8 +639,9 @@ function buildClosingChildren(children: VNode[], context: LayoutShorthandContext
 
 function buildDefinitionChildren(children: VNode[], context: LayoutShorthandContext) {
   const title = readHeadingText(children, 'explainer:definition')
+  const titleContent = readHeadingSlotContent(title.node, title.text)
   const paragraph = readParagraphText(children)
-  const body = context.readFrontmatterText('body') || paragraph?.text || ''
+  const body = context.readFrontmatterText('body') || paragraph?.content || ''
   const label = context.readFrontmatterText('label')
 
   if (!body)
@@ -590,7 +656,7 @@ function buildDefinitionChildren(children: VNode[], context: LayoutShorthandCont
   return [
     hSlot(context, 'primary', 'slide-explainer-definition-primary', {}, [
       ...(label ? [hText(context, 'div', '3', label, { muted: true, className: 'Slide-DefinitionLabel' })] : []),
-      hText(context, 'h1', '6', title.text, { priority: 1 }),
+      hText(context, 'h1', '6', titleContent, { priority: 1 }),
       hText(context, 'div', '6', body, { muted: true, priority: 1 }),
     ]),
   ]
@@ -607,6 +673,7 @@ function buildTitleRichSideChildren(
   options: { muted?: boolean } = {},
 ) {
   const title = readHeadingText(children, contract)
+  const titleContent = readHeadingSlotContent(title.node, title.text)
   const bodyNodes = children.filter(node =>
     node !== title.node
     && !isBlankTextNode(node),
@@ -626,7 +693,7 @@ function buildTitleRichSideChildren(
 
   return [
     hSlot(context, 'primary', `slide-explainer-${slotPrefix}-primary`, {}, [
-      hText(context, 'h1', '6', title.text),
+      hText(context, 'h1', '6', titleContent),
     ]),
     hSlot(context, 'secondary', `slide-explainer-${slotPrefix}-secondary`, {}, [
       h('div', { class: bodyClass }, bodyNodes.map(node => cloneVNode(node))),
@@ -645,6 +712,7 @@ function buildTitleSupportsChildren(
     return buildTitleRichSideChildren(children, context, 'explainer:title-supports', { muted: true })
 
   const title = readHeadingText(children, 'explainer:title-supports')
+  const titleContent = readHeadingSlotContent(title.node, title.text)
   const list = children.find(isListNode)
   const muted = options.muted ?? true
   const supportSize = options.supportSize ?? '4'
@@ -677,7 +745,7 @@ function buildTitleSupportsChildren(
 
   return [
     hSlot(context, 'primary', 'slide-explainer-title-supports-bottom-primary', {}, [
-      hText(context, 'h1', '6', title.text),
+      hText(context, 'h1', '6', titleContent),
     ]),
     ...items.map((item, index) =>
       hSlot(context, 'support', `slide-explainer-title-supports-bottom-support-${index + 1}`, {}, [
@@ -701,12 +769,21 @@ function buildTitleBodyChildren(children: VNode[], context: LayoutShorthandConte
 
 function buildPointsChildren(children: VNode[], context: LayoutShorthandContext) {
   const title = readHeadingText(children, 'collection:points')
+  const titleContent = readHeadingSlotContent(title.node, title.text)
   const list = children.find(isListNode)
 
   if (!list)
     failMarkdownContract('collection:points', 'ожидает markdown list с тремя пунктами.')
 
-  const items = readListItems(list, 'collection:points')
+  const listItems = readListItemNodes(list, 'collection:points')
+    .map(node => ({
+      text: readListItemText(node),
+      content: readListItemSlotContent(node),
+    }))
+  const items = listItems
+    .filter(item => item.text)
+    .map(item => item.content)
+
   if (items.length !== 3)
     failMarkdownContract('collection:points', 'ожидает ровно три пункта для arrangement: trio.')
 
@@ -720,7 +797,7 @@ function buildPointsChildren(children: VNode[], context: LayoutShorthandContext)
     hSlot(context, 'primary', 'slide-collection-points-primary', {
       ...(context.frontmatterDecor ? { decor: context.frontmatterDecor } : {}),
     }, [
-      hText(context, 'h1', '7', title.text, { className: 'Slide-PointsTitle' }),
+      hText(context, 'h1', '7', titleContent, { className: 'Slide-PointsTitle' }),
     ]),
     ...items.map((item, index) =>
       hSlot(context, 'support', `slide-collection-points-support-${index + 1}`, {}, [
@@ -777,6 +854,7 @@ function buildComparisonSideChildren(
 
 function buildComparisonChildren(children: VNode[], context: LayoutShorthandContext) {
   const title = readHeadingText(children, 'collection:comparison')
+  const titleContent = readHeadingSlotContent(title.node, title.text)
   const comparison = context.readFrontmatterObject('comparison')
 
   if (!comparison)
@@ -795,7 +873,7 @@ function buildComparisonChildren(children: VNode[], context: LayoutShorthandCont
 
   return [
     hSlot(context, 'primary', `slide-collection-${context.variant}-primary`, {}, [
-      hText(context, 'h1', '6', title.text),
+      hText(context, 'h1', '6', titleContent),
     ]),
     buildComparisonSideChildren(context, from, 0),
     buildComparisonSideChildren(context, to, 1),
@@ -825,12 +903,13 @@ type StepItem = {
 function normalizeStepItems(context: LayoutShorthandContext): StepItem[] {
   const items = context.readFrontmatterArray('items')
   const isStaggered = context.variant === 'steps-staggered'
+  const minItems = isStaggered ? 2 : 3
 
-  if (items.length < 3 || items.length > 6)
-    failMarkdownContract('collection:steps', 'ожидает от 3 до 6 элементов во frontmatter items.')
-
-  if (isStaggered && items.length !== 5)
-    failMarkdownContract('collection:steps', 'arrangement: staggered ожидает ровно 5 элементов.')
+  if (items.length < minItems || items.length > 6) {
+    const range = isStaggered ? 'от 2 до 6' : 'от 3 до 6'
+    const prefix = isStaggered ? 'arrangement: staggered ' : ''
+    failMarkdownContract('collection:steps', `${prefix}ожидает ${range} элементов во frontmatter items.`)
+  }
 
   const normalized = items.map((item, index) => {
     if (typeof item !== 'object' || item === null || Array.isArray(item))
@@ -858,6 +937,7 @@ function normalizeStepItems(context: LayoutShorthandContext): StepItem[] {
 
 function buildStepsChildren(children: VNode[], context: LayoutShorthandContext) {
   const title = readHeadingText(children, 'collection:steps')
+  const titleContent = readHeadingSlotContent(title.node, title.text)
   const items = normalizeStepItems(context)
   const arrangement = context.variant === 'steps-staggered' ? 'staggered' : 'linear'
 
@@ -868,25 +948,13 @@ function buildStepsChildren(children: VNode[], context: LayoutShorthandContext)
 
   return [
     hSlot(context, 'primary', `slide-collection-${context.variant}-primary`, {}, [
-      hText(context, 'h1', '6', title.text),
+      hText(context, 'h1', '6', titleContent),
     ]),
     hSlot(context, 'support', `slide-collection-${context.variant}-support`, {}, [
-      h('div', {
-        'class': ['Slide-StepsGrid', `Slide-StepsGrid_${arrangement}`],
-        'data-count': String(items.length),
-        'style': { '--slide-steps-count': items.length },
-      }, items.map((item, index) =>
-        h('article', {
-          'class': ['Slide-Step', item.active ? 'Slide-Step_active' : ''],
-          'data-index': String(index + 1),
-        }, [
-          hText(context, 'div', '2', item.label, { muted: !item.active }),
-          hText(context, 'div', '4-5', item.title, { priority: 1 }),
-          ...(item.body
-            ? [hText(context, 'div', '2-3', item.body, { priority: 2, muted: true })]
-            : []),
-        ]),
-      )),
+      h(context.components.StepsGrid, {
+        items,
+        arrangement,
+      }),
     ]),
   ]
 }
@@ -918,8 +986,9 @@ function normalizeTimelineItems(context: LayoutShorthandContext) {
 
 function buildTimelineChildren(children: VNode[], context: LayoutShorthandContext) {
   const title = readHeadingText(children, 'collection:timeline')
+  const titleContent = readHeadingSlotContent(title.node, title.text)
   const paragraph = readParagraphText(children)
-  const body = context.readFrontmatterText('body') || paragraph?.text || ''
+  const body = context.readFrontmatterText('body') || paragraph?.content || ''
 
   ensureOnlySupportedChildren('collection:timeline', children, node =>
     node === title.node
@@ -929,7 +998,7 @@ function buildTimelineChildren(children: VNode[], context: LayoutShorthandContex
 
   return [
     hSlot(context, 'primary', 'slide-collection-timeline-primary', {}, [
-      hText(context, 'h1', '6', title.text),
+      hText(context, 'h1', '6', titleContent),
     ]),
     ...(body
       ? [
@@ -1002,7 +1071,7 @@ function normalizeMetricItemsFromList(list: VNode) {
     failMarkdownContract('collection:metrics', 'ожидает минимум три пункта в markdown-списке.')
 
   return entries.map((entry, index) => {
-    if (!entry.label)
+    if (!hasRichSlotContent(entry.label))
       failMarkdownContract('collection:metrics', `ожидает вложенный пункт с подписью у metric[${index}].`)
 
     return {
@@ -1034,6 +1103,7 @@ function normalizeMediaItems(context: LayoutShorthandContext) {
 function buildMetricsChildren(children: VNode[], context: LayoutShorthandContext) {
   if (context.variant === 'metrics-dashboard') {
     const title = readHeadingText(children, 'collection:metrics')
+    const titleContent = readHeadingSlotContent(title.node, title.text)
     const metrics = normalizeDashboardMetrics(context)
     const fitGroup = 'collection-metrics-dashboard'
 
@@ -1044,7 +1114,7 @@ function buildMetricsChildren(children: VNode[], context: LayoutShorthandContext
 
     return [
       hSlot(context, 'primary', 'slide-collection-metrics-dashboard-primary', {}, [
-        hText(context, 'h1', '6', title.text),
+        hText(context, 'h1', '6', titleContent),
       ]),
       ...metrics.map((metric, index) =>
         hSlot(context, 'support', `slide-collection-metrics-dashboard-support-${index + 1}`, {
@@ -1167,7 +1237,7 @@ function buildFactsChildren(children: VNode[], context: LayoutShorthandContext)
   }
 
   facts.forEach((fact, index) => {
-    if (!fact.label) {
+    if (!hasRichSlotContent(fact.label)) {
       failMarkdownContract(
         'collection:facts',
         `ожидает вложенный пункт с подписью у facts[${index}].`,
@@ -1186,8 +1256,6 @@ function buildFactsChildren(children: VNode[], context: LayoutShorthandContext)
   const factFitGroup = shouldCoordinateFactSizes ? `collection-${context.variant}-facts` : ''
   const supportFactFitGroup = isFeatured ? `collection-${context.variant}-support-facts` : factFitGroup
   const headingText = readInlineText(heading)
-  const descriptionText = description ? readInlineText(description) : ''
-  const footnoteText = footnote ? readInlineText(footnote) : ''
   const rowFactSize: ThemeTextSizeInput = isQuartet ? '5-8' : isDuo ? '5-10' : '5-9'
   const stackedFactSize: ThemeTextSizeInput = '5-9'
   const stackedLabelSize: ThemeTextSizeInput = '3-5'
@@ -1196,24 +1264,30 @@ function buildFactsChildren(children: VNode[], context: LayoutShorthandContext)
   const supportFactSize: ThemeTextSizeInput = isFeatured ? '5-7' : isStacked ? stackedFactSize : rowFactSize
   const featuredLabelSize: ThemeTextSizeInput = isFeatured ? '4-6' : isStacked ? stackedLabelSize : rowLabelSize
   const supportLabelSize: ThemeTextSizeInput = isFeatured ? '2-4' : isStacked ? stackedLabelSize : rowLabelSize
+  const headingContent = readHeadingSlotContent(heading, headingText)
+  const descriptionContent = description ? readParagraphSlotContent(description, readInlineText(description)) : ''
+  const footnoteContent = footnote ? readParagraphSlotContent(footnote, readInlineText(footnote)) : ''
+  const hasFootnote = Array.isArray(footnoteContent)
+    ? footnoteContent.length > 0
+    : Boolean(footnoteContent)
 
   const primaryChildren: VNode[] = [
-    hText(context, 'h2', isFeatured ? '5-7' : '6-8', headingText, { priority: 1 }),
+    hText(context, 'h2', isFeatured ? '5-7' : '6-8', headingContent, { priority: 1 }),
   ]
 
-  if (descriptionText)
-    primaryChildren.push(hText(context, 'p', isStacked ? '4-5' : '3-4', descriptionText, { priority: 2, muted: true }))
+  if (descriptionContent)
+    primaryChildren.push(hText(context, 'p', isStacked ? '4-5' : '3-4', descriptionContent, { priority: 2, muted: true }))
 
-  if (footnoteText && factFitGroup)
-    primaryChildren.push(hText(context, 'div', '2-3', footnoteText, { priority: 3, muted: true }))
+  if (hasFootnote && factFitGroup)
+    primaryChildren.push(hText(context, 'div', '2-3', footnoteContent, { priority: 3, muted: true }))
 
   const featuredChildren: VNode[] = [
     hText(context, 'div', featuredFactSize, featured.value, { priority: 1 }),
     hText(context, 'div', featuredLabelSize, featured.label, { priority: 2, muted: true }),
   ]
 
-  if (footnoteText && !factFitGroup)
-    featuredChildren.push(hText(context, 'div', '2-3', footnoteText, { priority: 3, muted: true }))
+  if (hasFootnote && !factFitGroup)
+    featuredChildren.push(hText(context, 'div', '2-3', footnoteContent, { priority: 3, muted: true }))
 
   if (isNumberedQuartet) {
     return [

package/composables/local-layout-variant-files.ts

@@ -0,0 +1,106 @@
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { hasLayoutVariant, type ThemeLayout } from './layout-recipes'
+
+export type DeckLayoutVariantFile = {
+  key: string
+  layout: ThemeLayout
+  variant: string
+  path: string
+}
+
+export const DECK_LAYOUT_VARIANTS_VIRTUAL_ID = 'virtual:practicum-deck-layout-variants'
+export const RESOLVED_DECK_LAYOUT_VARIANTS_VIRTUAL_ID = '\0virtual:practicum-deck-layout-variants'
+
+const THEME_LAYOUTS = new Set<ThemeLayout>(['cover', 'message', 'explainer', 'collection'])
+const VARIANT_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+export function deckLayoutVariantsDirectory(root: string) {
+  return join(root, 'components', 'layout-variants')
+}
+
+function readDirectory(path: string) {
+  try {
+    return readdirSync(path, { withFileTypes: true })
+  }
+  catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+      return []
+    throw error
+  }
+}
+
+export function discoverDeckLayoutVariantFiles(root: string): DeckLayoutVariantFile[] {
+  const directory = deckLayoutVariantsDirectory(root)
+  const layoutEntries = readDirectory(directory)
+
+  for (const entry of layoutEntries) {
+    if (entry.isFile() && entry.name.endsWith('.vue')) {
+      throw new Error(
+        `[Practicum] Локальный вариант "${entry.name}" должен лежать в components/layout-variants/<layout>/${entry.name}.`,
+      )
+    }
+
+    if (entry.isDirectory() && !THEME_LAYOUTS.has(entry.name as ThemeLayout)) {
+      throw new Error(
+        `[Practicum] "${entry.name}" не является тематическим layout. Для нового layout создайте layouts/${entry.name}.vue.`,
+      )
+    }
+  }
+
+  return layoutEntries
+    .filter(entry => entry.isDirectory() && THEME_LAYOUTS.has(entry.name as ThemeLayout))
+    .flatMap((layoutEntry) => {
+      const layout = layoutEntry.name as ThemeLayout
+      const layoutDirectory = join(directory, layout)
+
+      return readDirectory(layoutDirectory)
+        .filter(entry => entry.isFile() && entry.name.endsWith('.vue'))
+        .map((entry) => {
+          const variant = entry.name.slice(0, -'.vue'.length)
+
+          if (!VARIANT_ID_PATTERN.test(variant)) {
+            throw new Error(
+              `[Practicum] Локальный вариант "${layout}/${entry.name}" должен иметь kebab-case имя, например "lesson-summary.vue".`,
+            )
+          }
+
+          if (hasLayoutVariant(layout, variant)) {
+            throw new Error(
+              `[Practicum] Локальный вариант "${layout}:${variant}" конфликтует со встроенным вариантом темы.`,
+            )
+          }
+
+          return {
+            key: `${layout}:${variant}`,
+            layout,
+            variant,
+            path: join(layoutDirectory, entry.name),
+          }
+        })
+    })
+    .sort((left, right) => left.key.localeCompare(right.key))
+}
+
+function toViteFileId(path: string) {
+  const normalized = path.replaceAll('\\', '/')
+  return `/@fs${normalized.startsWith('/') ? '' : '/'}${normalized}`
+}
+
+export function createDeckLayoutVariantModuleSource(files: readonly DeckLayoutVariantFile[]) {
+  const imports = files.map((file, index) =>
+    `import DeckLayoutVariant${index} from ${JSON.stringify(toViteFileId(file.path))}`,
+  )
+  const entries = files.map((file, index) =>
+    `  ${JSON.stringify(file.key)}: DeckLayoutVariant${index},`,
+  )
+
+  return [
+    ...imports,
+    '',
+    'export const DECK_LAYOUT_VARIANTS = Object.freeze({',
+    ...entries,
+    '})',
+    '',
+  ].join('\n')
+}

package/composables/local-layout-variants.ts

@@ -0,0 +1,73 @@
+import { h, type Component, type VNode } from 'vue'
+import type { ThemeLayout } from './layout-recipes'
+
+export type DeckLayoutVariantCatalog = Readonly<Record<string, Component>>
+
+export type DeckLayoutVariantProps<Frontmatter extends object = Record<string, unknown>> = {
+  layout: ThemeLayout
+  variant: string
+  frontmatter: Readonly<Frontmatter>
+}
+
+export type DeckLayoutVariantSlots = {
+  default(): VNode[]
+}
+
+export type SlideDeckLayoutVariantContractError = Error & {
+  name: 'SlideMarkdownContractError'
+  hint?: string
+}
+
+function failDeckLayoutVariantContract(message: string, hint?: string): never {
+  const error = new Error(`[Slide] Локальный вариант ${message}`) as SlideDeckLayoutVariantContractError
+  error.name = 'SlideMarkdownContractError'
+  if (hint)
+    error.hint = hint
+  throw error
+}
+
+export function deckLayoutVariantKey(layout: ThemeLayout, variant: string) {
+  return `${layout}:${variant}`
+}
+
+export function resolveDeckLayoutVariant(input: {
+  layout: ThemeLayout
+  variant: string
+  arrangement: string
+  variants: DeckLayoutVariantCatalog
+}) {
+  const component = input.variants[deckLayoutVariantKey(input.layout, input.variant)]
+
+  if (component && input.arrangement) {
+    failDeckLayoutVariantContract(
+      `"${input.layout}:${input.variant}" не поддерживает arrangement: ${input.arrangement}.`,
+      'Удалите `arrangement` либо используйте встроенный вариант темы.',
+    )
+  }
+
+  if (component)
+    return component
+
+  failDeckLayoutVariantContract(
+    `"${input.layout}:${input.variant}" не найден.`,
+    `Создайте components/layout-variants/${input.layout}/${input.variant}.vue в проекте презентации.`,
+  )
+}
+
+export function buildDeckLayoutVariantVNode(input: {
+  layout: ThemeLayout
+  variant: string
+  component: Component
+  frontmatter: Record<string, unknown>
+  children: readonly VNode[]
+}) {
+  const frontmatter = Object.freeze({ ...input.frontmatter })
+
+  return h(input.component, {
+    layout: input.layout,
+    variant: input.variant,
+    frontmatter,
+  } satisfies DeckLayoutVariantProps, {
+    default: () => [...input.children],
+  })
+}