@oneuptime/common 12.0.13 → 12.0.14

package/Tests/UI/Components/Forms/Utils/FormFieldSchemaTypeUtil.test.ts

@@ -0,0 +1,267 @@
+import FieldType from "../../../../../UI/Components/Types/FieldType";
+import FormFieldSchemaType from "../../../../../UI/Components/Forms/Types/FormFieldSchemaType";
+import FormFieldSchemaTypeUtil from "../../../../../UI/Components/Forms/Utils/FormFieldSchemaTypeUtil";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * FormFieldSchemaTypeUtil.toFieldType maps a form's high-level schema type onto
+ * the lower-level FieldType the renderer understands. The implementation is a
+ * pure switch, so every case is a fixed input -> fixed output with no time,
+ * network, database or randomness involved — all assertions below are
+ * deterministic.
+ */
+
+interface SchemaToFieldExpectation {
+  schemaType: FormFieldSchemaType;
+  expected: FieldType;
+}
+
+/*
+ * The full, hand-checked mapping table — one row per FormFieldSchemaType member.
+ * This is the backbone of the suite: it pins down the exact FieldType every
+ * schema type collapses to, including the several many-to-one and renamed
+ * cases (for example Time -> DateTime, Domain -> Text, Query -> Element).
+ */
+const expectations: Array<SchemaToFieldExpectation> = [
+  { schemaType: FormFieldSchemaType.ObjectID, expected: FieldType.ObjectID },
+  { schemaType: FormFieldSchemaType.Name, expected: FieldType.Name },
+  { schemaType: FormFieldSchemaType.Hostname, expected: FieldType.Hostname },
+  { schemaType: FormFieldSchemaType.ImageFile, expected: FieldType.ImageFile },
+  { schemaType: FormFieldSchemaType.URL, expected: FieldType.URL },
+  { schemaType: FormFieldSchemaType.Route, expected: FieldType.Route },
+  { schemaType: FormFieldSchemaType.Number, expected: FieldType.Number },
+  { schemaType: FormFieldSchemaType.Password, expected: FieldType.Password },
+  { schemaType: FormFieldSchemaType.Text, expected: FieldType.Text },
+  { schemaType: FormFieldSchemaType.Time, expected: FieldType.DateTime },
+  { schemaType: FormFieldSchemaType.Email, expected: FieldType.Email },
+  {
+    schemaType: FormFieldSchemaType.PositiveNumber,
+    expected: FieldType.Number,
+  },
+  { schemaType: FormFieldSchemaType.Date, expected: FieldType.Date },
+  { schemaType: FormFieldSchemaType.Phone, expected: FieldType.Phone },
+  { schemaType: FormFieldSchemaType.DateTime, expected: FieldType.DateTime },
+  { schemaType: FormFieldSchemaType.Domain, expected: FieldType.Text },
+  { schemaType: FormFieldSchemaType.LongText, expected: FieldType.LongText },
+  { schemaType: FormFieldSchemaType.Color, expected: FieldType.Color },
+  { schemaType: FormFieldSchemaType.Dropdown, expected: FieldType.Dropdown },
+  { schemaType: FormFieldSchemaType.File, expected: FieldType.File },
+  {
+    schemaType: FormFieldSchemaType.MultiSelectDropdown,
+    expected: FieldType.MultiSelectDropdown,
+  },
+  {
+    schemaType: FormFieldSchemaType.OptionChooserButton,
+    expected: FieldType.Element,
+  },
+  { schemaType: FormFieldSchemaType.Toggle, expected: FieldType.Boolean },
+  { schemaType: FormFieldSchemaType.Port, expected: FieldType.Port },
+  {
+    schemaType: FormFieldSchemaType.EncryptedText,
+    expected: FieldType.HiddenText,
+  },
+  { schemaType: FormFieldSchemaType.Markdown, expected: FieldType.Markdown },
+  {
+    schemaType: FormFieldSchemaType.JavaScript,
+    expected: FieldType.JavaScript,
+  },
+  { schemaType: FormFieldSchemaType.CSS, expected: FieldType.CSS },
+  { schemaType: FormFieldSchemaType.HTML, expected: FieldType.HTML },
+  { schemaType: FormFieldSchemaType.RadioButton, expected: FieldType.Text },
+  { schemaType: FormFieldSchemaType.JSON, expected: FieldType.JSON },
+  { schemaType: FormFieldSchemaType.Query, expected: FieldType.Element },
+  {
+    schemaType: FormFieldSchemaType.CustomComponent,
+    expected: FieldType.Element,
+  },
+  { schemaType: FormFieldSchemaType.Checkbox, expected: FieldType.Boolean },
+  {
+    schemaType: FormFieldSchemaType.CategoryCheckbox,
+    expected: FieldType.Boolean,
+  },
+  { schemaType: FormFieldSchemaType.Icon, expected: FieldType.Icon },
+  /*
+   * These three schema types have no explicit case in the switch and therefore
+   * fall through to the default arm, which returns Text. They are listed here
+   * so the exhaustiveness guard below sees them and so their default-path
+   * behaviour is asserted alongside every other member.
+   */
+  { schemaType: FormFieldSchemaType.MultipleFiles, expected: FieldType.Text },
+  { schemaType: FormFieldSchemaType.Dictionary, expected: FieldType.Text },
+  { schemaType: FormFieldSchemaType.CardSelect, expected: FieldType.Text },
+];
+
+describe("FormFieldSchemaTypeUtil.toFieldType — full mapping table", () => {
+  test.each(expectations)(
+    "maps schema type $schemaType to field type $expected",
+    (expectation: SchemaToFieldExpectation): void => {
+      const actual: FieldType = FormFieldSchemaTypeUtil.toFieldType(
+        expectation.schemaType,
+      );
+
+      expect(actual).toBe(expectation.expected);
+    },
+  );
+});
+
+describe("FormFieldSchemaTypeUtil.toFieldType — many-to-one and renamed cases", () => {
+  /*
+   * Several schema types deliberately do NOT map to a like-named FieldType.
+   * These are the cases most likely to break silently under a careless edit, so
+   * each is spelled out on its own to document the intended collapse.
+   */
+  test("Time renders as a DateTime field", () => {
+    expect(FormFieldSchemaTypeUtil.toFieldType(FormFieldSchemaType.Time)).toBe(
+      FieldType.DateTime,
+    );
+  });
+
+  test("PositiveNumber renders as a plain Number field", () => {
+    expect(
+      FormFieldSchemaTypeUtil.toFieldType(FormFieldSchemaType.PositiveNumber),
+    ).toBe(FieldType.Number);
+  });
+
+  test("Domain and RadioButton both render as Text fields", () => {
+    expect(
+      FormFieldSchemaTypeUtil.toFieldType(FormFieldSchemaType.Domain),
+    ).toBe(FieldType.Text);
+    expect(
+      FormFieldSchemaTypeUtil.toFieldType(FormFieldSchemaType.RadioButton),
+    ).toBe(FieldType.Text);
+  });
+
+  test("EncryptedText renders as a HiddenText field", () => {
+    expect(
+      FormFieldSchemaTypeUtil.toFieldType(FormFieldSchemaType.EncryptedText),
+    ).toBe(FieldType.HiddenText);
+  });
+
+  test("OptionChooserButton, Query and CustomComponent all render as Element fields", () => {
+    const elementSchemaTypes: Array<FormFieldSchemaType> = [
+      FormFieldSchemaType.OptionChooserButton,
+      FormFieldSchemaType.Query,
+      FormFieldSchemaType.CustomComponent,
+    ];
+
+    for (const schemaType of elementSchemaTypes) {
+      expect(FormFieldSchemaTypeUtil.toFieldType(schemaType)).toBe(
+        FieldType.Element,
+      );
+    }
+  });
+
+  test("Toggle, Checkbox and CategoryCheckbox all render as Boolean fields", () => {
+    const booleanSchemaTypes: Array<FormFieldSchemaType> = [
+      FormFieldSchemaType.Toggle,
+      FormFieldSchemaType.Checkbox,
+      FormFieldSchemaType.CategoryCheckbox,
+    ];
+
+    for (const schemaType of booleanSchemaTypes) {
+      expect(FormFieldSchemaTypeUtil.toFieldType(schemaType)).toBe(
+        FieldType.Boolean,
+      );
+    }
+  });
+});
+
+describe("FormFieldSchemaTypeUtil.toFieldType — default fallback", () => {
+  /*
+   * The switch matches on the enum's string VALUE. An input whose value is not a
+   * known schema type must land on the default arm and come back as Text rather
+   * than throwing or returning undefined.
+   */
+  test("an unrecognised value falls back to Text", () => {
+    expect(
+      FormFieldSchemaTypeUtil.toFieldType(
+        "definitely-not-a-schema-type" as FormFieldSchemaType,
+      ),
+    ).toBe(FieldType.Text);
+  });
+
+  test("an empty string falls back to Text", () => {
+    expect(FormFieldSchemaTypeUtil.toFieldType("" as FormFieldSchemaType)).toBe(
+      FieldType.Text,
+    );
+  });
+
+  test("the enum members with no explicit case (MultipleFiles, Dictionary, CardSelect) fall back to Text", () => {
+    expect(
+      FormFieldSchemaTypeUtil.toFieldType(FormFieldSchemaType.MultipleFiles),
+    ).toBe(FieldType.Text);
+    expect(
+      FormFieldSchemaTypeUtil.toFieldType(FormFieldSchemaType.Dictionary),
+    ).toBe(FieldType.Text);
+    expect(
+      FormFieldSchemaTypeUtil.toFieldType(FormFieldSchemaType.CardSelect),
+    ).toBe(FieldType.Text);
+  });
+});
+
+describe("FormFieldSchemaTypeUtil.toFieldType — the Toggle value quirk", () => {
+  /*
+   * FormFieldSchemaType.Toggle is unusual: its member name is Toggle but its
+   * string value is "Boolean". Because the switch compares the underlying
+   * string value, feeding the raw literal "Boolean" must resolve to the Toggle
+   * case (Boolean), not to the default arm.
+   */
+  test("the Toggle member's underlying string value is 'Boolean'", () => {
+    expect(FormFieldSchemaType.Toggle).toBe("Boolean");
+  });
+
+  test("the raw literal 'Boolean' resolves to the Toggle case", () => {
+    expect(
+      FormFieldSchemaTypeUtil.toFieldType("Boolean" as FormFieldSchemaType),
+    ).toBe(FieldType.Boolean);
+  });
+});
+
+describe("FormFieldSchemaTypeUtil.toFieldType — structural guarantees", () => {
+  test("covers every FormFieldSchemaType member (guards against a new, unmapped type)", () => {
+    const coveredValues: Set<string> = new Set(
+      expectations.map((expectation: SchemaToFieldExpectation): string => {
+        return expectation.schemaType;
+      }),
+    );
+    const allSchemaValues: Array<string> = Object.values(FormFieldSchemaType);
+
+    for (const schemaValue of allSchemaValues) {
+      expect(coveredValues.has(schemaValue)).toBe(true);
+    }
+
+    /*
+     * Every schema value is unique, so the covered set and the enum must be the
+     * same size. If a member is added to the enum this fails, flagging that the
+     * mapping (and this table) needs updating.
+     */
+    expect(coveredValues.size).toBe(allSchemaValues.length);
+  });
+
+  test("always returns a defined value that is a real FieldType member", () => {
+    const validFieldTypes: Set<string> = new Set(Object.values(FieldType));
+
+    for (const schemaValue of Object.values(FormFieldSchemaType)) {
+      const result: FieldType = FormFieldSchemaTypeUtil.toFieldType(
+        schemaValue as FormFieldSchemaType,
+      );
+
+      expect(result).toBeDefined();
+      expect(validFieldTypes.has(result)).toBe(true);
+    }
+  });
+
+  test("is pure — the same input yields the same output every time", () => {
+    for (const expectation of expectations) {
+      const first: FieldType = FormFieldSchemaTypeUtil.toFieldType(
+        expectation.schemaType,
+      );
+      const second: FieldType = FormFieldSchemaTypeUtil.toFieldType(
+        expectation.schemaType,
+      );
+
+      expect(first).toBe(second);
+      expect(first).toBe(expectation.expected);
+    }
+  });
+});

package/Tests/UI/Components/List.test.tsx

@@ -63,10 +63,17 @@ describe("List", () => {
     expect(screen.getByTestId("list-pagination")).toBeInTheDocument();
   });
 
-  it("renders loading state", () => {
+  it("renders skeleton cards while loading with nothing to show yet", () => {
+    render(<List {...defaultProps} isLoading={true} data={[]} />);
+
+    expect(screen.getByTestId("list-skeleton-loader")).toBeInTheDocument();
+  });
+
+  it("keeps existing cards visible, dimmed, while refetching", () => {
     render(<List {...defaultProps} isLoading={true} />);
 
-    expect(screen.getByTestId("component-loader")).toBeInTheDocument();
+    expect(screen.queryByTestId("list-skeleton-loader")).toBeNull();
+    expect(screen.getByTestId("list-content")).toHaveClass("opacity-60");
   });
 
   it("renders error state", () => {

package/Tests/UI/Components/ListLoadingStates.test.tsx

@@ -0,0 +1,173 @@
+import List, { ComponentProps } from "../../../UI/Components/List/List";
+import FieldType from "../../../UI/Components/Types/FieldType";
+import "@testing-library/jest-dom";
+import { describe, expect, it, jest } from "@jest/globals";
+import { render, screen } from "@testing-library/react";
+import React from "react";
+
+/*
+ * The list's loading contract, mirroring the table's: a first load (nothing
+ * fetched yet) renders card-shaped skeletons in ListBody's own wrapper so
+ * nothing shifts when data lands; a refetch keeps the stale cards visible,
+ * dimmed and unclickable; error and empty only speak once loading finishes.
+ */
+
+describe("List loading states", () => {
+  interface ListData {
+    id: string;
+    name: string;
+    description: string;
+  }
+
+  const fields: ComponentProps<ListData>["fields"] = [
+    {
+      title: "ID",
+      key: "id",
+      fieldType: FieldType.Text,
+      colSpan: 1,
+    },
+    {
+      title: "Name",
+      key: "name",
+      fieldType: FieldType.Text,
+      colSpan: 2,
+    },
+    {
+      title: "Description",
+      key: "description",
+      fieldType: FieldType.Text,
+      colSpan: 2,
+    },
+  ];
+
+  const defaultProps: ComponentProps<ListData> = {
+    data: [
+      { id: "1", name: "Item 1", description: "Description 1" },
+      { id: "2", name: "Item 2", description: "Description 2" },
+    ],
+    id: "test-list",
+    fields: fields,
+    onNavigateToPage: jest.fn(),
+    currentPageNumber: 1,
+    totalItemsCount: 10,
+    itemsOnPage: 10,
+    error: "",
+    isLoading: false,
+    singularLabel: "Item",
+    pluralLabel: "Items",
+  };
+
+  describe("first load (nothing to show yet)", () => {
+    it("renders skeleton cards instead of a spinner", () => {
+      render(<List {...defaultProps} isLoading={true} data={[]} />);
+
+      expect(screen.getByTestId("list-skeleton-loader")).toBeInTheDocument();
+      expect(screen.queryByTestId("component-loader")).toBeNull();
+    });
+
+    it("announces itself as a polite status with a Loading label", () => {
+      render(<List {...defaultProps} isLoading={true} data={[]} />);
+
+      const loader: HTMLElement = screen.getByTestId("list-skeleton-loader");
+      expect(loader).toHaveAttribute("role", "status");
+      expect(loader).toHaveAttribute("aria-live", "polite");
+      expect(loader).toHaveTextContent("Loading");
+    });
+
+    it("matches ListBody's wrapper so nothing shifts when data lands", () => {
+      render(<List {...defaultProps} isLoading={true} data={[]} />);
+
+      expect(screen.getByTestId("list-skeleton-loader")).toHaveClass(
+        "space-y-6",
+        "p-6",
+        "border-t",
+      );
+    });
+
+    it("renders one card per item on the page, capped at 6", () => {
+      render(
+        <List {...defaultProps} isLoading={true} data={[]} itemsOnPage={25} />,
+      );
+
+      const loader: HTMLElement = screen.getByTestId("list-skeleton-loader");
+      expect(loader.querySelectorAll(":scope > div")).toHaveLength(6);
+    });
+
+    it("renders fewer cards for a smaller page size", () => {
+      render(
+        <List {...defaultProps} isLoading={true} data={[]} itemsOnPage={3} />,
+      );
+
+      const loader: HTMLElement = screen.getByTestId("list-skeleton-loader");
+      expect(loader.querySelectorAll(":scope > div")).toHaveLength(3);
+    });
+
+    it("gives each card one placeholder line per field", () => {
+      render(<List {...defaultProps} isLoading={true} data={[]} />);
+
+      const loader: HTMLElement = screen.getByTestId("list-skeleton-loader");
+      const firstCard: Element = loader.querySelectorAll(
+        ":scope > div",
+      )[0] as Element;
+
+      expect(
+        firstCard.querySelectorAll('[data-testid="skeleton"]'),
+      ).toHaveLength(fields.length);
+    });
+  });
+
+  describe("refetch with cards already on screen", () => {
+    it("keeps the real cards and shows no skeletons", () => {
+      render(<List {...defaultProps} isLoading={true} />);
+
+      expect(screen.queryByTestId("list-skeleton-loader")).toBeNull();
+      expect(screen.getByText("Item 1")).toBeInTheDocument();
+    });
+
+    it("dims the stale cards and blocks pointer events on them", () => {
+      render(<List {...defaultProps} isLoading={true} />);
+
+      const content: HTMLElement = screen.getByTestId("list-content");
+      expect(content).toHaveClass("opacity-60");
+      expect(content).toHaveClass("pointer-events-none");
+    });
+
+    it("an idle list is neither dimmed nor blocked", () => {
+      render(<List {...defaultProps} />);
+
+      const content: HTMLElement = screen.getByTestId("list-content");
+      expect(content).not.toHaveClass("opacity-60");
+      expect(content).not.toHaveClass("pointer-events-none");
+    });
+
+    /*
+     * Loading outranks error: mid-refetch the error prop can only be stale
+     * (the parent clears it before every fetch), so surfacing it over live
+     * cards would report a failure that is not happening.
+     */
+    it("a stale error does not interrupt the dimmed cards", () => {
+      render(<List {...defaultProps} isLoading={true} error="stale failure" />);
+
+      expect(screen.getByText("Item 1")).toBeInTheDocument();
+      expect(screen.queryByText("stale failure")).toBeNull();
+    });
+  });
+
+  describe("after loading finishes", () => {
+    it("an error replaces the cards", () => {
+      render(<List {...defaultProps} error="Something went wrong" />);
+
+      expect(screen.getByText("Something went wrong")).toBeInTheDocument();
+      expect(screen.queryByTestId("list-skeleton-loader")).toBeNull();
+    });
+
+    it("an empty result shows the no-items message, not skeletons", () => {
+      render(
+        <List {...defaultProps} data={[]} noItemsMessage="Nothing here" />,
+      );
+
+      expect(screen.getByText("Nothing here")).toBeInTheDocument();
+      expect(screen.queryByTestId("list-skeleton-loader")).toBeNull();
+    });
+  });
+});

package/Tests/UI/Components/MarkdownLazy.test.tsx

@@ -0,0 +1,113 @@
+/*
+ * Perf contract for MarkdownViewer's mermaid integration (linear-polish):
+ * mermaid's pre-bundled build is ~4.5MB — it used to be statically imported
+ * and initialized at module scope, which dragged it into the Dashboard's
+ * eager first-load graph through every markdown call site. The contract now
+ * is: importing MarkdownViewer and rendering plain markdown must NEVER load
+ * mermaid; only a rendered mermaid diagram may trigger the dynamic import,
+ * and theme initialization must happen after that load.
+ *
+ * The jest module registry is the probe: the "mermaid" factory below flips a
+ * sentinel when the module is actually required, which under ts-jest's
+ * CommonJS output happens exactly when the component executes its dynamic
+ * import(). (Common/jest.config.json maps "mermaid" to a stub via
+ * moduleNameMapper, but an explicit jest.mock factory takes precedence.)
+ */
+import { afterEach, describe, expect, jest, test } from "@jest/globals";
+
+interface MockMermaidState {
+  required: boolean;
+  initializeCalls: Array<unknown>;
+  renderCalls: Array<string>;
+}
+
+const mockMermaidState: MockMermaidState = {
+  required: false,
+  initializeCalls: [],
+  renderCalls: [],
+};
+
+jest.mock("mermaid", () => {
+  // Runs only when something actually requires mermaid — the sentinel.
+  mockMermaidState.required = true;
+  return {
+    __esModule: true,
+    default: {
+      initialize: (config: unknown): void => {
+        mockMermaidState.initializeCalls.push(config);
+      },
+      render: (_id: string, chart: string): Promise<{ svg: string }> => {
+        mockMermaidState.renderCalls.push(chart);
+        return Promise.resolve({
+          svg: '<svg><g data-diagram="true"></g></svg>',
+        });
+      },
+    },
+  };
+});
+
+import "@testing-library/jest-dom";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import React from "react";
+import MarkdownViewer, {
+  MermaidDiagram,
+} from "../../../UI/Components/Markdown.tsx/MarkdownViewer";
+
+/*
+ * Captured immediately after the static import above: if MarkdownViewer ever
+ * regresses to a module-scope `import mermaid from "mermaid"` (or a
+ * module-scope initialize call), this flips to true before any test runs.
+ */
+const mermaidRequiredAtModuleLoad: boolean = mockMermaidState.required;
+
+afterEach(() => {
+  cleanup();
+});
+
+/*
+ * NOTE: test order inside this file is load-bearing. The sentinel is
+ * one-directional (a module stays required for the rest of the process), so
+ * the "never loads" assertions must run before the test that legitimately
+ * triggers the load.
+ */
+describe("MarkdownViewer lazy mermaid contract", () => {
+  test("importing the MarkdownViewer module does not require mermaid", () => {
+    expect(mermaidRequiredAtModuleLoad).toBe(false);
+  });
+
+  test("rendering plain markdown does not require mermaid", () => {
+    render(
+      <MarkdownViewer
+        text={"# Hello\n\nJust **plain** markdown with `inline code`."}
+      />,
+    );
+
+    const rendered: HTMLElement = screen.getByTestId("react-markdown");
+    expect(rendered).toBeInTheDocument();
+    expect(mockMermaidState.required).toBe(false);
+    expect(mockMermaidState.initializeCalls).toHaveLength(0);
+  });
+
+  test("rendering a mermaid diagram dynamically loads mermaid, then initializes and renders", async () => {
+    const chart: string = "graph TD; A-->B";
+    const { container } = render(<MermaidDiagram chart={chart} />);
+
+    // The load + render pipeline is async (dynamic import then render()).
+    await waitFor((): void => {
+      expect(mockMermaidState.renderCalls).toContain(chart);
+    });
+
+    expect(mockMermaidState.required).toBe(true);
+
+    /*
+     * Theme setup must run post-load and before render: with no module-scope
+     * initialization left, the only way initialize() can have been called is
+     * from the diagram's own effect after the dynamic import resolved.
+     */
+    expect(mockMermaidState.initializeCalls.length).toBeGreaterThan(0);
+
+    await waitFor((): void => {
+      expect(container.querySelector("svg")).not.toBeNull();
+    });
+  });
+});

package/Tests/UI/Components/MarkdownMermaidRetry.test.tsx

@@ -0,0 +1,110 @@
+/*
+ * Retry contract for MarkdownViewer's lazy mermaid load (linear-polish):
+ * loadMermaid() caches the dynamic-import promise module-wide so multiple
+ * diagrams share one load — but a REJECTED load (flaky network, a deploy
+ * rotating hashed chunk names) must not be cached forever. The contract is:
+ * the diagram that triggered the failed load shows its error state, and the
+ * next diagram mount retries the import from scratch.
+ *
+ * This lives in its own file rather than MarkdownLazy.test.tsx because that
+ * file's sentinel design is one-directional: once its legitimate-load test
+ * has run, jest's mock registry AND the component's module-scope cache both
+ * hold the successfully resolved module for the rest of the process, so a
+ * failure can no longer be staged there (jest.resetModules() is no escape —
+ * it would fork React's identity out from under @testing-library). Here the
+ * FIRST require of "mermaid" throws instead: jest memoizes a mock factory's
+ * result only after it returns, so a throwing factory is re-invoked on the
+ * next require — which is exactly the retry path under test.
+ */
+import { afterEach, describe, expect, jest, test } from "@jest/globals";
+
+interface MockMermaidState {
+  factoryAttempts: number;
+  failNextRequire: boolean;
+  renderCalls: Array<string>;
+}
+
+const mockMermaidState: MockMermaidState = {
+  factoryAttempts: 0,
+  failNextRequire: true,
+  renderCalls: [],
+};
+
+jest.mock("mermaid", () => {
+  // Runs on every require until it returns once — then jest memoizes it.
+  mockMermaidState.factoryAttempts++;
+  if (mockMermaidState.failNextRequire) {
+    mockMermaidState.failNextRequire = false;
+    throw new Error("simulated mermaid chunk load failure");
+  }
+  return {
+    __esModule: true,
+    default: {
+      initialize: (): void => {
+        // theme setup is exercised in MarkdownLazy.test.tsx — a no-op here.
+      },
+      render: (_id: string, chart: string): Promise<{ svg: string }> => {
+        mockMermaidState.renderCalls.push(chart);
+        return Promise.resolve({
+          svg: '<svg><g data-diagram="true"></g></svg>',
+        });
+      },
+    },
+  };
+});
+
+import "@testing-library/jest-dom";
+import { cleanup, render, waitFor } from "@testing-library/react";
+import React from "react";
+import { MermaidDiagram } from "../../../UI/Components/Markdown.tsx/MarkdownViewer";
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("MarkdownViewer mermaid load retry contract", () => {
+  test("a failed chunk load surfaces as the diagram's error state, and the next mount retries and succeeds", async () => {
+    const chart: string = "graph TD; A-->B";
+
+    /*
+     * First mount: the dynamic import rejects (the mock factory throws on
+     * the first require). The diagram must fall into its error path, not
+     * hang or crash the tree.
+     */
+    const first: ReturnType<typeof render> = render(
+      <MermaidDiagram chart={chart} />,
+    );
+
+    await waitFor((): void => {
+      expect(
+        first.container.querySelector("pre.text-red-500")?.textContent,
+      ).toContain("Error rendering diagram");
+    });
+
+    expect(mockMermaidState.factoryAttempts).toBe(1);
+    expect(mockMermaidState.renderCalls).toHaveLength(0);
+
+    first.unmount();
+
+    /*
+     * Second mount: the rejected load must NOT have been cached — the
+     * component retries the import, which now succeeds, and the diagram
+     * renders. Before the fix, the module-scope promise cache pinned the
+     * first rejection forever and this mount showed the error again.
+     */
+    const second: ReturnType<typeof render> = render(
+      <MermaidDiagram chart={chart} />,
+    );
+
+    await waitFor((): void => {
+      expect(mockMermaidState.renderCalls).toContain(chart);
+    });
+
+    expect(mockMermaidState.factoryAttempts).toBe(2);
+
+    await waitFor((): void => {
+      expect(second.container.querySelector("svg")).not.toBeNull();
+    });
+    expect(second.container.querySelector("pre.text-red-500")).toBeNull();
+  });
+});