Polish explorer frontend validation and utility pages

docs/EXPLORER_API_ACCESS.md

@@ -28,6 +28,19 @@ Why:
 - Setting `NEXT_PUBLIC_API_URL=https://explorer.d-bis.org/api` will incorrectly produce requests like `/api/api/v2/*`.
 - Token aggregation remains under `/token-aggregation/api/v1/*` and is linked separately by the frontend.
 
+### Local frontend validation
+
+From `frontend/`, the current local validation flow is:
+
+```bash
+npm run build:check
+BASE_URL=http://127.0.0.1:3000 npm run smoke:routes
+```
+
+- `build:check` runs lint, type-check, and a production build.
+- `smoke:routes` performs a lightweight route and content sweep against a running frontend instance.
+- `npm run dev` now binds to `127.0.0.1` by default, but still honors `HOST` and `PORT` overrides.
+
 ---
 
 ## CSP blocks eval / “script-src blocked”

frontend/package.json

@@ -4,9 +4,10 @@
   "private": true,
   "packageManager": "pnpm@10.0.0",
   "scripts": {
-    "dev": "next dev",
+    "dev": "sh -c 'HOST=${HOST:-127.0.0.1}; PORT=${PORT:-3000}; next dev -H \"$HOST\" -p \"$PORT\"'",
     "build": "next build",
     "build:check": "npm run lint && npm run type-check && npm run build",
+    "smoke:routes": "node ./scripts/smoke-routes.mjs",
     "start": "PORT=${PORT:-3000} node .next/standalone/server.js",
     "start:next": "next start",
     "lint": "next lint",

frontend/scripts/smoke-routes.mjs

@@ -0,0 +1,64 @@
+const baseUrl = (process.env.BASE_URL || 'http://127.0.0.1:3000').replace(/\/$/, '')
+
+const checks = [
+  { path: '/', expect: ['/addresses', '/transactions', '/watchlist', '/pools'] },
+  { path: '/blocks', expect: ['Latest Blocks', 'View blockchain blocks', 'Blocks'] },
+  { path: '/transactions', expect: ['Latest Transactions', 'Recent Transactions', 'Transactions'] },
+  { path: '/addresses', expect: ['Open An Address', 'Recently Active Addresses', 'Saved Watchlist'] },
+  { path: '/tokens', expect: ['Find A Token', 'Common token searches', 'Tokens'] },
+  { path: '/pools', expect: ['Canonical PMM routes', 'Pool operation shortcuts', 'Pools'] },
+  { path: '/watchlist', expect: ['Saved Addresses', 'Watchlist', 'Export JSON'] },
+  { path: '/search?q=cUSDT', expect: ['Search Results', 'Results for', 'Search'] },
+  { path: '/blocks/1', expect: ['Loading block details', 'Block Details'] },
+  {
+    path: '/transactions/0x0000000000000000000000000000000000000000000000000000000000000000',
+    expect: ['Loading transaction details', 'Transaction Details', 'Transaction not found'],
+  },
+  {
+    path: '/addresses/0x0000000000000000000000000000000000000000',
+    expect: ['Loading address details', 'Address Details', 'Open An Address'],
+  },
+]
+
+function hasExpectedBody(text, expectedSnippets) {
+  return expectedSnippets.some((snippet) => text.includes(snippet))
+}
+
+async function run() {
+  let failures = 0
+
+  for (const check of checks) {
+    const url = `${baseUrl}${check.path}`
+
+    try {
+      const response = await fetch(url, { redirect: 'follow' })
+      const body = await response.text()
+
+      if (!response.ok) {
+        console.error(`FAIL ${check.path}: HTTP ${response.status}`)
+        failures += 1
+        continue
+      }
+
+      if (!hasExpectedBody(body, check.expect)) {
+        console.error(`FAIL ${check.path}: expected one of ${check.expect.join(' | ')}`)
+        failures += 1
+        continue
+      }
+
+      console.log(`OK   ${check.path}`)
+    } catch (error) {
+      console.error(`FAIL ${check.path}: ${error instanceof Error ? error.message : String(error)}`)
+      failures += 1
+    }
+  }
+
+  if (failures > 0) {
+    process.exitCode = 1
+    return
+  }
+
+  console.log(`All ${checks.length} route checks passed for ${baseUrl}`)
+}
+
+run()

frontend/src/components/common/Navbar.tsx

@@ -63,7 +63,7 @@ function DropdownItem({
   if (external) {
     return (
       <li role="none">
-        <a href={href} className={className} role="menuitem">
+        <a href={href} className={className} role="menuitem" target="_blank" rel="noopener noreferrer">
           {icon}
           <span>{children}</span>
         </a>

frontend/src/pages/pools/index.tsx

@@ -5,7 +5,7 @@ import { Card } from '@/libs/frontend-ui-primitives'
 
 const poolCards = [
   {
-    title: 'Canonical PMM Matrix',
+    title: 'Canonical PMM routes',
     description: 'Review the public Chain 138 DODO PMM route matrix, live pool freshness, and payload examples.',
     href: '/liquidity',
     label: 'Open liquidity access',
@@ -25,6 +25,24 @@ const poolCards = [
   },
 ]
 
+const shortcutCards = [
+  {
+    title: 'cUSDT / USDT',
+    description: 'Open the canonical direct stable route coverage and compare the live pool snapshot.',
+    href: '/liquidity',
+  },
+  {
+    title: 'cUSDC / USDC',
+    description: 'Check the public stable bridge route and inspect the live reserves block.',
+    href: '/liquidity',
+  },
+  {
+    title: 'cUSDT / cXAUC',
+    description: 'Review one of the live gold-backed route families from the liquidity access page.',
+    href: '/liquidity',
+  },
+]
+
 export default function PoolsPage() {
   return (
     <div className="container mx-auto px-4 py-8">
@@ -48,6 +66,23 @@ export default function PoolsPage() {
           </Card>
         ))}
       </div>
+
+      <div className="mt-8">
+        <Card title="Pool operation shortcuts">
+          <div className="grid gap-4 md:grid-cols-3">
+            {shortcutCards.map((card) => (
+              <Link
+                key={card.title}
+                href={card.href}
+                className="rounded-lg border border-gray-200 p-4 transition hover:border-primary-400 hover:shadow-sm dark:border-gray-700"
+              >
+                <div className="text-sm font-semibold text-gray-900 dark:text-white">{card.title}</div>
+                <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">{card.description}</p>
+              </Link>
+            ))}
+          </div>
+        </Card>
+      </div>
     </div>
   )
 }

frontend/src/pages/tokens/index.tsx

@@ -5,6 +5,15 @@ import { useRouter } from 'next/router'
 import { useState } from 'react'
 import { Card } from '@/libs/frontend-ui-primitives'
 
+const quickSearches = [
+  { label: 'cUSDT', description: 'Canonical bridged USDT liquidity and address results.' },
+  { label: 'cUSDC', description: 'Canonical bridged USDC routes and address coverage.' },
+  { label: 'cXAUC', description: 'Gold-backed cXAUC pools and token references.' },
+  { label: 'cXAUT', description: 'Gold-backed cXAUT references and search coverage.' },
+  { label: 'cEURT', description: 'EUR liquidity and cXAUC-connected route coverage.' },
+  { label: 'USDT', description: 'Native-side USDT routes and address discovery.' },
+]
+
 function normalizeAddress(value: string) {
   const trimmed = value.trim()
   return /^0x[a-fA-F0-9]{40}$/.test(trimmed) ? trimmed : ''
@@ -75,6 +84,23 @@ export default function TokensPage() {
           </div>
         </Card>
       </div>
+
+      <div className="mt-8">
+        <Card title="Common token searches">
+          <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-3">
+            {quickSearches.map((token) => (
+              <Link
+                key={token.label}
+                href={`/search?q=${encodeURIComponent(token.label)}`}
+                className="rounded-lg border border-gray-200 p-4 transition hover:border-primary-400 hover:shadow-sm dark:border-gray-700"
+              >
+                <div className="text-sm font-semibold text-gray-900 dark:text-white">{token.label}</div>
+                <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">{token.description}</p>
+              </Link>
+            ))}
+          </div>
+        </Card>
+      </div>
     </div>
   )
 }

frontend/src/pages/watchlist/index.tsx

@@ -27,15 +27,72 @@ export default function WatchlistPage() {
     })
   }
 
+  const exportWatchlist = () => {
+    try {
+      const blob = new Blob([JSON.stringify(entries, null, 2)], { type: 'application/json' })
+      const url = URL.createObjectURL(blob)
+      const anchor = document.createElement('a')
+      anchor.href = url
+      anchor.download = 'explorer-watchlist.json'
+      anchor.click()
+      URL.revokeObjectURL(url)
+    } catch {}
+  }
+
+  const importWatchlist = (event: React.ChangeEvent<HTMLInputElement>) => {
+    const file = event.target.files?.[0]
+    if (!file) return
+
+    file.text().then((text) => {
+      try {
+        const parsed = JSON.parse(text)
+        const next = Array.isArray(parsed)
+          ? parsed.filter((entry): entry is string => typeof entry === 'string')
+          : []
+        setEntries(next)
+        window.localStorage.setItem('explorerWatchlist', JSON.stringify(next))
+      } catch {}
+    }).catch(() => {})
+
+    event.target.value = ''
+  }
+
   return (
     <div className="container mx-auto px-4 py-8">
       <h1 className="text-3xl font-bold mb-6">Watchlist</h1>
 
       <Card title="Saved Addresses">
-        {entries.length === 0 ? (
+        <div className="mb-4 flex flex-col gap-3 md:flex-row md:items-center md:justify-between">
           <p className="text-sm text-gray-600 dark:text-gray-400">
-            Your watchlist is empty. Add an address from its detail page to keep it here.
+            {entries.length === 0 ? 'No saved entries yet.' : `${entries.length} saved ${entries.length === 1 ? 'address' : 'addresses'}.`}
           </p>
+          <div className="flex flex-wrap gap-2">
+            <label className="cursor-pointer rounded-lg bg-gray-100 px-3 py-1.5 text-sm text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700">
+              Import JSON
+              <input type="file" accept="application/json" className="hidden" onChange={importWatchlist} />
+            </label>
+            <button
+              type="button"
+              onClick={exportWatchlist}
+              disabled={entries.length === 0}
+              className="rounded-lg bg-primary-600 px-3 py-1.5 text-sm text-white hover:bg-primary-700 disabled:opacity-50"
+            >
+              Export JSON
+            </button>
+          </div>
+        </div>
+        {entries.length === 0 ? (
+          <div className="space-y-3 text-sm text-gray-600 dark:text-gray-400">
+            <p>Your watchlist is empty. Add an address from its detail page to keep it here.</p>
+            <div className="flex flex-wrap gap-3">
+              <Link href="/addresses" className="text-primary-600 hover:underline">
+                Browse addresses →
+              </Link>
+              <Link href="/search" className="text-primary-600 hover:underline">
+                Search the explorer →
+              </Link>
+            </div>
+          </div>
         ) : (
           <div className="space-y-3">
             {entries.map((entry) => (