perf: reduce initial explorer bundles

[paulbalaji]

Summary

This PR makes the explorer do much less on the hot path.

The main idea is to split:

• metadata/read-only work needed to render search and the basic detail shell
• provider/runtime work only needed for PI lookup, delivery/debug inspection, collateral checks, chain-config modal paths, and other heavy follow-up flows

That lets the home page and the first detail paint load a much smaller shell up front, then progressively pull in heavier code only when needed.

What changed

1. Split metadata-only state from provider-backed runtime state

• added metadataStore.ts for registry metadata, overrides, scraped domains, banner state, and lazily built warp-route maps
• kept store.ts focused on syncing MultiProtocolProvider from that metadata when runtime/provider features are actually needed
• added ChainMetadataResolver plus metadata-only helpers so read-only UI no longer needs MultiProtocolProvider

2. Turn home/detail into staged client shells

• home now loads through MessageSearchPage
• detail now loads through MessageDetailsPage -> MessageDetailsInner -> MessageDetailsRuntime
• _app shows route-shaped loading shells during the SSR-to-hydration gap instead of a blank body
• hot secondary cards and follow-up flows now load on demand instead of landing in the default detail shell

3. Warm up detail navigation

• message table row intent (hover, focus, touch, click) now prefetches the detail route, a stub cache entry, and full detail data when safe
• detail pages consume prefetched stub/details before GraphQL/runtime follow-up work
• home also idly preloads the detail shell

4. Move metadata and warp-route work off startup

• chain metadata loading/validation moved into loadChainMetadata.ts
• warp-route maps now load lazily instead of during initial app startup
• request dedupe was hardened so registry/override changes do not let stale in-flight work repopulate caches

5. Tighten message-page SSR / OG behavior

• /message/[messageId] only fetches OG-specific data for bot requests
• detail HTML is marked private, no-store to avoid bot/human cache poisoning
• message pages keep a stable local error boundary through first paint

6. Review-driven correctness follow-ups included here

• delivery-status fetching is lazy-loaded and keyed off stable message inputs
• detail pages only skip GraphQL when the incoming message already has the full detail shape
• metadata resolver semantics are now explicit: numeric lookups follow SDK domain-id behavior; numeric strings remain the chain-id-string convenience path
• explorer URL helpers now fail closed on malformed explorer metadata
• several small cleanup/dedupe changes landed while addressing review comments

Why

Before this PR, the explorer still paid heavy JS/startup cost on both home and detail routes, and detail navigation still felt rough:

• too much provider/debugger/warp-route work landed on the initial path
• first paint could be blank/jarring before hydration
• clicking a message could still feel cold, then rehydrate through a large default detail bundle
• bot-specific OG handling and some lazy/dedupe paths needed hardening

This PR attacks that by keeping the initial path lightweight, then staging enrichment only after the user has already landed on useful UI.

Measured impact

Latest successful measurement on this branch:

Metric	Before	Current
Shared first-load JS	7.61 MB	132 kB
/	8.86 MB	121 kB
/message/[messageId]	8.82 MB	350 kB

User-visible result:

• home first paint shows a real search/table skeleton instead of a blank shell
• detail navigation is warmer from route/data prefetching
• first detail paint shows the base shell immediately, then upgrades progressively
• remaining heavy cost is concentrated in runtime enrichment, not in the default shell

Validation

• pnpm run lint
• pnpm run typecheck
• pnpm run test -- metadataManager.test.ts
• prior successful NEXT_TELEMETRY_DISABLED=1 pnpm run build on this branch for bundle measurements

Remaining work

• the biggest remaining async cost is still PI/provider/debugger/collateral runtime work
• next high-leverage follow-up is to shrink that stack itself, not just move it later

---

Note

^{Cursor Bugbot is generating a summary for commit 5fdd2ff. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperlane-explorer	Ready	Preview, Comment	Mar 27, 2026 4:34pm

[Xaroz]

another round of review, but overall looks good, my biggest concern probably is still that we are building basically a mini-multiprovider/chain manager, so if any changes happen in the SDK we might need to update here too

[paulbalaji]

Replying to the high-level concern about us growing a mini multiprovider / chain manager here: agreed this is a real maintenance risk if it calcifies. The intent with this PR is more of a bridge for the current perf split than a permanent second implementation.

We are already upstreaming the relevant pieces of this path-splitting work in:

• perf: expose lighter sdk/widgets package surfaces hyperlane-monorepo#8433
• perf: narrow runtime/bootstrap loading in warp ui hyperlane-warp-ui-template#1030

And there is already a concrete follow-on example of consuming those extracted SDK primitives in Explorer here:

• perf: keep explorer metadata-first and evm-only at runtime #301

So the plan is to move the shared read-only / lightweight metadata path into the upstream libs/templates, then simplify Explorer back around those shared primitives afterwards rather than permanently owning an Explorer-only mini chain manager.

[Xaroz]

@claude final review

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

There are 12 total unresolved issues (including 10 from previous reviews).

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}