From 7b1d29eb5b58bdc62db7099ca72a6f2e9338d1eb Mon Sep 17 00:00:00 2001
From: Santiago Palenque <santipalenque@gmail.com>
Date: Thu, 23 Jul 2026 17:44:58 -0300
Subject: [PATCH 1/2] feat: add lazy load with reload methods

---
 src/utils/__tests__/lazy-with-reload.test.js | 353 +++++++++++++++++++
 src/utils/lazy-with-reload.js                | 224 ++++++++++++
 webpack.common.js                            |   1 +
 3 files changed, 578 insertions(+)
 create mode 100644 src/utils/__tests__/lazy-with-reload.test.js
 create mode 100644 src/utils/lazy-with-reload.js

diff --git a/src/utils/__tests__/lazy-with-reload.test.js b/src/utils/__tests__/lazy-with-reload.test.js
new file mode 100644
index 00000000..7cac305f
--- /dev/null
+++ b/src/utils/__tests__/lazy-with-reload.test.js
@@ -0,0 +1,353 @@
+jest.mock("react", () => ({
+    ...jest.requireActual("react"),
+    lazy: jest.fn((loader) => loader),
+}));
+
+const mockCaptureMessage = jest.fn();
+jest.mock("@sentry/react", () => ({
+    captureMessage: (...args) => mockCaptureMessage(...args),
+}));
+
+import {
+    isChunkLoadError,
+    reloadOnChunkError,
+    lazyWithReload,
+    initChunkErrorRecovery,
+    chunkErrorSentryBeforeSend,
+} from "../lazy-with-reload";
+
+const chunkLoadError = () => Object.assign(new Error("Loading chunk 3 failed.\n(missing: https://app.test/foo_abc123.js)"), {
+    name: "ChunkLoadError",
+});
+
+const htmlParsedAsScriptError = (filename) => Object.assign(
+    new Error("Unexpected token '<'"),
+    { name: "SyntaxError", filename }
+);
+
+// Replaces document's <script> tags so getBuildFingerprint() (cached per
+// module instance) reads a specific, known set the next time a fresh
+// module instance computes it.
+const setDocumentScripts = (srcs) => {
+    document.querySelectorAll("script[data-test-build]").forEach((el) => el.remove());
+    srcs.forEach((src) => {
+        const script = document.createElement("script");
+        script.src = src;
+        script.setAttribute("data-test-build", "1");
+        document.body.appendChild(script);
+    });
+};
+
+beforeEach(() => {
+    window.sessionStorage.clear();
+    window.SENTRY_DSN = "https://test.example/dsn";
+    mockCaptureMessage.mockClear();
+    console.error = jest.fn(); // eslint-disable-line no-console
+    console.log = jest.fn(); // eslint-disable-line no-console
+    delete window.location;
+    window.location = { reload: jest.fn() };
+    setDocumentScripts([]);
+});
+
+describe("isChunkLoadError", () => {
+    test("matches webpack's ChunkLoadError by name, regardless of message", () => {
+        expect(isChunkLoadError(chunkLoadError())).toBe(true);
+    });
+
+    test("matches a SyntaxError for 'Unexpected token <' with no filename", () => {
+        expect(isChunkLoadError(htmlParsedAsScriptError())).toBe(true);
+    });
+
+    test("matches a SyntaxError for 'Unexpected token <' when the filename looks like a content-hashed chunk", () => {
+        expect(
+            isChunkLoadError(
+                htmlParsedAsScriptError(),
+                "https://app.test/static/dashboard_a1b2c3d4e5f6.js"
+            )
+        ).toBe(true);
+    });
+
+    test("does not match a SyntaxError for 'Unexpected token <' when the filename does not look like a chunk", () => {
+        expect(
+            isChunkLoadError(
+                htmlParsedAsScriptError(),
+                "https://app.test/static/vendor.min.js"
+            )
+        ).toBe(false);
+    });
+
+    test("does not match an unrelated error", () => {
+        expect(isChunkLoadError(new TypeError("x is not a function"))).toBe(false);
+    });
+
+    test("does not match null/undefined", () => {
+        expect(isChunkLoadError(null)).toBe(false);
+        expect(isChunkLoadError(undefined)).toBe(false);
+    });
+
+    test("accepts a custom chunk filename pattern", () => {
+        const customPattern = /^\/legacy-chunks\//;
+        expect(
+            isChunkLoadError(
+                htmlParsedAsScriptError(),
+                "/legacy-chunks/dashboard.js",
+                customPattern
+            )
+        ).toBe(true);
+        expect(
+            isChunkLoadError(
+                htmlParsedAsScriptError(),
+                "/static/dashboard_a1b2c3d4.js",
+                customPattern
+            )
+        ).toBe(false);
+    });
+});
+
+describe("reloadOnChunkError", () => {
+    test("reloads once and returns true for a first-time chunk error", () => {
+        const handled = reloadOnChunkError(chunkLoadError());
+
+        expect(handled).toBe(true);
+        expect(window.location.reload).toHaveBeenCalledTimes(1);
+        expect(mockCaptureMessage).not.toHaveBeenCalled();
+    });
+
+    test("does not reload again on a second chunk error on the same build, and reports it instead", () => {
+        reloadOnChunkError(chunkLoadError());
+        window.location.reload.mockClear();
+
+        const handled = reloadOnChunkError(chunkLoadError());
+
+        expect(handled).toBe(false);
+        expect(window.location.reload).not.toHaveBeenCalled();
+        expect(mockCaptureMessage).toHaveBeenCalledWith(
+            "Chunk load error persisted after auto-reload",
+            expect.objectContaining({
+                tags: { chunkErrorRecovery: "failed" },
+            })
+        );
+    });
+
+    test("falls back to console.error when Sentry is not initialized", () => {
+        delete window.SENTRY_DSN;
+        reloadOnChunkError(chunkLoadError());
+        window.location.reload.mockClear();
+
+        reloadOnChunkError(chunkLoadError());
+
+        expect(mockCaptureMessage).not.toHaveBeenCalled();
+        expect(console.error).toHaveBeenCalledWith(
+            "Chunk load error persisted after auto-reload",
+            expect.objectContaining({
+                tags: { chunkErrorRecovery: "failed" },
+            })
+        );
+    });
+
+    test("does nothing for a non-chunk error", () => {
+        const handled = reloadOnChunkError(new TypeError("boom"));
+
+        expect(handled).toBe(false);
+        expect(window.location.reload).not.toHaveBeenCalled();
+        expect(mockCaptureMessage).not.toHaveBeenCalled();
+    });
+
+    // Reproduces the "two deploys in the same long-lived tab" scenario: a
+    // reload already happened once for build A, and now build B (a distinct
+    // set of statically-loaded <script> tags) has its own, unrelated chunk
+    // failure - it should get its own fresh reload attempt rather than
+    // being silently blocked by the earlier, unrelated recovery.
+    test("allows a fresh reload when a chunk error occurs on a different build than the one already reloaded for", () => {
+        jest.resetModules();
+        setDocumentScripts(["https://app.test/main_buildA111111.js"]);
+        // eslint-disable-next-line global-require
+        const buildA = require("../lazy-with-reload");
+        expect(buildA.reloadOnChunkError(chunkLoadError())).toBe(true);
+        expect(window.location.reload).toHaveBeenCalledTimes(1);
+        window.location.reload.mockClear();
+
+        // still build A: same fingerprint, must not reload again
+        expect(buildA.reloadOnChunkError(chunkLoadError())).toBe(false);
+        expect(window.location.reload).not.toHaveBeenCalled();
+        mockCaptureMessage.mockClear();
+
+        // simulate the reload having carried the tab onto a new build
+        jest.resetModules();
+        setDocumentScripts(["https://app.test/main_buildB222222.js"]);
+        // eslint-disable-next-line global-require
+        const buildB = require("../lazy-with-reload");
+
+        expect(buildB.reloadOnChunkError(chunkLoadError())).toBe(true);
+        expect(window.location.reload).toHaveBeenCalledTimes(1);
+        expect(mockCaptureMessage).not.toHaveBeenCalled();
+    });
+});
+
+describe("lazyWithReload", () => {
+    test("on a chunk-load failure, reloads and returns a promise that never resolves", async () => {
+        const importer = () => Promise.reject(chunkLoadError());
+        const loader = lazyWithReload(importer);
+
+        let settled = false;
+        loader().then(() => { settled = true; }, () => { settled = true; });
+        await new Promise((resolve) => setTimeout(resolve, 0));
+
+        expect(window.location.reload).toHaveBeenCalledTimes(1);
+        expect(settled).toBe(false);
+    });
+
+    test("on an unrelated failure, rethrows so the error boundary still sees it", async () => {
+        const originalError = new TypeError("boom");
+        const importer = () => Promise.reject(originalError);
+        const loader = lazyWithReload(importer);
+
+        await expect(loader()).rejects.toBe(originalError);
+        expect(window.location.reload).not.toHaveBeenCalled();
+    });
+
+    test("on success, resolves normally", async () => {
+        const module = { default: () => null };
+        const importer = () => Promise.resolve(module);
+        const loader = lazyWithReload(importer);
+
+        await expect(loader()).resolves.toBe(module);
+    });
+});
+
+describe("initChunkErrorRecovery", () => {
+    // tracked so afterEach can always remove the listeners, even if a test's
+    // own assertions throw first - otherwise a failing test would leak
+    // listeners onto window and contaminate later tests in this file
+    let cleanup;
+
+    afterEach(() => {
+        cleanup?.();
+        cleanup = undefined;
+    });
+
+    test("reloads and prevents default on an unhandledrejection carrying a chunk error", () => {
+        cleanup = initChunkErrorRecovery();
+        const preventDefault = jest.fn();
+
+        window.dispatchEvent(
+            Object.assign(new Event("unhandledrejection"), {
+                reason: chunkLoadError(),
+                preventDefault,
+            })
+        );
+
+        expect(window.location.reload).toHaveBeenCalledTimes(1);
+        expect(preventDefault).toHaveBeenCalledTimes(1);
+    });
+
+    test("reloads and prevents default on a global error event for the HTML-as-script SyntaxError", () => {
+        cleanup = initChunkErrorRecovery();
+        const preventDefault = jest.fn();
+
+        window.dispatchEvent(
+            Object.assign(new Event("error"), {
+                error: htmlParsedAsScriptError(),
+                filename: "https://app.test/static/dashboard_a1b2c3d4e5f6.js",
+                preventDefault,
+            })
+        );
+
+        expect(window.location.reload).toHaveBeenCalledTimes(1);
+        expect(preventDefault).toHaveBeenCalledTimes(1);
+    });
+
+    test("does not touch unrelated errors", () => {
+        cleanup = initChunkErrorRecovery();
+        const preventDefault = jest.fn();
+
+        window.dispatchEvent(
+            Object.assign(new Event("error"), {
+                error: new TypeError("boom"),
+                preventDefault,
+            })
+        );
+
+        expect(window.location.reload).not.toHaveBeenCalled();
+        expect(preventDefault).not.toHaveBeenCalled();
+    });
+
+    test("cleanup removes the listeners", () => {
+        cleanup = initChunkErrorRecovery();
+        cleanup();
+        cleanup = undefined;
+        const preventDefault = jest.fn();
+
+        window.dispatchEvent(
+            Object.assign(new Event("unhandledrejection"), {
+                reason: chunkLoadError(),
+                preventDefault,
+            })
+        );
+
+        expect(window.location.reload).not.toHaveBeenCalled();
+    });
+
+    test("logs a confirmation once when a prior reload was pending, and clears the marker", () => {
+        window.sessionStorage.setItem("uicore.chunk-load-error-pending-confirmation", "1");
+
+        cleanup = initChunkErrorRecovery();
+
+        expect(console.log).toHaveBeenCalledWith(
+            "[lazy-with-reload] Recovered from a chunk load error via automatic reload"
+        );
+        expect(
+            window.sessionStorage.getItem("uicore.chunk-load-error-pending-confirmation")
+        ).toBeNull();
+    });
+
+    test("does not log a confirmation when no reload was pending", () => {
+        cleanup = initChunkErrorRecovery();
+
+        expect(console.log).not.toHaveBeenCalled();
+    });
+
+    test("a real reload-then-init cycle logs exactly one confirmation", () => {
+        // first "page load": a chunk error triggers the reload, which sets
+        // the pending marker (sessionStorage survives a real reload)
+        reloadOnChunkError(chunkLoadError());
+        expect(window.location.reload).toHaveBeenCalledTimes(1);
+
+        // "post-reload" bootstrap calls initChunkErrorRecovery once, as the
+        // app does in app.js
+        cleanup = initChunkErrorRecovery();
+
+        expect(console.log).toHaveBeenCalledWith(
+            "[lazy-with-reload] Recovered from a chunk load error via automatic reload"
+        );
+        expect(console.log).toHaveBeenCalledTimes(1);
+    });
+});
+
+describe("chunkErrorSentryBeforeSend", () => {
+    test("drops an event whose exception is a ChunkLoadError", () => {
+        const event = {
+            exception: { values: [{ type: "ChunkLoadError", value: "Loading chunk 3 failed" }] },
+        };
+        expect(chunkErrorSentryBeforeSend(event)).toBeNull();
+    });
+
+    test("drops an event whose exception is the HTML-as-script SyntaxError", () => {
+        const event = {
+            exception: { values: [{ type: "SyntaxError", value: "Unexpected token '<'" }] },
+        };
+        expect(chunkErrorSentryBeforeSend(event)).toBeNull();
+    });
+
+    test("passes through an unrelated exception unchanged", () => {
+        const event = {
+            exception: { values: [{ type: "TypeError", value: "x is not a function" }] },
+        };
+        expect(chunkErrorSentryBeforeSend(event)).toBe(event);
+    });
+
+    test("passes through a message-type event with no exception unchanged", () => {
+        const event = { message: "Chunk load error persisted after auto-reload" };
+        expect(chunkErrorSentryBeforeSend(event)).toBe(event);
+    });
+});
diff --git a/src/utils/lazy-with-reload.js b/src/utils/lazy-with-reload.js
new file mode 100644
index 00000000..93efb1fb
--- /dev/null
+++ b/src/utils/lazy-with-reload.js
@@ -0,0 +1,224 @@
+/**
+ * Copyright 2026 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+import React from "react";
+import * as Sentry from "@sentry/react";
+import { isSentryInitialized } from "./methods";
+
+const RELOAD_STATE_KEY = "uicore.chunk-load-error-reload-state";
+const PENDING_CONFIRMATION_KEY = "uicore.chunk-load-error-pending-confirmation";
+
+// webpack's own JSONP chunk-loading runtime hardcodes error.name = "ChunkLoadError"
+// on every chunk-load failure it detects through the import() promise - both a
+// genuine network 404 AND the "script tag loaded (200 OK) but the expected chunk
+// never registered" case, e.g. a stale content-hashed chunk URL falling through to
+// an SPA's index.html fallback. This is webpack's own intentional, stable
+// convention (see webpack/lib/web/JsonpChunkLoadingRuntimeModule.js), not a guess.
+const isWebpackChunkLoadError = (error) =>
+  Boolean(error) && error.name === "ChunkLoadError";
+
+// Separately from the promise rejection above, the browser is ALSO trying to
+// execute that stale response's HTML content as the script tag's body, which
+// throws a genuine engine-level SyntaxError as an uncaught global script error -
+// a completely different failure surface that no amount of wrapping import() in
+// a .catch() can observe. There's no clean, structured signal for this one, so we
+// match on the characteristic message and, when a source filename is available,
+// cross-check it against a typical content-hashed chunk filename so this can't
+// false-match an unrelated SyntaxError elsewhere in the app.
+const DEFAULT_CHUNK_FILENAME_PATTERN = /[._-][0-9a-f]{8,}\.js(\?.*)?$/i;
+
+const isHtmlParsedAsScriptError = (
+  error,
+  filename,
+  chunkFilenamePattern = DEFAULT_CHUNK_FILENAME_PATTERN
+) => {
+  const message = (error && error.message) || (typeof error === "string" ? error : "");
+  // "SyntaxError" can show up on error.name (a real SyntaxError object) or
+  // inline in the message text (window.onerror's flat event.message string,
+  // e.g. "Uncaught SyntaxError: Unexpected token '<'") - check both.
+  const looksLikeSyntaxError =
+    (error && error.name === "SyntaxError") || /SyntaxError/i.test(message);
+  if (!looksLikeSyntaxError || !/Unexpected token '<'/i.test(message)) {
+    return false;
+  }
+  return !filename || chunkFilenamePattern.test(filename);
+};
+
+export const isChunkLoadError = (error, filename, chunkFilenamePattern) =>
+  isWebpackChunkLoadError(error) ||
+  isHtmlParsedAsScriptError(error, filename, chunkFilenamePattern);
+
+// Fingerprints the statically-loaded <script> tags present the first time
+// this module runs on a given page load - i.e. before any lazy chunk has
+// been requested. This identifies "which build is currently running"
+// without requiring the consuming app to expose a dedicated build-version
+// global. Computed once and cached: document.scripts grows over time as
+// webpack's runtime appends a <script> tag for every lazy chunk that loads,
+// so reading it lazily-but-uncached would make the fingerprint drift within
+// a single build, not just across a real deploy.
+let cachedBuildFingerprint;
+const getBuildFingerprint = () => {
+  if (cachedBuildFingerprint === undefined) {
+    cachedBuildFingerprint =
+      typeof document !== "undefined"
+        ? Array.from(document.scripts)
+            .map((s) => s.src)
+            .filter(Boolean)
+            .sort()
+            .join(",")
+        : "";
+  }
+  return cachedBuildFingerprint;
+};
+
+const readReloadState = () => {
+  try {
+    const raw = window.sessionStorage.getItem(RELOAD_STATE_KEY);
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+};
+
+const writeReloadState = (state) => {
+  try {
+    window.sessionStorage.setItem(RELOAD_STATE_KEY, JSON.stringify(state));
+  } catch {
+    // ignore - sessionStorage can throw in some privacy modes
+  }
+};
+
+const reportRecoveryFailed = (error, filename) => {
+  const context = {
+    level: "error",
+    tags: { chunkErrorRecovery: "failed" },
+    extra: { originalMessage: error?.message, filename }
+  };
+  if (isSentryInitialized()) {
+    Sentry.captureMessage("Chunk load error persisted after auto-reload", context);
+  } else {
+    console.error("Chunk load error persisted after auto-reload", context);
+  }
+};
+
+// Reloads the page once per *build* when a lazy chunk fails to load
+// (typically a stale content-hashed filename after a deploy). Returns true
+// only when it actually triggers a *new* reload; false if this isn't a chunk
+// error, or if we already tried reloading once for this same build - in the
+// latter case a distinct Sentry report is filed (see reportRecoveryFailed)
+// and the caller should let the error propagate normally instead of
+// looping. Scoping the guard to the build (not just "once this session")
+// means that if a second deploy lands later in the same long-lived tab, a
+// fresh failure on that new build still gets its own reload attempt instead
+// of being silently blocked by an unrelated earlier recovery.
+export const reloadOnChunkError = (error, filename, chunkFilenamePattern) => {
+  if (!isChunkLoadError(error, filename, chunkFilenamePattern)) return false;
+
+  const currentBuild = getBuildFingerprint();
+  const state = readReloadState();
+
+  if (state && state.build === currentBuild) {
+    reportRecoveryFailed(error, filename);
+    return false;
+  }
+
+  writeReloadState({ build: currentBuild });
+  try {
+    window.sessionStorage.setItem(PENDING_CONFIRMATION_KEY, "1");
+  } catch {
+    // ignore - see readReloadState/writeReloadState
+  }
+  window.location.reload();
+  return true;
+};
+
+// Logs (once) that a prior chunk-load-error reload actually took effect, so
+// it's easy to confirm in the console that this recovery path fired.
+const confirmReloadIfPending = () => {
+  try {
+    if (window.sessionStorage.getItem(PENDING_CONFIRMATION_KEY) === "1") {
+      window.sessionStorage.removeItem(PENDING_CONFIRMATION_KEY);
+      // eslint-disable-next-line no-console
+      console.log(
+        "[lazy-with-reload] Recovered from a chunk load error via automatic reload"
+      );
+    }
+  } catch {
+    // ignore
+  }
+};
+
+// Drop-in replacement for React.lazy(() => import(...)) that auto-recovers
+// from a stale-chunk failure by reloading the page once. On any other error,
+// or a repeat chunk failure after the reload already happened once for this
+// build, the error is rethrown so it still reaches the app's own error
+// boundary/fallback UI.
+export const lazyWithReload = (importer, chunkFilenamePattern) =>
+  React.lazy(() =>
+    importer().catch((error) => {
+      if (reloadOnChunkError(error, undefined, chunkFilenamePattern)) {
+        // reload is in flight - never resolve so nothing renders (e.g. an
+        // error boundary flash) before it takes effect
+        return new Promise(() => {});
+      }
+      throw error;
+    })
+  );
+
+// Fallback safety net for chunk-load failures that don't flow through
+// lazyWithReload (e.g. a bare React.lazy()/dynamic import() call, or the raw
+// SyntaxError case, which is never a promise rejection at all - see
+// isHtmlParsedAsScriptError above). Call once at app bootstrap. Also
+// confirms (via console.log) whether a prior chunk-load-error reload
+// actually took effect, since this is the app's one designated bootstrap
+// entry point for this recovery mechanism.
+export const initChunkErrorRecovery = (chunkFilenamePattern) => {
+  confirmReloadIfPending();
+
+  const onUnhandledRejection = (event) => {
+    if (reloadOnChunkError(event.reason, undefined, chunkFilenamePattern)) {
+      event.preventDefault();
+    }
+  };
+
+  const onError = (event) => {
+    const error = event.error || { message: event.message };
+    if (reloadOnChunkError(error, event.filename, chunkFilenamePattern)) {
+      event.preventDefault();
+    }
+  };
+
+  window.addEventListener("unhandledrejection", onUnhandledRejection);
+  window.addEventListener("error", onError);
+
+  return () => {
+    window.removeEventListener("unhandledrejection", onUnhandledRejection);
+    window.removeEventListener("error", onError);
+  };
+};
+
+// Sentry beforeSend hook: drops chunk-load-error events from being reported,
+// since a first-time occurrence is expected to self-heal via the reload
+// above. A repeat failure (reload didn't help) is reported separately and
+// explicitly via reportRecoveryFailed's Sentry.captureMessage call, which is
+// a message-type event (no .exception), so it is unaffected by this filter.
+export const chunkErrorSentryBeforeSend = (event) => {
+  const exceptionValues = event.exception?.values || [];
+  const matchesChunkError = exceptionValues.some((exceptionValue) =>
+    isChunkLoadError({
+      name: exceptionValue.type,
+      message: exceptionValue.value
+    })
+  );
+  return matchesChunkError ? null : event;
+};
diff --git a/webpack.common.js b/webpack.common.js
index 162da07a..260f6761 100644
--- a/webpack.common.js
+++ b/webpack.common.js
@@ -173,6 +173,7 @@ module.exports = {
         'utils/use-event-callback': './src/utils/use-event-callback.js',
         'utils/external-store': './src/utils/external-store.js',
         'utils/theme': './src/components/mui/MuiBaseCustomTheme.js',
+        'utils/lazy-with-reload': './src/utils/lazy-with-reload.js',
     },
     output: {
         path: path.resolve(__dirname, 'lib'),

From 400adfb32fdb34065760593e52fb59d01ca8310c Mon Sep 17 00:00:00 2001
From: Santiago Palenque <santipalenque@gmail.com>
Date: Thu, 23 Jul 2026 17:52:13 -0300
Subject: [PATCH 2/2] v5.0.45-beta.0

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 2fc807d0..b8dddc29 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "openstack-uicore-foundation",
-    "version": "5.0.43",
+    "version": "5.0.45-beta.0",
     "description": "ui reactjs components for openstack marketing site",
     "main": "lib/openstack-uicore-foundation.js",
     "scripts": {