@openmrs/esm-dynamic-loading 9.0.3-pre.4533 → 9.0.3-pre.4550

package/src/import-maps.test.ts

@@ -0,0 +1,363 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import createFetchMock from 'vitest-fetch-mock';
+
+createFetchMock(vi).enableMocks();
+
+describe('import-maps', () => {
+  function setDomImportMaps(maps: Array<{ imports: Record<string, string> }>) {
+    document.querySelectorAll('script[type="systemjs-importmap"]').forEach((el) => el.remove());
+
+    for (const map of maps) {
+      const script = document.createElement('script');
+      script.type = 'systemjs-importmap';
+      script.textContent = JSON.stringify(map);
+      document.head.appendChild(script);
+    }
+  }
+
+  beforeEach(() => {
+    localStorage.clear();
+    fetchMock.resetMocks();
+    document.querySelectorAll('script[type="systemjs-importmap"]').forEach((el) => el.remove());
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    // Reset spaEnv so it can be reassigned in next test
+    Object.defineProperty(window, 'spaEnv', { value: undefined, writable: true, configurable: true });
+  });
+
+  describe('production mode', () => {
+    beforeEach(async () => {
+      (window as any).spaEnv = 'production';
+      vi.resetModules();
+    });
+
+    it('getCurrentPageMap returns the base map without overrides', async () => {
+      const { setupImportMapOverrides, getCurrentPageMap } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      setDomImportMaps([
+        { imports: { '@openmrs/esm-foo': '/foo.js' } },
+        { imports: { '@openmrs/esm-bar': '/bar.js' } },
+      ]);
+
+      localStorage.setItem('import-map-override:@openmrs/esm-foo', 'http://evil.com/foo.js');
+
+      const map = await getCurrentPageMap();
+      expect(map.imports['@openmrs/esm-foo']).toBe('/foo.js');
+      expect(map.imports['@openmrs/esm-bar']).toBe('/bar.js');
+    });
+
+    it('getImportMapOverrideMap returns empty imports', async () => {
+      const { setupImportMapOverrides, getImportMapOverrideMap } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      localStorage.setItem('import-map-override:@openmrs/esm-foo', 'http://evil.com/foo.js');
+      const map = getImportMapOverrideMap();
+      expect(map.imports).toEqual({});
+    });
+
+    it('addImportMapOverride is a no-op', async () => {
+      const { setupImportMapOverrides, addImportMapOverride } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      addImportMapOverride('@openmrs/esm-foo', 'http://evil.com/foo.js');
+      expect(localStorage.getItem('import-map-override:@openmrs/esm-foo')).toBeNull();
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining('disabled in production'));
+    });
+
+    it('removeImportMapOverride is a no-op', async () => {
+      const { setupImportMapOverrides, removeImportMapOverride } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      localStorage.setItem('import-map-override:@openmrs/esm-foo', '/foo.js');
+      removeImportMapOverride('@openmrs/esm-foo');
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining('disabled in production'));
+    });
+
+    it('resetImportMapOverrides is a no-op', async () => {
+      const { setupImportMapOverrides, resetImportMapOverrides } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      resetImportMapOverrides();
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining('disabled in production'));
+    });
+
+    it('getImportMapDisabledOverrides returns empty array', async () => {
+      const { setupImportMapOverrides, getImportMapDisabledOverrides } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      expect(getImportMapDisabledOverrides()).toEqual([]);
+    });
+
+    it('isImportMapOverrideDisabled returns false', async () => {
+      const { setupImportMapOverrides, isImportMapOverrideDisabled } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      expect(isImportMapOverrideDisabled('@openmrs/esm-foo')).toBe(false);
+    });
+  });
+
+  describe('development mode', () => {
+    beforeEach(async () => {
+      (window as any).spaEnv = 'development';
+      vi.resetModules();
+    });
+
+    it('getCurrentPageMap merges base map with overrides', async () => {
+      setDomImportMaps([{ imports: { '@openmrs/esm-foo': '/foo.js', '@openmrs/esm-bar': '/bar.js' } }]);
+      localStorage.setItem('import-map-override:@openmrs/esm-foo', 'http://localhost:8080/foo.js');
+
+      const { setupImportMapOverrides, getCurrentPageMap } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      const map = await getCurrentPageMap();
+      expect(map.imports['@openmrs/esm-foo']).toBe('http://localhost:8080/foo.js');
+      expect(map.imports['@openmrs/esm-bar']).toBe('/bar.js');
+    });
+
+    it('getImportMapDefaultMap returns only the base map', async () => {
+      setDomImportMaps([{ imports: { '@openmrs/esm-foo': '/foo.js' } }]);
+      localStorage.setItem('import-map-override:@openmrs/esm-foo', 'http://localhost:8080/foo.js');
+
+      const { setupImportMapOverrides, getImportMapDefaultMap } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      const map = await getImportMapDefaultMap();
+      expect(map.imports['@openmrs/esm-foo']).toBe('/foo.js');
+    });
+
+    it('addImportMapOverride stores in localStorage', async () => {
+      const { setupImportMapOverrides, addImportMapOverride } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      addImportMapOverride('@openmrs/esm-foo', 'http://localhost:8080/foo.js');
+      expect(localStorage.getItem('import-map-override:@openmrs/esm-foo')).toBe('http://localhost:8080/foo.js');
+    });
+
+    it('removeImportMapOverride removes from localStorage', async () => {
+      localStorage.setItem('import-map-override:@openmrs/esm-foo', 'http://localhost:8080/foo.js');
+
+      const { setupImportMapOverrides, removeImportMapOverride } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      removeImportMapOverride('@openmrs/esm-foo');
+      expect(localStorage.getItem('import-map-override:@openmrs/esm-foo')).toBeNull();
+    });
+
+    it('resetImportMapOverrides clears all override keys', async () => {
+      localStorage.setItem('import-map-override:@openmrs/esm-foo', '/foo.js');
+      localStorage.setItem('import-map-override:@openmrs/esm-bar', '/bar.js');
+      localStorage.setItem('unrelated-key', 'value');
+
+      const { setupImportMapOverrides, resetImportMapOverrides } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      resetImportMapOverrides();
+      expect(localStorage.getItem('import-map-override:@openmrs/esm-foo')).toBeNull();
+      expect(localStorage.getItem('import-map-override:@openmrs/esm-bar')).toBeNull();
+      expect(localStorage.getItem('unrelated-key')).toBe('value');
+    });
+
+    it('addImportMapOverride fires change event', async () => {
+      const { setupImportMapOverrides, addImportMapOverride } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      const handler = vi.fn();
+      window.addEventListener('import-map-overrides:change', handler);
+
+      addImportMapOverride('@openmrs/esm-foo', '/foo.js');
+      expect(handler).toHaveBeenCalledTimes(1);
+
+      window.removeEventListener('import-map-overrides:change', handler);
+    });
+
+    it('getImportMapOverrideMap excludes disabled overrides by default', async () => {
+      localStorage.setItem('import-map-override:@openmrs/esm-foo', '/foo.js');
+      localStorage.setItem('import-map-override:@openmrs/esm-bar', '/bar.js');
+      localStorage.setItem('import-map-overrides-disabled', JSON.stringify(['@openmrs/esm-foo']));
+
+      const { setupImportMapOverrides, getImportMapOverrideMap } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      const map = getImportMapOverrideMap();
+      expect(map.imports['@openmrs/esm-foo']).toBeUndefined();
+      expect(map.imports['@openmrs/esm-bar']).toBe('/bar.js');
+    });
+
+    it('getImportMapOverrideMap includes disabled overrides when requested', async () => {
+      localStorage.setItem('import-map-override:@openmrs/esm-foo', '/foo.js');
+      localStorage.setItem('import-map-overrides-disabled', JSON.stringify(['@openmrs/esm-foo']));
+
+      const { setupImportMapOverrides, getImportMapOverrideMap } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      const map = getImportMapOverrideMap(true);
+      expect(map.imports['@openmrs/esm-foo']).toBe('/foo.js');
+    });
+
+    it('getImportMapNextPageMap merges base map with current overrides', async () => {
+      setDomImportMaps([{ imports: { '@openmrs/esm-foo': '/foo.js', '@openmrs/esm-bar': '/bar.js' } }]);
+      localStorage.setItem('import-map-override:@openmrs/esm-foo', 'http://localhost:8080/foo.js');
+
+      const { setupImportMapOverrides, addImportMapOverride, getImportMapNextPageMap } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      // Add a new override after setup — should appear in the next-page map but not the current-page snapshot
+      addImportMapOverride('@openmrs/esm-bar', 'http://localhost:8080/bar.js');
+
+      const map = await getImportMapNextPageMap();
+      expect(map.imports['@openmrs/esm-foo']).toBe('http://localhost:8080/foo.js');
+      expect(map.imports['@openmrs/esm-bar']).toBe('http://localhost:8080/bar.js');
+    });
+
+    it('isImportMapOverrideDisabled returns true for a disabled override', async () => {
+      localStorage.setItem('import-map-override:@openmrs/esm-foo', '/foo.js');
+      localStorage.setItem('import-map-overrides-disabled', JSON.stringify(['@openmrs/esm-foo']));
+
+      const { setupImportMapOverrides, isImportMapOverrideDisabled } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      expect(isImportMapOverrideDisabled('@openmrs/esm-foo')).toBe(true);
+      expect(isImportMapOverrideDisabled('@openmrs/esm-bar')).toBe(false);
+    });
+
+    it('enableImportMapOverride re-enables a disabled override', async () => {
+      localStorage.setItem('import-map-override:@openmrs/esm-foo', '/foo.js');
+      localStorage.setItem('import-map-override:@openmrs/esm-bar', '/bar.js');
+      localStorage.setItem('import-map-overrides-disabled', JSON.stringify(['@openmrs/esm-foo', '@openmrs/esm-bar']));
+
+      const {
+        setupImportMapOverrides,
+        enableImportMapOverride,
+        getImportMapOverrideMap,
+        getImportMapDisabledOverrides,
+      } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      // Both overrides are disabled — neither appears in the active override map
+      expect(getImportMapOverrideMap().imports['@openmrs/esm-foo']).toBeUndefined();
+
+      enableImportMapOverride('@openmrs/esm-foo');
+
+      // Now foo is enabled again
+      expect(getImportMapOverrideMap().imports['@openmrs/esm-foo']).toBe('/foo.js');
+      // bar is still disabled
+      expect(getImportMapDisabledOverrides()).toEqual(['@openmrs/esm-bar']);
+    });
+
+    it('enableImportMapOverride removes the disabled key when the last override is re-enabled', async () => {
+      localStorage.setItem('import-map-override:@openmrs/esm-foo', '/foo.js');
+      localStorage.setItem('import-map-overrides-disabled', JSON.stringify(['@openmrs/esm-foo']));
+
+      const { setupImportMapOverrides, enableImportMapOverride, getImportMapDisabledOverrides } = await import(
+        './import-maps'
+      );
+      setupImportMapOverrides();
+
+      enableImportMapOverride('@openmrs/esm-foo');
+
+      expect(getImportMapDisabledOverrides()).toEqual([]);
+      expect(localStorage.getItem('import-map-overrides-disabled')).toBeNull();
+    });
+
+    it('enableImportMapOverride fires a change event', async () => {
+      localStorage.setItem('import-map-override:@openmrs/esm-foo', '/foo.js');
+      localStorage.setItem('import-map-overrides-disabled', JSON.stringify(['@openmrs/esm-foo']));
+
+      const { setupImportMapOverrides, enableImportMapOverride } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      const handler = vi.fn();
+      window.addEventListener('import-map-overrides:change', handler);
+
+      enableImportMapOverride('@openmrs/esm-foo');
+      expect(handler).toHaveBeenCalledTimes(1);
+
+      window.removeEventListener('import-map-overrides:change', handler);
+    });
+
+    it('handles remote import maps via fetch', async () => {
+      const script = document.createElement('script');
+      script.type = 'systemjs-importmap';
+      Object.defineProperty(script, 'src', { value: 'http://localhost/importmap.json', writable: false });
+      document.head.appendChild(script);
+
+      fetchMock.mockResponseOnce(JSON.stringify({ imports: { '@openmrs/esm-remote': '/remote.js' } }));
+
+      const { setupImportMapOverrides, getCurrentPageMap } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      const map = await getCurrentPageMap();
+      expect(map.imports['@openmrs/esm-remote']).toBe('/remote.js');
+    });
+
+    it('getImportMapNextPageMap does not include overrides added after setup in getCurrentPageMap', async () => {
+      setDomImportMaps([{ imports: { '@openmrs/esm-foo': '/foo.js' } }]);
+
+      const { setupImportMapOverrides, addImportMapOverride, getCurrentPageMap, getImportMapNextPageMap } =
+        await import('./import-maps');
+      setupImportMapOverrides();
+
+      // Add an override after setup
+      addImportMapOverride('@openmrs/esm-foo', 'http://localhost:8080/foo.js');
+
+      // getCurrentPageMap uses the snapshot from setup time — override not reflected
+      const currentMap = await getCurrentPageMap();
+      expect(currentMap.imports['@openmrs/esm-foo']).toBe('/foo.js');
+
+      // getImportMapNextPageMap reads the live overrides — reflects the new one
+      const nextMap = await getImportMapNextPageMap();
+      expect(nextMap.imports['@openmrs/esm-foo']).toBe('http://localhost:8080/foo.js');
+    });
+  });
+
+  describe('merging behavior', () => {
+    it('later maps override earlier ones', async () => {
+      (window as any).spaEnv = 'production';
+      vi.resetModules();
+
+      setDomImportMaps([
+        { imports: { '@openmrs/esm-foo': '/foo-v1.js' } },
+        { imports: { '@openmrs/esm-foo': '/foo-v2.js' } },
+      ]);
+
+      const { setupImportMapOverrides, getCurrentPageMap } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      const map = await getCurrentPageMap();
+      expect(map.imports['@openmrs/esm-foo']).toBe('/foo-v2.js');
+    });
+  });
+
+  describe('error handling', () => {
+    it('skips malformed inline import map script tags', async () => {
+      (window as any).spaEnv = 'production';
+      vi.resetModules();
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      // One valid map, one with invalid JSON
+      const good = document.createElement('script');
+      good.type = 'systemjs-importmap';
+      good.textContent = JSON.stringify({ imports: { '@openmrs/esm-foo': '/foo.js' } });
+      document.head.appendChild(good);
+
+      const bad = document.createElement('script');
+      bad.type = 'systemjs-importmap';
+      bad.textContent = '{ not valid json';
+      document.head.appendChild(bad);
+
+      const { setupImportMapOverrides, getCurrentPageMap } = await import('./import-maps');
+      setupImportMapOverrides();
+
+      const map = await getCurrentPageMap();
+      expect(map.imports['@openmrs/esm-foo']).toBe('/foo.js');
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to parse import map'), expect.anything());
+    });
+  });
+});

package/src/import-maps.ts

@@ -0,0 +1,274 @@
+/** @module @category Import Map */
+import type { ImportMap } from '@openmrs/esm-globals';
+
+const OVERRIDE_PREFIX = 'import-map-override:';
+const DISABLED_KEY = 'import-map-overrides-disabled';
+const CHANGE_EVENT = 'import-map-overrides:change';
+
+// Set by setupImportMapOverrides(); controls whether override functionality is active.
+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: 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.
+ */
+async function readBaseMap(): Promise<ImportMap> {
+  const scripts = document.querySelectorAll<HTMLScriptElement>('script[type="systemjs-importmap"]');
+  const maps: ImportMap[] = [];
+
+  for (let i = 0; i < scripts.length; i++) {
+    const script = scripts[i];
+    try {
+      if (script.src) {
+        const response = await fetch(script.src);
+        maps.push(await response.json());
+      } else if (script.textContent) {
+        maps.push(JSON.parse(script.textContent));
+      }
+    } catch (e) {
+      console.warn(`[import-maps] Failed to parse import map from script tag at index ${i}`, e);
+    }
+  }
+
+  return mergeMaps(maps);
+}
+
+function mergeMaps(maps: ImportMap[]): ImportMap {
+  const merged: ImportMap = { imports: {} };
+  for (const map of maps) {
+    if (map?.imports) {
+      Object.assign(merged.imports, map.imports);
+    }
+  }
+  return merged;
+}
+
+/** Returns all `import-map-override:*` entries from localStorage as an {@link ImportMap}. */
+function readOverrideMap(): ImportMap {
+  const imports: Record<string, string> = {};
+
+  try {
+    const disabled = getImportMapDisabledOverrides();
+
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (key?.startsWith(OVERRIDE_PREFIX)) {
+        const moduleName = key.slice(OVERRIDE_PREFIX.length);
+        if (!disabled.includes(moduleName)) {
+          const url = localStorage.getItem(key);
+          if (url) {
+            imports[moduleName] = url;
+          }
+        }
+      }
+    }
+  } catch (e) {
+    console.warn('[import-maps] Failed to read import-map overrides from localStorage', e);
+  }
+
+  return { imports };
+}
+
+/**
+ * Returns the import map for the current page. In dev mode, this merges
+ * the base map with the override snapshot captured at page load.
+ */
+export async function getCurrentPageMap(): Promise<ImportMap> {
+  const base = await readBaseMap();
+  if (!devMode) {
+    return base;
+  }
+  const overrides = initialOverrideSnapshot ?? readOverrideMap();
+  return mergeMaps([base, overrides]);
+}
+
+/**
+ * Returns the base import map from the DOM without any overrides applied.
+ */
+export async function getImportMapDefaultMap(): Promise<ImportMap> {
+  return readBaseMap();
+}
+
+/**
+ * Returns what the import map will look like on the next page load, including
+ * any overrides that have been added/removed since the page loaded.
+ * In production, this is the same as the base map.
+ */
+export async function getImportMapNextPageMap(): Promise<ImportMap> {
+  if (!devMode) {
+    return readBaseMap();
+  }
+  const base = await readBaseMap();
+  return mergeMaps([base, readOverrideMap()]);
+}
+
+/**
+ * Returns the current override map. In production, returns empty imports.
+ * @param includeDisabled If true, includes disabled overrides.
+ */
+export function getImportMapOverrideMap(includeDisabled?: boolean): ImportMap {
+  if (!devMode) {
+    return { imports: {} };
+  }
+
+  if (includeDisabled) {
+    const imports: Record<string, string> = {};
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (key?.startsWith(OVERRIDE_PREFIX)) {
+        const url = localStorage.getItem(key);
+        if (url) {
+          imports[key.slice(OVERRIDE_PREFIX.length)] = url;
+        }
+      }
+    }
+    return { imports };
+  }
+  return readOverrideMap();
+}
+
+/**
+ * Returns the list of module names whose overrides are disabled.
+ * In production, returns an empty array.
+ */
+export function getImportMapDisabledOverrides(): string[] {
+  if (!devMode) {
+    return [];
+  }
+
+  try {
+    const raw = localStorage.getItem(DISABLED_KEY);
+    if (raw) {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) {
+        return parsed;
+      }
+    }
+  } catch {
+    // ignore malformed data
+  }
+  return [];
+}
+
+/**
+ * Returns whether the given module's override is disabled.
+ * In production, returns false.
+ */
+export function isImportMapOverrideDisabled(moduleName: string): boolean {
+  if (!devMode) {
+    return false;
+  }
+  return getImportMapDisabledOverrides().includes(moduleName);
+}
+
+/**
+ * Adds an import map override. In production, this is a no-op.
+ */
+export function addImportMapOverride(name: string, url: string): void {
+  if (!devMode) {
+    console.warn('[Security] Import map overrides are disabled in production mode.');
+    return;
+  }
+  try {
+    localStorage.setItem(OVERRIDE_PREFIX + name, url);
+    window.dispatchEvent(new CustomEvent(CHANGE_EVENT));
+  } catch (e) {
+    console.warn('[import-maps] Failed to write import-map override to localStorage', e);
+  }
+}
+
+/**
+ * Removes an import map override. In production, this is a no-op.
+ */
+export function removeImportMapOverride(name: string): void {
+  if (!devMode) {
+    console.warn('[Security] Import map overrides are disabled in production mode.');
+    return;
+  }
+  try {
+    localStorage.removeItem(OVERRIDE_PREFIX + name);
+    const disabled = getImportMapDisabledOverrides().filter((n) => n !== name);
+    if (disabled.length > 0) {
+      localStorage.setItem(DISABLED_KEY, JSON.stringify(disabled));
+    } else {
+      localStorage.removeItem(DISABLED_KEY);
+    }
+    window.dispatchEvent(new CustomEvent(CHANGE_EVENT));
+  } catch (e) {
+    console.warn('[import-maps] Failed to update import-map overrides in localStorage', e);
+  }
+}
+
+/**
+ * Clears all import map overrides. In production, this is a no-op.
+ */
+export function resetImportMapOverrides(): void {
+  if (!devMode) {
+    console.warn('[Security] Import map overrides are disabled in production mode.');
+    return;
+  }
+  try {
+    const keysToRemove: string[] = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (key?.startsWith(OVERRIDE_PREFIX)) {
+        keysToRemove.push(key);
+      }
+    }
+    keysToRemove.forEach((key) => localStorage.removeItem(key));
+    localStorage.removeItem(DISABLED_KEY);
+    window.dispatchEvent(new CustomEvent(CHANGE_EVENT));
+  } catch (e) {
+    console.warn('[import-maps] Failed to clear import-map overrides from localStorage', e);
+  }
+}
+
+/**
+ * Re-enables a previously disabled import map override. In production, this is a no-op.
+ */
+export function enableImportMapOverride(name: string): void {
+  if (!devMode) {
+    console.warn('[Security] Import map overrides are disabled in production mode.');
+    return;
+  }
+  try {
+    const disabled = getImportMapDisabledOverrides().filter((n) => n !== name);
+    if (disabled.length > 0) {
+      localStorage.setItem(DISABLED_KEY, JSON.stringify(disabled));
+    } else {
+      localStorage.removeItem(DISABLED_KEY);
+    }
+    window.dispatchEvent(new CustomEvent(CHANGE_EVENT));
+  } catch (e) {
+    console.warn('[import-maps] Failed to update import-map overrides in localStorage', e);
+  }
+}
+
+/**
+ * Initializes the import map override system with mode-aware behavior.
+ *
+ * In production (`window.spaEnv !== 'development'`), mutation functions are
+ * no-ops and localStorage overrides are never consulted. In development, the
+ * full override workflow is available.
+ *
+ * Must be called before any code that depends on the import map functions.
+ */
+let initialized = false;
+
+export function setupImportMapOverrides() {
+  if (initialized) {
+    return;
+  }
+  initialized = true;
+
+  devMode = window.spaEnv === 'development';
+
+  if (devMode) {
+    initialOverrideSnapshot = readOverrideMap();
+  }
+}

package/src/index.ts

@@ -1 +1,3 @@
 export * from './dynamic-loading';
+export * from './import-maps';
+export * from './route-maps';