kompas-kernel 0.0.1__py3-none-any.whl

kompas_kernel/features/document_session/ksapi/screenshot.py

@@ -0,0 +1,365 @@
+"""Window screenshot capture via WinAPI (`ctypes` only, no pywin32 dependency).
+
+`capture_window` is a free function taking the already-connected `app` explicitly
+(no adapter `self` state), same facade split as the other KsAPI capability modules.
+
+Три грабли живого КОМПАС, из-за которых наивный `PrintWindow` отдаёт мусор
+(все три проверены живьём, см. `docs/recipes/ksapi-link.md`):
+
+- **DPI.** Python-процесс не DPI-aware, поэтому `GetWindowRect` отдаёт ЛОГИЧЕСКИЕ
+  координаты (напр. 822x877), а КОМПАС рисует себя в ФИЗИЧЕСКИХ пикселях
+  (1440x1536 при масштабе 175%) — в битмап влезает только левый верхний угол.
+  Лечится `SetThreadDpiAwarenessContext` на время захвата: контекст потоко-локальный
+  и обратимый, процесс целиком не трогаем.
+- **Свёрнутое окно.** У свёрнутого окна прямоугольник — sentinel 158x26, снимок
+  бесполезен. Разворачиваем на время съёмки и возвращаем как было.
+- **GPU-рендер сцены.** `PrintWindow` ПО ДОЧЕРНЕМУ окну вьюпорта (`D3View`) даёт
+  чёрный кадр — у child-окна нет своей DWM-поверхности. Сцена попадает в снимок
+  только через ГЛАВНОЕ окно с `PW_RENDERFULLCONTENT`, поэтому кадр — окно целиком.
+
+Формат — JPEG (`SCREENSHOT_IMAGE_FORMAT`): BMP не принимает ни одна vision-модель
+(у pydantic-ai в `_image_format_lookup` только png/jpeg/gif/webp), а PNG на скриншоте
+окна весит втрое больше при том же читаемом дереве.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import ctypes
+import time
+from collections.abc import Generator
+from ctypes import wintypes
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from PIL import Image
+
+from kompas_kernel.features.document_session.models import (
+    SCREENSHOT_IMAGE_FORMAT,
+    ScreenshotResult,
+)
+from kompas_kernel.kompas.errors import KompasError
+from kompas_kernel.kompas.objects import constants_class
+from kompas_kernel.kompas.runtime import KsApiModules
+from kompas_kernel.observability.logger import get_logger
+from kompas_kernel.observability.taxonomy import LogDomain, LogEventType, event_name
+from kompas_kernel.utils.filesystem import atomic_write_file
+
+logger = get_logger(__name__)
+
+# Длинная сторона снимка, уходящего в модель. Окно КОМПАС на 4K-мониторе — это ~2880px
+# и мегабайты токенов на ровном месте; 1400 держит дерево построения читаемым и
+# совпадает с типичным рабочим разрешением окна на 175% масштабе.
+CAPTURE_MAX_SIDE_PX = 1400
+
+# Формат кодирования — из общего контракта (`SCREENSHOT_IMAGE_FORMAT`), качество живёт
+# здесь: q=90 на живом окне 1312x1400 дал 257 КБ против 907 КБ у PNG, при этом имена
+# элементов в дереве построения читаются без потерь (проверено глазами и моделью).
+_PILLOW_FORMAT = "JPEG"
+_JPEG_QUALITY = 90
+
+# Паузы: КОМПАС исполняет ExecuteKompasCommand асинхронно (см. `_fit_view_to_document`),
+# а восстановленное окно рисуется не мгновенно. Снимать раньше — поймать полукадр.
+_VIEW_SETTLE_SECONDS = 0.5
+_WINDOW_RESTORE_SECONDS = 1.2
+
+# Меньше — уже не окно, а sentinel свёрнутого/схлопнутого состояния: снимать нечего.
+_MIN_USABLE_WINDOW_SIDE_PX = 200
+
+_PW_RENDERFULLCONTENT = 2
+_BI_RGB = 0
+_DIB_RGB_COLORS = 0
+_BMP_INFO_HEADER_SIZE = 40
+_BITS_PER_PIXEL = 32
+_BYTES_PER_PIXEL = _BITS_PER_PIXEL // 8
+
+# `DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2` — псевдо-хэндл -4 (windef.h).
+_DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2 = ctypes.c_void_p(-4)
+
+_SW_MINIMIZE = 6
+_SW_RESTORE = 9
+# `showCmd` свёрнутого окна: SW_SHOWMINIMIZED / SW_SHOWMINNOACTIVE.
+_MINIMIZED_SHOW_COMMANDS = frozenset({2, 7})
+
+
+class _RECT(ctypes.Structure):
+    _fields_ = [
+        ("left", wintypes.LONG),
+        ("top", wintypes.LONG),
+        ("right", wintypes.LONG),
+        ("bottom", wintypes.LONG),
+    ]
+
+
+class _BITMAPINFOHEADER(ctypes.Structure):
+    _fields_ = [
+        ("biSize", wintypes.DWORD),
+        ("biWidth", wintypes.LONG),
+        ("biHeight", wintypes.LONG),
+        ("biPlanes", wintypes.WORD),
+        ("biBitCount", wintypes.WORD),
+        ("biCompression", wintypes.DWORD),
+        ("biSizeImage", wintypes.DWORD),
+        ("biXPelsPerMeter", wintypes.LONG),
+        ("biYPelsPerMeter", wintypes.LONG),
+        ("biClrUsed", wintypes.DWORD),
+        ("biClrImportant", wintypes.DWORD),
+    ]
+
+
+class _BITMAPINFO(ctypes.Structure):
+    _fields_ = [
+        ("bmiHeader", _BITMAPINFOHEADER),
+        ("bmiColors", wintypes.DWORD * 1),
+    ]
+
+
+class _WINDOWPLACEMENT(ctypes.Structure):
+    _fields_ = [
+        ("length", wintypes.UINT),
+        ("flags", wintypes.UINT),
+        ("showCmd", wintypes.UINT),
+        ("ptMinPosition", wintypes.POINT),
+        ("ptMaxPosition", wintypes.POINT),
+        ("rcNormalPosition", _RECT),
+    ]
+
+
+@dataclass(frozen=True)
+class _WinApi:
+    user32: Any
+    gdi32: Any
+
+
+@dataclass(frozen=True)
+class _WindowSize:
+    width: int
+    height: int
+
+
+@dataclass
+class _CaptureResources:
+    api: _WinApi
+    hwnd: int
+    window_dc: int = 0
+    memory_dc: int = 0
+    bitmap: int = 0
+    old_object: int = 0
+
+    @classmethod
+    def create(cls, *, api: _WinApi, hwnd: int, size: _WindowSize) -> _CaptureResources:
+        resources = cls(api=api, hwnd=hwnd)
+        try:
+            resources.window_dc = int(api.user32.GetWindowDC(wintypes.HWND(hwnd)))
+            if not resources.window_dc:
+                raise _winapi_error("GetWindowDC")
+            resources.memory_dc = int(api.gdi32.CreateCompatibleDC(resources.window_dc))
+            if not resources.memory_dc:
+                raise _winapi_error("CreateCompatibleDC")
+            resources.bitmap = int(api.gdi32.CreateCompatibleBitmap(resources.window_dc, size.width, size.height))
+            if not resources.bitmap:
+                raise _winapi_error("CreateCompatibleBitmap")
+            resources.old_object = int(api.gdi32.SelectObject(resources.memory_dc, resources.bitmap))
+            if not resources.old_object:
+                raise _winapi_error("SelectObject")
+            return resources
+        except Exception:
+            resources.close()
+            raise
+
+    def close(self) -> None:
+        if self.old_object:
+            self.api.gdi32.SelectObject(self.memory_dc, self.old_object)
+            self.old_object = 0
+        if self.bitmap:
+            self.api.gdi32.DeleteObject(self.bitmap)
+            self.bitmap = 0
+        if self.memory_dc:
+            self.api.gdi32.DeleteDC(self.memory_dc)
+            self.memory_dc = 0
+        if self.window_dc:
+            self.api.user32.ReleaseDC(wintypes.HWND(self.hwnd), self.window_dc)
+            self.window_dc = 0
+
+
+def _winapi_error(operation: str) -> KompasError:
+    code = ctypes.get_last_error()
+    return KompasError(f"screenshot: {operation} failed (WinError {code})")
+
+
+def _load_winapi() -> _WinApi:
+    return _WinApi(
+        user32=ctypes.WinDLL("user32", use_last_error=True),
+        gdi32=ctypes.WinDLL("gdi32", use_last_error=True),
+    )
+
+
+@contextlib.contextmanager
+def _thread_dpi_awareness(api: _WinApi) -> Generator[None, None, None]:
+    """Сделать ТЕКУЩИЙ ПОТОК per-monitor-v2 DPI-aware на время захвата.
+
+    Без этого `GetWindowRect` врёт в логических координатах и снимок обрезается до
+    `1/scale` по каждой оси (при 175% — до 57%). Контекст потоко-локальный, поэтому
+    остальной процесс (и другие KsAPI-вызовы) поведение не меняют.
+    """
+    set_context = getattr(api.user32, "SetThreadDpiAwarenessContext", None)
+    if set_context is None:
+        raise KompasError("screenshot: SetThreadDpiAwarenessContext unavailable (needs Windows 10 1607+)")
+    set_context.restype = ctypes.c_void_p
+    set_context.argtypes = [ctypes.c_void_p]
+    previous = set_context(_DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2)
+    if not previous:
+        raise _winapi_error("SetThreadDpiAwarenessContext")
+    try:
+        yield
+    finally:
+        set_context(ctypes.c_void_p(previous))
+
+
+def _show_command(api: _WinApi, hwnd: int) -> int:
+    placement = _WINDOWPLACEMENT()
+    placement.length = ctypes.sizeof(_WINDOWPLACEMENT)
+    if not api.user32.GetWindowPlacement(wintypes.HWND(hwnd), ctypes.byref(placement)):
+        raise _winapi_error("GetWindowPlacement")
+    return int(placement.showCmd)
+
+
+@contextlib.contextmanager
+def _window_unminimized(api: _WinApi, hwnd: int) -> Generator[None, None, None]:
+    """Развернуть свёрнутое окно КОМПАС на время съёмки и вернуть его как было.
+
+    Разворачивается ровно свёрнутое окно: размер и позицию нормального окна не трогаем —
+    пользователь мог поставить его так намеренно. Это смена состояния ОКНА, не документа.
+    """
+    if _show_command(api, hwnd) not in _MINIMIZED_SHOW_COMMANDS:
+        yield
+        return
+    logger.info(event_name(LogDomain.BRIDGE, "ksapi_screenshot_window_restore", LogEventType.STARTED), hwnd=hwnd)
+    api.user32.ShowWindow(wintypes.HWND(hwnd), _SW_RESTORE)
+    time.sleep(_WINDOW_RESTORE_SECONDS)
+    try:
+        yield
+    finally:
+        api.user32.ShowWindow(wintypes.HWND(hwnd), _SW_MINIMIZE)
+
+
+def _fit_view_to_document(app: Any, constants: Any) -> bool:
+    """Вписать документ в окно (`ksCMZoomEntireDocument`) — иначе в кадр попадает кусок детали.
+
+    `ExecuteKompasCommand` требует `asyncExecution=True`: синхронный вызов с worker-потока
+    не отрабатывает (то же ограничение, что у `ksCMZoomSelected` в `adapter.show_component`).
+    Команда уходит в очередь UI-потока КОМПАС, поэтому дальше — пауза на перерисовку.
+    """
+    zoomed = bool(app.ExecuteKompasCommand(int(constants.ksCMZoomEntireDocument), True))
+    time.sleep(_VIEW_SETTLE_SECONDS)
+    return zoomed
+
+
+def _window_size(api: _WinApi, hwnd: int) -> _WindowSize:
+    rect = _RECT()
+    if not api.user32.GetWindowRect(wintypes.HWND(hwnd), ctypes.byref(rect)):
+        raise _winapi_error("GetWindowRect")
+    width = int(rect.right - rect.left)
+    height = int(rect.bottom - rect.top)
+    if width <= 0 or height <= 0:
+        raise KompasError("screenshot: KOMPAS window has zero size")
+    if width < _MIN_USABLE_WINDOW_SIDE_PX or height < _MIN_USABLE_WINDOW_SIDE_PX:
+        raise KompasError(
+            f"screenshot: KOMPAS window is too small to capture ({width}x{height}px) — "
+            "разверните окно КОМПАС и повторите"
+        )
+    return _WindowSize(width=width, height=height)
+
+
+def _render_window(api: _WinApi, *, hwnd: int, memory_dc: int) -> None:
+    if not api.user32.PrintWindow(wintypes.HWND(hwnd), memory_dc, _PW_RENDERFULLCONTENT):
+        raise _winapi_error("PrintWindow")
+
+
+def _bitmap_info(size: _WindowSize, image_size: int) -> _BITMAPINFO:
+    bitmap_info = _BITMAPINFO()
+    bitmap_info.bmiHeader.biSize = _BMP_INFO_HEADER_SIZE
+    bitmap_info.bmiHeader.biWidth = size.width
+    bitmap_info.bmiHeader.biHeight = -size.height
+    bitmap_info.bmiHeader.biPlanes = 1
+    bitmap_info.bmiHeader.biBitCount = _BITS_PER_PIXEL
+    bitmap_info.bmiHeader.biCompression = _BI_RGB
+    bitmap_info.bmiHeader.biSizeImage = image_size
+    return bitmap_info
+
+
+def _read_bitmap_pixels(api: _WinApi, *, memory_dc: int, bitmap: int, size: _WindowSize) -> bytes:
+    image_size = size.width * size.height * _BYTES_PER_PIXEL
+    pixels = ctypes.create_string_buffer(image_size)
+    bitmap_info = _bitmap_info(size, image_size)
+    scan_lines = api.gdi32.GetDIBits(
+        memory_dc,
+        bitmap,
+        0,
+        size.height,
+        pixels,
+        ctypes.byref(bitmap_info),
+        _DIB_RGB_COLORS,
+    )
+    if int(scan_lines) != size.height:
+        raise _winapi_error("GetDIBits")
+    return pixels.raw
+
+
+def _grab_window_pixels(api: _WinApi, *, hwnd: int, size: _WindowSize) -> bytes:
+    resources = _CaptureResources.create(api=api, hwnd=hwnd, size=size)
+    try:
+        _render_window(api, hwnd=hwnd, memory_dc=resources.memory_dc)
+        return _read_bitmap_pixels(api, memory_dc=resources.memory_dc, bitmap=resources.bitmap, size=size)
+    finally:
+        resources.close()
+
+
+def to_downscaled_rgb(pixels_bgra: bytes, *, size: _WindowSize, max_side: int) -> Image.Image:
+    """Сырые BGRA-пиксели окна → RGB-картинка, вписанная в квадрат `max_side` (только уменьшение).
+
+    Альфу отбрасываем намеренно: `PrintWindow` заполняет её нулями, и снимок с такой
+    альфой уезжает в модель полностью прозрачным (виден как пустой кадр).
+    """
+    # Отрицательный `biHeight` в `_bitmap_info` уже дал top-down порядок строк — переворот не нужен.
+    image = Image.frombuffer("RGBA", (size.width, size.height), pixels_bgra, "raw", "BGRA", 0, 1).convert("RGB")
+    longest_side = max(image.width, image.height)
+    if longest_side <= max_side:
+        return image
+    scale = max_side / longest_side
+    return image.resize((round(image.width * scale), round(image.height * scale)), Image.Resampling.LANCZOS)
+
+
+def write_image_atomic(image: Image.Image, out_path: Path) -> None:
+    """Снимок на диск через temp+rename (GPC5): читатель никогда не видит полуфайл."""
+
+    def write_jpeg(temporary: Path) -> None:
+        with temporary.open("wb") as stream:
+            image.save(stream, format=_PILLOW_FORMAT, quality=_JPEG_QUALITY, optimize=True)
+
+    atomic_write_file(out_path, write_jpeg, create_parents=True)
+
+
+def capture_window(app: Any, modules: KsApiModules, out_path: Path) -> ScreenshotResult:
+    """Снять окно КОМПАС целиком: вписать вид, снять DPI-aware, уменьшить до `CAPTURE_MAX_SIDE_PX`."""
+    hwnd = int(app.GetMainWindowHandle())
+    if hwnd == 0:
+        raise KompasError("screenshot: KOMPAS has no main window handle")
+
+    api = _load_winapi()
+    constants = constants_class(modules)
+    with _thread_dpi_awareness(api), _window_unminimized(api, hwnd):
+        zoomed = _fit_view_to_document(app, constants)
+        size = _window_size(api, hwnd)
+        pixels = _grab_window_pixels(api, hwnd=hwnd, size=size)
+
+    image = to_downscaled_rgb(pixels, size=size, max_side=CAPTURE_MAX_SIDE_PX)
+    write_image_atomic(image, out_path)
+    logger.info(
+        event_name(LogDomain.BRIDGE, "ksapi_screenshot", LogEventType.COMPLETED),
+        captured_px=f"{size.width}x{size.height}",
+        saved_px=f"{image.width}x{image.height}",
+        zoomed=zoomed,
+    )
+    return ScreenshotResult(path=out_path, image_format=SCREENSHOT_IMAGE_FORMAT, width=image.width, height=image.height)

kompas_kernel/features/document_session/ksapi/snapshot.py

@@ -0,0 +1,181 @@
+"""Checkpoint/restore: копия файла документа как снимок и откат документа к ней.
+
+Free functions taking explicit `modules`/`app` dependencies (no adapter `self`
+state), same facade split as the other KsAPI capability modules.
+
+Два факта KsAPI, на которых всё держится (проверено по `ksapi.py`):
+
+- **Безымянный документ сохраняется сам.** `IKompasDocument.SaveAs(fileName)` даёт
+  свежесозданной детали (`IDocuments.Add`) путь — до этого `GetFullPath()` пуст, и
+  снимать копию было не с чего. Путь берём НЕ «где-нибудь во временном каталоге», а в
+  рабочей области сессии агента (`untitled_document_dir`): там же лежат todo, спул и
+  сами чекпоинты, пользователь видит файл рядом с остальным.
+- **Откат = закрыть → перезаписать → открыть.** `IDocuments.GetItemByFilePath` находит
+  открытый документ по пути, `Close(constants.kdDoNotSaveChanges)` закрывает его БЕЗ
+  сохранения (иначе КОМПАС держит файл и перезапись упадёт), после подмены файла
+  `IDocuments.Open(path, True, False)` открывает его заново и `SetActive()` возвращает
+  фокус. Прежняя версия просто открывала файл снимка соседним документом — исходный
+  документ оставался изменённым, а «откат» был фикцией.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from kompas_kernel.features.document_session.models import Checkpoint
+from kompas_kernel.kompas.errors import KompasError
+from kompas_kernel.kompas.objects import as_document_3d, constants_class, doc_path
+from kompas_kernel.kompas.runtime import KsApiModules
+from kompas_kernel.utils.filesystem import atomic_write_file
+
+# Расширение файла для безымянного 3D-документа, сохраняемого в рабочую область.
+# Деталь и сборка различаются (`.m3d`/`.a3d`), поэтому выбирается по типу документа
+# сессии, а не хардкодится одним значением (GPC1 — константа в одном месте).
+_PART_SUFFIX = ".m3d"
+_ASSEMBLY_SUFFIX = ".a3d"
+
+# Имя файла для безымянного документа, у которого и `GetName()` пуст.
+_FALLBACK_DOCUMENT_STEM = "untitled"
+
+# Всё, кроме букв/цифр/пробела/`-`/`_`/`.`, вырезается из имени документа КОМПАС перед
+# использованием в имени файла: `GetName()` возвращает произвольный пользовательский
+# текст («Деталь без имени 1»), а он попадает в filesystem path.
+_UNSAFE_NAME_CHARS = re.compile(r"[^\w\-. ]", flags=re.UNICODE)
+
+# Потолок длины имени файла (без расширения) — длинное имя документа не должно
+# упереться в лимит пути Windows.
+_MAX_STEM_LENGTH = 60
+
+
+@dataclass(frozen=True)
+class SavedSnapshot:
+    """Итог `save_snapshot` для сервиса: куда лёг снимок и что стало с документом.
+
+    `document_path` — путь документа ПОСЛЕ возможного `SaveAs` (для безымянного он
+    только что появился); `saved_untitled_document` — честный признак, что файл
+    документа создан нами в рабочей области, а не был у пользователя изначально.
+    """
+
+    checkpoint_path: Path
+    document_path: str
+    saved_untitled_document: bool
+
+
+def _document_suffix(modules: KsApiModules, doc: Any) -> str:
+    """`.m3d` для детали, `.a3d` для сборки — по типу документа сессии, не по имени."""
+    constants = constants_class(modules)
+    return _ASSEMBLY_SUFFIX if int(doc.GetDocumentType()) == int(constants.ksDocumentAssembly) else _PART_SUFFIX
+
+
+def _safe_stem(raw_name: Any) -> str:
+    """Имя документа КОМПАС → безопасная основа имени файла (непустая, ограниченной длины)."""
+    text = str(raw_name).strip() if raw_name is not None else ""
+    cleaned = _UNSAFE_NAME_CHARS.sub("", text).strip().strip(".")
+    return cleaned[:_MAX_STEM_LENGTH] if cleaned else _FALLBACK_DOCUMENT_STEM
+
+
+def _unique_path(directory: Path, stem: str, suffix: str) -> Path:
+    """Свободный путь `directory/stem[-N]suffix` — не затираем ранее сохранённый документ."""
+    candidate = directory / f"{stem}{suffix}"
+    index = 2
+    while candidate.exists():
+        candidate = directory / f"{stem}-{index}{suffix}"
+        index += 1
+    return candidate
+
+
+def _save_untitled_document(modules: KsApiModules, doc: Any, untitled_document_dir: Path) -> str:
+    """Дать безымянному документу путь в рабочей области сессии через `SaveAs`.
+
+    Прежнее поведение — `KompasError` «save it once» — делало чекпоинт недоступным ровно
+    в самом частом сценарии («построй деталь с нуля»): документ создан агентом и имени
+    у него нет. Каталог для таких документов приходит СНАРУЖИ (рабочая область сессии),
+    этот модуль сам ничего про рабочую область не знает.
+    """
+    untitled_document_dir.mkdir(parents=True, exist_ok=True)
+    target = _unique_path(untitled_document_dir, _safe_stem(doc.GetName()), _document_suffix(modules, doc))
+    if not doc.SaveAs(str(target)):
+        raise KompasError(f"checkpoint: SaveAs безымянного документа вернул false: {target}")
+    saved_path = doc_path(doc)
+    if saved_path is None:
+        raise KompasError(f"checkpoint: после SaveAs у документа всё ещё нет пути: {target}")
+    return saved_path
+
+
+def _copy_atomically(source: Path, target: Path) -> None:
+    """Скопировать файл через общий атомарный file-write примитив (GPC5)."""
+
+    def copy_file(temporary: Path) -> None:
+        shutil.copy2(source, temporary)
+
+    atomic_write_file(target, copy_file, create_parents=True)
+
+
+def save_snapshot(
+    modules: KsApiModules,
+    app: Any,
+    *,
+    checkpoint_dir: Path,
+    checkpoint_id: str,
+    untitled_document_dir: Path,
+) -> SavedSnapshot:
+    """Сохранить активный 3D-документ и положить его копию в `checkpoint_dir`.
+
+    Безымянный документ сперва получает путь в `untitled_document_dir` (см.
+    `_save_untitled_document`) — только «нет активного 3D-документа» остаётся отказом.
+    """
+    doc = as_document_3d(modules, app.GetActiveDocument())
+    if doc is None:
+        raise KompasError("checkpoint: нет активного 3D-документа — открой или создай деталь/сборку")
+    source = doc_path(doc)
+    saved_untitled_document = source is None
+    if source is None:
+        source = _save_untitled_document(modules, doc, untitled_document_dir)
+    elif not doc.Save():
+        raise KompasError(f"checkpoint: Save() активного документа вернул false: {source}")
+    target = checkpoint_dir / f"{checkpoint_id}{Path(source).suffix or _PART_SUFFIX}"
+    _copy_atomically(Path(source), target)
+    return SavedSnapshot(
+        checkpoint_path=target,
+        document_path=source,
+        saved_untitled_document=saved_untitled_document,
+    )
+
+
+def _close_if_open(modules: KsApiModules, docs: Any, document_path: str) -> None:
+    """Закрыть документ БЕЗ сохранения, если он сейчас открыт в КОМПАС.
+
+    Пока файл открыт, КОМПАС держит его — перезапись копией снимка либо упадёт, либо
+    останется невидимой (в памяти по-прежнему изменённая модель). Документ может быть и
+    не открыт (пользователь закрыл его сам) — это не ошибка, откат просто подменит файл.
+    """
+    open_doc = docs.GetItemByFilePath(document_path)
+    if open_doc is None:
+        return
+    constants = constants_class(modules)
+    if not open_doc.Close(int(constants.kdDoNotSaveChanges)):
+        raise KompasError(f"restore: КОМПАС не закрыл документ перед откатом: {document_path}")
+
+
+def restore_snapshot(modules: KsApiModules, app: Any, checkpoint: Checkpoint) -> None:
+    """Откатить документ к снимку: закрыть без сохранения → подменить файл → открыть.
+
+    Именно ИСХОДНЫЙ документ (`checkpoint.document_path`) возвращается к состоянию
+    снимка и становится активным; файл снимка при этом остаётся нетронутым и годен для
+    повторного отката.
+    """
+    if not checkpoint.path.exists():
+        raise KompasError(f"restore: файл чекпойнта не найден: {checkpoint.path}")
+    docs = app.GetDocuments()
+    if docs is None:
+        raise KompasError("restore: КОМПАС не отдал коллекцию Documents")
+    _close_if_open(modules, docs, checkpoint.document_path)
+    _copy_atomically(checkpoint.path, Path(checkpoint.document_path))
+    reopened = docs.Open(checkpoint.document_path, True, False)
+    if reopened is None:
+        raise KompasError(f"restore: КОМПАС не смог открыть откаченный документ: {checkpoint.document_path}")
+    reopened.SetActive()