@livedesk/hub 0.1.0 → 0.1.1

package/README.md

@@ -1,9 +1,15 @@
 # @livedesk/hub
 
-Local LiveDesk manager hub.
+Local LiveDesk Hub runtime.
 
 This package is used by the `livedesk` launcher package. Most users should run:
 
 ```powershell
 npx -y livedesk
 ```
+
+Mode 4 runs its Atlas compositor in a separate worker process. It consumes
+latest-only Mode 2 frames and exposes one H.264 wall stream at
+`/api/remote/atlas/ws`. The grid uses native 320x180 cells until the configured
+1920x1080 bound requires smaller cells; focused control continues to use direct
+Mode 3.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@livedesk/hub",
-  "version": "0.1.0",
-  "description": "LiveDesk local RemoteHub API and browser frame bridge",
+  "version": "0.1.1",
+  "description": "LiveDesk local Hub API and browser frame bridge",
   "type": "module",
   "main": "src/server.js",
   "files": [
@@ -14,8 +14,11 @@
     "check": "node --check src/server.js && node --check src/remote-hub.js"
   },
   "dependencies": {
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
     "cors": "^2.8.5",
     "express": "^4.21.2",
+    "ffmpeg-static": "^5.3.0",
+    "path-to-regexp": "0.1.13",
     "ws": "^8.18.3"
   },
   "engines": {

package/src/filesystem/directory-reader.js

@@ -0,0 +1,187 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
+import { isPathWithinRoot } from './path-registry.js';
+
+function filesystemError(message, code = 'FILESYSTEM_ERROR', status = 400) {
+  const error = new Error(message);
+  error.code = code;
+  error.status = status;
+  return error;
+}
+
+function safeEntryName(name) {
+  return String(name || '').replace(/[\0\r\n\t]/g, ' ').slice(0, 512);
+}
+
+function toPublicEntry(entry) {
+  return {
+    id: entry.id,
+    parentId: entry.parentId,
+    name: entry.name,
+    type: entry.type,
+    size: entry.size || 0,
+    modifiedAt: entry.modifiedAt || null,
+    extension: entry.type === 'file' ? path.extname(entry.name).toLowerCase() : '',
+    hasChildren: entry.type !== 'file' && entry.hasChildren === true,
+    displayPath: entry.displayPath,
+    locked: entry.locked === true
+  };
+}
+
+async function readEntryStat(absolutePath) {
+  try {
+    return await fs.lstat(absolutePath);
+  } catch (error) {
+    if (error?.code === 'EACCES' || error?.code === 'EPERM') throw filesystemError('filesystem-access-denied', 'ACCESS_DENIED', 403);
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') throw filesystemError('filesystem-entry-unavailable', 'NOT_FOUND', 404);
+    throw error;
+  }
+}
+
+export async function readDirectoryEntries(registry, folderId) {
+  const folder = registry.resolve(folderId);
+  if (folder.type === 'file') throw filesystemError('filesystem-entry-is-not-folder', 'NOT_A_FOLDER', 400);
+  if (folder.locked) throw filesystemError('filesystem-access-denied', 'ACCESS_DENIED', 403);
+  let entries;
+  try {
+    entries = await fs.readdir(folder.absolutePath, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === 'EACCES' || error?.code === 'EPERM') throw filesystemError('filesystem-access-denied', 'ACCESS_DENIED', 403);
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') throw filesystemError('filesystem-entry-unavailable', 'NOT_FOUND', 404);
+    throw error;
+  }
+
+  const output = [];
+  for (const dirent of entries) {
+    const name = safeEntryName(dirent.name);
+    if (!name || name === '.' || name === '..') continue;
+    const absolutePath = path.resolve(folder.absolutePath, name);
+    if (!isPathWithinRoot(folder.rootPath, absolutePath)) continue;
+    const stat = await readEntryStat(absolutePath).catch(error => {
+      if (error?.code === 'ACCESS_DENIED' || error?.code === 'NOT_FOUND') return null;
+      throw error;
+    });
+    if (!stat) continue;
+    const isSymlink = dirent.isSymbolicLink() || stat.isSymbolicLink();
+    const type = !isSymlink && (dirent.isDirectory() || stat.isDirectory()) ? 'folder' : 'file';
+    const child = registry.register({
+      absolutePath,
+      rootPath: folder.rootPath,
+      rootId: folder.rootId,
+      parentId: folder.id,
+      name,
+      type,
+      displayPath: path.join(folder.displayPath, name),
+      locked: isSymlink
+    });
+    output.push(toPublicEntry({
+      ...child,
+      size: type === 'file' ? stat.size : 0,
+      modifiedAt: stat.mtime?.toISOString(),
+      hasChildren: type === 'folder' && !isSymlink
+    }));
+  }
+  output.sort((left, right) => {
+    if (left.type !== right.type) return left.type === 'folder' ? -1 : 1;
+    return left.name.localeCompare(right.name, undefined, { numeric: true, sensitivity: 'base' });
+  });
+  return {
+    folder: toPublicEntry({ ...folder, hasChildren: true }),
+    entries: output
+  };
+}
+
+async function walkDirectory(registry, entry, relativePrefix, output, visited, counters) {
+  const realPath = await fs.realpath(entry.absolutePath).catch(() => entry.absolutePath);
+  if (visited.has(realPath)) return;
+  visited.add(realPath);
+  let dirents;
+  try {
+    dirents = await fs.readdir(entry.absolutePath, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === 'EACCES' || error?.code === 'EPERM') throw filesystemError('filesystem-access-denied', 'ACCESS_DENIED', 403);
+    throw error;
+  }
+  for (const dirent of dirents) {
+    const name = safeEntryName(dirent.name);
+    if (!name || name === '.' || name === '..' || dirent.isSymbolicLink()) continue;
+    const absolutePath = path.resolve(entry.absolutePath, name);
+    if (!isPathWithinRoot(entry.rootPath, absolutePath)) continue;
+    const stat = await readEntryStat(absolutePath);
+    const relativePath = path.posix.join(relativePrefix, name);
+    if (stat.isDirectory()) {
+      counters.folders += 1;
+      const child = registry.register({
+        absolutePath,
+        rootPath: entry.rootPath,
+        rootId: entry.rootId,
+        parentId: entry.id,
+        name,
+        type: 'folder',
+        displayPath: path.join(entry.displayPath, name)
+      });
+      await walkDirectory(registry, child, relativePath, output, visited, counters);
+    } else if (stat.isFile()) {
+      const child = registry.register({
+        absolutePath,
+        rootPath: entry.rootPath,
+        rootId: entry.rootId,
+        parentId: entry.id,
+        name,
+        type: 'file',
+        displayPath: path.join(entry.displayPath, name)
+      });
+      output.push({
+        id: child.id,
+        absolutePath,
+        relativePath,
+        name,
+        size: stat.size,
+        modifiedMs: stat.mtimeMs,
+        modifiedAt: stat.mtime?.toISOString() || null
+      });
+      counters.files += 1;
+      counters.totalBytes += stat.size;
+    }
+    if ((counters.files + counters.folders) % 100 === 0) await yieldToEventLoop();
+  }
+}
+
+export async function scanSelection(registry, itemIds) {
+  const ids = [...new Set((Array.isArray(itemIds) ? itemIds : []).map(value => String(value || '').trim()).filter(Boolean))].slice(0, 5000);
+  if (ids.length === 0) throw filesystemError('no-filesystem-items-selected', 'NO_SELECTION', 400);
+  const selected = ids.map(id => registry.resolve(id));
+  const selectedPaths = selected.filter(entry => entry.type === 'folder').map(entry => path.resolve(entry.absolutePath));
+  const topLevel = selected.filter(entry => !selectedPaths.some(parent => parent !== entry.absolutePath && isPathWithinRoot(parent, entry.absolutePath)));
+  const files = [];
+  const counters = { files: 0, folders: 0, totalBytes: 0 };
+  const visited = new Set();
+  for (const entry of topLevel) {
+    const stat = await readEntryStat(entry.absolutePath);
+    if (entry.type === 'file' || stat.isFile()) {
+      files.push({
+        id: entry.id,
+        absolutePath: entry.absolutePath,
+        relativePath: entry.name,
+        name: entry.name,
+        size: stat.size,
+        modifiedMs: stat.mtimeMs,
+        modifiedAt: stat.mtime?.toISOString() || null
+      });
+      counters.files += 1;
+      counters.totalBytes += stat.size;
+      continue;
+    }
+    counters.folders += 1;
+    await walkDirectory(registry, entry, entry.name, files, visited, counters);
+  }
+  files.sort((left, right) => left.relativePath.localeCompare(right.relativePath, undefined, { numeric: true }));
+  return { ...counters, files };
+}
+
+export function toFilesystemHttpError(error) {
+  return error?.status
+    ? error
+    : filesystemError('filesystem-operation-failed', 'FILESYSTEM_ERROR', 500);
+}

package/src/filesystem/hub-filesystem.js

@@ -0,0 +1,78 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { discoverFilesystemRoots } from './roots.js';
+import { OpaquePathRegistry, isPathWithinRoot } from './path-registry.js';
+import { readDirectoryEntries, scanSelection } from './directory-reader.js';
+
+export class HubFilesystem {
+  constructor() {
+    this.registry = new OpaquePathRegistry();
+    this.rootsCache = null;
+    this.rootsLoadedAt = 0;
+  }
+
+  async getRoots({ refresh = false } = {}) {
+    if (!refresh && this.rootsCache && Date.now() - this.rootsLoadedAt < 30_000) return this.rootsCache;
+    const roots = await discoverFilesystemRoots();
+    const entries = roots.map(root => this.registry.register({
+      absolutePath: root.path,
+      rootPath: root.path,
+      rootId: `root:${root.path}`,
+      parentId: 'this-pc',
+      name: root.name,
+      type: 'folder',
+      displayPath: root.displayPath
+    }));
+    this.rootsCache = {
+      roots: entries.map((entry, index) => ({
+        id: entry.id,
+        parentId: 'this-pc',
+        name: entry.name,
+        type: 'drive',
+        size: 0,
+        modifiedAt: null,
+        hasChildren: roots[index].hasChildren,
+        displayPath: roots[index].displayPath,
+        driveType: roots[index].driveType,
+        totalBytes: roots[index].totalBytes,
+        freeBytes: roots[index].freeBytes
+      }))
+    };
+    this.rootsLoadedAt = Date.now();
+    return this.rootsCache;
+  }
+
+  async getEntries(id) {
+    return readDirectoryEntries(this.registry, id);
+  }
+
+  async scan(itemIds) {
+    return scanSelection(this.registry, itemIds);
+  }
+
+  resolve(id) {
+    return this.registry.resolve(id);
+  }
+
+  async registerPersistedFolder(absolutePath, displayPath = absolutePath) {
+    const normalized = path.resolve(String(absolutePath || ''));
+    const roots = await discoverFilesystemRoots();
+    const root = roots.find(candidate => isPathWithinRoot(candidate.path, normalized));
+    if (!root) return null;
+    const stat = await fs.lstat(normalized).catch(() => null);
+    if (!stat?.isDirectory()) return null;
+    return this.registry.register({
+      absolutePath: normalized,
+      rootPath: root.path,
+      rootId: `root:${root.path}`,
+      parentId: null,
+      name: path.basename(normalized) || normalized,
+      type: 'folder',
+      displayPath
+    });
+  }
+}
+
+export function createHubFilesystem() {
+  return new HubFilesystem();
+}

package/src/filesystem/path-registry.js

@@ -0,0 +1,78 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+
+function isWithinRoot(rootPath, candidatePath) {
+  const relative = path.relative(rootPath, candidatePath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+export class OpaquePathRegistry {
+  constructor({ ttlMs = 30 * 60 * 1000 } = {}) {
+    this.ttlMs = ttlMs;
+    this.entries = new Map();
+    this.byPath = new Map();
+  }
+
+  register({ absolutePath, rootPath, rootId, parentId = null, name, type, displayPath = absolutePath, locked = false }) {
+    const normalizedPath = path.resolve(absolutePath);
+    const normalizedRoot = path.resolve(rootPath);
+    if (!isWithinRoot(normalizedRoot, normalizedPath)) {
+      const error = new Error('filesystem-path-outside-root');
+      error.code = 'PATH_OUTSIDE_ROOT';
+      throw error;
+    }
+    const key = `${rootId}:${normalizedPath}`;
+    const existing = this.byPath.get(key);
+    if (existing && this.entries.has(existing)) {
+      const entry = this.entries.get(existing);
+      entry.expiresAt = Date.now() + this.ttlMs;
+      return entry;
+    }
+    const entry = {
+      id: `fs_${crypto.randomBytes(18).toString('base64url')}`,
+      absolutePath: normalizedPath,
+      rootPath: normalizedRoot,
+      rootId: String(rootId),
+      parentId,
+      name: String(name || path.basename(normalizedPath) || normalizedPath),
+      type: type === 'file' ? 'file' : 'folder',
+      displayPath: String(displayPath || normalizedPath),
+      locked: locked === true,
+      expiresAt: Date.now() + this.ttlMs
+    };
+    this.entries.set(entry.id, entry);
+    this.byPath.set(key, entry.id);
+    return entry;
+  }
+
+  resolve(id) {
+    this.prune();
+    const entry = this.entries.get(String(id || ''));
+    if (!entry) {
+      const error = new Error('invalid-filesystem-id');
+      error.code = 'INVALID_ID';
+      error.status = 400;
+      throw error;
+    }
+    entry.expiresAt = Date.now() + this.ttlMs;
+    return entry;
+  }
+
+  remove(id) {
+    const entry = this.entries.get(String(id || ''));
+    if (!entry) return;
+    this.entries.delete(entry.id);
+    this.byPath.delete(`${entry.rootId}:${entry.absolutePath}`);
+  }
+
+  prune() {
+    const now = Date.now();
+    for (const [id, entry] of this.entries) {
+      if (entry.expiresAt <= now) this.remove(id);
+    }
+  }
+}
+
+export function isPathWithinRoot(rootPath, candidatePath) {
+  return isWithinRoot(path.resolve(rootPath), path.resolve(candidatePath));
+}

package/src/filesystem/roots.js

@@ -0,0 +1,115 @@
+import fs from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import os from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+function normalizeRootPath(value) {
+  const text = String(value || '').trim();
+  if (!text) return '';
+  return process.platform === 'win32'
+    ? text.replace(/[\\/]+$/, '\\')
+    : text.replace(/\/+$/, '') || '/';
+}
+
+async function statfsCapacity(rootPath) {
+  try {
+    const stat = await fs.statfs(rootPath);
+    const blockSize = Number(stat.bsize || stat.frsize || 0);
+    return {
+      totalBytes: blockSize > 0 ? Number(stat.blocks || 0) * blockSize : 0,
+      freeBytes: blockSize > 0 ? Number(stat.bavail || stat.bfree || 0) * blockSize : 0
+    };
+  } catch {
+    return { totalBytes: 0, freeBytes: 0 };
+  }
+}
+
+async function windowsDriveTypes() {
+  if (process.platform !== 'win32') return new Map();
+  try {
+    const { stdout } = await execFileAsync('powershell.exe', [
+      '-NoProfile', '-NonInteractive', '-Command',
+      '$ProgressPreference="SilentlyContinue"; Get-CimInstance Win32_LogicalDisk | Select-Object DeviceID,DriveType | ConvertTo-Json -Compress'
+    ], { timeout: 2500, windowsHide: true, maxBuffer: 1024 * 1024 });
+    const parsed = JSON.parse(String(stdout || 'null'));
+    const rows = Array.isArray(parsed) ? parsed : parsed ? [parsed] : [];
+    const names = new Map([[2, 'removable'], [3, 'fixed'], [4, 'network'], [5, 'optical']]);
+    return new Map(rows.map(row => [String(row.DeviceID || '').toUpperCase(), names.get(Number(row.DriveType)) || 'unknown']));
+  } catch {
+    return new Map();
+  }
+}
+
+async function windowsRoots() {
+  const types = await windowsDriveTypes();
+  const roots = [];
+  for (let code = 65; code <= 90; code += 1) {
+    const letter = String.fromCharCode(code);
+    const path = `${letter}:\\`;
+    try {
+      await fs.access(path, fsConstants.R_OK);
+      const capacity = await statfsCapacity(path);
+      const driveType = types.get(`${letter}:`.toUpperCase()) || 'fixed';
+      roots.push({
+        path,
+        name: `${driveType === 'network' ? 'Network' : driveType === 'removable' ? 'External' : 'Drive'} (${letter}:)`,
+        displayPath: path,
+        type: 'drive',
+        driveType,
+        ...capacity,
+        hasChildren: true
+      });
+    } catch {
+      // An unavailable or inaccessible drive is not exposed to the browser.
+    }
+  }
+  return roots;
+}
+
+async function mountedRoots() {
+  const candidates = new Set(['/']);
+  if (process.platform === 'darwin') candidates.add('/Volumes');
+  if (process.platform === 'linux') {
+    candidates.add('/mnt');
+    candidates.add('/media');
+  }
+  const roots = [];
+  for (const candidate of candidates) {
+    try {
+      const stat = await fs.stat(candidate);
+      if (!stat.isDirectory()) continue;
+      const capacity = await statfsCapacity(candidate);
+      roots.push({
+        path: candidate,
+        name: candidate === '/' ? 'System root (/)' : candidate,
+        displayPath: candidate,
+        type: 'drive',
+        driveType: candidate === '/' ? 'fixed' : 'mount',
+        ...capacity,
+        hasChildren: true
+      });
+    } catch {
+      // Keep probing the remaining mount points.
+    }
+  }
+  return roots;
+}
+
+export async function discoverFilesystemRoots() {
+  const roots = process.platform === 'win32' ? await windowsRoots() : await mountedRoots();
+  if (roots.length > 0) return roots;
+  const fallback = process.platform === 'win32' ? `${process.env.SystemDrive || 'C:'}\\` : os.homedir();
+  return [{
+    path: fallback,
+    name: fallback,
+    displayPath: fallback,
+    type: 'drive',
+    driveType: 'unknown',
+    totalBytes: 0,
+    freeBytes: 0,
+    hasChildren: true
+  }];
+}

package/src/filesystem/shared-folders.js

@@ -0,0 +1,180 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const MANIFEST_VERSION = 1;
+const AUTO_SYNC_MS = 30_000;
+
+function publicFolder(folder, sourceId, status = 'ready', message = '') {
+  return {
+    id: folder.id,
+    sourceId,
+    displayPath: folder.displayPath,
+    name: folder.name,
+    autoSync: folder.autoSync === true,
+    status,
+    fileCount: Number(folder.fileCount || 0),
+    totalBytes: Number(folder.totalBytes || 0),
+    lastScannedAt: folder.lastScannedAt || undefined,
+    lastSyncedAt: folder.lastSyncedAt || undefined,
+    message: message || folder.message || undefined
+  };
+}
+
+export class HubSharedFolders {
+  constructor({ filesystem, transferJobs, remoteHub, dataDir = path.join(os.homedir(), '.livedesk') } = {}) {
+    this.filesystem = filesystem;
+    this.transferJobs = transferJobs;
+    this.remoteHub = remoteHub;
+    this.dataDir = dataDir;
+    this.filePath = path.join(dataDir, 'shared-folders.json');
+    this.folders = new Map();
+    this.loaded = false;
+    this.autoSyncTimer = null;
+    this.syncing = new Set();
+  }
+
+  async ensureLoaded() {
+    if (this.loaded) return;
+    this.loaded = true;
+    try {
+      const parsed = JSON.parse(await fs.readFile(this.filePath, 'utf8'));
+      for (const folder of Array.isArray(parsed?.folders) ? parsed.folders : []) {
+        if (folder?.id && folder?.sourcePath) this.folders.set(folder.id, { ...folder, manifestVersion: MANIFEST_VERSION });
+      }
+    } catch (error) {
+      if (error?.code !== 'ENOENT') console.warn(`[LiveDesk Hub] shared folder store unavailable: ${error?.message || error}`);
+    }
+  }
+
+  async persist() {
+    await fs.mkdir(this.dataDir, { recursive: true });
+    const temp = `${this.filePath}.tmp`;
+    await fs.writeFile(temp, JSON.stringify({ version: MANIFEST_VERSION, folders: [...this.folders.values()] }, null, 2), 'utf8');
+    await fs.rename(temp, this.filePath);
+  }
+
+  async list() {
+    await this.ensureLoaded();
+    const result = [];
+    for (const folder of this.folders.values()) {
+      const entry = await this.filesystem.registerPersistedFolder(folder.sourcePath, folder.displayPath);
+      result.push(publicFolder(folder, entry?.id || '', entry ? 'ready' : 'error', entry ? '' : 'Drive or folder unavailable'));
+    }
+    return result;
+  }
+
+  async add(sourceId) {
+    await this.ensureLoaded();
+    const entry = this.filesystem.resolve(sourceId);
+    if (entry.type !== 'folder') throw new Error('sync-source-must-be-folder');
+    const existing = [...this.folders.values()].find(folder => path.resolve(folder.sourcePath) === path.resolve(entry.absolutePath));
+    if (existing) return publicFolder(existing, sourceId);
+    const folder = {
+      id: `sync_${crypto.randomBytes(12).toString('base64url')}`,
+      sourcePath: entry.absolutePath,
+      displayPath: entry.displayPath,
+      name: entry.name,
+      autoSync: false,
+      fileCount: 0,
+      totalBytes: 0,
+      manifestVersion: MANIFEST_VERSION,
+      manifests: {}
+    };
+    this.folders.set(folder.id, folder);
+    await this.persist();
+    return publicFolder(folder, sourceId);
+  }
+
+  async update(id, patch = {}) {
+    await this.ensureLoaded();
+    const folder = this.folders.get(String(id || ''));
+    if (!folder) throw new Error('sync-folder-not-found');
+    if (typeof patch.autoSync === 'boolean') folder.autoSync = patch.autoSync;
+    await this.persist();
+    const entry = await this.filesystem.registerPersistedFolder(folder.sourcePath, folder.displayPath);
+    return publicFolder(folder, entry?.id || '', entry ? 'ready' : 'error', entry ? '' : 'Drive or folder unavailable');
+  }
+
+  async remove(id) {
+    await this.ensureLoaded();
+    const removed = this.folders.delete(String(id || ''));
+    if (removed) await this.persist();
+    return { ok: removed };
+  }
+
+  async sync(id, deviceIds, remoteDirectory) {
+    await this.ensureLoaded();
+    const folder = this.folders.get(String(id || ''));
+    if (!folder) throw new Error('sync-folder-not-found');
+    if (this.syncing.has(folder.id)) throw new Error('sync-already-running');
+    const source = await this.filesystem.registerPersistedFolder(folder.sourcePath, folder.displayPath);
+    if (!source) throw new Error('sync-source-unavailable');
+    const scan = await this.filesystem.scan([source.id]);
+    folder.fileCount = scan.files.length;
+    folder.totalBytes = scan.totalBytes;
+    folder.lastScannedAt = new Date().toISOString();
+    folder.message = '';
+    const jobs = [];
+    const targets = [...new Set((Array.isArray(deviceIds) ? deviceIds : []).map(value => String(value || '').trim()).filter(Boolean))];
+    this.syncing.add(folder.id);
+    try {
+      for (const deviceId of targets) {
+        const previous = folder.manifests?.[deviceId]?.entries || {};
+        const changedFiles = scan.files.filter(file => previous[file.relativePath]?.size !== file.size || previous[file.relativePath]?.modifiedMs !== file.modifiedMs);
+        if (changedFiles.length === 0) continue;
+        const fingerprints = Object.fromEntries(scan.files.map(file => [file.relativePath, { size: file.size, modifiedMs: file.modifiedMs }]));
+        jobs.push(this.transferJobs.create({
+          files: changedFiles,
+          deviceIds: [deviceId],
+          remoteDirectory,
+          onComplete: async ({ completed }) => {
+            if (!completed) return;
+            folder.manifests = folder.manifests || {};
+            folder.manifests[deviceId] = { version: MANIFEST_VERSION, entries: fingerprints, updatedAt: new Date().toISOString() };
+            folder.lastSyncedAt = new Date().toISOString();
+            await this.persist();
+          }
+        }));
+      }
+      folder.message = jobs.length > 0 ? `Syncing ${jobs.length} workstation${jobs.length === 1 ? '' : 's'}` : 'No changed files';
+      await this.persist();
+      return { ok: true, jobs, files: scan.files.length, totalBytes: scan.totalBytes };
+    } finally {
+      this.syncing.delete(folder.id);
+    }
+  }
+
+  startAutoSync(getDeviceIds, getRemoteDirectory = () => '') {
+    if (this.autoSyncTimer) return;
+    this.autoSyncTimer = setInterval(() => {
+      void this.runAutoSync(getDeviceIds, getRemoteDirectory);
+    }, AUTO_SYNC_MS);
+    this.autoSyncTimer.unref?.();
+  }
+
+  async runAutoSync(getDeviceIds, getRemoteDirectory) {
+    const deviceIds = typeof getDeviceIds === 'function' ? getDeviceIds() : [];
+    if (!deviceIds.length) return;
+    await this.ensureLoaded();
+    for (const folder of this.folders.values()) {
+      if (!folder.autoSync || this.syncing.has(folder.id)) continue;
+      try {
+        await this.sync(folder.id, deviceIds, getRemoteDirectory());
+      } catch (error) {
+        folder.message = error instanceof Error ? error.message : String(error);
+        await this.persist().catch(() => undefined);
+      }
+    }
+  }
+
+  close() {
+    if (this.autoSyncTimer) clearInterval(this.autoSyncTimer);
+    this.autoSyncTimer = null;
+  }
+}
+
+export function createHubSharedFolders(options) {
+  return new HubSharedFolders(options);
+}