feat(route-explorer): Sprint 2 — modal shell + URL state + keyboard system (#2982)

* feat(supply-chain): Sprint 1 — Route Explorer wrapper RPC

Adds an internal wrapper around the vendor-only route-intelligence
compute so the upcoming Route Explorer UI can call it from a browser
PRO session instead of forcing an X-WorldMonitor-Key API gate.

Backend:
- New proto get-route-explorer-lane.proto with GetRouteExplorerLane{Request,Response}
- New handler server/worldmonitor/supply-chain/v1/get-route-explorer-lane.ts
- New static lookup tables _route-explorer-static-tables.ts:
  TRANSIT_DAYS_BY_ROUTE_ID, FREIGHT_USD_BY_CARGO_TYPE,
  BYPASS_CORRIDOR_GEOMETRY_BY_ID — covers all 5 land-bridge corridors
  plus every sea-alternative corridor with hand-curated coordinates
- Wired into supply-chain handler.ts service dispatcher
- Cache key ROUTE_EXPLORER_LANE_KEY in cache-keys.ts (NOT in BOOTSTRAP_KEYS)
- Gateway entry: PREMIUM_RPC_PATHS + RPC_CACHE_TIER 'slow-browser'
- Premium path entry in src/shared/premium-paths.ts so browser PRO auth attaches

Response contract enriches route-intelligence with:
- primaryRouteGeometry polyline from TRADE_ROUTES (lon/lat pairs)
- fromPort/toPort coords on every bypass option so the client can call
  MapContainer.setBypassRoutes directly without geometry lookups
- status: 'active' | 'proposed' | 'unavailable' derived from corridor notes
  to honestly label kra_canal_future and black_sea_western_ports
- estTransitDaysRange + estFreightUsdPerTeuRange from static tables
- noModeledLane: true when origin/destination clusters share no routes

Client wrapper fetchRouteExplorerLane added to src/services/supply-chain/index.ts.

Tests: tests/route-explorer-lane.test.mts — 30-query smoke matrix
(10 country pairs × 3 HS2 codes), structural assertions only, no
hard-coded transit/cost values. Test exposes a pure computeLane()
function with an injectable status map so it does not need Redis.

Gap report (from smoke run): 12 of 30 queries fall back to a synthetic
primaryRouteId because the destination's port cluster has no shared route
with the origin (US-JP, ZA-IN, CL-CN, TR-DE × 3 HS2 each). These pairs
return noModeledLane:true; Sprint 3 will render an empty-state for them.

Plan: docs/plans/2026-04-11-001-feat-worldwide-route-explorer-plan.md

* fix(route-explorer): address PR #2980 review findings

P1: bypass warRiskTier was hard-coded to WAR_RISK_TIER_NORMAL, dropping
the live risk signal from chokepoint status. Now derived from the
statusMap via the corridor's primaryChokepointId.

P2: freight fallback in emptyResponse and client-side empty payload used
a cargo-agnostic container range for all cargo types. Removed the ranges
entirely from fallback/noModeledLane responses; they are only present
when the lane is actually modeled.

Suggestion: when noModeledLane is true, the response now returns empty
primaryRouteId, empty geometry, empty exposures, empty bypasses, and
omits transit/freight ranges. Previously it returned plausible-looking
synthetic data from the origin's first route which could mislead the UI.

Tests updated to assert the noModeledLane contract: empty fields when
the flag is set, non-empty ranges only when the lane is modeled.

* fix(route-explorer): cargo-aware route ranking + bypass waypoint risk

P1: primary route selection was order-dependent, picking whichever
shared route the origin cluster listed first. Mixed clusters like
CN/JP could return an energy lane for a container request. Now ranks
shared routes by cargo-category compatibility (container→container,
tanker→energy, bulk→bulk, roro→container) before selecting.

P1: bypass warRiskTier was copied from the primary chokepoint instead
of derived from the corridor's own waypointChokepointIds. This
overstated risk for alternatives like Cape of Good Hope whose waypoints
may have a lower risk tier. Now uses max-tier across waypoint
chokepoints, matching get-bypass-options.ts logic.

Suggestion: placeholder corridors with addedTransitDays=0 (like
gibraltar_no_bypass, cape_of_good_hope_is_bypass) are now filtered out.
Previously they could surface as active alternatives.

Regression tests added:
- CN→JP tanker: asserts energy route is selected over container route
- CN→DE with faked Suez=CRITICAL / Cape=NORMAL: asserts Cape bypass
  shows NORMAL, not CRITICAL
- ES→EG: asserts zero-transit-day placeholders are excluded

* fix(route-explorer): scope exposures to primary route + narrow placeholder filter

P1: chokepointExposures and bypassOptions were computed from the full
sharedRoutes set, mixing data from energy/container corridors into a
single response. Now scoped to the cargo-ranked primaryRouteId only,
matching the proto contract that exposures are "on the primary route."

P2: the addedTransitDays === 0 filter was too broad and removed
kra_canal_future (a proposed bypass with real modeling). Narrowed to an
explicit PLACEHOLDER_CORRIDOR_IDS set (gibraltar_no_bypass,
cape_of_good_hope_is_bypass) so proposed zero-day corridors survive and
are surfaced with CORRIDOR_STATUS_PROPOSED.

Regression tests:
- chokepointExposures follow primaryRouteId (CN->JP container)
- kra_canal_future appears as CORRIDOR_STATUS_PROPOSED for Malacca routes
- placeholder filter still excludes explicit placeholders

* fix(route-explorer): address PR #2980 review comments

1. Unavailable corridors without waypoints (e.g. black_sea_western_ports)
   now derive WAR_RISK_TIER_WAR_ZONE from their CORRIDOR_STATUS_UNAVAILABLE
   status, instead of returning WAR_RISK_TIER_UNSPECIFIED. Corridors with
   waypointChokepointIds still use max-tier across those waypoints.

2. Added fixture test with non-empty status map (suez=75/HIGH,
   malacca=30/ELEVATED) so disruptionScore and warRiskTier assertions are
   not trivially satisfied by the empty-map default path.

3. Documented the single-chokepoint bypass design gap in the test gap report:
   bypassOptions only cover the primary chokepoint; multi-chokepoint routes
   show exposure for all but bypass guidance for only the top one. Sprint 3
   will decide whether to expand to top-N or add a UI hint.

* feat(route-explorer): Sprint 2 — modal shell + URL state + keyboard system

Adds the standalone Route Explorer modal as a CMD+K command. Sprint 2
ships the SHELL only — no API calls yet, tab panels render placeholders.
Sprint 3 will wire the tabs to get-route-explorer-lane.

Components (src/components/RouteExplorer/):
- url-state.ts: parse / serialize / writeExplorerUrl with silent fallback
  on invalid values. Format: ?explorer=from:CN,to:DE,hs:85,cargo:container,tab:1
- RouteExplorer.utils.ts: getAllCountries (197 port-clustered ISO2s with
  Intl.DisplayNames + flag emoji), getAllHs2 (~50 sectors), filter helpers,
  inferCargoFromHs2 mapping
- CountryPicker.ts: keyboard-first typeahead, ↑/↓/Enter/Esc, max 50 results
- Hs2Picker.ts: same pattern over HS2 chapters
- CargoTypeDropdown.ts: native select with auto-infer indicator badge
- KeyboardHelp.ts: ? cheat-sheet overlay
- RouteExplorer.ts: full-screen modal with focus trap. State synced to URL
  via history.replaceState. Singleton via getRouteExplorer(). DEV-only
  __routeExplorerTestHook installed for E2E in Sprint 6

Keyboard model:
- Esc: close picker, then close modal
- Tab/Shift+Tab: focus trap inside modal
- F/T/P: jump to From/To/Product picker (scoped to modal+non-text-input)
- S: swap From ↔ To
- 1-4: switch tabs (Current/Alternatives/Land/Impact)
- ?: open KeyboardHelp overlay
- Cmd+, / Ctrl+,: copy share URL to clipboard

Single-letter bindings check document.activeElement and ignore the keystroke
when an input/textarea/contenteditable is focused, so they don't collide
with picker typeahead.

CMD+K integration:
- src/config/commands.ts: new view:route-explorer entry with category 'view',
  ship-wheel icon, label 'Route Explorer — plan a shipment'
- src/app/search-manager.ts: handleCommand 'view' branch lazy-imports
  RouteExplorer module and calls .open() on the singleton

Tests (tests/route-explorer-*.test.mts):
- url-state: 19 cases — parse, serialize, roundtrip, invalid-value fallback
- pickers: 17 cases — country list shape + sort, filter behavior, HS2 list,
  cargo inference for HS 27/10/12/26/87/89/85
- keyboard: 3 module-surface smoke tests (full focus-trap behavior is
  exercised by Sprint 6 Playwright E2E since it needs a real DOM)

Known follow-up: tab panels are placeholders. Sprint 3 wires them to the
RPC and adds the left-rail summary card.

Plan: docs/plans/2026-04-11-001-feat-worldwide-route-explorer-plan.md
Stack: depends on PR #2980 (Sprint 1 wrapper RPC)

* fix(route-explorer): address PR #2982 review findings

P1: wire onCancel on CountryPicker and Hs2Picker so Esc inside a
focused picker blurs the input first, allowing the modal-level Esc
handler to fire on the next press. Previously Esc was a no-op inside
pickers because the modal handler returned early for focused inputs.

P2: include SELECT in the form-control guard (renamed from
isTextInputFocused to isFormControlFocused). The cargo dropdown is a
native select whose keyboard interaction was hijacked by single-letter
shortcuts (F/T/P/S/1-4). Now the guard exempts all form controls with
native keyboard behavior.

Suggestion: reset helpOverlay in close() so the ? overlay can reopen
cleanly on the next modal open. Previously a stale reference prevented
reopening.

src/app/search-manager.ts

@@ -539,6 +539,10 @@ export class SearchManager implements AppModule {
           } else {
             this.ctx.map?.setLayers(this.ctx.mapLayers);
           }
+        } else if (action === 'route-explorer') {
+          void import('@/components/RouteExplorer/RouteExplorer').then((m) => {
+            m.getRouteExplorer().open();
+          });
         }
         break;
 

src/components/RouteExplorer/CargoTypeDropdown.ts

@@ -0,0 +1,61 @@
+/**
+ * Cargo type dropdown with auto-infer indicator. The user can override the
+ * auto-inferred value at any time.
+ */
+
+import type { ExplorerCargo } from './RouteExplorer.utils';
+
+export interface CargoTypeDropdownOptions {
+  initialCargo?: ExplorerCargo | null;
+  initialAutoInferred?: boolean;
+  onChange: (cargo: ExplorerCargo, manual: boolean) => void;
+}
+
+const CARGO_LABELS: Record<ExplorerCargo, string> = {
+  container: 'Container',
+  tanker: 'Tanker',
+  bulk: 'Bulk',
+  roro: 'RoRo',
+};
+
+export class CargoTypeDropdown {
+  public readonly element: HTMLDivElement;
+  private select: HTMLSelectElement;
+  private autoBadge: HTMLSpanElement;
+
+  constructor(opts: CargoTypeDropdownOptions) {
+    this.element = document.createElement('div');
+    this.element.className = 're-cargo';
+
+    this.select = document.createElement('select');
+    this.select.className = 're-cargo__select';
+    this.select.setAttribute('aria-label', 'Cargo type');
+    for (const [value, label] of Object.entries(CARGO_LABELS) as Array<
+      [ExplorerCargo, string]
+    >) {
+      const opt = document.createElement('option');
+      opt.value = value;
+      opt.textContent = label;
+      this.select.append(opt);
+    }
+    if (opts.initialCargo) this.select.value = opts.initialCargo;
+
+    this.autoBadge = document.createElement('span');
+    this.autoBadge.className = 're-cargo__auto';
+    this.autoBadge.textContent = 'auto';
+    this.autoBadge.title = 'Inferred from selected product';
+    if (!opts.initialAutoInferred) this.autoBadge.style.display = 'none';
+
+    this.element.append(this.select, this.autoBadge);
+
+    this.select.addEventListener('change', () => {
+      this.autoBadge.style.display = 'none';
+      opts.onChange(this.select.value as ExplorerCargo, true);
+    });
+  }
+
+  public setAutoInferred(cargo: ExplorerCargo): void {
+    this.select.value = cargo;
+    this.autoBadge.style.display = '';
+  }
+}

src/components/RouteExplorer/CountryPicker.ts

@@ -0,0 +1,148 @@
+/**
+ * Search-first country typeahead for the Route Explorer query bar.
+ * Keyboard-first: ↑/↓ to move, Enter to commit, Esc to close.
+ */
+
+import { filterCountries, getAllCountries, type CountryListEntry } from './RouteExplorer.utils';
+
+export interface CountryPickerOptions {
+  placeholder?: string;
+  initialIso2?: string | null;
+  /** Fired when the user commits a selection (Enter or click). */
+  onCommit: (iso2: string) => void;
+  /** Fired when the user presses Esc inside the picker. */
+  onCancel?: () => void;
+}
+
+export class CountryPicker {
+  public readonly element: HTMLDivElement;
+  private input: HTMLInputElement;
+  private list: HTMLUListElement;
+  private results: CountryListEntry[] = [];
+  private highlightIndex = 0;
+  private opts: CountryPickerOptions;
+
+  constructor(opts: CountryPickerOptions) {
+    this.opts = opts;
+    this.element = document.createElement('div');
+    this.element.className = 're-picker re-picker--country';
+
+    this.input = document.createElement('input');
+    this.input.type = 'text';
+    this.input.className = 're-picker__input';
+    this.input.placeholder = opts.placeholder ?? 'Search countries';
+    this.input.autocomplete = 'off';
+    this.input.spellcheck = false;
+    this.input.setAttribute('aria-label', opts.placeholder ?? 'Search countries');
+
+    this.list = document.createElement('ul');
+    this.list.className = 're-picker__list';
+    this.list.setAttribute('role', 'listbox');
+
+    this.element.append(this.input, this.list);
+
+    if (opts.initialIso2) {
+      const initial = getAllCountries().find((c) => c.iso2 === opts.initialIso2);
+      if (initial) this.input.value = initial.name;
+    }
+
+    this.refreshResults('');
+    this.input.addEventListener('input', () => this.refreshResults(this.input.value));
+    this.input.addEventListener('keydown', this.handleKeydown);
+    this.list.addEventListener('click', this.handleClick);
+  }
+
+  public focusInput(): void {
+    this.input.focus();
+    this.input.select();
+  }
+
+  public setValue(iso2: string | null): void {
+    if (!iso2) {
+      this.input.value = '';
+      this.refreshResults('');
+      return;
+    }
+    const c = getAllCountries().find((x) => x.iso2 === iso2);
+    if (c) {
+      this.input.value = c.name;
+      this.refreshResults('');
+    }
+  }
+
+  private refreshResults(query: string): void {
+    this.results = filterCountries(query).slice(0, 50);
+    this.highlightIndex = 0;
+    this.renderList();
+  }
+
+  private renderList(): void {
+    this.list.innerHTML = '';
+    if (this.results.length === 0) {
+      const empty = document.createElement('li');
+      empty.className = 're-picker__empty';
+      empty.textContent = 'No matching countries';
+      this.list.append(empty);
+      return;
+    }
+    this.results.forEach((entry, idx) => {
+      const li = document.createElement('li');
+      li.className = 're-picker__item';
+      li.setAttribute('role', 'option');
+      li.dataset.iso2 = entry.iso2;
+      li.dataset.idx = String(idx);
+      if (idx === this.highlightIndex) {
+        li.classList.add('re-picker__item--active');
+        li.setAttribute('aria-selected', 'true');
+      }
+      li.innerHTML = `<span class="re-picker__flag">${entry.flag}</span><span class="re-picker__name">${escapeHtml(entry.name)}</span><span class="re-picker__code">${entry.iso2}</span>`;
+      this.list.append(li);
+    });
+  }
+
+  private commit(idx: number): void {
+    const entry = this.results[idx];
+    if (!entry) return;
+    this.input.value = entry.name;
+    this.opts.onCommit(entry.iso2);
+  }
+
+  private handleKeydown = (e: KeyboardEvent): void => {
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      this.highlightIndex = Math.min(this.highlightIndex + 1, this.results.length - 1);
+      this.renderList();
+      return;
+    }
+    if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      this.highlightIndex = Math.max(this.highlightIndex - 1, 0);
+      this.renderList();
+      return;
+    }
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      this.commit(this.highlightIndex);
+      return;
+    }
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      this.opts.onCancel?.();
+      return;
+    }
+  };
+
+  private handleClick = (e: MouseEvent): void => {
+    const target = e.target as HTMLElement;
+    const item = target.closest('.re-picker__item') as HTMLElement | null;
+    if (!item || item.dataset.idx === undefined) return;
+    const idx = Number.parseInt(item.dataset.idx, 10);
+    this.commit(idx);
+  };
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) =>
+    c === '&' ? '&amp;' : c === '<' ? '&lt;' : c === '>' ? '&gt;' : c === '"' ? '&quot;' : '&#39;',
+  );
+}

src/components/RouteExplorer/Hs2Picker.ts

@@ -0,0 +1,145 @@
+/**
+ * HS2 product chapter typeahead picker. Same keyboard model as CountryPicker.
+ */
+
+import { filterHs2, getAllHs2, type Hs2Entry } from './RouteExplorer.utils';
+
+export interface Hs2PickerOptions {
+  placeholder?: string;
+  initialHs2?: string | null;
+  onCommit: (hs2: string) => void;
+  onCancel?: () => void;
+}
+
+export class Hs2Picker {
+  public readonly element: HTMLDivElement;
+  private input: HTMLInputElement;
+  private list: HTMLUListElement;
+  private results: Hs2Entry[] = [];
+  private highlightIndex = 0;
+  private opts: Hs2PickerOptions;
+
+  constructor(opts: Hs2PickerOptions) {
+    this.opts = opts;
+    this.element = document.createElement('div');
+    this.element.className = 're-picker re-picker--hs2';
+
+    this.input = document.createElement('input');
+    this.input.type = 'text';
+    this.input.className = 're-picker__input';
+    this.input.placeholder = opts.placeholder ?? 'Search products (HS code)';
+    this.input.autocomplete = 'off';
+    this.input.spellcheck = false;
+    this.input.setAttribute('aria-label', opts.placeholder ?? 'Search products');
+
+    this.list = document.createElement('ul');
+    this.list.className = 're-picker__list';
+    this.list.setAttribute('role', 'listbox');
+
+    this.element.append(this.input, this.list);
+
+    if (opts.initialHs2) {
+      const initial = getAllHs2().find((e) => e.hs2 === opts.initialHs2);
+      if (initial) this.input.value = `${initial.label} (HS ${initial.hs2})`;
+    }
+
+    this.refreshResults('');
+    this.input.addEventListener('input', () => this.refreshResults(this.input.value));
+    this.input.addEventListener('keydown', this.handleKeydown);
+    this.list.addEventListener('click', this.handleClick);
+  }
+
+  public focusInput(): void {
+    this.input.focus();
+    this.input.select();
+  }
+
+  public setValue(hs2: string | null): void {
+    if (!hs2) {
+      this.input.value = '';
+      this.refreshResults('');
+      return;
+    }
+    const e = getAllHs2().find((x) => x.hs2 === hs2);
+    if (e) {
+      this.input.value = `${e.label} (HS ${e.hs2})`;
+      this.refreshResults('');
+    }
+  }
+
+  private refreshResults(query: string): void {
+    this.results = filterHs2(query).slice(0, 50);
+    this.highlightIndex = 0;
+    this.renderList();
+  }
+
+  private renderList(): void {
+    this.list.innerHTML = '';
+    if (this.results.length === 0) {
+      const empty = document.createElement('li');
+      empty.className = 're-picker__empty';
+      empty.textContent = 'No matching products';
+      this.list.append(empty);
+      return;
+    }
+    this.results.forEach((entry, idx) => {
+      const li = document.createElement('li');
+      li.className = 're-picker__item';
+      li.setAttribute('role', 'option');
+      li.dataset.hs2 = entry.hs2;
+      li.dataset.idx = String(idx);
+      if (idx === this.highlightIndex) {
+        li.classList.add('re-picker__item--active');
+        li.setAttribute('aria-selected', 'true');
+      }
+      li.innerHTML = `<span class="re-picker__code">HS ${entry.hs2}</span><span class="re-picker__name">${escapeHtml(entry.label)}</span>`;
+      this.list.append(li);
+    });
+  }
+
+  private commit(idx: number): void {
+    const entry = this.results[idx];
+    if (!entry) return;
+    this.input.value = `${entry.label} (HS ${entry.hs2})`;
+    this.opts.onCommit(entry.hs2);
+  }
+
+  private handleKeydown = (e: KeyboardEvent): void => {
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      this.highlightIndex = Math.min(this.highlightIndex + 1, this.results.length - 1);
+      this.renderList();
+      return;
+    }
+    if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      this.highlightIndex = Math.max(this.highlightIndex - 1, 0);
+      this.renderList();
+      return;
+    }
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      this.commit(this.highlightIndex);
+      return;
+    }
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      this.opts.onCancel?.();
+      return;
+    }
+  };
+
+  private handleClick = (e: MouseEvent): void => {
+    const target = e.target as HTMLElement;
+    const item = target.closest('.re-picker__item') as HTMLElement | null;
+    if (!item || item.dataset.idx === undefined) return;
+    const idx = Number.parseInt(item.dataset.idx, 10);
+    this.commit(idx);
+  };
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) =>
+    c === '&' ? '&amp;' : c === '<' ? '&lt;' : c === '>' ? '&gt;' : c === '"' ? '&quot;' : '&#39;',
+  );
+}

src/components/RouteExplorer/KeyboardHelp.ts

@@ -0,0 +1,56 @@
+/**
+ * `?` cheat-sheet overlay for the Route Explorer keyboard bindings.
+ */
+
+export interface KeyboardHelpOptions {
+  onClose: () => void;
+}
+
+const BINDINGS: ReadonlyArray<readonly [string, string]> = [
+  ['Esc', 'Close picker, then close modal'],
+  ['Tab / Shift+Tab', 'Cycle focusable zones'],
+  ['F', 'Jump to From picker'],
+  ['T', 'Jump to To picker'],
+  ['P', 'Jump to Product picker'],
+  ['S', 'Swap From ↔ To'],
+  ['1 – 4', 'Switch tabs (Current / Alternatives / Land / Impact)'],
+  ['↑ / ↓', 'Navigate ranked list'],
+  ['Enter', 'Commit selection'],
+  ['Cmd+,', 'Copy shareable URL'],
+  ['?', 'Show this help'],
+];
+
+export class KeyboardHelp {
+  public readonly element: HTMLDivElement;
+
+  constructor(opts: KeyboardHelpOptions) {
+    this.element = document.createElement('div');
+    this.element.className = 're-help';
+    this.element.setAttribute('role', 'dialog');
+    this.element.setAttribute('aria-label', 'Route Explorer keyboard shortcuts');
+
+    const header = document.createElement('div');
+    header.className = 're-help__header';
+    header.innerHTML =
+      '<span class="re-help__title">Keyboard shortcuts</span>' +
+      '<button class="re-help__close" aria-label="Close help">×</button>';
+
+    const list = document.createElement('table');
+    list.className = 're-help__table';
+    for (const [key, label] of BINDINGS) {
+      const row = document.createElement('tr');
+      row.innerHTML = `<td class="re-help__key"><kbd>${escapeHtml(key)}</kbd></td><td class="re-help__label">${escapeHtml(label)}</td>`;
+      list.append(row);
+    }
+
+    this.element.append(header, list);
+
+    header.querySelector('.re-help__close')?.addEventListener('click', () => opts.onClose());
+  }
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) =>
+    c === '&' ? '&amp;' : c === '<' ? '&lt;' : c === '>' ? '&gt;' : c === '"' ? '&quot;' : '&#39;',
+  );
+}

src/components/RouteExplorer/RouteExplorer.ts

@@ -0,0 +1,485 @@
+/**
+ * RouteExplorer — full-screen modal for the worldwide Route Explorer feature.
+ *
+ * Sprint 2 ships the SHELL only: query bar + tab strip + URL state + keyboard
+ * focus trap. No API calls yet — tab panels render placeholder text. Sprint 3
+ * wires CurrentRouteTab / AlternativesTab / LandTab to the
+ * `get-route-explorer-lane` RPC, and Sprint 4 adds the Impact tab.
+ *
+ * Keyboard model:
+ *   - Esc: close picker, then close modal
+ *   - Tab / Shift+Tab: cycle focusable zones (focus-trapped inside modal)
+ *   - F / T / P: jump to From / To / Product picker
+ *   - S: swap From ↔ To
+ *   - 1–4: switch tabs
+ *   - ?: show keyboard help overlay
+ *   - Cmd+,: copy shareable URL
+ *
+ * Single-letter bindings are scoped to "modal focused AND no text input
+ * focused" so they don't collide with typing into the picker text fields.
+ */
+
+import { CountryPicker } from './CountryPicker';
+import { Hs2Picker } from './Hs2Picker';
+import { CargoTypeDropdown } from './CargoTypeDropdown';
+import { KeyboardHelp } from './KeyboardHelp';
+import {
+  inferCargoFromHs2,
+  type ExplorerCargo,
+} from './RouteExplorer.utils';
+import {
+  parseExplorerUrl,
+  serializeExplorerUrl,
+  writeExplorerUrl,
+  DEFAULT_EXPLORER_STATE,
+  type ExplorerUrlState,
+  type ExplorerTab,
+} from './url-state';
+
+const TAB_LABELS: Record<ExplorerTab, string> = {
+  1: 'Current',
+  2: 'Alternatives',
+  3: 'Land',
+  4: 'Impact',
+};
+
+interface TestHook {
+  lastHighlightedRouteIds?: string[];
+  lastBypassRoutes?: Array<{ fromPort: [number, number]; toPort: [number, number] }>;
+  lastClearHighlight?: number;
+  lastClearBypass?: number;
+}
+
+declare global {
+  interface Window {
+    __routeExplorerTestHook?: TestHook;
+  }
+}
+
+export class RouteExplorer {
+  private root: HTMLDivElement | null = null;
+  private state: ExplorerUrlState;
+  private fromPicker!: CountryPicker;
+  private toPicker!: CountryPicker;
+  private hs2Picker!: Hs2Picker;
+  private cargoDropdown!: CargoTypeDropdown;
+  private tabStrip!: HTMLDivElement;
+  private contentEl!: HTMLDivElement;
+  private leftRailEl!: HTMLElement;
+  private cargoManual = false;
+  private isOpen = false;
+  private previousFocus: HTMLElement | null = null;
+  private helpOverlay: KeyboardHelp | null = null;
+
+  constructor() {
+    this.state = { ...DEFAULT_EXPLORER_STATE };
+    this.installTestHook();
+  }
+
+  // ─── Public API ────────────────────────────────────────────────────────
+
+  public open(): void {
+    if (this.isOpen) {
+      this.fromPicker?.focusInput();
+      return;
+    }
+    this.state = this.readInitialState();
+    this.previousFocus = (document.activeElement as HTMLElement) ?? null;
+    this.root = this.buildRoot();
+    document.body.append(this.root);
+    this.isOpen = true;
+    document.addEventListener('keydown', this.handleGlobalKeydown, { capture: true });
+    this.focusInitial();
+  }
+
+  public close(): void {
+    if (!this.isOpen || !this.root) return;
+    document.removeEventListener('keydown', this.handleGlobalKeydown, { capture: true });
+    this.helpOverlay?.element.remove();
+    this.helpOverlay = null;
+    this.root.remove();
+    this.root = null;
+    this.isOpen = false;
+    if (this.previousFocus && document.body.contains(this.previousFocus)) {
+      this.previousFocus.focus();
+    }
+    this.previousFocus = null;
+  }
+
+  public isOpenNow(): boolean {
+    return this.isOpen;
+  }
+
+  // ─── Initial state from URL ─────────────────────────────────────────────
+
+  private readInitialState(): ExplorerUrlState {
+    if (typeof window === 'undefined') return { ...DEFAULT_EXPLORER_STATE };
+    return parseExplorerUrl(window.location.search);
+  }
+
+  private writeStateToUrl(): void {
+    writeExplorerUrl(this.state);
+  }
+
+  // ─── DOM construction ──────────────────────────────────────────────────
+
+  private buildRoot(): HTMLDivElement {
+    const root = document.createElement('div');
+    root.className = 're-modal';
+    root.setAttribute('role', 'dialog');
+    root.setAttribute('aria-modal', 'true');
+    root.setAttribute('aria-label', 'Route Explorer — plan a shipment');
+
+    const backdrop = document.createElement('div');
+    backdrop.className = 're-modal__backdrop';
+    backdrop.addEventListener('click', () => this.close());
+
+    const surface = document.createElement('div');
+    surface.className = 're-modal__surface';
+
+    surface.append(this.buildQueryBar(), this.buildTabStrip(), this.buildBody());
+
+    root.append(backdrop, surface);
+    return root;
+  }
+
+  private buildQueryBar(): HTMLDivElement {
+    const bar = document.createElement('div');
+    bar.className = 're-querybar';
+
+    const back = document.createElement('button');
+    back.type = 'button';
+    back.className = 're-querybar__back';
+    back.textContent = '← Back';
+    back.setAttribute('aria-label', 'Close Route Explorer');
+    back.addEventListener('click', () => this.close());
+
+    this.fromPicker = new CountryPicker({
+      placeholder: 'From country',
+      initialIso2: this.state.fromIso2,
+      onCommit: (iso2) => this.handleFromCommit(iso2),
+      onCancel: () => this.blurActiveInput(),
+    });
+
+    const arrow = document.createElement('span');
+    arrow.className = 're-querybar__arrow';
+    arrow.textContent = '→';
+    arrow.setAttribute('aria-hidden', 'true');
+
+    this.toPicker = new CountryPicker({
+      placeholder: 'To country',
+      initialIso2: this.state.toIso2,
+      onCommit: (iso2) => this.handleToCommit(iso2),
+      onCancel: () => this.blurActiveInput(),
+    });
+
+    this.hs2Picker = new Hs2Picker({
+      placeholder: 'Pick a product',
+      initialHs2: this.state.hs2,
+      onCommit: (hs2) => this.handleHs2Commit(hs2),
+      onCancel: () => this.blurActiveInput(),
+    });
+
+    const initialCargo = this.state.cargo ?? inferCargoFromHs2(this.state.hs2);
+    this.cargoManual = this.state.cargo !== null;
+    this.cargoDropdown = new CargoTypeDropdown({
+      initialCargo,
+      initialAutoInferred: !this.cargoManual,
+      onChange: (cargo, manual) => this.handleCargoChange(cargo, manual),
+    });
+
+    bar.append(
+      back,
+      this.fromPicker.element,
+      arrow,
+      this.toPicker.element,
+      this.hs2Picker.element,
+      this.cargoDropdown.element,
+    );
+    return bar;
+  }
+
+  private buildTabStrip(): HTMLDivElement {
+    this.tabStrip = document.createElement('div');
+    this.tabStrip.className = 're-tabstrip';
+    this.tabStrip.setAttribute('role', 'tablist');
+    for (const n of [1, 2, 3, 4] as const) {
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.className = 're-tabstrip__tab';
+      button.dataset.tab = String(n);
+      button.setAttribute('role', 'tab');
+      button.setAttribute('aria-selected', n === this.state.tab ? 'true' : 'false');
+      if (n === this.state.tab) button.classList.add('re-tabstrip__tab--active');
+      button.innerHTML = `<span class="re-tabstrip__digit">${n}</span><span class="re-tabstrip__label">${TAB_LABELS[n]}</span>`;
+      button.addEventListener('click', () => this.setTab(n));
+      this.tabStrip.append(button);
+    }
+    return this.tabStrip;
+  }
+
+  private buildBody(): HTMLDivElement {
+    const body = document.createElement('div');
+    body.className = 're-body';
+
+    this.leftRailEl = document.createElement('aside');
+    this.leftRailEl.className = 're-leftrail';
+    this.leftRailEl.setAttribute('aria-label', 'Lane summary');
+    this.leftRailEl.innerHTML =
+      '<div class="re-leftrail__placeholder">Pick a country pair and product to see the lane summary.</div>';
+
+    this.contentEl = document.createElement('div');
+    this.contentEl.className = 're-content';
+    this.renderActiveTab();
+
+    body.append(this.leftRailEl, this.contentEl);
+    return body;
+  }
+
+  // ─── Tab rendering (Sprint 2 placeholders) ──────────────────────────────
+
+  private renderActiveTab(): void {
+    if (!this.contentEl) return;
+    const tab = this.state.tab;
+    const label = TAB_LABELS[tab];
+    this.contentEl.innerHTML = `<div class="re-content__placeholder" data-tab="${tab}"><h2>${label}</h2><p>Sprint 3 wires this tab to the route-explorer-lane RPC. Pick a country pair and product to see the data.</p></div>`;
+  }
+
+  // ─── Event handlers ────────────────────────────────────────────────────
+
+  private handleFromCommit(iso2: string): void {
+    this.state = { ...this.state, fromIso2: iso2 };
+    this.writeStateToUrl();
+    this.fromPicker.setValue(iso2);
+    // Move focus to the next empty slot for keyboard flow.
+    if (!this.state.toIso2) this.toPicker.focusInput();
+    else if (!this.state.hs2) this.hs2Picker.focusInput();
+  }
+
+  private handleToCommit(iso2: string): void {
+    this.state = { ...this.state, toIso2: iso2 };
+    this.writeStateToUrl();
+    this.toPicker.setValue(iso2);
+    if (!this.state.fromIso2) this.fromPicker.focusInput();
+    else if (!this.state.hs2) this.hs2Picker.focusInput();
+  }
+
+  private handleHs2Commit(hs2: string): void {
+    this.state = { ...this.state, hs2 };
+    this.writeStateToUrl();
+    this.hs2Picker.setValue(hs2);
+    if (!this.cargoManual) {
+      const inferred = inferCargoFromHs2(hs2);
+      this.cargoDropdown.setAutoInferred(inferred);
+    }
+  }
+
+  private handleCargoChange(cargo: ExplorerCargo, manual: boolean): void {
+    this.cargoManual = manual;
+    this.state = { ...this.state, cargo };
+    this.writeStateToUrl();
+  }
+
+  private setTab(n: ExplorerTab): void {
+    if (n === this.state.tab) return;
+    this.state = { ...this.state, tab: n };
+    this.writeStateToUrl();
+    if (this.tabStrip) {
+      const buttons = this.tabStrip.querySelectorAll<HTMLButtonElement>('.re-tabstrip__tab');
+      buttons.forEach((b) => {
+        const isActive = Number.parseInt(b.dataset.tab ?? '0', 10) === n;
+        b.classList.toggle('re-tabstrip__tab--active', isActive);
+        b.setAttribute('aria-selected', isActive ? 'true' : 'false');
+      });
+    }
+    this.renderActiveTab();
+  }
+
+  private swapFromTo(): void {
+    const newFrom = this.state.toIso2;
+    const newTo = this.state.fromIso2;
+    this.state = { ...this.state, fromIso2: newFrom, toIso2: newTo };
+    this.writeStateToUrl();
+    this.fromPicker.setValue(newFrom);
+    this.toPicker.setValue(newTo);
+  }
+
+  // ─── Keyboard ──────────────────────────────────────────────────────────
+
+  private isFormControlFocused(): boolean {
+    const el = document.activeElement;
+    if (!el) return false;
+    const tag = el.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return true;
+    if ((el as HTMLElement).isContentEditable) return true;
+    return false;
+  }
+
+  private blurActiveInput(): void {
+    const el = document.activeElement as HTMLElement | null;
+    el?.blur();
+  }
+
+  private handleGlobalKeydown = (e: KeyboardEvent): void => {
+    if (!this.isOpen || !this.root) return;
+
+    // Esc: close help if open, else close picker (let pickers handle), else close modal.
+    if (e.key === 'Escape') {
+      if (this.helpOverlay) {
+        e.preventDefault();
+        e.stopPropagation();
+        this.closeHelp();
+        return;
+      }
+      // If a picker input is focused, let the picker handle Esc first.
+      if (this.isFormControlFocused()) return;
+      e.preventDefault();
+      e.stopPropagation();
+      this.close();
+      return;
+    }
+
+    // Cmd+, / Ctrl+, : copy URL
+    if ((e.metaKey || e.ctrlKey) && e.key === ',') {
+      e.preventDefault();
+      this.copyShareUrl();
+      return;
+    }
+
+    // Tab focus trap
+    if (e.key === 'Tab') {
+      this.handleTabKey(e);
+      return;
+    }
+
+    // Single-letter shortcuts only when no text input is focused
+    if (this.isFormControlFocused()) return;
+    if (e.metaKey || e.ctrlKey || e.altKey) return;
+
+    switch (e.key) {
+      case '1':
+      case '2':
+      case '3':
+      case '4': {
+        e.preventDefault();
+        this.setTab(Number.parseInt(e.key, 10) as ExplorerTab);
+        return;
+      }
+      case 'F':
+      case 'f':
+        e.preventDefault();
+        this.fromPicker.focusInput();
+        return;
+      case 'T':
+      case 't':
+        e.preventDefault();
+        this.toPicker.focusInput();
+        return;
+      case 'P':
+      case 'p':
+        e.preventDefault();
+        this.hs2Picker.focusInput();
+        return;
+      case 'S':
+      case 's':
+        e.preventDefault();
+        this.swapFromTo();
+        return;
+      case '?':
+        e.preventDefault();
+        this.openHelp();
+        return;
+      default:
+        return;
+    }
+  };
+
+  private handleTabKey(e: KeyboardEvent): void {
+    if (!this.root) return;
+    const focusable = this.collectFocusable();
+    if (focusable.length === 0) return;
+    const current = document.activeElement as HTMLElement | null;
+    const idx = current ? focusable.indexOf(current) : -1;
+    let nextIdx: number;
+    if (e.shiftKey) {
+      nextIdx = idx <= 0 ? focusable.length - 1 : idx - 1;
+    } else {
+      nextIdx = idx === -1 || idx >= focusable.length - 1 ? 0 : idx + 1;
+    }
+    const next = focusable[nextIdx];
+    if (!next) return;
+    e.preventDefault();
+    next.focus();
+  }
+
+  private collectFocusable(): HTMLElement[] {
+    if (!this.root) return [];
+    const sel = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+    return Array.from(this.root.querySelectorAll<HTMLElement>(sel)).filter(
+      (el) => !el.hasAttribute('disabled') && el.offsetParent !== null,
+    );
+  }
+
+  private focusInitial(): void {
+    if (!this.state.fromIso2) {
+      this.fromPicker.focusInput();
+    } else if (!this.state.toIso2) {
+      this.toPicker.focusInput();
+    } else if (!this.state.hs2) {
+      this.hs2Picker.focusInput();
+    } else {
+      this.fromPicker.focusInput();
+    }
+  }
+
+  // ─── Help overlay ──────────────────────────────────────────────────────
+
+  private openHelp(): void {
+    if (!this.root || this.helpOverlay) return;
+    this.helpOverlay = new KeyboardHelp({ onClose: () => this.closeHelp() });
+    this.root.append(this.helpOverlay.element);
+  }
+
+  private closeHelp(): void {
+    if (!this.helpOverlay) return;
+    this.helpOverlay.element.remove();
+    this.helpOverlay = null;
+  }
+
+  // ─── Share URL ────────────────────────────────────────────────────────
+
+  private copyShareUrl(): void {
+    if (typeof window === 'undefined') return;
+    const url = new URL(window.location.href);
+    const serialized = serializeExplorerUrl(this.state);
+    if (serialized) url.searchParams.set('explorer', serialized);
+    if (navigator.clipboard?.writeText) {
+      void navigator.clipboard.writeText(url.toString());
+    }
+  }
+
+  // ─── Test hook (DEV builds only) ──────────────────────────────────────
+
+  private installTestHook(): void {
+    if (typeof window === 'undefined') return;
+    // Only install in dev / test builds; production strips this on init.
+    const isDev = (() => {
+      try {
+        return Boolean((import.meta as { env?: { DEV?: boolean } }).env?.DEV);
+      } catch {
+        return false;
+      }
+    })();
+    if (!isDev) return;
+    if (!window.__routeExplorerTestHook) {
+      window.__routeExplorerTestHook = {};
+    }
+  }
+}
+
+/** Singleton instance used by the command palette dispatch. */
+let singleton: RouteExplorer | null = null;
+export function getRouteExplorer(): RouteExplorer {
+  if (!singleton) singleton = new RouteExplorer();
+  return singleton;
+}

src/components/RouteExplorer/RouteExplorer.utils.ts

@@ -0,0 +1,179 @@
+/**
+ * Pure builders + data helpers for the Route Explorer modal.
+ *
+ * Kept in a sibling -utils file so node:test can import it without pulling
+ * in the @/services/i18n dependency chain (per
+ * `feedback_panel_utils_split_for_node_test.md`).
+ */
+
+import COUNTRY_PORT_CLUSTERS from '../../../scripts/shared/country-port-clusters.json';
+import { toFlagEmoji } from '../../utils/country-flag';
+
+// ─── Country list ───────────────────────────────────────────────────────────
+
+const regionNames = (() => {
+  try {
+    return new Intl.DisplayNames(['en'], { type: 'region' });
+  } catch {
+    return null;
+  }
+})();
+
+export interface CountryListEntry {
+  iso2: string;
+  name: string;
+  flag: string;
+  searchKey: string; // lowercase, no diacritics, used for typeahead matching
+}
+
+function isIso2Key(key: string): boolean {
+  return /^[A-Z]{2}$/.test(key);
+}
+
+function normalizeForSearch(s: string): string {
+  return s
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-z0-9 ]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+let cachedCountries: CountryListEntry[] | null = null;
+
+/**
+ * Get all 197 port-clustered countries with display names + flags. Cached.
+ * Sorted alphabetically by display name.
+ */
+export function getAllCountries(): CountryListEntry[] {
+  if (cachedCountries) return cachedCountries;
+  const out: CountryListEntry[] = [];
+  for (const key of Object.keys(COUNTRY_PORT_CLUSTERS as Record<string, unknown>)) {
+    if (!isIso2Key(key)) continue;
+    const name = regionNames?.of(key) ?? key;
+    out.push({
+      iso2: key,
+      name,
+      flag: toFlagEmoji(key),
+      searchKey: `${normalizeForSearch(name)} ${key.toLowerCase()}`,
+    });
+  }
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  cachedCountries = out;
+  return out;
+}
+
+/**
+ * Filter the country list by a typeahead query. Empty query returns the
+ * full list. Matches against display name + ISO2.
+ */
+export function filterCountries(
+  query: string,
+  list: CountryListEntry[] = getAllCountries(),
+): CountryListEntry[] {
+  const q = normalizeForSearch(query);
+  if (!q) return list;
+  return list.filter((c) => c.searchKey.includes(q));
+}
+
+// ─── HS2 list ───────────────────────────────────────────────────────────────
+
+export interface Hs2Entry {
+  hs2: string; // numeric, may be 1 or 2 chars
+  label: string;
+  searchKey: string;
+}
+
+/**
+ * The HS2 sectors the Route Explorer surfaces. Kept in sync with the
+ * server-side `HS2_LABELS` table in get-sector-dependency.ts so users only
+ * see codes the backend can actually compute against.
+ */
+const HS2_LABELS: ReadonlyArray<readonly [string, string]> = [
+  ['1', 'Live Animals'],
+  ['2', 'Meat'],
+  ['3', 'Fish & Seafood'],
+  ['4', 'Dairy'],
+  ['6', 'Plants & Flowers'],
+  ['7', 'Vegetables'],
+  ['8', 'Fruit & Nuts'],
+  ['10', 'Cereals'],
+  ['11', 'Milling Products'],
+  ['12', 'Oilseeds'],
+  ['15', 'Animal & Vegetable Fats'],
+  ['16', 'Meat Preparations'],
+  ['17', 'Sugar'],
+  ['18', 'Cocoa'],
+  ['19', 'Food Preparations'],
+  ['22', 'Beverages & Spirits'],
+  ['23', 'Residues & Animal Feed'],
+  ['24', 'Tobacco'],
+  ['25', 'Salt & Cement'],
+  ['26', 'Ores, Slag & Ash'],
+  ['27', 'Mineral Fuels & Energy'],
+  ['28', 'Inorganic Chemicals'],
+  ['29', 'Organic Chemicals'],
+  ['30', 'Pharmaceuticals'],
+  ['31', 'Fertilizers'],
+  ['38', 'Chemical Products'],
+  ['39', 'Plastics'],
+  ['40', 'Rubber'],
+  ['44', 'Wood'],
+  ['47', 'Pulp & Paper'],
+  ['48', 'Paper & Paperboard'],
+  ['52', 'Cotton'],
+  ['61', 'Clothing (Knitted)'],
+  ['62', 'Clothing (Woven)'],
+  ['71', 'Precious Metals & Gems'],
+  ['72', 'Iron & Steel'],
+  ['73', 'Iron & Steel Articles'],
+  ['74', 'Copper'],
+  ['76', 'Aluminium'],
+  ['79', 'Zinc'],
+  ['80', 'Tin'],
+  ['84', 'Machinery & Mechanical Appliances'],
+  ['85', 'Electrical & Electronic Equipment'],
+  ['86', 'Railway'],
+  ['87', 'Vehicles'],
+  ['88', 'Aircraft'],
+  ['89', 'Ships & Boats'],
+  ['90', 'Optical & Medical Instruments'],
+  ['93', 'Arms & Ammunition'],
+];
+
+let cachedHs2: Hs2Entry[] | null = null;
+
+export function getAllHs2(): Hs2Entry[] {
+  if (cachedHs2) return cachedHs2;
+  cachedHs2 = HS2_LABELS.map(([hs2, label]) => ({
+    hs2,
+    label,
+    searchKey: `${normalizeForSearch(label)} hs${hs2} ${hs2}`,
+  }));
+  return cachedHs2;
+}
+
+export function filterHs2(query: string, list: Hs2Entry[] = getAllHs2()): Hs2Entry[] {
+  const q = normalizeForSearch(query);
+  if (!q) return list;
+  return list.filter((e) => e.searchKey.includes(q));
+}
+
+// ─── Cargo type inference ──────────────────────────────────────────────────
+
+export type ExplorerCargo = 'container' | 'tanker' | 'bulk' | 'roro';
+
+/**
+ * Auto-infer a cargo type from the selected HS2 chapter. Returns 'container'
+ * as a sensible default for codes not in the explicit map.
+ */
+export function inferCargoFromHs2(hs2: string | null): ExplorerCargo {
+  if (!hs2) return 'container';
+  const code = hs2.replace(/\D/g, '');
+  if (code === '27') return 'tanker';
+  if (['10', '11', '12', '15', '26'].includes(code)) return 'bulk';
+  if (['87', '89'].includes(code)) return 'roro';
+  // Container default covers 84/85/90/61/62/etc.
+  return 'container';
+}

src/components/RouteExplorer/url-state.ts

@@ -0,0 +1,129 @@
+/**
+ * URL state serialization for the Route Explorer modal.
+ *
+ * Format: `?explorer=from:CN,to:DE,hs:85,cargo:container,tab:1`
+ *
+ * Invalid values fall back to defaults silently — never throw — so the modal
+ * always opens to a usable state regardless of where the URL came from.
+ */
+
+export type ExplorerCargo = 'container' | 'tanker' | 'bulk' | 'roro';
+export type ExplorerTab = 1 | 2 | 3 | 4;
+
+export interface ExplorerUrlState {
+  fromIso2: string | null;
+  toIso2: string | null;
+  hs2: string | null;
+  cargo: ExplorerCargo | null;
+  tab: ExplorerTab;
+}
+
+export const DEFAULT_EXPLORER_STATE: ExplorerUrlState = {
+  fromIso2: null,
+  toIso2: null,
+  hs2: null,
+  cargo: null,
+  tab: 1,
+};
+
+const EXPLORER_QUERY_KEY = 'explorer';
+const VALID_CARGO: ReadonlySet<ExplorerCargo> = new Set([
+  'container',
+  'tanker',
+  'bulk',
+  'roro',
+]);
+const VALID_TABS: ReadonlySet<ExplorerTab> = new Set([1, 2, 3, 4]);
+const ISO2_RE = /^[A-Z]{2}$/;
+const HS2_RE = /^\d{1,2}$/;
+
+/**
+ * Parse the `explorer=...` query parameter into a typed state object.
+ * Unknown or malformed fields fall back to defaults silently.
+ */
+export function parseExplorerUrl(search: string): ExplorerUrlState {
+  let raw: string | null;
+  try {
+    raw = new URLSearchParams(search).get(EXPLORER_QUERY_KEY);
+  } catch {
+    return { ...DEFAULT_EXPLORER_STATE };
+  }
+  if (!raw) return { ...DEFAULT_EXPLORER_STATE };
+
+  const out: ExplorerUrlState = { ...DEFAULT_EXPLORER_STATE };
+  const parts = raw.split(',');
+  for (const part of parts) {
+    const [key, value] = part.split(':');
+    if (!key || value === undefined) continue;
+    switch (key.trim().toLowerCase()) {
+      case 'from': {
+        const v = value.trim().toUpperCase();
+        if (ISO2_RE.test(v)) out.fromIso2 = v;
+        break;
+      }
+      case 'to': {
+        const v = value.trim().toUpperCase();
+        if (ISO2_RE.test(v)) out.toIso2 = v;
+        break;
+      }
+      case 'hs': {
+        const v = value.trim();
+        if (HS2_RE.test(v)) out.hs2 = v;
+        break;
+      }
+      case 'cargo': {
+        const v = value.trim().toLowerCase() as ExplorerCargo;
+        if (VALID_CARGO.has(v)) out.cargo = v;
+        break;
+      }
+      case 'tab': {
+        const n = Number.parseInt(value.trim(), 10) as ExplorerTab;
+        if (VALID_TABS.has(n)) out.tab = n;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return out;
+}
+
+/**
+ * Serialize a state object into the `explorer=...` query value. Returns
+ * `null` when no field is set so callers can remove the param entirely.
+ */
+export function serializeExplorerUrl(state: ExplorerUrlState): string | null {
+  const parts: string[] = [];
+  if (state.fromIso2 && ISO2_RE.test(state.fromIso2)) parts.push(`from:${state.fromIso2}`);
+  if (state.toIso2 && ISO2_RE.test(state.toIso2)) parts.push(`to:${state.toIso2}`);
+  if (state.hs2 && HS2_RE.test(state.hs2)) parts.push(`hs:${state.hs2}`);
+  if (state.cargo && VALID_CARGO.has(state.cargo)) parts.push(`cargo:${state.cargo}`);
+  if (state.tab !== 1 && VALID_TABS.has(state.tab)) parts.push(`tab:${state.tab}`);
+  if (parts.length === 0) return null;
+  return parts.join(',');
+}
+
+/**
+ * Apply a state update to `window.location` without triggering a navigation.
+ * No-op when running in a non-browser context (test runners, sidecar).
+ */
+export function writeExplorerUrl(state: ExplorerUrlState): void {
+  if (typeof window === 'undefined' || !window.history?.replaceState) return;
+  const url = new URL(window.location.href);
+  const serialized = serializeExplorerUrl(state);
+  if (serialized) {
+    url.searchParams.set(EXPLORER_QUERY_KEY, serialized);
+  } else {
+    url.searchParams.delete(EXPLORER_QUERY_KEY);
+  }
+  window.history.replaceState(window.history.state, '', url.toString());
+}
+
+/**
+ * Read state from the current `window.location`. Returns defaults when
+ * running in a non-browser context.
+ */
+export function readExplorerUrl(): ExplorerUrlState {
+  if (typeof window === 'undefined') return { ...DEFAULT_EXPLORER_STATE };
+  return parseExplorerUrl(window.location.search);
+}

src/config/commands.ts

@@ -246,6 +246,7 @@ export const COMMANDS: Command[] = [
   { id: 'view:settings', keywords: ['settings', 'config', 'api keys'], label: 'Open settings', icon: '\u2699\uFE0F', category: 'view' },
   { id: 'view:refresh', keywords: ['refresh', 'reload', 'refresh all'], label: 'Refresh all data', icon: '\u{1F504}', category: 'view' },
   { id: 'view:resilience', keywords: ['resilience', 'resilience score', 'baseline', 'stress', 'country resilience'], label: 'Toggle resilience score', icon: '\u{1F6E1}\uFE0F', category: 'view' },
+  { id: 'view:route-explorer', keywords: ['route', 'explorer', 'ship', 'shipping', 'freight', 'cargo', 'lane', 'hs code', 'hs2', 'import', 'export', 'plan a shipment'], label: 'Route Explorer \u2014 plan a shipment', icon: '\u{1F6A2}', category: 'view' },
 
   // Time range
   { id: 'time:1h', keywords: ['1h', 'last hour', '1 hour'], label: 'Show events from last hour', icon: '\u{1F550}', category: 'actions' },

tests/route-explorer-keyboard.test.mts

@@ -0,0 +1,43 @@
+/**
+ * Smoke tests for the RouteExplorer module's pure-logic surface.
+ *
+ * Focus-trap, digit-binding, and modal lifecycle live in a real DOM and are
+ * covered by the Sprint 6 Playwright E2E suite (`e2e/route-explorer.spec.ts`).
+ * Here we verify that:
+ *   1. The module imports without DOM access (defensive — `installTestHook`
+ *      and the singleton helpers must not crash in node).
+ *   2. The exported singleton is stable across calls.
+ *   3. Open/close are no-ops without a document (server-side import safety).
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+describe('RouteExplorer module surface', () => {
+  it('imports without throwing in a node environment', async () => {
+    const mod = await import('../src/components/RouteExplorer/RouteExplorer.ts');
+    assert.equal(typeof mod.RouteExplorer, 'function');
+    assert.equal(typeof mod.getRouteExplorer, 'function');
+  });
+
+  it('getRouteExplorer returns a stable singleton', async () => {
+    const mod = await import('../src/components/RouteExplorer/RouteExplorer.ts');
+    const a = mod.getRouteExplorer();
+    const b = mod.getRouteExplorer();
+    assert.equal(a, b);
+  });
+
+  it('open() does not throw without a window/document', async () => {
+    // tsx test runner has no DOM by default. The modal's open() uses
+    // `document.body.append` — verify it either no-ops cleanly or throws a
+    // recognizable ReferenceError, not a TypeError that would mask a bug.
+    const mod = await import('../src/components/RouteExplorer/RouteExplorer.ts');
+    const explorer = mod.getRouteExplorer();
+    assert.equal(typeof explorer.open, 'function');
+    assert.equal(typeof explorer.close, 'function');
+    assert.equal(explorer.isOpenNow(), false);
+    // Don't actually call open() — that requires a DOM. The point of this
+    // test is just to confirm the module surface is wired correctly so the
+    // command palette dispatch can find it at runtime.
+  });
+});

tests/route-explorer-pickers.test.mts

@@ -0,0 +1,122 @@
+/**
+ * Unit tests for the Route Explorer picker utilities (pure functions only).
+ * The DOM-bound CountryPicker / Hs2Picker classes are exercised by E2E in
+ * Sprint 6; here we just verify the typeahead filtering and HS2 cargo
+ * inference that the modal relies on.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  filterCountries,
+  getAllCountries,
+  filterHs2,
+  getAllHs2,
+  inferCargoFromHs2,
+} from '../src/components/RouteExplorer/RouteExplorer.utils.ts';
+
+describe('getAllCountries', () => {
+  it('returns at least 190 entries (197 port-clustered countries)', () => {
+    const list = getAllCountries();
+    assert.ok(list.length >= 190, `expected ≥190 countries, got ${list.length}`);
+  });
+
+  it('every entry has iso2 + name + flag + searchKey', () => {
+    const list = getAllCountries();
+    for (const c of list.slice(0, 20)) {
+      assert.match(c.iso2, /^[A-Z]{2}$/);
+      assert.ok(c.name.length > 0);
+      assert.ok(c.flag.length > 0);
+      assert.ok(c.searchKey.length > 0);
+    }
+  });
+
+  it('is sorted alphabetically by display name', () => {
+    const list = getAllCountries();
+    for (let i = 1; i < list.length; i++) {
+      assert.ok(
+        list[i - 1]!.name.localeCompare(list[i]!.name) <= 0,
+        `out of order at ${i}: ${list[i - 1]!.name} > ${list[i]!.name}`,
+      );
+    }
+  });
+});
+
+describe('filterCountries', () => {
+  it('returns full list for empty query', () => {
+    assert.equal(filterCountries('').length, getAllCountries().length);
+  });
+
+  it('matches by partial display name', () => {
+    const out = filterCountries('germ');
+    assert.ok(out.some((c) => c.iso2 === 'DE'));
+  });
+
+  it('matches by ISO2 code', () => {
+    const out = filterCountries('cn');
+    assert.ok(out.some((c) => c.iso2 === 'CN'));
+  });
+
+  it('case-insensitive', () => {
+    const lower = filterCountries('china');
+    const upper = filterCountries('CHINA');
+    assert.equal(lower.length, upper.length);
+  });
+
+  it('returns empty array for nonsense query', () => {
+    const out = filterCountries('zzzzzzzzzzzzzz');
+    assert.equal(out.length, 0);
+  });
+});
+
+describe('getAllHs2 + filterHs2', () => {
+  it('returns ~50 HS2 entries', () => {
+    const list = getAllHs2();
+    assert.ok(list.length >= 40 && list.length <= 60);
+  });
+
+  it('matches by label substring', () => {
+    const out = filterHs2('elect');
+    assert.ok(out.some((e) => e.hs2 === '85'));
+  });
+
+  it('matches by HS code prefix', () => {
+    const out = filterHs2('27');
+    assert.ok(out.some((e) => e.hs2 === '27'));
+  });
+
+  it('returns empty for nonsense query', () => {
+    assert.equal(filterHs2('zzzzzzzzz').length, 0);
+  });
+});
+
+describe('inferCargoFromHs2', () => {
+  it('infers tanker for HS 27', () => {
+    assert.equal(inferCargoFromHs2('27'), 'tanker');
+  });
+
+  it('infers bulk for cereals (10), oilseeds (12), ores (26)', () => {
+    assert.equal(inferCargoFromHs2('10'), 'bulk');
+    assert.equal(inferCargoFromHs2('12'), 'bulk');
+    assert.equal(inferCargoFromHs2('26'), 'bulk');
+  });
+
+  it('infers roro for vehicles (87), ships (89)', () => {
+    assert.equal(inferCargoFromHs2('87'), 'roro');
+    assert.equal(inferCargoFromHs2('89'), 'roro');
+  });
+
+  it('defaults to container for HS 85, 84, 90, 61, 62', () => {
+    assert.equal(inferCargoFromHs2('85'), 'container');
+    assert.equal(inferCargoFromHs2('84'), 'container');
+    assert.equal(inferCargoFromHs2('90'), 'container');
+    assert.equal(inferCargoFromHs2('61'), 'container');
+    assert.equal(inferCargoFromHs2('62'), 'container');
+  });
+
+  it('defaults to container for null / unknown', () => {
+    assert.equal(inferCargoFromHs2(null), 'container');
+    assert.equal(inferCargoFromHs2('999'), 'container');
+  });
+});

tests/route-explorer-url-state.test.mts

@@ -0,0 +1,127 @@
+/**
+ * Roundtrip + edge-case tests for the Route Explorer URL state module.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  parseExplorerUrl,
+  serializeExplorerUrl,
+  DEFAULT_EXPLORER_STATE,
+  type ExplorerUrlState,
+} from '../src/components/RouteExplorer/url-state.ts';
+
+describe('parseExplorerUrl', () => {
+  it('returns defaults for empty search string', () => {
+    const out = parseExplorerUrl('');
+    assert.deepEqual(out, DEFAULT_EXPLORER_STATE);
+  });
+
+  it('returns defaults when explorer param is missing', () => {
+    const out = parseExplorerUrl('?other=value');
+    assert.deepEqual(out, DEFAULT_EXPLORER_STATE);
+  });
+
+  it('parses a complete state string', () => {
+    const out = parseExplorerUrl('?explorer=from:CN,to:DE,hs:85,cargo:container,tab:2');
+    assert.deepEqual(out, {
+      fromIso2: 'CN',
+      toIso2: 'DE',
+      hs2: '85',
+      cargo: 'container',
+      tab: 2,
+    });
+  });
+
+  it('uppercases ISO2 codes', () => {
+    const out = parseExplorerUrl('?explorer=from:cn,to:de');
+    assert.equal(out.fromIso2, 'CN');
+    assert.equal(out.toIso2, 'DE');
+  });
+
+  it('lowercases cargo type', () => {
+    const out = parseExplorerUrl('?explorer=cargo:CONTAINER');
+    assert.equal(out.cargo, 'container');
+  });
+
+  it('drops invalid ISO2 codes silently', () => {
+    const out = parseExplorerUrl('?explorer=from:USA,to:1');
+    assert.equal(out.fromIso2, null);
+    assert.equal(out.toIso2, null);
+  });
+
+  it('drops invalid HS2 codes silently', () => {
+    const out = parseExplorerUrl('?explorer=hs:abc');
+    assert.equal(out.hs2, null);
+  });
+
+  it('drops invalid cargo type silently', () => {
+    const out = parseExplorerUrl('?explorer=cargo:rocket');
+    assert.equal(out.cargo, null);
+  });
+
+  it('drops invalid tab silently', () => {
+    const out = parseExplorerUrl('?explorer=tab:99');
+    assert.equal(out.tab, 1);
+  });
+
+  it('accepts partial state', () => {
+    const out = parseExplorerUrl('?explorer=from:CN,hs:27');
+    assert.equal(out.fromIso2, 'CN');
+    assert.equal(out.toIso2, null);
+    assert.equal(out.hs2, '27');
+    assert.equal(out.cargo, null);
+    assert.equal(out.tab, 1);
+  });
+
+  it('does not throw on malformed param', () => {
+    const out = parseExplorerUrl('?explorer=garbage:::');
+    assert.deepEqual(out, DEFAULT_EXPLORER_STATE);
+  });
+});
+
+describe('serializeExplorerUrl', () => {
+  it('returns null for default state', () => {
+    assert.equal(serializeExplorerUrl(DEFAULT_EXPLORER_STATE), null);
+  });
+
+  it('serializes complete state', () => {
+    const state: ExplorerUrlState = {
+      fromIso2: 'CN',
+      toIso2: 'DE',
+      hs2: '85',
+      cargo: 'container',
+      tab: 2,
+    };
+    assert.equal(serializeExplorerUrl(state), 'from:CN,to:DE,hs:85,cargo:container,tab:2');
+  });
+
+  it('omits tab=1 from output', () => {
+    const state: ExplorerUrlState = { ...DEFAULT_EXPLORER_STATE, fromIso2: 'CN', tab: 1 };
+    assert.equal(serializeExplorerUrl(state), 'from:CN');
+  });
+
+  it('omits null fields', () => {
+    const state: ExplorerUrlState = { ...DEFAULT_EXPLORER_STATE, fromIso2: 'CN', hs2: '85' };
+    assert.equal(serializeExplorerUrl(state), 'from:CN,hs:85');
+  });
+});
+
+describe('roundtrip', () => {
+  const cases: ExplorerUrlState[] = [
+    { fromIso2: 'CN', toIso2: 'DE', hs2: '85', cargo: 'container', tab: 1 },
+    { fromIso2: 'IR', toIso2: 'CN', hs2: '27', cargo: 'tanker', tab: 3 },
+    { fromIso2: null, toIso2: null, hs2: '10', cargo: 'bulk', tab: 4 },
+    { fromIso2: 'BR', toIso2: 'NL', hs2: null, cargo: null, tab: 2 },
+  ];
+
+  for (const state of cases) {
+    it(`roundtrips ${JSON.stringify(state)}`, () => {
+      const serialized = serializeExplorerUrl(state);
+      assert.ok(serialized, 'expected non-null serialization');
+      const parsed = parseExplorerUrl(`?explorer=${serialized}`);
+      assert.deepEqual(parsed, state);
+    });
+  }
+});