Fix fresh-install blank settings and add startup guards

Author: alexphillips-dev

archive/folderview.plus-2026.03.08.04.txz

@@ -0,0 +1 @@
+66f91bc29c12a9bf13ce50b4cc549abb11a3d847b3204e95c0f819cdb9055cec  folderview.plus-2026.03.08.04.txz

archive/folderview.plus-2026.03.08.04.txz.sha256

@@ -6,13 +6,24 @@
 <!ENTITY launch "Settings/FolderViewPlus">
 <!ENTITY plugdir "/usr/local/emhttp/plugins/&name;">
 <!ENTITY pluginURL "https://raw.githubusercontent.com/&github;/main/folderview.plus.plg">
-<!ENTITY version "2026.03.08.02">
-<!ENTITY md5 "2b970f8206b92b1608b6e6dfb4cdfb3d">
+<!ENTITY version "2026.03.08.04">
+<!ENTITY md5 "2e71f08fbeb23ce32587c25abd680b71">
 ]>
 
 <PLUGIN name="&name;" author="&author;" version="&version;" launch="&launch;" pluginURL="&pluginURL;" icon="folder-icon.png" support="https://github.com/alexphillips-dev/FolderView-Plus/issues" min="7.0.0">
     <CHANGES>
 
+###2026.03.08.04
+- Bug fix: resolved a first-install regression that could render the Settings page blank.
+- Reliability: added startup safeguards so basic Docker/VM sections stay visible even if initial API calls fail.
+- Stability: refresh now falls back to empty/default data on first-load fetch hiccups instead of aborting UI rendering.
+- Regression guard: added tests to prevent future blank-first-run settings regressions.
+
+
+###2026.03.08.03
+- Maintenance: automated release metadata update.
+
+
 ###2026.03.08.02
 - UI/UX fix: advanced side-by-side modules now use adaptive panel sizing instead of forcing full-height blocks.
 - Layout fix: advanced module grids now align cards to the top so shorter cards no longer stretch and show unnecessary blank space.

folderview.plus.plg

@@ -687,7 +687,31 @@ const getSectionSearchHaystack = (section) => section.nodes
     .join(' ')
     .toLowerCase();
 
-const isBasicWorkspaceSection = (section) => BASIC_WORKSPACE_SECTION_KEYS.has(String(section?.key || ''));
+const sectionContainsSelector = (section, selector) => {
+    const nodes = Array.isArray(section?.nodes) ? section.nodes : [];
+    for (const node of nodes) {
+        if (!(node instanceof Element)) {
+            continue;
+        }
+        if (typeof node.matches === 'function' && node.matches(selector)) {
+            return true;
+        }
+        if (typeof node.querySelector === 'function' && node.querySelector(selector)) {
+            return true;
+        }
+    }
+    return false;
+};
+
+const isBasicWorkspaceSection = (section) => {
+    const key = String(section?.key || '').trim().toLowerCase();
+    if (BASIC_WORKSPACE_SECTION_KEYS.has(key)) {
+        return true;
+    }
+    return sectionContainsSelector(section, 'tbody#docker, tbody#vms');
+};
+
+const getBasicWorkspaceSections = () => settingsUiState.sections.filter((section) => isBasicWorkspaceSection(section));
 
 const getVisibleSections = () => settingsUiState.sections.filter((section) => {
     const modeVisible = settingsUiState.mode === 'advanced'
@@ -811,6 +835,11 @@ const toggleAdvancedSectionByKey = (sectionKey) => {
 
 const applySettingsSectionVisibility = () => {
     const visibleKeys = new Set(getVisibleSections().map((section) => section.key));
+    if (!visibleKeys.size && settingsUiState.mode === 'basic' && !settingsUiState.query) {
+        for (const section of getBasicWorkspaceSections()) {
+            visibleKeys.add(section.key);
+        }
+    }
     const forceExpandForQuery = Boolean(settingsUiState.query);
 
     for (const section of settingsUiState.sections) {
@@ -6889,17 +6918,17 @@ const renderPerformanceDiagnostics = () => {
 const refreshType = async (type) => {
     const startedAt = perfNowMs();
     const [folders, prefs, info] = await Promise.all([
-        fetchFolders(type),
-        fetchPrefs(type),
+        fetchFolders(type).catch(() => ({})),
+        fetchPrefs(type).catch(() => (utils.normalizePrefs({}))),
         fetchTypeInfo(type).catch(() => ({}))
     ]);
 
     prefsByType[type] = utils.normalizePrefs(prefs || {});
     infoByType[type] = info && typeof info === 'object' ? info : {};
-    setTypeFolders(type, folders);
+    setTypeFolders(type, utils.normalizeFolderMap(folders || {}));
     renderTable(type);
     recordPerformanceDiagnosticsSample('refresh', type, perfNowMs() - startedAt, {
-        folderCount: Object.keys(folders || {}).length,
+        folderCount: Object.keys(utils.normalizeFolderMap(folders || {})).length,
         infoCount: Object.keys(info || {}).length
     });
 };
@@ -8814,7 +8843,13 @@ window.setSettingsMode = setSettingsMode;
         initOverflowGuard();
         renderPerformanceDiagnostics();
         await fetchPluginVersion();
-        await refreshAll();
+        try {
+            await refreshAll();
+        } catch (error) {
+            // Keep initial settings sections visible on first-load API hiccups.
+            refreshSettingsUx();
+            showError('Initial data load failed', error);
+        }
         const serverMode = getServerSettingsMode();
         if (serverMode) {
             settingsUiState.mode = serverMode;
@@ -8841,6 +8876,11 @@ window.setSettingsMode = setSettingsMode;
         }
         settingsUiState.initialized = true;
     } catch (error) {
+        try {
+            refreshSettingsUx();
+        } catch (_ignored) {
+            // Best effort only; do not shadow the original initialization error.
+        }
         showError('Initialization failed', error);
     }
 })();

src/folderview.plus/usr/local/emhttp/plugins/folderview.plus/scripts/folderviewplus.js

@@ -79,3 +79,12 @@ test('basic toolbar actions reuse compact progress overlay for docker and vm flo
     assert.match(script, /openImportApplyProgressDialog\(resolvedType, progressTotal\);/);
     assert.match(script, /setProgress\(0, 'Creating safety backup\.\.\.'\);/);
 });
+
+test('fresh install guard keeps basic Docker/VM sections visible on startup failures', () => {
+    assert.match(script, /const sectionContainsSelector = \(section, selector\) =>/);
+    assert.match(script, /return sectionContainsSelector\(section, 'tbody#docker, tbody#vms'\);/);
+    assert.match(script, /if \(!visibleKeys\.size && settingsUiState\.mode === 'basic' && !settingsUiState\.query\) \{/);
+    assert.match(script, /for \(const section of getBasicWorkspaceSections\(\)\) \{/);
+    assert.match(script, /visibleKeys\.add\(section\.key\);/);
+    assert.match(script, /showError\('Initial data load failed', error\);/);
+});