slidev-theme-practicum 0.2.0 → 0.3.0

package/scripts/trace-line-art.py

@@ -0,0 +1,422 @@
+#!/usr/bin/env python3
+"""Очищает контурный PNG и трассирует его в SVG с currentColor."""
+
+from __future__ import annotations
+
+import argparse
+import math
+import sys
+from collections import defaultdict
+from html import escape
+from pathlib import Path
+
+try:
+    from PIL import Image
+except ImportError as error:
+    raise SystemExit(
+        "Для трассировки нужен Pillow: установите пакет в используемое Python-окружение"
+    ) from error
+
+
+Point = tuple[int, int]
+Edge = tuple[Point, Point]
+
+
+def parse_arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        add_help=False,
+        description=(
+            "Выделяет чёрный контур по альфа-каналу или яркости, сохраняет "
+            "очищенный PNG и строит SVG из замкнутых путей."
+        )
+    )
+    parser._positionals.title = "позиционные аргументы"
+    parser._optionals.title = "параметры"
+    parser.add_argument(
+        "-h",
+        "--help",
+        action="help",
+        help="показать эту справку и выйти",
+    )
+    parser.add_argument("source", type=Path, help="Исходный PNG")
+    parser.add_argument(
+        "output_prefix",
+        type=Path,
+        help="Путь результата без расширения, например public/illustrations/axe",
+    )
+    parser.add_argument("--title", required=True, help="Русское название для <title>")
+    parser.add_argument(
+        "--threshold",
+        type=int,
+        default=128,
+        help="Порог яркости для непрозрачного исходника, 0–255; по умолчанию 128",
+    )
+    parser.add_argument(
+        "--alpha-threshold",
+        type=int,
+        default=128,
+        help="Порог альфа-канала для прозрачного исходника, 0–255; по умолчанию 128",
+    )
+    parser.add_argument(
+        "--small-span",
+        type=int,
+        default=260,
+        help="Максимальный размах малого контура; по умолчанию 260",
+    )
+    parser.add_argument(
+        "--small-tolerance",
+        type=float,
+        default=1.05,
+        help="Допуск упрощения малого контура; по умолчанию 1.05",
+    )
+    parser.add_argument(
+        "--large-tolerance",
+        type=float,
+        default=2.4,
+        help="Допуск упрощения крупного контура; по умолчанию 2.4",
+    )
+    return parser.parse_args()
+
+
+def create_mask(
+    image: Image.Image,
+    luminance_threshold: int,
+    alpha_threshold: int,
+) -> tuple[list[list[bool]], bool]:
+    rgba = image.convert("RGBA")
+    width, height = rgba.size
+    alpha_minimum, _ = rgba.getchannel("A").getextrema()
+    use_alpha = alpha_minimum < 255
+    pixels = rgba.load()
+    mask_flat: list[bool] = []
+
+    for y in range(height):
+        for x in range(width):
+            red, green, blue, alpha = pixels[x, y]
+            if use_alpha:
+                mask_flat.append(alpha >= alpha_threshold)
+            else:
+                luminance = round(0.2126 * red + 0.7152 * green + 0.0722 * blue)
+                mask_flat.append(luminance < luminance_threshold)
+
+    mask = [
+        mask_flat[row_start : row_start + width]
+        for row_start in range(0, width * height, width)
+    ]
+    return mask, use_alpha
+
+
+def save_clean_png(mask: list[list[bool]], output_path: Path) -> None:
+    height = len(mask)
+    width = len(mask[0])
+    result = Image.new("RGBA", (width, height))
+    result.putdata(
+        [
+            (0, 0, 0, 255 if is_ink else 0)
+            for row in mask
+            for is_ink in row
+        ]
+    )
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    result.save(output_path)
+
+
+def perpendicular_distance(point: Point, start: Point, end: Point) -> float:
+    if start == end:
+        return math.dist(point, start)
+    x, y = point
+    x1, y1 = start
+    x2, y2 = end
+    numerator = abs((y2 - y1) * x - (x2 - x1) * y + x2 * y1 - y2 * x1)
+    return numerator / math.hypot(y2 - y1, x2 - x1)
+
+
+def simplify_open(points: list[Point], tolerance: float) -> list[Point]:
+    if len(points) <= 2:
+        return points
+
+    start = points[0]
+    end = points[-1]
+    maximum_distance = 0.0
+    split_index = 0
+
+    for index in range(1, len(points) - 1):
+        distance = perpendicular_distance(points[index], start, end)
+        if distance > maximum_distance:
+            maximum_distance = distance
+            split_index = index
+
+    if maximum_distance <= tolerance:
+        return [start, end]
+
+    left = simplify_open(points[: split_index + 1], tolerance)
+    right = simplify_open(points[split_index:], tolerance)
+    return left[:-1] + right
+
+
+def simplify_closed(points: list[Point], tolerance: float) -> list[Point]:
+    if len(points) < 5:
+        return points
+
+    first = min(range(len(points)), key=lambda index: (points[index][1], points[index][0]))
+    anchor = points[first]
+    second = max(range(len(points)), key=lambda index: math.dist(points[index], anchor))
+
+    if first > second:
+        first, second = second, first
+
+    first_arc = points[first : second + 1]
+    second_arc = points[second:] + points[: first + 1]
+    simplified = (
+        simplify_open(first_arc, tolerance)[:-1]
+        + simplify_open(second_arc, tolerance)[:-1]
+    )
+
+    deduplicated: list[Point] = []
+    for point in simplified:
+        if not deduplicated or point != deduplicated[-1]:
+            deduplicated.append(point)
+    return deduplicated
+
+
+def build_edges(mask: list[list[bool]]) -> set[Edge]:
+    height = len(mask)
+    width = len(mask[0])
+    edges: set[Edge] = set()
+
+    for y, row in enumerate(mask):
+        for x, is_ink in enumerate(row):
+            if not is_ink:
+                continue
+            if y == 0 or not mask[y - 1][x]:
+                edges.add(((x, y), (x + 1, y)))
+            if x == width - 1 or not mask[y][x + 1]:
+                edges.add(((x + 1, y), (x + 1, y + 1)))
+            if y == height - 1 or not mask[y + 1][x]:
+                edges.add(((x + 1, y + 1), (x, y + 1)))
+            if x == 0 or not mask[y][x - 1]:
+                edges.add(((x, y + 1), (x, y)))
+
+    return edges
+
+
+def edge_direction(edge: Edge) -> int:
+    (x1, y1), (x2, y2) = edge
+    direction = (x2 - x1, y2 - y1)
+    return {(1, 0): 0, (0, 1): 1, (-1, 0): 2, (0, -1): 3}[direction]
+
+
+def trace_contours(edges: set[Edge]) -> list[list[Point]]:
+    outgoing: dict[Point, set[Edge]] = defaultdict(set)
+    for edge in edges:
+        outgoing[edge[0]].add(edge)
+
+    contours: list[list[Point]] = []
+    turn_priority = {1: 0, 0: 1, 3: 2, 2: 3}
+
+    while edges:
+        first_edge = min(edges)
+        start = first_edge[0]
+        current = first_edge
+        contour = [start]
+
+        while current in edges:
+            edges.remove(current)
+            outgoing[current[0]].discard(current)
+            endpoint = current[1]
+            contour.append(endpoint)
+
+            if endpoint == start:
+                break
+
+            candidates = [candidate for candidate in outgoing[endpoint] if candidate in edges]
+            if not candidates:
+                break
+
+            incoming_direction = edge_direction(current)
+            current = min(
+                candidates,
+                key=lambda candidate: turn_priority[
+                    (edge_direction(candidate) - incoming_direction) % 4
+                ],
+            )
+
+        if len(contour) >= 8 and contour[-1] == start:
+            contours.append(contour[:-1])
+
+    return contours
+
+
+def contour_area(points: list[Point]) -> float:
+    return 0.5 * abs(
+        sum(
+            x1 * y2 - x2 * y1
+            for (x1, y1), (x2, y2) in zip(points, points[1:] + points[:1])
+        )
+    )
+
+
+def contour_span(points: list[Point]) -> int:
+    xs = [point[0] for point in points]
+    ys = [point[1] for point in points]
+    return max(max(xs) - min(xs), max(ys) - min(ys))
+
+
+def format_number(value: float) -> str:
+    rounded = round(value, 1)
+    return str(int(rounded)) if rounded.is_integer() else str(rounded)
+
+
+def is_corner(
+    previous: Point,
+    current: Point,
+    following: Point,
+    threshold_degrees: float,
+) -> bool:
+    incoming = (current[0] - previous[0], current[1] - previous[1])
+    outgoing = (following[0] - current[0], following[1] - current[1])
+    incoming_length = math.hypot(*incoming)
+    outgoing_length = math.hypot(*outgoing)
+    if incoming_length == 0 or outgoing_length == 0:
+        return True
+    cosine = max(
+        -1.0,
+        min(
+            1.0,
+            (incoming[0] * outgoing[0] + incoming[1] * outgoing[1])
+            / (incoming_length * outgoing_length),
+        ),
+    )
+    return math.acos(cosine) > math.radians(threshold_degrees)
+
+
+def path_data(contour: list[Point]) -> str:
+    count = len(contour)
+    span = contour_span(contour)
+    corner_threshold = 100 if span <= 120 else 48
+    corners = [
+        is_corner(
+            contour[(index - 1) % count],
+            contour[index],
+            contour[(index + 1) % count],
+            corner_threshold,
+        )
+        for index in range(count)
+    ]
+
+    if any(corners):
+        start_index = corners.index(True)
+        contour = contour[start_index:] + contour[:start_index]
+        corners = corners[start_index:] + corners[:start_index]
+        first = contour[0]
+        commands = [f"M{format_number(first[0])} {format_number(first[1])}"]
+
+        for index in range(1, count):
+            current = contour[index]
+            following = contour[(index + 1) % count]
+            if corners[index]:
+                commands.append(
+                    f"L{format_number(current[0])} {format_number(current[1])}"
+                )
+            else:
+                midpoint = (
+                    (current[0] + following[0]) / 2,
+                    (current[1] + following[1]) / 2,
+                )
+                commands.append(
+                    "Q"
+                    f"{format_number(current[0])} {format_number(current[1])} "
+                    f"{format_number(midpoint[0])} {format_number(midpoint[1])}"
+                )
+        commands.append(f"L{format_number(first[0])} {format_number(first[1])}")
+    else:
+        first_midpoint = (
+            (contour[0][0] + contour[1][0]) / 2,
+            (contour[0][1] + contour[1][1]) / 2,
+        )
+        commands = [
+            f"M{format_number(first_midpoint[0])} {format_number(first_midpoint[1])}"
+        ]
+        for index in range(1, count + 1):
+            current = contour[index % count]
+            following = contour[(index + 1) % count]
+            midpoint = (
+                (current[0] + following[0]) / 2,
+                (current[1] + following[1]) / 2,
+            )
+            commands.append(
+                "Q"
+                f"{format_number(current[0])} {format_number(current[1])} "
+                f"{format_number(midpoint[0])} {format_number(midpoint[1])}"
+            )
+
+    commands.append("Z")
+    return "".join(commands)
+
+
+def save_svg(
+    contours: list[list[Point]],
+    width: int,
+    height: int,
+    title: str,
+    output_path: Path,
+) -> None:
+    paths = "\n    ".join(path_data(contour) for contour in contours)
+    svg = f"""<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {width} {height}" fill="none" color="#111111">
+  <title>{escape(title)}</title>
+  <path fill="currentColor" fill-rule="evenodd" clip-rule="evenodd" d="
+    {paths}
+  "/>
+</svg>
+"""
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(svg, encoding="utf-8")
+
+
+def main() -> None:
+    arguments = parse_arguments()
+    if not 0 <= arguments.threshold <= 255:
+        raise SystemExit("--threshold должен быть в диапазоне 0–255")
+    if not 0 <= arguments.alpha_threshold <= 255:
+        raise SystemExit("--alpha-threshold должен быть в диапазоне 0–255")
+
+    image = Image.open(arguments.source)
+    width, height = image.size
+    mask, used_alpha = create_mask(
+        image,
+        arguments.threshold,
+        arguments.alpha_threshold,
+    )
+    png_output = arguments.output_prefix.with_suffix(".png")
+    svg_output = arguments.output_prefix.with_suffix(".svg")
+    save_clean_png(mask, png_output)
+
+    contours = [
+        contour
+        for contour in trace_contours(build_edges(mask))
+        if contour_area(contour) >= 3
+    ]
+    simplified = [
+        simplify_closed(
+            contour,
+            arguments.small_tolerance
+            if contour_span(contour) <= arguments.small_span
+            else arguments.large_tolerance,
+        )
+        for contour in contours
+    ]
+    save_svg(simplified, width, height, arguments.title, svg_output)
+
+    source_mode = "альфа-канал" if used_alpha else f"яркость < {arguments.threshold}"
+    vertex_count = sum(len(contour) for contour in simplified)
+    print(
+        f"Готово: {png_output}, {svg_output}; "
+        f"маска: {source_mode}; контуров: {len(contours)}; вершин: {vertex_count}"
+    )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except OSError as error:
+        raise SystemExit(f"Ошибка обработки изображения: {error}") from error

package/scripts/validate-deck.cjs

@@ -6,7 +6,7 @@ const deckPath = resolve(process.argv[2] ?? 'example.md')
 
 validateDeckLayouts(deckPath).then((issues) => {
   if (!issues.length) {
-    console.log(`OK: ${deckPath} — контракты layout/markdown соблюдены.`)
+    console.log(`OK: ${deckPath} — контракты макетов, Markdown и локальных вариантов соблюдены.`)
     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` — канонические паттерны слайдов, которые нужно копировать и адаптировать.
@@ -21,5 +23,17 @@ description: Используй, когда нужно создать, отре
 - Во внешней колоде с установленным пакетом используй `theme: practicum`.
 - Пиши по-русски, если пользователь не попросил другой язык.
 - Выбирай тип слайда по задаче кадра, следуя `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`. Он владеет семантическими ролями изображений, распределением ролей между референсами, карточкой сложной сцены, масштабом, физическими контактами, перспективой жёстких объектов и проверкой увеличений. Документы конкретной колоды загружай только для её персонажей, предметов, окружения и сюжета.