Initial deployable Flask application

upload/frontend/index.js

@@ -0,0 +1,193 @@
+import { addFiles, onFilesChange } from './table/on_files_change.js';
+import { onFolderChange } from './table/on_folder_change.js';
+import { findNode, flattenFiles, render } from './table/render.js';
+import { esc } from './table/esc.js';
+
+const DEFAULTS = {
+  allowedExt: [],
+  labels: {
+    pickFiles: 'Выбрать файлы',
+    pickFolder: 'Выбрать папку',
+    clear: 'Очистить',
+    empty: 'Нет выбранных файлов',
+    statusReady: 'готов',
+    remove: 'Удалить',
+    columns: { path: 'Путь', size: 'Размер', status: 'Статус' },
+    count: (count, bytes) => `${count} файлов · ${bytes} B`,
+  },
+  layout: { columns: ['path', 'size', 'status'], controls: ['files', 'folder', 'clear'] },
+  limits: {
+    maxEntries: 1000,
+    maxTotalBytes: 100 * 1024 * 1024,
+    maxEntryBytes: 50 * 1024 * 1024,
+    maxDepth: 20,
+  },
+};
+
+function resolveMount(mount) {
+  const element = typeof mount === 'string' ? document.querySelector(mount) : mount;
+  if (!element) throw new Error('File picker mount element не найден');
+  return element;
+}
+
+function normalizeConfig(config) {
+  return {
+    ...config,
+    allowedExt: config.allowedExt || DEFAULTS.allowedExt,
+    labels: {
+      ...DEFAULTS.labels,
+      ...(config.labels || {}),
+      columns: { ...DEFAULTS.labels.columns, ...(config.labels?.columns || {}) },
+    },
+    layout: { ...DEFAULTS.layout, ...(config.layout || {}) },
+    limits: { ...DEFAULTS.limits, ...(config.limits || {}) },
+  };
+}
+
+function injectStyles() {
+  if (document.querySelector('style[data-file-picker]')) return;
+  const style = document.createElement('style');
+  style.dataset.filePicker = '';
+  style.textContent = `
+.file-picker { color: #17211b; font-family: Georgia, 'Times New Roman', serif; }
+.file-picker .fp-toolbar { display: flex; flex-wrap: wrap; gap: 10px; margin: 16px 0; }
+.file-picker .fp-toolbar button { border: 0; border-radius: 4px; padding: 12px 17px; color: #f7faf4; background: #1f5a3b; font: 700 13px sans-serif; cursor: pointer; }
+.file-picker .fp-toolbar button.secondary { color: #1f5a3b; background: #cbdcc9; }
+.file-picker .fp-toolbar button.quiet { color: #5d6a61; background: transparent; }
+.file-picker .fp-table-wrap { overflow-x: auto; border-top: 1px solid #b9c7ba; }
+.file-picker .fp-table { width: 100%; border-collapse: collapse; font: 14px/1.4 sans-serif; }
+.file-picker .fp-table th, .file-picker .fp-table td { padding: 14px 10px; border-bottom: 1px solid #cbd5cc; text-align: left; }
+.file-picker .fp-table th { color: #56745f; font-size: 11px; text-transform: uppercase; letter-spacing: 1px; }
+.file-picker .fp-status, .file-picker .fp-count { color: #5d6a61; font: 13px sans-serif; }
+.file-picker .fp-count { min-height: 22px; }
+.file-picker .tree-name { display: inline-flex; align-items: center; gap: 8px; min-width: 240px; padding-top: 0; padding-bottom: 0; border: 0; background: transparent; color: #17211b; font: inherit; text-align: left; }
+.file-picker .tree-group { padding-left: 0; cursor: pointer; }
+.file-picker .tree-chevron { display: inline-block; width: 12px; color: #78917d; font-size: 10px; }
+.file-picker .remove-btn { padding: 2px 7px; color: #8c5148; background: transparent; font: 20px/1 sans-serif; }
+.file-picker .tree-row td:first-child { white-space: nowrap; }
+@media (max-width: 600px) { .file-picker .fp-toolbar button { flex: 1 1 42%; } }
+`;
+  document.head.append(style);
+}
+
+function buildMarkup(root, cfg) {
+  const controls = cfg.layout.controls || [];
+  const control = (name, id, label, className = '') => controls.includes(name)
+    ? `<button id="${id}" type="button" class="${className}">${esc(label)}</button>` : '';
+  const columns = cfg.layout.columns?.length ? cfg.layout.columns : Object.keys(cfg.labels.columns);
+  const headings = columns.map((column) => `<th>${esc(cfg.labels.columns[column] || column)}</th>`).join('');
+  root.innerHTML = `
+    <div class="file-picker${cfg.layout.theme ? ` ${esc(cfg.layout.theme)}` : ''}">
+      <div class="fp-toolbar" aria-label="${esc(cfg.labels.pickFiles)}">
+        <input class="fp-file-input" type="file" accept="${esc([...cfg.allowedExt, '.zip'].join(','))}" multiple hidden>
+        <input class="fp-folder-input" type="file" accept="${esc([...cfg.allowedExt, '.zip'].join(','))}" webkitdirectory directory multiple hidden>
+        ${control('files', 'fp-files-btn', cfg.labels.pickFiles)}
+        ${control('folder', 'fp-folder-btn', cfg.labels.pickFolder, 'secondary')}
+        ${control('clear', 'fp-clear-btn', cfg.labels.clear, 'quiet')}
+      </div>
+      <p class="fp-status" role="status"></p>
+      <div class="fp-table-wrap"><table class="fp-table"><thead><tr>${headings}<th></th></tr></thead><tbody class="fp-table-body"></tbody></table></div>
+      <p class="fp-count"></p>
+    </div>`;
+}
+
+function notify(cfg, state) {
+  if (typeof cfg.onChange === 'function') cfg.onChange([...flattenFiles(state.nodes)]);
+}
+
+function removeMetadata(state, node) {
+  if (node.kind === 'file') {
+    state.fileKeys.delete(`${node.path}\u0000${node.file.size}`);
+    return;
+  }
+  node.children.forEach((child) => removeMetadata(state, child));
+}
+
+function removeNode(state, id) {
+  const found = findNode(state.nodes, id);
+  if (!found) return false;
+  removeMetadata(state, found.node);
+  found.nodes.splice(found.nodes.indexOf(found.node), 1);
+  return true;
+}
+
+export function initFilePicker(config) {
+  const cfg = normalizeConfig(config);
+  const mount = resolveMount(cfg.mount);
+  injectStyles();
+  buildMarkup(mount, cfg);
+  const root = mount.firstElementChild;
+  const elements = {
+    fileInputEl: root.querySelector('.fp-file-input'),
+    folderInputEl: root.querySelector('.fp-folder-input'),
+    statusEl: root.querySelector('.fp-status'),
+    tableBodyEl: root.querySelector('.fp-table-body'),
+    countEl: root.querySelector('.fp-count'),
+  };
+  const state = { nodes: [], fileKeys: new Set(), busy: false };
+  const listeners = [];
+  const listen = (target, event, handler) => {
+    target.addEventListener(event, handler);
+    listeners.push(() => target.removeEventListener(event, handler));
+  };
+  const redraw = () => render(state, elements, cfg);
+  const filesChange = onFilesChange(state, cfg, elements);
+  const folderChange = onFolderChange(state, cfg, elements);
+  listen(elements.fileInputEl, 'change', async () => { await filesChange(); notify(cfg, state); });
+  listen(elements.folderInputEl, 'change', async () => { await folderChange(); notify(cfg, state); });
+  listen(elements.tableBodyEl, 'click', (event) => {
+    const toggle = event.target.closest('[data-toggle]');
+    if (toggle) {
+      const found = findNode(state.nodes, toggle.dataset.toggle);
+      if (found) found.node.expanded = !found.node.expanded;
+      redraw();
+      return;
+    }
+    const remove = event.target.closest('[data-remove]');
+    if (remove) {
+      if (removeNode(state, remove.dataset.remove)) {
+        redraw();
+        notify(cfg, state);
+      }
+    }
+  });
+  if (root.querySelector('#fp-files-btn')) listen(root.querySelector('#fp-files-btn'), 'click', () => elements.fileInputEl.click());
+  if (root.querySelector('#fp-folder-btn')) listen(root.querySelector('#fp-folder-btn'), 'click', () => elements.folderInputEl.click());
+  if (root.querySelector('#fp-clear-btn')) listen(root.querySelector('#fp-clear-btn'), 'click', () => {
+    state.nodes = [];
+    state.fileKeys.clear();
+    redraw();
+    notify(cfg, state);
+  });
+  redraw();
+  return {
+    pickFiles: () => elements.fileInputEl.click(),
+    pickFolder: () => elements.folderInputEl.click(),
+    addFiles: async (files) => { await addFiles(state, cfg, files, elements); notify(cfg, state); },
+    getFiles: () => [...flattenFiles(state.nodes)],
+    remove: (id) => {
+      if (removeNode(state, id)) {
+        redraw();
+        notify(cfg, state);
+      }
+    },
+    clear: () => {
+      state.nodes = [];
+      state.fileKeys.clear();
+      redraw();
+      notify(cfg, state);
+    },
+    render: redraw,
+    destroy: () => {
+      listeners.forEach((removeListener) => removeListener());
+      state.nodes = [];
+      state.fileKeys.clear();
+      mount.replaceChildren();
+    },
+  };
+}
+
+export { putToVm } from './upload/put_to_vm.js';
+export { uploadViaVM } from './upload/upload_via_vm.js';
+export { DEFAULTS };
+

upload/frontend/table/add_file_with_dedup.js

@@ -0,0 +1,54 @@
+/**
+ * Добавляет узел файла или группы в состояние picker с рекурсивной дедупликацией.
+ *
+ * @param {{nodes: Array, fileKeys: Set<string>}} state Внутреннее состояние таблицы.
+ * @param {{kind: string, path: string, file?: File, children?: Array}} fileNode
+ *   Корневой узел файла, папки или ZIP-архива.
+ * @returns {boolean} True, если в состояние добавлен хотя бы один узел.
+ *
+ * Ключ дедупликации состоит из полного пути и размера файла. Это позволяет
+ * повторно выбрать файл после удаления и одновременно не скрывает файл с тем
+ * же путём, но другим размером.
+ */
+export function addFileWithDedup(state, fileNode) {
+  // Удаляет дубли и пустые группы снизу вверх, сохраняя исходные File objects.
+  const accept = (node) => {
+    if (node.kind === 'file') {
+      // NUL-разделитель исключает неоднозначность при склейке пути и размера.
+      const key = `${node.path}\u0000${node.file.size}`;
+      if (state.fileKeys.has(key)) return null;
+      state.fileKeys.add(key);
+      return node;
+    }
+    // Группа нужна только пока после фильтрации в ней остался хотя бы один leaf.
+    node.children = node.children.map(accept).filter(Boolean);
+    return node.children.length ? node : null;
+  };
+  const accepted = accept(fileNode);
+  // Пустой ZIP/каталог не должен появляться в таблице как пустая строка.
+  if (!accepted || (accepted.kind !== 'file' && !accepted.children.length)) return false;
+  if (accepted.kind !== 'file') {
+    const existing = state.nodes.find((node) => node.kind !== 'file' && node.path === accepted.path);
+    if (existing) {
+      mergeChildren(existing, accepted);
+      return true;
+    }
+  }
+  state.nodes.push(accepted);
+  return true;
+}
+
+function mergeChildren(target, incoming) {
+  incoming.children.forEach((child) => {
+    if (child.kind === 'file') {
+      const duplicate = target.children.some((existing) => existing.kind === 'file'
+        && existing.path === child.path && existing.file.size === child.file.size);
+      if (!duplicate) target.children.push(child);
+      return;
+    }
+    const existing = target.children.find((candidate) => candidate.kind !== 'file'
+      && candidate.path === child.path);
+    if (existing) mergeChildren(existing, child);
+    else target.children.push(child);
+  });
+}

upload/frontend/table/esc.js

@@ -0,0 +1,18 @@
+/**
+ * Экранирует текст перед вставкой в HTML-шаблон, собираемый через innerHTML.
+ *
+ * @param {*} value Имя файла, путь или сообщение статуса.
+ * @returns {string} Строка с заменёнными HTML-значимыми символами.
+ *
+ * Экранируются и кавычки, потому что значение может попасть не только в текст
+ * кнопки, но и в HTML-атрибут вроде data-path или aria-label.
+ */
+export function esc(value) {
+  return String(value).replace(/[&<>"']/g, (character) => ({
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+  }[character]));
+}

upload/frontend/table/fs.js

@@ -0,0 +1,11 @@
+/**
+ * Преобразует размер файла из байтов в короткую строку для таблицы.
+ *
+ * @param {number} bytes Размер в байтах.
+ * @returns {string} Значение в B, KB или MB с одним знаком после запятой.
+ */
+export function fs(bytes) {
+  return bytes < 1024 ? `${bytes} B`
+    : bytes < 1048576 ? `${(bytes / 1024).toFixed(1)} KB`
+    : `${(bytes / 1048576).toFixed(1)} MB`;
+}

upload/frontend/table/on_files_change.js

@@ -0,0 +1,72 @@
+import { listZipFiles } from '../zip/list_zip_files.js';
+import { addFileWithDedup } from './add_file_with_dedup.js';
+import { render } from './render.js';
+
+/**
+ * Обрабатывает список файлов из обычного file input.
+ *
+ * @param {{fileKeys: Set<string>, nodes: Array, busy: boolean}} state Состояние picker.
+ * @param {{allowedExt: string[]}} cfg Конфигурация разрешённых расширений.
+ * @param {FileList|File[]} files Выбранные browser File objects.
+ * @param {{tableBodyEl: HTMLElement, countEl: HTMLElement}} elements DOM-элементы вывода.
+ * @returns {Promise<void>} Завершается после разбора всех ZIP и перерисовки таблицы.
+ *
+ * Обычные документы добавляются сразу. ZIP читаются асинхронно в браузере;
+ * ошибка одного архива не отменяет обработку остальных выбранных файлов.
+ */
+export async function addFiles(state, cfg, files, elements) {
+  for (const file of Array.from(files)) {
+    if (!file.name.toLowerCase().endsWith('.zip')) {
+      // Фильтр повторяет accept в HTML, потому что accept не является защитой API.
+      if (!cfg.allowedExt.some((extension) => file.name.toLowerCase().endsWith(extension.toLowerCase()))) {
+        continue;
+      }
+      // Обычный файл получает имя как путь: у file input нет относительного пути.
+      addFileWithDedup(state, {
+        id: crypto.randomUUID(), kind: 'file', name: file.name, path: file.name,
+        file, children: [], expanded: true,
+      });
+      continue;
+    }
+    try {
+      // listZipFiles возвращает дерево только с разрешёнными leaf-файлами.
+      const zipTree = await listZipFiles(file, cfg.allowedExt, cfg.limits);
+      if (zipTree) addFileWithDedup(state, zipTree);
+    } catch (error) {
+      // Битый или небезопасный ZIP пропускается, чтобы не блокировать picker.
+      if (typeof cfg.onError === 'function') {
+        cfg.onError(error, file);
+      } else if (elements.statusEl) {
+        elements.statusEl.textContent = `Ошибка чтения архива ${file.name}: ${error.message}`;
+      }
+      continue;
+    }
+  }
+  // Единая перерисовка после всей пачки предотвращает промежуточные состояния UI.
+  render(state, elements, cfg);
+}
+
+/**
+ * Создаёт обработчик change для обычного выбора файлов.
+ *
+ * @param {object} state Состояние picker, включая флаг busy.
+ * @param {object} cfg Конфигурация picker.
+ * @param {object} elements DOM-элементы picker.
+ * @returns {Function} Async-обработчик для addEventListener('change', ...).
+ *
+ * busy устанавливается синхронно до первого await. Поэтому второе быстрое
+ * событие выбора не запускает параллельный разбор и не меняет дерево конкурирующе.
+ */
+export function onFilesChange(state, cfg, elements) {
+  return async () => {
+    if (state.busy) return;
+    state.busy = true;
+    try {
+      await addFiles(state, cfg, elements.fileInputEl.files, elements);
+    } finally {
+      // Даже исключение вне внутреннего ZIP-catch не оставляет picker заблокированным.
+      elements.fileInputEl.value = '';
+      state.busy = false;
+    }
+  };
+}

upload/frontend/table/on_folder_change.js

@@ -0,0 +1,84 @@
+import { listZipFiles } from '../zip/list_zip_files.js';
+import { addFileWithDedup } from './add_file_with_dedup.js';
+import { rebaseTree } from './rebase_tree.js';
+import { render } from './render.js';
+
+/**
+ * Создаёт async-обработчик выбора каталога через webkitdirectory.
+ *
+ * @param {{nodes: Array, fileKeys: Set<string>, busy: boolean}} state Состояние picker.
+ * @param {{allowedExt: string[]}} cfg Разрешённые расширения.
+ * @param {{folderInputEl: HTMLInputElement, tableBodyEl: HTMLElement, countEl: HTMLElement}} elements DOM-элементы.
+ * @returns {Function} Async-обработчик события change.
+ *
+ * Браузер отдаёт плоский FileList с webkitRelativePath. Обработчик группирует
+ * его по первой части пути, создаёт промежуточные папки и затем добавляет каждый
+ * корень через общую дедупликацию. ZIP внутри каталога раскрывается тем же кодом,
+ * что и ZIP из обычного file input.
+ */
+export function onFolderChange(state, cfg, elements) {
+  return async () => {
+    if (state.busy) return;
+    state.busy = true;
+    try {
+      const roots = new Map();
+      for (const file of Array.from(elements.folderInputEl.files)) {
+        // Для webkitdirectory путь начинается с выбранной корневой папки.
+        const parts = (file.webkitRelativePath || file.name).split('/');
+        const relativePath = parts.slice(1).join('/') || file.name;
+        const lowerPath = relativePath.toLowerCase();
+        const rootName = parts[0] || file.name;
+        if (!roots.has(rootName)) {
+          // Один root на выбранный каталог позволяет сохранить дерево целиком.
+          roots.set(rootName, { id: crypto.randomUUID(), kind: 'folder', name: rootName,
+            path: rootName, children: [], expanded: false });
+        }
+        const root = roots.get(rootName);
+        // Вставляет узел по его пути, создавая отсутствующие промежуточные папки.
+        const addToFolder = (node) => {
+          let current = root;
+          const nodeParts = node.path.split('/').slice(1);
+          nodeParts.forEach((part, index) => {
+            const last = index === nodeParts.length - 1;
+            let child = current.children.find((item) => item.name === part);
+            if (!child) {
+              child = last ? node : { id: crypto.randomUUID(), kind: 'folder', name: part,
+                path: `${rootName}/${nodeParts.slice(0, index + 1).join('/')}`,
+                children: [], expanded: false };
+              current.children.push(child);
+            }
+            current = child;
+          });
+        };
+        if (lowerPath.endsWith('.zip')) {
+          try {
+            // ZIP rebased на имя выбранной папки перед вставкой в общий root.
+            const zip = await listZipFiles(file, cfg.allowedExt, cfg.limits);
+            if (zip) {
+              rebaseTree(zip, rootName);
+              addToFolder(zip);
+            }
+          } catch (error) {
+            // Ошибка одного ZIP не должна терять остальные файлы каталога.
+            if (typeof cfg.onError === 'function') {
+              cfg.onError(error, file);
+            } else if (elements.statusEl) {
+              elements.statusEl.textContent = `Ошибка чтения архива ${file.name}: ${error.message}`;
+            }
+            continue;
+          }
+        } else if (cfg.allowedExt.some((extension) => lowerPath.endsWith(extension))) {
+          addToFolder({ id: crypto.randomUUID(), kind: 'file', name: parts.at(-1),
+            path: `${rootName}/${relativePath}`, file, children: [], expanded: true });
+        }
+      }
+      // Дедупликация выполняется после сборки каждого корня каталога.
+      roots.forEach((root) => addFileWithDedup(state, root));
+      // Сброс value позволяет выбрать тот же каталог повторно.
+      elements.folderInputEl.value = '';
+      render(state, elements, cfg);
+    } finally {
+      state.busy = false;
+    }
+  };
+}

upload/frontend/table/rebase_tree.js

@@ -0,0 +1,16 @@
+/**
+ * Добавляет префикс корневой папки к каждому пути дерева.
+ *
+ * @param {{path: string, file?: File, children: Array}} root Узел дерева.
+ * @param {string} prefix Путь выбранной папки, в которую попал узел.
+ * @returns {object} Тот же узел после изменения путей.
+ *
+ * Для leaf-файлов создаётся новый File с тем же базовым именем; логический путь
+ * хранится отдельно в узле дерева.
+ */
+export function rebaseTree(root, prefix) {
+  root.path = `${prefix}/${root.path}`;
+  if (root.file) root.file = new File([root.file], root.file.name, { lastModified: root.file.lastModified });
+  root.children.forEach((child) => rebaseTree(child, prefix));
+  return root;
+}

upload/frontend/table/render.js

@@ -0,0 +1,124 @@
+import { esc } from './esc.js';
+import { fs } from './fs.js';
+
+const DEFAULT_RENDER_CONFIG = {
+  labels: {
+    statusReady: 'готов',
+    remove: 'Удалить',
+    empty: 'Нет выбранных файлов',
+    columns: { path: 'Путь', size: 'Размер', status: 'Статус' },
+    count: (count, bytes) => `${count} файлов · ${fs(bytes)}`,
+  },
+  layout: { columns: ['path', 'size', 'status'] },
+};
+
+function renderConfig(cfg = {}) {
+  return {
+    labels: {
+      ...DEFAULT_RENDER_CONFIG.labels,
+      ...(cfg.labels || {}),
+      columns: {
+        ...DEFAULT_RENDER_CONFIG.labels.columns,
+        ...(cfg.labels?.columns || {}),
+      },
+    },
+    layout: { ...DEFAULT_RENDER_CONFIG.layout, ...(cfg.layout || {}) },
+  };
+}
+
+/**
+ * Рендерит один узел дерева и его раскрытых потомков в HTML-строки таблицы.
+ *
+ * @param {{kind: string, id: string, name: string, path: string, file?: File,
+ *   children: Array, expanded: boolean, error?: string}} node Узел file/folder/zip.
+ * @param {number} depth Глубина узла; используется для визуального отступа.
+ * @returns {string} HTML одной строки или поддерева строк.
+ *
+ * Имена и пути проходят через esc до вставки в innerHTML. Группа получает
+ * кнопку раскрытия, leaf-файл — размер, статус и data-path для будущего API статусов.
+ */
+function renderNode(node, depth, cfg) {
+  const isGroup = node.kind !== 'file';
+  const padding = depth * 4;
+  const name = esc(node.name);
+  const action = isGroup
+    ? `<button class="tree-name tree-group tree-${node.kind}" style="padding-left:${padding}ch" data-toggle="${node.id}" `
+      + `aria-expanded="${node.expanded}"><span class="tree-chevron">${node.expanded ? '▼' : '▶'}</span>${name}</button>`
+    : `<span class="tree-name" style="padding-left:${padding}ch">${name}</span>`;
+  const remove = `<button class="remove-btn" type="button" data-remove="${node.id}" aria-label="${esc(cfg.labels.remove)} ${name}">×</button>`;
+  const pathAttribute = node.kind === 'file' ? ` data-path="${esc(node.path)}"` : '';
+  const cells = {
+    path: action,
+    size: node.kind === 'file' ? fs(node.file.size) : '',
+    status: node.error ? esc(node.error) : node.kind === 'file' ? esc(cfg.labels.statusReady) : '',
+  };
+  const columns = cfg.layout.columns?.length
+    ? cfg.layout.columns
+    : Object.keys(DEFAULT_RENDER_CONFIG.labels.columns);
+  const row = `<tr class="tree-row tree-${node.kind}"${pathAttribute}>`
+    + columns.map((column) => `<td>${cells[column] || ''}</td>`).join('')
+    + `<td>${remove}</td></tr>`;
+  if (!isGroup || !node.expanded) return row;
+  // Дочерние строки добавляются только для раскрытой группы.
+  return row + node.children.map((child) => renderNode(child, depth + 1, cfg)).join('');
+}
+
+/**
+ * Полностью синхронизирует DOM таблицы и счётчик с текущим state.nodes.
+ *
+ * @param {{nodes: Array}} state Состояние дерева.
+ * @param {{tableBodyEl: HTMLElement, countEl: HTMLElement}} elements DOM-вывод.
+ * @returns {void}
+ *
+ * Обход для счётчика независим от раскрытия: свернутая группа всё равно входит
+ * в количество leaf-файлов и суммарный размер.
+ */
+export function render(state, elements, cfg) {
+  const normalized = renderConfig(cfg);
+  const columns = normalized.layout.columns?.length
+    ? normalized.layout.columns
+    : Object.keys(DEFAULT_RENDER_CONFIG.labels.columns);
+  elements.tableBodyEl.innerHTML = state.nodes.length
+    ? state.nodes.map((node) => renderNode(node, 0, normalized)).join('')
+    : `<tr><td colspan="${columns.length + 1}">${esc(normalized.labels.empty)}</td></tr>`;
+  const files = [];
+  // Собирает все leaf-файлы, включая содержимое свернутых групп.
+  const visit = (node) => {
+    if (node.kind === 'file') files.push(node);
+    else node.children.forEach(visit);
+  };
+  state.nodes.forEach(visit);
+  const totalBytes = files.reduce((sum, node) => sum + node.file.size, 0);
+  elements.countEl.textContent = normalized.labels.count(files.length, totalBytes);
+}
+
+/**
+ * Ищет узел по уникальному id и возвращает также массив его непосредственного родителя.
+ *
+ * @param {Array} nodes Массив узлов текущего уровня.
+ * @param {string} id Идентификатор, созданный через crypto.randomUUID().
+ * @returns {{node: object, nodes: Array}|null} Узел и контейнер для удаления либо null.
+ */
+export function findNode(nodes, id) {
+  for (const node of nodes) {
+    if (node.id === id) return { node, nodes };
+    const found = findNode(node.children || [], id);
+    if (found) return found;
+  }
+  return null;
+}
+
+/**
+ * Преобразует иерархическое дерево в плоский список leaf-файлов.
+ *
+ * @param {Array} nodes Узлы любого уровня.
+ * @param {Array} result Внутренний аккумулятор рекурсивного вызова.
+ * @returns {Array<{path: string, name: string, size: number, file: File}>} Файлы для приложения.
+ */
+export function flattenFiles(nodes, result = []) {
+  nodes.forEach((node) => {
+    if (node.kind === 'file') result.push({ path: node.path, name: node.name, size: node.file.size, file: node.file });
+    else flattenFiles(node.children, result);
+  });
+  return result;
+}

upload/frontend/upload/put_to_vm.js

@@ -0,0 +1,78 @@
+/**
+ * putToVm — отправка одного файла в буфер методом HTTP PUT (сырое бинарное тело).
+ *
+ * @param {Blob|File} file Файл для отправки.
+ * @param {string} url Полный целевой URL в буфере.
+ * @param {Object} options Опции отправки:
+ * @param {function(number, number, number): void} [options.onProgress] Колбэк прогресса (pct, loaded, total).
+ * @param {function(XMLHttpRequest): void} [options.onXHR] Колбэк регистрации XHR для прямого контроля.
+ * @param {AbortSignal} [options.signal] Сигнал прерывания запроса (AbortController.signal).
+ * @param {number} [options.timeoutMs=300000] Таймаут в миллисекундах (по умолчанию 300с).
+ * @returns {Promise<void>} Разрешается при ответе 2xx, отклоняется при ошибке или прерывании.
+ */
+export function putToVm(file, url, options = {}) {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+
+    if (options.onXHR) {
+      options.onXHR(xhr);
+    }
+
+    const abortHandler = () => {
+      xhr.abort();
+      reject(new DOMException('Upload aborted', 'AbortError'));
+    };
+
+    if (options.signal) {
+      if (options.signal.aborted) {
+        reject(new DOMException('Upload aborted', 'AbortError'));
+        return;
+      }
+      options.signal.addEventListener('abort', abortHandler, { once: true });
+    }
+
+    xhr.open('PUT', url);
+    xhr.timeout = options.timeoutMs || 300000;
+
+    xhr.upload.onprogress = (e) => {
+      if (e.lengthComputable && options.onProgress) {
+        const pct = Math.round((e.loaded / e.total) * 100);
+        options.onProgress(pct, e.loaded, e.total);
+      }
+    };
+
+    xhr.onload = () => {
+      if (options.signal) {
+        options.signal.removeEventListener('abort', abortHandler);
+      }
+      if (xhr.status >= 200 && xhr.status < 300) {
+        resolve();
+      } else {
+        reject(new Error(`Буфер: HTTP ${xhr.status} ${xhr.statusText}`));
+      }
+    };
+
+    xhr.onerror = () => {
+      if (options.signal) {
+        options.signal.removeEventListener('abort', abortHandler);
+      }
+      reject(new Error('Сетевая ошибка при отправке в буфер'));
+    };
+
+    xhr.ontimeout = () => {
+      if (options.signal) {
+        options.signal.removeEventListener('abort', abortHandler);
+      }
+      reject(new Error(`Таймаут ожидания ответа буфера (${Math.round(xhr.timeout / 1000)}с)`));
+    };
+
+    xhr.onabort = () => {
+      if (options.signal) {
+        options.signal.removeEventListener('abort', abortHandler);
+      }
+      reject(new DOMException('Upload aborted', 'AbortError'));
+    };
+
+    xhr.send(file);
+  });
+}

upload/frontend/upload/upload_via_vm.js

@@ -0,0 +1,188 @@
+/**
+ * uploadViaVM — Слой 2 (Фронтенд): пофайловый транзит через ВМ-буфер в сессию бэкенда.
+ *
+ * Архитектура потокового транзита:
+ * Для каждого файла k:
+ *   1. Браузер отправляет файл k методом PUT в буфер на ВМ.
+ *   2. Браузер сразу делает POST /api/upload_refs для одного файла k.
+ *   3. Бэкенд забирает файл исходящим GET в память RAM и сразу шлёт DELETE в буфер.
+ *   4. Файл удалён из буфера ВМ, память чиста.
+ *   5. Браузер переходит к файлу k+1.
+ */
+
+import { putToVm } from './put_to_vm.js';
+import { fs } from '../table/fs.js';
+
+function generateUuid() {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+/**
+ * Нормализует элемент списка файлов (поддерживает как File, так и объект из FilePicker.getFiles()).
+ */
+function normalizeFileEntry(item) {
+  if (item instanceof File || item instanceof Blob) {
+    return { name: item.name || 'unnamed', size: item.size, file: item, path: item.name || '' };
+  }
+  if (item && item.file) {
+    return {
+      name: item.name || item.file.name || 'unnamed',
+      size: item.size ?? item.file.size ?? 0,
+      file: item.file,
+      path: item.path || item.name || '',
+    };
+  }
+  throw new Error('Некорректный объект файла');
+}
+
+/**
+ * Выполняет пофайловую транзитную загрузку файлов в сессию бэкенда через буфер.
+ *
+ * @param {Array<File|{name: string, size: number, file: File, path?: string}>} files Список файлов.
+ * @param {Object} options Параметры загрузки:
+ * @param {string} options.vmUploadUrl Базовый URL буфера (обязателен).
+ * @param {string} [options.backendUploadUrl='/api/upload_refs'] URL эндпоинта приёма ссылок.
+ * @param {string} [options.session=''] Идентификатор существующей сессии (если есть).
+ * @param {AbortSignal} [options.signal] Сигнал отмены загрузки.
+ * @param {function(string): void} [options.onStatus] Колбэк общего текстового статуса.
+ * @param {function(number, string): void} [options.onFileStatus] Колбэк обновления статуса конкретного файла (индекс, текст/html).
+ * @param {function(Object): void} [options.onProgress] Колбэк прогресса текущего файла ({ index, total, pct, speed }).
+ * @param {function(Object): void} [options.onFileComplete] Колбэк успешной доставки файла ({ index, name, session, totalAdded }).
+ * @returns {Promise<{ok: boolean, session?: string, count?: number, error?: string, aborted?: boolean}>}
+ */
+export async function uploadViaVM(files, options = {}) {
+  if (!options.vmUploadUrl) {
+    return { ok: false, error: 'Параметр options.vmUploadUrl обязателен' };
+  }
+
+  const normalizedFiles = Array.from(files).map(normalizeFileEntry);
+  const total = normalizedFiles.length;
+  if (total === 0) {
+    return { ok: true, session: options.session || '', count: 0 };
+  }
+
+  const backendUrl = options.backendUploadUrl || (options.apiBase || '') + '/api/upload_refs';
+  const vmBase = options.vmUploadUrl.endsWith('/') ? options.vmUploadUrl : `${options.vmUploadUrl}/`;
+  let currentSession = options.session || '';
+  let totalAdded = 0;
+
+  for (let k = 0; k < total; k++) {
+    if (options.signal?.aborted) {
+      return { ok: false, error: 'Загрузка отменена', aborted: true, session: currentSession };
+    }
+
+    const { name, size, file } = normalizedFiles[k];
+    const fileKey = `${generateUuid()}_${k}`;
+    const fileUrl = `${vmBase}${fileKey}`;
+
+    if (options.onStatus) {
+      options.onStatus(`Загрузка в буфер (${k + 1}/${total}): ${name}`);
+    }
+    if (options.onFileStatus) {
+      options.onFileStatus(k, '⏳ В буфер...');
+    }
+
+    // Этап 1: Отправка одного файла в буфер
+    const t0 = performance.now();
+    try {
+      await putToVm(file, fileUrl, {
+        signal: options.signal,
+        onXHR: options.onXHR,
+        onProgress(pct, loaded, fileTotal) {
+          const elapsed = (performance.now() - t0) / 1000;
+          const speed = elapsed > 0 ? (loaded / elapsed) : 0;
+          if (options.onFileStatus) {
+            options.onFileStatus(k, `⏳ ${pct}% (${fs(speed)}/s)`);
+          }
+          if (options.onProgress) {
+            options.onProgress({ index: k, total, pct, speed, loaded, fileTotal, name });
+          }
+        },
+      });
+    } catch (err) {
+      if (options.signal?.aborted) {
+        return { ok: false, error: 'Загрузка отменена', aborted: true, session: currentSession };
+      }
+      if (options.onFileStatus) {
+        options.onFileStatus(k, '✗ Ошибка буфера');
+      }
+      return {
+        ok: false,
+        error: `Ошибка отправки файла ${name} в буфер: ${err.message}`,
+        failedIndex: k,
+        session: currentSession,
+      };
+    }
+
+    // Этап 2: Вызов /api/upload_refs для немедленного переноса файла с буфера в RAM сессии
+    if (options.onStatus) {
+      options.onStatus(`Приём сервисом (${k + 1}/${total}): ${name}`);
+    }
+    if (options.onFileStatus) {
+      options.onFileStatus(k, '⚡ В сессию...');
+    }
+
+    try {
+      const resp = await fetch(backendUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          session: currentSession,
+          files: [{ name, size, url: fileUrl }],
+        }),
+        signal: options.signal,
+      });
+
+      if (!resp.ok) {
+        throw new Error(`HTTP ${resp.status} ${resp.statusText}`);
+      }
+
+      const data = await resp.json();
+      if (!data.ok) {
+        throw new Error(data.error || 'Бэкенд вернул ошибку');
+      }
+
+      currentSession = data.session || currentSession;
+      totalAdded = data.count ?? (totalAdded + 1);
+
+      if (options.onFileStatus) {
+        options.onFileStatus(k, '✓ Доставлен');
+      }
+      if (options.onFileComplete) {
+        options.onFileComplete({
+          fileIndex: k,
+          name,
+          size,
+          session: currentSession,
+          totalAdded,
+        });
+      }
+    } catch (err) {
+      if (options.signal?.aborted) {
+        return { ok: false, error: 'Загрузка отменена', aborted: true, session: currentSession };
+      }
+      if (options.onFileStatus) {
+        options.onFileStatus(k, '✗ Ошибка приёма');
+      }
+      return {
+        ok: false,
+        error: `Ошибка приёма файла ${name} бэкендом: ${err.message}`,
+        failedIndex: k,
+        session: currentSession,
+      };
+    }
+  }
+
+  if (options.onStatus) {
+    options.onStatus(`Завершено. Успешно передано файлов: ${total}`);
+  }
+
+  return { ok: true, session: currentSession, count: totalAdded };
+}

upload/frontend/zip/list_zip_files.js

@@ -0,0 +1,125 @@
+// Построить дерево ZIP с файлами только разрешённых расширений.
+import { unzipSync } from 'fflate';
+import { rebaseTree } from '../table/rebase_tree.js';
+
+const DEFAULT_LIMITS = {
+  maxEntries: 1000,
+  maxTotalBytes: 100 * 1024 * 1024,
+  maxEntryBytes: 50 * 1024 * 1024,
+  maxDepth: 20,
+};
+
+/** Возвращает true, если имя заканчивается одним из разрешённых расширений. */
+function extensionAllowed(name, allowedExt) {
+  const lowerName = name.toLowerCase();
+  return allowedExt.some((extension) => lowerName.endsWith(extension.toLowerCase()));
+}
+
+/** Создаёт browser File из байтов ZIP entry с базовым именем файла. */
+function makeFile(data, name) {
+  return new File([data], name.split('/').at(-1));
+}
+
+/**
+ * Валидирует путь ZIP entry до его использования в дереве.
+ *
+ * @param {string} entryName Сырой путь из центрального каталога ZIP.
+ * @returns {string[]|null} Безопасные сегменты пути или null для опасной записи.
+ *
+ * Отклоняются абсолютные пути, backslash, пустые сегменты, `.` и `..`.
+ * Это предотвращает traversal и появление ложных групп в UI.
+ */
+function safeEntryParts(entryName) {
+  if (!entryName || entryName.startsWith('/') || entryName.includes('\\')) return null;
+  const parts = entryName.split('/');
+  if (parts.some((part) => !part || part === '.' || part === '..')) return null;
+  return parts;
+}
+
+/** Создаёт единый узел file, folder или zip с уникальным id и начальным состоянием раскрытия. */
+function node(kind, name, path, children = [], file = null) {
+  return { id: crypto.randomUUID(), kind, name, path, children, file, expanded: kind === 'file' };
+}
+
+/** Вставляет leaf или вложенное дерево по сегментам пути, создавая folder-узлы. */
+function addPath(root, parts, fileNode) {
+  let current = root;
+  parts.forEach((part, index) => {
+    const last = index === parts.length - 1;
+    let child = current.children.find((item) => item.name === part);
+    if (!child) {
+      child = last
+        ? fileNode
+        : node('folder', part, `${current.path}/${part}`);
+      current.children.push(child);
+    }
+    current = child;
+  });
+}
+
+/**
+ * Рекурсивно читает байтовый массив ZIP и строит дерево разрешённых файлов.
+ *
+ * @param {Uint8Array} data Распаковываемые байты ZIP.
+ * @param {string} zipName Имя текущего архива для корневого узла и пути.
+ * @param {string[]} allowedExt Разрешённые расширения документов.
+ * @param {number} depth Текущая глубина вложенных ZIP.
+ * @returns {Promise<object|null>} Дерево или null, если разрешённых leaf нет.
+ * @throws {Error} При превышении глубины или повреждённом ZIP.
+ */
+async function listEntries(data, zipName, allowedExt, depth, limits, budget) {
+  // Ограничение глубины защищает браузер от бесконечной/чрезмерной рекурсии.
+  if (depth > limits.maxDepth) throw new Error('Слишком глубокая вложенность ZIP');
+  const entries = unzipSync(data, {
+    filter: (entry) => {
+      budget.entries += 1;
+      if (budget.entries > limits.maxEntries) throw new Error('Слишком много ZIP entries');
+      const lowerName = entry.name.toLowerCase();
+      if (!extensionAllowed(lowerName, allowedExt) && !lowerName.endsWith('.zip')) return false;
+      if (entry.originalSize > limits.maxEntryBytes) return false;
+      if (budget.totalBytes + entry.originalSize > limits.maxTotalBytes) {
+        throw new Error('Превышен суммарный размер распакованных ZIP entries');
+      }
+      budget.totalBytes += entry.originalSize;
+      return true;
+    },
+  });
+  const root = node('zip', zipName, zipName);
+
+  for (const [entryName, entryData] of Object.entries(entries)) {
+    // Каталоги ZIP не являются файлами и будут созданы addPath при необходимости.
+    if (entryName.endsWith('/')) continue;
+    const parts = safeEntryParts(entryName);
+    if (!parts) continue;
+    const normalizedName = parts.join('/');
+    if (normalizedName.toLowerCase().endsWith('.zip')) {
+      // Вложенный ZIP раскрывается только если внутри есть разрешённые leaf-файлы.
+      const nested = await listEntries(entryData, entryName, allowedExt, depth + 1, limits, budget);
+      if (nested) {
+        rebaseTree(nested, zipName);
+        nested.name = parts.at(-1);
+        addPath(root, parts, nested);
+      }
+    } else if (extensionAllowed(normalizedName, allowedExt)) {
+      // Запрещённые документы отбрасываются до создания browser File.
+      const path = `${zipName}/${normalizedName}`;
+      const file = makeFile(entryData, path);
+      addPath(root, parts, node('file', parts.at(-1), path, [], file));
+    }
+  }
+  return root.children.length ? root : null;
+}
+
+/**
+ * Публично читает выбранный ZIP-файл и возвращает его фильтрованное дерево.
+ *
+ * @param {File} file Browser File с ZIP-содержимым.
+ * @param {string[]} allowedExt Разрешённые расширения.
+ * @param {object} customLimits Ограничения распаковки.
+ * @returns {Promise<object|null>} Корневой zip-узел или null для пустого результата.
+ */
+export async function listZipFiles(file, allowedExt, customLimits = {}) {
+  const data = new Uint8Array(await file.arrayBuffer());
+  const limits = { ...DEFAULT_LIMITS, ...customLimits };
+  return listEntries(data, file.name, allowedExt, 0, limits, { entries: 0, totalBytes: 0 });
+}