slidev-theme-practicum 0.2.0 → 0.4.0

package/scripts/typography-browser.mjs

@@ -0,0 +1,134 @@
+import { inspectTypography } from '../composables/typography-guard.cjs'
+
+export async function settleTypography(slide) {
+  await slide.evaluate(async (root) => {
+    const timeout = new Promise((_, reject) => setTimeout(
+      () => reject(new Error('Шрифты или изображения не загрузились за 5 секунд.')), 5_000,
+    ))
+    await Promise.race([
+      Promise.all([
+        document.fonts.ready,
+        ...[...root.querySelectorAll('img')].map(image => image.decode().catch(() => undefined)),
+      ]),
+      timeout,
+    ])
+    await new Promise((resolveStable, rejectStable) => {
+      const deadline = performance.now() + 5_000
+      let previous = ''
+      let stableFrames = 0
+      function observe() {
+        const signature = [...root.querySelectorAll('.Slot, .Slot-Content, .Text, .Text *')]
+          .map((element) => {
+            const style = getComputedStyle(element)
+            const rect = element.getBoundingClientRect()
+            return [element.className, element.textContent, style.fontSize, style.color,
+              rect.x, rect.y, rect.width, rect.height, element.scrollWidth, element.scrollHeight].join(':')
+          }).join('|')
+        stableFrames = signature === previous ? stableFrames + 1 : 0
+        previous = signature
+        if (stableFrames >= 8)
+          resolveStable()
+        else if (performance.now() >= deadline)
+          rejectStable(new Error('Типографика слайда не стабилизировалась за 5 секунд.'))
+        else
+          requestAnimationFrame(observe)
+      }
+      requestAnimationFrame(observe)
+    })
+  })
+}
+
+// Функция передаётся в браузер целиком, поэтому не использует внешние замыкания.
+export function collectRenderedTypography(root) {
+  const content = root.querySelector('.Slide-Grid') ?? root.querySelector('.slidev-layout') ?? root
+  const excluded = '.Slide-Header, .Header, .Logo, .Slot-Background, .ImageRenderer, svg, img, canvas, video, audio, script, style'
+  const slots = [...content.querySelectorAll('.Slot')]
+  const texts = []
+  const issues = []
+  const walker = document.createTreeWalker(content, NodeFilter.SHOW_TEXT)
+  const canvas = document.createElement('canvas')
+  canvas.width = canvas.height = 1
+  const colorContext = canvas.getContext('2d', { willReadFrequently: true })
+  if (!colorContext)
+    throw new Error('Не удалось нормализовать вычисленные цвета в sRGB.')
+  const colors = new Map()
+
+  function normalizeColor(value) {
+    if (!colors.has(value)) {
+      colorContext.clearRect(0, 0, 1, 1)
+      colorContext.fillStyle = value
+      colorContext.fillRect(0, 0, 1, 1)
+      const [red, green, blue, alpha] = colorContext.getImageData(0, 0, 1, 1).data
+      colors.set(value, `rgba(${red}, ${green}, ${blue}, ${alpha / 255})`)
+    }
+    return colors.get(value)
+  }
+
+  function visible(element) {
+    for (let current = element; current; current = current.parentElement) {
+      const style = getComputedStyle(current)
+      if (style.display === 'none' || style.visibility !== 'visible' || Number(style.opacity) === 0)
+        return false
+      if (current === root)
+        break
+    }
+    return true
+  }
+
+  while (walker.nextNode()) {
+    const node = walker.currentNode
+    const element = node.parentElement
+    const text = node.textContent.replace(/\s+/gu, ' ').trim().slice(0, 100)
+    if (!text || !element || element.closest(excluded) || !visible(element))
+      continue
+    const range = document.createRange()
+    range.selectNodeContents(node)
+    const rects = [...range.getClientRects()].filter(rect => rect.width > 0 && rect.height > 0)
+    if (!rects.length)
+      continue
+    const slotElement = element.closest('.Slot')
+    const slot = slotElement ? `Slot ${slots.indexOf(slotElement) + 1}` : 'Слайд вне Slot'
+    const style = getComputedStyle(element)
+    const textElement = element.closest('.Text')
+    texts.push({
+      text,
+      slot,
+      size: `${Math.round(Number.parseFloat(style.fontSize) * 100) / 100}px`,
+      color: normalizeColor(style.color),
+      keyNumber: textElement?.tagName === 'DATA',
+      muted: Boolean(element.closest('.Text_muted, [data-text-color^="text-muted"]')),
+    })
+
+    // Проверяем также внешний Slot: вложенная композиция не должна вытекать из него.
+    for (let current = slotElement; current; current = current.parentElement?.closest('.Slot')) {
+      const boundsElement = current.querySelector(':scope > .Slot-Content') ?? current
+      const bounds = boundsElement.getBoundingClientRect()
+      const scaleY = current.getBoundingClientRect().height / current.offsetHeight || 1
+      const lineHeight = Number.parseFloat(style.lineHeight) * scaleY
+      const overflow = Math.max(0, ...rects.flatMap((rect) => {
+        // Range включает метрики шрифта за пределами CSS-строки даже у
+        // корректного заголовка. По вертикали проверяем именно строку.
+        const leading = Number.isFinite(lineHeight) ? Math.max(0, rect.height - lineHeight) / 2 : 0
+        return [
+          bounds.left - rect.left, rect.right - bounds.right,
+          bounds.top - rect.top - leading, rect.bottom - leading - bounds.bottom,
+        ]
+      }))
+      if (overflow > 1) {
+        issues.push({
+          code: 'text-overflow',
+          message: `Slot ${slots.indexOf(current) + 1}: «${text}» выходит за границы текста слота на ${overflow.toFixed(1)} px.`,
+          hint: 'Сократите текст или измените композицию, сохранив число размеров.',
+        })
+        break
+      }
+    }
+  }
+  return { texts, issues }
+}
+
+export async function inspectRenderedTypography(slide) {
+  await settleTypography(slide)
+  const { texts, issues } = await slide.evaluate(collectRenderedTypography)
+  return { textCount: texts.length, issues: [...issues, ...inspectTypography(texts)] }
+}

package/scripts/validate-deck.cjs

@@ -1,12 +1,32 @@
 #!/usr/bin/env node
 const { resolve } = require('node:path')
+const { parseArgs } = require('node:util')
 const { formatDeckLayoutIssues, validateDeckLayouts } = require('../composables/validate-deck-layouts.cjs')
 
-const deckPath = resolve(process.argv[2] ?? 'example.md')
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    'typography-guard': { type: 'boolean', default: false },
+    'help': { type: 'boolean', short: 'h' },
+  },
+})
+if (values.help) {
+  console.log('Использование: slidev-practicum-validate [slides.md] [--typography-guard]\n'
+    + '--typography-guard проверяет объявленные политики Text. Фактический результат проверяйте командой slidev-practicum-check-typography.')
+  process.exit(0)
+}
+if (positionals.length > 1) {
+  console.error('Укажите один файл колоды.')
+  process.exit(1)
+}
+const deckPath = resolve(positionals[0] ?? 'example.md')
+const typographyGuard = values['typography-guard']
 
-validateDeckLayouts(deckPath).then((issues) => {
+validateDeckLayouts(deckPath, { typographyGuard }).then((issues) => {
   if (!issues.length) {
-    console.log(`OK: ${deckPath} — контракты layout/markdown соблюдены.`)
+    console.log(`OK: ${deckPath} — контракты макетов, Markdown и локальных вариантов соблюдены.`)
+    if (typographyGuard)
+      console.log('Объявленные политики Text соблюдены. Для размеров после подбора, Markdown и компонентов выполните slidev-practicum-check-typography.')
     process.exit(0)
   }
 

package/setup/vite-plugins.ts

@@ -1,19 +1,124 @@
-import { resolve } from 'node:path'
+import { relative, resolve, sep } from 'node:path'
 import type { ResolvedSlidevOptions } from '@slidev/types'
 import type { Plugin } from 'vite'
+import {
+  collectDeckDecorFiles,
+  DECK_DECORS_VIRTUAL_ID,
+  resolveDeckFileDecors,
+  RESOLVED_DECK_DECORS_VIRTUAL_ID,
+} from '../composables/deck-decors'
 import { createFileDecorStore } from '../composables/decor-file-store'
+import { isRecord } from '../composables/decor-sources'
 import { createDecorSaveMiddleware } from './decor-save-middleware'
+import {
+  createDeckLayoutVariantModuleSource,
+  deckLayoutVariantsDirectory,
+  DECK_LAYOUT_VARIANTS_VIRTUAL_ID,
+  discoverDeckLayoutVariantFiles,
+  RESOLVED_DECK_LAYOUT_VARIANTS_VIRTUAL_ID,
+} from '../composables/local-layout-variant-files'
 
 const OUTPUT_PATH = resolve(process.cwd(), 'composables/decor-tuning-overrides.mjs')
 
 type DecorLibraryVitePluginContext = Pick<ResolvedSlidevOptions, 'data'>
+  & Partial<Pick<ResolvedSlidevOptions, 'userRoot'>>
+
+function readThemeConfig(options?: DecorLibraryVitePluginContext) {
+  const value = options?.data?.config?.themeConfig
+  return isRecord(value) ? value : {}
+}
 
 function readExpectedOrigin(options?: DecorLibraryVitePluginContext) {
-  const value = options?.data.config.themeConfig.decorSaveOrigin
+  const value = readThemeConfig(options).decorSaveOrigin
 
   return typeof value === 'string' && value.trim() ? value : undefined
 }
 
+function createDeckDecorsPlugin(options?: DecorLibraryVitePluginContext): Plugin {
+  const root = process.cwd()
+
+  function spec() {
+    return {
+      decors: readThemeConfig(options).decors,
+      root,
+    }
+  }
+
+  return {
+    name: 'practicum:deck-decors',
+    async config() {
+      return {
+        define: {
+          __PRATICUM_DECK_DECORS__: JSON.stringify(await resolveDeckFileDecors(spec())),
+        },
+        optimizeDeps: {
+          exclude: ['slidev-theme-practicum'],
+        },
+      }
+    },
+    resolveId(id) {
+      if (id === DECK_DECORS_VIRTUAL_ID)
+        return RESOLVED_DECK_DECORS_VIRTUAL_ID
+    },
+    async load(id) {
+      if (id !== RESOLVED_DECK_DECORS_VIRTUAL_ID)
+        return
+
+      const current = spec()
+      for (const path of collectDeckDecorFiles(current))
+        this.addWatchFile(path)
+
+      return `export const DECK_FILE_DECORS = ${JSON.stringify(await resolveDeckFileDecors(current))}\n`
+    },
+    configureServer(server) {
+      const watcher = server.watcher
+      if (!watcher?.add)
+        return
+
+      for (const path of collectDeckDecorFiles(spec()))
+        watcher.add(path)
+    },
+  }
+}
+
+function createDeckLayoutVariantsPlugin(options?: DecorLibraryVitePluginContext): Plugin {
+  const root = options?.userRoot ?? process.cwd()
+
+  return {
+    name: 'practicum:deck-layout-variants',
+    resolveId(id) {
+      if (id === DECK_LAYOUT_VARIANTS_VIRTUAL_ID)
+        return RESOLVED_DECK_LAYOUT_VARIANTS_VIRTUAL_ID
+    },
+    load(id) {
+      if (id !== RESOLVED_DECK_LAYOUT_VARIANTS_VIRTUAL_ID)
+        return
+
+      const files = discoverDeckLayoutVariantFiles(root)
+      for (const file of files)
+        this.addWatchFile(file.path)
+
+      return createDeckLayoutVariantModuleSource(files)
+    },
+    configureServer(server) {
+      server.watcher.add(deckLayoutVariantsDirectory(root))
+    },
+    handleHotUpdate(context) {
+      const relativeFile = relative(deckLayoutVariantsDirectory(root), context.file)
+      const segments = relativeFile.split(sep)
+      if (segments.length !== 2 || relativeFile.startsWith(`..${sep}`) || !context.file.endsWith('.vue'))
+        return
+
+      const virtualModule = context.server.moduleGraph.getModuleById(RESOLVED_DECK_LAYOUT_VARIANTS_VIRTUAL_ID)
+      if (virtualModule)
+        context.server.moduleGraph.invalidateModule(virtualModule)
+
+      context.server.ws.send({ type: 'full-reload' })
+      return []
+    },
+  }
+}
+
 export default function decorLibraryVitePlugins(
   options?: DecorLibraryVitePluginContext,
 ): Plugin[] {
@@ -32,5 +137,7 @@ export default function decorLibraryVitePlugins(
         }))
       },
     },
+    createDeckDecorsPlugin(options),
+    createDeckLayoutVariantsPlugin(options),
   ]
 }

package/skills/slidev-practicum/SKILL.md

@@ -1,15 +1,17 @@
 ---
 name: slidev-practicum
-description: Используй, когда нужно создать, отредактировать, проверить или экспортировать Slidev-презентацию для slidev-theme-practicum, Яндекс Практикума, стиля Практикума или запроса вроде «слайды в стиле Практикума».
+description: Используй для Slidev-презентаций, фотографических и предметных контурных иллюстраций в стиле slidev-theme-practicum или Яндекс Практикума.
 ---
 
 # Slidev Практикума
 
-Используй этот скилл как тонкий маршрутизатор для коротких запросов вроде «сделай слайды в стиле Практикума».
+Используй этот скилл как тонкий маршрутизатор для колод, фотографических и контурных иллюстраций темы.
 
-**ОБЯЗАТЕЛЬНЫЙ ПОДСКИЛЛ:** используй `slidev` для платформенной механики: Markdown-синтаксиса, frontmatter, блоков кода, заметок, анимаций, dev-сервера, сборки и экспорта.
+## Колода
 
-Для авторинга в стиле Практикума не дублируй правила из документации темы. Читай локальный источник истины:
+**ОБЯЗАТЕЛЬНЫЙ ПОДСКИЛЛ:** используй `slidev` для Markdown-синтаксиса, frontmatter, кода, заметок, анимаций, dev-сервера, сборки и экспорта.
+
+Не дублируй правила темы. Читай локальный источник истины:
 
 - `README.md` — публичный авторский контракт, лейауты, компоненты, `themeConfig`, декор и правила контента.
 - `example.md` — канонические паттерны слайдов, которые нужно копировать и адаптировать.
@@ -20,6 +22,19 @@ description: Используй, когда нужно создать, отре
 - Внутри этого репозитория используй `theme: ./`.
 - Во внешней колоде с установленным пакетом используй `theme: practicum`.
 - Пиши по-русски, если пользователь не попросил другой язык.
+- Если для колоды выбрана строгая типографика, прочитай раздел README темы «Строгая проверка типографики», включая пример слайда и порядок работы агента. Во внешней колоде источник — `node_modules/slidev-theme-practicum/README.md`. Проверяй объявления через `npm exec -- slidev-practicum-validate slides.md --typography-guard`, затем фактический результат свежей сборки через `npm exec -- slidev-practicum-check-typography slides.md --dist dist`. Отмечай ключевые числа явно через `Text as="data"`, не назначай это исключение датам и номерам шагов автоматически. Не считай статическую проверку достаточной для Markdown, динамических атрибутов и автоматического подбора размеров. После исправлений пересобери колоду и повтори проверки по порядку из README.
 - Выбирай тип слайда по задаче кадра, следуя `README.md`.
+- Используй верхнеуровневый `title` только в первом headmatter как служебное название всей колоды. Не считай его видимым содержимым: пиши основной заголовок каждого кадра в теле слайда как Markdown `# …`, а для явной композиции — как видимый `<Text as="h1">…</Text>`. Вложенные `title` моделей компонентов сохраняй по контракту варианта.
+- Для повторяющейся композиции конкретной колоды без Vue-тегов в `slides.md` используй `components/layout-variants/<layout>/<variant>.vue` и существующие поля front matter `layout` + `variant`; точный контракт бери из раздела README «Локальные варианты презентации».
+
+Перед созданием структуры новой колоды, добавлением локального медиа или реорганизацией существующей колоды полностью прочитай `references/deck-project-structure.md`. Он владеет каноническим деревом проекта, классификацией `public/decor`, `public/photos`, `public/illustrations`, `public/figures`, правилами путей и именования. Не создавай альтернативные общие каталоги `assets` или `images`.
 
 Не используй `slidev-theme-architect-skill.md` для обычных колод; он нужен для создания или редизайна theme package.
+
+## Контурная иллюстрация
+
+Перед созданием, перерисовкой или векторизацией предметной контурной иллюстрации полностью прочитай `references/contour-illustrations.md`. Он владеет референсами, растровой генерацией, трассировкой и приёмкой. Документы колоды загружай только если задача одновременно меняет слайд.
+
+## Фотографическая иллюстрация
+
+Перед созданием, редактированием или приёмкой сюжетной фотографической иллюстрации полностью прочитай `references/photographic-illustrations.md`. Он владеет семантическими ролями изображений, распределением ролей между референсами, карточкой сложной сцены, масштабом, физическими контактами, перспективой жёстких объектов и проверкой увеличений. Документы конкретной колоды загружай только для её персонажей, предметов, окружения и сюжета.

package/skills/slidev-practicum/references/contour-illustrations.md

@@ -0,0 +1,114 @@
+# Контурные иллюстрации
+
+Используй этот протокол для одного самостоятельного предмета в контурном стиле темы: создать, перерисовать или перевести в SVG. Многообъектной сцене нужен отдельный композиционный замысел.
+
+Пути ниже относительны корню `slidev-theme-practicum`.
+
+## Результат
+
+Одна и та же принятая иллюстрация сохраняется в двух форматах:
+
+- PNG — чёрный растр с настоящим альфа-каналом;
+- SVG — его векторная трассировка с `currentColor`, русским `<title>` и без встроенного растра.
+
+Для иллюстрации конкретной колоды используй её `public/illustrations/<slug>.{png,svg}` по контракту `deck-project-structure.md`. Не перемещай контурный предмет в `public/decor` только потому, что он используется как декор. В `public/decor` темы добавляй только переиспользуемый графический декор; вместе с ним обнови каталог декора и прогони проверки темы.
+
+## Визуальный контракт
+
+- Один узнаваемый предмет, целиком и крупно; безопасный отступ 5–8%.
+- Чистая чёрная линия ровного оптического веса: строгая, гладкая, слегка органичная.
+- Правдоподобные пропорции, перспектива и соединения деталей.
+- Трёхчетвертной или диагональный ракурс, если он лучше раскрывает конструкцию; осевая фронтальность — когда важна симметрия.
+- Прозрачный фон, одна краска, без теней, заливок, градиентов, фактур и подложки.
+- Текст и символические атрибуты — только дословно из задания.
+- Детализация сохраняет силуэт и обязательные соединения при размере 320 пикселей.
+
+По умолчанию используй квадратный холст не меньше 1024×1024. Для явно широкого или высокого предмета выбери естественное соотношение сторон. Несколько размеров или вариантов одного предмета создавай только по отдельному запросу.
+
+## Референсы
+
+Для характера линии и меры детализации выбери 2–4 подходящих SVG из:
+
+```text
+public/decor/decor-{1,3,4,8,9,10,13,14,15,16,19}.svg
+```
+
+Для цельности предмета и ожидаемого комплекта PNG/SVG используй:
+
+```text
+skills/slidev-practicum/references/illustration-examples/{woodcutter-axe,chainsaw,graduation-cap,balance-scales}.{png,svg}
+```
+
+PNG прикладывай генератору как стилевые референсы; SVG используй для проверки формата. Референс задаёт язык линии, а не предметное содержание.
+
+## Процесс
+
+### 1. Зафиксировать конструкцию
+
+Одним абзацем перечисли узнаваемые части, их физические соединения, подходящий ракурс и нежелательные ассоциации. Шаг завершён, когда результат можно проверить не только «на похожесть», но и на связность конструкции.
+
+### 2. Получить растровый оригинал
+
+Приложи выбранные PNG и передай генератору заполненный промпт:
+
+```text
+Референсы задают только визуальный язык: строгую гладкую контурную линию, слегка органичный характер и меру детализации. Не копируй их предметы.
+
+Нарисуй один отдельный объект: <ПРЕДМЕТ>. Обязательные детали и связи: <ДЕТАЛИ>. Ракурс: <РАКУРС>. Покажи объект целиком и крупно, с отступом 5–8%.
+
+Чистая одноцветная чёрная линия ровного оптического веса; правдоподобные соединения и согласованная перспектива. Настоящий прозрачный фон, а если он недоступен — ровный белый. Без теней, заливок, градиентов, фактур, рамки, окружения, текста, логотипов и случайных символов. Нужен растровый оригинал высокого разрешения для последующей трассировки, не иконка, логотип, чертёж или SVG.
+
+Исключи: <ИСКЛЮЧЕНИЯ>.
+```
+
+Прими растр только после визуальной проверки: предмет узнаваем; пропорции, соединения и перспектива согласованы; силуэт читается; лишних объектов и подложки нет. Крупный дефект исправляй одной целевой перегенерацией, а не ручной правкой SVG.
+
+### 3. Очистить и трассировать
+
+Канонический инструмент — `scripts/trace-line-art.py`; его стандартные параметры и справка являются источником истины. Зафиксированное окружение — `scripts/requirements-illustrations.txt`.
+
+```bash
+python3 -m pip install -r scripts/requirements-illustrations.txt
+python3 scripts/trace-line-art.py <исходник> <каталог>/<slug> --title "<русское название>"
+```
+
+Трассировщик сам выбирает альфа-канал либо яркость, сохраняет очищенный PNG и строит SVG. Промежуточные маски вручную не нужны. Любое переопределение параметров укажи в отчёте.
+
+### 4. Принять комплект
+
+Работа завершена, когда выполнены все условия:
+
+- предмет узнаваем без подписи, конструктивно связен и читается при 320 пикселях;
+- PNG прозрачен; SVG валиден и рендерится;
+- SVG содержит `viewBox`, русский `<title>`, `currentColor` и векторные пути;
+- внутри SVG нет `<image>`, `data:image` и внешнего `href` на растр;
+- после рендера SVG в размере PNG каждая сторона ограничивающей рамки отличается не более чем на 3 пикселя;
+- результат проверен чёрным на `#ffffff`, `#f0f0f0`, `#98d2fe` и белым на `#1e1e1e`;
+- в отчёте есть пути к PNG/SVG, окончательный промпт, генератор и отклонения от стандартной трассировки.
+
+## Диагностика
+
+| Симптом | Действие |
+|---|---|
+| Слабая форма, перспектива или соединения | Перегенерировать растр с одной поправкой |
+| Белый фон или нарисованная шахматка | Подать исходник трассировщику; проверить очищенный PNG на цветной подложке |
+| «Лесенка», гранёные окружности, шипы | Умеренно изменить допуск трассировки и зафиксировать параметры |
+| Параллельные линии слиплись | Вернуться к растру; механическое утолщение часто ухудшает результат |
+| Рисунок стал пиктограммой | Усилить предметность и конструкцию в промпте |
+
+## Короткое задание другому ИИ
+
+Передай этот файл целиком и заполни только параметры:
+
+```xml
+<задание_контурной_иллюстрации>
+  <предмет>{{ОДИН ПРЕДМЕТ}}</предмет>
+  <обязательные_детали>{{ДЕТАЛИ И СОЕДИНЕНИЯ}}</обязательные_детали>
+  <ракурс>{{РАКУРС ИЛИ «ВЫБЕРИ САМ»}}</ракурс>
+  <исключения>{{ЧЕГО НЕ ДОЛЖНО БЫТЬ}}</исключения>
+  <каталог>{{КАТАЛОГ РЕЗУЛЬТАТА}}</каталог>
+  <slug>{{ИМЯ БЕЗ РАСШИРЕНИЯ}}</slug>
+</задание_контурной_иллюстрации>
+```
+
+ИИ самостоятельно проходит весь процесс до проверенных PNG и SVG. Вопрос нужен только при смысловой неоднозначности, которую нельзя разрешить по заданию и референсам.

package/skills/slidev-practicum/references/deck-project-structure.md

@@ -0,0 +1,136 @@
+# Структура проекта колоды
+
+Используй этот контракт при создании новой Slidev-колоды на теме Практикума, при добавлении в неё медиа и при целевой реорганизации существующей колоды.
+
+## Каноническое дерево
+
+```text
+<deck>/
+├── slides.md
+├── decors.yaml
+├── package.json
+├── package-lock.json
+├── README.md
+├── .gitignore
+├── pages/
+├── components/
+│   └── layout-variants/
+├── layouts/
+├── snippets/
+├── styles/
+│   └── index.css
+├── public/
+│   ├── decor/
+│   ├── photos/
+│   ├── illustrations/
+│   └── figures/
+└── reference/
+    └── media-sources.md
+```
+
+Обязательный минимум — `slides.md`, `package.json`, файл блокировки зависимостей и `public/` с реально используемыми подкаталогами. Остальные каталоги создавай только тогда, когда в них появляется содержимое; не добавляй пустую структуру «на будущее».
+
+| Путь | Ответственность |
+|---|---|
+| `slides.md` | Единственная точка входа: общие метаданные и сама колода либо импорты разделов. Для установленного пакета указывай `theme: practicum`; внутри репозитория темы — `theme: ./`. |
+| `decors.yaml` | Необязательный внешний каталог декора колоды. Подключается как `themeConfig.decors: ./decors.yaml` или подхватывается сам, если `decors` не задан. Большой каталог не держи в headmatter `slides.md`. |
+| `package.json` | Зависимости и команды `dev`, `build`, `export`, `validate:slides` для одной точки входа `slides.md`. |
+| `package-lock.json` | Зафиксированное дерево зависимостей. При выбранном другом диспетчере пакетов используй только его один файл блокировки. |
+| `README.md` | Короткие команды запуска, проверки и экспорта, требования к окружению и правила обновления колоды. |
+| `.gitignore` | Результаты сборки, экспорта, кэш Slidev и локальные служебные файлы. |
+| `pages/` | Разделы большой колоды, подключаемые через `src: ./pages/<slug>.md`. Небольшую колоду не дроби без необходимости. |
+| `components/` | Только компоненты, специфичные для этой колоды. Не копируй сюда компоненты и макеты темы. Обычные компоненты Slidev подключает автоматически. |
+| `components/layout-variants/` | Необязательные Vue-композиции для новых вариантов тематических макетов. Файл `components/layout-variants/explainer/lesson-summary.vue` соответствует `layout: explainer` и `variant: lesson-summary`; используй `kebab-case`, ручные координаты `Slot`, не добавляй `arrangement` и не затеняй встроенный вариант темы. |
+| `layouts/` | Нативные макеты Slidev для принципиально новых типов слайда. Например, `layouts/workshop.vue` выбирается через `layout: workshop` и не проходит через механизм вариантов темы. |
+| `snippets/` | Исходный код для вставок вида `<<< @/snippets/<file>`. |
+| `styles/index.css` | Минимальные глобальные переопределения колоды. Сначала используй API и токены темы. |
+| `public/` | Только файлы, которые должны быть доступны в собранной презентации. |
+| `reference/` | Референсы, исходники, лицензии, ссылки и рабочие материалы, которые не должны попадать в сборку и не подключаются из слайдов. |
+
+Не вводи параллельные каталоги `assets/`, `images/`, `img/` или `static/`: они размывают классификацию. В существующей колоде не начинай массовый перенос старых файлов без явного запроса; новые файлы клади по этому контракту, а затронутые старые переноси только вместе с обновлением всех ссылок.
+
+## Классификация медиа
+
+Каталог выбирается по природе и роли файла, а не по конкретному месту на одном слайде.
+
+| Каталог | Что хранить | Обычные форматы | Пример URL |
+|---|---|---|---|
+| `public/decor/` | Графический декор: пятна, паттерны, абстрактные и брендовые композиции без самостоятельного предметного смысла | SVG, PNG, WebP | `/decor/data-flow.svg` |
+| `public/photos/` | Декоративные фотографии и сюжетные фотографические иллюстрации; ни те ни другие не несут единственный факт или инструкцию | WebP, при необходимости PNG/JPEG | `/photos/team-workshop.webp` |
+| `public/illustrations/` | Предметные контурные иллюстрации в визуальном языке темы | парные PNG и SVG | `/illustrations/balance-scales.svg` |
+| `public/figures/` | Информационные изображения: схемы, графики, диаграммы и снимки интерфейса, которые зритель должен рассмотреть | SVG, PNG, WebP | `/figures/research-funnel.svg` |
+
+Правила разрешения пограничных случаев:
+
+- фотография остаётся в `photos`, даже если используется как декоративный фон;
+- сюжетная фотография тоже остаётся в `photos`; её конкретный смысл дублируется заголовком, текстом, подписью или доступным описанием;
+- контурный предмет остаётся в `illustrations`, даже если включён в каталог `themeConfig.decors`;
+- в `decor` не складывай все «картинки для красоты»: это каталог именно графического декора;
+- если изображение содержит необходимый факт, интерфейс или причинно-следственную схему, это `figures`, а смысл должен быть продублирован доступной подписью или текстом слайда;
+- промпты генерации, оригиналы высокого разрешения, мудборды и сведения об источниках храни в `reference/`, а не в `public/`.
+
+Для одной принятой контурной иллюстрации сохраняй комплект с одинаковым именем:
+
+```text
+public/illustrations/balance-scales.png
+public/illustrations/balance-scales.svg
+```
+
+На слайде по умолчанию используй SVG. Полный протокол генерации, трассировки и приёмки находится в `contour-illustrations.md`.
+
+Для сюжетной фотографической иллюстрации до генерации зафиксируй роли референсов, масштаб, граф контактов, предметную конструкцию, камеру и обязательные увеличения. Полный производственный контур находится в `photographic-illustrations.md`.
+
+## Пути в слайдах
+
+Файлы колоды из `public/` доступны от корня сайта. Сегмент `public` в URL не пишется:
+
+```md
+<Image src="/photos/team-workshop.webp" fit="cover" />
+<Image src="/illustrations/balance-scales.svg" fit="contain" />
+```
+
+Встроенные медиа самой темы имеют отдельное пространство имён `/theme`:
+
+```md
+<Image src="/theme/photos/photo-5.webp" fit="cover" />
+<Image src="/theme/decor/decor-10.svg" fit="contain" />
+```
+
+Не используй `/theme` для файлов колоды и не пиши `src="public/..."` или `src="./public/..."`.
+
+Если графический декор колоды должен участвовать в семантическом подборе, зарегистрируй его из корневого headmatter или вынеси во внешний файл. Файл каталога заменяет встроенные картинки темы; для колоды только со своими изображениями закрепляй слоты через `decor.id`.
+
+```yaml
+themeConfig:
+  replaceDecors: true
+  decors: ./decors.yaml
+```
+
+```yaml
+# decors.yaml
+- id: deck-data-flow
+  src: /decor/data-flow.svg
+  meaning: data
+  tone: blue
+```
+
+Короткий список можно оставить inline. Несколько файлов и точечные записи можно смешивать в одном `decors`. Прямое использование через `Image` или `Slot.background` регистрации не требует. Фотографию или контурную иллюстрацию при регистрации не перемещай в `decor`: `src` может ссылаться на `/photos/...` или `/illustrations/...`.
+
+## Имена и подготовка файлов
+
+- Используй строчные семантические имена в `kebab-case`: `team-workshop.webp`, а не `IMG_4821-final-2.webp`.
+- Не нумеруй файлы, если номер не выражает реальную серию. Для вариантов добавляй осмысленный суффикс: `data-flow-wide.svg`, `data-flow-square.svg`.
+- У парных PNG/SVG контурной иллюстрации должен совпадать `<slug>`.
+- Перед добавлением проверь лицензию и зафиксируй источник в `reference/media-sources.md`; не оставляй удалённый URL единственным источником медиа для сборки.
+- Оптимизируй публикуемый файл, но не храни рядом с ним исходники редактора, промежуточные маски и дубликаты форматов, которые не нужны контракту.
+
+## Проверка перед завершением
+
+- Каждый новый файл лежит ровно в одной смысловой категории.
+- Все ссылки начинаются с `/`, а `/theme` используется только для встроенных файлов темы.
+- В `public/` нет референсов, промптов, исходников редактора и неиспользуемых дублей.
+- Фотографии не являются единственным носителем факта или инструкции.
+- Для каждой нетривиальной фотографии понятна роль: декоративная или сюжетная.
+- Контурные иллюстрации сохранены парой PNG/SVG и прошли протокол `contour-illustrations.md`.
+- Каталоги и имена файлов в `components/layout-variants/<layout>/` совпадают со значениями `layout` и `variant` и записаны в `kebab-case`.
+- `npm exec -- slidev-practicum-validate slides.md` и сборка колоды завершаются без ошибок.