From 4ae3646700c5694a02d6891692c70593b1137e29 Mon Sep 17 00:00:00 2001
From: jason5ng32 <jason5ng32@gmail.com>
Date: Sat, 22 Aug 2026 13:32:57 +0800
Subject: [PATCH 01/11] Feat(core): add the app command bus and route
 cross-component triggers through it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Events keep saying "this happened"; commands say "do this" — single owner,
dispatch resolves when the work finishes with the owner's result, reject
codes unavailable/timeout (bus) and auth/quota/input (owners, via
appCommandError). Homepage sections register ipinfo:refresh /
connectivity:run / webrtc:run / dnsleak:run / speedtest:toggle; keyboard
shortcuts, the refresh orchestrator, and Persona Check's dependency repair
dispatch instead of reaching through template refs, and Home.vue sheds the
test-section refs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 frontend/components/ConnectivityTest.vue      |  15 +-
 frontend/components/DnsLeaksTest.vue          |  16 +-
 frontend/components/Home.vue                  |  22 +--
 frontend/components/IpInfos.vue               |  23 ++-
 frontend/components/SpeedTest.vue             |   8 +-
 frontend/components/WebRtcTest.vue            |  17 +-
 .../advanced-tools/PersonaCheck.vue           |  49 ++---
 frontend/composables/use-app-command.js       |  13 ++
 .../composables/use-refresh-orchestrator.js   |  35 ++--
 frontend/composables/use-shortcuts.js         |  31 +--
 frontend/utils/app-commands.js                |  95 ++++++++++
 frontend/utils/app-events.js                  |  22 +++
 tests/app-commands.test.js                    | 177 ++++++++++++++++++
 tests/app-events.test.js                      |  33 +++-
 tests/composable-refresh-orchestrator.test.js |  80 +++++---
 tests/composable-shortcuts.test.js            |  55 ++++--
 16 files changed, 562 insertions(+), 129 deletions(-)
 create mode 100644 frontend/composables/use-app-command.js
 create mode 100644 frontend/utils/app-commands.js
 create mode 100644 tests/app-commands.test.js

diff --git a/frontend/components/ConnectivityTest.vue b/frontend/components/ConnectivityTest.vue
index c69bf92e8..35a591ba9 100644
--- a/frontend/components/ConnectivityTest.vue
+++ b/frontend/components/ConnectivityTest.vue
@@ -106,6 +106,7 @@
 
     <!-- Add / import dialog (custom form + curated list browser) -->
     <ConnectivityAddDialog v-model:open="addDialogOpen" />
+
   </section>
 </template>
 
@@ -114,7 +115,8 @@ import { ref, computed, onMounted, onBeforeUnmount, reactive, watch } from 'vue'
 import { useMainStore } from '@/store';
 import { useI18n } from 'vue-i18n';
 import { trackEvent } from '@/utils/analytics';
-import { emitAppEvent } from '@/utils/app-events';
+import { emitAppEvent, waitForAppEvent } from '@/utils/app-events';
+import { useAppCommand } from '@/composables/use-app-command.js';
 import { CONNECTIVITY_STATUS } from '@/utils/report-schema.js';
 import { TILE_PREVIEW, faviconPath } from '@/data/connectivity-import-lists.js';
 import { removeTarget } from '@/utils/connectivity-import.js';
@@ -512,6 +514,15 @@ const handelCheckStart = async (trigger = 'boot') => {
   }
 };
 
+// Command owner: run the connectivity pass. `trigger` keeps handelCheckStart's
+// toast / card-reset semantics; resolves with the next connectivity:finished
+// snapshot (the first pass in multi-round mode).
+useAppCommand('connectivity:run', ({ trigger = 'manual' } = {}) => {
+  const finished = waitForAppEvent('connectivity:finished');
+  handelCheckStart(trigger);
+  return finished;
+});
+
 onMounted(() => {
   store.setMountingStatus('Connectivity', true);
 });
@@ -528,6 +539,4 @@ onBeforeUnmount(() => {
 // Either signal flipping fires sendAlert; the gates inside pick the winner.
 watch(() => store.allHasLoaded, (v) => { if (v) sendAlert(); });
 watch(allRoundsDone, (v) => { if (v) sendAlert(); });
-
-defineExpose({ handelCheckStart });
 </script>
diff --git a/frontend/components/DnsLeaksTest.vue b/frontend/components/DnsLeaksTest.vue
index 573c1e694..5a50ba106 100644
--- a/frontend/components/DnsLeaksTest.vue
+++ b/frontend/components/DnsLeaksTest.vue
@@ -98,7 +98,8 @@ import { useRouter } from 'vue-router';
 import { useMainStore } from '@/store';
 import { useI18n } from 'vue-i18n';
 import { trackEvent } from '@/utils/analytics';
-import { emitAppEvent } from '@/utils/app-events';
+import { emitAppEvent, waitForAppEvent } from '@/utils/app-events';
+import { useAppCommand } from '@/composables/use-app-command.js';
 import { JnTooltip } from '@/components/ui/tooltip';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent } from '@/components/ui/card';
@@ -252,12 +253,15 @@ const checkAllDNSLeakTest = async (isRefresh) => {
   });
 };
 
-onMounted(() => {
-  store.setMountingStatus('DNSLeakTest', true);
+// Command owner: run all leak providers. Resolves with the next
+// dnsleak:finished snapshot.
+useAppCommand('dnsleak:run', ({ isRefresh = false } = {}) => {
+  const finished = waitForAppEvent('dnsleak:finished');
+  checkAllDNSLeakTest(isRefresh);
+  return finished;
 });
 
-defineExpose({
-  checkAllDNSLeakTest,
-  leakTest,
+onMounted(() => {
+  store.setMountingStatus('DNSLeakTest', true);
 });
 </script>
diff --git a/frontend/components/Home.vue b/frontend/components/Home.vue
index 106501419..43c188ca8 100644
--- a/frontend/components/Home.vue
+++ b/frontend/components/Home.vue
@@ -5,11 +5,11 @@
   <Preferences />
   <main id="mainpart" class="mx-auto w-full px-4 jn-container">
     <div class="rounded-md">
-      <IPCheck ref="IPCheckRef" />
-      <Connectivity ref="connectivityRef" />
-      <WebRTC ref="webRTCRef" />
-      <DNSLeaks ref="dnsLeaksRef" />
-      <SpeedTest ref="speedTestRef" />
+      <IPCheck />
+      <Connectivity />
+      <WebRTC />
+      <DNSLeaks />
+      <SpeedTest />
       <AdvancedTools ref="advancedToolsRef" />
     </div>
   </main>
@@ -75,18 +75,14 @@ const store = useMainStore();
 const configs = computed(() => store.configs);
 const userPreferences = computed(() => store.userPreferences);
 
-// Template refs
+// Template refs — UI chrome only; the test sections are reached through the
+// command bus (utils/app-commands.js), not refs.
 const userRef = ref(null);
 const achievementsRef = ref(null);
 const queryIPRef = ref(null);
 const helpModalRef = ref(null);
 const shareReportRef = ref(null);
-const speedTestRef = ref(null);
 const advancedToolsRef = ref(null);
-const IPCheckRef = ref(null);
-const connectivityRef = ref(null);
-const webRTCRef = ref(null);
-const dnsLeaksRef = ref(null);
 
 // Info mask
 const { infoMaskLevel, isInfosLoaded, showMaskButton, toggleInfoMask } = useInfoMask({
@@ -96,7 +92,6 @@ const { infoMaskLevel, isInfosLoaded, showMaskButton, toggleInfoMask } = useInfo
 
 // Refresh / initial load sequence
 const { loadingControl } = useRefreshOrchestrator({
-    refs: { IPCheckRef, connectivityRef, webRTCRef, dnsLeaksRef },
     store,
     t,
     userPreferences,
@@ -106,8 +101,7 @@ const { loadingControl } = useRefreshOrchestrator({
 // Shortcuts
 const { loadShortcuts } = useShortcuts({
     refs: {
-        queryIPRef, helpModalRef, shareReportRef,
-        speedTestRef, advancedToolsRef, IPCheckRef, connectivityRef, webRTCRef, dnsLeaksRef,
+        queryIPRef, helpModalRef, shareReportRef, advancedToolsRef,
         isInfosLoaded, toggleInfoMask,
     },
     store, t, configs, userPreferences,
diff --git a/frontend/components/IpInfos.vue b/frontend/components/IpInfos.vue
index 25267ebb7..e07c92b6a 100644
--- a/frontend/components/IpInfos.vue
+++ b/frontend/components/IpInfos.vue
@@ -22,6 +22,7 @@
           :asnConnectivityInfos="asnConnectivityInfos" @refresh-card="refreshCard" />
       </div>
     </div>
+
   </section>
 </template>
 
@@ -34,7 +35,8 @@ import { trackEvent } from '@/utils/analytics';
 import { isUsablePublicIP } from '@/utils/valid-ip.js';
 import { transformDataFromIPapi } from '@/utils/transform-ip-data.js';
 import { getIPFromIPIP, getIPFromCloudflare_V4, getIPFromCloudflare_V6, getIPFromIPChecking64, getIPFromIPChecking4, getIPFromIPChecking6 } from '@/utils/getips';
-import { emitAppEvent } from '@/utils/app-events';
+import { emitAppEvent, waitForAppEvent } from '@/utils/app-events';
+import { useAppCommand } from '@/composables/use-app-command.js';
 import { authenticatedFetch, fetchErrorLabel } from '@/utils/authenticated-fetch';
 import IPCard from './ip-infos/IPCard.vue';
 
@@ -430,14 +432,21 @@ watch(IPArray, () => {
   store.updateAllIPs(IPArray.value);
 });
 
-onMounted(() => {
-  store.setMountingStatus('IPInfo', true);
+// Command owner: refresh one card ({ index }) or the whole grid. Resolves
+// with the next ipinfo:finished snapshot — the grid re-emits it whenever a
+// card settles, single-card refreshes included.
+useAppCommand('ipinfo:refresh', ({ index } = {}) => {
+  const finished = waitForAppEvent('ipinfo:finished');
+  if (Number.isInteger(index) && ipDataCards[index]) {
+    refreshCard(ipDataCards[index], index);
+  } else {
+    checkAllIPs();
+  }
+  return finished;
 });
 
-defineExpose({
-  checkAllIPs,
-  ipDataCards,
-  refreshCard,
+onMounted(() => {
+  store.setMountingStatus('IPInfo', true);
 });
 
 </script>
diff --git a/frontend/components/SpeedTest.vue b/frontend/components/SpeedTest.vue
index 26549c6fe..adb953985 100644
--- a/frontend/components/SpeedTest.vue
+++ b/frontend/components/SpeedTest.vue
@@ -165,6 +165,7 @@
         </div>
       </CardContent>
     </Card>
+
   </section>
 </template>
 
@@ -174,6 +175,7 @@ import { useMainStore } from '@/store';
 import { useI18n } from 'vue-i18n';
 import { trackEvent } from '@/utils/analytics';
 import { emitAppEvent } from '@/utils/app-events.js';
+import { useAppCommand } from '@/composables/use-app-command.js';
 import { fetchWithTimeout } from '@/utils/fetch-with-timeout.js';
 import { isValidIP } from '@/utils/valid-ip.js';
 import { parseTrace } from '@/utils/parse-trace.js';
@@ -529,6 +531,10 @@ const speedTestController = async () => {
   }
 };
 
+// Command owner: run / pause / resume toggle, same semantics as the section's
+// own button. Resolves when the toggle applies, not when the test finishes.
+useAppCommand('speedtest:toggle', () => speedTestController());
+
 // --- Lifecycle ----------------------------------------------------------
 
 onMounted(() => { store.setMountingStatus('SpeedTest', true); });
@@ -546,8 +552,6 @@ onUnmounted(() => {
   }
   destroyCharts();
 });
-
-defineExpose({ speedTestController });
 </script>
 
 <style scoped>
diff --git a/frontend/components/WebRtcTest.vue b/frontend/components/WebRtcTest.vue
index c6a38aa19..714129411 100644
--- a/frontend/components/WebRtcTest.vue
+++ b/frontend/components/WebRtcTest.vue
@@ -112,6 +112,7 @@
         </CardContent>
       </Card>
     </div>
+
   </section>
 </template>
 
@@ -120,7 +121,8 @@ import { ref, computed, onMounted, onBeforeUnmount, reactive, watch } from 'vue'
 import { useMainStore } from '@/store';
 import { useI18n } from 'vue-i18n';
 import { trackEvent } from '@/utils/analytics';
-import { emitAppEvent } from '@/utils/app-events';
+import { emitAppEvent, waitForAppEvent } from '@/utils/app-events';
+import { useAppCommand } from '@/composables/use-app-command.js';
 import { JnTooltip } from '@/components/ui/tooltip';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent } from '@/components/ui/card';
@@ -435,6 +437,14 @@ const checkAllWebRTC = async (isRefresh) => {
   });
 };
 
+// Command owner: run all STUN checks. Resolves with the next webrtc:finished
+// snapshot (also emitted when WebRTC is unavailable in this browser).
+useAppCommand('webrtc:run', ({ isRefresh = false } = {}) => {
+  const finished = waitForAppEvent('webrtc:finished');
+  checkAllWebRTC(isRefresh);
+  return finished;
+});
+
 onMounted(() => {
   store.setMountingStatus('WebRTC', true);
 });
@@ -450,9 +460,4 @@ onBeforeUnmount(() => {
 watch(IPArray, () => {
   store.updateAllIPs(IPArray.value);
 }, { deep: true });
-
-defineExpose({
-  checkAllWebRTC,
-  stunServers,
-});
 </script>
diff --git a/frontend/components/advanced-tools/PersonaCheck.vue b/frontend/components/advanced-tools/PersonaCheck.vue
index b4ca89b9c..ecc799d5f 100644
--- a/frontend/components/advanced-tools/PersonaCheck.vue
+++ b/frontend/components/advanced-tools/PersonaCheck.vue
@@ -262,13 +262,14 @@
 </template>
 
 <script setup>
-import { ref, computed, watch, onScopeDispose } from 'vue';
+import { ref, computed, watch } from 'vue';
 import { useI18n } from 'vue-i18n';
 import { useRoute, useRouter } from 'vue-router';
 import { REGEXP_ONLY_DIGITS } from 'vue-input-otp';
 import { useMainStore } from '@/store';
 import { trackEvent } from '@/utils/analytics';
 import { emitAppEvent } from '@/utils/app-events.js';
+import { dispatchAppCommand, waitForAppCommand } from '@/utils/app-commands.js';
 import { authenticatedFetch, fetchErrorLabel } from '@/utils/authenticated-fetch';
 import { buildObservation, usePersonaSnapshots } from '@/composables/use-persona-collector.js';
 import { localProfile } from '@/utils/persona/local-profile.js';
@@ -362,34 +363,40 @@ const requestLocation = async () => {
 const dependencyRows = computed(() => ['ipinfo', 'webrtc', 'dnsleak']
     .map((id) => ({ id, ready: Boolean(snapshots[id]) })));
 
-// The repair click only kicks off the homepage sequence; the tests report back
-// through the snapshots, so the button holds its running state until the last
-// missing one lands rather than disappearing the moment it is pressed. The cap
-// hands the button back if a test never reports at all.
+// The repair click dispatches only the tests that never ran, through the
+// command bus; each dispatch resolves when its test reports. The button holds
+// its running state until every dispatch settles; the per-command timeout
+// hands it back if a test never reports at all.
 const DEPENDENCY_RUN_TIMEOUT = 60 * 1000;
 const runningDependencies = ref(false);
-let dependencyTimer = null;
 
-const stopDependencyRun = () => {
-    runningDependencies.value = false;
-    clearTimeout(dependencyTimer);
-    dependencyTimer = null;
+// missing source id → its owner's command (all payload-free here: these
+// tests never ran, so nothing needs the refresh/reset variants).
+const DEPENDENCY_COMMANDS = {
+    ipinfo: 'ipinfo:refresh',
+    webrtc: 'webrtc:run',
+    dnsleak: 'dnsleak:run',
 };
 
-const runDependencies = () => {
-    if (route.name !== 'home') router.push('/');
+const runDependencies = async () => {
+    if (runningDependencies.value) return;
+    const missing = missingSources.value;
+    if (!missing.length) return;
     runningDependencies.value = true;
-    clearTimeout(dependencyTimer);
-    dependencyTimer = setTimeout(stopDependencyRun, DEPENDENCY_RUN_TIMEOUT);
-    store.setRefreshEveryThing(true);
+    try {
+        // Off the homepage, the owners aren't mounted yet — navigate first,
+        // then wait for each command to be registered before dispatching.
+        if (route.name !== 'home') await router.push('/');
+        await Promise.allSettled(missing.map(async (source) => {
+            const command = DEPENDENCY_COMMANDS[source];
+            await waitForAppCommand(command, { timeoutMs: DEPENDENCY_RUN_TIMEOUT });
+            await dispatchAppCommand(command, {}, { timeoutMs: DEPENDENCY_RUN_TIMEOUT });
+        }));
+    } finally {
+        runningDependencies.value = false;
+    }
 };
 
-watch(missingSources, (missing) => {
-    if (runningDependencies.value && !missing.length) stopDependencyRun();
-});
-
-onScopeDispose(stopDependencyRun);
-
 const report = ref(null);
 const runStatus = ref('idle');
 // Which line renders under the run button; a locale key so it translates live.
diff --git a/frontend/composables/use-app-command.js b/frontend/composables/use-app-command.js
new file mode 100644
index 000000000..1bfcda034
--- /dev/null
+++ b/frontend/composables/use-app-command.js
@@ -0,0 +1,13 @@
+// Vue binding for the command bus (utils/app-commands.js): register a command
+// owner for the life of the current component / effect scope. Registration
+// happens at setup time so the command is dispatchable as soon as the owner
+// exists; the scope's disposal unregisters it.
+
+import { getCurrentScope, onScopeDispose } from 'vue';
+import { registerAppCommand } from '../utils/app-commands.js';
+
+export const useAppCommand = (name, handler) => {
+    const unregister = registerAppCommand(name, handler);
+    if (getCurrentScope()) onScopeDispose(unregister);
+    return unregister;
+};
diff --git a/frontend/composables/use-refresh-orchestrator.js b/frontend/composables/use-refresh-orchestrator.js
index c4e766f28..d95321af7 100644
--- a/frontend/composables/use-refresh-orchestrator.js
+++ b/frontend/composables/use-refresh-orchestrator.js
@@ -1,7 +1,6 @@
 // Refresh / initial load sequence orchestration
 //
 // Input:
-//   - refs: { IPCheckRef, connectivityRef, webRTCRef, dnsLeaksRef }
 //   - store: main store
 //   - t: i18n translation function
 //   - userPreferences: computed(() => store.userPreferences)
@@ -11,9 +10,21 @@
 //   - loadingControl(): initial load sequence starts (after all cards are mounted)
 //
 // Internal:
-//   - monitor store.shouldRefreshEveryThing, trigger refresh → reset loadingStatus → schedule component refreshes → Alert → reset flag
+//   - monitor store.shouldRefreshEveryThing, trigger refresh → reset loadingStatus → dispatch section commands → Alert → reset flag
+//
+// Sections are driven through the command bus (utils/app-commands.js): the
+// owner components register ipinfo:refresh / connectivity:run / webrtc:run /
+// dnsleak:run at setup, before loadingControl's mounted gate opens. Dispatches
+// here are fire-and-forget — completion is reported on the event bus.
 
 import { watch } from 'vue';
+import { dispatchAppCommand } from '../utils/app-commands.js';
+
+const runCommand = (name, payload) => {
+    dispatchAppCommand(name, payload).catch((error) => {
+        console.warn(`[refresh-orchestrator] ${name} failed:`, error);
+    });
+};
 
 function scheduleTimedTasks(tasks) {
     tasks.forEach((task) => {
@@ -24,7 +35,7 @@ function scheduleTimedTasks(tasks) {
     });
 }
 
-export function useRefreshOrchestrator({ refs, store, t, userPreferences, infoMaskLevel }) {
+export function useRefreshOrchestrator({ store, t, userPreferences, infoMaskLevel }) {
     const refreshingAlert = () => {
         store.setAlert(
             true,
@@ -40,12 +51,11 @@ export function useRefreshOrchestrator({ refs, store, t, userPreferences, infoMa
         store.setLoadingStatus('DNSLeakTest', false);
         store.setLoadingStatus('IPInfo', false);
 
-        const { IPCheckRef, connectivityRef, webRTCRef, dnsLeaksRef } = refs;
         scheduleTimedTasks([
-            { action: () => IPCheckRef.value.checkAllIPs(), delay: 0 },
-            { action: () => connectivityRef.value.handelCheckStart('refresh'), delay: 300 },
-            { action: () => webRTCRef.value.checkAllWebRTC(true), delay: 200 },
-            { action: () => dnsLeaksRef.value.checkAllDNSLeakTest(true), delay: 100 },
+            { action: () => runCommand('ipinfo:refresh'), delay: 0 },
+            { action: () => runCommand('connectivity:run', { trigger: 'refresh' }), delay: 300 },
+            { action: () => runCommand('webrtc:run', { isRefresh: true }), delay: 200 },
+            { action: () => runCommand('dnsleak:run', { isRefresh: true }), delay: 100 },
             { action: () => refreshingAlert(), delay: 300 },
         ]);
         infoMaskLevel.value = 0;
@@ -53,27 +63,26 @@ export function useRefreshOrchestrator({ refs, store, t, userPreferences, infoMa
     };
 
     const loadingControl = (t1 = 0, t2 = 300, t3 = 200, t4 = 100) => {
-        const { IPCheckRef, connectivityRef, webRTCRef, dnsLeaksRef } = refs;
         const mountedStatus = Object.values(store.mountingStatus).every(Boolean);
         if (mountedStatus) {
             const prefs = userPreferences.value;
             // IP info always runs on load — it has no per-module switch by design.
-            setTimeout(() => IPCheckRef.value.checkAllIPs(), t1);
+            setTimeout(() => runCommand('ipinfo:refresh'), t1);
             // Each remaining module runs only if its switch is on; when off we
             // flag it loaded immediately so allHasLoaded still resolves — it gates
             // the info-mask button, the user-info fetch, and the brand shimmer.
             if (prefs.autoRunConnectivity) {
-                setTimeout(() => connectivityRef.value.handelCheckStart(), t2);
+                setTimeout(() => runCommand('connectivity:run', { trigger: 'boot' }), t2);
             } else {
                 store.setLoadingStatus('Connectivity', true);
             }
             if (prefs.autoRunWebRTC) {
-                setTimeout(() => webRTCRef.value.checkAllWebRTC(false), t3);
+                setTimeout(() => runCommand('webrtc:run'), t3);
             } else {
                 store.setLoadingStatus('WebRTC', true);
             }
             if (prefs.autoRunDnsLeak) {
-                setTimeout(() => dnsLeaksRef.value.checkAllDNSLeakTest(false), t4);
+                setTimeout(() => runCommand('dnsleak:run'), t4);
             } else {
                 store.setLoadingStatus('DNSLeakTest', true);
             }
diff --git a/frontend/composables/use-shortcuts.js b/frontend/composables/use-shortcuts.js
index da120af2c..fb4ee1fd8 100644
--- a/frontend/composables/use-shortcuts.js
+++ b/frontend/composables/use-shortcuts.js
@@ -1,7 +1,8 @@
 // Keyboard shortcut registration
 //
 // Input:
-//   - refs: all components involved in the shortcut keys (see below for destructuring)
+//   - refs: UI chrome the shortcut keys drive (see below for destructuring) —
+//     test sections aren't here, they're reached via the command bus
 //   - store: main store
 //   - t: i18n translation function
 //   - configs: computed(() => store.configs)
@@ -13,7 +14,8 @@
 //     Config-gated keys fill in reactively when /api/configs lands
 //
 // Note:
-//   - all scrolling + navigation actions use scrollToElement + advancedToolsRef.openTool(slug)
+//   - scrolling + navigation actions use scrollToElement + advancedToolsRef.openTool(slug);
+//     test-running keys dispatch commands on utils/app-commands.js
 //   - `h` key infoMask switch only executes when isInfosLoaded is true
 //   - every entry here is a home-page action. Overlays (Dialog / Sheet /
 //     Drawer) suspend the whole map while they are open — see
@@ -23,21 +25,25 @@
 import { getCurrentScope, onScopeDispose, watch } from 'vue';
 import { trackEvent } from '../utils/analytics.js';
 import { emitAppEvent } from '../utils/app-events.js';
+import { dispatchAppCommand } from '../utils/app-commands.js';
 import { registerShortcuts, keyMap, navigateCards } from '../utils/shortcut.js';
 import { scrollToElement } from '../utils/scroll-to.js';
 import { hasPulseBackend } from '../utils/pulse-beacon.js';
 
+// A shortcut only kicks the run off — completion is the owner's business —
+// so a failed dispatch just logs.
+const runCommand = (name, payload) => {
+    dispatchAppCommand(name, payload).catch((error) => {
+        console.warn(`[shortcuts] ${name} failed:`, error);
+    });
+};
+
 const buildShortcutConfig = ({ refs, store, t, configs, userPreferences }) => {
     const {
         queryIPRef,
         helpModalRef,
         shareReportRef,
-        speedTestRef,
         advancedToolsRef,
-        IPCheckRef,
-        connectivityRef,
-        webRTCRef,
-        dnsLeaksRef,
         isInfosLoaded,
         toggleInfoMask,
     } = refs;
@@ -105,9 +111,8 @@ const buildShortcutConfig = ({ refs, store, t, configs, userPreferences }) => {
             type: 'regex',
             action: (num) => {
                 if (num > userPreferences.value.ipCardsToShow) return;
-                const card = IPCheckRef.value.ipDataCards[num - 1];
                 scrollToElement('IPInfoCard-' + num, 70);
-                IPCheckRef.value.refreshCard(card, num - 1);
+                runCommand('ipinfo:refresh', { index: num - 1 });
                 trackEvent('ShortCut', 'ShortCut', 'IPCheck');
             },
             description: t('shortcutKeys.RefreshIPCard'),
@@ -116,7 +121,7 @@ const buildShortcutConfig = ({ refs, store, t, configs, userPreferences }) => {
             keys: 'c',
             action: () => {
                 scrollToElement('Connectivity', 80);
-                connectivityRef.value.handelCheckStart('manual');
+                runCommand('connectivity:run', { trigger: 'manual' });
                 trackEvent('ShortCut', 'ShortCut', 'Connectivity');
             },
             description: t('shortcutKeys.RefreshConnectivityTests'),
@@ -125,7 +130,7 @@ const buildShortcutConfig = ({ refs, store, t, configs, userPreferences }) => {
             keys: 'w',
             action: () => {
                 scrollToElement('WebRTC', 80);
-                webRTCRef.value.checkAllWebRTC(false);
+                runCommand('webrtc:run', { isRefresh: false });
                 trackEvent('ShortCut', 'ShortCut', 'WebRTC');
             },
             description: t('shortcutKeys.RefreshWebRTC'),
@@ -134,7 +139,7 @@ const buildShortcutConfig = ({ refs, store, t, configs, userPreferences }) => {
             keys: 'd',
             action: () => {
                 scrollToElement('DNSLeakTest', 80);
-                dnsLeaksRef.value.checkAllDNSLeakTest(true);
+                runCommand('dnsleak:run', { isRefresh: true });
                 trackEvent('ShortCut', 'ShortCut', 'DNSLeakTest');
             },
             description: t('shortcutKeys.RefreshDNSLeakTest'),
@@ -143,7 +148,7 @@ const buildShortcutConfig = ({ refs, store, t, configs, userPreferences }) => {
             keys: 's',
             action: () => {
                 scrollToElement('SpeedTest', 80);
-                speedTestRef.value.speedTestController();
+                runCommand('speedtest:toggle');
                 trackEvent('ShortCut', 'ShortCut', 'SpeedTest');
             },
             description: t('shortcutKeys.SpeedTestButton'),
diff --git a/frontend/utils/app-commands.js b/frontend/utils/app-commands.js
new file mode 100644
index 000000000..0299941b5
--- /dev/null
+++ b/frontend/utils/app-commands.js
@@ -0,0 +1,95 @@
+// App-wide command bus — the imperative sibling of app-events.js. Events say
+// "this happened": any number of subscribers, no return value. Commands say
+// "do this": exactly one owner, and dispatching returns a promise that
+// resolves when the work is done, with the owner's result. Owner components
+// register through composables/use-app-command.js; decoupled callers
+// (shortcuts, the refresh orchestrator, Persona Check) dispatch by name.
+// Framework-agnostic on purpose: no Vue imports.
+//
+// Payload contract: a payload is a single plain-JSON object whose shape the
+// command's owner defines and documents at its registration site. Rejections
+// carry `error.code` per the appCommandError vocabulary below, so callers can
+// tell a gated or malformed run from a real failure programmatically.
+
+const handlers = new Map(); // command name → handler
+const registrationHooks = new Map(); // command name → Set<hook> (waitForAppCommand)
+
+// Structured rejection for command owners: a real Error carrying a machine-
+// readable `code`. Reserved codes —
+//   bus-level (produced by the bus itself):
+//     'unavailable' — no owner registered for the command
+//     'timeout'     — the handler (or registration wait) exceeded timeoutMs
+//   owner-level (produced by handlers, by convention):
+//     'auth'  — sign-in required
+//     'quota' — usage limit reached
+//     'input' — payload missing or invalid
+// Owners may add domain-specific codes, but these five names keep these
+// meanings everywhere on the bus.
+export const appCommandError = (code, message) => Object.assign(new Error(message), { code });
+
+// Register the single owner of a command. A second registration wins the name
+// (warned — two live owners is a wiring bug); the returned unregister only
+// removes its own handler, so a stale owner can't evict its replacement.
+export const registerAppCommand = (name, handler) => {
+    if (handlers.has(name)) {
+        console.warn(`[app-commands] "${name}" re-registered; replacing the previous owner`);
+    }
+    handlers.set(name, handler);
+    const hooks = registrationHooks.get(name);
+    if (hooks) {
+        registrationHooks.delete(name);
+        for (const hook of hooks) hook();
+    }
+    return () => {
+        if (handlers.get(name) === handler) handlers.delete(name);
+    };
+};
+
+export const hasAppCommand = (name) => handlers.has(name);
+
+// Run a command. The handler is invoked synchronously; the promise resolves
+// with its result once the work completes. Rejects with code 'unavailable'
+// (no owner), 'timeout' (took longer than timeoutMs), or whatever the
+// handler threw.
+export const dispatchAppCommand = (name, payload = {}, { timeoutMs } = {}) => {
+    const handler = handlers.get(name);
+    if (!handler) {
+        return Promise.reject(appCommandError('unavailable', `[app-commands] no handler registered for "${name}"`));
+    }
+    let result;
+    try {
+        result = Promise.resolve(handler(payload));
+    } catch (error) {
+        return Promise.reject(error);
+    }
+    if (!timeoutMs) return result;
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(appCommandError('timeout', `[app-commands] command "${name}" timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    return Promise.race([result, timeout]).finally(() => clearTimeout(timer));
+};
+
+// Resolve once the command has an owner (immediately if it already does) —
+// lets a caller dispatch right after navigating to the page that registers
+// it. With timeoutMs, rejects with code 'timeout' if no owner appears.
+export const waitForAppCommand = (name, { timeoutMs } = {}) => {
+    if (handlers.has(name)) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        let timer;
+        const hook = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        if (!registrationHooks.has(name)) registrationHooks.set(name, new Set());
+        registrationHooks.get(name).add(hook);
+        if (timeoutMs) {
+            timer = setTimeout(() => {
+                registrationHooks.get(name)?.delete(hook);
+                reject(appCommandError('timeout', `[app-commands] command "${name}" was not registered within ${timeoutMs}ms`));
+            }, timeoutMs);
+        }
+    });
+};
diff --git a/frontend/utils/app-events.js b/frontend/utils/app-events.js
index 3045e982a..c582ad9e1 100644
--- a/frontend/utils/app-events.js
+++ b/frontend/utils/app-events.js
@@ -19,6 +19,28 @@ export const onAppEvent = (event, handler) => {
     };
 };
 
+// One-shot subscription: resolves with the next payload of the event. Safe
+// to call before triggering the producer — subscribe first, then invoke.
+// With timeoutMs, rejects (code 'timeout') and unsubscribes if the event
+// never fires.
+export const waitForAppEvent = (event, { timeoutMs } = {}) => new Promise((resolve, reject) => {
+    let timer;
+    const off = onAppEvent(event, (payload) => {
+        clearTimeout(timer);
+        off();
+        resolve(payload);
+    });
+    if (timeoutMs) {
+        timer = setTimeout(() => {
+            off();
+            reject(Object.assign(
+                new Error(`[app-events] "${event}" did not fire within ${timeoutMs}ms`),
+                { code: 'timeout' },
+            ));
+        }, timeoutMs);
+    }
+});
+
 // Emit an event to all subscribers. Emitting is fire-and-forget: a throwing
 // handler must not break the emitter or the remaining handlers.
 export const emitAppEvent = (event, payload = {}) => {
diff --git a/tests/app-commands.test.js b/tests/app-commands.test.js
new file mode 100644
index 000000000..60bdb1a45
--- /dev/null
+++ b/tests/app-commands.test.js
@@ -0,0 +1,177 @@
+// Tests for the app-wide command bus (frontend/utils/app-commands.js):
+// single-owner registration, dispatch / result semantics, 'unavailable' and
+// 'timeout' rejection codes, the appCommandError owner-rejection helper, and
+// waitForAppCommand registration hooks.
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import {
+  registerAppCommand,
+  dispatchAppCommand,
+  hasAppCommand,
+  waitForAppCommand,
+  appCommandError,
+} from '../frontend/utils/app-commands.js';
+
+const withSilencedWarn = async (fn) => {
+  const original = console.warn;
+  console.warn = () => {};
+  try {
+    return await fn();
+  } finally {
+    console.warn = original;
+  }
+};
+
+describe('app-commands', () => {
+  it('dispatch resolves with the handler result and passes the payload', async () => {
+    const off = registerAppCommand('test:echo', (payload) => ({ got: payload.value }));
+    try {
+      assert.deepEqual(await dispatchAppCommand('test:echo', { value: 7 }), { got: 7 });
+    } finally {
+      off();
+    }
+  });
+
+  it('defaults the payload to an empty object and awaits async handlers', async () => {
+    const off = registerAppCommand('test:async', async (payload) => payload);
+    try {
+      assert.deepEqual(await dispatchAppCommand('test:async'), {});
+    } finally {
+      off();
+    }
+  });
+
+  it('dispatch with no handler rejects with code "unavailable"', async () => {
+    await assert.rejects(dispatchAppCommand('test:nobody'), (error) => {
+      assert.equal(error.code, 'unavailable');
+      assert.match(error.message, /test:nobody/);
+      return true;
+    });
+  });
+
+  it('re-registering warns and the new handler wins', async () => {
+    await withSilencedWarn(async () => {
+      let warned = 0;
+      const originalWarn = console.warn;
+      console.warn = () => { warned += 1; };
+      const offA = registerAppCommand('test:owner', () => 'a');
+      const offB = registerAppCommand('test:owner', () => 'b');
+      console.warn = originalWarn;
+      try {
+        assert.equal(warned, 1, 'second registration warns');
+        assert.equal(await dispatchAppCommand('test:owner'), 'b');
+      } finally {
+        offA();
+        offB();
+      }
+    });
+  });
+
+  it('an unregister only removes its own handler, never a replacement', async () => {
+    await withSilencedWarn(async () => {
+      const offA = registerAppCommand('test:stale', () => 'a');
+      const offB = registerAppCommand('test:stale', () => 'b');
+      offA(); // stale owner unregisters after being replaced
+      try {
+        assert.equal(hasAppCommand('test:stale'), true, 'replacement survives');
+        assert.equal(await dispatchAppCommand('test:stale'), 'b');
+      } finally {
+        offB();
+      }
+      assert.equal(hasAppCommand('test:stale'), false);
+    });
+  });
+
+  it('a throwing handler propagates as a rejection (sync and async)', async () => {
+    const offSync = registerAppCommand('test:throws', () => { throw new Error('sync boom'); });
+    const offAsync = registerAppCommand('test:rejects', async () => { throw new Error('async boom'); });
+    try {
+      await assert.rejects(dispatchAppCommand('test:throws'), /sync boom/);
+      await assert.rejects(dispatchAppCommand('test:rejects'), /async boom/);
+    } finally {
+      offSync();
+      offAsync();
+    }
+  });
+
+  it('a handler rejecting with appCommandError surfaces its code to the dispatcher', async () => {
+    const off = registerAppCommand('test:gated', () => {
+      throw appCommandError('auth', 'sign-in required');
+    });
+    try {
+      await assert.rejects(dispatchAppCommand('test:gated'), (error) => {
+        assert.ok(error instanceof Error, 'helper produces a real Error');
+        assert.equal(error.code, 'auth');
+        assert.equal(error.message, 'sign-in required');
+        return true;
+      });
+    } finally {
+      off();
+    }
+  });
+
+  it('timeoutMs rejects a hung handler with code "timeout", naming the command', async () => {
+    const off = registerAppCommand('test:hangs', () => new Promise(() => {}));
+    try {
+      await assert.rejects(
+        dispatchAppCommand('test:hangs', {}, { timeoutMs: 20 }),
+        (error) => {
+          assert.equal(error.code, 'timeout');
+          assert.match(error.message, /test:hangs/);
+          return true;
+        },
+      );
+    } finally {
+      off();
+    }
+  });
+
+  it('a handler resolving before timeoutMs wins the race', async () => {
+    const off = registerAppCommand('test:fast', async () => 'done');
+    try {
+      assert.equal(await dispatchAppCommand('test:fast', {}, { timeoutMs: 1000 }), 'done');
+    } finally {
+      off();
+    }
+  });
+
+  it('hasAppCommand reflects registration state', () => {
+    assert.equal(hasAppCommand('test:presence'), false);
+    const off = registerAppCommand('test:presence', () => {});
+    assert.equal(hasAppCommand('test:presence'), true);
+    off();
+    assert.equal(hasAppCommand('test:presence'), false);
+  });
+
+  it('waitForAppCommand resolves immediately for an already-registered command', async () => {
+    const off = registerAppCommand('test:already', () => {});
+    try {
+      await waitForAppCommand('test:already');
+    } finally {
+      off();
+    }
+  });
+
+  it('waitForAppCommand resolves when the command registers later', async () => {
+    const waited = waitForAppCommand('test:later', { timeoutMs: 1000 });
+    const off = registerAppCommand('test:later', () => {});
+    try {
+      await waited;
+    } finally {
+      off();
+    }
+  });
+
+  it('waitForAppCommand rejects with code "timeout" when nothing registers', async () => {
+    await assert.rejects(
+      waitForAppCommand('test:never', { timeoutMs: 20 }),
+      (error) => {
+        assert.equal(error.code, 'timeout');
+        assert.match(error.message, /test:never/);
+        return true;
+      },
+    );
+  });
+});
diff --git a/tests/app-events.test.js b/tests/app-events.test.js
index 26c7bfce8..5bdac10f8 100644
--- a/tests/app-events.test.js
+++ b/tests/app-events.test.js
@@ -1,10 +1,11 @@
 // Tests for the app-wide event bus (frontend/utils/app-events.js):
-// subscribe / emit / unsubscribe semantics and handler error isolation.
+// subscribe / emit / unsubscribe semantics, handler error isolation, and the
+// waitForAppEvent one-shot subscription.
 
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 
-import { onAppEvent, emitAppEvent } from '../frontend/utils/app-events.js';
+import { onAppEvent, emitAppEvent, waitForAppEvent } from '../frontend/utils/app-events.js';
 
 describe('app-events', () => {
   it('delivers the payload to every subscriber of the event', () => {
@@ -54,4 +55,32 @@ describe('app-events', () => {
   it('emitting an event with no subscribers is a no-op', () => {
     assert.doesNotThrow(() => emitAppEvent('test:nobody-listens', { any: 'thing' }));
   });
+
+  it('waitForAppEvent resolves with the next payload, subscribe-before-trigger', async () => {
+    const waited = waitForAppEvent('test:one-shot');
+    emitAppEvent('test:one-shot', { value: 1 });
+    assert.deepEqual(await waited, { value: 1 });
+  });
+
+  it('waitForAppEvent is one-shot: only the first emission is delivered', async () => {
+    let delivered = 0;
+    const waited = waitForAppEvent('test:one-shot-only').then(() => { delivered += 1; });
+    emitAppEvent('test:one-shot-only', { n: 1 });
+    emitAppEvent('test:one-shot-only', { n: 2 });
+    await waited;
+    assert.equal(delivered, 1);
+  });
+
+  it('waitForAppEvent rejects with code "timeout" and unsubscribes', async () => {
+    await assert.rejects(
+      waitForAppEvent('test:never-fires', { timeoutMs: 20 }),
+      (error) => {
+        assert.equal(error.code, 'timeout');
+        assert.match(error.message, /test:never-fires/);
+        return true;
+      },
+    );
+    // The timed-out subscription is gone: emitting afterwards is a no-op.
+    assert.doesNotThrow(() => emitAppEvent('test:never-fires'));
+  });
 });
diff --git a/tests/composable-refresh-orchestrator.test.js b/tests/composable-refresh-orchestrator.test.js
index c4b4edc80..2ebfd9055 100644
--- a/tests/composable-refresh-orchestrator.test.js
+++ b/tests/composable-refresh-orchestrator.test.js
@@ -3,6 +3,7 @@ import { describe, it, beforeEach, afterEach } from 'node:test';
 import { ref, computed, reactive, nextTick } from 'vue';
 
 import { useRefreshOrchestrator } from '../frontend/composables/use-refresh-orchestrator.js';
+import { registerAppCommand } from '../frontend/utils/app-commands.js';
 
 const t = (k) => `<${k}>`;
 
@@ -32,42 +33,49 @@ function makeStoreStub({ mountedFlags = {}, shouldRefresh = false, autoRun = {}
   };
 }
 
-function makeRefs() {
-  const calls = { ip: 0, conn: [], web: [], dns: [] };
-  const IPCheckRef       = ref({ checkAllIPs:            () => { calls.ip += 1; } });
-  const connectivityRef  = ref({ handelCheckStart:       (flag) => { calls.conn.push(flag); } });
-  const webRTCRef        = ref({ checkAllWebRTC:         (flag) => { calls.web.push(flag); } });
-  const dnsLeaksRef      = ref({ checkAllDNSLeakTest:    (flag) => { calls.dns.push(flag); } });
-  return { refs: { IPCheckRef, connectivityRef, webRTCRef, dnsLeaksRef }, calls };
+// The orchestrator drives sections through the command bus; stub the four
+// owner commands and record the payloads each dispatch carried.
+function registerCommandStubs() {
+  const calls = { ip: [], conn: [], web: [], dns: [] };
+  const unregisters = [
+    registerAppCommand('ipinfo:refresh', (payload) => { calls.ip.push(payload); }),
+    registerAppCommand('connectivity:run', (payload) => { calls.conn.push(payload.trigger); }),
+    registerAppCommand('webrtc:run', (payload) => { calls.web.push(payload.isRefresh); }),
+    registerAppCommand('dnsleak:run', (payload) => { calls.dns.push(payload.isRefresh); }),
+  ];
+  return { calls, unregister: () => unregisters.forEach((off) => off()) };
 }
 
 describe('useRefreshOrchestrator()', () => {
   let realSetTimeout;
+  let stubs;
   beforeEach(() => {
     // synchronize setTimeout immediately: ignore delay, for assertion order
     realSetTimeout = globalThis.setTimeout;
     globalThis.setTimeout = (fn) => { fn(); return 0; };
+    stubs = registerCommandStubs();
   });
   afterEach(() => {
     globalThis.setTimeout = realSetTimeout;
+    stubs.unregister();
   });
 
-  it('loadingControl: all cards mounted + every module on triggers all four checks', () => {
+  it('loadingControl: all cards mounted + every module on dispatches all four commands', () => {
     const store = makeStoreStub({
       mountedFlags: { IPInfo: true, Connectivity: true, WebRTC: true, DNSLeakTest: true },
       autoRun: { autoRunConnectivity: true, autoRunWebRTC: true, autoRunDnsLeak: true },
     });
     const userPreferences = computed(() => store.state.userPreferences);
     const infoMaskLevel = ref(0);
-    const { refs, calls } = makeRefs();
+    const { calls } = stubs;
 
-    const { loadingControl } = useRefreshOrchestrator({ refs, store, t, userPreferences, infoMaskLevel });
+    const { loadingControl } = useRefreshOrchestrator({ store, t, userPreferences, infoMaskLevel });
     loadingControl();
 
-    assert.equal(calls.ip, 1);
-    assert.deepEqual(calls.conn, [undefined]); // initial load passes no arg
-    assert.deepEqual(calls.web, [false]);
-    assert.deepEqual(calls.dns, [false]);
+    assert.equal(calls.ip.length, 1);
+    assert.deepEqual(calls.conn, ['boot'], 'initial load runs the boot trigger');
+    assert.deepEqual(calls.web, [undefined], 'initial load leaves isRefresh to the owner default');
+    assert.deepEqual(calls.dns, [undefined]);
   });
 
   it('loadingControl: every module off skips auto checks and flags loading complete', () => {
@@ -77,12 +85,12 @@ describe('useRefreshOrchestrator()', () => {
     });
     const userPreferences = computed(() => store.state.userPreferences);
     const infoMaskLevel = ref(0);
-    const { refs, calls } = makeRefs();
+    const { calls } = stubs;
 
-    const { loadingControl } = useRefreshOrchestrator({ refs, store, t, userPreferences, infoMaskLevel });
+    const { loadingControl } = useRefreshOrchestrator({ store, t, userPreferences, infoMaskLevel });
     loadingControl();
 
-    assert.equal(calls.ip, 1, 'IP info always runs');
+    assert.equal(calls.ip.length, 1, 'IP info always runs');
     assert.deepEqual(calls.conn, [], 'connectivity should not auto-run');
     assert.deepEqual(calls.web, [], 'webrtc should not auto-run');
     assert.deepEqual(calls.dns, [], 'dns leak test should not auto-run');
@@ -98,13 +106,13 @@ describe('useRefreshOrchestrator()', () => {
     });
     const userPreferences = computed(() => store.state.userPreferences);
     const infoMaskLevel = ref(0);
-    const { refs, calls } = makeRefs();
+    const { calls } = stubs;
 
-    const { loadingControl } = useRefreshOrchestrator({ refs, store, t, userPreferences, infoMaskLevel });
+    const { loadingControl } = useRefreshOrchestrator({ store, t, userPreferences, infoMaskLevel });
     loadingControl();
 
-    assert.equal(calls.ip, 1);
-    assert.deepEqual(calls.conn, [undefined], 'connectivity runs');
+    assert.equal(calls.ip.length, 1);
+    assert.deepEqual(calls.conn, ['boot'], 'connectivity runs');
     assert.deepEqual(calls.web, [], 'webrtc stays off');
     assert.deepEqual(calls.dns, [], 'dns stays off');
     // Connectivity flags itself loaded when its check resolves (not here);
@@ -119,15 +127,15 @@ describe('useRefreshOrchestrator()', () => {
     const store = makeStoreStub();
     const userPreferences = computed(() => store.state.userPreferences);
     const infoMaskLevel = ref(2);
-    const { refs, calls } = makeRefs();
+    const { calls } = stubs;
 
-    useRefreshOrchestrator({ refs, store, t, userPreferences, infoMaskLevel });
+    useRefreshOrchestrator({ store, t, userPreferences, infoMaskLevel });
 
     // flip the trigger
     store.state.shouldRefreshEveryThing = true;
     await nextTick();
 
-    assert.equal(calls.ip, 1, 'ipcheck refreshes');
+    assert.equal(calls.ip.length, 1, 'ipcheck refreshes');
     assert.deepEqual(calls.conn, ['refresh'], 'connectivity refresh via the refresh trigger');
     assert.deepEqual(calls.web, [true]);
     assert.deepEqual(calls.dns, [true]);
@@ -140,6 +148,27 @@ describe('useRefreshOrchestrator()', () => {
     assert.equal(alert.style, 'text-success');
   });
 
+  it('refresh with no command owners logs, never throws', async () => {
+    stubs.unregister();
+    const warns = [];
+    const originalWarn = console.warn;
+    console.warn = (...args) => { warns.push(args[0]); };
+    try {
+      const store = makeStoreStub();
+      const userPreferences = computed(() => store.state.userPreferences);
+      const infoMaskLevel = ref(0);
+      useRefreshOrchestrator({ store, t, userPreferences, infoMaskLevel });
+      store.state.shouldRefreshEveryThing = true;
+      await nextTick();
+      // Let the dispatch rejections reach their .catch handlers.
+      await Promise.resolve();
+      await Promise.resolve();
+      assert.equal(warns.length, 4, 'each unavailable command logs one warning');
+    } finally {
+      console.warn = originalWarn;
+    }
+  });
+
   it('loadingControl: not all mounted → re-schedules itself until ready', () => {
     let attemptCount = 0;
     const scheduled = [];
@@ -158,9 +187,8 @@ describe('useRefreshOrchestrator()', () => {
     });
     const userPreferences = computed(() => store.state.userPreferences);
     const infoMaskLevel = ref(0);
-    const { refs } = makeRefs();
 
-    const { loadingControl } = useRefreshOrchestrator({ refs, store, t, userPreferences, infoMaskLevel });
+    const { loadingControl } = useRefreshOrchestrator({ store, t, userPreferences, infoMaskLevel });
 
     // run first attempt (mounted = false) → schedule retry 1s later
     loadingControl();
diff --git a/tests/composable-shortcuts.test.js b/tests/composable-shortcuts.test.js
index 373f34ac0..7f17d5f81 100644
--- a/tests/composable-shortcuts.test.js
+++ b/tests/composable-shortcuts.test.js
@@ -47,9 +47,28 @@ registerHooks({
 
 const { useShortcuts } = await import('../frontend/composables/use-shortcuts.js');
 const { onAppEvent } = await import('../frontend/utils/app-events.js');
+const { registerAppCommand } = await import('../frontend/utils/app-commands.js');
 
 const t = (k) => `<${k}>`;
 
+// The test-running shortcuts dispatch on the command bus rather than calling
+// through refs. Register the five owner commands once, into a shared record
+// that loadAndGetKeyMap resets per test.
+const commandCalls = { ipRefresh: [], connectivity: [], webrtc: [], dnsleak: [], speedTest: 0 };
+registerAppCommand('ipinfo:refresh', (payload) => { commandCalls.ipRefresh.push(payload.index); });
+registerAppCommand('connectivity:run', (payload) => { commandCalls.connectivity.push(payload.trigger); });
+registerAppCommand('webrtc:run', (payload) => { commandCalls.webrtc.push(payload.isRefresh); });
+registerAppCommand('dnsleak:run', (payload) => { commandCalls.dnsleak.push(payload.isRefresh); });
+registerAppCommand('speedtest:toggle', () => { commandCalls.speedTest += 1; });
+
+const resetCommandCalls = () => {
+  commandCalls.ipRefresh = [];
+  commandCalls.connectivity = [];
+  commandCalls.webrtc = [];
+  commandCalls.dnsleak = [];
+  commandCalls.speedTest = 0;
+};
+
 function makeStoreStub() {
   const state = reactive({
     refreshRequested: false,
@@ -63,18 +82,20 @@ function makeStoreStub() {
 }
 
 function makeRefs() {
+  // UI-chrome calls live here; the test-section calls land in commandCalls
+  // (merged into the returned record so assertions read one object).
   const calls = {
     queryOpen: 0,
     helpOpen: 0,
     shareOpen: 0,
-    speedTest: 0,
     advancedNavigate: [],
     advancedFullScreen: 0,
-    ipRefresh: [],
-    connectivity: [],
-    webrtc: [],
-    dnsleak: [],
     mask: 0,
+    get speedTest() { return commandCalls.speedTest; },
+    get ipRefresh() { return commandCalls.ipRefresh; },
+    get connectivity() { return commandCalls.connectivity; },
+    get webrtc() { return commandCalls.webrtc; },
+    get dnsleak() { return commandCalls.dnsleak; },
   };
 
   const advancedToolsRef = ref({
@@ -87,18 +108,7 @@ function makeRefs() {
       queryIPRef:        ref({ openModal: () => { calls.queryOpen += 1; } }),
       helpModalRef:      ref({ openModal: () => { calls.helpOpen += 1; }, keyMap: null }),
       shareReportRef:    ref({ openDialog: () => { calls.shareOpen += 1; } }),
-      speedTestRef:      ref({ speedTestController: () => { calls.speedTest += 1; } }),
       advancedToolsRef,
-      IPCheckRef:        ref({
-        ipDataCards: [
-          { id: 'a', ip: '1.1.1.1' }, { id: 'b', ip: '2.2.2.2' }, { id: 'c', ip: '3.3.3.3' },
-          { id: 'd', ip: '4.4.4.4' }, { id: 'e', ip: '5.5.5.5' }, { id: 'f', ip: '6.6.6.6' },
-        ],
-        refreshCard: (_card, i) => { calls.ipRefresh.push(i); },
-      }),
-      connectivityRef:   ref({ handelCheckStart: (flag) => { calls.connectivity.push(flag); } }),
-      webRTCRef:         ref({ checkAllWebRTC: (flag) => { calls.webrtc.push(flag); } }),
-      dnsLeaksRef:       ref({ checkAllDNSLeakTest: (flag) => { calls.dnsleak.push(flag); } }),
       isInfosLoaded:     ref(true),
       toggleInfoMask:    () => { calls.mask += 1; },
     },
@@ -117,6 +127,7 @@ function loadAndGetKeyMap({
   cloudFlare = false,
 } = {}) {
   globalThis.__setPulseBackendForTest(pulseBackend);
+  resetCommandCalls();
   const store = makeStoreStub();
   const { refs, calls } = makeRefs();
   const configs = computed(() => ({ originalSite, map: true, cloudFlare }));
@@ -196,6 +207,18 @@ describe('useShortcuts()', () => {
     assert.deepEqual(calls.ipRefresh, [], 'num > ipCardsToShow → no-op');
   });
 
+  it('"c"/"w"/"d"/"s" dispatch the section commands with their payloads', () => {
+    const { keyMap, calls } = loadAndGetKeyMap();
+    keyMap.findLast((e) => e.keys === 'c').action();
+    keyMap.findLast((e) => e.keys === 'w').action();
+    keyMap.findLast((e) => e.keys === 'd').action();
+    keyMap.findLast((e) => e.keys === 's').action();
+    assert.deepEqual(calls.connectivity, ['manual']);
+    assert.deepEqual(calls.webrtc, [false]);
+    assert.deepEqual(calls.dnsleak, [true]);
+    assert.equal(calls.speedTest, 1, 'the s key stays a run/pause toggle');
+  });
+
   it('"?" opens help modal and emits the shortcut:help-opened app event', () => {
     // The achievement itself (CleverTrickery) is the engine's concern —
     // use-shortcuts only emits the domain event. See achievement-rules tests.

From 0907d563afeee12221919699cf55ab5abb93f5c7 Mon Sep 17 00:00:00 2001
From: jason5ng32 <jason5ng32@gmail.com>
Date: Sat, 22 Aug 2026 13:33:05 +0800
Subject: [PATCH 02/11] Feat(nav): let the docs assistant run the visitor's
 core tests

Second GitBook tool run_my_tests rides the command bus: optional sections
subset, navigate home first when needed, waitForAppCommand + dispatch per
test with a 60s cap, allSettled partial-failure semantics, and the same
snapshot shape the read tool returns plus ran/failed lists. Confirmation
label and summary land in all four locales.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 frontend/composables/use-docs-assistant.js | 112 ++++++++++++++++++---
 frontend/locales/en.json                   |   2 +
 frontend/locales/fr.json                   |   2 +
 frontend/locales/ru.json                   |   2 +
 frontend/locales/zh.json                   |   2 +
 frontend/utils/docs-run-tests.js           |  36 +++++++
 tests/docs-run-tests.test.js               |  66 ++++++++++++
 7 files changed, 206 insertions(+), 16 deletions(-)
 create mode 100644 frontend/utils/docs-run-tests.js
 create mode 100644 tests/docs-run-tests.test.js

diff --git a/frontend/composables/use-docs-assistant.js b/frontend/composables/use-docs-assistant.js
index 59214e2b0..a8ce9876d 100644
--- a/frontend/composables/use-docs-assistant.js
+++ b/frontend/composables/use-docs-assistant.js
@@ -18,11 +18,14 @@
 // reports back through `setOpen`. It drives the touch-only chrome there — a
 // tap-outside backdrop and a body scroll lock.
 //
-// One tool is registered (`get_my_test_results`): the assistant can read the
+// Two tools are registered. `get_my_test_results`: the assistant can read the
 // visitor's finished on-page diagnostics — the report collector's snapshots,
 // annotated with each test's localized product name so the assistant refers
 // to tests as the visitor knows them, not by raw schema ids. It asks for
-// confirmation first, since those results carry their IP.
+// confirmation first, since those results carry their IP. `run_my_tests`:
+// the assistant can (re)run the four core tests through the app command bus
+// (navigating home first, since the owners only live there) and gets the
+// fresh snapshots back once they finish.
 //
 // The welcome screen's greeting, suggestions and the sidebar action are
 // localized, and re-sent on every open so a language switch takes effect. The
@@ -34,10 +37,13 @@
 // docs site in a new tab so the action never dead-ends.
 import { ref } from 'vue';
 import { useI18n } from 'vue-i18n';
+import { useRoute, useRouter } from 'vue-router';
 import { useMainStore } from '@/store';
 import { useCollectedReport } from '@/composables/use-report-collector.js';
 import { REPORT_SECTION_IDS } from '@/utils/report-schema.js';
 import { SECTION_TITLE_KEYS } from '@/utils/report-export.js';
+import { dispatchAppCommand, waitForAppCommand } from '@/utils/app-commands.js';
+import { RUNNABLE_SECTION_COMMANDS, RUNNABLE_SECTION_IDS, normalizeRunSections } from '@/utils/docs-run-tests.js';
 
 export const DOCS_URL = (import.meta.env?.VITE_DOCS_URL || '').replace(/\/+$/, '');
 export const isDocsConfigured = !!DOCS_URL;
@@ -81,12 +87,34 @@ const loadEmbedScript = () => {
     return loadPromise;
 };
 
+// The command owners only exist while the home route is mounted; if a run
+// never reports (or the owner never appears), the per-command timeout hands
+// the tool call back instead of hanging the assistant.
+const RUN_TEST_TIMEOUT = 60 * 1000;
+
 export function useDocsAssistant() {
     const { t, tm, rt } = useI18n();
     const store = useMainStore();
+    const route = useRoute();
+    const router = useRouter();
     const isOpening = ref(false);
     const { sections } = useCollectedReport();
 
+    // Schema-shaped snapshots annotated with localized product names — the
+    // payload both tools return (read as-is, run after the tests finish).
+    const buildResultsSnapshot = () => {
+        const available = Object.keys(sections);
+        const sectionName = (id) => t(SECTION_TITLE_KEYS[id]);
+        return {
+            results: Object.fromEntries(available.map((id) => [id, {
+                name: sectionName(id),
+                ...JSON.parse(JSON.stringify(sections[id])),
+            }])),
+            missingSections: REPORT_SECTION_IDS.filter((id) => !available.includes(id))
+                .map((id) => ({ id, name: sectionName(id) })),
+        };
+    };
+
     // Localized suggestion questions (shared with the nav placeholder rotation).
     const docsQuestions = () => tm('nav.DocsQuestions').map((message) => rt(message));
 
@@ -113,20 +141,72 @@ export function useDocsAssistant() {
         ].join(' '),
         inputSchema: { type: 'object', properties: {}, required: [] },
         confirmation: { icon: 'eye', label: t('nav.DocsToolConfirm') },
-        execute: async () => {
-            const available = Object.keys(sections);
-            // Localized product names alongside the schema ids
-            const sectionName = (id) => t(SECTION_TITLE_KEYS[id]);
-            return {
-                output: {
-                    results: Object.fromEntries(available.map((id) => [id, {
-                        name: sectionName(id),
-                        ...JSON.parse(JSON.stringify(sections[id])),
-                    }])),
-                    missingSections: REPORT_SECTION_IDS.filter((id) => !available.includes(id))
-                        .map((id) => ({ id, name: sectionName(id) })),
+        execute: async () => ({
+            output: buildResultsSnapshot(),
+            summary: { icon: 'eye', text: t('nav.DocsToolSummary') },
+        }),
+    };
+
+    // Tool the assistant can call to actually (re)run the four core tests,
+    // PersonaCheck-style: navigate home if needed (the command owners only
+    // live there), wait for each owner, dispatch, and report the refreshed
+    // snapshots plus what ran, failed, or wasn't recognized. Partial failure
+    // is fine — allSettled keeps the healthy tests' results.
+    const runTestsTool = {
+        name: 'run_my_tests',
+        description: [
+            "Run (or re-run) the visitor's core network tests on their MyIP page",
+            'and return the fresh results when they finish.',
+            'Use it when the visitor asks to run, re-run, or refresh their tests,',
+            'or when the results a question needs are missing or stale.',
+            'It covers ONLY the four core tests: IP address lookup (`ipinfo`),',
+            'website connectivity (`connectivity`), WebRTC leak (`webrtc`), and',
+            'DNS leak (`dnsleak`) — no other tool or test can be started this way;',
+            'ask the visitor to run those themselves.',
+            'Takes roughly 10-60 seconds. The output lists what `ran`, what',
+            '`failed`, and the same results snapshot `get_my_test_results` returns.',
+        ].join(' '),
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sections: {
+                    type: 'array',
+                    items: { type: 'string', enum: RUNNABLE_SECTION_IDS },
+                    description: [
+                        'Which tests to run: ipinfo (IP address lookup),',
+                        'connectivity (website connectivity), webrtc (WebRTC leak),',
+                        'dnsleak (DNS leak).',
+                        'Omit or pass an empty array to run all four.',
+                    ].join(' '),
                 },
-                summary: { icon: 'eye', text: t('nav.DocsToolSummary') },
+            },
+            required: [],
+        },
+        confirmation: { icon: 'play', label: t('nav.DocsToolRunConfirm') },
+        execute: async (args) => {
+            const { requested, unknown } = normalizeRunSections(args);
+            if (route.name !== 'home') await router.push('/');
+            const settled = await Promise.allSettled(requested.map(async (id) => {
+                const { command, payload } = RUNNABLE_SECTION_COMMANDS[id];
+                await waitForAppCommand(command, { timeoutMs: RUN_TEST_TIMEOUT });
+                await dispatchAppCommand(command, payload, { timeoutMs: RUN_TEST_TIMEOUT });
+            }));
+            const ran = [];
+            const failed = [];
+            settled.forEach((result, i) => {
+                if (result.status === 'fulfilled') {
+                    ran.push(requested[i]);
+                } else {
+                    const code = result.reason?.code;
+                    const reason = code === 'timeout' || code === 'unavailable' ? code : 'error';
+                    failed.push({ id: requested[i], reason });
+                }
+            });
+            const output = { ...buildResultsSnapshot(), ran, failed };
+            if (unknown.length) output.unknownSections = unknown;
+            return {
+                output,
+                summary: { icon: 'play', text: t('nav.DocsToolRunSummary') },
             };
         },
     };
@@ -170,7 +250,7 @@ export function useDocsAssistant() {
                 actions: [
                     { icon: 'book', label: t('nav.OpenDocs'), onClick: openDocsSite },
                 ],
-                tools: [readResultsTool],
+                tools: [readResultsTool, runTestsTool],
             });
             window.GitBook('open');
             markIntent();
diff --git a/frontend/locales/en.json b/frontend/locales/en.json
index 5aa1ebc0a..a50309e8f 100644
--- a/frontend/locales/en.json
+++ b/frontend/locales/en.json
@@ -206,6 +206,8 @@
     "SearchDocs": "Search docs…",
     "DocsToolConfirm": "Share your current test results?",
     "DocsToolSummary": "Read your on-page results",
+    "DocsToolRunConfirm": "Run tests on your page?",
+    "DocsToolRunSummary": "Ran your network tests",
     "AskIPilot": "Ask IPilot",
     "OpenDocs": "Open docs",
     "DocsGreetingTitle": "How can I help?",
diff --git a/frontend/locales/fr.json b/frontend/locales/fr.json
index 810b54ec4..0c8ed1208 100644
--- a/frontend/locales/fr.json
+++ b/frontend/locales/fr.json
@@ -206,6 +206,8 @@
     "SearchDocs": "Rechercher dans la doc…",
     "DocsToolConfirm": "Partager vos résultats actuels ?",
     "DocsToolSummary": "Résultats de la page lus",
+    "DocsToolRunConfirm": "Lancer les tests sur votre page ?",
+    "DocsToolRunSummary": "Tests réseau exécutés",
     "AskIPilot": "Demander à IPilot",
     "OpenDocs": "Ouvrir la doc",
     "DocsGreetingTitle": "Comment puis-je vous aider ?",
diff --git a/frontend/locales/ru.json b/frontend/locales/ru.json
index cf0f026e7..425eb2576 100644
--- a/frontend/locales/ru.json
+++ b/frontend/locales/ru.json
@@ -206,6 +206,8 @@
     "SearchDocs": "Поиск по документации…",
     "DocsToolConfirm": "Показать ваши текущие результаты?",
     "DocsToolSummary": "Результаты со страницы прочитаны",
+    "DocsToolRunConfirm": "Запустить тесты на вашей странице?",
+    "DocsToolRunSummary": "Сетевые тесты выполнены",
     "AskIPilot": "Спросить IPilot",
     "OpenDocs": "Открыть документацию",
     "DocsGreetingTitle": "Чем могу помочь?",
diff --git a/frontend/locales/zh.json b/frontend/locales/zh.json
index bae3b3525..ea2ec58e2 100644
--- a/frontend/locales/zh.json
+++ b/frontend/locales/zh.json
@@ -206,6 +206,8 @@
     "SearchDocs": "搜索文档…",
     "DocsToolConfirm": "把当前的检测结果给助手看？",
     "DocsToolSummary": "已读取页面上的检测结果",
+    "DocsToolRunConfirm": "在你的页面上运行检测？",
+    "DocsToolRunSummary": "已运行你的网络检测",
     "AskIPilot": "询问 IPilot",
     "OpenDocs": "打开文档",
     "DocsGreetingTitle": "有什么可以帮你？",
diff --git a/frontend/utils/docs-run-tests.js b/frontend/utils/docs-run-tests.js
new file mode 100644
index 000000000..81eeb14e5
--- /dev/null
+++ b/frontend/utils/docs-run-tests.js
@@ -0,0 +1,36 @@
+// Pure support for the docs assistant's `run_my_tests` tool: which report
+// sections can be (re)run through the app command bus, the command + payload
+// each one maps to, and defensive normalization of the tool-call arguments.
+// GitBook's argument passing is unverified, so anything missing or malformed
+// is treated as "run everything".
+
+// Section id → its owner's command and payload. Refresh-flavored payloads on
+// purpose: these runs re-trigger tests that already ran once at boot.
+export const RUNNABLE_SECTION_COMMANDS = {
+    ipinfo: { command: 'ipinfo:refresh', payload: {} },
+    connectivity: { command: 'connectivity:run', payload: { trigger: 'manual' } },
+    webrtc: { command: 'webrtc:run', payload: { isRefresh: true } },
+    dnsleak: { command: 'dnsleak:run', payload: { isRefresh: true } },
+};
+
+export const RUNNABLE_SECTION_IDS = Object.keys(RUNNABLE_SECTION_COMMANDS);
+
+// `args?.sections` → { requested, unknown }, both deduped. A missing,
+// malformed, or empty list means "run all"; a non-empty list that names only
+// unknown ids runs nothing — the assistant asked for something specific and
+// gets the mismatch reported back instead of a full run it didn't ask for.
+export const normalizeRunSections = (args) => {
+    const sections = Array.isArray(args?.sections) ? args.sections : [];
+    if (!sections.length) return { requested: [...RUNNABLE_SECTION_IDS], unknown: [] };
+    const requested = [];
+    const unknown = [];
+    for (const entry of sections) {
+        if (RUNNABLE_SECTION_IDS.includes(entry)) {
+            if (!requested.includes(entry)) requested.push(entry);
+        } else {
+            const label = String(entry);
+            if (!unknown.includes(label)) unknown.push(label);
+        }
+    }
+    return { requested, unknown };
+};
diff --git a/tests/docs-run-tests.test.js b/tests/docs-run-tests.test.js
new file mode 100644
index 000000000..bbbc48875
--- /dev/null
+++ b/tests/docs-run-tests.test.js
@@ -0,0 +1,66 @@
+// Tests for frontend/utils/docs-run-tests.js — the pure half of the docs
+// assistant's `run_my_tests` tool: the section → command-bus mapping and the
+// defensive normalization of GitBook's (unverified) tool-call arguments.
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import {
+    RUNNABLE_SECTION_COMMANDS,
+    RUNNABLE_SECTION_IDS,
+    normalizeRunSections,
+} from '../frontend/utils/docs-run-tests.js';
+
+describe('runnable section commands', () => {
+    it('covers exactly the four core tests', () => {
+        assert.deepEqual(RUNNABLE_SECTION_IDS, ['ipinfo', 'connectivity', 'webrtc', 'dnsleak']);
+    });
+
+    it('maps each section to its owner command and payload', () => {
+        assert.deepEqual(RUNNABLE_SECTION_COMMANDS.ipinfo, { command: 'ipinfo:refresh', payload: {} });
+        assert.deepEqual(RUNNABLE_SECTION_COMMANDS.connectivity, { command: 'connectivity:run', payload: { trigger: 'manual' } });
+        assert.deepEqual(RUNNABLE_SECTION_COMMANDS.webrtc, { command: 'webrtc:run', payload: { isRefresh: true } });
+        assert.deepEqual(RUNNABLE_SECTION_COMMANDS.dnsleak, { command: 'dnsleak:run', payload: { isRefresh: true } });
+    });
+});
+
+describe('normalizeRunSections', () => {
+    it('runs all four when args are omitted entirely', () => {
+        assert.deepEqual(normalizeRunSections(undefined), { requested: RUNNABLE_SECTION_IDS, unknown: [] });
+    });
+
+    it('runs all four on an empty or missing sections list', () => {
+        assert.deepEqual(normalizeRunSections({}).requested, RUNNABLE_SECTION_IDS);
+        assert.deepEqual(normalizeRunSections({ sections: [] }).requested, RUNNABLE_SECTION_IDS);
+    });
+
+    it('runs all four when sections is malformed (not an array)', () => {
+        assert.deepEqual(normalizeRunSections({ sections: 'webrtc' }).requested, RUNNABLE_SECTION_IDS);
+        assert.deepEqual(normalizeRunSections({ sections: { 0: 'webrtc' } }).requested, RUNNABLE_SECTION_IDS);
+        assert.deepEqual(normalizeRunSections(null).requested, RUNNABLE_SECTION_IDS);
+    });
+
+    it('keeps a valid subset in request order, deduped', () => {
+        const { requested, unknown } = normalizeRunSections({ sections: ['dnsleak', 'ipinfo', 'dnsleak'] });
+        assert.deepEqual(requested, ['dnsleak', 'ipinfo']);
+        assert.deepEqual(unknown, []);
+    });
+
+    it('splits unknown ids out instead of failing, keeping the valid ones', () => {
+        const { requested, unknown } = normalizeRunSections({ sections: ['webrtc', 'speedtest', 'speedtest', 42] });
+        assert.deepEqual(requested, ['webrtc']);
+        assert.deepEqual(unknown, ['speedtest', '42']);
+    });
+
+    it('runs nothing when a non-empty list names only unknown ids', () => {
+        const { requested, unknown } = normalizeRunSections({ sections: ['speedtest', 'mtrtest'] });
+        assert.deepEqual(requested, []);
+        assert.deepEqual(unknown, ['speedtest', 'mtrtest']);
+    });
+
+    it('returns a fresh array — mutating requested never leaks into the id list', () => {
+        const { requested } = normalizeRunSections({ sections: [] });
+        requested.pop();
+        assert.equal(RUNNABLE_SECTION_IDS.length, 4);
+    });
+});

From f0aa85588d31433815592c7802538e6d5aa99577 Mon Sep 17 00:00:00 2001
From: jason5ng32 <jason5ng32@gmail.com>
Date: Sat, 22 Aug 2026 13:33:27 +0800
Subject: [PATCH 03/11] Refactor(ui): turn InfoBanner into a data-driven
 per-section promo slot
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every homepage section ends with one fixed slot; frontend/data/banners/
<section>.js (gitignored — deploy-time data, placing a file IS the decision
to show it) decides what renders. Data contract in utils/banners.js: inline
four-language copy, url+utm or internal to target, requireSettled /
transition / sweep switches, BannerClick_<section> analytics. The Enhanced
DNS Leak promo moves from hardcoded component copy into the mechanism, so
its locale keys retire.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .gitignore                                 |   3 +
 frontend/components/Advanced.vue           |   4 +
 frontend/components/ConnectivityTest.vue   |   6 +
 frontend/components/DnsLeaksTest.vue       |  25 +---
 frontend/components/IpInfos.vue            |   7 +
 frontend/components/SpeedTest.vue          |   8 +-
 frontend/components/WebRtcTest.vue         |   7 +
 frontend/components/widgets/InfoBanner.vue |  89 +++++++++----
 frontend/locales/en.json                   |   7 +-
 frontend/locales/fr.json                   |   7 +-
 frontend/locales/ru.json                   |   7 +-
 frontend/locales/zh.json                   |   7 +-
 frontend/utils/banners.js                  |  70 ++++++++++
 tests/banners.test.js                      | 147 +++++++++++++++++++++
 14 files changed, 326 insertions(+), 68 deletions(-)
 create mode 100644 frontend/utils/banners.js
 create mode 100644 tests/banners.test.js

diff --git a/.gitignore b/.gitignore
index a3b6e7f3b..ac350ec7e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -57,6 +57,9 @@ docs/
 # Local Scripts
 scripts/
 
+# Section banners — deploy-time data (ads and campaign promos stay out of git)
+frontend/data/banners/*
+
 # Site configuration
 public/sitemap.xml
 public/robots.txt
diff --git a/frontend/components/Advanced.vue b/frontend/components/Advanced.vue
index e2cd5372b..54ba176a9 100644
--- a/frontend/components/Advanced.vue
+++ b/frontend/components/Advanced.vue
@@ -83,6 +83,9 @@
                 </div>
             </DrawerContent>
         </Drawer>
+
+        <!-- Section banner slot (data-driven; see InfoBanner.vue) -->
+        <InfoBanner section="advanced" />
     </section>
 </template>
 
@@ -97,6 +100,7 @@ import { isRunningAsPwa } from '@/utils/pwa.js';
 import { Drawer, DrawerContent, DrawerClose } from '@/components/ui/drawer';
 import { Card, CardContent } from '@/components/ui/card';
 import { ToolLoadingSkeleton } from '@/components/ui/tool-loading-skeleton';
+import InfoBanner from '@/components/widgets/InfoBanner.vue';
 import { Maximize, Minimize, PanelBottomOpen, SquareArrowOutUpRight } from '@lucide/vue';
 
 const { t } = useI18n();
diff --git a/frontend/components/ConnectivityTest.vue b/frontend/components/ConnectivityTest.vue
index 35a591ba9..38328a06c 100644
--- a/frontend/components/ConnectivityTest.vue
+++ b/frontend/components/ConnectivityTest.vue
@@ -107,6 +107,8 @@
     <!-- Add / import dialog (custom form + curated list browser) -->
     <ConnectivityAddDialog v-model:open="addDialogOpen" />
 
+    <!-- Section banner slot (data-driven; see InfoBanner.vue) -->
+    <InfoBanner section="connectivity" :settled="hasEverSettled" />
   </section>
 </template>
 
@@ -124,6 +126,7 @@ import { JnTooltip } from '@/components/ui/tooltip';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent } from '@/components/ui/card';
 import ConnectivityAddDialog from '@/components/widgets/ConnectivityAddDialog.vue';
+import InfoBanner from '@/components/widgets/InfoBanner.vue';
 import { useStatusTone, ipFieldTone } from '@/composables/use-status-tone.js';
 import {
   Play, Frown, Meh, Plus, RotateCw, Smile, X,
@@ -141,6 +144,8 @@ const alertMessage = ref("");
 const multipleTests = ref(userPreferences.value.connectivityMultipleTests);
 const autoShowAltert = ref(userPreferences.value.popupConnectivityNotifications);
 const isStarted = ref(false);
+// Sticky settled flag for the section's banner slot: true once a pass settles.
+const hasEverSettled = ref(false);
 const counter = ref(0);
 const maxCounts = ref(9);
 const manualRun = ref(false);
@@ -375,6 +380,7 @@ const checkAllConnectivity = (isAlertToShow, isRefresh, isManualRun) => {
       );
       const allOk = finished.every((test) => test.statusCode === CONNECTIVITY_STATUS.OK);
       updateConnectivityAlert(allOk ? 'success' : 'error');
+      hasEverSettled.value = true;
       // Domain event: deliberately the whole grid, not just this pass —
       // the report is a latest-wins snapshot, and a mid-pass addition with
       // a real result is accurate information there.
diff --git a/frontend/components/DnsLeaksTest.vue b/frontend/components/DnsLeaksTest.vue
index 5a50ba106..cf026be13 100644
--- a/frontend/components/DnsLeaksTest.vue
+++ b/frontend/components/DnsLeaksTest.vue
@@ -83,18 +83,15 @@
       </Card>
     </div>
 
-    <!-- Enhanced DNS leak test banner — surfaces the deeper tool once the
-         homepage test has resolved (success or timeout). -->
-    <InfoBanner :show="showEnhancedBanner" :icon="Sparkles" :title="t('dnsleaktest.EnhancedBanner.Title')"
-      :note="t('dnsleaktest.EnhancedBanner.Note')" :cta="t('dnsleaktest.EnhancedBanner.CTA')"
-      @action="openEnhancedTest" />
+    <!-- Section banner slot (data-driven; see InfoBanner.vue); settled once
+         the homepage test has resolved (success or timeout). -->
+    <InfoBanner section="dnsleak" :settled="hasEverSettled" />
   </section>
 </template>
 
 
 <script setup>
 import { ref, computed, onMounted, reactive } from 'vue';
-import { useRouter } from 'vue-router';
 import { useMainStore } from '@/store';
 import { useI18n } from 'vue-i18n';
 import { trackEvent } from '@/utils/analytics';
@@ -106,7 +103,7 @@ import { Card, CardContent } from '@/components/ui/card';
 import { useStatusTone, ipFieldTone, isFieldPending as isFieldPendingShared } from '@/composables/use-status-tone.js';
 import { createMaskGate } from '@/composables/use-info-mask.js';
 import { useMaxmind } from '@/composables/use-maxmind.js';
-import { EthernetPort, Play, MapPin, RotateCw, Sparkles, DoorOpen } from '@lucide/vue';
+import { EthernetPort, Play, MapPin, RotateCw, DoorOpen } from '@lucide/vue';
 import { Icon } from '@iconify/vue';
 import FitText from '@/components/widgets/FitText.vue';
 import InfoBanner from '@/components/widgets/InfoBanner.vue';
@@ -123,27 +120,15 @@ const PROVIDERS = [ipApi, surfshark, ipleak, fastly];
 
 const { t } = useI18n();
 const store = useMainStore();
-const router = useRouter();
 const { lookupMaxmind } = useMaxmind();
 // Skip the info-mask blur on waiting/error placeholders (not a real IP).
 const maskAttr = createMaskGate(t);
 const isStarted = ref(false);
 const userPreferences = computed(() => store.userPreferences);
 const isSimpleMode = computed(() => userPreferences.value.simpleMode);
-// Sticky flag for the Enhanced DNS Leak Test banner.
+// Sticky settled flag for the section's banner slot.
 const hasEverSettled = ref(false);
 
-// Also gated on configs.originalSite to match the Advanced.vue card gate.
-const showEnhancedBanner = computed(() =>
-  hasEverSettled.value && store.configs?.originalSite === true
-);
-
-const openEnhancedTest = () => {
-  trackEvent('Section', 'BannerClick', 'EnhancedDnsLeakTest');
-  // Open the in-depth DNS Leak Test's in-page drawer (tools are query-driven now).
-  router.push({ path: '/', query: { tool: 'enhanceddnsleaktest' } });
-};
-
 const { dotClass, textClass } = useStatusTone();
 
 // Business status → 4 tone levels
diff --git a/frontend/components/IpInfos.vue b/frontend/components/IpInfos.vue
index e07c92b6a..18943d19d 100644
--- a/frontend/components/IpInfos.vue
+++ b/frontend/components/IpInfos.vue
@@ -23,6 +23,9 @@
       </div>
     </div>
 
+    <!-- Section banner slot — renders nothing unless a data file for this
+        section exists (see InfoBanner.vue). -->
+    <InfoBanner section="ipinfo" :settled="cardsHaveSettled" />
   </section>
 </template>
 
@@ -39,6 +42,7 @@ import { emitAppEvent, waitForAppEvent } from '@/utils/app-events';
 import { useAppCommand } from '@/composables/use-app-command.js';
 import { authenticatedFetch, fetchErrorLabel } from '@/utils/authenticated-fetch';
 import IPCard from './ip-infos/IPCard.vue';
+import InfoBanner from './widgets/InfoBanner.vue';
 
 
 const { t } = useI18n();
@@ -124,6 +128,8 @@ const IPArray = ref([]);
 const ipGeoSource = ref(userPreferences.value.ipGeoSource);
 const usingSource = ref(userPreferences.value.ipGeoSource);
 const fetchStatus = reactive([]);
+// Timing gate for the sponsor slot: flips once every visible card settled.
+const cardsHaveSettled = ref(false);
 
 // Middleware
 let pendingIPDetailsRequests = new Map();
@@ -234,6 +240,7 @@ const trackFetchStatus = (status) => {
     }
   }
   if (allHasFetched) {
+    cardsHaveSettled.value = true;
     store.setLoadingStatus('IPInfo', true);
     // Domain event: full snapshot of the visible cards, re-emitted whenever a
     // card settles after this point (single-card refresh included). The report
diff --git a/frontend/components/SpeedTest.vue b/frontend/components/SpeedTest.vue
index adb953985..d17b413e7 100644
--- a/frontend/components/SpeedTest.vue
+++ b/frontend/components/SpeedTest.vue
@@ -166,11 +166,13 @@
       </CardContent>
     </Card>
 
+    <!-- Section banner slot (data-driven; see InfoBanner.vue) -->
+    <InfoBanner section="speedtest" :settled="hasEverSettled" />
   </section>
 </template>
 
 <script setup>
-import { reactive, computed, onMounted, markRaw, onUnmounted } from 'vue';
+import { reactive, ref, computed, onMounted, markRaw, onUnmounted } from 'vue';
 import { useMainStore } from '@/store';
 import { useI18n } from 'vue-i18n';
 import { trackEvent } from '@/utils/analytics';
@@ -187,6 +189,7 @@ import { Button } from '@/components/ui/button';
 import { Card, CardContent } from '@/components/ui/card';
 import { Progress } from '@/components/ui/progress';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
+import InfoBanner from '@/components/widgets/InfoBanner.vue';
 import {
   ArrowLeftRight, CalendarCheck2, CircleAlert, Play, CloudDownload, CloudUpload,
   Globe, Pause, PersonStanding, RotateCw,
@@ -198,6 +201,8 @@ const store = useMainStore();
 const lang = computed(() => store.lang);
 const userPreferences = computed(() => store.userPreferences);
 const isSimpleMode = computed(() => userPreferences.value.simpleMode);
+// Sticky settled flag for the section's banner slot: true once a run finishes.
+const hasEverSettled = ref(false);
 // State Management
 const state = reactive({
   speedTest: {
@@ -464,6 +469,7 @@ const setupTestEngine = async () => {
     // Achievement rules for speed thresholds live in data/achievement-rules.js;
     // the report collector consumes the full result (unmeasured fields keep
     // their '-' placeholder — the builder drops non-numbers).
+    hasEverSettled.value = true;
     emitAppEvent('speedtest:finished', {
       downloadSpeed: state.speedTest.downloadSpeed,
       uploadSpeed: state.speedTest.uploadSpeed,
diff --git a/frontend/components/WebRtcTest.vue b/frontend/components/WebRtcTest.vue
index 714129411..a5ad6cb88 100644
--- a/frontend/components/WebRtcTest.vue
+++ b/frontend/components/WebRtcTest.vue
@@ -113,6 +113,8 @@
       </Card>
     </div>
 
+    <!-- Section banner slot (data-driven; see InfoBanner.vue) -->
+    <InfoBanner section="webrtc" :settled="hasEverSettled" />
   </section>
 </template>
 
@@ -134,6 +136,7 @@ import { Play, MapPin, EthernetPort, Flower, Network, RotateCw, FileText, Chevro
 import { Icon } from '@iconify/vue';
 import FitText from '@/components/widgets/FitText.vue';
 import CopyButton from '@/components/widgets/CopyButton.vue';
+import InfoBanner from '@/components/widgets/InfoBanner.vue';
 import { INLINE_TIERS } from '@/composables/use-fit-text.js';
 
 const { t } = useI18n();
@@ -146,6 +149,9 @@ const { dotClass, textClass } = useStatusTone();
 const { lookupMaxmind } = useMaxmind();
 
 const isStarted = ref(false);
+// Sticky settled flag for the section's banner slot: true once a full STUN
+// pass finishes (including the WebRTC-unavailable path).
+const hasEverSettled = ref(false);
 const IPArray = ref([]);
 const stunServers = reactive([
   { id: 'google', url: 'stun.l.google.com:19302', ip: t('webrtc.StatusWait'), natType: t('webrtc.StatusWait'), country: t('webrtc.StatusWait'), country_code: '', org: t('webrtc.StatusWait'), sdpLog: [], sdpOpen: false },
@@ -384,6 +390,7 @@ const natTypeCodeOf = (candidate) => {
 // Domain event: snapshot of all STUN cards for the report collector (servers
 // still waiting carry no natTypeCode and are dropped by the builder).
 const emitWebrtcFinished = () => {
+  hasEverSettled.value = true;
   emitAppEvent('webrtc:finished', {
     servers: stunServers.map((server) => ({
       id: server.id,
diff --git a/frontend/components/widgets/InfoBanner.vue b/frontend/components/widgets/InfoBanner.vue
index d3a326932..22216f04a 100644
--- a/frontend/components/widgets/InfoBanner.vue
+++ b/frontend/components/widgets/InfoBanner.vue
@@ -1,24 +1,33 @@
-<!-- InfoBanner — fade-slide section banner that upsells an advanced tool
-     after a homepage test settles (DNS Leak → Enhanced DNS Leak Test) or
-     carries a sponsored placement. With `sweep`, it also announces itself with
-     a border light sweep whenever it scrolls into view.
-     Callers pass icon / copy / action, plus optional show / sweep. -->
+<!-- InfoBanner — the per-section info-banner slot. Every homepage section
+     permanently wires one of these at its bottom; what (if anything) shows is
+     decided purely by data: frontend/data/banners/<section>.js (contract in
+     utils/banners.js), one banner per section. The directory is deploy-time
+     data, never in git — placing a file there IS the decision to show that
+     banner on that deployment (self-promo of a built-in tool via `to`, or an
+     external advertiser via `url`); a missing file and a file
+     default-exporting null both mean the slot renders nothing. Timing is
+     data-driven: parents feed their section's completion into the `settled`
+     prop, and
+     a banner waits for it unless its data sets requireSettled: false. The
+     fade-slide appear/disappear can be turned off per banner with
+     transition: false; with `sweep: true`, the banner announces itself with a
+     border light sweep whenever it scrolls into view. -->
 <template>
-  <Transition name="fade-slide">
-    <div v-if="show" ref="root" :class="{ 'jn-banner-sweep': sweep && visible }"
+  <Transition :name="transitionName">
+    <div v-if="banner && shown" ref="root" :class="{ 'jn-banner-sweep': sweep && visible }"
       class="jn-banner mt-3 flex flex-col md:flex-row items-start gap-3 rounded-lg border border-info/30 bg-info/5 p-4 md:p-5">
       <div class="flex-1 min-w-0 space-y-1.5">
         <h3 class="text-sm font-semibold m-0 flex items-center gap-2 mb-2">
           <component :is="icon" class="size-4 text-info shrink-0" />
-          {{ title }}
+          {{ text.title }}
         </h3>
         <p class="text-sm text-muted-foreground leading-relaxed m-0">
-          {{ note }}
+          {{ text.note }}
         </p>
       </div>
       <div class="w-full md:w-auto md:self-stretch flex justify-end items-end md:items-center">
-        <Button variant="action" size="sm" @click="emit('action')" class="w-full md:w-auto shrink-0 cursor-pointer">
-          <span>{{ cta }}</span>
+        <Button variant="action" size="sm" @click="openBanner" class="w-full md:w-auto shrink-0 cursor-pointer">
+          <span>{{ text.cta }}</span>
           <ArrowRight class="size-4 ml-1" />
         </Button>
       </div>
@@ -27,23 +36,57 @@
 </template>
 
 <script setup>
-import { ref } from 'vue';
+import { computed, ref } from 'vue';
 import { useElementVisibility } from '@vueuse/core';
+import { useRouter } from 'vue-router';
+import { useMainStore } from '@/store';
 import { Button } from '@/components/ui/button';
-import { ArrowRight } from '@lucide/vue';
-
-defineProps({
-  show: { type: Boolean, default: true },
-  icon: { type: [Object, Function], required: true },
-  title: { type: String, required: true },
-  note: { type: String, required: true },
-  cta: { type: String, required: true },
-  sweep: { type: Boolean, default: false },
+import { ArrowRight, Globe, Megaphone, Server, Shield, Sparkles, Zap } from '@lucide/vue';
+import { trackEvent } from '@/utils/analytics';
+import { bannerCopy, bannerLink, pickBanner } from '@/utils/banners';
+
+const props = defineProps({
+  section: { type: String, required: true },
+  settled: { type: Boolean, default: true }, // parent's "section tests have completed a full pass" signal
 });
 
-const emit = defineEmits(['action']);
+// Data discovery — glob is resolved at build time; the slot's file is the one
+// named after the section, and null/absent both mean "render nothing".
+const modules = import.meta.glob('../../data/banners/*.js', { eager: true });
+const banner = pickBanner(modules, props.section);
+
+// Data files carry lucide icon NAMES so they stay pure (Node-loadable by the
+// data test); the component maps them onto imported components here.
+const ICONS = { Globe, Megaphone, Server, Shield, Sparkles, Zap };
+const icon = ICONS[banner?.icon] ?? Megaphone;
+const sweep = banner?.sweep === true; // opt-in per banner, default off
+// transition: false in the data swaps to a name with no CSS hooks, so the
+// Transition finds no transition/animation styles and inserts/removes the
+// element instantly — no fade-slide.
+const transitionName = banner?.transition === false ? 'jn-none' : 'fade-slide';
+
+const store = useMainStore();
+const router = useRouter();
+const lang = computed(() => store.lang);
+// requireSettled defaults to true — only an explicit false shows the banner
+// before the parent reports `settled`. Deployment placement is the only other
+// gate: whoever put the data file on this deployment wanted the banner shown.
+const shown = computed(() => banner?.requireSettled === false || props.settled);
+// Locale-reactive: the inline `copy` map resolves via the store language.
+const text = computed(() => bannerCopy(banner, lang.value));
+
+const openBanner = () => {
+  // Section in the event name (GA4 reports list event names out of the box;
+  // params would need registered custom dimensions), campaign id as label.
+  trackEvent('Section', `BannerClick_${props.section}`, banner.track);
+  if (banner.to) {
+    router.push(banner.to);
+  } else {
+    window.open(bannerLink(banner, lang.value), '_blank', 'noopener');
+  }
+};
 
-// `show` can flip while the banner is still below the fold, so entering the
+// `shown` can flip while the banner is still below the fold, so entering the
 // viewport — not mounting — is what triggers the sweep. Leaving and coming
 // back replays it. Nothing is observed until the element exists, so a banner
 // without `sweep` only pays for one idle observer.
diff --git a/frontend/locales/en.json b/frontend/locales/en.json
index a50309e8f..b668492b6 100644
--- a/frontend/locales/en.json
+++ b/frontend/locales/en.json
@@ -1271,12 +1271,7 @@
     "Note2": "The method to test for DNS leaks involves accessing a newly generated domain name to detect which regional DNS exit you are resolving through. If the endpoint region returned matches your local service provider's region, there is a risk of DNS leakage. In this case, you may need to modify your VPN/proxy settings.",
     "EndpointCountry": "Endpoint Region",
     "StatusWait": "Awaiting Test",
-    "StatusError": "Test Error",
-    "EnhancedBanner": {
-      "Title": "Want to dig deeper?",
-      "Note": "Want to see every recursive resolver you're actually using, their ASN, whether any of them forwards a prefix of your real IP upstream via ECS, and whether DNSSEC validation is in play, open the \"In-depth DNS Leak Test\" below.",
-      "CTA": "Open the in-depth test"
-    }
+    "StatusError": "Test Error"
   },
   "speedtest": {
     "Title": "Speed Test",
diff --git a/frontend/locales/fr.json b/frontend/locales/fr.json
index 0c8ed1208..a6d744ca6 100644
--- a/frontend/locales/fr.json
+++ b/frontend/locales/fr.json
@@ -1271,12 +1271,7 @@
     "Note2": "La méthode de test des fuites DNS consiste à accéder à un nom de domaine nouvellement généré pour détecter la région DNS de sortie à laquelle vous effectuez une résolution. Si la région de l'extrémité renvoyée correspond à la région de votre fournisseur de services local, il y a un risque de fuite DNS. Dans ce cas, vous devrez peut-être modifier vos paramètres VPN/proxy.",
     "EndpointCountry": "Région de l'extrémité",
     "StatusWait": "En attente du test",
-    "StatusError": "Erreur de test",
-    "EnhancedBanner": {
-      "Title": "Envie d'aller plus loin ?",
-      "Note": "Si vous voulez voir tous les résolveurs récursifs que vous utilisez réellement, leur ASN, si l'un d'entre eux transmet un préfixe de votre IP réelle en amont via ECS, et si la validation DNSSEC est en place, ouvrez le « Test de fuite DNS approfondi » ci-dessous.",
-      "CTA": "Ouvrir le test approfondi"
-    }
+    "StatusError": "Erreur de test"
   },
   "speedtest": {
     "Title": "Test de vitesse",
diff --git a/frontend/locales/ru.json b/frontend/locales/ru.json
index 425eb2576..1cb6dfbdc 100644
--- a/frontend/locales/ru.json
+++ b/frontend/locales/ru.json
@@ -1271,12 +1271,7 @@
     "Note2": "Для проверки утечки DNS выполняется обращение к недавно созданному доменному имени, чтобы определить регион выхода DNS. Если возвращённый регион совпадает с регионом вашего местного провайдера, возможна утечка DNS. В таком случае может потребоваться изменить настройки VPN или прокси.",
     "EndpointCountry": "Регион конечной точки",
     "StatusWait": "Ожидание теста",
-    "StatusError": "Ошибка теста",
-    "EnhancedBanner": {
-      "Title": "Нужна более глубокая проверка?",
-      "Note": "Чтобы увидеть все используемые рекурсивные резолверы, их ASN, передачу префикса реального IP через ECS и состояние проверки DNSSEC, откройте ниже «Углублённый тест утечки DNS».",
-      "CTA": "Открыть углублённый тест"
-    }
+    "StatusError": "Ошибка теста"
   },
   "speedtest": {
     "Title": "Тест скорости",
diff --git a/frontend/locales/zh.json b/frontend/locales/zh.json
index ea2ec58e2..0878a8c85 100644
--- a/frontend/locales/zh.json
+++ b/frontend/locales/zh.json
@@ -1271,12 +1271,7 @@
     "Note2": "泄露测试的方法是通过访问新生成的域名，检测你是通过哪个地区的 DNS 出口进行解析，如果返回的出口区域和你当地的运营商区域相同，则有 DNS 泄露风险，你可能需要修改 VPN/代理设置。",
     "EndpointCountry": "出口地区",
     "StatusWait": "待检测",
-    "StatusError": "测试出错",
-    "EnhancedBanner": {
-      "Title": "想做更深入的检查？",
-      "Note": "如果想进一步了解你正在使用的所有递归解析器是谁、它们的 ASN 归属、是否通过 ECS 把你真实 IP 的前缀转发给了上游、以及是否启用了 DNSSEC 校验，可以打开下方的「深度 DNS 泄露测试」。",
-      "CTA": "打开深度 DNS 泄露测试"
-    }
+    "StatusError": "测试出错"
   },
   "speedtest": {
     "Title": "网速测试",
diff --git a/frontend/utils/banners.js b/frontend/utils/banners.js
new file mode 100644
index 000000000..940bafb20
--- /dev/null
+++ b/frontend/utils/banners.js
@@ -0,0 +1,70 @@
+// Pure helpers for the per-section info-banner slot (components/widgets/
+// InfoBanner.vue). Every homepage section owns one fixed slot, served by
+// one data file: frontend/data/banners/<section>.js (e.g. ipinfo.js serves
+// <InfoBanner section="ipinfo" />). The file default-exports either `null`
+// (slot explicitly off) or ONE plain object — no imports, so the plain Node
+// test runner can load it:
+//
+//   {
+//     id: 'vps',                   // unique across all data files
+//     icon: 'Server',              // lucide icon NAME (string, no import);
+//                                  // dict in InfoBanner.vue: Globe, Megaphone,
+//                                  // Server, Shield, Sparkles, Zap —
+//                                  // unknown/absent falls back to Megaphone
+//     track: 'IPInfoVPS',          // campaign id — the label on the
+//                                  // BannerClick_<section> analytics event
+//     copy: { en: { title, note, cta }, zh: { … }, … },  // wording: en
+//                                  // required, other langs optional,
+//                                  // fallback is en
+//     // Click target — exactly ONE of:
+//     url: 'https://…',            // external: new tab, utm params appended
+//     utm: { source: '…', … },     // with `url` only; keys WITHOUT the utm_
+//                                  // prefix — bannerLink adds it, plus
+//                                  // utm_content=<lang>
+//     to: '/?tool=invisibilitytest', // internal: router.push target, no utm
+//     requireSettled: true,        // default true when absent: wait for the
+//                                  // section's own tests (the parent's
+//                                  // `settled` prop) before showing; set
+//                                  // false to show immediately
+//     transition: true,            // default true when absent: fade-slide
+//                                  // appear/disappear; set false for an
+//                                  // instant swap
+//     sweep: true,                 // optional: border light sweep on entering
+//                                  // the viewport; default false
+//   }
+//
+// Banner wording is data by design — the inline `copy` map is the ONLY
+// wording form, never locale-pack keys: banners are per-campaign deploy-time
+// data files, not product UI, and must ride along without touching locales/.
+
+// Banner wording for the active locale: the language block from the inline
+// `copy` map, falling back to English. Always returns a renderable object so
+// callers never branch on missing copy.
+export const bannerCopy = (banner, lang) => {
+    const copy = banner?.copy ?? {};
+    return copy[lang] ?? copy.en ?? { title: '', note: '', cta: '' };
+};
+
+// External landing URL with utm_* attribution: each `utm` key gains the utm_
+// prefix, and utm_content carries the visitor's locale so campaigns see which
+// language surface converted. Existing query params on `url` are preserved.
+export const bannerLink = (banner, lang) => {
+    const url = new URL(banner.url);
+    for (const [key, value] of Object.entries(banner.utm ?? {})) {
+        url.searchParams.set(`utm_${key}`, String(value));
+    }
+    url.searchParams.set('utm_content', lang);
+    return url.toString();
+};
+
+// The banner for a section from an import.meta.glob modules map
+// ({ path: module }): the file NAMED after the section is its slot —
+// data/banners/ipinfo.js serves section "ipinfo". A missing file and a file
+// default-exporting null/undefined both mean "no banner" (returns null).
+export const pickBanner = (modules, section) => {
+    for (const key of Object.keys(modules ?? {})) {
+        const name = key.split('/').pop().replace(/\.js$/, '');
+        if (name === section) return modules[key]?.default ?? null;
+    }
+    return null;
+};
diff --git a/tests/banners.test.js b/tests/banners.test.js
new file mode 100644
index 000000000..3819fb4ad
--- /dev/null
+++ b/tests/banners.test.js
@@ -0,0 +1,147 @@
+// Section-banner tests: unit-tests for the pure helpers in
+// frontend/utils/banners.js, plus a data-validation block over
+// frontend/data/banners/. The whole directory is deploy-time data (gitignored),
+// so the scan validates whatever files are present on this machine and passes
+// vacuously when the directory is empty or absent.
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { bannerCopy, bannerLink, pickBanner } from '../frontend/utils/banners.js';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const BANNERS_DIR = path.join(repoRoot, 'frontend', 'data', 'banners');
+
+// Inline fixtures matching the data-file contract documented in the util.
+const external = {
+    id: 'vps',
+    icon: 'Server',
+    url: 'https://sponsor.example.com/deal?ref=abc',
+    utm: { source: 'ipcheck.ing', medium: 'referral', campaign: 'ipinfo-vps' },
+    copy: {
+        en: { title: 'Fast VPS', note: 'A note.', cta: 'Get it' },
+        zh: { title: '高速 VPS', note: '一段说明。', cta: '立即获取' },
+    },
+    track: 'IPInfoVPS',
+};
+
+const internal = {
+    id: 'invisibility',
+    icon: 'Shield',
+    to: '/?tool=invisibilitytest',
+    copy: { en: { title: 'Go deeper', note: 'A note.', cta: 'Try it' } },
+    track: 'WebRTCInvisibility',
+};
+
+describe('bannerCopy', () => {
+    it('returns the inline copy for the active language', () => {
+        assert.deepEqual(bannerCopy(external, 'zh'), external.copy.zh);
+    });
+
+    it('falls back to English for an uncovered language', () => {
+        assert.deepEqual(bannerCopy(external, 'fr'), external.copy.en);
+    });
+
+    it('stays renderable with no banner or no copy at all', () => {
+        for (const value of [null, undefined, {}]) {
+            assert.deepEqual(bannerCopy(value, 'en'), { title: '', note: '', cta: '' });
+        }
+    });
+});
+
+describe('bannerLink', () => {
+    it('appends prefixed utm params and utm_content=lang, keeping existing query', () => {
+        const url = new URL(bannerLink(external, 'zh'));
+        assert.equal(url.origin + url.pathname, 'https://sponsor.example.com/deal');
+        assert.equal(url.searchParams.get('ref'), 'abc');
+        assert.equal(url.searchParams.get('utm_source'), 'ipcheck.ing');
+        assert.equal(url.searchParams.get('utm_medium'), 'referral');
+        assert.equal(url.searchParams.get('utm_campaign'), 'ipinfo-vps');
+        assert.equal(url.searchParams.get('utm_content'), 'zh');
+    });
+
+    it('works with an empty or missing utm object', () => {
+        const url = new URL(bannerLink({ url: 'https://x.example.com/' }, 'en'));
+        assert.equal(url.searchParams.get('utm_content'), 'en');
+        assert.equal([...url.searchParams.keys()].length, 1);
+    });
+});
+
+describe('pickBanner', () => {
+    // Shape mirrors an eager import.meta.glob result: { path: { default } }.
+    const modules = {
+        '../../data/banners/ipinfo.js': { default: external },
+        '../../data/banners/webrtc.js': { default: internal },
+        '../../data/banners/speedtest.js': { default: null }, // explicitly off
+    };
+
+    it('matches by filename: <section>.js serves section "<section>"', () => {
+        assert.equal(pickBanner(modules, 'ipinfo'), external);
+        assert.equal(pickBanner(modules, 'webrtc'), internal);
+    });
+
+    it('treats a null default export as absent', () => {
+        assert.equal(pickBanner(modules, 'speedtest'), null);
+        assert.equal(pickBanner({ './x.js': {} }, 'x'), null); // undefined default
+    });
+
+    it('returns null when nothing matches or the map is empty', () => {
+        assert.equal(pickBanner(modules, 'connectivity'), null);
+        assert.equal(pickBanner({}, 'ipinfo'), null);
+        assert.equal(pickBanner(undefined, 'ipinfo'), null);
+    });
+});
+
+describe('banner data files', () => {
+    // A missing directory would be an empty list, not a failure — null-export
+    // files likewise stay vacuously valid.
+    const listBannerFiles = async () => {
+        try {
+            return (await readdir(BANNERS_DIR)).filter((f) => f.endsWith('.js'));
+        } catch (err) {
+            if (err.code === 'ENOENT') return [];
+            throw err;
+        }
+    };
+
+    it('every data file is pure, Node-loadable, and matches the contract', async () => {
+        const files = await listBannerFiles();
+        const ids = [];
+        for (const file of files) {
+            // Dynamic import doubles as the purity check: a data file that
+            // imported Vue or app code would fail to load under Node.
+            const mod = await import(pathToFileURL(path.join(BANNERS_DIR, file)).href);
+            const banner = mod.default;
+            if (banner === null) continue; // explicitly disabled slot — valid
+            assert.ok(banner && typeof banner === 'object', `${file}: default export must be an object or null`);
+            for (const field of ['id', 'icon', 'track']) {
+                assert.ok(typeof banner[field] === 'string' && banner[field].length > 0,
+                    `${file}: ${field} must be a non-empty string`);
+            }
+            // Click target: exactly one of external `url` / internal `to`.
+            const hasUrl = typeof banner.url === 'string';
+            const hasTo = typeof banner.to === 'string';
+            assert.ok(hasUrl !== hasTo, `${file}: exactly one of url | to`);
+            if (hasUrl) {
+                assert.doesNotThrow(() => new URL(banner.url), `${file}: url must parse`);
+            } else {
+                assert.ok(banner.utm === undefined, `${file}: utm only makes sense with url`);
+            }
+            // Wording is always the inline `copy` map: en required and
+            // complete, other languages optional (bannerCopy falls back).
+            for (const field of ['title', 'note', 'cta']) {
+                assert.ok(typeof banner.copy?.en?.[field] === 'string' && banner.copy.en[field].length > 0,
+                    `${file}: copy.en.${field} must be a non-empty string`);
+            }
+            for (const flag of ['requireSettled', 'transition', 'sweep']) {
+                if (banner[flag] !== undefined) {
+                    assert.equal(typeof banner[flag], 'boolean', `${file}: ${flag} must be a boolean`);
+                }
+            }
+            ids.push(banner.id);
+        }
+        assert.equal(new Set(ids).size, ids.length, 'banner ids must be unique');
+    });
+});

From f6ef42f98f39f527898a01cb414c504c015f57c2 Mon Sep 17 00:00:00 2001
From: jason5ng32 <jason5ng32@gmail.com>
Date: Sat, 22 Aug 2026 13:33:33 +0800
Subject: [PATCH 04/11] Docs(agents): slim frontend/AGENTS.md back to 150 lines

Drop what the file structure and header comments already say; keep rules,
deliberate exceptions, and traps. Documents the command bus alongside the
event bus.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 frontend/AGENTS.md | 265 +++++++++++++++++----------------------------
 1 file changed, 98 insertions(+), 167 deletions(-)

diff --git a/frontend/AGENTS.md b/frontend/AGENTS.md
index dfdb21e77..b0b9f8890 100644
--- a/frontend/AGENTS.md
+++ b/frontend/AGENTS.md
@@ -6,214 +6,145 @@ Conventions specific to the Vue 3 SPA under `frontend/`. Universal rules
 ## Overview
 
 Vue 3 `<script setup>` + Pinia + vue-router (HTML5 history) + Tailwind CSS v4
-over shadcn-vue primitives (copied in, not a package). No TypeScript, no
-`dark:` dual-pair utilities.
+over copied-in shadcn-vue primitives. No TypeScript, no `dark:` dual pairs.
 
 ## Layout
 
 ```
 frontend/
-├── App.vue          ← thin shell: global providers + <router-view>
-├── main.js          ← bootstrap + env-gated dynamic init (Sentry, Firebase)
-├── store.js         ← Pinia main store
-├── firebase-init.js ← env-gated lazy Firebase Auth; boot path picked by the
-│                      utils/auth-hint.js flag (signed-in → gate mount on
-│                      auth; visitor → SDK never loads until sign-in)
-├── sentry-init.js   ← env-gated Sentry (see "Error monitoring" below)
-├── router/          ← `/` Home · `/tools/:slug` StandaloneTool · `/privacy`
-│                      · `/r/:id` shared report (noindex)
-│                      (advanced tools also open in-page via `?tool=<slug>`)
-├── locales/         ← en / zh / fr / ru + on-demand sub-packs
-├── style/style.css  ← Tailwind v4 entry + design tokens
-├── lib/             ← cn() only (shadcn support layer)
-├── data/            ← static config: achievements + achievement-rules /
-│                      ip-databases / sections / changelog / tools registry
-│                      (router + cards + drawer all derive from it) /
-│                      pulse-statuses (Earth Online vocabulary: presets +
-│                      date-windowed festival statuses + their celebration
-│                      effect mapping; recipes in utils/pulse-celebration.js)/
-│                      connectivity-import-lists (default target set +
-│                      curated import sets + the shared cap; icons are
-│                      committed 64px PNGs under public/favicons/ — one per
-│                      member, enforced by its data test)
-├── utils/           ← framework-agnostic helpers + IO
-│                      (app-events bus / getips/ / valid-ip / analytics / …)
-├── composables/     ← Vue-aware `useXxx` logic
-└── components/      ← Home / StandaloneTool / top-level sections, plus
-                       ip-infos/ · advanced-tools/ · report/ · widgets/ ·
-                       svgicons/ · ui/
+├── App.vue / main.js / store.js / router/ / locales/ / style/style.css
+├── firebase-init.js ← env-gated lazy Firebase Auth (boot path: utils/auth-hint.js)
+├── sentry-init.js   ← env-gated Sentry (see "Error monitoring")
+├── data/            ← static config (tools registry drives router+cards+drawer)
+├── lib/ · utils/ · composables/  ← see "Helper placement"
+└── components/      ← sections + ip-infos/ advanced-tools/ report/ widgets/ svgicons/ ui/
 ```
 
-Directory-level only — every file opens with a header comment stating its
-purpose; read those for specifics.
+Every file opens with a header comment stating its purpose — read those.
 
 ## Conventions
 
-- **Composition API.** `<script setup>` everywhere; no Options API.
-- **Path alias.** `@` → `frontend/`.
-- **Shared-with-backend helpers live in `common/`**, re-exported through a
-  thin bridge in `utils/` so consumers keep `@/utils/...` imports (pattern:
-  `utils/valid-ip.js`, `utils/fetch-with-timeout.js`).
-- **Helper placement:** needs Vue reactivity / lifecycle → `composables/`
-  (`useXxx`); otherwise → `utils/` (never `use-` prefixed). `lib/` stays
-  shadcn-only. A pure function living next to a composable is exported from
-  that composable's file, not promoted to its own.
+- **Composition API** everywhere; no Options API. Alias `@` → `frontend/`.
+- **Shared-with-backend helpers live in `common/`**, re-exported through a thin
+  `utils/` bridge so consumers keep `@/utils/...` imports (`utils/valid-ip.js`).
+- **Helper placement:** Vue reactivity / lifecycle → `composables/` (`useXxx`);
+  otherwise `utils/` (never `use-` prefixed). `lib/` stays shadcn-only. A pure
+  function next to a composable exports from that composable's file.
 
 ### Achievements are event-driven
 
-Components never touch the achievement system. They emit domain events
-unconditionally — `emitAppEvent('speedtest:finished', {…})` on the
-`utils/app-events.js` bus — and the pipeline downstream handles the rest:
-`data/achievement-rules.js` maps events to achievement slugs (single place to
-look for "what unlocks X"); `composables/use-achievement-engine.js` (init'd
-once in App.vue) owns the signed-in / remote-sync / already-achieved / rate
-guards (rules never evaluate until the remote achievements snapshot lands —
-`store.userAchievementsSynced`; pre-sync hits are parked and re-checked).
-New achievement = entry in `data/achievements.js` + rule + (only if no
-suitable event exists) a new domain event. Tests:
-`tests/achievement-rules.test.js`, `tests/composable-achievement-engine.test.js`.
-
-The shareable diagnostic report rides the same bus: every "my network" test
-emits `<domain>:finished` with its full structured result;
-`composables/use-report-collector.js` (init'd once in App.vue) normalizes
-payloads through `utils/report-builders.js` into sections whitelisted by
-`common/report-schema.js`, and `components/report/` consumes the snapshots
-(share dialog + read-only /r/:id page). New reportable test = emit event +
-builder + schema entry, in the same change. Changing a test's result
-semantics or an upstream field means updating that test's builder whitelist
-+ schema enum too — builders fail soft (unknown values silently drop the
-field) and test fixtures are frozen, so drift shows up as quietly missing
-report fields, not as errors.
-
-A report link is readable by anyone who has it, so the builder — not the
-renderer — is where anything the visitor supplied gets dropped. Persona
-Check is the sharpest case: its live results carry a `detail` per check
-(issuing bank, the country a shared position resolved to), and only the
-id / axis / verdict triple reaches the section. Invisibility follows the
-same rule with key + flag. Keep new sections on that side of the line.
+Components never touch the achievement system — they emit domain events
+unconditionally (`emitAppEvent('speedtest:finished', {…})` on `utils/app-events.js`);
+`data/achievement-rules.js` maps events → slugs, `composables/use-achievement-engine.js`
+owns all guards (rules wait for the remote snapshot; pre-sync hits parked).
+New achievement = entry + rule + (only if no suitable event exists) a new event.
+
+The shareable report rides the same bus: tests emit `<domain>:finished`;
+`composables/use-report-collector.js` normalizes via `utils/report-builders.js`
+into sections whitelisted by `common/report-schema.js`. New reportable test =
+event + builder + schema entry, same change; changing result semantics means
+updating builder whitelist + schema enum too — builders fail soft and fixtures
+are frozen, so drift shows up as quietly missing fields, not errors.
+
+A report link is readable by anyone, so the builder — not the renderer — drops
+anything the visitor supplied: Persona Check ships only id / axis / verdict
+(never the per-check `detail`); Invisibility likewise key + flag only.
+
+### Commands are the imperative twin of events
+
+`utils/app-commands.js`: events say "this happened" (any subscribers); a command
+says "do this" — exactly one owner, and `dispatchAppCommand` resolves when the
+work is done, with the owner's result. Owners register via
+`composables/use-app-command.js` (scope-bound, setup-time); payload = one plain
+JSON object whose shape the owner defines at its registration site. Handlers
+reject gated / invalid runs with `appCommandError(code, message)` and reserved
+codes `auth` / `quota` / `input` (the bus produces `unavailable` / `timeout`),
+so callers react programmatically. Cross-component triggers go through the bus —
+never template refs (refs stay for UI chrome). Future advanced tools register
+at setup (`?tool=` mount); callers `waitForAppCommand` + dispatch.
 
 ### Overlays take no keyboard shortcuts
 
-`utils/shortcut.js` runs one document-level keydown dispatcher over the map
-`composables/use-shortcuts.js` registers — every entry there is a home-page
-action, and the whole map is suspended while any overlay is open. The rule keys
-off the component's form, not its purpose: the `ui/` roots (`Dialog` / `Sheet` /
-`Drawer`) call `composables/use-overlay-shortcuts.js`, so anything built on them
-inherits it, and overlays nest. Esc and the native scrolling keys still work —
-reka-ui / vaul and the browser own those.
-
-`registerShortcuts()` replaces the map rather than appending, and Home clears it
-on unmount — shortcuts belong to the home route alone.
+One document-level dispatcher (`utils/shortcut.js`) over the map
+`composables/use-shortcuts.js` registers — all home-page actions, suspended
+while any overlay is open. The rule keys off form, not purpose: the `ui/`
+roots (`Dialog` / `Sheet` / `Drawer`) call `composables/use-overlay-shortcuts.js`,
+so anything built on them inherits it; overlays nest. Esc and native scrolling
+keys still work (reka-ui / vaul / the browser own those). `registerShortcuts()`
+replaces the map, and Home clears it on unmount — shortcuts are home-route only.
 
 ### Error monitoring (Sentry) is env-gated and invisible to app code
 
-`sentry-init.js` loads via a build-time-gated dynamic import: no
-`VITE_SENTRY_DSN_FRONTEND` → no Sentry code in the bundle at all (same
-philosophy as `firebase-init.js`). Two rules:
-
-- **Never import `@sentry/vue` in app code** — a static import would drag the
-  SDK back into the main bundle. All Sentry config lives in `sentry-init.js`.
-- **Explicit signals go through the app-events bus**, like achievements: the
-  component emits, `sentry-init.js` subscribes. One signal is captured:
-  `ip-source:exhausted` (an IP card's whole source chain failed). Cards
-  report only when the `ipinfo:finished` snapshot shows some card resolved a
-  valid IP of the same version — otherwise "our chain failed" is
-  indistinguishable from visitor-side conditions (no IPv6 / dead network),
-  which is routine noise.
-
-Capture surface: uncaught errors; `console.error` (fingerprinted on the first
-argument, so a call site that fails several ways names the failure there —
-`fetchErrorLabel` in `utils/authenticated-fetch.js` renders the HTTP status,
-keeping an edge-blocked 403 out of the same issue as a 5xx; individual
-`utils/getips/` source failures are `console.warn` — invisible to Sentry by
-design, the per-card exhaustion event above is the health signal);
-route-change traces;
-error-only Replay, page text deliberately unmasked (the visitor's on-screen
-network info IS the debugging context; typed input stays masked; disclosed
-in the privacy policy). Third-party script errors (Cloudflare's RUM beacon)
-are dropped via `denyUrls`.
-Backend 5xx is deliberately NOT captured frontend-side — the backend SDK
-reports its own failures. Envelopes ship through the first-party tunnel
-`/api/monitoring` (`api/sentry-tunnel.js`) to beat ad blockers; source maps
-upload at build, gated on `SENTRY_AUTH_TOKEN`.
-
-## UI system
+No `VITE_SENTRY_DSN_FRONTEND` → no Sentry code in the bundle at all
+(build-time-gated dynamic import, like `firebase-init.js`). Rules:
 
-**shadcn-vue first.** Check `components/ui/` (copied-in primitives), then
-https://www.shadcn-vue.com/docs/components for something to copy in;
-hand-rolled Tailwind only when neither fits. Four local notes: `Spinner`
-(lucide `Loader2` + `role="status"`) and `ToolLoadingSkeleton` (chunk-loading
-placeholder for lazy tools) are project-specific; `toggle` / `toggle-group`
-deliberately use the `primary` pair for the pressed state; and the `Dialog` /
-`Sheet` / `Drawer` roots suspend the keyboard shortcuts while open — keep all
-of these when syncing upstream.
+- **Never import `@sentry/vue` in app code** — a static import drags the SDK
+  into the main bundle. All config lives in `sentry-init.js`.
+- **Explicit signals go through the app-events bus**: component emits,
+  `sentry-init.js` subscribes. One signal: `ip-source:exhausted` (a card's whole
+  source chain failed) — emitted only when another card resolved a valid IP of
+  the same version; otherwise no-IPv6 / dead-network visitors = routine noise.
 
-### Design tokens
+Traps: `console.error` is captured, fingerprinted on the first argument — name
+the failure there; `utils/getips/` source failures stay `console.warn`,
+invisible by design. Replay leaves page text unmasked deliberately (on-screen
+network info IS the debugging context; typed input masked; in the privacy
+policy). Backend 5xx is NOT captured frontend-side. Envelopes ship through the
+first-party tunnel `/api/monitoring` to beat ad blockers.
 
-Top of `style/style.css`; four business-semantic colors on top of shadcn
-defaults, each with a paired `-foreground`:
+## UI system
 
-`--info` (waiting / in-progress) · `--success` (ok-fast) · `--warning`
-(ok-slow) · `--action` (the "run / trigger" brand color)
+**shadcn-vue first.** Check `components/ui/`, then the shadcn-vue docs for
+something to copy in; hand-rolled Tailwind only when neither fits. Keep when
+syncing upstream: `Spinner` + `ToolLoadingSkeleton` (project-specific),
+`toggle` / `toggle-group`'s deliberate `primary` pressed pair, and the
+overlay roots' shortcut suspension.
 
-Rule: semantic tokens only (`bg-info` / `bg-action` / `bg-muted` /
-`text-muted-foreground` / …). Never write `dark:` dual pairs — tokens theme
-themselves.
+### Design tokens
 
-Button adds `action` and `success` variants to the shadcn set; Badge adds
-`success` and has hover globally disabled (display element — wrap it for
-interactivity). FAB colors express semantics, never decoration: `action` =
-trigger, `default` = stateless panels, `success` = protective state active,
-`secondary` = dock controls; at most two accents visible at once.
+Top of `style/style.css`; four business-semantic colors with paired `-foreground`:
+`--info` (waiting) · `--success` (ok-fast) · `--warning` (ok-slow) · `--action`
+(run / trigger). Semantic tokens only; never `dark:` dual pairs — tokens theme
+themselves. Button adds `action` / `success` variants; Badge adds `success`,
+hover globally disabled (display element — wrap it for interactivity). FAB colors
+are semantic, never decorative: `action` = trigger, `default` = stateless panel,
+`success` = protective state active, `secondary` = dock; max two accents at once.
 
 ### Status tones
 
 Every "business state → color" mapping goes through
 `composables/use-status-tone.js` (`wait` / `ok-fast` / `ok-slow` / `fail`),
-normally via its `ipFieldTone()` helper. No hand-rolled state→color switches.
+normally via `ipFieldTone()` — no hand-rolled state→color switches.
 
 ### Canonical patterns
 
-Copy from the named exemplar instead of re-inventing:
+Copy the named exemplar instead of re-inventing:
 
-- **Trigger button** — `variant="action"` + `<Spinner v-if />` + `:disabled`
-  (QueryIP, MacChecker, Whois, …).
-- **Input + icon trigger** — flex row, compact icon Button (lucide `Search`),
-  no text label (QueryIP / Whois / DnsResolver).
-- **AutoFill-proof inputs** — every free-form Input carries all six:
+- **Trigger button** — `variant="action"` + `<Spinner v-if />` + `:disabled` (QueryIP, Whois).
+- **Input + icon trigger** — flex row, compact icon Button, no text label (QueryIP).
+- **AutoFill-proof inputs** — all six on every free-form Input:
   `autocomplete="off" autocorrect="off" autocapitalize="off"
-  spellcheck="false" data-1p-ignore data-lpignore="true"`, and placeholder
-  copy avoids "address / 地址 / adresse / adresi" — iOS QuickType keys on the
-  word itself even with autocomplete off.
-- **Status card** — `keyboard-shortcut-card jn-card` markers + hover-lift
-  transition (Connectivity / WebRTC / IPCard). `jn-card` = shadow / border /
-  keyboard outline; `keyboard-shortcut-card` = J/K navigation target.
+  spellcheck="false" data-1p-ignore data-lpignore="true"`; placeholder copy
+  avoids "address / 地址 / adresse / adresi" — iOS QuickType keys on the word.
+- **Status card** — `keyboard-shortcut-card jn-card` + hover lift (IPCard):
+  `jn-card` = shadow / border / outline; `keyboard-shortcut-card` = J/K target.
 - **Flag** — always `<Icon :icon="'circle-flags:' + code.toLowerCase()" />`.
 - **Dates & times** — every user-visible stamp renders through
-  `utils/time-utils.js` with the vue-i18n locale: `formatIsoDate` (date-only
-  ISO — changelog, OONI windows, IP-history day headers), `isoToDateTime`
-  (ISO instants — report generated / expiry / per-section stamps),
-  `unixToDateTime` (epoch ms — account & achievement dates),
-  `relativeTimeFromMinutes` / `relativeTimeSince` / `formatDuration` (Pulse).
-  No hand-rolled `toLocaleDateString` / `Intl.DateTimeFormat` in components;
-  a deliberate exception carries a comment saying why (ASNHistory's
-  fixed-width ISO columns, report-export's AI-facing ISO intro,
-  ServiceStatus's seconds-bearing refresh clock).
-- **Fit-to-width tokens** — IP / MAC strings render inside `<FitText>`
-  (`HERO_TIERS` hero rows, `INLINE_TIERS` compact rows; `:max-lines="2"` on
-  heroes). Never per-component length-threshold helpers (IPCard, QueryIP).
+  `utils/time-utils.js` with the vue-i18n locale; no hand-rolled
+  `toLocaleDateString` / `Intl.DateTimeFormat` — deliberate exceptions carry a
+  why-comment (ASNHistory ISO columns, report-export intro, ServiceStatus clock).
+- **Fit-to-width tokens** — IP / MAC strings render in `<FitText>` (`HERO_TIERS` /
+  `INLINE_TIERS`; `:max-lines="2"` on heroes); never length-threshold helpers.
 - **Tables vs lists** — real per-column header semantics → `<table>`;
   otherwise a bordered `<ul class="rounded-lg border bg-card divide-y">`.
 - **Dialog header** — the `<DialogHeader :icon :title />` primitive.
-- **Drawer vs Sheet** — the vaul-vue bottom Drawer is for the Advanced Tools
-  panel and full-bleed expansions of an inline visual (ASNConnectivity); side
-  panels use `Sheet`.
+- **Drawer vs Sheet** — vaul-vue bottom Drawer for the Advanced Tools panel
+  and full-bleed expansions of an inline visual; side panels use `Sheet`.
 - **Motion** — hover lift `transition-transform duration-300 ease-out
-  hover:-translate-y-1.5`; loading is `<Spinner />`, never pulse-dot clusters.
+  hover:-translate-y-1.5`; loading is `<Spinner />`, never pulse-dots.
 
 ## Testing
 
-Composables and utils are the target (`tests/composable-*.test.js` and
-friends). Vue rendering / browser APIs are out of scope for the Node runner.
-Visual changes can't be self-tested — say so and let the user verify in
-`pnpm dev`.
+Composables and utils are the target (`tests/composable-*.test.js`). Vue
+rendering / browser APIs are out of scope for the Node runner. Visual changes
+can't be self-tested — say so and let the user verify in `pnpm dev`.

From 1e6608fd1873c21f5f7539aac2e30dfb35c91ec7 Mon Sep 17 00:00:00 2001
From: jason5ng32 <jason5ng32@gmail.com>
Date: Sat, 22 Aug 2026 13:33:33 +0800
Subject: [PATCH 05/11] Chore(changelog): v7.5.0 beta notes

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 frontend/data/changelog.json | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/frontend/data/changelog.json b/frontend/data/changelog.json
index b7a78f58e..5334b7965 100644
--- a/frontend/data/changelog.json
+++ b/frontend/data/changelog.json
@@ -1654,5 +1654,38 @@
         }
       }
     ]
+  },
+  {
+    "version": "v7.5.0",
+    "date": "Beta",
+    "content": [
+      {
+        "type": "add",
+        "change": {
+          "en": "Section promo slots: every fork can light up promo content under any homepage section as needed",
+          "zh": "Section 推广位：每个 Forker 可以根据需要，在不同的 Section 增加推广内容",
+          "fr": "Emplacements promotionnels par section : chaque fork peut afficher du contenu promotionnel sous n'importe quelle section de la page d'accueil",
+          "ru": "Промо-слоты в секциях: каждый форк может при необходимости добавлять промо-контент в разные секции главной страницы"
+        }
+      },
+      {
+        "type": "improve",
+        "change": {
+          "en": "IPilot can now run some of the tests for you",
+          "zh": "IPilot 现在可以帮使用者运行部分测试",
+          "fr": "IPilot peut désormais exécuter certains tests pour vous",
+          "ru": "IPilot теперь может запускать часть тестов за вас"
+        }
+      },
+      {
+        "type": "fix",
+        "change": {
+          "en": "Fixed some issues",
+          "zh": "修复了一些问题",
+          "fr": "Correction de divers problèmes",
+          "ru": "Исправлены некоторые проблемы"
+        }
+      }
+    ]
   }
 ]

From d325144f835db99230e933215462790b5afd911a Mon Sep 17 00:00:00 2001
From: jason5ng32 <jason5ng32@gmail.com>
Date: Sat, 22 Aug 2026 17:23:41 +0800
Subject: [PATCH 06/11] Feat(connectivity): ship the favicon fetcher and
 auto-heal missing icons

The fetch script was gitignored while the data test hard-required its
output, so outside contributors were blocked by a tool they couldn't
see. The script is now committed (pnpm fetch-favicons) and the data
test auto-downloads missing icons on local runs; CI stays offline and
keeps enforcing that PNGs are committed. Also adds a locale-coverage
check for list names.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .gitignore                                 |   6 +-
 frontend/data/connectivity-import-lists.js |   6 +-
 package.json                               |   3 +-
 scripts/fetch-favicons.js                  | 158 +++++++++++++++++++++
 tests/connectivity-import-lists.test.js    |  58 +++++++-
 5 files changed, 220 insertions(+), 11 deletions(-)
 create mode 100644 scripts/fetch-favicons.js

diff --git a/.gitignore b/.gitignore
index ac350ec7e..d19780a0f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -54,8 +54,10 @@ common/as-rel-db/*.next
 docs/
 .plan/
 
-# Local Scripts
-scripts/
+# Local Scripts (fetch-favicons.js is the one public exception —
+# contributors need it for the Connectivity favicon pipeline)
+scripts/*
+!scripts/fetch-favicons.js
 
 # Section banners — deploy-time data (ads and campaign promos stay out of git)
 frontend/data/banners/*
diff --git a/frontend/data/connectivity-import-lists.js b/frontend/data/connectivity-import-lists.js
index 350eb3b8d..77fabf968 100644
--- a/frontend/data/connectivity-import-lists.js
+++ b/frontend/data/connectivity-import-lists.js
@@ -29,8 +29,10 @@ export const DEFAULT_LIST_MEMBERS = [
     { id: 'wechat', name: 'WeChat', url: 'https://res.wx.qq.com/a/wx_fed/assets/res/NTI4MWU5.ico', iconDomain: 'weixin.qq.com' },
 ];
 
-// Favicon-fetch targets for scripts/fetch-favicons.js. `iconDomain` differs
-// from the test URL's host where that host serves a poor or missing icon.
+// Favicon-fetch targets for the committed scripts/fetch-favicons.js
+// (`pnpm fetch-favicons`; the data test also auto-invokes it when icons
+// are missing). `iconDomain` differs from the test URL's host where that
+// host serves a poor or missing icon.
 export const BUILTIN_FAVICONS = DEFAULT_LIST_MEMBERS.map((m) => ({
     id: m.id,
     iconDomain: m.iconDomain || new URL(m.url).hostname,
diff --git a/package.json b/package.json
index 11a733620..51a9fbf43 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,8 @@
     "start-backend": "node --import ./sentry-instrument.js backend-server.js",
     "start-frontend": "node frontend-server.js",
     "start": "concurrently \"node frontend-server.js\" \"node --import ./sentry-instrument.js backend-server.js\"",
-    "purge-index": "node scripts/purge-index-cache.js"
+    "purge-index": "node scripts/purge-index-cache.js",
+    "fetch-favicons": "node scripts/fetch-favicons.js"
   },
   "dependencies": {
     "@cloudflare/speedtest": "^1.13.0",
diff --git a/scripts/fetch-favicons.js b/scripts/fetch-favicons.js
new file mode 100644
index 000000000..bad64374b
--- /dev/null
+++ b/scripts/fetch-favicons.js
@@ -0,0 +1,158 @@
+// scripts/fetch-favicons.js — favicon fetcher for the Connectivity import
+// lists (frontend/data/connectivity-import-lists.js). Committed tooling with
+// two entry points: `pnpm fetch-favicons` runs the CLI, and
+// tests/connectivity-import-lists.test.js imports fetchFavicons() to
+// auto-download any icons missing locally. The PNGs it writes into
+// public/favicons/ are committed, so the steady state needs no network.
+// Tries the favicon services in order, accepts PNG payloads only, and
+// detects each service's "unknown domain" default image by byte-comparison
+// against a probe of a nonexistent domain — probed lazily, only once a
+// fetch is actually attempted, so importing the module costs no network.
+// Whatever still fails gets hand-sourced into public/favicons/<id>.png:
+// any 64px PNG source works (on macOS, sips/qlmanage convert ICO/SVG).
+//
+// Usage: node scripts/fetch-favicons.js [--only id1,id2] [--force]
+import { writeFile, mkdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { IMPORT_LISTS, BUILTIN_FAVICONS } from '../frontend/data/connectivity-import-lists.js';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const outDir = path.join(repoRoot, 'public', 'favicons');
+
+// Every icon the site needs: built-in targets + all import-list members.
+const buildTargets = () => [
+    ...BUILTIN_FAVICONS,
+    ...IMPORT_LISTS.flatMap((list) => list.members.map((m) => ({
+        id: m.id,
+        iconDomain: m.iconDomain || new URL(m.url).hostname,
+    }))),
+];
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+const isPng = (buf) => buf.length > 8 && buf.subarray(0, 4).equals(PNG_MAGIC);
+
+const fetchBuf = async (url) => {
+    const res = await fetch(url, { signal: AbortSignal.timeout(15000) });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
+};
+
+// Three tiers, PNG-only: s2 converts to PNG reliably; favicon.im passes the
+// site's original format through (accepted only when that happens to be
+// PNG); DDG serves PNGs for well-known domains. Non-PNG payloads (ICO/SVG)
+// are rejected — hand-convert those.
+const s2Url = (domain) => `https://www.google.com/s2/favicons?domain=${domain}&sz=64`;
+const faviconImUrl = (domain) => `https://favicon.im/${domain}?larger=true`;
+const ddgUrl = (domain) => `https://icons.duckduckgo.com/ip3/${domain}.ico`;
+
+// Domain that cannot exist — each service's response for it is its
+// "unknown" default image, recognizable afterwards by byte equality.
+const PROBE_DOMAIN = 'nonexistent-domain-probe-4c1d2e.invalid';
+
+// Fetch favicons for the given member ids (all targets when ids is null);
+// existing files are kept unless `force`. Returns { written, skipped,
+// failures } — failures carry { id, iconDomain, reason }.
+export const fetchFavicons = async ({ ids = null, force = false, log = console.log } = {}) => {
+    const only = new Set(ids || []);
+    const queue = buildTargets().filter((t) => !only.size || only.has(t.id));
+
+    await mkdir(outDir, { recursive: true });
+
+    // Per-service default-image probe, memoized and lazy: first attempted
+    // fetch per service triggers it, a fully-skipped run never touches
+    // the network.
+    const serviceDefaults = new Map();
+    const defaultFor = (toUrl) => {
+        if (!serviceDefaults.has(toUrl)) {
+            serviceDefaults.set(toUrl, fetchBuf(toUrl(PROBE_DOMAIN)).catch(() => null));
+        }
+        return serviceDefaults.get(toUrl);
+    };
+
+    const failures = [];
+    let written = 0;
+    let skipped = 0;
+
+    const fetchIcon = async ({ id, iconDomain }) => {
+        const outPath = path.join(outDir, `${id}.png`);
+        if (!force && existsSync(outPath)) {
+            // Keep manually curated replacements; --force refetches everything.
+            skipped += 1;
+            return;
+        }
+        try {
+            for (const toUrl of [s2Url, faviconImUrl, ddgUrl]) {
+                const [buf, defaultBuf] = await Promise.all([
+                    fetchBuf(toUrl(iconDomain)).catch(() => null),
+                    defaultFor(toUrl),
+                ]);
+                if (buf && isPng(buf) && !(defaultBuf && buf.equals(defaultBuf))) {
+                    await writeFile(outPath, buf);
+                    written += 1;
+                    return;
+                }
+            }
+            failures.push({ id, iconDomain, reason: 'no usable PNG from s2/favicon.im/ddg' });
+        } catch (err) {
+            failures.push({ id, iconDomain, reason: err.message });
+        }
+    };
+
+    // Small worker pool — polite to the icon services, still quick for ~140 ids.
+    const CONCURRENCY = 6;
+    let cursor = 0;
+    await Promise.all(Array.from({ length: CONCURRENCY }, async () => {
+        while (cursor < queue.length) {
+            const next = queue[cursor];
+            cursor += 1;
+            await fetchIcon(next);
+        }
+    }));
+
+    log(`favicons: ${written} written, ${skipped} kept, ${failures.length} failed (of ${queue.length})`);
+    for (const f of failures) log(`  MISSING ${f.id} (${f.iconDomain}): ${f.reason}`);
+    return { written, skipped, failures };
+};
+
+// CLI flow — only when executed directly, never on import.
+const runCli = async () => {
+    const { values: opts } = parseArgs({
+        options: {
+            only: { type: 'string', default: '' },
+            force: { type: 'boolean', default: false },
+        },
+    });
+
+    const ids = opts.only ? opts.only.split(',').map((s) => s.trim()) : null;
+    const { failures } = await fetchFavicons({ ids, force: opts.force });
+    if (failures.length) {
+        console.log('Hand-source the missing ones into public/favicons/<id>.png (64px PNG).');
+        process.exitCode = 1;
+    }
+
+    // Sanity: verify every list member now has an icon on disk.
+    const targets = buildTargets();
+    const missingOnDisk = targets.filter((t) => !existsSync(path.join(outDir, `${t.id}.png`)));
+    if (!failures.length && missingOnDisk.length) {
+        console.log(`On-disk check: ${missingOnDisk.map((t) => t.id).join(', ')} missing`);
+        process.exitCode = 1;
+    }
+
+    // Guard against accidentally committing oversized icons (s2 64px PNGs are
+    // a few KB each; anything huge means a service change worth eyeballing).
+    const big = [];
+    for (const t of targets) {
+        const p = path.join(outDir, `${t.id}.png`);
+        if (!existsSync(p)) continue;
+        const buf = await readFile(p);
+        if (buf.length > 30 * 1024) big.push(`${t.id} (${Math.round(buf.length / 1024)}KB)`);
+    }
+    if (big.length) console.log(`Large icons worth reviewing: ${big.join(', ')}`);
+};
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    await runCli();
+}
diff --git a/tests/connectivity-import-lists.test.js b/tests/connectivity-import-lists.test.js
index 38eef62cc..644c90b82 100644
--- a/tests/connectivity-import-lists.test.js
+++ b/tests/connectivity-import-lists.test.js
@@ -1,11 +1,16 @@
 // Data-integrity tests for the curated Connectivity import lists
 // (frontend/data/connectivity-import-lists.js): shape, uniqueness, size
-// floor, HTTPS-only URLs, and a committed favicon PNG for every member,
-// built-in target, and tile-preview reference.
+// floor, HTTPS-only URLs, locale coverage of list names, and a committed
+// favicon PNG for every member, built-in target, and tile-preview
+// reference. When icons are missing locally, a before() hook auto-fetches
+// them via scripts/fetch-favicons.js (skipped under CI, which stays
+// offline and deterministic — there the assertions just tell the
+// contributor to run `pnpm fetch-favicons` and commit the PNGs). With all
+// PNGs committed, the whole spec runs without touching the network.
 
 import assert from 'node:assert/strict';
-import { describe, it } from 'node:test';
-import { existsSync } from 'node:fs';
+import { describe, it, before } from 'node:test';
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
@@ -17,12 +22,37 @@ import {
     faviconPath,
     CONNECTIVITY_TARGET_LIMIT,
 } from '../frontend/data/connectivity-import-lists.js';
+import { fetchFavicons } from '../scripts/fetch-favicons.js';
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const faviconFile = (id) => path.join(repoRoot, 'public', 'favicons', `${id}.png`);
 const allMembers = IMPORT_LISTS.flatMap((l) => l.members);
 
+// Every id that must have a committed PNG: members + built-ins + defaults.
+const faviconIds = [...new Set([
+    ...allMembers.map((m) => m.id),
+    ...BUILTIN_FAVICONS.map((b) => b.id),
+    ...DEFAULT_LIST_MEMBERS.map((m) => m.id),
+])];
+const missingFavicons = () => faviconIds.filter((id) => !existsSync(faviconFile(id)));
+
+// Failure message for a still-missing PNG — after the local auto-fetch has
+// had its chance, or under CI where no network is allowed.
+const faviconHelp = (id) => (process.env.CI
+    ? `missing public/favicons/${id}.png — run pnpm fetch-favicons locally and commit the PNGs`
+    : `missing public/favicons/${id}.png — auto-fetch could not find a PNG — hand-source a `
+      + `64px PNG into public/favicons/${id}.png (or run pnpm fetch-favicons)`);
+
 describe('import lists data integrity', () => {
+    // Local runs self-heal: missing PNGs are fetched before the existence
+    // assertions re-check them. CI never touches the network — the
+    // committed-PNG gate stays intact there.
+    before(async () => {
+        const missing = missingFavicons();
+        if (!missing.length || process.env.CI) return;
+        await fetchFavicons({ ids: missing });
+    });
+
     it('list ids are unique and every list carries an emoji icon', () => {
         const ids = IMPORT_LISTS.map((l) => l.id);
         assert.equal(new Set(ids).size, ids.length);
@@ -76,7 +106,7 @@ describe('import lists data integrity', () => {
         assert.equal(new Set(ids).size, ids.length);
         for (const m of DEFAULT_LIST_MEMBERS) {
             assert.equal(new URL(m.url).protocol, 'https:', m.id);
-            assert.ok(existsSync(faviconFile(m.id)), `missing public/favicons/${m.id}.png`);
+            assert.ok(existsSync(faviconFile(m.id)), faviconHelp(m.id));
         }
     });
 
@@ -89,7 +119,7 @@ describe('import lists data integrity', () => {
     it('every member and built-in target has a committed favicon PNG', () => {
         const builtinIds = BUILTIN_FAVICONS.map((b) => b.id);
         for (const id of [...allMembers.map((m) => m.id), ...builtinIds]) {
-            assert.ok(existsSync(faviconFile(id)), `missing public/favicons/${id}.png`);
+            assert.ok(existsSync(faviconFile(id)), faviconHelp(id));
         }
     });
 
@@ -110,4 +140,20 @@ describe('import lists data integrity', () => {
             assert.ok(list.members.length <= CONNECTIVITY_TARGET_LIMIT, list.id);
         }
     });
+
+    it('every list (and the system list) is named in all four locale packs', () => {
+        // ConnectivityAddDialog renders `connectivity.importLists.<id>` for
+        // IMPORT_LISTS and SYSTEM_IMPORT_LIST alike. Translations can't be
+        // auto-filled — the failure message names the exact file and key.
+        const listIds = [...IMPORT_LISTS.map((l) => l.id), SYSTEM_IMPORT_LIST.id];
+        for (const locale of ['en', 'zh', 'fr', 'ru']) {
+            const packPath = path.join(repoRoot, 'frontend', 'locales', `${locale}.json`);
+            const names = JSON.parse(readFileSync(packPath, 'utf8')).connectivity?.importLists ?? {};
+            for (const id of listIds) {
+                assert.ok(typeof names[id] === 'string' && names[id].trim().length > 0,
+                    `frontend/locales/${locale}.json is missing a non-empty `
+                    + `connectivity.importLists.${id}`);
+            }
+        }
+    });
 });

From a28aaeba0f4ffa8c6edbf80ec1c28e0889f11d0c Mon Sep 17 00:00:00 2001
From: jason5ng32 <jason5ng32@gmail.com>
Date: Sat, 22 Aug 2026 17:23:50 +0800
Subject: [PATCH 07/11] Feat(dnsresolver): country-annotated resolver list with
 region filter

Move the resolver list into api/data/dns-resolvers.js as structured
per-country data so adding a resolver becomes a one-object PR, gated
by a new data-integrity test. The API returns one flat annotated list
and the UI grows badge-style region filter chips (flags + localized
names via Intl.DisplayNames) above the result table.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 api/AGENTS.md                                 |   4 +
 api/data/dns-resolvers.js                     |  45 +++++++
 api/dns-resolver.js                           |  83 ++++++------
 .../components/advanced-tools/DnsResolver.vue | 122 ++++++++++++------
 frontend/locales/en.json                      |   3 +-
 frontend/locales/fr.json                      |   3 +-
 frontend/locales/ru.json                      |   3 +-
 frontend/locales/zh.json                      |   3 +-
 tests/dns-resolvers-data.test.js              |  65 ++++++++++
 9 files changed, 245 insertions(+), 86 deletions(-)
 create mode 100644 api/data/dns-resolvers.js
 create mode 100644 tests/dns-resolvers-data.test.js

diff --git a/api/AGENTS.md b/api/AGENTS.md
index 056b44391..ae3d62878 100644
--- a/api/AGENTS.md
+++ b/api/AGENTS.md
@@ -21,6 +21,10 @@ proxies (`get-user-info` / `update-user-achievement`), platform
 (`configs` / `sentry-tunnel` / `share-report`). Each file's header comment
 states its route and purpose — read those for specifics.
 
+`api/data/` holds contributor-editable static config consumed by handlers —
+currently `dns-resolvers.js`, the country-annotated resolver list behind
+`dns-resolver` (gated by `tests/dns-resolvers-data.test.js`).
+
 ## Conventions
 
 - **Handler shape.** Single default export `async (req, res) => …`: read
diff --git a/api/data/dns-resolvers.js b/api/data/dns-resolvers.js
new file mode 100644
index 000000000..2ffab8468
--- /dev/null
+++ b/api/data/dns-resolvers.js
@@ -0,0 +1,45 @@
+// api/data/dns-resolvers.js — the curated resolver list behind /api/dnsresolver.
+//
+// 👋 Contributors: this file is THE place to add a public DNS resolver.
+// Add one object to DNS_RESOLVERS below; no other backend change is needed
+// (the frontend groups results by `country` automatically). Entry shape:
+//
+//   {
+//       id: 'google',                             // unique lowercase slug, [a-z0-9-]
+//       name: 'Google',                           // display name shown in the UI
+//       country: 'US',                            // ISO 3166-1 alpha-2, UPPERCASE
+//                                                 // ('EU' allowed for EU-wide services)
+//       udp: '8.8.8.8',                           // optional — public UDP resolver IPv4
+//       doh: 'https://dns.google/resolve?',       // optional — DoH JSON endpoint prefix
+//   }
+//
+// Rules (enforced by tests/dns-resolvers-data.test.js — run `pnpm test`):
+// - At least one of `udp` / `doh` per entry.
+// - `doh` must be an https:// URL prefix ending in '?' or '&' — the handler
+//   appends `name=<host>&type=<type>` directly, so a prefix that already
+//   carries query params ends in '&' (see Cloudflare's `ct=…&`). The endpoint
+//   must speak the DNS-over-HTTPS JSON API (`Accept: application/dns-json`),
+//   not just RFC 8484 wire format.
+// - `country` is where the operator is based (headquarters), not where the
+//   anycast nodes are.
+//
+// ⚠️ Keep this list curated, not exhaustive: EVERY resolver here adds one
+// parallel upstream query per protocol to EVERY /api/dnsresolver request.
+// Prefer well-known, stable, globally reachable services — and resolvers
+// from countries not yet represented over a fifth US entry.
+//
+// Result ordering is stable: data-file order, and for providers with both
+// protocols the udp lookup comes right before the doh one.
+
+export const DNS_RESOLVERS = [
+    { id: 'google', name: 'Google', country: 'US', udp: '8.8.8.8', doh: 'https://dns.google/resolve?' },
+    { id: 'cloudflare', name: 'Cloudflare', country: 'US', udp: '1.1.1.1', doh: 'https://cloudflare-dns.com/dns-query?ct=application/dns-json&' },
+    { id: 'opendns', name: 'OpenDNS', country: 'US', udp: '208.67.222.222' },
+    { id: 'quad9', name: 'Quad9', country: 'CH', udp: '9.9.9.9' },
+    { id: 'controld', name: 'ControlD', country: 'CA', udp: '76.76.2.0' },
+    { id: 'adguard', name: 'AdGuard', country: 'CY', udp: '94.140.14.14', doh: 'https://dns.adguard.com/resolve?' },
+    { id: 'alidns', name: 'AliDNS', country: 'CN', udp: '223.5.5.5', doh: 'https://dns.alidns.com/resolve?' },
+    { id: 'dnspod', name: 'DNSPod', country: 'CN', udp: '119.29.29.29' },
+    { id: '114dns', name: '114DNS', country: 'CN', udp: '114.114.114.114' },
+    { id: 'dns4eu', name: 'DNS4EU', country: 'EU', udp: '86.54.11.1' },
+];
diff --git a/api/dns-resolver.js b/api/dns-resolver.js
index 560f06b3f..7b188e87d 100644
--- a/api/dns-resolver.js
+++ b/api/dns-resolver.js
@@ -1,8 +1,11 @@
-// api/dnsresolver.js
+// api/dns-resolver.js — GET /api/dnsresolver: resolve a hostname against every
+// resolver in api/data/dns-resolvers.js (UDP DNS + DoH) in parallel and return
+// one flat, country-annotated result list the frontend groups by country.
 import { Resolver } from 'dns';
 import { promisify } from 'util';
 import { fetchUpstream } from '../common/fetch-with-timeout.js';
 import logger from '../common/logger.js';
+import { DNS_RESOLVERS } from './data/dns-resolvers.js';
 
 // Bound each upstream lookup so the slowest server doesn't pin the
 // overall response. 3s for UDP DNS (`Resolver` rejects on first
@@ -11,28 +14,8 @@ import logger from '../common/logger.js';
 const DNS_TIMEOUT_MS = 3000;
 const DOH_TIMEOUT_MS = 5000;
 
-// Normal DNS server list
-const dnsServers = {
-    'Google': '8.8.8.8',
-    'Cloudflare': '1.1.1.1',
-    'OpenDNS': '208.67.222.222',
-    'Quad9': '9.9.9.9',
-    'ControlD': '76.76.2.0',
-    'AdGuard': '94.140.14.14',
-    'AliDNS': '223.5.5.5',
-    'DNSPod': '119.29.29.29',
-    '114DNS': '114.114.114.114',
-    'DNS4EU': '86.54.11.1',
-};
-
-// DNS-over-HTTPS server list
-const dohServers = {
-    'Google': 'https://dns.google/resolve?',
-    'Cloudflare': 'https://cloudflare-dns.com/dns-query?ct=application/dns-json&',
-    'AdGuard': 'https://dns.adguard.com/resolve?',
-    'AliDNS': 'https://dns.alidns.com/resolve?',
-};
-
+// Resolve via classic UDP DNS. Returns the raw result value: an array of
+// strings, a joined MX string, or 'N/A' on empty/failure.
 const resolveDns = async (hostname, type, name, server) => {
     const resolver = new Resolver({ timeout: DNS_TIMEOUT_MS, tries: 1 });
     resolver.setServers([server]);
@@ -74,19 +57,21 @@ const resolveDns = async (hostname, type, name, server) => {
         }
 
         if (addresses.length === 0 || addresses === '' || addresses === null) {
-            return { [name]: `N/A` };
+            return 'N/A';
         }
 
-        return { [name]: addresses };
+        return addresses;
     } catch (error) {
         // Per-server timeouts are expected (some DNS hosts are unreachable
         // from a given network); demote to debug so they don't spam the
         // terminal during normal operation.
         logger.debug({ err: error, server: name }, 'DNS resolver: lookup failed, returning N/A');
-        return { [name]: `N/A` };
+        return 'N/A';
     }
 };
 
+// Resolve via the DNS-over-HTTPS JSON API. Same return semantics as
+// resolveDns. `url` is a prefix ending in '?' or '&' (see the data file).
 const resolveDoh = async (hostname, type, name, url) => {
     try {
         const response = await fetchUpstream(`${url}name=${hostname}&type=${type}`, {
@@ -96,12 +81,12 @@ const resolveDoh = async (hostname, type, name, url) => {
         const data = await response.json();
         const addresses = data.Answer ? data.Answer.map(answer => answer.data) : ['N/A'];
         if (addresses.length === 0 || addresses === '' || addresses === null) {
-            return { [name]: `N/A` };
+            return 'N/A';
         }
-        return { [name]: addresses };
+        return addresses;
     } catch (error) {
         logger.debug({ err: error, server: name }, 'DoH resolver: lookup failed, returning N/A');
-        return { [name]: `N/A` };
+        return 'N/A';
     }
 };
 
@@ -127,20 +112,36 @@ const dnsResolver = async (req, res) => {
         return res.status(400).send({ error: 'Invalid hostname' });
     }
 
-    const dnsPromises = Object.entries(dnsServers).map(([name, ip]) => resolveDns(hostname, type, name, ip));
-    const dohPromises = Object.entries(dohServers).map(([name, url]) => resolveDoh(hostname, type, name, url));
+    // One lookup task per entry × protocol, in stable order: data-file order,
+    // udp before doh within a provider. Each task resolves to one row of the
+    // response; failures collapse to result 'N/A' inside the resolvers, so
+    // Promise.all never rejects here.
+    const lookups = DNS_RESOLVERS.flatMap((server) => {
+        const tasks = [];
+        if (server.udp) {
+            tasks.push(resolveDns(hostname, type, server.name, server.udp).then((result) => ({
+                id: server.id,
+                provider: server.name,
+                country: server.country,
+                type: 'udp',
+                result,
+            })));
+        }
+        if (server.doh) {
+            tasks.push(resolveDoh(hostname, type, server.name, server.doh).then((result) => ({
+                id: server.id,
+                provider: server.name,
+                country: server.country,
+                type: 'doh',
+                result,
+            })));
+        }
+        return tasks;
+    });
 
     try {
-        // Execute all DNS and DoH queries in parallel
-
-        const result_dns = await Promise.all(dnsPromises);
-        const result_doh = await Promise.all(dohPromises);
-
-        res.json({
-            hostname,
-            result_dns,
-            result_doh
-        });
+        const results = await Promise.all(lookups);
+        res.json({ hostname, results });
     } catch (error) {
         res.status(500).send({ error: error.message });
     }
diff --git a/frontend/components/advanced-tools/DnsResolver.vue b/frontend/components/advanced-tools/DnsResolver.vue
index b45d01b33..cb6f32bcd 100644
--- a/frontend/components/advanced-tools/DnsResolver.vue
+++ b/frontend/components/advanced-tools/DnsResolver.vue
@@ -37,45 +37,70 @@
             <p v-if="errorMsg" class="text-sm text-destructive">{{ errorMsg }}</p>
         </div>
 
-        <!-- Result table -->
-        <Card v-if="combinedResults && combinedResults.length">
-            <CardContent class="p-0">
-                <div class="overflow-x-auto">
-                    <table class="w-full text-sm">
-                        <thead>
-                            <tr class="border-b">
-                                <th scope="col"
-                                    class="text-left px-4 py-2.5 text-xs font-medium text-muted-foreground uppercase tracking-wide">
-                                    {{ t('dnsresolver.Provider') }}
-                                </th>
-                                <th scope="col"
-                                    class="text-left px-4 py-2.5 text-xs font-medium text-muted-foreground uppercase tracking-wide">
-                                    {{ t('dnsresolver.Result') }}
-                                </th>
-                            </tr>
-                        </thead>
-                        <tbody class="divide-y">
-                            <tr v-for="(result, index) in combinedResults" :key="index"
-                                class="hover:bg-muted/50 transition-colors">
-                                <td class="px-4 py-2.5 whitespace-nowrap font-medium">{{ result.provider }}</td>
-                                <td class="px-4 py-2.5 font-mono wrap-break-word"
-                                    :class="result.address === 'N/A' ? 'text-muted-foreground/60' : ''">
-                                    {{ result.address }}
-                                </td>
-                            </tr>
-                        </tbody>
-                    </table>
-                </div>
-            </CardContent>
-        </Card>
+        <!-- Results: region filter chips + provider table -->
+        <div v-if="combinedResults && combinedResults.length" class="space-y-3">
+            <!-- Country selector (first-appearance order from the response),
+                 badge-shaped toggles: all regions + one per country. -->
+            <ToggleGroup :model-value="countryFilter" type="single" variant="outline" size="sm"
+                class="flex-wrap justify-start"
+                @update:model-value="(v) => v && (countryFilter = v)">
+                <ToggleGroupItem value="all" class="gap-1.5 cursor-pointer">
+                    {{ t('dnsresolver.AllRegions') }}
+                </ToggleGroupItem>
+                <ToggleGroupItem v-for="country in resultCountries" :key="country" :value="country"
+                    class="gap-1.5 cursor-pointer" :aria-label="countryName(country)">
+                    <Icon :icon="'circle-flags:' + country.toLowerCase()" class="size-3.5 shrink-0" />
+                    {{ countryName(country) }}
+                </ToggleGroupItem>
+            </ToggleGroup>
+
+            <Card>
+                <CardContent class="p-0">
+                    <div class="overflow-x-auto">
+                        <table class="w-full text-sm">
+                            <thead>
+                                <tr class="border-b">
+                                    <th scope="col"
+                                        class="text-left px-4 py-2.5 text-xs font-medium text-muted-foreground uppercase tracking-wide">
+                                        {{ t('dnsresolver.Provider') }}
+                                    </th>
+                                    <th scope="col"
+                                        class="text-left px-4 py-2.5 text-xs font-medium text-muted-foreground uppercase tracking-wide">
+                                        {{ t('dnsresolver.Result') }}
+                                    </th>
+                                </tr>
+                            </thead>
+                            <tbody class="divide-y">
+                                <tr v-for="(result, index) in filteredResults" :key="result.country + '-' + index"
+                                    class="hover:bg-muted/50 transition-colors">
+                                    <td class="px-4 py-2.5 whitespace-nowrap font-medium">
+                                        <span class="flex items-center gap-2">
+                                            <Icon :icon="'circle-flags:' + result.country.toLowerCase()"
+                                                class="size-4 shrink-0" :title="countryName(result.country)" />
+                                            {{ result.provider }}
+                                        </span>
+                                    </td>
+                                    <td class="px-4 py-2.5 font-mono wrap-break-word"
+                                        :class="result.address === 'N/A' ? 'text-muted-foreground/60' : ''">
+                                        {{ result.address }}
+                                    </td>
+                                </tr>
+                            </tbody>
+                        </table>
+                    </div>
+                </CardContent>
+            </Card>
+        </div>
     </div>
 </template>
 
 <script setup>
-import { ref } from 'vue';
+import { computed, ref } from 'vue';
 import { useI18n } from 'vue-i18n';
+import { Icon } from '@iconify/vue';
 import { trackEvent } from '@/utils/analytics';
 import { isValidDomain } from '@/utils/valid-ip.js';
+import getCountryName from '@/data/country-name.js';
 import { Input } from '@/components/ui/input';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent } from '@/components/ui/card';
@@ -84,13 +109,14 @@ import { Spinner } from '@/components/ui/spinner';
 import { Play } from '@lucide/vue';
 import { Label } from '@/components/ui/label';
 
-const { t } = useI18n();
+const { t, locale } = useI18n();
 
 const queryURL = ref('');
 const queryType = ref('A');
 const dnsCheckStatus = ref('idle');
 const errorMsg = ref('');
 const combinedResults = ref([]);
+const countryFilter = ref('all');
 
 const recordTypes = ['A', 'AAAA', 'CNAME', 'MX', 'NS', 'TXT'];
 
@@ -133,14 +159,28 @@ const getDNSResults = async (hostname, type) => {
     }
 };
 
+// Flatten the API's { id, provider, country, type, result } rows into
+// display rows; the protocol keeps its label suffix on the provider name.
 const processResults = (data) => {
-    const processEntries = (entries, kind) => entries.map(entry => {
-        const provider = Object.keys(entry)[0];
-        const address = Array.isArray(entry[provider]) ? entry[provider].join(', ') : entry[provider];
-        return { provider: `${provider} (${kind})`, address };
-    });
-
-    if (data.result_dns) combinedResults.value.push(...processEntries(data.result_dns, 'DNS'));
-    if (data.result_doh) combinedResults.value.push(...processEntries(data.result_doh, 'DoH 🔒'));
+    if (!Array.isArray(data.results)) return;
+    combinedResults.value = data.results.map(entry => ({
+        country: entry.country,
+        provider: `${entry.provider} (${entry.type === 'doh' ? 'DoH 🔒' : 'DNS'})`,
+        address: Array.isArray(entry.result) ? entry.result.join(', ') : entry.result,
+    }));
+    // A previously selected region may be absent from the new result set.
+    if (countryFilter.value !== 'all' && !resultCountries.value.includes(countryFilter.value)) {
+        countryFilter.value = 'all';
+    }
 };
+
+// Countries present in the results, first-appearance order.
+const resultCountries = computed(() => [...new Set(combinedResults.value.map((r) => r.country))]);
+
+const filteredResults = computed(() => (countryFilter.value === 'all'
+    ? combinedResults.value
+    : combinedResults.value.filter((r) => r.country === countryFilter.value)));
+
+// Localized country name via Intl.DisplayNames; fall back to the raw code.
+const countryName = (code) => getCountryName(code, locale.value) || code;
 </script>
diff --git a/frontend/locales/en.json b/frontend/locales/en.json
index b668492b6..c03384ddf 100644
--- a/frontend/locales/en.json
+++ b/frontend/locales/en.json
@@ -968,7 +968,8 @@
     "fetchError": "Unable to fetch resolution results",
     "Provider": "DNS Provider",
     "Result": "Resolution Result",
-    "Record": "Record"
+    "Record": "Record",
+    "AllRegions": "All Regions"
   },
   "ruletest": {
     "Title": "Rule Test",
diff --git a/frontend/locales/fr.json b/frontend/locales/fr.json
index a6d744ca6..27425d9ba 100644
--- a/frontend/locales/fr.json
+++ b/frontend/locales/fr.json
@@ -968,7 +968,8 @@
     "fetchError": "Impossible de récupérer les résultats de résolution",
     "Provider": "Fournisseur DNS",
     "Result": "Résultat de la Résolution",
-    "Record": "Enregistrement"
+    "Record": "Enregistrement",
+    "AllRegions": "Toutes les régions"
   },
   "ruletest": {
     "Title": "Test de règles",
diff --git a/frontend/locales/ru.json b/frontend/locales/ru.json
index 1cb6dfbdc..3f2197c0e 100644
--- a/frontend/locales/ru.json
+++ b/frontend/locales/ru.json
@@ -968,7 +968,8 @@
     "fetchError": "Не удалось получить результаты разрешения",
     "Provider": "DNS-провайдер",
     "Result": "Результат разрешения",
-    "Record": "Запись"
+    "Record": "Запись",
+    "AllRegions": "Все регионы"
   },
   "ruletest": {
     "Title": "Проверка правил",
diff --git a/frontend/locales/zh.json b/frontend/locales/zh.json
index 0878a8c85..d55e47e38 100644
--- a/frontend/locales/zh.json
+++ b/frontend/locales/zh.json
@@ -968,7 +968,8 @@
     "fetchError": "无法获取解析结果",
     "Provider": "DNS 服务商",
     "Result": "解析结果",
-    "Record": "记录"
+    "Record": "记录",
+    "AllRegions": "全部地区"
   },
   "ruletest": {
     "Title": "分流测试",
diff --git a/tests/dns-resolvers-data.test.js b/tests/dns-resolvers-data.test.js
new file mode 100644
index 000000000..57a1b19fd
--- /dev/null
+++ b/tests/dns-resolvers-data.test.js
@@ -0,0 +1,65 @@
+// Data-integrity gate for api/data/dns-resolvers.js — the file resolver-
+// addition PRs touch. A new entry that breaks any rule here (bad country
+// code, malformed doh prefix, duplicate id, …) fails `pnpm test` before it
+// can break the live /api/dnsresolver endpoint.
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { DNS_RESOLVERS } from '../api/data/dns-resolvers.js';
+import { isValidIP, isIPv6 } from '../common/valid-ip.js';
+
+// 'EU' is a CLDR-supported region code, so this also validates DNS4EU.
+const regionNames = new Intl.DisplayNames(['en'], { type: 'region', fallback: 'none' });
+
+describe('DNS_RESOLVERS data integrity', () => {
+    it('is a non-empty array', () => {
+        assert.ok(Array.isArray(DNS_RESOLVERS));
+        assert.ok(DNS_RESOLVERS.length > 0);
+    });
+
+    it('ids are unique lowercase slugs', () => {
+        const ids = DNS_RESOLVERS.map((r) => r.id);
+        assert.equal(new Set(ids).size, ids.length, 'duplicate id');
+        for (const id of ids) {
+            assert.match(id, /^[a-z0-9-]+$/, `id "${id}" must be a lowercase slug`);
+        }
+    });
+
+    it('names are unique non-empty strings', () => {
+        const names = DNS_RESOLVERS.map((r) => r.name);
+        assert.equal(new Set(names).size, names.length, 'duplicate name');
+        for (const name of names) {
+            assert.equal(typeof name, 'string');
+            assert.ok(name.length > 0);
+        }
+    });
+
+    it('country is an uppercase two-letter code that Intl.DisplayNames resolves', () => {
+        for (const { id, country } of DNS_RESOLVERS) {
+            assert.match(country, /^[A-Z]{2}$/, `${id}: country "${country}" must be ISO alpha-2 uppercase`);
+            const resolved = regionNames.of(country);
+            assert.ok(resolved, `${id}: country "${country}" is not a known region code`);
+        }
+    });
+
+    it('every entry has at least one of udp / doh', () => {
+        for (const { id, udp, doh } of DNS_RESOLVERS) {
+            assert.ok(udp || doh, `${id}: needs a udp IP or a doh URL`);
+        }
+    });
+
+    it('udp, when present, is a valid IPv4 address', () => {
+        for (const { id, udp } of DNS_RESOLVERS) {
+            if (udp === undefined) continue;
+            assert.ok(isValidIP(udp) && !isIPv6(udp), `${id}: udp "${udp}" is not a valid IPv4`);
+        }
+    });
+
+    it("doh, when present, is https:// and ends with '?' or '&'", () => {
+        for (const { id, doh } of DNS_RESOLVERS) {
+            if (doh === undefined) continue;
+            assert.ok(doh.startsWith('https://'), `${id}: doh must be https://`);
+            assert.match(doh, /[?&]$/, `${id}: doh prefix must end with '?' or '&' — the handler appends name=<host>&type=<type>`);
+        }
+    });
+});

From 06d25f373b492fdd94d217d1eb7324cc8cb5ba42 Mon Sep 17 00:00:00 2001
From: jason5ng32 <jason5ng32@gmail.com>
Date: Sat, 22 Aug 2026 17:23:57 +0800
Subject: [PATCH 08/11] Docs(contributing): rewrite onboarding and slim the
 GitHub templates

CONTRIBUTING now reflects the real workflow (pnpm-only setup, dev-in
dev-out, pnpm check) and points contributors at the AGENTS.md files
and the online Developer Guide. The bug report template drops
self-host-only fields most reporters can't fill; the PR checklist
shrinks to five verifiable items.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .github/ISSUE_TEMPLATE/bug_report.md |  59 +++-----
 .github/pull_request_template.md     |  28 ++--
 CONTRIBUTING.md                      | 192 +++++++++++++++------------
 3 files changed, 136 insertions(+), 143 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 105a2c0d7..249fb7f52 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,58 +1,33 @@
 ---
 name: Bug report
-about: Bug Report Template
-title: "[Short Description of the Bug]"
+about: Something isn't working
+title: ''
 labels: bug
 assignees: ''
 
 ---
 
-## Environment:
+## What happened?
 
-* Operating System:
-* Browser (if applicable):
-* Node Version:
-* Vite Version:
-* Vue3 Version:
-* Docker Version (if applicable):
-* Deployment Method (Vercel/Docker/Node):
-* Environment Variables (without sensitive info):
-* Any other relevant software versions:
+A clear description of the bug. Screenshots or recordings help a lot.
 
-## Description:
+## Steps to reproduce
 
-Provide a clear and concise description of what the bug is.
+1. …
+2. …
 
-Steps to Reproduce:
+## What did you expect?
 
-1. Step one to reproduce
-2. Step two...
-3. ...
+## Environment
 
-## Expected Behavior:
+- Where: ipcheck.ing / self-hosted (Docker / Node / Vercel)
+- OS & browser (for page issues):
+- Node version (self-hosted only):
 
-Describe what you expected to happen.
+## Logs (if applicable)
 
-## Actual Behavior:
+Browser console errors for page issues; terminal output for self-hosted / backend issues.
 
-Describe what actually happened. Include screenshots or screen recordings if possible.
-
-## Terminal & Console Logs:
-
-**Important**: Please include the terminal logs and browser console logs if applicable. These logs are crucial for identifying the root cause of the issue.
-
-### Terminal Logs (include any error messages or stack traces):
-
-[Logs here]
-
-### Browser Console Logs (if frontend issue):
-
-[Logs here]
-
-Additional Context:
-
-Add any other context about the problem here, like links to related issues, logs, etc.
-
-## Possible Solution (optional):
-
-If you have an idea of how to fix the issue, please describe it here.
+```text
+paste logs here
+```
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 16c0188a9..342a7c0f2 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,23 +1,13 @@
-# Pull Request Template
+> ⚠️ **Open this PR against the `dev` branch, not `main`.** `main` only receives release merges from `dev`.
 
-> ⚠️ **Please open this PR against the `dev` branch, not `main`.** All contributions go through `dev`; `main` only receives release merges.
+## What & why
 
-## Description
-Please include a summary of the change and which issue is fixed. 
+Summary of the change, and the issue it fixes if any (e.g. `Closes #123`).
 
-## Type of change
-- [ ] Bug fix
-- [ ] New feature
-- [ ] Breaking change
-- [ ] Documentation update
+## Checklist
 
-## Checklist:
-- [ ] This PR targets the `dev` branch, not `main`.
-- [ ] I have followed the contribution guidelines.
-- [ ] My code follows the style guidelines of this project.
-- [ ] I have performed a self-review of my own code.
-- [ ] I have commented my code, particularly in hard-to-understand areas.
-- [ ] I have made corresponding changes to the documentation.
-- [ ] My changes generate no new warnings.
-- [ ] I have added tests that prove my fix is effective or that my feature works.
-- [ ] New and existing unit tests pass locally with my changes.
+- [ ] Targets `dev`; one concern per PR
+- [ ] `pnpm check` is green locally (tests + build)
+- [ ] Logic changes ship with a spec in `tests/`
+- [ ] User-visible copy lands in all four locales (`en` / `zh` / `fr` / `ru`)
+- [ ] I've read [CONTRIBUTING.md](../CONTRIBUTING.md) and the relevant `AGENTS.md`
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b82597024..775284c69 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,82 +1,110 @@
-# CONTRIBUTING.md
-
-## Welcome Contributors! 👋
-
-We're delighted that you're interested in contributing to our project! This document provides guidelines to ensure a smooth contribution process for everyone involved.
-
-### Table of Contents
-
-- [CONTRIBUTING.md](#contributingmd)
-  - [Welcome Contributors! 👋](#welcome-contributors-)
-    - [Table of Contents](#table-of-contents)
-    - [Code of Conduct](#code-of-conduct)
-    - [Getting Started](#getting-started)
-    - [Reporting Bugs](#reporting-bugs)
-    - [Feature Requests](#feature-requests)
-    - [Submitting Changes](#submitting-changes)
-    - [Setting Up Your Environment](#setting-up-your-environment)
-    - [Testing](#testing)
-    - [Pull Request Guidelines](#pull-request-guidelines)
-    - [Code Review Process](#code-review-process)
-    - [Community and Support](#community-and-support)
-  - [Thank You! 👏](#thank-you-)
-
-### Code of Conduct
-
-This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
-
-### Getting Started
-
-If you're new to the project, consider:
-
-- Reading the project's README for an overview.
-- Checking the issues labeled as `good first issue` for an easy entry point.
-
-### Reporting Bugs
-
-Please follow the bug report template provided in [BUG_REPORT_TEMPLATE.md](.github/ISSUE_TEMPLATE/bug_report.md). Include terminal and console logs for a comprehensive report.
-
-### Feature Requests
-
-We love to hear your ideas! Open an issue with the tag `feature request` and provide a clear and detailed explanation of the feature and its benefits.
-
-### Submitting Changes
-
-Before making any changes, please:
-
-1. Open a new issue discussing your proposed change.
-2. Fork the repository and create your branch from **`dev`** — all contributions are based on `dev`, not `main`.
-
-### Setting Up Your Environment
-
-To set up the development environment for this project, you'll need to:
-
-1. Install Node.js, Vite, and Vue3.
-2. Clone the repository.
-3. Run `pnpm install` to install dependencies.
-4. Follow the instructions for Docker and Vercel deployment in our documentation if necessary.
-
-### Testing
-
-Ensure that all tests pass and, if applicable, add new tests for your changes. Run `pnpm test` to execute tests.
-
-### Pull Request Guidelines
-
-When you're ready to submit your changes:
-
-1. **Open your pull request against the `dev` branch — not `main`.** `main` only receives release merges from `dev`, so any PR targeting `main` will be asked to retarget.
-2. Rebase your branch onto the latest `dev` before submitting.
-3. Keep one concern per PR — don't bundle unrelated changes (e.g. a feature plus a dev-environment tweak) into the same pull request.
-4. Ensure your changes adhere to the coding standards and guidelines, with a clear description of what you changed.
-
-### Code Review Process
-
-The project maintainers will review your pull request. They might request changes or provide feedback before merging.
-
-### Community and Support
-
-Join our community channels (link your channels here) for support and discussions.
-
-## Thank You! 👏
-
-Your contributions are what make this community great. We appreciate your efforts in making this project better!
+# Contributing to MyIP
+
+Thanks for your interest in contributing! MyIP ([IPCheck.ing](https://ipcheck.ing)) is an
+open-source IP toolbox — IP lookup, connectivity tests, WebRTC / DNS-leak detection,
+speed test, and more — built as a Vue 3 SPA with an Express 5 backend.
+
+New here? Look for issues labeled
+[`good first issue`](https://github.com/jason5ng32/MyIP/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+— they're scoped to be doable without knowing the whole codebase.
+
+## Quick start
+
+1. **Fork** the repo and create your branch **from `dev`** (never `main` — `main` only
+   receives release merges from `dev`).
+2. **Set up:** Node.js 20+ (CI runs on Node 24) and pnpm. The pnpm version is pinned
+   via the `packageManager` field, so the easiest path is:
+
+   ```bash
+   corepack enable   # or: npm install -g pnpm
+   pnpm install
+   pnpm dev          # starts Vite + the backend together
+   ```
+
+   **pnpm only.** npm or yarn would produce a competing lockfile — PRs that touch
+   `package-lock.json` / `yarn.lock` will be asked to redo the install with pnpm.
+3. Make your change — **one concern per PR**, don't bundle unrelated changes.
+4. **Run `pnpm check`** (tests + production build). It must be green before you open a PR.
+5. Open your PR **against `dev`**, rebased onto the latest `dev`, with a clear
+   description of what changed and why.
+
+For anything non-trivial, open an issue first to discuss the approach — it saves you
+from building something that can't be merged.
+
+## Project map
+
+```
+frontend/   Vue 3 SPA (Pinia, vue-router, vue-i18n, Tailwind v4 + shadcn-vue)
+api/        Express 5 handlers, one file per route (wired in backend-server.js)
+common/     Code shared by both halves (validators, fetch helper, logger, …)
+tests/      Node test runner specs (node --test)
+```
+
+**The real architecture and convention docs are the AGENTS.md files:**
+[`AGENTS.md`](AGENTS.md) (root), [`frontend/AGENTS.md`](frontend/AGENTS.md), and
+[`api/AGENTS.md`](api/AGENTS.md). Don't let the filename fool you — they're written
+for humans and AI agents alike, and they're the single source of truth for how this
+repo works. Read the root one plus whichever half you're touching before writing code.
+
+Prefer a guided tour? The online **[Developer Guide](https://docs.ipcheck.ing/developer)**
+walks through the project architecture, configuration, and deployment in detail
+(also available in 中文, français, and русский).
+
+## Key conventions (short version)
+
+Details and rationale live in the AGENTS.md files; the headlines:
+
+- **JavaScript only** — no TypeScript, no `lang="ts"`.
+- **New functions use `const` arrow syntax** (`const fn = async () => {}`).
+- **Every new file opens with a header comment** stating its purpose.
+- **Four locales land together** — user-visible copy ships in `en` / `zh` / `fr` / `ru`
+  in the same PR (`frontend/locales/`; tests enforce this for some surfaces).
+- **Backend logging goes through the shared pino logger** (`common/logger.js`) —
+  no `console.*` in `api/` or `common/`.
+
+## Good places to start
+
+**DNS resolvers** — the resolver list lives in `api/data/dns-resolvers.js`, a
+country-annotated data file written for exactly this kind of PR (the header
+comment documents the entry shape and rules, and `tests/dns-resolvers-data.test.js`
+checks your entry). Adding a well-known public resolver — especially from a
+country not yet represented — is a one-object change; the UI groups results
+by country automatically.
+
+**Connectivity test sites & lists** — curated site lists live in
+`frontend/data/connectivity-import-lists.js`. Each member needs a committed 64px PNG
+icon at `public/favicons/<id>.png`, but you normally don't source it yourself: run
+`pnpm test` locally and the data test auto-downloads any missing icons (also
+runnable directly as `pnpm fetch-favicons`). Only if auto-fetch can't find a usable
+PNG do you hand-source one (on macOS, `sips` handles ICO→PNG). Remember to commit
+the PNGs with your change — CI stays offline and only checks they exist.
+
+**Translations** — improvements to the existing `en` / `zh` / `fr` / `ru` packs are
+welcome. Adding a whole new locale is heavier than it looks (every future copy change
+must land in it too), so please open an issue to discuss before starting one.
+
+## Bugs & feature requests
+
+Use the issue templates in [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/) —
+one for bug reports (include terminal / browser console logs) and one for feature
+requests. For general questions, GitHub Issues is also the right place; there are
+no chat channels.
+
+## Testing
+
+- Specs live in `tests/` and run with `pnpm test` (Node's built-in test runner).
+- Non-visual logic — pure functions, composables, transforms, validators — ships with
+  a spec in the same PR. Tests never hit real upstreams (the one exception: the
+  connectivity data test may download missing favicons on local runs, never in CI).
+- UI rendering and browser APIs are out of scope for the Node runner; visual changes
+  are verified by the maintainer during review, so mention in your PR what to look at.
+
+## Code of Conduct
+
+This project follows a [Code of Conduct](CODE_OF_CONDUCT.md). By participating,
+you agree to uphold it.
+
+---
+
+Thank you for making MyIP better! Every contribution — a one-line fix, a new
+resolver, a better translation — is appreciated.

From c291e0779475770eefccb07990a4646cae5ee874 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B1=86=E8=85=90=E3=81=9F=E3=81=9D?= <tasodoufu@gmail.com>
Date: Sat, 22 Aug 2026 19:04:13 +0900
Subject: [PATCH 09/11] =?UTF-8?q?Docs(prefs):=20fix=20stale=20locale=20com?=
 =?UTF-8?q?ment=20(tr=20=E2=86=92=20ru)=20(#409)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: tasodoufu <313684430+tasodoufu@users.noreply.github.com>
---
 frontend/data/default-preferences.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend/data/default-preferences.js b/frontend/data/default-preferences.js
index 2f4a9e317..82b35da2b 100644
--- a/frontend/data/default-preferences.js
+++ b/frontend/data/default-preferences.js
@@ -26,7 +26,7 @@ export const DEFAULT_PREFERENCES = Object.freeze({
   // Local IP-history recorder (see use-ip-history.js). Days: 1–90.
   ipHistoryEnabled: true,
   ipHistoryDays: 90,
-  lang: 'auto', // auto | zh | en | fr | tr
+  lang: 'auto', // auto | zh | en | fr | ru
   // The full Connectivity target set (defaults included). null until first
   // load — store.loadPreferences() runs it through sanitizeTargets(), which
   // also rebuilds a hand-emptied or corrupted stored value.

From 8b2e49b57ef835bfc498b64ed722438fdb587ef4 Mon Sep 17 00:00:00 2001
From: jason5ng32 <jason5ng32@gmail.com>
Date: Sat, 22 Aug 2026 18:16:04 +0800
Subject: [PATCH 10/11] Docs(readme): add a Contributing section and open the
 door to README translations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The READMEs — the project's highest-traffic pages — carried no
contribution invitation. All four gain a short Contributing section
pointing at the good-first-issue label and CONTRIBUTING.md, which now
also documents community-maintained README translations (English stays
canonical) as a starter area distinct from UI translations.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CONTRIBUTING.md | 14 +++++++++++---
 README.md       |  7 +++++++
 README_FR.md    |  7 +++++++
 README_RU.md    |  7 +++++++
 README_ZH.md    |  7 +++++++
 5 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 775284c69..f3e8ce7f1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -79,9 +79,17 @@ runnable directly as `pnpm fetch-favicons`). Only if auto-fetch can't find a usa
 PNG do you hand-source one (on macOS, `sips` handles ICO→PNG). Remember to commit
 the PNGs with your change — CI stays offline and only checks they exist.
 
-**Translations** — improvements to the existing `en` / `zh` / `fr` / `ru` packs are
-welcome. Adding a whole new locale is heavier than it looks (every future copy change
-must land in it too), so please open an issue to discuss before starting one.
+**README translations** — beyond the four READMEs we maintain (`en` / `zh` / `fr` /
+`ru`), community-maintained translations in any language are welcome. Create
+`README_<LANG>.md` from the English [README.md](README.md) (the canonical source),
+open it with a one-line "community-maintained translation — English is canonical"
+note in your language, and add your language to the switcher row near the top of the
+existing READMEs. Keep code blocks, URLs, and badges unchanged. Check open issues
+for requested languages before starting.
+
+**UI translations** — improvements to the existing `en` / `zh` / `fr` / `ru` packs are
+welcome. Adding a whole new UI locale is heavier than it looks (every future copy
+change must land in it too), so please open an issue to discuss before starting one.
 
 ## Bugs & feature requests
 
diff --git a/README.md b/README.md
index d4786513f..331f36246 100644
--- a/README.md
+++ b/README.md
@@ -99,6 +99,13 @@ Full guides live in the MyIP Docs Center: **[docs.ipcheck.ing](https://docs.ipch
 * [Developer Guide](https://docs.ipcheck.ing/developer) — deployment, configuration, architecture, and contributing
 * [Knowledge Base](https://docs.ipcheck.ing/knowledge-base) — how to use every tool, step-by-step network diagnosis, and networking concepts
 
+## 🤝 Contributing
+
+Contributions are welcome! We keep a curated set of beginner-friendly tasks — each with exact file paths, acceptance criteria, and tests that guide you to a green build:
+
+* 🏷️ [Good first issues](https://github.com/jason5ng32/MyIP/labels/good%20first%20issue) — add a DNS resolver from your country, add curated site lists, translate the README into your language, polish translations, and more
+* 📄 [CONTRIBUTING.md](CONTRIBUTING.md) — setup, conventions, and how PRs flow (target the `dev` branch)
+
 ## ⚙️ Configuration
 
 Two settings matter before anything else:
diff --git a/README_FR.md b/README_FR.md
index 925cd9de3..9c9a75dd7 100644
--- a/README_FR.md
+++ b/README_FR.md
@@ -99,6 +99,13 @@ Les guides complets se trouvent dans le centre de documentation MyIP : **[docs.i
 * [Guide du développeur](https://docs.ipcheck.ing/developer/fr) — déploiement, configuration, architecture et contribution
 * [Base de connaissances](https://docs.ipcheck.ing/knowledge-base/fr) — utilisation de chaque outil, diagnostic réseau pas à pas, concepts réseau
 
+## 🤝 Contribuer
+
+Les contributions sont les bienvenues ! Nous maintenons une sélection de tâches adaptées aux débutants — chacune avec les fichiers précis, les critères d'acceptation et des tests pour vous guider :
+
+* 🏷️ [Good first issues](https://github.com/jason5ng32/MyIP/labels/good%20first%20issue) — ajouter un résolveur DNS de votre pays, enrichir les listes de sites, traduire le README dans votre langue, améliorer les traductions…
+* 📄 [CONTRIBUTING.md](CONTRIBUTING.md) — installation, conventions et flux des PR (ciblez la branche `dev`)
+
 ## ⚙️ Configuration
 
 Deux réglages comptent avant tout :
diff --git a/README_RU.md b/README_RU.md
index 996baa305..cb545df19 100644
--- a/README_RU.md
+++ b/README_RU.md
@@ -99,6 +99,13 @@ docker run -d -p 18966:18966 --name myip --restart always jason5ng32/myip:latest
 * [Руководство разработчика](https://docs.ipcheck.ing/developer/ru) — развёртывание, настройка, архитектура и участие в разработке
 * [База знаний](https://docs.ipcheck.ing/knowledge-base/ru) — как пользоваться каждым инструментом, пошаговая диагностика сети, сетевые концепции
 
+## 🤝 Участие в проекте
+
+Мы рады вашему участию! У нас есть подборка задач для новичков — с точными путями к файлам, критериями приёмки и тестами, которые ведут вас к зелёной сборке:
+
+* 🏷️ [Good first issues](https://github.com/jason5ng32/MyIP/labels/good%20first%20issue) — добавьте DNS-резолвер своей страны, расширьте подборки сайтов, переведите README на свой язык, улучшите переводы
+* 📄 [CONTRIBUTING.md](CONTRIBUTING.md) — настройка окружения, соглашения и процесс PR (PR направляются в ветку `dev`)
+
 ## ⚙️ Конфигурация
 
 Прежде всего важны две настройки:
diff --git a/README_ZH.md b/README_ZH.md
index f347793be..be5ba2dda 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -99,6 +99,13 @@ docker run -d -p 18966:18966 --name myip --restart always jason5ng32/myip:latest
 * [开发者指南](https://docs.ipcheck.ing/developer/zh) —— 部署、配置、架构说明与参与贡献
 * [知识库](https://docs.ipcheck.ing/knowledge-base/zh) —— 每个工具的使用说明、网络问题排查指南、网络概念科普
 
+## 🤝 参与贡献
+
+欢迎参与贡献！我们维护着一批对新手友好的任务，每条都写明了具体文件、验收标准，并有测试引导你完成：
+
+* 🏷️ [Good first issues](https://github.com/jason5ng32/MyIP/labels/good%20first%20issue) —— 添加你所在国家的 DNS 解析服务、添加精选网站列表、把 README 翻译成你的语言、润色翻译等
+* 📄 [CONTRIBUTING.md](CONTRIBUTING.md) —— 环境搭建、开发约定与 PR 流程（请将 PR 提交到 `dev` 分支）
+
 ## ⚙️ 配置
 
 开始之前，有两项配置最重要：

From daac0b753572c54936a8a9f16aa7ff76afafa967 Mon Sep 17 00:00:00 2001
From: jason5ng32 <jason5ng32@gmail.com>
Date: Sat, 22 Aug 2026 18:36:41 +0800
Subject: [PATCH 11/11] Fix(ipinfo): reset completion flags on whole-grid
 refresh

A whole-grid ipinfo:refresh left fetchStatus set from the previous pass,
so the first card to settle re-emitted ipinfo:finished and resolved the
command early with a mix of fresh and stale cards. Clearing the flags at
the top of checkAllIPs makes the snapshot wait for every card again.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 frontend/components/IpInfos.vue | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/frontend/components/IpInfos.vue b/frontend/components/IpInfos.vue
index 18943d19d..52f7656ce 100644
--- a/frontend/components/IpInfos.vue
+++ b/frontend/components/IpInfos.vue
@@ -272,6 +272,10 @@ const trackFetchStatus = (status) => {
 // allSettled so one card can't sink the batch (fetchIP already swallows per-card
 // errors — this is belt-and-suspenders). Cards paint independently as they land.
 const checkAllIPs = async () => {
+  // A whole-grid pass means no card is settled: clear the completion flags so
+  // ipinfo:finished (and the ipinfo:refresh command riding on it) waits for
+  // every card to land again, instead of re-firing on the first one.
+  fetchStatus.splice(0);
   const ipSources = [
     [0, getIPFromIPChecking4],
     [1, getIPFromIPChecking6],