Persist custom icon storage across reboot and upgrade

Author: FolderView Plus Test

archive/folderview.plus-2026.04.11.01.txz.sha256

@@ -0,0 +1 @@
+d637da0e9f97228b598d7274c765461a18d31ae124723c24b8caa35fa2eb1e10  folderview.plus-2026.04.14.13.txz

archive/folderview.plus-2026.04.11.01.txz archive/folderview.plus-2026.04.14.13.txzarchive/folderview.plus-2026.04.11.01.txz renamed to archive/folderview.plus-2026.04.14.13.txz

@@ -6,13 +6,19 @@
 <!ENTITY launch "Settings/FolderViewPlus">
 <!ENTITY plugdir "/usr/local/emhttp/plugins/&name;">
 <!ENTITY pluginURL "https://raw.githubusercontent.com/&github;/dev/folderview.plus.plg">
-<!ENTITY version "2026.04.14.12">
-<!ENTITY md5 "30d83c8cf8ca389091433e0bac0bb10c">
+<!ENTITY version "2026.04.14.13">
+<!ENTITY md5 "07376d047fc962390c36ae7661cd5085">
 ]>
 
 <PLUGIN name="&name;" author="&author;" version="&version;" launch="&launch;" pluginURL="&pluginURL;" icon="folder-icon.png" support="https://forums.unraid.net/topic/197631-plugin-folderview-plus/" min="7.0.0">
     <CHANGES>
 
+###2026.04.14.13
+- UX: Folder editor flows, previews, and bootstrap behavior.
+- UX: Icon picker, bundled icon packs, and custom icon management.
+- Fix: Server endpoints, runtime payloads, and persistence or validation paths.
+
+
 ###2026.04.14.12
 - Fix: Docker support-bundle snapshots, trace storage caps, and rendered-state diagnostics.
 - Fix: Docker runtime rows, folder state, and container interactions.

archive/folderview.plus-2026.04.14.13.txz.sha256

@@ -697,7 +697,7 @@ try {
                     <br>
                     For 3rd-party icon folders, place files under <b>/usr/local/emhttp/plugins/folderview.plus/images/third-party-icons/&lt;folder-name&gt;/</b>.
                     <br>
-                    Uploaded custom icons are saved in <b>/usr/local/emhttp/plugins/folderview.plus/images/custom/</b>.
+                    Uploaded custom icons are saved in <b>/boot/config/plugins/folderview.plus/images/custom/</b> and are restored into the live plugin path automatically after reboot or upgrade.
                     <br>
                     You can click the icon of the Docker/VM to set the folder icon.
                 </p>

folderview.plus.plg

@@ -824,9 +824,10 @@ function diagnosticsBuildCustomIconUsageMap(): array {
     }
 
     function diagnosticsBuildCustomIconStorage(string $privacyMode): array {
-        global $sourceDir;
         $privacyMode = normalizeDiagnosticsPrivacyMode($privacyMode);
-        $directory = "$sourceDir/images/custom";
+        $directory = function_exists('fvplusCustomIconDirPath')
+            ? fvplusCustomIconDirPath()
+            : '/boot/config/plugins/folderview.plus/images/custom';
         $descriptor = diagnosticsPathDescriptor($directory, $privacyMode);
         $extensions = diagnosticsCustomIconExtensions();
         $usageMap = diagnosticsBuildCustomIconUsageMap();

src/folderview.plus/usr/local/emhttp/plugins/folderview.plus/Folder.page

@@ -3872,11 +3872,306 @@ function createFile(string $type): void {
         }
     }
 
+    function fvplusAllowedCustomIconExtensions(): array {
+        return ['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'bmp', 'ico', 'avif'];
+    }
+
     function fvplusCustomIconDirPath(): string {
+        global $configDir;
+        return "$configDir/images/custom";
+    }
+
+    function fvplusCustomIconRuntimeDirPath(): string {
         global $sourceDir;
         return "$sourceDir/images/custom";
     }
 
+    function fvplusCustomIconRepairHintCommand(): string {
+        $dir = fvplusCustomIconDirPath();
+        return "mkdir -p " . escapeshellarg($dir) . " && chmod -R 775 " . escapeshellarg($dir);
+    }
+
+    function fvplusShouldManageCustomIconStorageEntry(string $name, bool $includeMetadata = true): bool {
+        $safeName = trim($name);
+        if ($safeName === '' || $safeName !== basename($safeName) || $safeName === '.' || $safeName === '..') {
+            return false;
+        }
+        if ($includeMetadata && $safeName === '.metadata.json') {
+            return true;
+        }
+        if ($safeName === 'README.txt') {
+            return true;
+        }
+        $extension = strtolower((string)pathinfo($safeName, PATHINFO_EXTENSION));
+        return $extension !== '' && in_array($extension, fvplusAllowedCustomIconExtensions(), true);
+    }
+
+    function fvplusCopyCustomIconStorageFile(string $sourcePath, string $targetPath): bool {
+        $targetDir = dirname($targetPath);
+        if (!is_dir($targetDir)) {
+            @mkdir($targetDir, 0770, true);
+        }
+        if (!@copy($sourcePath, $targetPath)) {
+            return false;
+        }
+        $mtime = (int)@filemtime($sourcePath);
+        if ($mtime > 0) {
+            @touch($targetPath, $mtime);
+        }
+        @chmod($targetPath, 0644);
+        return true;
+    }
+
+    function fvplusListCustomIconStorageEntries(string $directory, bool $includeMetadata = true): array {
+        $entries = [];
+        if (!is_dir($directory)) {
+            return $entries;
+        }
+        foreach ((array)@scandir($directory) as $name) {
+            if (!fvplusShouldManageCustomIconStorageEntry((string)$name, $includeMetadata)) {
+                continue;
+            }
+            $path = "$directory/$name";
+            if (!is_file($path)) {
+                continue;
+            }
+            $entries[(string)$name] = [
+                'path' => $path,
+                'mtime' => max(0, (int)@filemtime($path)),
+                'size' => max(0, (int)@filesize($path))
+            ];
+        }
+        return $entries;
+    }
+
+    function fvplusMigrateRuntimeCustomIconsToPersistent(): array {
+        $runtimeDir = fvplusCustomIconRuntimeDirPath();
+        $storageDir = fvplusCustomIconDirPath();
+        $migratedFiles = [];
+        $migratedMetadata = false;
+        if (!is_dir($runtimeDir) || is_link($runtimeDir)) {
+            return [
+                'migratedFileCount' => 0,
+                'migratedMetadata' => false,
+                'migratedFiles' => []
+            ];
+        }
+        if (!is_dir($storageDir)) {
+            @mkdir($storageDir, 0770, true);
+        }
+        $runtimeEntries = fvplusListCustomIconStorageEntries($runtimeDir, true);
+        foreach ($runtimeEntries as $name => $entry) {
+            if ($name === 'README.txt') {
+                continue;
+            }
+            $sourcePath = (string)($entry['path'] ?? '');
+            if ($sourcePath === '') {
+                continue;
+            }
+            $targetPath = "$storageDir/$name";
+            $shouldCopy = !is_file($targetPath);
+            if (!$shouldCopy) {
+                $targetSize = max(0, (int)@filesize($targetPath));
+                $targetMtime = max(0, (int)@filemtime($targetPath));
+                $shouldCopy = $targetSize !== (int)($entry['size'] ?? 0) || $targetMtime < (int)($entry['mtime'] ?? 0);
+            }
+            if (!$shouldCopy) {
+                continue;
+            }
+            if (!fvplusCopyCustomIconStorageFile($sourcePath, $targetPath)) {
+                continue;
+            }
+            if ($name === '.metadata.json') {
+                $migratedMetadata = true;
+            } else {
+                $migratedFiles[] = $name;
+            }
+        }
+        return [
+            'migratedFileCount' => count($migratedFiles),
+            'migratedMetadata' => $migratedMetadata,
+            'migratedFiles' => array_values($migratedFiles)
+        ];
+    }
+
+    function fvplusRemoveRuntimeCustomIconDirForLink(): bool {
+        $runtimeDir = fvplusCustomIconRuntimeDirPath();
+        if (is_link($runtimeDir)) {
+            return @unlink($runtimeDir);
+        }
+        if (!is_dir($runtimeDir)) {
+            return !file_exists($runtimeDir);
+        }
+        foreach ((array)@scandir($runtimeDir) as $name) {
+            if ($name === '.' || $name === '..') {
+                continue;
+            }
+            if (!fvplusShouldManageCustomIconStorageEntry((string)$name, true)) {
+                return false;
+            }
+            $path = "$runtimeDir/$name";
+            if (!is_file($path) || !@unlink($path)) {
+                return false;
+            }
+        }
+        return @rmdir($runtimeDir);
+    }
+
+    function fvplusMirrorPersistentCustomIconsToRuntime(): array {
+        $storageDir = fvplusCustomIconDirPath();
+        $runtimeDir = fvplusCustomIconRuntimeDirPath();
+        $copied = 0;
+        $pruned = 0;
+        $runtimeParent = dirname($runtimeDir);
+        if (!is_dir($runtimeParent)) {
+            @mkdir($runtimeParent, 0770, true);
+        }
+        if (!is_dir($runtimeDir)) {
+            @mkdir($runtimeDir, 0770, true);
+        }
+        if (!is_dir($runtimeDir)) {
+            return [
+                'copiedCount' => 0,
+                'prunedCount' => 0,
+                'ready' => false
+            ];
+        }
+
+        $storageEntries = fvplusListCustomIconStorageEntries($storageDir, false);
+        $runtimeEntries = fvplusListCustomIconStorageEntries($runtimeDir, false);
+
+        foreach ($storageEntries as $name => $entry) {
+            $sourcePath = (string)($entry['path'] ?? '');
+            $targetPath = "$runtimeDir/$name";
+            $targetExists = is_file($targetPath);
+            $targetSize = $targetExists ? max(0, (int)@filesize($targetPath)) : -1;
+            $targetMtime = $targetExists ? max(0, (int)@filemtime($targetPath)) : -1;
+            if ($targetExists && $targetSize === (int)($entry['size'] ?? 0) && $targetMtime >= (int)($entry['mtime'] ?? 0)) {
+                continue;
+            }
+            if (fvplusCopyCustomIconStorageFile($sourcePath, $targetPath)) {
+                $copied++;
+            }
+        }
+
+        foreach ($runtimeEntries as $name => $_entry) {
+            if (isset($storageEntries[$name])) {
+                continue;
+            }
+            if (@unlink("$runtimeDir/$name")) {
+                $pruned++;
+            }
+        }
+
+        return [
+            'copiedCount' => $copied,
+            'prunedCount' => $pruned,
+            'ready' => is_dir($runtimeDir) && is_readable($runtimeDir)
+        ];
+    }
+
+    function fvplusEnsureCustomIconStorageReady(bool $requireWritable = false): array {
+        $storageDir = fvplusCustomIconDirPath();
+        $runtimeDir = fvplusCustomIconRuntimeDirPath();
+        $storageParent = dirname($storageDir);
+        $runtimeParent = dirname($runtimeDir);
+        $repairAttempted = false;
+
+        if (!is_dir($storageParent)) {
+            $repairAttempted = true;
+            @mkdir($storageParent, 0770, true);
+        }
+        if (!is_dir($storageDir)) {
+            $repairAttempted = true;
+            @mkdir($storageDir, 0770, true);
+        }
+        if (is_dir($storageDir) && !is_writable($storageDir)) {
+            $repairAttempted = true;
+            @chmod($storageDir, 0770);
+        }
+
+        $storageExists = is_dir($storageDir);
+        $storageWritable = $storageExists && is_writable($storageDir);
+        if (!$storageExists) {
+            throw new RuntimeException('Custom icon directory does not exist. Run: ' . fvplusCustomIconRepairHintCommand());
+        }
+        if ($requireWritable && !$storageWritable) {
+            throw new RuntimeException('Custom icon directory is not writable. Run: ' . fvplusCustomIconRepairHintCommand());
+        }
+
+        $migration = fvplusMigrateRuntimeCustomIconsToPersistent();
+        $repairAttempted = $repairAttempted
+            || ((int)($migration['migratedFileCount'] ?? 0) > 0)
+            || (($migration['migratedMetadata'] ?? false) === true);
+
+        $publicMode = 'missing';
+        $publicReady = false;
+        if (is_link($runtimeDir)) {
+            $runtimeResolved = @realpath($runtimeDir);
+            $storageResolved = @realpath($storageDir);
+            if (is_string($runtimeResolved) && $runtimeResolved !== '' && $runtimeResolved === $storageResolved) {
+                $publicMode = 'symlink';
+                $publicReady = true;
+            } else {
+                $repairAttempted = true;
+                @unlink($runtimeDir);
+            }
+        }
+
+        $symlinkCreated = false;
+        if (!$publicReady && function_exists('symlink')) {
+            if (!is_dir($runtimeParent)) {
+                $repairAttempted = true;
+                @mkdir($runtimeParent, 0770, true);
+            }
+            if (!file_exists($runtimeDir) || fvplusRemoveRuntimeCustomIconDirForLink()) {
+                $repairAttempted = true;
+                $symlinkCreated = @symlink($storageDir, $runtimeDir);
+            }
+            if ($symlinkCreated) {
+                $publicMode = 'symlink';
+                $publicReady = true;
+            }
+        }
+
+        $mirror = ['copiedCount' => 0, 'prunedCount' => 0, 'ready' => false];
+        if (!$publicReady) {
+            $repairAttempted = true;
+            $mirror = fvplusMirrorPersistentCustomIconsToRuntime();
+            $publicMode = 'mirror';
+            $publicReady = ($mirror['ready'] ?? false) === true;
+        }
+
+        return [
+            'storageDir' => $storageDir,
+            'runtimeDir' => $runtimeDir,
+            'storageExists' => $storageExists,
+            'storageWritable' => $storageWritable,
+            'publicMode' => $publicMode,
+            'publicReady' => $publicReady,
+            'repairAttempted' => $repairAttempted,
+            'repairSucceeded' => $storageExists && (!$requireWritable || $storageWritable) && $publicReady,
+            'repairHint' => fvplusCustomIconRepairHintCommand(),
+            'migratedFileCount' => (int)($migration['migratedFileCount'] ?? 0),
+            'migratedMetadata' => ($migration['migratedMetadata'] ?? false) === true,
+            'mirrorCopiedCount' => (int)($mirror['copiedCount'] ?? 0),
+            'mirrorPrunedCount' => (int)($mirror['prunedCount'] ?? 0)
+        ];
+    }
+
+    function fvplusBootstrapCustomIconStorage(): void {
+        static $bootstrapped = false;
+        if ($bootstrapped) {
+            return;
+        }
+        $bootstrapped = true;
+        try {
+            fvplusEnsureCustomIconStorageReady(false);
+        } catch (Throwable $_error) {
+            // Keep runtime bootstrap non-fatal; diagnostics will surface path issues.
+        }
+    }
+
     function fvplusRepairMissingCustomIconReferences(): array {
         $customIconDir = fvplusCustomIconDirPath();
         $existingIcons = [];
@@ -4049,13 +4344,13 @@ function repairPluginPaths(): array {
                 $created[] = $path;
             }
         }
-        $customIconDir = fvplusCustomIconDirPath();
-        if (!is_dir($customIconDir)) {
-            @mkdir($customIconDir, 0770, true);
-            $created[] = $customIconDir;
-        }
-        if (is_dir($customIconDir)) {
-            @chmod($customIconDir, 0770);
+        $customIconHealth = fvplusEnsureCustomIconStorageReady(false);
+        $customIconDir = (string)($customIconHealth['storageDir'] ?? fvplusCustomIconDirPath());
+        $customIconRuntimeDir = (string)($customIconHealth['runtimeDir'] ?? fvplusCustomIconRuntimeDirPath());
+        foreach ([$customIconDir, dirname($customIconDir)] as $path) {
+            if (is_string($path) && $path !== '' && !in_array($path, $created, true) && file_exists($path)) {
+                $created[] = $path;
+            }
         }
         foreach (FVPLUS_ALLOWED_TYPES as $type) {
             createFile($type);
@@ -4064,10 +4359,13 @@ function repairPluginPaths(): array {
         return [
             'createdPaths' => $created,
             'configDir' => $configDir,
-            'customIconDir' => $customIconDir
+            'customIconDir' => $customIconDir,
+            'customIconRuntimeDir' => $customIconRuntimeDir
         ];
     }
 
+    fvplusBootstrapCustomIconStorage();
+
     function getDockerTemplateCachePath(): string {
         return fv3_cache_root() . '/docker-template-index/cache.json';
     }