MetaMask · itsyoboieltr · Nov 24, 2025 · Nov 20, 2025 · Nov 20, 2025 · Nov 20, 2025
diff --git a/app/background.html b/app/background.html
diff --git a/app/home.html b/app/home.html
diff --git a/app/html/pages/background.html b/app/html/pages/background.html
@@ -0,0 +1,10 @@
+<!doctype html>
+<html dir="ltr">
+  <head>
+    <meta charset="utf-8" />
+  </head>
+  <body>
+    <script src="../../scripts/load/bootstrap.ts" defer></script>
+    <script src="../../scripts/load/background.ts" defer></script>
+  </body>
+</html>
diff --git a/app/html/pages/home.html b/app/html/pages/home.html
@@ -0,0 +1,9 @@
+<!doctype html>
+<html dir="ltr">
+  <head>
+    <%~ include("html/partials/partial-head.html") %>
+  </head>
+  <body>
+    <%~ include("html/partials/partial-body.html") %>
+  </body>
+</html>
diff --git a/app/loading.html → app/html/pages/loading.html b/app/loading.html → app/html/pages/loading.html
@@ -7,7 +7,7 @@
   <title>MetaMask Loading</title>
   <% if (it.shouldIncludeSnow) { %>
   <script src="@lavamoat/snow/snow.prod.js"></script>
-  <script src="./scripts/use-snow.js"></script>
+  <script src="../../scripts/use-snow.js"></script>
   <% } %>
   <style>
     #div-logo {
@@ -37,7 +37,7 @@
 </head>
 <body>
   <div id="div-logo">
-    <img id="logo" src="./images/enslogo.svg" loading="lazy">
+    <img id="logo" src="../../images/enslogo.svg" loading="lazy">
     <h1 class="center">MetaMask is querying ENS ...</h1>
   </div>
 </body>

diff --git a/app/notification.html → app/html/pages/notification.html b/app/notification.html → app/html/pages/notification.html
@@ -1,12 +1,12 @@
 <!doctype html>
 <html dir="ltr">
   <head>
-    <%~ include("partial-head.html", {
+    <%~ include("html/partials/partial-head.html", {
       title: it.isTest ? "MetaMask Dialog" : null,
       viewport: "width=device-width, initial-scale=1.0"
     }) %>
   </head>
   <body class="notification">
-    <%~ include("partial-body.html") %>
+    <%~ include("html/partials/partial-body.html") %>
   </body>
 </html>
diff --git a/app/offscreen.html → app/html/pages/offscreen.html b/app/offscreen.html → app/html/pages/offscreen.html
@@ -5,6 +5,6 @@
     <title>MetaMask Offscreen Page</title>
   </head>
   <body>
-    <script src="./offscreen/offscreen.ts" defer></script>
+    <script src="../../offscreen/offscreen.ts" defer></script>
   </body>
 </html>
diff --git a/app/popup-init.html → app/html/pages/popup-init.html b/app/popup-init.html → app/html/pages/popup-init.html
diff --git a/app/popup.html → app/html/pages/popup.html b/app/popup.html → app/html/pages/popup.html
@@ -1,9 +1,9 @@
 <!doctype html>
 <html style="width:400px; height:600px;" dir="ltr">
   <head>
-    <%~ include("partial-head.html") %>
+    <%~ include("html/partials/partial-head.html") %>
   </head>
   <body style="width:400px; height:600px;">
-    <%~ include("partial-body.html") %>
+    <%~ include("html/partials/partial-body.html") %>
   </body>
 </html>
diff --git a/app/sidepanel.html → app/html/pages/sidepanel.html b/app/sidepanel.html → app/html/pages/sidepanel.html
@@ -1,9 +1,9 @@
 <!doctype html>
 <html style="width:100%; height:100%;" dir="ltr">
   <head>
-    <%~ include("partial-head.html") %>
+    <%~ include("html/partials/partial-head.html") %>
   </head>
   <body style="width:100%; height:100%;">
-    <%~ include("partial-body.html") %>
+    <%~ include("html/partials/partial-body.html") %>
   </body>
 </html>
diff --git a/app/trezor-usb-permissions.html → app/html/pages/trezor-usb-permissions.html b/app/trezor-usb-permissions.html → app/html/pages/trezor-usb-permissions.html
@@ -7,7 +7,7 @@
     <title>TrezorConnect | Trezor</title>
     <% if (it.shouldIncludeSnow) { %>
     <script src="@lavamoat/snow/snow.prod.js"></script>
-    <script src="./scripts/use-snow.js"></script>
+    <script src="../../scripts/use-snow.js"></script>
     <% } %>
     <meta name="description" content="" />
     <meta name="keywords" content="" />
@@ -33,5 +33,5 @@
 </head>
 <body>
     <iframe id="trezor-usb-permissions" src="https://connect.trezor.io/9/extension-permissions.html" allow="usb" frameborder="0" width="100%" height="100%"></iframe>
-    <script src="./vendor/trezor/usb-permissions.js"></script>
+    <script src="../../vendor/trezor/usb-permissions.js"></script>
 </body>
diff --git a/app/html/partials/partial-body.html b/app/html/partials/partial-body.html
@@ -0,0 +1,8 @@
+<div id="app-content">
+  <img class="loading-logo" src="../../images/logo/metamask-fox.svg" alt="" loading="lazy" />
+  <img class="loading-spinner" src="../../images/spinner.gif" alt="" loading="lazy" />
+  <div class="loading-timeout-message" aria-live="polite" role="status"></div>
+</div>
+<div id="popover-content"></div>
+<script src="../../scripts/load/bootstrap.ts" defer></script>
+<script src="../../scripts/load/ui.ts" defer></script>
diff --git a/app/partial-head.html → app/html/partials/partial-head.html b/app/partial-head.html → app/html/partials/partial-head.html
@@ -2,4 +2,4 @@
 <meta name="viewport" content="<%= it?.viewport ?? "width=device-width, initial-scale=1, user-scalable=no" %>" />
 <title><%= it?.title ?? "MetaMask" %></title>
 <link rel="preload" href="/_locales/en/messages.json" as="fetch" type="application/json" crossorigin="anonymous" />
-<link rel="stylesheet" href="../ui/css/index.scss" />
+<link rel="stylesheet" href="../../../ui/css/index.scss" />
diff --git a/app/partial-body.html b/app/partial-body.html
diff --git a/development/build/scripts.js b/development/build/scripts.js
@@ -1301,27 +1301,44 @@ function renderHtmlFile({
 
   const scriptTags = scripts.join('\n    ');
 
-  const htmlFilePath = `./app/${htmlName}.html`;
+  const htmlFilePath = `./app/html/pages/${htmlName}.html`;
   const htmlTemplate = readFileSync(htmlFilePath, 'utf8');
 
   const eta = new Eta({ views: './app/' });
   const htmlOutput = eta
     .renderString(htmlTemplate, { isTest, shouldIncludeSnow })
     // these replacements are added to support the webpack build's automatic
     // compilation of html files, which the gulp-based process doesn't support.
-    .replace('./scripts/load/background.ts', './load-background.js')
+    .replace('../../scripts/load/background.ts', './load-background.js')
     .replace(
       '<script src="./load-background.js" defer></script>',
       `${scriptTags}\n    <script src="./chromereload.js" async></script>`,
     )
-    .replace('<script src="./scripts/load/ui.ts" defer></script>', scriptTags)
     .replace(
-      '<script src="./offscreen/offscreen.ts" defer></script>',
+      '<script src="../../scripts/load/ui.ts" defer></script>',
       scriptTags,
     )
-    .replace('../ui/css/index.scss', './index.css')
+    .replace(
+      '<script src="../../offscreen/offscreen.ts" defer></script>',
+      scriptTags,
+    )
+    .replace('../../../ui/css/index.scss', './index.css')
     .replace('@lavamoat/snow/snow.prod.js', './scripts/snow.js')
-    .replace('<script src="./scripts/load/bootstrap.ts" defer></script>', '');
+    .replace('../../scripts/use-snow.js', './scripts/use-snow.js')
+    .replace(
+      '<script src="../../scripts/load/bootstrap.ts" defer></script>',
+      '',
+    )
+    .replace('../../images/enslogo.svg', './images/enslogo.svg')
+    .replace(
+      '../../images/logo/metamask-fox.svg',
+      './images/logo/metamask-fox.svg',
+    )
+    .replace('../../images/spinner.gif', './images/spinner.gif')
+    .replace(
+      '../../vendor/trezor/usb-permissions.js',
+      './vendor/trezor/usb-permissions.js',
+    );
   browserPlatforms.forEach((platform) => {
     const dest = `./dist/${platform}/${htmlName}.html`;
     // we dont have a way of creating async events atm

diff --git a/development/webpack/test/helpers.test.ts b/development/webpack/test/helpers.test.ts
@@ -25,10 +25,11 @@ describe('./utils/helpers.ts', () => {
     const originalReaddirSync = fs.readdirSync;
     const otherHtmlEntries = ['one.html', 'two.html'];
     const appRoot = '<app-root>';
+    const htmlPages = join(appRoot, 'html', 'pages');
     // TODO: Fix in https://github.com/MetaMask/metamask-extension/issues/31973
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     mock.method(fs, 'readdirSync', function (path: string, options: any) {
-      if (path === appRoot) {
+      if (path === htmlPages) {
         return [...otherHtmlEntries, 'three.not-html'];
       }
       return originalReaddirSync.call(fs, path, options);
@@ -102,9 +103,9 @@ describe('./utils/helpers.ts', () => {
       },
     };
     const expectedHtml = {
-      background: join(appRoot, `background.html`),
-      one: join(appRoot, `one.html`),
-      two: join(appRoot, `two.html`),
+      background: join(htmlPages, `background.html`),
+      one: join(htmlPages, `one.html`),
+      two: join(htmlPages, `two.html`),
       // notice: three.not-html is NOT included, since it doesn't have an `.html` extension
     };
     const expectedEntries = { ...expectedScripts, ...expectedHtml };
@@ -124,10 +125,11 @@ describe('./utils/helpers.ts', () => {
     const originalReaddirSync = fs.readdirSync;
     const otherHtmlEntries = ['one.html', 'two.html'];
     const appRoot = '<app-root>';
+    const htmlPages = join(appRoot, 'html', 'pages');
     // TODO: Fix in https://github.com/MetaMask/metamask-extension/issues/31973
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     mock.method(fs, 'readdirSync', (path: string, options: any) => {
-      if (path === appRoot) {
+      if (path === htmlPages) {
         return [...otherHtmlEntries, 'three.not-html'];
       }
       return originalReaddirSync.call(fs, path, options);
@@ -204,8 +206,8 @@ describe('./utils/helpers.ts', () => {
       },
     };
     const expectedHtml = {
-      one: join(appRoot, `one.html`),
-      two: join(appRoot, `two.html`),
+      one: join(htmlPages, `one.html`),
+      two: join(htmlPages, `two.html`),
       // notice: three.not-html is NOT included, since it doesn't have an `.html` extension
     };
     const expectedEntries = {
@@ -227,11 +229,12 @@ describe('./utils/helpers.ts', () => {
   it('should handle manifest.json files with empty sections', () => {
     const originalReaddirSync = fs.readdirSync;
     const appRoot = '<app-root>';
+    const htmlPages = join(appRoot, 'html', 'pages');
 
     // TODO: Fix in https://github.com/MetaMask/metamask-extension/issues/31973
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     mock.method(fs, 'readdirSync', (path: string, options: any) => {
-      if (path === appRoot) {
+      if (path === htmlPages) {
         return [];
       }
       return originalReaddirSync.call(fs, path, options);
@@ -258,21 +261,6 @@ describe('./utils/helpers.ts', () => {
     assert.deepStrictEqual(entryv3, {});
   });
 
-  it('should throw if an entry file starts with an underscore', () => {
-    const manifest = {
-      // TODO: Fix in https://github.com/MetaMask/metamask-extension/issues/31860
-      // eslint-disable-next-line @typescript-eslint/naming-convention
-      manifest_version: 2,
-      background: {
-        page: '_badfile.html',
-      },
-    } as helpers.ManifestV2;
-    assert.throws(
-      () => helpers.collectEntries(manifest, ''),
-      /Error: Invalid Entrypoint Filename Detected/u,
-    );
-  });
-
   describe('logStats', () => {
     const getStatsMock = (
       stats: 'normal' | 'none',

diff --git a/development/webpack/utils/helpers.ts b/development/webpack/utils/helpers.ts
@@ -1,5 +1,5 @@
 import { readdirSync } from 'node:fs';
-import { parse, join, relative, sep } from 'node:path';
+import { parse, join, sep } from 'node:path';
 import type { EntryObject, Stats } from 'webpack';
 import type TerserPluginType from 'terser-webpack-plugin';
 
@@ -80,6 +80,7 @@ export const extensionToJs = (filename: string) =>
  * that were added to it.
  */
 export function collectEntries(manifest: Manifest, appRoot: string) {
+  const htmlPages = join(appRoot, 'html', 'pages');
   const entry: EntryObject = {};
   /**
    * Scripts that must be self-contained and not split into chunks.
@@ -105,9 +106,8 @@ export function collectEntries(manifest: Manifest, appRoot: string) {
   }
 
   function addHtml(filename: string) {
-    assertValidEntryFileName(filename, appRoot);
     const parsedFileName = parse(filename).name;
-    entry[parsedFileName] = join(appRoot, filename);
+    entry[parsedFileName] = join(htmlPages, filename);
   }
 
   // add content_scripts to entries
@@ -144,7 +144,7 @@ export function collectEntries(manifest: Manifest, appRoot: string) {
     }
   }
 
-  for (const filename of readdirSync(appRoot)) {
+  for (const filename of readdirSync(htmlPages)) {
     // ignore non-htm/html files
     if (/\.html?$/iu.test(filename)) {
       // ignore background.html for MV2 as it was already handled above.
@@ -174,38 +174,6 @@ export function collectEntries(manifest: Manifest, appRoot: string) {
   return { entry, canBeChunked };
 }
 
-/**
- * @param filename
- * @param appRoot
- * @throws Throws an `Error` if the file is an invalid entrypoint filename
- * (a file starting with "_")
- */
-function assertValidEntryFileName(filename: string, appRoot: string) {
-  if (!filename.startsWith('_')) {
-    return;
-  }
-
-  const relativeFile = relative(process.cwd(), join(appRoot, filename));
-  const error = `Invalid Entrypoint Filename Detected\nPath: ${relativeFile}`;
-  const reason = `Filenames at the root of the extension directory starting with "_" are reserved for use by the browser.`;
-  const newFile = filename.slice(1);
-  const solutions = [
-    `Rename this file to remove the underscore, e.g., '${filename}' to '${newFile}'`,
-    `Move this file to a subdirectory and, if necessary, add it manually to the build 😱`,
-  ];
-  const context = `This file was included in the build automatically by our build script, which adds all HTML files at the root of '${appRoot}'.`;
-
-  const message = `${error}
-  Reason: ${reason}
-
-  Suggested Actions:
-  ${solutions.map((solution) => ` •  ${solution}`).join('\n')}
-  ${`\n ${context}`}
-  `;
-
-  throw new Error(message);
-}
-
 /**
  * It gets minimizers for the webpack build.
  */