Add graceful failure handling and error banner for dashboard API calls

- Extract _normalizeArray helper to safely unwrap API responses that may
  return plain arrays or {data: [...]} / {entity_types: [...]} objects
- Apply normalization to /entity-types, /entities, and /maps endpoints
- Track load errors per tab and surface them in a visible error banner
  with a Retry button, so users see what failed instead of empty tabs

https://claude.ai/code/session_01FcPMoRaH9FZsmU9JQ1eALo

Author: claude

scripts/sync-dashboard.mjs

@@ -109,6 +109,28 @@ export class SyncDashboard extends HandlebarsApplicationMixin(ApplicationV2) {
   // Data
   // ---------------------------------------------------------------------------
 
+  /**
+   * Normalize an API response to an array.
+   * Chronicle endpoints may return a plain array or an object wrapping
+   * the array under common keys like `data`, `entity_types`, `entities`,
+   * `maps`, etc.  This helper unwraps whichever shape we get.
+   * @param {*} raw - The raw parsed JSON from the API.
+   * @param {...string} keys - Object keys to try (in order) if raw is not an array.
+   * @returns {Array}
+   * @private
+   */
+  _normalizeArray(raw, ...keys) {
+    if (Array.isArray(raw)) return raw;
+    if (raw && typeof raw === 'object') {
+      for (const key of keys) {
+        if (Array.isArray(raw[key])) return raw[key];
+      }
+      // Last resort: try the generic `data` wrapper.
+      if (Array.isArray(raw.data)) return raw.data;
+    }
+    return [];
+  }
+
   /** @override */
   async _prepareContext(options = {}) {
     if (!this._syncManager || !this.api) {
@@ -117,6 +139,7 @@ export class SyncDashboard extends HandlebarsApplicationMixin(ApplicationV2) {
 
     this._loading = true;
     const exclusions = this._getExclusions();
+    const loadErrors = [];
 
     // Build entity tab data.
     let entityGroups = [];
@@ -126,6 +149,7 @@ export class SyncDashboard extends HandlebarsApplicationMixin(ApplicationV2) {
       foundryOnlyJournals = this._getFoundryOnlyJournals();
     } catch (err) {
       console.error('Chronicle Dashboard: Failed to load entities', err);
+      loadErrors.push({ tab: 'entities', message: err.message || 'Failed to load entities' });
     }
 
     // Build map tab data.
@@ -134,6 +158,7 @@ export class SyncDashboard extends HandlebarsApplicationMixin(ApplicationV2) {
       mapData = await this._buildMapData();
     } catch (err) {
       console.error('Chronicle Dashboard: Failed to load maps', err);
+      loadErrors.push({ tab: 'maps', message: err.message || 'Failed to load maps' });
     }
 
     // Build shops tab data.
@@ -142,6 +167,7 @@ export class SyncDashboard extends HandlebarsApplicationMixin(ApplicationV2) {
       shopData = await this._buildShopData();
     } catch (err) {
       console.error('Chronicle Dashboard: Failed to load shops', err);
+      loadErrors.push({ tab: 'shops', message: err.message || 'Failed to load shops' });
     }
 
     // Build calendar tab data.
@@ -150,6 +176,7 @@ export class SyncDashboard extends HandlebarsApplicationMixin(ApplicationV2) {
       calendarData = await this._buildCalendarData();
     } catch (err) {
       console.error('Chronicle Dashboard: Failed to load calendar', err);
+      loadErrors.push({ tab: 'calendar', message: err.message || 'Failed to load calendar' });
     }
 
     // Build status tab data.
@@ -168,6 +195,8 @@ export class SyncDashboard extends HandlebarsApplicationMixin(ApplicationV2) {
       loading: false,
       searchFilter: this._searchFilter,
       activeTab: this._activeTab,
+      loadErrors,
+      hasLoadErrors: loadErrors.length > 0,
 
       // Config tab.
       config: configData,
@@ -209,7 +238,7 @@ export class SyncDashboard extends HandlebarsApplicationMixin(ApplicationV2) {
     // Fetch entity types from Chronicle.
     if (!this._cache.entityTypes) {
       const raw = await this.api.get('/entity-types');
-      this._cache.entityTypes = Array.isArray(raw) ? raw : (raw?.data || raw?.entity_types || []);
+      this._cache.entityTypes = this._normalizeArray(raw, 'entity_types');
     }
     const types = this._cache.entityTypes;
 
@@ -220,8 +249,8 @@ export class SyncDashboard extends HandlebarsApplicationMixin(ApplicationV2) {
       let hasMore = true;
       while (hasMore && page <= 5) {
         const result = await this.api.get(`/entities?per_page=100&page=${page}`);
-        const entities = result?.entities || result || [];
-        if (Array.isArray(entities) && entities.length > 0) {
+        const entities = this._normalizeArray(result, 'entities');
+        if (entities.length > 0) {
           allEntities.push(...entities);
           hasMore = entities.length === 100;
           page++;
@@ -346,9 +375,10 @@ export class SyncDashboard extends HandlebarsApplicationMixin(ApplicationV2) {
   async _buildMapData() {
     // Fetch Chronicle maps.
     if (!this._cache.maps) {
-      this._cache.maps = await this.api.get('/maps').catch(() => []);
+      const raw = await this.api.get('/maps').catch(() => []);
+      this._cache.maps = this._normalizeArray(raw, 'maps');
     }
-    const chronicles = this._cache.maps || [];
+    const chronicles = this._cache.maps;
 
     // Index Foundry scenes by linked mapId.
     const scenesByMapId = new Map();
@@ -397,7 +427,7 @@ export class SyncDashboard extends HandlebarsApplicationMixin(ApplicationV2) {
     // Ensure entity types are cached.
     if (!this._cache.entityTypes) {
       const raw = await this.api.get('/entity-types');
-      this._cache.entityTypes = Array.isArray(raw) ? raw : (raw?.data || raw?.entity_types || []);
+      this._cache.entityTypes = this._normalizeArray(raw, 'entity_types');
     }
     const types = this._cache.entityTypes;
 

styles/chronicle-sync.css

@@ -228,6 +228,27 @@
   border-bottom: 1px solid rgba(96, 165, 250, 0.15);
 }
 
+/* Load error banner */
+.dashboard-load-errors {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 4px;
+  padding: 6px 10px;
+  font-size: 12px;
+  color: #fca5a5;
+  background: rgba(248, 113, 113, 0.1);
+  border-bottom: 1px solid rgba(248, 113, 113, 0.25);
+}
+
+.dashboard-load-errors i {
+  margin-right: 4px;
+}
+
+.load-error-item {
+  font-weight: 600;
+}
+
 /* Tab navigation */
 .dashboard-tabs {
   display: flex;

templates/sync-dashboard.hbs

@@ -43,6 +43,20 @@
     </a>
   </nav>
 
+  {{!-- Load error banner --}}
+  {{#if hasLoadErrors}}
+  <div class="dashboard-load-errors">
+    <i class="fa-solid fa-triangle-exclamation"></i>
+    Some data failed to load from Chronicle:
+    {{#each loadErrors}}
+    <span class="load-error-item">{{tab}}{{#unless @last}},{{/unless}}</span>
+    {{/each}}
+    <button type="button" data-action="refresh" class="dashboard-btn btn-xs" title="Retry">
+      <i class="fa-solid fa-arrows-rotate"></i> Retry
+    </button>
+  </div>
+  {{/if}}
+
   {{!-- Tab content --}}
   <section class="dashboard-content">