@mindexec/cli 0.2.458 → 0.2.460

package/desktop-workspace-state.cjs

@@ -0,0 +1,120 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DESKTOP_WORKSPACE_STATE_VERSION = 1;
+
+function normalizeWorkspacePath(value) {
+  const candidate = String(value || '').trim();
+  return candidate ? path.resolve(candidate) : '';
+}
+
+function isExistingDirectory(candidatePath) {
+  if (!candidatePath) {
+    return false;
+  }
+
+  try {
+    return fs.statSync(candidatePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function loadDesktopWorkspaceState(statePath) {
+  const resolvedStatePath = normalizeWorkspacePath(statePath);
+  if (!resolvedStatePath) {
+    return null;
+  }
+
+  try {
+    const payload = JSON.parse(fs.readFileSync(resolvedStatePath, 'utf8'));
+    const workspacePath = normalizeWorkspacePath(payload?.workspacePath);
+    if (Number(payload?.version) !== DESKTOP_WORKSPACE_STATE_VERSION || !workspacePath) {
+      return null;
+    }
+
+    return {
+      version: DESKTOP_WORKSPACE_STATE_VERSION,
+      workspacePath
+    };
+  } catch {
+    return null;
+  }
+}
+
+function resolveDesktopWorkspace(options = {}) {
+  const explicitWorkspace = normalizeWorkspacePath(options.explicitWorkspace);
+  if (explicitWorkspace) {
+    return {
+      workspacePath: explicitWorkspace,
+      source: 'explicit'
+    };
+  }
+
+  const savedState = loadDesktopWorkspaceState(options.statePath);
+  if (savedState && isExistingDirectory(savedState.workspacePath)) {
+    return {
+      workspacePath: savedState.workspacePath,
+      source: 'saved'
+    };
+  }
+
+  const fallbackWorkspace = normalizeWorkspacePath(options.fallbackWorkspace);
+  if (!fallbackWorkspace) {
+    throw new Error('A fallback desktop workspace is required.');
+  }
+
+  return {
+    workspacePath: fallbackWorkspace,
+    source: 'fallback'
+  };
+}
+
+function saveDesktopWorkspaceState(statePath, workspacePath) {
+  const resolvedStatePath = normalizeWorkspacePath(statePath);
+  if (!resolvedStatePath) {
+    return false;
+  }
+
+  const resolvedWorkspacePath = normalizeWorkspacePath(workspacePath);
+  if (!isExistingDirectory(resolvedWorkspacePath)) {
+    throw new Error(`Desktop workspace must be an existing directory: ${resolvedWorkspacePath || workspacePath}`);
+  }
+
+  fs.mkdirSync(path.dirname(resolvedStatePath), { recursive: true });
+  const payload = {
+    version: DESKTOP_WORKSPACE_STATE_VERSION,
+    workspacePath: resolvedWorkspacePath
+  };
+  const tempPath = `${resolvedStatePath}.${process.pid}.${Date.now()}.tmp`;
+
+  try {
+    fs.writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600
+    });
+    try {
+      fs.renameSync(tempPath, resolvedStatePath);
+    } catch (error) {
+      if (error?.code !== 'EEXIST' && error?.code !== 'EPERM' && error?.code !== 'ENOTEMPTY') {
+        throw error;
+      }
+
+      fs.rmSync(resolvedStatePath, { force: true });
+      fs.renameSync(tempPath, resolvedStatePath);
+    }
+  } finally {
+    fs.rmSync(tempPath, { force: true });
+  }
+
+  return true;
+}
+
+module.exports = {
+  DESKTOP_WORKSPACE_STATE_VERSION,
+  loadDesktopWorkspaceState,
+  resolveDesktopWorkspace,
+  saveDesktopWorkspaceState
+};

package/electron/main.cjs

@@ -6,6 +6,9 @@ const fs = require('fs');
 const http = require('http');
 const net = require('net');
 const path = require('path');
+const workspaceState = require('../desktop-workspace-state.cjs');
+
+const { resolveDesktopWorkspace } = workspaceState;
 
 const DEFAULT_BRIDGE_PORT = 5147;
 const DEFAULT_REMOTE_HUB_PORT = 5198;
@@ -20,6 +23,7 @@ let requestedExitCode = 0;
 let activeBridgePort = DEFAULT_BRIDGE_PORT;
 let activeRemoteHubPort = DEFAULT_REMOTE_HUB_PORT;
 let activeWorkspace = '';
+let desktopWorkspaceStatePath = '';
 
 function resolveDesktopIconPath() {
   const iconPath = path.resolve(__dirname, '..', 'wwwroot', 'icon-512.png');
@@ -121,6 +125,7 @@ function spawnBundledBridge(packageRoot) {
       ELECTRON_RUN_AS_NODE: '1',
       MINDEXEC_DESKTOP: '1',
       MINDEXEC_NO_OPEN: '1',
+      MINDEXEC_DESKTOP_WORKSPACE_STATE_PATH: desktopWorkspaceStatePath,
       WORKSPACE_PATH: activeWorkspace,
       BRIDGE_PORT: String(activeBridgePort),
       REMOTE_HUB_PORT: String(activeRemoteHubPort)
@@ -180,15 +185,21 @@ async function prepareBundledRuntime() {
     'RemoteHub',
     activeBridgePort
   );
-  activeWorkspace = path.resolve(
-    process.env.MINDEXEC_DESKTOP_WORKSPACE
-      || process.env.WORKSPACE_PATH
-      || path.join(app.getPath('documents'), 'MindExecution')
+  desktopWorkspaceStatePath = path.resolve(
+    process.env.MINDEXEC_DESKTOP_WORKSPACE_STATE_PATH
+      || path.join(app.getPath('userData'), 'workspace-state.json')
   );
+  const workspaceResolution = resolveDesktopWorkspace({
+    explicitWorkspace: process.env.MINDEXEC_DESKTOP_WORKSPACE || process.env.WORKSPACE_PATH,
+    statePath: desktopWorkspaceStatePath,
+    fallbackWorkspace: path.join(app.getPath('documents'), 'MindExecution')
+  });
+  activeWorkspace = workspaceResolution.workspacePath;
 
   fs.mkdirSync(activeWorkspace, { recursive: true });
   appendDesktopLog(
-    `Starting bundled runtime: bridge=${activeBridgePort}, remoteHub=${activeRemoteHubPort}, workspace=${activeWorkspace}`
+    `Starting bundled runtime: bridge=${activeBridgePort}, remoteHub=${activeRemoteHubPort}, ` +
+    `workspace=${activeWorkspace}, workspaceSource=${workspaceResolution.source}`
   );
   spawnBundledBridge(packageRoot);
   return waitForBundledBridge();
@@ -203,7 +214,7 @@ function createMainWindow() {
     minHeight: 640,
     show: !hiddenSmokeMode,
     autoHideMenuBar: true,
-    backgroundColor: '#0b1020',
+    backgroundColor: '#f8fafc',
     title: 'MindExec',
     icon: resolveDesktopIconPath(),
     webPreferences: {

package/electron/source-smoke.mjs

@@ -8,12 +8,14 @@ const electronDirectory = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(electronDirectory, '..');
 const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
 const mainSource = fs.readFileSync(path.join(electronDirectory, 'main.cjs'), 'utf8');
+const serverSource = fs.readFileSync(path.join(packageRoot, 'server.js'), 'utf8');
 
 assert.equal(packageJson.build?.appId, 'com.mindexec.desktop', 'Stable desktop appId is required.');
 assert.equal(packageJson.build?.productName, 'MindExec', 'Desktop product name changed unexpectedly.');
 assert.equal(packageJson.build?.extraMetadata?.main, 'electron/main.cjs', 'Packaged Electron entry point is missing.');
 assert.equal(packageJson.build?.asar, false, 'Bundled runtime executables require an unpacked app directory.');
 assert.ok(packageJson.files?.includes('electron/'), 'The npm package must include the Electron source contract.');
+assert.ok(packageJson.files?.includes('desktop-workspace-state.cjs'), 'The npm package must include desktop workspace state.');
 assert.match(packageJson.scripts?.['desktop:build:win'] || '', /electron-builder/, 'Windows build script is missing.');
 assert.match(packageJson.scripts?.['test:desktop:win'] || '', /windows-package-smoke/, 'Packaged smoke test is missing.');
 
@@ -27,6 +29,21 @@ assert.ok(fs.existsSync(builderIconPath), `Electron builder icon is missing: ${b
 const builderIconMetadata = await sharp(builderIconPath).metadata();
 assert.equal(builderIconMetadata.width, 1024, 'Electron builder icon must be 1024px wide.');
 assert.equal(builderIconMetadata.height, 1024, 'Electron builder icon must be 1024px tall.');
+assert.equal(builderIconMetadata.hasAlpha, true, 'Electron builder icon must preserve transparency.');
+const { data: builderIconPixels, info: builderIconInfo } = await sharp(builderIconPath)
+  .ensureAlpha()
+  .raw()
+  .toBuffer({ resolveWithObject: true });
+const builderIconCornerAlpha = [
+  builderIconPixels[3],
+  builderIconPixels[(builderIconInfo.width - 1) * 4 + 3],
+  builderIconPixels[(builderIconInfo.height - 1) * builderIconInfo.width * 4 + 3],
+  builderIconPixels[(builderIconInfo.width * builderIconInfo.height - 1) * 4 + 3]
+];
+assert.ok(
+  builderIconCornerAlpha.every((alpha) => alpha === 0),
+  'Electron builder icon must have fully transparent corners.'
+);
 
 const targets = packageJson.build?.win?.target || [];
 assert.ok(targets.some((target) => target.target === 'nsis'), 'NSIS target is required.');
@@ -43,6 +60,10 @@ assert.doesNotMatch(mainSource, /adopted|probeBridge/, 'Electron must not adopt
 assert.match(mainSource, /MINDEXEC_DESKTOP_SMOKE_RESULT/, 'Packaged runtime smoke contract is missing.');
 assert.match(mainSource, /icon:\s*resolveDesktopIconPath\(\)/, 'Electron windows must use the packaged MindExec icon.');
 assert.match(mainSource, /app\.setAppUserModelId\(DESKTOP_APP_ID\)/, 'Windows taskbar identity must use the stable app id.');
+assert.match(mainSource, /resolveDesktopWorkspace/, 'Electron startup must restore the last desktop workspace.');
+assert.match(mainSource, /MINDEXEC_DESKTOP_WORKSPACE_STATE_PATH/, 'Electron must share its workspace state path with LocalBridge.');
+assert.match(serverSource, /saveDesktopWorkspaceState\(DESKTOP_WORKSPACE_STATE_PATH, resolvedPath\)/,
+  'A successful desktop workspace switch must be saved for the next launch.');
 
 console.log(JSON.stringify({
   ok: true,

package/electron/windows-package-smoke.mjs

@@ -5,6 +5,9 @@ import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import desktopWorkspaceState from '../desktop-workspace-state.cjs';
+
+const { saveDesktopWorkspaceState } = desktopWorkspaceState;
 
 const electronDirectory = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(electronDirectory, '..');
@@ -85,9 +88,11 @@ function canBind(port) {
 const bridgePort = await reservePort();
 const remoteHubPort = await reservePort();
 const smokeRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mindexec-electron-smoke-'));
-const workspace = path.join(smokeRoot, 'workspace');
+const workspace = path.join(smokeRoot, 'saved-workspace');
 const resultPath = path.join(smokeRoot, 'result.json');
+const workspaceStatePath = path.join(smokeRoot, 'workspace-state.json');
 fs.mkdirSync(workspace, { recursive: true });
+saveDesktopWorkspaceState(workspaceStatePath, workspace);
 
 let child;
 try {
@@ -97,7 +102,7 @@ try {
       ...process.env,
       MINDEXEC_DESKTOP_SMOKE: '1',
       MINDEXEC_DESKTOP_SMOKE_RESULT: resultPath,
-      MINDEXEC_DESKTOP_WORKSPACE: workspace,
+      MINDEXEC_DESKTOP_WORKSPACE_STATE_PATH: workspaceStatePath,
       MINDEXEC_NO_OPEN: '1',
       BRIDGE_PORT: String(bridgePort),
       REMOTE_HUB_PORT: String(remoteHubPort)
@@ -123,6 +128,7 @@ try {
   assert.equal(result.runtimeMode, 'bundled', 'Electron did not use its bundled runtime.');
   assert.equal(result.bridgePort, bridgePort, 'Packaged shell did not use the requested Bridge port.');
   assert.equal(result.remoteHubPort, remoteHubPort, 'Packaged shell did not use the requested RemoteHub port.');
+  assert.equal(path.resolve(result.workspace), path.resolve(workspace), 'Packaged Electron did not restore the saved workspace.');
 
   const exitCode = await waitForExit(child, 15_000);
   assert.equal(exitCode, 0, `Packaged Electron smoke exited with code ${exitCode}.`);

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@mindexec/cli",
-  "version": "0.2.458",
+  "version": "0.2.460",
   "description": "MindExec local runtime and bridge CLI",
   "main": "server.js",
   "type": "module",
   "files": [
     "start-bridge.bat",
     "start-bridge.sh",
-    "launch-bridge.cjs",
-    "server.js",
+    "launch-bridge.cjs",
+    "desktop-workspace-state.cjs",
+    "server.js",
     "remote-hub.js",
     "lzo1x.js",
     "mode4-atlas.js",
@@ -28,9 +29,9 @@
     "dev": "node launch-bridge.cjs --watch",
     "desktop:start": "electron electron/main.cjs",
     "desktop:build:win": "electron-builder --win --x64 --publish never",
-    "test:desktop": "node electron/source-smoke.mjs",
+    "test:desktop": "node electron/source-smoke.mjs && node scripts/desktop-workspace-state-smoke.mjs",
     "test:desktop:win": "node electron/windows-package-smoke.mjs",
-    "test:syntax": "node --check server.js && node --check remote-hub.js && node --check lzo1x.js && node --check mode4-atlas.js && node --check mode4-atlas-worker.js && node --check codex-runtime.js && node --check codex-model-catalog.js && node --check launch-bridge.cjs && node --check port-guard.cjs && node --check electron/main.cjs && node --check electron/source-smoke.mjs && node --check electron/windows-package-smoke.mjs && node --check scripts/setup-tree-sitter-grammars.mjs && node --check scripts/npm-fresh-install-smoke.mjs && node --check scripts/auth-session-smoke.mjs && node --check scripts/codex-model-catalog-smoke.mjs && node --check scripts/codex-sdk-runtime-smoke.mjs && node --check scripts/remote-hub-smoke.mjs && node --check scripts/remote-hub-scale-smoke.mjs && node --check scripts/remote-fleet-render-smoke.mjs && node --check scripts/remote-http-smoke.mjs && node --check scripts/remote-frame-ws-smoke.mjs && node --check scripts/remote-input-ws-smoke.mjs && node --check scripts/remote-agent-ws-smoke.mjs && node --check scripts/remote-agent-managed-smoke.mjs && node --check scripts/remote-registry-follower-smoke.mjs && node --check scripts/remote-agent-package-smoke.mjs && node --check scripts/remote-fast-live-rate-smoke.mjs && node --check scripts/remote-fast-mdm-browser-smoke.mjs",
+    "test:syntax": "node --check server.js && node --check remote-hub.js && node --check lzo1x.js && node --check mode4-atlas.js && node --check mode4-atlas-worker.js && node --check codex-runtime.js && node --check codex-model-catalog.js && node --check launch-bridge.cjs && node --check port-guard.cjs && node --check desktop-workspace-state.cjs && node --check electron/main.cjs && node --check electron/source-smoke.mjs && node --check electron/windows-package-smoke.mjs && node --check scripts/desktop-workspace-state-smoke.mjs && node --check scripts/setup-tree-sitter-grammars.mjs && node --check scripts/npm-fresh-install-smoke.mjs && node --check scripts/auth-session-smoke.mjs && node --check scripts/codex-model-catalog-smoke.mjs && node --check scripts/codex-sdk-runtime-smoke.mjs && node --check scripts/remote-hub-smoke.mjs && node --check scripts/remote-hub-scale-smoke.mjs && node --check scripts/remote-fleet-render-smoke.mjs && node --check scripts/remote-http-smoke.mjs && node --check scripts/remote-frame-ws-smoke.mjs && node --check scripts/remote-input-ws-smoke.mjs && node --check scripts/remote-agent-ws-smoke.mjs && node --check scripts/remote-agent-managed-smoke.mjs && node --check scripts/remote-registry-follower-smoke.mjs && node --check scripts/remote-agent-package-smoke.mjs && node --check scripts/remote-fast-live-rate-smoke.mjs && node --check scripts/remote-fast-mdm-browser-smoke.mjs",
     "test:codex-sdk": "node scripts/codex-sdk-runtime-smoke.mjs",
     "test:codex-sdk:live": "node scripts/codex-sdk-runtime-smoke.mjs --live",
     "test:codex-sdk:live-tools": "node scripts/codex-sdk-runtime-smoke.mjs --live-tools",

package/scripts/desktop-workspace-state-smoke.mjs

@@ -0,0 +1,81 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import desktopWorkspaceState from '../desktop-workspace-state.cjs';
+
+const {
+  loadDesktopWorkspaceState,
+  resolveDesktopWorkspace,
+  saveDesktopWorkspaceState
+} = desktopWorkspaceState;
+
+const smokeRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mindexec-workspace-state-'));
+const savedWorkspace = path.join(smokeRoot, 'saved-workspace');
+const explicitWorkspace = path.join(smokeRoot, 'explicit-workspace');
+const fallbackWorkspace = path.join(smokeRoot, 'fallback-workspace');
+const missingWorkspace = path.join(smokeRoot, 'missing-workspace');
+const statePath = path.join(smokeRoot, 'profile', 'workspace-state.json');
+
+fs.mkdirSync(savedWorkspace, { recursive: true });
+fs.mkdirSync(explicitWorkspace, { recursive: true });
+fs.mkdirSync(fallbackWorkspace, { recursive: true });
+
+try {
+  assert.equal(saveDesktopWorkspaceState('', savedWorkspace), false, 'Non-desktop runtimes must remain a no-op.');
+  assert.equal(saveDesktopWorkspaceState(statePath, savedWorkspace), true);
+  assert.deepEqual(loadDesktopWorkspaceState(statePath), {
+    version: 1,
+    workspacePath: path.resolve(savedWorkspace)
+  });
+
+  assert.equal(saveDesktopWorkspaceState(statePath, explicitWorkspace), true);
+  assert.equal(loadDesktopWorkspaceState(statePath)?.workspacePath, path.resolve(explicitWorkspace),
+    'Changing folders must replace the prior desktop workspace state.');
+  assert.equal(saveDesktopWorkspaceState(statePath, savedWorkspace), true);
+
+  assert.deepEqual(resolveDesktopWorkspace({
+    statePath,
+    fallbackWorkspace
+  }), {
+    workspacePath: path.resolve(savedWorkspace),
+    source: 'saved'
+  });
+
+  assert.deepEqual(resolveDesktopWorkspace({
+    explicitWorkspace,
+    statePath,
+    fallbackWorkspace
+  }), {
+    workspacePath: path.resolve(explicitWorkspace),
+    source: 'explicit'
+  });
+
+  fs.writeFileSync(statePath, `${JSON.stringify({ version: 1, workspacePath: missingWorkspace })}\n`, 'utf8');
+  assert.deepEqual(resolveDesktopWorkspace({
+    statePath,
+    fallbackWorkspace
+  }), {
+    workspacePath: path.resolve(fallbackWorkspace),
+    source: 'fallback'
+  });
+  assert.equal(fs.existsSync(missingWorkspace), false, 'A deleted saved workspace must not be recreated.');
+
+  fs.writeFileSync(statePath, '{broken json', 'utf8');
+  assert.deepEqual(resolveDesktopWorkspace({
+    statePath,
+    fallbackWorkspace
+  }), {
+    workspacePath: path.resolve(fallbackWorkspace),
+    source: 'fallback'
+  });
+
+  console.log(JSON.stringify({
+    ok: true,
+    restoredWorkspace: path.resolve(savedWorkspace),
+    invalidSavedWorkspaceFallsBack: true,
+    explicitWorkspaceWins: true
+  }));
+} finally {
+  fs.rmSync(smokeRoot, { recursive: true, force: true });
+}

package/server.js

@@ -26,10 +26,12 @@ import { createCodexModelCatalog } from './codex-model-catalog.js';
 import { createRemoteHub } from './remote-hub.js';
 import { Mode4AtlasSession } from './mode4-atlas.js';
 import portGuard from './port-guard.cjs';
+import desktopWorkspaceState from './desktop-workspace-state.cjs';
 
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
 const { normalizePort, releaseBridgePort } = portGuard;
+const { saveDesktopWorkspaceState } = desktopWorkspaceState;
 
 const app = express();
 const PORT = normalizePort(process.env.BRIDGE_PORT);
@@ -48,6 +50,7 @@ const VERBOSE_REMOTE_HTTP_LOGS = /^(1|true|yes|on)$/i.test(String(process.env.MI
 const VERBOSE_REMOTE_AGENT_LOGS = /^(1|true|yes|on)$/i.test(String(process.env.MINDEXEC_VERBOSE_REMOTE_AGENT || process.env.BRIDGE_VERBOSE_REMOTE_AGENT || ''));
 const COLOR_LOGS_ENABLED = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
 const DEFAULT_WEB_APP_ROOT = path.join(BRIDGE_ROOT, 'wwwroot');
+const DESKTOP_WORKSPACE_STATE_PATH = String(process.env.MINDEXEC_DESKTOP_WORKSPACE_STATE_PATH || '').trim();
 
 const ANSI = {
     reset: '\x1b[0m',
@@ -13204,11 +13207,12 @@ app.post('/api/workspace/set', async (req, res) => {
             return res.status(400).json({ error: 'Path is required' });
         }
 
-        const resolvedPath = path.resolve(newPath);
-        await closeProjectSession();
-        await ensureWorkspaceDataLayout(resolvedPath);
-
-        workspacePath = resolvedPath;
+        const resolvedPath = path.resolve(newPath);
+        await closeProjectSession();
+        await ensureWorkspaceDataLayout(resolvedPath);
+        saveDesktopWorkspaceState(DESKTOP_WORKSPACE_STATE_PATH, resolvedPath);
+
+        workspacePath = resolvedPath;
         console.log(`[Workspace] Set to: ${workspacePath}`);
 
         res.json({ success: true, workspace: workspacePath });
@@ -14062,7 +14066,12 @@ async function generateThumbnail(inputBuffer, outputPath) {
         await fs.mkdir(thumbsDir, { recursive: true });
 
         // Generate thumbnail with sharp
-        await sharp(inputBuffer)
+        await sharp(inputBuffer, {
+            animated: false,
+            page: 0,
+            pages: 1,
+            limitInputPixels: 64 * 1024 * 1024
+        })
             .resize(THUMBNAIL_SIZE, THUMBNAIL_SIZE, {
                 fit: 'inside',
                 withoutEnlargement: true
@@ -14193,16 +14202,27 @@ app.post('/api/assets/generate-thumbnail/:filename', async (req, res) => {
             }
         }
 
-        // Read original file
-        const buffer = await fs.readFile(originalPath);
-
-        // Generate thumbnail
-        const thumbnailPath = getThumbnailPath(filename);
-        const success = await generateThumbnail(buffer, thumbnailPath);
-
-        if (success) {
-            const thumbnailUrl = `http://127.0.0.1:${PORT}/assets/thumbs/${path.basename(thumbnailPath)}`;
-            res.json({
+        const thumbnailPath = getThumbnailPath(filename);
+        const thumbnailUrl = `http://127.0.0.1:${PORT}/assets/thumbs/${path.basename(thumbnailPath)}`;
+        try {
+            await fs.access(thumbnailPath);
+            return res.json({
+                success: true,
+                thumbnailUrl,
+                filename: path.basename(thumbnailPath),
+                existing: true
+            });
+        } catch { }
+
+        // Read the original only when a bounded static thumbnail is missing.
+        const buffer = await fs.readFile(originalPath);
+
+        // Generate a single-frame thumbnail. Animated WebP originals can contain
+        // hundreds of frames and must never be fully decoded for resident LOD.
+        const success = await generateThumbnail(buffer, thumbnailPath);
+
+        if (success) {
+            res.json({
                 success: true,
                 thumbnailUrl,
                 filename: path.basename(thumbnailPath)