VCOMP

VCOMP = Versatile Compression.

VCOMP is an experimental lossless compression and archive toolkit built around a Rust core. The project combines:

• single-file .vcomp containers
• multi-file archive workflows
• multiple compression modes and adaptive policies
• preview and inspection features
• password-protected containers and archives

Current repository layout:

• vcomp_rs/ - Rust core, archive runtime, codecs, security, and tests
• vcomp_rust/ - Python package and bindings for the Rust core
• vcomp_gui.py - current desktop GUI prototype
• vcomp_benchmark.py - benchmark and comparison utility
• vcomp_prototype.py - legacy Python prototype and reference path
• VCOMP_TZ.md - live technical specification and implementation status

Project positioning:

• current state: functional MVP / experimental toolkit
• main strengths: archive workflows, previews, container security, adaptive archive policies
• current gap: the project is not yet a finished 7-Zip-class general-purpose archiver
• target direction: stronger archive compression, richer policies, better UX, and later GUI redesign

License

The project is released under the root LICENSE.

Important:

• source code is available publicly
• commercial use is not permitted under the default repository license
• in strict OSI terms this is source-available, not an OSI-approved open source license

Current licensing model: PolyForm Noncommercial 1.0.0

Repository publishing notes

This directory is prepared as one monorepo.

• the repository root is initialized as git
• vcomp_rs/ is now a normal subdirectory of the main repository
• publication-related local artifacts were removed and are ignored by .gitignore

Local/private artifacts such as photos, local archives, report outputs, SQLite databases, temporary smoke directories, Python caches and Rust target/ have already been removed from this workspace and are now ignored by .gitignore.

Запуск

Запуск GUI:

cd <repo-root>
python vcomp_gui.py

Если python не найден:

py vcomp_gui.py

Optional зависимости для preview

GUI может работать и без них, но richer preview зависит от дополнительных пакетов:

• Pillow — preview изображений
• pypdfium2 — rendered first-page preview для PDF

Установка:

python -m pip install pillow pypdfium2

Что сейчас представляет собой GUI

Текущий GUI — это рабочий prototype/operator UI, а не финальный desktop UX.

Он уже умеет:

• Compress
• Decompress
• Info
• Archive Create
• Archive Append
• Archive Update
• Archive Delete
• Archive List
• Archive Extract
• Archive Test

Также доступны:

• переключение Engine (rust / python) для file-based операций
• Mode и Mode policy
• Preview cache (auto / off) для archive create/update/delete
• compact action selector с верхней кнопкой Run
• скрываемые Advanced settings
• archive browser с деревом entry
• панель details
• preview pane
• password field для encrypted .vcomp и encrypted archives
• log pane

Для archive-операций GUI использует Rust path.

Как устроен текущий интерфейс

Окно разделено на блоки:

1. Action
   • выбор операции
   • верхняя кнопка Run
   • краткая подсказка по текущему workflow
   • кнопка Advanced settings
2. Paths
   • входной файл/архив
   • выходной путь
   • global dictionary path
   • password
   • archive selection
3. Archive Inputs
   • показывается только для Archive Create / Append / Update
   • список файлов и папок для создания/обновления архива
4. Archive Browser
   • показывается только для archive-browse действий
   • дерево содержимого архива
   • details panel
   • preview panel
5. Options
   • Engine
   • Mode
   • Mode policy
   • Preview cache для архивов
   • дополнительные codec/storage настройки доступны после Advanced settings
6. Log
   • ход выполнения и ошибки
   • скрыт по умолчанию и показывается в Advanced settings

Основные сценарии

1. Сжатие одного файла

1. Action -> Compress
2. Engine -> rust
3. Input -> исходный файл
4. Output -> путь к .vcomp
5. Mode -> auto
6. Run

2. Распаковка .vcomp

1. Action -> Decompress
2. Input -> .vcomp
3. Output -> путь восстановленного файла
4. если контейнер зашифрован, заполнить Password
5. Run

3. Просмотр информации о контейнере

1. Action -> Info
2. Input -> .vcomp или archive .vcomp
3. если archive/container concealed, заполнить Password
4. Run

4. Создание архива

1. Action -> Archive Create
2. нажать Add Folder... в Archive Inputs
3. выбрать папку, которую нужно упаковать
4. GUI автоматически предложит Output вида имя_папки.vcomp, при необходимости его можно поменять
5. если нужно, можно дополнительно нажать Add Files...
6. Mode -> обычно auto или ansdict
7. Mode policy:
   • fixed — один mode для всех entry
   • type-aware — базовая policy по типу файла
   • smart — улучшенная policy для папок с кодом/текстом; использует обычный baseline mode как основу, а затем при необходимости пробует дополнительные text/code кандидаты (ansbpe, anslz), archive-local shared BPE seeds, group-aware archive-local shared dictionaries (code, config, markup, text) и solid-like grouping для небольших code/config/markup/text файлов. Для shared dictionaries теперь учитывается не только per-entry амортизация, но и реальная group-level цена всей группы; для solid grouping grouped codec выбирается измерением из безопасного набора кандидатов. На наборах из множества похожих небольших text/code файлов режим может переключаться на ansgdict или solid-like grouped codec и давать заметно меньший архив
8. при необходимости открой Advanced settings и поставь Preview cache = off, если нужен более компактный архив без preview cache
9. при необходимости заполнить Password
10. Run

5. Просмотр архива

1. Action -> Archive List
2. Input -> архив
3. Load Archive
4. смотреть дерево, details и preview

6. Выборочное извлечение

1. Action -> Archive Extract
2. Input -> архив
3. Output -> папка назначения
4. выделить entry в Archive Browser
5. Run

7. Проверка архива

1. Action -> Archive Test
2. Input -> архив
3. при необходимости заполнить Password
4. Run

Preview

Текущий preview в GUI:

• text-like files
• изображения через Pillow
• PDF:
  • cached preview из архива
  • rendered first-page preview, если доступен pypdfium2
  • fallback на text/summary preview

Encryption

GUI использует одно поле Password для:

• encrypted single-file .vcomp
• encrypted archives

Если архив использует concealed metadata/table (VARCH003), без пароля:

• Archive List не откроет file table
• Info не раскроет содержимое

Что важно понимать

Текущий GUI:

• рабочий и функциональный
• подходит для MVP и проверки возможностей
• не является финальным UX

Он пока остается:

• монолитным
• action-driven
• без context menu
• без progress/status bar
• с только базовым Advanced settings, но без полноценного Simple / Advanced UX
• без drag-and-drop

Целевой UI-roadmap описан в VCOMP_TZ.md.