@openmrs/esm-dynamic-loading 10.0.1-pre.5251 → 10.0.1-pre.5255

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-[0] Successfully compiled: 5 files with swc (250.51ms)
+[0] Successfully compiled: 5 files with swc (229.8ms)
 [0] swc --strip-leading-paths src -d dist exited with code 0
 [1] tsc --project tsconfig.build.json exited with code 0

package/dist/import-maps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-maps.d.ts","sourceRoot":"","sources":["../src/import-maps.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AA2EtD;;;GAGG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,SAAS,CAAC,CAO5D;AAED;;GAEG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,SAAS,CAAC,CAEjE;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,SAAS,CAAC,CAMlE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAmB5E;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,IAAI,MAAM,EAAE,CAiBxD;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAKvE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAWpE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAiB1D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAmB9C;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAgB1D;AAaD,wBAAgB,uBAAuB,SAWtC"}
+{"version":3,"file":"import-maps.d.ts","sourceRoot":"","sources":["../src/import-maps.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAkGtD;;;GAGG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,SAAS,CAAC,CAO5D;AAED;;GAEG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,SAAS,CAAC,CAEjE;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,SAAS,CAAC,CAMlE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAmB5E;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,IAAI,MAAM,EAAE,CAiBxD;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAKvE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAWpE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAiB1D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAmB9C;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAgB1D;AAaD,wBAAgB,uBAAuB,SAWtC"}

package/dist/import-maps.js

@@ -6,27 +6,50 @@ let devMode = false;
 // Snapshot of overrides at setup time (matches import-map-overrides library behavior:
 // getCurrentPageMap returns the overrides as they were when the page loaded).
 let initialOverrideSnapshot = null;
+// Memoizes the base map so that the import map is fetched at most once per page load.
+let baseMapPromise = null;
 /**
  * Reads all `<script type="systemjs-importmap">` tags from the DOM and merges
  * them into a single {@link ImportMap}. Tags with a `src` attribute are fetched;
  * inline tags have their `textContent` parsed as JSON.
+ *
+ * A read in which every tag was parsed successfully is cached and reused by all later
+ * callers. A read that lost one or more tags to an error is returned as-is but not cached, so
+ * that a transient network failure doesn't leave the page with a permanently incomplete map.
  */ async function readBaseMap() {
+    baseMapPromise ?? (baseMapPromise = loadBaseMap().then(({ map, complete })=>{
+        if (!complete) {
+            baseMapPromise = null;
+        }
+        return map;
+    }));
+    return baseMapPromise;
+}
+async function loadBaseMap() {
     const scripts = document.querySelectorAll('script[type="systemjs-importmap"]');
     const maps = [];
+    let complete = true;
     for(let i = 0; i < scripts.length; i++){
         const script = scripts[i];
         try {
             if (script.src) {
                 const response = await fetch(script.src);
+                if (!response.ok) {
+                    throw new Error(`Request for ${script.src} returned ${response.status} ${response.statusText}`);
+                }
                 maps.push(await response.json());
             } else if (script.textContent) {
                 maps.push(JSON.parse(script.textContent));
             }
         } catch (e) {
+            complete = false;
             console.warn(`[import-maps] Failed to parse import map from script tag at index ${i}`, e);
         }
     }
-    return mergeMaps(maps);
+    return {
+        map: mergeMaps(maps),
+        complete
+    };
 }
 function mergeMaps(maps) {
     const merged = {

package/dist/route-maps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-maps.d.ts","sourceRoot":"","sources":["../src/route-maps.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,OAAO,EAAuC,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA+GtH;;;GAGG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,aAAa,CAAC,CAOjE;AAED;;GAEG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,aAAa,CAAC,CAEpE;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,aAAa,CAAC,CAMrE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoB/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,GAAG,QAkC9F;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,QAYxD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,SAmBrC;AAaD,wBAAgB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAgBtD"}
+{"version":3,"file":"route-maps.d.ts","sourceRoot":"","sources":["../src/route-maps.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,OAAO,EAAuC,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAuItH;;;GAGG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,aAAa,CAAC,CAOjE;AAED;;GAEG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,aAAa,CAAC,CAEpE;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,aAAa,CAAC,CAMrE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoB/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,GAAG,QAkC9F;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,QAYxD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,SAmBrC;AAaD,wBAAgB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAgBtD"}

package/dist/route-maps.js

@@ -6,19 +6,39 @@ let devMode = false;
 // Snapshot of overrides at setup time (mirrors the import-map-overrides pattern:
 // getCurrentRouteMap returns the overrides as they were when the page loaded).
 let initialOverrideSnapshot = null;
+// Memoizes the base map so that the routes registry is fetched at most once per page load.
+let baseMapPromise = null;
 /**
  * Reads all `<script type="openmrs-routes">` tags from the DOM and merges
  * them into a single {@link OpenmrsRoutes} object. Tags with a `src` attribute
  * are fetched; inline tags have their `textContent` parsed as JSON.
+ *
+ * A read in which no tag threw is cached and reused by all later callers. A read that lost a
+ * tag to an error is returned as-is but not cached, so that a transient network failure doesn't
+ * leave the page with a permanently incomplete map. A tag that loads but fails validation is
+ * dropped without invalidating the cache, since re-reading it would only fail the same way.
  */ async function readBaseMap() {
+    baseMapPromise ?? (baseMapPromise = loadBaseMap().then(({ map, complete })=>{
+        if (!complete) {
+            baseMapPromise = null;
+        }
+        return map;
+    }));
+    return baseMapPromise;
+}
+async function loadBaseMap() {
     const scripts = document.querySelectorAll("script[type='openmrs-routes']");
     const maps = [];
+    let complete = true;
     for(let i = 0; i < scripts.length; i++){
         const script = scripts[i];
         try {
             let parsed;
             if (script.src) {
                 const response = await fetch(script.src);
+                if (!response.ok) {
+                    throw new Error(`Request for ${script.src} returned ${response.status} ${response.statusText}`);
+                }
                 parsed = await response.json();
             } else if (script.textContent) {
                 parsed = JSON.parse(script.textContent);
@@ -27,10 +47,14 @@ let initialOverrideSnapshot = null;
                 maps.push(parsed);
             }
         } catch (e) {
+            complete = false;
             console.warn(`[route-maps] Failed to parse routes from script tag at index ${i}`, e);
         }
     }
-    return mergeRouteMaps(maps);
+    return {
+        map: mergeRouteMaps(maps),
+        complete
+    };
 }
 function mergeRouteMaps(maps) {
     const merged = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-dynamic-loading",
-  "version": "10.0.1-pre.5251",
+  "version": "10.0.1-pre.5255",
   "license": "MPL-2.0",
   "description": "Utilities for dynamically loading code in OpenMRS",
   "type": "module",
@@ -25,6 +25,7 @@
     "test": "cross-env TZ=UTC vitest run --passWithNoTests",
     "test:watch": "cross-env TZ=UTC vitest watch --passWithNoTests",
     "build": "rimraf dist && concurrently \"swc --strip-leading-paths src -d dist\" \"tsc --project tsconfig.build.json\"",
+    "clean": "git clean -fdX -- dist",
     "build:development": "rimraf dist && concurrently \"swc --strip-leading-paths src -d dist\" \"tsc --project tsconfig.build.json\"",
     "typescript": "tsc --project tsconfig.build.json",
     "lint": "eslint src",
@@ -53,12 +54,12 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@openmrs/esm-globals": "^10.0.1-pre.5251",
-    "@openmrs/esm-translations": "^10.0.1-pre.5251"
+    "@openmrs/esm-globals": "^10.0.1-pre.5255",
+    "@openmrs/esm-translations": "^10.0.1-pre.5255"
   },
   "devDependencies": {
-    "@openmrs/esm-globals": "10.0.1-pre.5251",
-    "@openmrs/esm-translations": "10.0.1-pre.5251",
+    "@openmrs/esm-globals": "10.0.1-pre.5255",
+    "@openmrs/esm-translations": "10.0.1-pre.5255",
     "@swc/cli": "0.8.1",
     "@swc/core": "1.15.21",
     "@vitest/coverage-v8": "^4.1.2",

package/src/import-maps.test.ts

@@ -334,6 +334,94 @@ describe('import-maps', () => {
     });
   });
 
+  describe('remote import map caching', () => {
+    function setRemoteImportMap(src = 'http://localhost/importmap.json') {
+      const script = document.createElement('script');
+      script.type = 'systemjs-importmap';
+      Object.defineProperty(script, 'src', { value: src, writable: false });
+      document.head.appendChild(script);
+    }
+
+    beforeEach(() => {
+      (window as any).spaEnv = 'production';
+      vi.resetModules();
+    });
+
+    it('fetches the import map with the default credentials mode so the preloaded response is reused', async () => {
+      setRemoteImportMap();
+      fetchMock.mockResponse(JSON.stringify({ imports: { '@openmrs/esm-remote': '/remote.js' } }));
+
+      const { setupImportMapOverrides, getCurrentPageMap } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      await getCurrentPageMap();
+
+      // `crossorigin="anonymous"` on the preload link gives it a `same-origin` credentials mode,
+      // which is also `fetch()`'s default; passing anything else here misses the preload cache.
+      expect(fetchMock).toHaveBeenCalledWith('http://localhost/importmap.json');
+    });
+
+    it('fetches the import map only once across repeated reads', async () => {
+      setRemoteImportMap();
+      fetchMock.mockResponse(JSON.stringify({ imports: { '@openmrs/esm-remote': '/remote.js' } }));
+
+      const { setupImportMapOverrides, getCurrentPageMap, getImportMapDefaultMap, getImportMapNextPageMap } =
+        await import('./import-maps');
+      setupImportMapOverrides();
+
+      const [first, second, third] = await Promise.all([
+        getCurrentPageMap(),
+        getImportMapDefaultMap(),
+        getImportMapNextPageMap(),
+      ]);
+      const fourth = await getCurrentPageMap();
+
+      for (const map of [first, second, third, fourth]) {
+        expect(map.imports['@openmrs/esm-remote']).toBe('/remote.js');
+      }
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not cache a map whose fetch failed', async () => {
+      setRemoteImportMap();
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      fetchMock.mockRejectOnce(new Error('network is down'));
+      fetchMock.mockResponse(JSON.stringify({ imports: { '@openmrs/esm-remote': '/remote.js' } }));
+
+      const { setupImportMapOverrides, getCurrentPageMap } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      const failed = await getCurrentPageMap();
+      expect(failed.imports).toEqual({});
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to parse import map'), expect.anything());
+
+      // The failed read was not cached, so the next call retries and succeeds
+      const retried = await getCurrentPageMap();
+      expect(retried.imports['@openmrs/esm-remote']).toBe('/remote.js');
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('does not cache a map whose fetch returned an error status', async () => {
+      setRemoteImportMap();
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      fetchMock.mockResponseOnce(JSON.stringify({ error: 'service unavailable' }), { status: 503 });
+      fetchMock.mockResponse(JSON.stringify({ imports: { '@openmrs/esm-remote': '/remote.js' } }));
+
+      const { setupImportMapOverrides, getCurrentPageMap } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      const failed = await getCurrentPageMap();
+      expect(failed.imports).toEqual({});
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to parse import map'), expect.anything());
+
+      const retried = await getCurrentPageMap();
+      expect(retried.imports['@openmrs/esm-remote']).toBe('/remote.js');
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+  });
+
   describe('error handling', () => {
     it('skips malformed inline import map script tags', async () => {
       (window as any).spaEnv = 'production';

package/src/import-maps.ts

@@ -12,30 +12,53 @@ let devMode = false;
 // getCurrentPageMap returns the overrides as they were when the page loaded).
 let initialOverrideSnapshot: ImportMap | null = null;
 
+// Memoizes the base map so that the import map is fetched at most once per page load.
+let baseMapPromise: Promise<ImportMap> | null = null;
+
 /**
  * Reads all `<script type="systemjs-importmap">` tags from the DOM and merges
  * them into a single {@link ImportMap}. Tags with a `src` attribute are fetched;
  * inline tags have their `textContent` parsed as JSON.
+ *
+ * A read in which every tag was parsed successfully is cached and reused by all later
+ * callers. A read that lost one or more tags to an error is returned as-is but not cached, so
+ * that a transient network failure doesn't leave the page with a permanently incomplete map.
  */
 async function readBaseMap(): Promise<ImportMap> {
+  baseMapPromise ??= loadBaseMap().then(({ map, complete }) => {
+    if (!complete) {
+      baseMapPromise = null;
+    }
+    return map;
+  });
+
+  return baseMapPromise;
+}
+
+async function loadBaseMap(): Promise<{ map: ImportMap; complete: boolean }> {
   const scripts = document.querySelectorAll<HTMLScriptElement>('script[type="systemjs-importmap"]');
   const maps: ImportMap[] = [];
+  let complete = true;
 
   for (let i = 0; i < scripts.length; i++) {
     const script = scripts[i];
     try {
       if (script.src) {
         const response = await fetch(script.src);
+        if (!response.ok) {
+          throw new Error(`Request for ${script.src} returned ${response.status} ${response.statusText}`);
+        }
         maps.push(await response.json());
       } else if (script.textContent) {
         maps.push(JSON.parse(script.textContent));
       }
     } catch (e) {
+      complete = false;
       console.warn(`[import-maps] Failed to parse import map from script tag at index ${i}`, e);
     }
   }
 
-  return mergeMaps(maps);
+  return { map: mergeMaps(maps), complete };
 }
 
 function mergeMaps(maps: ImportMap[]): ImportMap {

package/src/route-maps.test.ts

@@ -375,6 +375,94 @@ describe('route-maps', () => {
     });
   });
 
+  describe('remote route map caching', () => {
+    function setRemoteRouteMap(src = 'http://localhost/routes.registry.json') {
+      const script = document.createElement('script');
+      script.type = 'openmrs-routes';
+      Object.defineProperty(script, 'src', { value: src, writable: false });
+      document.head.appendChild(script);
+    }
+
+    beforeEach(() => {
+      (window as any).spaEnv = 'production';
+      vi.resetModules();
+    });
+
+    it('fetches the routes registry only once across repeated reads', async () => {
+      setRemoteRouteMap();
+      fetchMock.mockResponse(JSON.stringify({ routes: { '@openmrs/esm-remote': { pages: [] } } }));
+
+      const { setupRouteMapOverrides, getCurrentRouteMap, getRouteMapDefaultMap, getRouteMapNextPageMap } =
+        await import('./route-maps');
+      await setupRouteMapOverrides();
+
+      const [first, second, third] = await Promise.all([
+        getCurrentRouteMap(),
+        getRouteMapDefaultMap(),
+        getRouteMapNextPageMap(),
+      ]);
+      const fourth = await getCurrentRouteMap();
+
+      for (const map of [first, second, third, fourth]) {
+        expect(map.routes['@openmrs/esm-remote']).toEqual({ pages: [] });
+      }
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not cache a map whose fetch failed', async () => {
+      setRemoteRouteMap();
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      fetchMock.mockRejectOnce(new Error('network is down'));
+      fetchMock.mockResponse(JSON.stringify({ routes: { '@openmrs/esm-remote': { pages: [] } } }));
+
+      const { setupRouteMapOverrides, getCurrentRouteMap } = await import('./route-maps');
+      await setupRouteMapOverrides();
+
+      const failed = await getCurrentRouteMap();
+      expect(Object.keys(failed.routes)).toHaveLength(0);
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to parse routes'), expect.anything());
+
+      // The failed read was not cached, so the next call retries and succeeds
+      const retried = await getCurrentRouteMap();
+      expect(retried.routes['@openmrs/esm-remote']).toEqual({ pages: [] });
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('does not cache a map whose fetch returned an error status', async () => {
+      setRemoteRouteMap();
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      fetchMock.mockResponseOnce(JSON.stringify({ error: 'service unavailable' }), { status: 503 });
+      fetchMock.mockResponse(JSON.stringify({ routes: { '@openmrs/esm-remote': { pages: [] } } }));
+
+      const { setupRouteMapOverrides, getCurrentRouteMap } = await import('./route-maps');
+      await setupRouteMapOverrides();
+
+      const failed = await getCurrentRouteMap();
+      expect(Object.keys(failed.routes)).toHaveLength(0);
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to parse routes'), expect.anything());
+
+      const retried = await getCurrentRouteMap();
+      expect(retried.routes['@openmrs/esm-remote']).toEqual({ pages: [] });
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('caches a map whose tags loaded but failed validation', async () => {
+      setRemoteRouteMap();
+      // Valid JSON that isn't an OpenmrsRoutes object is dropped without throwing. Re-fetching
+      // would fail identically, so this must not defeat the cache.
+      fetchMock.mockResponse(JSON.stringify({ something: 'unexpected' }));
+
+      const { setupRouteMapOverrides, getCurrentRouteMap } = await import('./route-maps');
+      await setupRouteMapOverrides();
+
+      expect(Object.keys((await getCurrentRouteMap()).routes)).toHaveLength(0);
+      expect(Object.keys((await getCurrentRouteMap()).routes)).toHaveLength(0);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe('error handling', () => {
     it('reads route maps from remote script src attributes', async () => {
       (window as any).spaEnv = 'production';
@@ -394,6 +482,8 @@ describe('route-maps', () => {
 
       const map = await getCurrentRouteMap();
       expect(map.routes['@openmrs/esm-remote']).toEqual({ pages: [{ component: 'root', route: '/remote' }] });
+      // `crossorigin="anonymous"` on the preload link gives it a `same-origin` credentials mode,
+      // which is also `fetch()`'s default; passing anything else here misses the preload cache.
       expect(fetchMock).toHaveBeenCalledWith('http://localhost/routes.json');
     });
 

package/src/route-maps.ts

@@ -11,14 +11,34 @@ let devMode = false;
 // getCurrentRouteMap returns the overrides as they were when the page loaded).
 let initialOverrideSnapshot: OpenmrsRoutes | null = null;
 
+// Memoizes the base map so that the routes registry is fetched at most once per page load.
+let baseMapPromise: Promise<OpenmrsRoutes> | null = null;
+
 /**
  * Reads all `<script type="openmrs-routes">` tags from the DOM and merges
  * them into a single {@link OpenmrsRoutes} object. Tags with a `src` attribute
  * are fetched; inline tags have their `textContent` parsed as JSON.
+ *
+ * A read in which no tag threw is cached and reused by all later callers. A read that lost a
+ * tag to an error is returned as-is but not cached, so that a transient network failure doesn't
+ * leave the page with a permanently incomplete map. A tag that loads but fails validation is
+ * dropped without invalidating the cache, since re-reading it would only fail the same way.
  */
 async function readBaseMap(): Promise<OpenmrsRoutes> {
+  baseMapPromise ??= loadBaseMap().then(({ map, complete }) => {
+    if (!complete) {
+      baseMapPromise = null;
+    }
+    return map;
+  });
+
+  return baseMapPromise;
+}
+
+async function loadBaseMap(): Promise<{ map: OpenmrsRoutes; complete: boolean }> {
   const scripts = document.querySelectorAll<HTMLScriptElement>("script[type='openmrs-routes']");
   const maps: OpenmrsRoutes[] = [];
+  let complete = true;
 
   for (let i = 0; i < scripts.length; i++) {
     const script = scripts[i];
@@ -26,6 +46,9 @@ async function readBaseMap(): Promise<OpenmrsRoutes> {
       let parsed: unknown;
       if (script.src) {
         const response = await fetch(script.src);
+        if (!response.ok) {
+          throw new Error(`Request for ${script.src} returned ${response.status} ${response.statusText}`);
+        }
         parsed = await response.json();
       } else if (script.textContent) {
         parsed = JSON.parse(script.textContent);
@@ -35,11 +58,12 @@ async function readBaseMap(): Promise<OpenmrsRoutes> {
         maps.push(parsed);
       }
     } catch (e) {
+      complete = false;
       console.warn(`[route-maps] Failed to parse routes from script tag at index ${i}`, e);
     }
   }
 
-  return mergeRouteMaps(maps);
+  return { map: mergeRouteMaps(maps), complete };
 }
 
 function mergeRouteMaps(maps: OpenmrsRoutes[]): OpenmrsRoutes {