From 68b4469dec4d3c4b8ed067ccd0291032a6b25353 Mon Sep 17 00:00:00 2001
From: Twelveeee <twelveeee12@gmail.com>
Date: Wed, 22 Apr 2026 16:23:16 +0800
Subject: [PATCH] feat: improve Cloudflare Temp Email random subdomain flow and
 sidepanel UX

---
 background.js                                 |   3 +
 background/generated-email-helpers.js         |   1 +
 sidepanel/sidepanel.css                       |  13 +
 sidepanel/sidepanel.html                      |  75 +++--
 sidepanel/sidepanel.js                        | 126 +++++++-
 ...und-cloudflare-temp-email-settings.test.js | 145 +++++++++
 .../background-generated-email-module.test.js | 169 +++++++++-
 ...dflare-temp-email-random-subdomain.test.js | 297 ++++++++++++++++++
 tests/sidepanel-contribution-mode.test.js     |   3 +
 9 files changed, 792 insertions(+), 40 deletions(-)
 create mode 100644 tests/background-cloudflare-temp-email-settings.test.js
 create mode 100644 tests/sidepanel-cloudflare-temp-email-random-subdomain.test.js

diff --git a/background.js b/background.js
index 7297909..3b68339 100644
--- a/background.js
+++ b/background.js
@@ -280,6 +280,7 @@ const PERSISTED_SETTING_DEFAULTS = {
   cloudflareTempEmailAdminAuth: '',
   cloudflareTempEmailCustomAuth: '',
   cloudflareTempEmailReceiveMailbox: '',
+  cloudflareTempEmailUseRandomSubdomain: false,
   cloudflareTempEmailDomain: '',
   cloudflareTempEmailDomains: [],
   hotmailAccounts: [],
@@ -827,6 +828,7 @@ function getCloudflareTempEmailConfig(state = {}) {
     adminAuth: String(state.cloudflareTempEmailAdminAuth || ''),
     customAuth: String(state.cloudflareTempEmailCustomAuth || ''),
     receiveMailbox: normalizeCloudflareTempEmailReceiveMailbox(state.cloudflareTempEmailReceiveMailbox),
+    useRandomSubdomain: Boolean(state.cloudflareTempEmailUseRandomSubdomain),
     domain: normalizeCloudflareTempEmailDomain(state.cloudflareTempEmailDomain),
     domains: normalizeCloudflareTempEmailDomains(state.cloudflareTempEmailDomains),
   };
@@ -895,6 +897,7 @@ function normalizePersistentSettingValue(key, value) {
       return normalizeEmailGenerator(value);
     case 'autoDeleteUsedIcloudAlias':
     case 'accountRunHistoryTextEnabled':
+    case 'cloudflareTempEmailUseRandomSubdomain':
       return Boolean(value);
     case 'icloudHostPreference':
       return normalizeIcloudHost(value) || 'auto';
diff --git a/background/generated-email-helpers.js b/background/generated-email-helpers.js
index 3d924a7..7db5c98 100644
--- a/background/generated-email-helpers.js
+++ b/background/generated-email-helpers.js
@@ -146,6 +146,7 @@
       const requestedName = String(options.localPart || options.name || '').trim().toLowerCase() || generateCloudflareAliasLocalPart();
       const payload = {
         enablePrefix: true,
+        enableRandomSubdomain: Boolean(config.useRandomSubdomain),
         name: requestedName,
         domain: config.domain,
       };
diff --git a/sidepanel/sidepanel.css b/sidepanel/sidepanel.css
index f40f857..aa9e607 100644
--- a/sidepanel/sidepanel.css
+++ b/sidepanel/sidepanel.css
@@ -2393,6 +2393,19 @@ header {
   line-height: 1.55;
   color: var(--text-secondary);
   margin-bottom: 14px;
+  white-space: pre-line;
+}
+
+.modal-message a,
+.modal-alert a {
+  color: var(--blue);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.modal-message a:hover,
+.modal-alert a:hover {
+  color: var(--cyan);
 }
 
 .modal-alert {
diff --git a/sidepanel/sidepanel.html b/sidepanel/sidepanel.html
index 6b75d35..7cb4fba 100644
--- a/sidepanel/sidepanel.html
+++ b/sidepanel/sidepanel.html
@@ -235,31 +235,6 @@
           <option value="cloudflare-temp-email">Cloudflare Temp Email</option>
         </select>
       </div>
-      <div class="data-row" id="row-temp-email-base-url" style="display:none;">
-        <span class="data-label">Temp API</span>
-        <input type="text" id="input-temp-email-base-url" class="data-input" placeholder="https://your-worker-domain" />
-      </div>
-      <div class="data-row" id="row-temp-email-admin-auth" style="display:none;">
-        <span class="data-label">Admin Auth</span>
-        <input type="password" id="input-temp-email-admin-auth" class="data-input data-input-with-icon" placeholder="Cloudflare Temp Email admin password" />
-      </div>
-      <div class="data-row" id="row-temp-email-custom-auth" style="display:none;">
-        <span class="data-label">Custom Auth</span>
-        <input type="password" id="input-temp-email-custom-auth" class="data-input data-input-with-icon" placeholder="仅当站点启用了访问密码时再填写；这是额外鉴权，不替代 Admin Auth。" />
-      </div>
-      <div class="data-row" id="row-temp-email-receive-mailbox" style="display:none;">
-        <span class="data-label">邮件接收</span>
-        <input type="text" id="input-temp-email-receive-mailbox" class="data-input" placeholder="用于接收转发邮件的邮箱，例如 1@email.example.com" />
-      </div>
-      <div class="data-row" id="row-temp-email-domain" style="display:none;">
-        <span class="data-label">Temp 域名</span>
-        <div class="data-inline">
-          <select id="select-temp-email-domain" class="data-select"></select>
-          <input type="text" id="input-temp-email-domain" class="data-input" placeholder="例如 mail.example.com"
-            style="display:none;" />
-          <button id="btn-temp-email-domain-mode" class="btn btn-outline btn-sm" type="button">添加</button>
-        </div>
-      </div>
       <div class="data-row" id="row-cf-domain" style="display:none;">
         <span class="data-label">CF 域名</span>
         <div class="data-inline">
@@ -389,6 +364,56 @@
       </div>
     </div>
     </div>
+    <div id="cloudflare-temp-email-section" class="data-card hotmail-card" style="display:none;">
+      <div class="section-mini-header">
+        <div class="section-mini-copy">
+          <span class="section-label">Cloudflare Temp Email</span>
+          <span class="data-value">用于生成邮箱或接收转发邮件</span>
+        </div>
+        <div class="section-mini-actions">
+          <button id="btn-cloudflare-temp-email-usage-guide" class="btn btn-ghost btn-xs" type="button">使用教程</button>
+          <button id="btn-cloudflare-temp-email-github" class="btn btn-ghost btn-xs" type="button">GitHub</button>
+        </div>
+      </div>
+      <div class="data-row" id="row-temp-email-base-url" style="display:none;">
+        <span class="data-label">Temp API</span>
+        <input type="text" id="input-temp-email-base-url" class="data-input" placeholder="https://your-worker-domain" />
+      </div>
+      <div class="data-row" id="row-temp-email-admin-auth" style="display:none;">
+        <span class="data-label">Admin Auth</span>
+        <input type="password" id="input-temp-email-admin-auth" class="data-input data-input-with-icon" placeholder="Cloudflare Temp Email admin password" />
+      </div>
+      <div class="data-row" id="row-temp-email-custom-auth" style="display:none;">
+        <span class="data-label">Custom Auth</span>
+        <input type="password" id="input-temp-email-custom-auth" class="data-input data-input-with-icon" placeholder="仅当站点启用了访问密码时再填写；这是额外鉴权，不替代 Admin Auth。" />
+      </div>
+      <div class="data-row" id="row-temp-email-receive-mailbox" style="display:none;">
+        <span class="data-label">邮件接收</span>
+        <input type="text" id="input-temp-email-receive-mailbox" class="data-input" placeholder="用于接收转发邮件的邮箱，例如 1@email.example.com" />
+      </div>
+      <div class="data-row" id="row-temp-email-random-subdomain-toggle" style="display:none;">
+        <span class="data-label">随机子域</span>
+        <div class="data-inline">
+          <label class="toggle-switch" for="input-temp-email-use-random-subdomain" title="依赖后端 RANDOM_SUBDOMAIN_DOMAINS 配置">
+            <input type="checkbox" id="input-temp-email-use-random-subdomain" />
+            <span class="toggle-switch-track" aria-hidden="true">
+              <span class="toggle-switch-thumb"></span>
+            </span>
+            <span>启用</span>
+          </label>
+          <span class="setting-caption">依赖后端 RANDOM_SUBDOMAIN_DOMAINS</span>
+        </div>
+      </div>
+      <div class="data-row" id="row-temp-email-domain" style="display:none;">
+        <span class="data-label">Temp 域名</span>
+        <div class="data-inline">
+          <select id="select-temp-email-domain" class="data-select"></select>
+          <input type="text" id="input-temp-email-domain" class="data-input" placeholder="例如 mail.example.com"
+            style="display:none;" />
+          <button id="btn-temp-email-domain-mode" class="btn btn-outline btn-sm" type="button">添加</button>
+        </div>
+      </div>
+    </div>
     <div id="hotmail-section" class="data-card hotmail-card" style="display:none;">
       <div class="section-mini-header">
         <div class="section-mini-copy">
diff --git a/sidepanel/sidepanel.js b/sidepanel/sidepanel.js
index 37a6d3e..63045a1 100644
--- a/sidepanel/sidepanel.js
+++ b/sidepanel/sidepanel.js
@@ -110,10 +110,15 @@ const rowTempEmailCustomAuth = document.getElementById('row-temp-email-custom-au
 const inputTempEmailCustomAuth = document.getElementById('input-temp-email-custom-auth');
 const rowTempEmailReceiveMailbox = document.getElementById('row-temp-email-receive-mailbox');
 const inputTempEmailReceiveMailbox = document.getElementById('input-temp-email-receive-mailbox');
+const rowTempEmailRandomSubdomainToggle = document.getElementById('row-temp-email-random-subdomain-toggle');
+const inputTempEmailUseRandomSubdomain = document.getElementById('input-temp-email-use-random-subdomain');
 const rowTempEmailDomain = document.getElementById('row-temp-email-domain');
 const selectTempEmailDomain = document.getElementById('select-temp-email-domain');
 const inputTempEmailDomain = document.getElementById('input-temp-email-domain');
 const btnTempEmailDomainMode = document.getElementById('btn-temp-email-domain-mode');
+const cloudflareTempEmailSection = document.getElementById('cloudflare-temp-email-section');
+const btnCloudflareTempEmailUsageGuide = document.getElementById('btn-cloudflare-temp-email-usage-guide');
+const btnCloudflareTempEmailGithub = document.getElementById('btn-cloudflare-temp-email-github');
 const hotmailSection = document.getElementById('hotmail-section');
 const mail2925Section = document.getElementById('mail2925-section');
 const luckmailSection = document.getElementById('luckmail-section');
@@ -606,6 +611,10 @@ const LOG_LEVEL_LABELS = {
   error: '错误',
 };
 
+const CLOUDFLARE_TEMP_EMAIL_REPOSITORY_URL = 'https://github.com/dreamhunter2333/cloudflare_temp_email';
+const CLOUDFLARE_TEMP_EMAIL_BUILD_TUTORIAL_URL = 'https://linux.do/t/topic/316819';
+const CLOUDFLARE_TEMP_EMAIL_RANDOM_SUBDOMAIN_ISSUE_URL = 'https://github.com/dreamhunter2333/cloudflare_temp_email/issues/942';
+
 function usesGeneratedAliasMailProvider(provider, mail2925Mode = getSelectedMail2925Mode()) {
   return isManagedAliasProvider(provider, mail2925Mode);
 }
@@ -670,6 +679,19 @@ function resetActionModalAlert() {
   autoStartAlert.className = 'modal-alert';
 }
 
+function setActionModalMessageContent({ text = '', html = '' } = {}) {
+  if (!autoStartMessage) {
+    return;
+  }
+
+  if (html) {
+    autoStartMessage.innerHTML = html;
+    return;
+  }
+
+  autoStartMessage.textContent = text;
+}
+
 function resetActionModalButtons() {
   const buttons = [btnAutoStartCancel, btnAutoStartRestart, btnAutoStartContinue];
   buttons.forEach((button) => {
@@ -745,7 +767,7 @@ function resolveModalChoice(choice) {
   }
 }
 
-function openActionModal({ title, message, actions, option, alert, buildResult }) {
+function openActionModal({ title, message, messageHtml, actions, option, alert, buildResult }) {
   if (!autoStartModal) {
     return Promise.resolve(null);
   }
@@ -756,7 +778,7 @@ function openActionModal({ title, message, actions, option, alert, buildResult }
 
   resetActionModalButtons();
   autoStartTitle.textContent = title;
-  autoStartMessage.textContent = message;
+  setActionModalMessageContent({ text: message, html: messageHtml });
   currentModalActions = actions || [];
   modalResultBuilder = typeof buildResult === 'function' ? buildResult : null;
   const buttonSlots = currentModalActions.length <= 2
@@ -1456,6 +1478,18 @@ function setCloudflareTempEmailDomainEditMode(editing, options = {}) {
   }
 }
 
+function applyCloudflareTempEmailSettingsState(state = {}) {
+  inputTempEmailBaseUrl.value = state?.cloudflareTempEmailBaseUrl || '';
+  inputTempEmailAdminAuth.value = state?.cloudflareTempEmailAdminAuth || '';
+  inputTempEmailCustomAuth.value = state?.cloudflareTempEmailCustomAuth || '';
+  inputTempEmailReceiveMailbox.value = state?.cloudflareTempEmailReceiveMailbox || '';
+  if (inputTempEmailUseRandomSubdomain) {
+    inputTempEmailUseRandomSubdomain.checked = Boolean(state?.cloudflareTempEmailUseRandomSubdomain);
+  }
+  renderCloudflareTempEmailDomainOptions(state?.cloudflareTempEmailDomain || '');
+  setCloudflareTempEmailDomainEditMode(false, { clearInput: true });
+}
+
 function collectSettingsPayload() {
   const { domains, activeDomain } = getCloudflareDomainsFromState();
   const selectedCloudflareDomain = normalizeCloudflareDomainValue(
@@ -1508,6 +1542,7 @@ function collectSettingsPayload() {
     cloudflareTempEmailAdminAuth: inputTempEmailAdminAuth.value,
     cloudflareTempEmailCustomAuth: inputTempEmailCustomAuth.value,
     cloudflareTempEmailReceiveMailbox: normalizeCloudflareTempEmailReceiveMailboxValue(inputTempEmailReceiveMailbox.value),
+    cloudflareTempEmailUseRandomSubdomain: Boolean(inputTempEmailUseRandomSubdomain?.checked),
     cloudflareTempEmailDomain: selectedCloudflareTempEmailDomain,
     cloudflareTempEmailDomains: tempEmailDomains,
     autoRunSkipFailures: inputAutoSkipFailures.checked,
@@ -1912,14 +1947,9 @@ function applySettingsState(state) {
   inputLuckmailBaseUrl.value = normalizeLuckmailBaseUrl(state?.luckmailBaseUrl);
   selectLuckmailEmailType.value = normalizeLuckmailEmailType(state?.luckmailEmailType);
   inputLuckmailDomain.value = state?.luckmailDomain || '';
-  inputTempEmailBaseUrl.value = state?.cloudflareTempEmailBaseUrl || '';
-  inputTempEmailAdminAuth.value = state?.cloudflareTempEmailAdminAuth || '';
-  inputTempEmailCustomAuth.value = state?.cloudflareTempEmailCustomAuth || '';
-  inputTempEmailReceiveMailbox.value = state?.cloudflareTempEmailReceiveMailbox || '';
+  applyCloudflareTempEmailSettingsState(state);
   renderCloudflareDomainOptions(state?.cloudflareDomain || '');
   setCloudflareDomainEditMode(false, { clearInput: true });
-  renderCloudflareTempEmailDomainOptions(state?.cloudflareTempEmailDomain || '');
-  setCloudflareTempEmailDomainEditMode(false, { clearInput: true });
   inputAutoSkipFailures.checked = Boolean(state?.autoRunSkipFailures);
   inputAutoSkipFailuresThreadIntervalMinutes.value = String(normalizeAutoRunThreadIntervalMinutes(state?.autoRunFallbackThreadIntervalMinutes));
   inputAutoDelayEnabled.checked = Boolean(state?.autoRunDelayEnabled);
@@ -2038,6 +2068,51 @@ function openReleaseListPage() {
   openExternalUrl(getReleaseListUrl());
 }
 
+function buildCloudflareTempEmailUsageGuideModalConfig() {
+  const useCloudflareTempEmailProvider = String(selectMailProvider?.value || '').trim().toLowerCase() === 'cloudflare-temp-email';
+  const useCloudflareTempEmailGenerator = getSelectedEmailGenerator() === 'cloudflare-temp-email';
+  let alertText = '当前还没有把 Cloudflare Temp Email 选为邮箱服务或邮箱生成器。下面说明同时覆盖“生成邮箱”和“接收转发邮件”两种用法。';
+  if (useCloudflareTempEmailProvider && useCloudflareTempEmailGenerator) {
+    alertText = '当前同时把 Cloudflare Temp Email 用作“邮箱服务”和“邮箱生成器”。请同时配置生成邮箱和接收转发两套必填项。';
+  } else if (useCloudflareTempEmailProvider) {
+    alertText = '当前把 Cloudflare Temp Email 用作“邮箱服务”。重点填写 Temp API、Custom Auth 和 邮件接收。';
+  } else if (useCloudflareTempEmailGenerator) {
+    alertText = '当前把 Cloudflare Temp Email 用作“邮箱生成器”。重点填写 Temp API、Admin Auth 和 Temp 域名；随机子域按需开启。';
+  }
+
+  return {
+    title: 'Cloudflare Temp Email 使用教程',
+    alert: { text: alertText },
+    messageHtml: `Temp API：填写 Cloudflare Temp Email 后端地址。<br><br>
+Admin Auth：填写后端 admin auth。<br>
+仅在“邮箱生成 = Cloudflare Temp Email”时必填。<br><br>
+Custom Auth：仅当站点额外开启访问密码时填写。没有开启就留空。<br><br>
+Temp 域名：填写允许创建的基础域名。启用随机子域时，这里仍然填写基础域名。<br><br>
+随机子域：仅在“邮箱生成 = Cloudflare Temp Email”时使用。<br>
+后端需要已配置 RANDOM_SUBDOMAIN_DOMAINS。<br>
+CF DNS 需要设置 MX *，参考 <a href="${CLOUDFLARE_TEMP_EMAIL_RANDOM_SUBDOMAIN_ISSUE_URL}" target="_blank" rel="noopener noreferrer">Issue #942</a>。<br><br>
+邮件接收：仅在“邮箱服务 = Cloudflare Temp Email”时填写。<br>
+这里填写真正接收转发邮件的目标邮箱。<br><br>
+搭建教程：<a href="${CLOUDFLARE_TEMP_EMAIL_BUILD_TUTORIAL_URL}" target="_blank" rel="noopener noreferrer">LINUX DO 教程</a>。`,
+  };
+}
+
+function showCloudflareTempEmailUsageGuide() {
+  const modalConfig = buildCloudflareTempEmailUsageGuideModalConfig();
+  return openActionModal({
+    title: modalConfig.title,
+    messageHtml: modalConfig.messageHtml,
+    alert: modalConfig.alert,
+    actions: [
+      { id: 'ok', label: '知道了', variant: 'btn-primary' },
+    ],
+  });
+}
+
+function openCloudflareTempEmailRepositoryPage() {
+  openExternalUrl(CLOUDFLARE_TEMP_EMAIL_REPOSITORY_URL);
+}
+
 function createUpdateNoteList(notes = []) {
   if (!Array.isArray(notes) || notes.length === 0) {
     const empty = document.createElement('p');
@@ -2672,10 +2747,14 @@ function updateMailProviderUI() {
   const showCloudflareDomain = useEmailGenerator && useCloudflare;
   const showCloudflareTempEmailSettings = useCloudflareTempEmailProvider || (useEmailGenerator && useCloudflareTempEmailGenerator);
   const showCloudflareTempEmailReceiveMailbox = useCloudflareTempEmailProvider && !useCloudflareTempEmailGenerator;
+  const showCloudflareTempEmailRandomSubdomainToggle = useEmailGenerator && useCloudflareTempEmailGenerator;
   const showCloudflareTempEmailDomain = useEmailGenerator && useCloudflareTempEmailGenerator;
   if (rowEmailGenerator) {
     rowEmailGenerator.style.display = useEmailGenerator ? '' : 'none';
   }
+  if (cloudflareTempEmailSection) {
+    cloudflareTempEmailSection.style.display = showCloudflareTempEmailSettings ? '' : 'none';
+  }
   if (icloudSection) {
     const showIcloudSection = (useEmailGenerator && useIcloud) || useIcloudProvider;
     icloudSection.style.display = showIcloudSection ? '' : 'none';
@@ -2697,6 +2776,9 @@ function updateMailProviderUI() {
   rowTempEmailAdminAuth.style.display = showCloudflareTempEmailSettings ? '' : 'none';
   rowTempEmailCustomAuth.style.display = showCloudflareTempEmailSettings ? '' : 'none';
   rowTempEmailReceiveMailbox.style.display = showCloudflareTempEmailReceiveMailbox ? '' : 'none';
+  if (rowTempEmailRandomSubdomainToggle) {
+    rowTempEmailRandomSubdomainToggle.style.display = showCloudflareTempEmailRandomSubdomainToggle ? '' : 'none';
+  }
   rowTempEmailDomain.style.display = showCloudflareTempEmailDomain ? '' : 'none';
   const { domains: tempEmailDomains } = getCloudflareTempEmailDomainsFromState();
   if (showCloudflareTempEmailDomain) {
@@ -2784,6 +2866,9 @@ function updateMailProviderUI() {
   if (autoHintText && showCloudflareTempEmailReceiveMailbox) {
     autoHintText.textContent = '若注册邮箱会转发到 Cloudflare Temp Email，请在“邮件接收”中填写实际接收转发邮件的邮箱。';
   }
+  if (autoHintText && showCloudflareTempEmailRandomSubdomainToggle && inputTempEmailUseRandomSubdomain?.checked) {
+    autoHintText.textContent = '已启用随机子域名：扩展会按当前选中的 Temp 域名提交，并额外携带 enableRandomSubdomain；是否生效取决于后端 RANDOM_SUBDOMAIN_DOMAINS 配置。';
+  }
   if (useHotmail) {
     inputEmail.value = getCurrentHotmailEmail();
   } else if (useLuckmail) {
@@ -3776,6 +3861,14 @@ btnRepoHome?.addEventListener('click', () => {
   openRepositoryHomePage();
 });
 
+btnCloudflareTempEmailUsageGuide?.addEventListener('click', () => {
+  showCloudflareTempEmailUsageGuide();
+});
+
+btnCloudflareTempEmailGithub?.addEventListener('click', () => {
+  openCloudflareTempEmailRepositoryPage();
+});
+
 extensionUpdateStatus?.addEventListener('click', () => {
   openReleaseListPage();
 });
@@ -4387,6 +4480,13 @@ inputTempEmailReceiveMailbox.addEventListener('blur', () => {
   saveSettings({ silent: true }).catch(() => { });
 });
 
+inputTempEmailUseRandomSubdomain?.addEventListener('change', () => {
+  updateMailProviderUI();
+  clearRegistrationEmail({ silent: true }).catch(() => { });
+  markSettingsDirty(true);
+  saveSettings({ silent: true }).catch(() => { });
+});
+
 inputAutoSkipFailuresThreadIntervalMinutes.addEventListener('input', () => {
   markSettingsDirty(true);
   scheduleSettingsAutoSave();
@@ -4609,9 +4709,19 @@ chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
       if (message.payload.cloudflareTempEmailReceiveMailbox !== undefined) {
         inputTempEmailReceiveMailbox.value = message.payload.cloudflareTempEmailReceiveMailbox || '';
       }
+      if (message.payload.cloudflareTempEmailUseRandomSubdomain !== undefined && inputTempEmailUseRandomSubdomain) {
+        inputTempEmailUseRandomSubdomain.checked = Boolean(message.payload.cloudflareTempEmailUseRandomSubdomain);
+      }
       if (message.payload.cloudflareTempEmailDomain !== undefined || message.payload.cloudflareTempEmailDomains !== undefined) {
         renderCloudflareTempEmailDomainOptions(message.payload.cloudflareTempEmailDomain || latestState?.cloudflareTempEmailDomain || '');
       }
+      if (
+        message.payload.cloudflareTempEmailUseRandomSubdomain !== undefined
+        || message.payload.cloudflareTempEmailDomain !== undefined
+        || message.payload.cloudflareTempEmailDomains !== undefined
+      ) {
+        updateMailProviderUI();
+      }
       if (message.payload.currentHotmailAccountId !== undefined || message.payload.hotmailAccounts !== undefined) {
         renderHotmailAccounts();
         if (selectMailProvider.value === 'hotmail-api') {
diff --git a/tests/background-cloudflare-temp-email-settings.test.js b/tests/background-cloudflare-temp-email-settings.test.js
new file mode 100644
index 0000000..e44404f
--- /dev/null
+++ b/tests/background-cloudflare-temp-email-settings.test.js
@@ -0,0 +1,145 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+
+const source = fs.readFileSync('background.js', 'utf8');
+
+function extractFunction(name) {
+  const markers = [`async function ${name}(`, `function ${name}(`];
+  const start = markers
+    .map((marker) => source.indexOf(marker))
+    .find((index) => index >= 0);
+  if (start < 0) {
+    throw new Error(`missing function ${name}`);
+  }
+
+  let parenDepth = 0;
+  let signatureEnded = false;
+  let braceStart = -1;
+  for (let i = start; i < source.length; i += 1) {
+    const ch = source[i];
+    if (ch === '(') {
+      parenDepth += 1;
+    } else if (ch === ')') {
+      parenDepth -= 1;
+      if (parenDepth === 0) {
+        signatureEnded = true;
+      }
+    } else if (ch === '{' && signatureEnded) {
+      braceStart = i;
+      break;
+    }
+  }
+
+  let depth = 0;
+  let end = braceStart;
+  for (; end < source.length; end += 1) {
+    const ch = source[end];
+    if (ch === '{') depth += 1;
+    if (ch === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        end += 1;
+        break;
+      }
+    }
+  }
+
+  return source.slice(start, end);
+}
+
+test('cloudflare temp email settings normalize and expose the random-subdomain toggle', () => {
+  const bundle = [
+    extractFunction('normalizeCloudflareTempEmailReceiveMailbox'),
+    extractFunction('getCloudflareTempEmailConfig'),
+    extractFunction('normalizePersistentSettingValue'),
+    extractFunction('buildPersistentSettingsPayload'),
+  ].join('\n');
+
+  const api = new Function(`
+const DEFAULT_VERIFICATION_RESEND_COUNT = 4;
+const PERSISTED_SETTING_DEFAULTS = {
+  panelMode: 'cpa',
+  autoStepDelaySeconds: null,
+  verificationResendCount: DEFAULT_VERIFICATION_RESEND_COUNT,
+  mailProvider: '163',
+  mail2925Mode: 'provide',
+  emailGenerator: 'duck',
+  autoDeleteUsedIcloudAlias: false,
+  accountRunHistoryTextEnabled: false,
+  cloudflareTempEmailUseRandomSubdomain: false,
+  cloudflareTempEmailDomain: '',
+  cloudflareTempEmailDomains: [],
+};
+const PERSISTED_SETTING_KEYS = Object.keys(PERSISTED_SETTING_DEFAULTS);
+function normalizePanelMode(value) { return value === 'sub2api' ? 'sub2api' : 'cpa'; }
+function normalizeLocalCpaStep9Mode(value) { return value === 'bypass' ? 'bypass' : 'submit'; }
+function normalizeAutoRunFallbackThreadIntervalMinutes(value) { return Number(value) || 0; }
+function normalizeAutoRunDelayMinutes(value) { return Number(value) || 30; }
+function normalizeAutoStepDelaySeconds(value, fallback = null) { return value == null || value === '' ? fallback : Number(value); }
+function normalizeVerificationResendCount(value, fallback) { return Number.isFinite(Number(value)) ? Number(value) : fallback; }
+function normalizeMailProvider(value) { return String(value || '').trim().toLowerCase() || '163'; }
+function normalizeMail2925Mode(value) { return String(value || '').trim().toLowerCase() === 'receive' ? 'receive' : 'provide'; }
+function normalizeEmailGenerator(value) { return String(value || '').trim().toLowerCase() || 'duck'; }
+function normalizeIcloudHost(value) { const normalized = String(value || '').trim().toLowerCase(); return normalized === 'icloud.com' || normalized === 'icloud.com.cn' ? normalized : ''; }
+function normalizeAccountRunHistoryHelperBaseUrl(value) { return String(value || '').trim(); }
+function normalizeHotmailServiceMode(value) { return String(value || '').trim().toLowerCase() === 'remote' ? 'remote' : 'local'; }
+function normalizeHotmailRemoteBaseUrl(value) { return String(value || '').trim(); }
+function normalizeHotmailLocalBaseUrl(value) { return String(value || '').trim(); }
+function normalizeCloudflareDomain(value) { return String(value || '').trim().toLowerCase(); }
+function normalizeCloudflareDomains(value) { return Array.isArray(value) ? value.map((item) => String(item || '').trim().toLowerCase()).filter(Boolean) : []; }
+function normalizeCloudflareTempEmailBaseUrl(value) { return String(value || '').trim(); }
+function normalizeCloudflareTempEmailAddress(value = '') { return String(value || '').trim().toLowerCase(); }
+function normalizeCloudflareTempEmailDomain(value) { return String(value || '').trim().toLowerCase(); }
+function normalizeCloudflareTempEmailDomains(value) {
+  const seen = new Set();
+  const domains = [];
+  for (const item of Array.isArray(value) ? value : []) {
+    const normalized = normalizeCloudflareTempEmailDomain(item);
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    domains.push(normalized);
+  }
+  return domains;
+}
+function normalizeHotmailAccounts(value) { return Array.isArray(value) ? value : []; }
+function normalizeMail2925Accounts(value) { return Array.isArray(value) ? value : []; }
+function resolveLegacyAutoStepDelaySeconds() { return undefined; }
+${bundle}
+return {
+  buildPersistentSettingsPayload,
+  getCloudflareTempEmailConfig,
+  normalizePersistentSettingValue,
+};
+  `)();
+
+  assert.equal(api.normalizePersistentSettingValue('cloudflareTempEmailUseRandomSubdomain', 1), true);
+
+  const payload = api.buildPersistentSettingsPayload({
+    cloudflareTempEmailUseRandomSubdomain: true,
+    cloudflareTempEmailDomain: 'mail.example.com',
+    cloudflareTempEmailDomains: ['mail.example.com', 'alt.example.com'],
+  });
+  assert.equal(payload.cloudflareTempEmailUseRandomSubdomain, true);
+  assert.equal(payload.cloudflareTempEmailDomain, 'mail.example.com');
+  assert.deepEqual(payload.cloudflareTempEmailDomains, ['mail.example.com', 'alt.example.com']);
+
+  const config = api.getCloudflareTempEmailConfig({
+    cloudflareTempEmailBaseUrl: 'https://temp.example.com',
+    cloudflareTempEmailAdminAuth: 'admin-secret',
+    cloudflareTempEmailCustomAuth: 'custom-secret',
+    cloudflareTempEmailReceiveMailbox: 'Forward@Example.com',
+    cloudflareTempEmailUseRandomSubdomain: true,
+    cloudflareTempEmailDomain: 'mail.example.com',
+    cloudflareTempEmailDomains: ['mail.example.com'],
+  });
+  assert.deepEqual(config, {
+    baseUrl: 'https://temp.example.com',
+    adminAuth: 'admin-secret',
+    customAuth: 'custom-secret',
+    receiveMailbox: 'forward@example.com',
+    useRandomSubdomain: true,
+    domain: 'mail.example.com',
+    domains: ['mail.example.com'],
+  });
+});
diff --git a/tests/background-generated-email-module.test.js b/tests/background-generated-email-module.test.js
index fb5d764..7c9a868 100644
--- a/tests/background-generated-email-module.test.js
+++ b/tests/background-generated-email-module.test.js
@@ -2,24 +2,25 @@ const test = require('node:test');
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
 
+function loadGeneratedEmailHelpersApi() {
+  const source = fs.readFileSync('background/generated-email-helpers.js', 'utf8');
+  const globalScope = {};
+  return new Function('self', `${source}; return self.MultiPageGeneratedEmailHelpers;`)(globalScope);
+}
+
 test('background imports generated email helper module', () => {
   const source = fs.readFileSync('background.js', 'utf8');
   assert.match(source, /importScripts\([\s\S]*'background\/generated-email-helpers\.js'/);
 });
 
 test('generated email helper module exposes a factory', () => {
-  const source = fs.readFileSync('background/generated-email-helpers.js', 'utf8');
-  const globalScope = {};
-
-  const api = new Function('self', `${source}; return self.MultiPageGeneratedEmailHelpers;`)(globalScope);
+  const api = loadGeneratedEmailHelpersApi();
 
   assert.equal(typeof api?.createGeneratedEmailHelpers, 'function');
 });
 
 test('generated email helper falls back to normal generator when 2925 is in receive mode', async () => {
-  const source = fs.readFileSync('background/generated-email-helpers.js', 'utf8');
-  const globalScope = {};
-  const api = new Function('self', `${source}; return self.MultiPageGeneratedEmailHelpers;`)(globalScope);
+  const api = loadGeneratedEmailHelpersApi();
   const events = [];
 
   const helpers = api.createGeneratedEmailHelpers({
@@ -76,3 +77,157 @@ test('generated email helper falls back to normal generator when 2925 is in rece
     ['email', 'duck@example.com'],
   ]);
 });
+
+test('generated email helper uses the regular temp email domain when random subdomain mode is disabled', async () => {
+  const api = loadGeneratedEmailHelpersApi();
+  const requests = [];
+  const savedEmails = [];
+
+  const helpers = api.createGeneratedEmailHelpers({
+    addLog: async () => {},
+    buildGeneratedAliasEmail: () => {
+      throw new Error('should not build managed alias');
+    },
+    buildCloudflareTempEmailHeaders: () => ({ 'x-admin-auth': 'admin-secret' }),
+    CLOUDFLARE_TEMP_EMAIL_GENERATOR: 'cloudflare-temp-email',
+    DUCK_AUTOFILL_URL: 'https://duckduckgo.com/email',
+    fetch: async (url, options = {}) => {
+      requests.push({
+        url,
+        method: options.method,
+        body: options.body ? JSON.parse(options.body) : null,
+      });
+      return {
+        ok: true,
+        text: async () => JSON.stringify({ address: 'user@mail.example.com' }),
+      };
+    },
+    fetchIcloudHideMyEmail: async () => {
+      throw new Error('should not use icloud generator');
+    },
+    getCloudflareTempEmailAddressFromResponse: (payload) => payload.address,
+    getCloudflareTempEmailConfig: () => ({
+      baseUrl: 'https://temp.example.com',
+      adminAuth: 'admin-secret',
+      customAuth: '',
+      useRandomSubdomain: false,
+      domain: 'mail.example.com',
+    }),
+    getState: async () => ({
+      mailProvider: '163',
+      emailGenerator: 'cloudflare-temp-email',
+    }),
+    ensureMail2925AccountForFlow: async () => {
+      throw new Error('should not allocate mail2925 account');
+    },
+    joinCloudflareTempEmailUrl: (baseUrl, path) => `${baseUrl}${path}`,
+    normalizeCloudflareDomain: () => '',
+    normalizeCloudflareTempEmailAddress: (value) => String(value || '').trim().toLowerCase(),
+    normalizeEmailGenerator: (value) => String(value || '').trim().toLowerCase(),
+    isGeneratedAliasProvider: () => false,
+    reuseOrCreateTab: async () => {},
+    sendToContentScript: async () => {
+      throw new Error('should not use duck generator');
+    },
+    setEmailState: async (email) => {
+      savedEmails.push(email);
+    },
+    throwIfStopped: () => {},
+  });
+
+  const email = await helpers.fetchGeneratedEmail({
+    emailGenerator: 'cloudflare-temp-email',
+  }, {
+    generator: 'cloudflare-temp-email',
+  });
+
+  assert.equal(email, 'user@mail.example.com');
+  assert.deepEqual(savedEmails, ['user@mail.example.com']);
+  assert.equal(requests.length, 1);
+  assert.equal(requests[0].url, 'https://temp.example.com/admin/new_address');
+  assert.equal(requests[0].method, 'POST');
+  assert.deepEqual(requests[0].body, {
+    enablePrefix: true,
+    enableRandomSubdomain: false,
+    name: requests[0].body.name,
+    domain: 'mail.example.com',
+  });
+  assert.match(requests[0].body.name, /^[a-z0-9]+$/);
+});
+
+test('generated email helper requests random subdomain creation while preserving the returned address', async () => {
+  const api = loadGeneratedEmailHelpersApi();
+  const requests = [];
+  const savedEmails = [];
+
+  const helpers = api.createGeneratedEmailHelpers({
+    addLog: async () => {},
+    buildGeneratedAliasEmail: () => {
+      throw new Error('should not build managed alias');
+    },
+    buildCloudflareTempEmailHeaders: () => ({ 'x-admin-auth': 'admin-secret' }),
+    CLOUDFLARE_TEMP_EMAIL_GENERATOR: 'cloudflare-temp-email',
+    DUCK_AUTOFILL_URL: 'https://duckduckgo.com/email',
+    fetch: async (url, options = {}) => {
+      requests.push({
+        url,
+        method: options.method,
+        body: options.body ? JSON.parse(options.body) : null,
+      });
+      return {
+        ok: true,
+        text: async () => JSON.stringify({ address: 'user@a1b2c3d4.example.com' }),
+      };
+    },
+    fetchIcloudHideMyEmail: async () => {
+      throw new Error('should not use icloud generator');
+    },
+    getCloudflareTempEmailAddressFromResponse: (payload) => payload.address,
+    getCloudflareTempEmailConfig: () => ({
+      baseUrl: 'https://temp.example.com',
+      adminAuth: 'admin-secret',
+      customAuth: '',
+      useRandomSubdomain: true,
+      domain: 'mail.example.com',
+    }),
+    getState: async () => ({
+      mailProvider: '163',
+      emailGenerator: 'cloudflare-temp-email',
+    }),
+    ensureMail2925AccountForFlow: async () => {
+      throw new Error('should not allocate mail2925 account');
+    },
+    joinCloudflareTempEmailUrl: (baseUrl, path) => `${baseUrl}${path}`,
+    normalizeCloudflareDomain: () => '',
+    normalizeCloudflareTempEmailAddress: (value) => String(value || '').trim().toLowerCase(),
+    normalizeEmailGenerator: (value) => String(value || '').trim().toLowerCase(),
+    isGeneratedAliasProvider: () => false,
+    reuseOrCreateTab: async () => {},
+    sendToContentScript: async () => {
+      throw new Error('should not use duck generator');
+    },
+    setEmailState: async (email) => {
+      savedEmails.push(email);
+    },
+    throwIfStopped: () => {},
+  });
+
+  const email = await helpers.fetchGeneratedEmail({
+    emailGenerator: 'cloudflare-temp-email',
+  }, {
+    generator: 'cloudflare-temp-email',
+    localPart: 'user',
+  });
+
+  assert.equal(email, 'user@a1b2c3d4.example.com');
+  assert.deepEqual(savedEmails, ['user@a1b2c3d4.example.com']);
+  assert.equal(requests.length, 1);
+  assert.equal(requests[0].url, 'https://temp.example.com/admin/new_address');
+  assert.equal(requests[0].method, 'POST');
+  assert.deepEqual(requests[0].body, {
+    enablePrefix: true,
+    enableRandomSubdomain: true,
+    name: 'user',
+    domain: 'mail.example.com',
+  });
+});
diff --git a/tests/sidepanel-cloudflare-temp-email-random-subdomain.test.js b/tests/sidepanel-cloudflare-temp-email-random-subdomain.test.js
new file mode 100644
index 0000000..e969761
--- /dev/null
+++ b/tests/sidepanel-cloudflare-temp-email-random-subdomain.test.js
@@ -0,0 +1,297 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+
+const source = fs.readFileSync('sidepanel/sidepanel.js', 'utf8');
+
+function extractFunction(name) {
+  const markers = [`async function ${name}(`, `function ${name}(`];
+  const start = markers
+    .map((marker) => source.indexOf(marker))
+    .find((index) => index >= 0);
+  if (start < 0) {
+    throw new Error(`missing function ${name}`);
+  }
+
+  let parenDepth = 0;
+  let signatureEnded = false;
+  let braceStart = -1;
+  for (let i = start; i < source.length; i += 1) {
+    const ch = source[i];
+    if (ch === '(') {
+      parenDepth += 1;
+    } else if (ch === ')') {
+      parenDepth -= 1;
+      if (parenDepth === 0) {
+        signatureEnded = true;
+      }
+    } else if (ch === '{' && signatureEnded) {
+      braceStart = i;
+      break;
+    }
+  }
+
+  let depth = 0;
+  let end = braceStart;
+  for (; end < source.length; end += 1) {
+    const ch = source[end];
+    if (ch === '{') depth += 1;
+    if (ch === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        end += 1;
+        break;
+      }
+    }
+  }
+
+  return source.slice(start, end);
+}
+
+function createRow(initialDisplay = 'none') {
+  return {
+    style: { display: initialDisplay },
+  };
+}
+
+test('sidepanel html places cloudflare temp email controls in a standalone section', () => {
+  const html = fs.readFileSync('sidepanel/sidepanel.html', 'utf8');
+  assert.match(html, /id="cloudflare-temp-email-section"/);
+  assert.match(html, /id="btn-cloudflare-temp-email-usage-guide"/);
+  assert.match(html, /id="btn-cloudflare-temp-email-github"/);
+  assert.match(html, /id="row-temp-email-random-subdomain-toggle"/);
+  assert.match(html, /id="input-temp-email-use-random-subdomain"/);
+  assert.doesNotMatch(html, /id="row-temp-email-random-subdomain-domain"/);
+});
+
+test('sidepanel modal message preserves line breaks and supports inline links', () => {
+  const css = fs.readFileSync('sidepanel/sidepanel.css', 'utf8');
+  assert.match(css, /\.modal-message\s*\{[\s\S]*white-space:\s*pre-line;/);
+  assert.match(css, /\.modal-message a,\s*[\s\S]*\.modal-alert a/);
+});
+
+test('buildCloudflareTempEmailUsageGuideModalConfig returns a modal payload with inline links for generator mode', () => {
+  const bundle = extractFunction('buildCloudflareTempEmailUsageGuideModalConfig');
+
+  const api = new Function(`
+const selectMailProvider = { value: '163' };
+const selectEmailGenerator = { value: 'cloudflare-temp-email' };
+const CLOUDFLARE_TEMP_EMAIL_BUILD_TUTORIAL_URL = 'https://linux.do/t/topic/316819';
+const CLOUDFLARE_TEMP_EMAIL_RANDOM_SUBDOMAIN_ISSUE_URL = 'https://github.com/dreamhunter2333/cloudflare_temp_email/issues/942';
+function getSelectedEmailGenerator() { return String(selectEmailGenerator.value || '').trim().toLowerCase(); }
+${bundle}
+return {
+  buildCloudflareTempEmailUsageGuideModalConfig,
+};
+  `)();
+
+  const modalConfig = api.buildCloudflareTempEmailUsageGuideModalConfig();
+  assert.equal(typeof modalConfig.title, 'string');
+  assert.equal(typeof modalConfig.messageHtml, 'string');
+  assert.equal(typeof modalConfig.alert?.text, 'string');
+  assert.equal(modalConfig.title.length > 0, true);
+  assert.equal(modalConfig.messageHtml.length > 0, true);
+  assert.equal(modalConfig.alert.text.length > 0, true);
+  assert.equal(modalConfig.messageHtml.includes('<a '), true);
+  assert.equal(modalConfig.messageHtml.includes('Issue #942'), true);
+  assert.equal(modalConfig.messageHtml.includes('LINUX DO 教程'), true);
+});
+
+test('buildCloudflareTempEmailUsageGuideModalConfig returns a distinct alert for provider mode', () => {
+  const bundle = extractFunction('buildCloudflareTempEmailUsageGuideModalConfig');
+
+  const api = new Function(`
+const selectMailProvider = { value: 'cloudflare-temp-email' };
+const selectEmailGenerator = { value: 'duck' };
+const CLOUDFLARE_TEMP_EMAIL_BUILD_TUTORIAL_URL = 'https://linux.do/t/topic/316819';
+const CLOUDFLARE_TEMP_EMAIL_RANDOM_SUBDOMAIN_ISSUE_URL = 'https://github.com/dreamhunter2333/cloudflare_temp_email/issues/942';
+function getSelectedEmailGenerator() { return String(selectEmailGenerator.value || '').trim().toLowerCase(); }
+${bundle}
+return {
+  buildCloudflareTempEmailUsageGuideModalConfig,
+};
+  `)();
+
+  const providerConfig = api.buildCloudflareTempEmailUsageGuideModalConfig();
+
+  const generatorApi = new Function(`
+const selectMailProvider = { value: '163' };
+const selectEmailGenerator = { value: 'cloudflare-temp-email' };
+const CLOUDFLARE_TEMP_EMAIL_BUILD_TUTORIAL_URL = 'https://linux.do/t/topic/316819';
+const CLOUDFLARE_TEMP_EMAIL_RANDOM_SUBDOMAIN_ISSUE_URL = 'https://github.com/dreamhunter2333/cloudflare_temp_email/issues/942';
+function getSelectedEmailGenerator() { return String(selectEmailGenerator.value || '').trim().toLowerCase(); }
+${bundle}
+return {
+  buildCloudflareTempEmailUsageGuideModalConfig,
+};
+  `)();
+
+  const generatorConfig = generatorApi.buildCloudflareTempEmailUsageGuideModalConfig();
+  assert.equal(typeof providerConfig.alert?.text, 'string');
+  assert.equal(typeof providerConfig.messageHtml, 'string');
+  assert.equal(providerConfig.alert.text.length > 0, true);
+  assert.equal(providerConfig.messageHtml.length > 0, true);
+  assert.notEqual(providerConfig.alert.text, generatorConfig.alert.text);
+});
+
+test('openCloudflareTempEmailRepositoryPage opens the upstream repository', () => {
+  const bundle = extractFunction('openCloudflareTempEmailRepositoryPage');
+
+  const api = new Function(`
+const calls = [];
+const CLOUDFLARE_TEMP_EMAIL_REPOSITORY_URL = 'https://github.com/dreamhunter2333/cloudflare_temp_email';
+function openExternalUrl(url) { calls.push(url); }
+${bundle}
+return {
+  calls,
+  openCloudflareTempEmailRepositoryPage,
+};
+  `)();
+
+  api.openCloudflareTempEmailRepositoryPage();
+  assert.deepEqual(api.calls, ['https://github.com/dreamhunter2333/cloudflare_temp_email']);
+});
+
+test('applyCloudflareTempEmailSettingsState restores the random subdomain toggle and temp domain list', () => {
+  const bundle = extractFunction('applyCloudflareTempEmailSettingsState');
+
+  const api = new Function(`
+const inputTempEmailBaseUrl = { value: '' };
+const inputTempEmailAdminAuth = { value: '' };
+const inputTempEmailCustomAuth = { value: '' };
+const inputTempEmailReceiveMailbox = { value: '' };
+const inputTempEmailUseRandomSubdomain = { checked: false };
+const calls = {
+  domainOptions: [],
+  domainEditMode: [],
+};
+function renderCloudflareTempEmailDomainOptions(value) { calls.domainOptions.push(value); }
+function setCloudflareTempEmailDomainEditMode(editing, options) { calls.domainEditMode.push({ editing, options }); }
+${bundle}
+return {
+  applyCloudflareTempEmailSettingsState,
+  calls,
+  inputTempEmailBaseUrl,
+  inputTempEmailAdminAuth,
+  inputTempEmailCustomAuth,
+  inputTempEmailReceiveMailbox,
+  inputTempEmailUseRandomSubdomain,
+};
+  `)();
+
+  api.applyCloudflareTempEmailSettingsState({
+    cloudflareTempEmailBaseUrl: 'https://temp.example.com',
+    cloudflareTempEmailAdminAuth: 'admin-secret',
+    cloudflareTempEmailCustomAuth: 'custom-secret',
+    cloudflareTempEmailReceiveMailbox: 'relay@example.com',
+    cloudflareTempEmailUseRandomSubdomain: true,
+    cloudflareTempEmailDomain: 'mail.example.com',
+  });
+
+  assert.equal(api.inputTempEmailBaseUrl.value, 'https://temp.example.com');
+  assert.equal(api.inputTempEmailAdminAuth.value, 'admin-secret');
+  assert.equal(api.inputTempEmailCustomAuth.value, 'custom-secret');
+  assert.equal(api.inputTempEmailReceiveMailbox.value, 'relay@example.com');
+  assert.equal(api.inputTempEmailUseRandomSubdomain.checked, true);
+  assert.deepEqual(api.calls.domainOptions, ['mail.example.com']);
+  assert.deepEqual(api.calls.domainEditMode, [{ editing: false, options: { clearInput: true } }]);
+});
+
+test('updateMailProviderUI keeps the temp domain selector visible and updates the hint when random subdomain is enabled', () => {
+  const bundle = extractFunction('updateMailProviderUI');
+
+  const api = new Function(`
+let latestState = {
+  cloudflareTempEmailDomains: ['mail.example.com'],
+};
+let cloudflareTempEmailDomainEditMode = false;
+const ICLOUD_PROVIDER = 'icloud';
+const GMAIL_PROVIDER = 'gmail';
+const LUCKMAIL_PROVIDER = 'luckmail-api';
+const rowMail2925Mode = ${JSON.stringify(createRow('none'))};
+const rowMail2925PoolSettings = ${JSON.stringify(createRow('none'))};
+const rowEmailPrefix = ${JSON.stringify(createRow('none'))};
+const rowInbucketHost = ${JSON.stringify(createRow('none'))};
+const rowInbucketMailbox = ${JSON.stringify(createRow('none'))};
+const rowEmailGenerator = ${JSON.stringify(createRow(''))};
+const rowCfDomain = ${JSON.stringify(createRow('none'))};
+const rowTempEmailBaseUrl = ${JSON.stringify(createRow('none'))};
+const rowTempEmailAdminAuth = ${JSON.stringify(createRow('none'))};
+const rowTempEmailCustomAuth = ${JSON.stringify(createRow('none'))};
+const rowTempEmailReceiveMailbox = ${JSON.stringify(createRow('none'))};
+const rowTempEmailRandomSubdomainToggle = ${JSON.stringify(createRow('none'))};
+const rowTempEmailDomain = ${JSON.stringify(createRow('none'))};
+const cloudflareTempEmailSection = ${JSON.stringify(createRow('none'))};
+const hotmailSection = ${JSON.stringify(createRow('none'))};
+const mail2925Section = ${JSON.stringify(createRow('none'))};
+const luckmailSection = ${JSON.stringify(createRow('none'))};
+const icloudSection = ${JSON.stringify(createRow('none'))};
+const labelEmailPrefix = { textContent: '' };
+const inputEmailPrefix = { placeholder: '', style: { display: '' }, readOnly: false };
+const labelMail2925UseAccountPool = ${JSON.stringify(createRow('none'))};
+const selectMail2925PoolAccount = { style: { display: 'none' }, disabled: false };
+const btnFetchEmail = { hidden: false, disabled: false, textContent: '' };
+const btnMailLogin = { disabled: false, textContent: '', title: '' };
+const inputEmail = { readOnly: false, placeholder: '', value: '' };
+const autoHintText = { textContent: '' };
+const rowHotmailServiceMode = ${JSON.stringify(createRow('none'))};
+const rowHotmailRemoteBaseUrl = ${JSON.stringify(createRow('none'))};
+const rowHotmailLocalBaseUrl = ${JSON.stringify(createRow('none'))};
+const inputMail2925UseAccountPool = { checked: false };
+const selectMailProvider = { value: '163' };
+const selectEmailGenerator = { value: 'cloudflare-temp-email', disabled: false };
+const inputTempEmailUseRandomSubdomain = { checked: false };
+const calls = {
+  tempDomainEditMode: [],
+};
+function isLuckmailProvider() { return false; }
+function isCustomMailProvider() { return false; }
+function isIcloudMailProvider() { return false; }
+function usesGeneratedAliasMailProvider() { return false; }
+function getSelectedMail2925Mode() { return 'provide'; }
+function getManagedAliasProviderUiCopy() { return null; }
+function getCurrentRegistrationEmailUiCopy() {
+  return {
+    buttonLabel: '生成 Temp',
+    placeholder: '点击生成 Cloudflare Temp Email，或手动粘贴邮箱',
+    label: 'Cloudflare Temp Email',
+  };
+}
+function updateMailLoginButtonState() {}
+function getSelectedHotmailServiceMode() { return 'local'; }
+function getCloudflareDomainsFromState() { return { domains: [], activeDomain: '' }; }
+function setCloudflareDomainEditMode() {}
+function getCloudflareTempEmailDomainsFromState() { return { domains: ['mail.example.com'], activeDomain: 'mail.example.com' }; }
+function setCloudflareTempEmailDomainEditMode(editing) { calls.tempDomainEditMode.push(editing); }
+function queueIcloudAliasRefresh() {}
+function hideIcloudLoginHelp() {}
+function syncMail2925PoolAccountOptions() {}
+function getMail2925Accounts() { return []; }
+function renderHotmailAccounts() {}
+function renderMail2925Accounts() {}
+function renderLuckmailPurchases() {}
+function getSelectedEmailGenerator() { return String(selectEmailGenerator.value || '').trim().toLowerCase(); }
+function isAutoRunLockedPhase() { return false; }
+${bundle}
+return {
+  updateMailProviderUI,
+  cloudflareTempEmailSection,
+  rowTempEmailRandomSubdomainToggle,
+  rowTempEmailDomain,
+  inputTempEmailUseRandomSubdomain,
+  autoHintText,
+  calls,
+};
+  `)();
+
+  api.updateMailProviderUI();
+  assert.equal(api.cloudflareTempEmailSection.style.display, '');
+  assert.equal(api.rowTempEmailRandomSubdomainToggle.style.display, '');
+  assert.equal(api.rowTempEmailDomain.style.display, '');
+
+  api.inputTempEmailUseRandomSubdomain.checked = true;
+  api.updateMailProviderUI();
+  assert.equal(api.cloudflareTempEmailSection.style.display, '');
+  assert.equal(api.rowTempEmailDomain.style.display, '');
+  assert.match(api.autoHintText.textContent, /RANDOM_SUBDOMAIN_DOMAINS/);
+});
diff --git a/tests/sidepanel-contribution-mode.test.js b/tests/sidepanel-contribution-mode.test.js
index fca11f2..f61d7a5 100644
--- a/tests/sidepanel-contribution-mode.test.js
+++ b/tests/sidepanel-contribution-mode.test.js
@@ -154,6 +154,7 @@ const inputTempEmailBaseUrl = { value: 'https://temp.example.com' };
 const inputTempEmailAdminAuth = { value: 'admin-secret' };
 const inputTempEmailCustomAuth = { value: 'custom-secret' };
 const inputTempEmailReceiveMailbox = { value: 'relay@example.com' };
+const inputTempEmailUseRandomSubdomain = { checked: true };
 const inputAutoSkipFailures = { checked: false };
 const inputAutoSkipFailuresThreadIntervalMinutes = { value: '5' };
 const inputAutoDelayEnabled = { checked: true };
@@ -190,12 +191,14 @@ return {
   assert.equal('customPassword' in contributionPayload, false);
   assert.equal('accountRunHistoryTextEnabled' in contributionPayload, false);
   assert.equal('accountRunHistoryHelperBaseUrl' in contributionPayload, false);
+  assert.equal(contributionPayload.cloudflareTempEmailUseRandomSubdomain, true);
 
   api.setLatestState({ contributionMode: false });
   const normalPayload = api.collectSettingsPayload();
   assert.equal(normalPayload.customPassword, 'Secret123!');
   assert.equal(normalPayload.accountRunHistoryTextEnabled, true);
   assert.equal(normalPayload.accountRunHistoryHelperBaseUrl, 'http://127.0.0.1:17373');
+  assert.equal(normalPayload.cloudflareTempEmailUseRandomSubdomain, true);
 });
 
 test('contribution mode manager enters mode, starts main auto flow, polls contribution status, and exits cleanly', async () => {