docs: sync readmes with picker API

HISTORY/2026-09-05-readme-sync.md

@@ -0,0 +1,20 @@
+# 2026-09-05 — синхронизация README с универсальным picker API
+
+## Что исправлено
+
+- Корневой `README.md` теперь описывает актуальные `package.json`, `build.mjs`
+  и `dist/`.
+- Добавлены команды `npm install` и `npm run build` в локальный запуск.
+- Инструкция интеграции переведена на готовые ESM/IIFE bundle.
+- Зафиксировано, что `fflate` уже встроен в bundle и отдельный vendor script
+  для интеграции не требуется.
+- В `upload/README.md` описаны `onChange(files)` и `onError(error, file)`.
+- `docs/CODE-REFERENCE.md` синхронизирован с bundle-архитектурой и актуальными
+  сигнатурами `render`.
+
+## Проверка
+
+- Все целевые файлы и ссылки на `docs/CODE-REFERENCE.md`, `HISTORY/` и оба
+  bundle существуют.
+- `git diff --check` прошёл.
+- Исходный код picker-а не изменялся.

README.md

@@ -19,6 +19,9 @@ backend.
 upload-platform/
 ├── requirements.txt
 ├── config.json               # слой 0 (рабочий конфиг этого демо)
+├── package.json               # сборка browser bundle
+├── build.mjs                  # esbuild: ESM + IIFE
+├── dist/                      # готовые bundle для встраивания
 ├── upload/                   # ← переиспользуемый модуль (копируется в любой проект)
 │   ├── README.md             # инструкция интеграции
 │   ├── config.example.json
@@ -37,10 +40,16 @@ upload-platform/
 
 ```bash
 pip install -r requirements.txt
+npm install
+npm run build
 python site/app.py
 # → http://127.0.0.1:5000/
 ```
 
+Для запуска уже собранного demo достаточно иметь зависимости Python и
+содержимое `dist/`. `npm run build` требуется после изменения исходников
+`upload/frontend/`.
+
 ## Деплой на Nubes
 
 - Точка входа: `site/app.py` (платформа запускает `python site/app.py`).
@@ -50,13 +59,16 @@ python site/app.py
 
 ## Как интегрировать picker в другой проект
 
-1. Скопировать `upload/frontend/` и один из собранных файлов `dist/` в свой проект.
+1. Скопировать `dist/file-picker.iife.js` или `dist/file-picker.esm.js` в свой проект.
-2. Подключить `file-picker.iife.js` через `<script>` и вызвать `FilePicker.initFilePicker`, либо импортировать ESM-бандл.
+2. Подключить IIFE через `<script>` и вызвать `FilePicker.initFilePicker`, либо импортировать ESM-бандл.
 3. Передать `mount`, `allowedExt`, а при необходимости `labels`, `layout`, `limits` и `onChange`.
 4. Получить выбранные leaf-файлы через `picker.getFiles()`; каждый элемент содержит
     `path`, `name`, `size` и исходный `file`.
 5. После удаления компонента вызвать `picker.destroy()`.
 
+Исходники `upload/frontend/` нужны только для разработки и пересборки bundle;
+встроенная библиотека `fflate` уже включена в готовые bundle.
+
 Разрешённые расширения демо: `.pdf`, `.doc`, `.docx`, `.txt`, `.md`.
 ZIP-файлы используются как контейнеры и раскрываются в браузере; сам ZIP не
 возвращается как leaf-файл. По умолчанию действуют ограничения: 1000 entries,
@@ -71,3 +83,5 @@ ZIP-файлы используются как контейнеры и раск
 
 Полный справочник функций, состояния, DOM-контрактов и ограничений находится в
 [`docs/CODE-REFERENCE.md`](docs/CODE-REFERENCE.md).
+
+История решений и проверок находится в [`HISTORY/`](HISTORY/).

docs/CODE-REFERENCE.md

@@ -17,7 +17,7 @@ site/app.py
           -> zip/list_zip_files.js
 ```
 
-Flask отдаёт страницу и ES-модули. Все выбранные файлы остаются в памяти браузера;
+Flask отдаёт страницу и готовый bundle. Все выбранные файлы остаются в памяти браузера;
 сервер не принимает содержимое файлов.
 
 ## Модель данных
@@ -99,8 +99,8 @@ callback задан. `finally` обязательно освобождает `bu
 
 | Функция | Вход | Выход | Назначение |
 |---|---|---|---|
-| `renderNode(node, depth)` | Узел и глубина | HTML | Рекурсивно создаёт строки дерева. Внутренняя функция. |
+| `renderNode(node, depth, cfg)` | Узел, глубина и render config | HTML | Рекурсивно создаёт строки дерева. Внутренняя функция. |
-| `render(state, elements)` | state и DOM | `void` | Перерисовывает таблицу и счётчик. |
+| `render(state, elements, cfg)` | state, DOM и render config | `void` | Перерисовывает таблицу и счётчик. |
 | `findNode(nodes, id)` | Массив узлов и id | `{node, nodes}` или `null` | Ищет узел и его родительский массив. |
 | `flattenFiles(nodes, result)` | Дерево и аккумулятор | Массив leaf-файлов | Преобразует дерево для API приложения. |
 

upload/README.md

@@ -1,14 +1,16 @@
 # Upload module
 
-Скопируйте `upload/frontend/` и подключите собранный picker:
+Для встраивания скопируйте один готовый bundle из `dist/`:
 
 - IIFE: `FilePicker.initFilePicker(config)`;
 - ESM: `import { initFilePicker } from './file-picker.esm.js'`.
 
 `config` должен содержать `mount` как DOM-элемент или CSS-селектор. Основные
-параметры: `allowedExt`, `labels`, `layout`, `limits` и `onChange`.
+параметры: `allowedExt`, `labels`, `layout`, `limits`, `onChange(files)` и
+`onError(error, file)`. `onError` вызывается для ошибок разбора ZIP; обычные
+файлы с неподдерживаемым расширением просто пропускаются.
 
-Публичный API таблицы:
+Публичный API picker-а:
 
 - `pickFiles()` и `pickFolder()` — открыть системный выбор;
 - `getFiles()` — получить leaf-файлы с `path`, `name`, `size` и `file`;
@@ -29,3 +31,14 @@ Picker поддерживает разрешённые документы, па
 
 Подробная таблица функций, входов, выходов и побочных эффектов находится в
 [`../docs/CODE-REFERENCE.md`](../docs/CODE-REFERENCE.md).
+
+## Сборка из исходников
+
+Исходники находятся в `frontend/`. В корне проекта:
+
+```bash
+npm install
+npm run build
+```
+
+Результат сборки: `dist/file-picker.esm.js` и `dist/file-picker.iife.js`.