Introducing a new way to review your PRs.

Read the announcement

koala73 / worldmonitor

Real-time global intelligence dashboard. AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface

View on GitHub

29 documents · Updated Nov 20, 2026

docs / client-experience

Web client experience

WorldMonitor is a browser application for viewing live global signals in one interactive workspace. The client turns a static page shell into a variant-aware map and panel experience, then connects that experience to data services, user access, saved preferences, localization, agent control, search, and background refresh.

Client lifecycle

The browser uses staged startup so the user sees a stable workspace before all data and feature code are ready. The page first paints a loading shape, then starts the application, composes the map and panels, fills visible data, and continues with background work.

flowchart TD
    A[HTML page and loading shell] --> B[Browser entry startup]
    B --> C[Runtime and presentation setup]
    C --> D[Shared application context]
    D --> E[Map and panel composition]
    E --> F[Visible data and user state]
    F --> G[Search, agent actions, and background refresh]

Browser entry

The browser enters through home/…/main.ts. Startup prepares presentation state, runtime routing, error reporting, analytics, update checks, and the selected client surface. The static shell in home/…/index.html gives the first view a useful shape while JavaScript and network work finish. After the active language is known, the client also localizes the document title and sharing descriptions without replacing the variant-specific English copy.

The main dashboard is one surface among several. Settings, live channels, and embeds use the same product language but have narrower goals. Desktop sign-in can move origin-bound work to the system browser, while the embedded runtime keeps provider credentials and one-time sign-in material outside renderer code.

References: src/main.ts• L29-70 src/main.ts• L543-604 src/main.ts• L625-687 src/…/shell-meta.ts• L1-18 src/embed-main.ts• L21-88 index.html• L423-490

Application composition

The application coordinator creates shared context for map state, panels, data, access, URL state, and lifecycle flags. It connects feature managers for layout, loading, refresh, events, search, country intelligence, alerts, account flows, and optional tracking.

The composition keeps feature modules independent while giving them common state and narrow callbacks. The web application shell and composition page describes entrypoints and central orchestration in more detail. Addressable panels receive their own visibility and refresh paths, so one optional domain read does not block unrelated work.

Before bootstrap data loads, web startup can establish an anonymous session. Protected work waits for the matching access state. Sign-up, billing return, passkey, and Pro activation flows attach to the application lifecycle so a redirect or delayed identity result can resume the right user task.

After the dashboard settles, the shell also evaluates deferred onboarding and community prompts. The GitHub star prompt counts eligible visits, waits for user idle time, and loads its controller only when the user can be asked; overlays and account state can suppress it, and shell teardown removes it.

References: src/App.ts• L299-381 src/App.ts• L414-449 src/App.ts• L738-1000 src/…/app-context.ts• L67-163 src/…/panel-layout.ts• L460-539 src/…/panel-layout.ts• L764-776 src/…/github-star-prompt-boot.ts• L39-68 src/…/github-star-prompt.ts• L97-119 src/…/passkey-offer-controller.ts• L205-260 src/…/pro-activation-controller.ts• L156-235

Interactive workspace

The main dashboard combines a geographic view with configurable feature panels. The selected product variant changes the default focus, while the shared workspace supports common map, news, market, tracking, intelligence, and search actions.

Variant experience

A variant is a product view with its own domain focus, default panels, map layers, labels, public page text, and visual treatment. The client selects a variant from the host name or stored preferences. The main views are full, tech, finance, commodity, energy, and happy.

Variant configuration controls active defaults. A shared panel registry keeps supported panels addressable for saved workspaces and cross-variant use. Panel categories give settings and mobile navigation a variant-aware view of the same registry.

VariantPrimary user focus
FullGeopolitical and global intelligence
TechTechnology, AI, startups, and digital infrastructure
FinanceMarkets, trading, and macro signals
CommodityMining, metals, energy, and supply chains
EnergyEnergy assets, routes, chokepoints, and disruption
HappyPositive events, progress, conservation, and giving

Each variant also has public metadata for its title, description, canonical URL, feature summary, and search terms. This lets the browser surface keep a shared application while presenting a clear product identity for the selected view.

References: src/…/panels.ts• L20-141 src/…/panels.ts• L991-1026 src/…/panels.ts• L1153-1255 src/…/panels.ts• L1504-1667 src/…/variant-meta.ts• L1-153 src/…/index.ts• L118-132

Map and panel workspace

The map is the main geographic surface. It presents selectable layers and regional views, while panels provide focused views of news, markets, infrastructure, events, forecasts, alerts, aviation, displacement, and intelligence. Map and panel state are linked: a layer can start data work, and a panel can move the map or open a country, asset, story, or research view.

Point markers can carry the same category symbol shown in the Layers menu. The map adds these non-interactive glyphs beside markers and adds the category to tooltips, while dense world views hide most glyphs until the user zooms closer. This keeps object status and layer identity visible without replacing the marker's own interaction or status color.

The map can use a globe, a high-volume desktop map, or a flat mobile and fallback map. These surfaces share map state and can fall back when a preferred renderer is unavailable. The visible map-dimension control and agent action use the same transition, so the saved preference follows the renderer that actually becomes active. A renderer change can also remove a layer that the new surface cannot run. Geographic labels adapt to the map theme without changing the provider's label order or collision behavior.

Country navigation uses a map-specific geographic footprint rather than a broad country record. This keeps the camera centered on the area that the map should show, including countries whose borders cross the date line or whose full geographic record includes distant territories. A map-opened country brief also returns focus to the map when it closes.

Panels can mount early or near the viewport. A deferred panel shell reserves its saved or natural size before the feature code is ready, which reduces blank space and layout movement. When a panel is locked, its shell uses the compact locked footprint as well, so access changes do not pull later panels upward.

The technology experience includes geographic infrastructure such as AI data centers. Live news and webcam surfaces use ordered source choices and show only sources that can be verified or played in the browser. Satellite evidence surfaces distinguish a recent scene that is still processing from a scene that failed to load, so a short archive delay does not look like a permanent data error.

The orbital watch experience adds a point-based satellite view to the same workspace. A user selects a place or uses a shared point link, then receives upcoming satellite passes, archive evidence, a timeline, and an optional ground track on the map. The sheet can add watched-site context and reservoir information without changing the selected point, and it restores the prior map view when it closes.

The monitoring dashboards and feature experiences page covers domain panels, map layers, and feature workflows in more detail.

References: src/…/MapContainer.ts• L166-184 src/…/MapContainer.ts• L318-359 src/…/MapContainer.ts• L623-725 src/…/DeckGLMap.ts• L2550-2636 src/…/DeckGLMap.ts• L5272-5281 src/…/DeckGLMap.ts• L1290-1306 src/…/map-layer-glyphs.ts• L4-20 src/…/map-layer-glyphs.ts• L84-120 src/…/MapPopup.ts• L248-432 src/…/map-dimension-control.ts• L76-163 src/…/country-map-focus.ts• L49-101 src/…/country-intel.ts• L371-438 src/…/panel-layout.ts• L262-343 src/…/panel-layout.ts• L830-865 src/…/panel-layout.ts• L1122-1171 src/…/panel-layout.ts• L3228-3243 src/…/panel-mount-deferral.ts• L6-18 src/…/panel-mount-deferral.ts• L95-188 src/…/split-layout.ts• L9-80 src/…/orbital-watch.ts• L329-357 src/…/orbital-watch.ts• L404-426 src/…/orbital-watch.ts• L498-574 src/…/en.json• L4697-4727

Country intelligence

Country intelligence turns a selected country into a bounded brief with risk, resilience, markets, military context, trade, supply chains, raw signals, demographics, and forecasts. The normal website and host-controlled surfaces use the same country brief contract while applying their own access rules.

The brief shows its main country surface first, then enriches independent sections. Each section can be ready, locked, partial, or unavailable. A new country cancels older work, and late results cannot update the wrong country. Invalid country codes are rejected before they can replace a valid open. If opening fails after the loading surface appears, the unfinished surface is removed so the map can resume.

The web client records whether an AI brief was denied because sign-in or Pro access is needed, or because the service is unavailable. If the account or entitlement changes while that notice is visible, the brief can retry in the same country and preserve the current owner. A local signal summary remains a separate fallback from a generated or local-model brief, so live signal rows can refresh without replacing prose.

The manager separates human and agent ownership. An agent can inspect a brief without replacing a visible human selection. When access changes, affected premium sections refresh in the current brief.

References: src/…/country-intel.ts• L306-399 src/…/country-intel.ts• L402-438 src/…/country-intel.ts• L793-963 src/…/country-intel.ts• L1060-1110 src/…/CountryBriefController.ts• L39-159 src/…/CountryDeepDivePanel.ts• L390-445

User workspaces

Presentation state lets users shape the dashboard without changing product defaults. The client stores panel visibility, order, size, map mode, map layers, time range, monitors, tabs, and custom panels. It reconciles this state when account, entitlement, variant, or renderer state changes.

Mission presets restore a compatible set of panels, layers, map view, and time range for a task. The dashboard can suggest a mission after first paint, then offer an account profile prompt only when another onboarding surface does not own that load. Applying or resetting a mission starts the new panel view at its first useful panel instead of leaving the user at a stale scroll position. Panel changes from settings, search, undo, mobile navigation, and agent actions use the same entitlement and persistence path.

The unified settings surface groups appearance, map, media, intelligence, language, panel, source, notification, billing, API key, embed, and connected MCP choices. A signed-in user can also sync account-bound preferences without confusing them with local browser state. Users can copy a share link through the browser's available copy path, with a fallback when the preferred clipboard API is absent.

Panel changes from search, settings, undo, and agent actions share one apply path. It persists the catalog panel state, updates the live layout, refreshes settings controls, and can start fresh data work when a panel is restored. Free users receive a clear limit response instead of a silent no-op.

References: src/…/event-handlers.ts• L446-518 src/…/event-handlers.ts• L757-807 src/…/event-handlers.ts• L1405-1438 src/…/event-handlers.ts• L1557-1615 src/…/panel-layout.ts• L502-539 src/…/panel-layout.ts• L1122-1171 src/…/panels.ts• L1230-1255 src/…/panels.ts• L1504-1667

Search and discovery

The dashboard search palette is a common discovery surface for countries, news, markets, predictions, flights, infrastructure, technology, finance, commands, and available panels. It turns a selection into the same map, panel, country, theme, or external-navigation action used by the rest of the client.

Country commands provide separate map and brief actions. They use translated display names, curated aliases, and country-specific names such as common names for Côte d’Ivoire. Canonical country names keep matching and downstream actions stable when the visible language changes. Layer and panel terms avoid bare country-name conflicts so a country query opens the country action instead of an unrelated feature.

Search keeps short-lived live sources separate from durable sources. Current news and flight positions come from the active workspace, while headline history can fill stories that have left the loaded news set. A signed-in Pro user can also search alerts that were delivered to that account, even when the dashboard no longer holds the article. These private and external results remain human-only.

Search and WebMCP share one selection dispatcher. It checks the active variant, renderer, entitlement, panel availability, and current search match before it acts. Agent-issued results use short-lived opaque keys and are checked again at open time, so a change in access or workspace state revokes an old result rather than applying it to a new context.

References: src/…/commands.ts• L336-428 src/…/search-manager.ts• L216-326 src/…/search-manager.ts• L362-558 src/…/search-manager.ts• L980-1034 src/…/country-map-focus.ts• L79-101 src/…/headline-history-search.ts• L5-14 src/…/search-alert-source.ts• L4-10 src/…/search-alert-wiring.ts• L55-114 src/…/search-selection-dispatcher.ts• L67-215

Agent interaction

The dashboard exposes a browser agent interface called WebMCP. A supported browser or assistant can inspect dashboard context and use bounded actions to navigate the map, panels, tabs, mission presets, followed countries, settings, access state, and time range. These actions use the same application state as human controls.

WebMCP separates static homepage tools, imperative dashboard tools, and a conditional procurement form. Dashboard tools are present across variants, while the procurement tool appears only when its panel is enabled, entitled, visible, and ready. Shared name, description, schema, output, and error budgets keep the agent surface bounded.

Read-only and reversible view actions can run without target cancellation support. Actions that persist state, consume a quota, or trigger external work require a host that can cancel them. Agents cannot bypass account or free-tier limits.

Search results issued to an agent carry the effect class of the action. A map move is a reversible view change, while a layer toggle, panel enablement, country brief, or external article open has a stronger boundary. The client rejects a result when the host cannot cancel an action that needs cancellation, or when a newer human or agent action has superseded it.

Settings also helps users connect the WorldMonitor MCP service to common agent clients. Each supported client has one verified link, command, or service URL so the connection path stays clear without changing dashboard access rules.

References: src/…/webmcp.ts• L3-9 src/…/webmcp.ts• L11-52 src/…/webmcp.ts• L54-88 src/…/webmcp.ts• L115-168 src/…/webmcp.ts• L501-569 src/…/webmcp.ts• L773-851 src/…/webmcp-search-controller.ts• L68-119 src/…/webmcp-search-controller.ts• L121-197 src/…/webmcp-search-controller.ts• L200-329 src/…/webmcp-search-effects.ts• L4-22 src/…/webmcp-search-effects.ts• L66-119 src/…/event-handlers.ts• L444-515 src/…/mcp-agent-clients.ts• L17-43 src/…/mcp-agent-clients.ts• L58-119

Data and service coordination

The client separates showing a feature from obtaining its data. Loaders fill shared application state, panels render that state, and shared services provide request routing, cache access, authentication, entitlement checks, and product-wide behavior.

Initial data fill

The client starts with a small public bootstrap response for data near the first view. Slower responses fill shared data after first paint. A recent persistent snapshot can keep the workspace useful when the network is unavailable, with the result marked as cached rather than live.

The data loader runs work by priority. News, markets, and intelligence receive early attention. Other work starts when its panel or map layer is near the viewport. Optional domain reads stay out of bootstrap until their panel or map layer is active. Mobile uses lower concurrent work than desktop so feature startup does not create one long main-thread task. A failed task does not stop unrelated features.

News uses a generated browser catalog as the shared source of feed, edition, language, and cross-variant coverage. Variant presets choose the first categories, while the canonical catalog lets a user-enabled panel resolve its sources even when that panel belongs to another variant. Locale-matched and strategic sources shape the visible set without changing the product's common feed contract. The catalog records the current feed endpoints and source language metadata, so feed redirects do not silently change the source identity used by the browser.

Viewport hydration records which panel instances have received their first load and only claims new near-viewport work on a viewport pass. Concurrent or repeated load requests drain through one queued pass, while a full pass can still force all work. News uses a work-list signature so viewport events do not refetch an unchanged category set; panel, tab, mission, or source changes re-arm the news load.

News loading can paint from a fallback digest while a fresher digest is pending, then reload preset categories and intelligence against the final digest. Cross-edition panels combine the relevant edition digests and can fill missing enabled sources from bounded cached rows after the main view is visible. Population Exposure combines unrest and UCDP event inputs, keeps source coverage visible, and distinguishes projected UCDP locations from a full feed. A digest coverage summary is retained in shared application state, so a status panel that mounts after the first digest can show the same coverage without waiting for another digest.

References: src/…/bootstrap.ts• L21-36 src/…/bootstrap.ts• L298-409 src/…/data-loader.ts• L1050-1117 src/…/data-loader.ts• L1152-1222 src/…/data-loader.ts• L1231-1252 src/…/data-loader.ts• L1690-1755 src/…/data-loader.ts• L2180-2218 src/…/data-loader.ts• L2380-2490 src/…/data-loader.ts• L4000-4032 src/…/news-loader-sequencing.ts• L62-93 src/…/news-loader-sequencing.ts• L100-214 src/…/viewport-hydration-ledger.ts• L17-89 src/…/population-exposure.ts• L24-72 src/…/feeds.ts• L19-45 src/…/feeds.ts• L116-148 src/…/news-catalog.browser.generated.ts• L1-12

Signal aggregation

Signal aggregation gives map, country, and analysis views a common country-level context. It combines event families such as outages, military activity, unrest, shipping disruption, hazards, sanctions, and strikes, then ranks countries and regions by signal variety, count, and severity.

Each source keeps its own freshness and coverage rules before entering the shared context. A refresh replaces the source family instead of silently treating missing data as a quiet result.

References: src/…/signal-aggregator.ts• L19-70 src/…/signal-aggregator.ts• L116-165 src/…/signal-aggregator.ts• L303-392

Refresh behavior

Live behavior continues after the first data fill through application-owned refresh lanes. Each lane has its own interval and can pause when the page is hidden. Viewport checks and in-flight guards prevent duplicate work.

This ties freshness to user attention. A visible panel can refresh sooner, while an unseen panel waits until it becomes relevant. The client keeps the last useful result when a later refresh fails and keeps stale or partial status visible.

References: src/…/refresh-scheduler.ts• L85-130 src/…/data-loader.ts• L1027-1103 src/App.ts• L414-449 src/App.ts• L738-762 src/…/base.ts• L11-91

Request paths

The client uses one request model across web and desktop, but the destination depends on the runtime. Web requests use the WorldMonitor gateway. Desktop local requests use the sidecar and can use a remote service only when the endpoint allows it. The native bridge keeps local credentials outside renderer code.

Request routing carries access context for protected features. Premium authentication is added only to routes that need it. Local-only routes cannot use cloud fallback. Anonymous web access uses a short-lived session cookie and limits recovery after route failures so one broken route does not disable all anonymous work.

References: src/…/runtime.ts• L24-160 src/…/tauri-bridge.ts• L78-117 src/…/desktop-cloud-auth.ts• L17-75 src/…/premium-fetch.ts• L170-235 src/…/wm-session.ts• L23-72 src/…/wm-session.ts• L981-1037

Access and language

The browser experience adapts to the current user and environment without making the dashboard coordinator own every access or language detail. Authentication, entitlement, runtime readiness, and localization publish state for the shell and panels.

Identity and entitlements

Authentication settles as a signed-in user or anonymous session. The dashboard uses this state for account controls and panel gates. Entitlement changes can unlock premium panels during the current session, while sign-out clears account-bound state.

Billing and entitlement watches are account-bound. A late response from an earlier account cannot attach state to the current account. The client keeps renewal, payment hold, and lapsed access distinct from an ordinary free state.

References: src/…/auth-state.ts• L9-92 src/…/entitlements.ts• L19-87 src/…/convex-client.ts• L26-149 src/…/billing-state.ts• L143-160 src/…/billing.ts• L94-186

Billing and activation

Upgrade actions use one client path for locked panels, mission previews, and resilience views. Web checkout uses the hosted payment page, while desktop opens the system browser. A short-lived return record carries the originating task across the return and lets the dashboard restore focus after access changes. Generated product identities and plan limits keep checkout choices consistent with the access and usage state shown in the client.

New Pro subscribers can receive an activation flow for a morning brief, real-time alerts, and Pro tools. The flow preserves existing settings and distinguishes verified, skipped, blocked, unavailable, and failed steps. A passkey offer is a separate post-sign-in prompt. It is limited by account and device history and waits for overlays and identity state to settle before it appears.

References: src/…/pro-activation-controller.ts• L135-319 src/…/passkey-offer-controller.ts• L41-182 src/…/upgrade-flow.ts• L1-43 src/…/billing-portal-intent.ts• L1-129 src/…/products.generated.ts• L1-30 src/…/ProActivationInterstitial.ts• L302-376

Runtime readiness

Runtime configuration describes optional services that may need a key or local provider. Settings groups these capabilities by area, shows readiness, validates staged values, and commits only verified values. A missing provider removes only its dependent feature or shows an unavailable state.

References: src/…/runtime-config.ts• L5-77 src/…/runtime-config.ts• L109-290 src/…/RuntimeConfigPanel.ts• L35-159 src/…/desktop-readiness.ts• L38-142

Localization

Localization chooses a supported language from a shareable URL, an explicit user choice, or the browser language. The client loads a small English shell first and then the active full dictionary. It updates document language and text direction, including right-to-left layout for Arabic and Persian.

The shell and feature modules use one translation service for controls, panel labels, status messages, access prompts, commands, country context, alerts, layer guides, live media, orbital watch, search results, and errors. Locale resources also cover connectivity states, the deferred GitHub star prompt, sent-alert search, the focused-tab trip assessment action, and the user's daily brief-language choice across the supported languages. Generated news catalog data keeps edition, source, and digest-language coverage aligned with the active language.

References: src/…/i18n.ts• L21-89 src/…/i18n.ts• L145-216 src/…/i18n.ts• L255-317 src/…/en.shell.json• L1-87 src/…/en.json• L713-765 src/…/en.json• L4612-4727 src/…/en.json• L5227-5268 src/…/en.json• L5845-5851 src/…/ar.json• L1-19 src/…/zh.json• L1-19 src/…/news-catalog.browser.generated.ts• L1-12 src/…/index.ts• L118-132

Web presentation surfaces

The web experience includes the interactive dashboard and public HTML surfaces that lead users and crawlers to it. These surfaces preserve product identity without requiring JavaScript for every useful response.

Variant page presentation

Variant subdomains share the dashboard application but receive domain-specific titles, descriptions, canonical URLs, feature summaries, and no-script text. Shared graph identifiers connect each variant to the WorldMonitor organization, website, and software product.

References: src/…/variant-dashboard-html.ts• L1-17 src/…/variant-dashboard-html.ts• L216-318 src/…/variant-meta.ts• L14-153 src/…/schema-graph-ids.ts• L21-87

Documentation and not-found responses

Documentation navigation maps short public paths to the hosted docs service. Locale-aware responses now set the active document language and Open Graph locale, add the canonical URL and reciprocal English/Chinese links when both pages exist, and align the page's structured data with the canonical WorldMonitor graph. The page-date manifest supplies known publication and modification dates, while only pages with a known date and name receive an article record. Unknown paths return a real 404 with a human page for browsers and a compact Markdown guide for agents and SDKs.

This keeps translated documentation discoverable without claiming a locale twin that does not exist. It also lets search systems connect a documentation page to the product site instead of treating the hosted docs vendor as a separate site.

References: src/…/docs-locale-seo.ts• L19-30 src/…/docs-locale-seo.ts• L41-112 src/…/docs-locale-seo.ts• L138-166 src/…/docs-locale-seo.ts• L390-455 src/…/docs-locale-seo.ts• L515-567 src/…/docs-page-dates.generated.ts• L1-5 src/…/agent-not-found.ts• L16-24

Presentation state

Presentation state is the visible condition of the workspace: theme, type scale, direction, map mode, connectivity, loading shape, and data freshness. The client applies these choices before or during composition so the view changes with minimal disruption.

Connectivity and freshness

The header distinguishes live, cached, partial, and unavailable states. It uses browser connectivity and the source of bootstrap data. A mixed result is not described as wholly unavailable when some live data is already on screen.

References: src/…/bootstrap.ts• L21-34 src/App.ts• L624-712 src/App.ts• L1991-2001 src/…/en.shell.json• L9-15 src/…/en.shell.json• L259-263

Visual continuity

The loading shell keeps dimensions close to the first dashboard frame. The map and large feature code can load later, but the user sees reserved space instead of a blank page or a large layout jump. Themes, fonts, scale preferences, saved map width, and panel footprints apply early.

References: index.html• L444-489 src/…/panel-layout.ts• L263-424 src/…/panel-layout.ts• L1048-1070 src/…/panel-mount-deferral.ts• L136-188 src/…/split-layout.ts• L9-80 src/main.ts• L606-629

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the static loading shell aligned with the first hydrated layout and with deferred panel footprints, including the compact footprint for locked panels.
  • Keep variant panel defaults, public metadata, map-layer defaults, renderer support, panel categories, labels, and the unified registry aligned.
  • Keep opt-in panel and layer gates aligned with their data-loader triggers.
  • Keep the split-layout threshold, right-to-left side mapping, map width limits, and stored layout behavior aligned.
  • Keep country-map focus geometry, antimeridian handling, country command aliases, translated names, and country brief navigation aligned.
  • Keep map-opened country briefs' return focus, request ownership, cancellation, loading-shell cleanup, and current-presentation guards aligned.
  • Keep mission preset application and reset aligned with panel order, map layers, time range, URL state, data refresh, and the visible scroll position.
  • Keep point-layer category mappings, deliberate glyph exclusions, registry icons, tooltip labels, zoom limits, and marker offsets aligned.
  • Keep the orbital lookup's URL fragment, selected pass, map camera hold and restore, visible-map offset, archive state, and abort ownership aligned.
  • Keep viewport hydration identity, access context, expiry, near-viewport checks, queued reruns, and refresh-scheduler ownership aligned.
  • Keep news work-list signatures aligned with enabled categories, intelligence sources, disabled sources, tab changes, mission changes, and direct refresh ownership.
  • Keep the browser news catalog, variant feed presets, canonical cross-variant categories, locale fields, digest editions, proxy routing, and default source policy aligned.
  • Keep cross-edition digest completeness, language scope, stale state, source fill, item limits, work-list signatures, and generation checks aligned.
  • Keep map-dimension button actions, agent actions, renderer fallback, effective preference persistence, and incompatible layer changes aligned.
  • Keep search source registration, loaded-news matching, headline-history fallback, sent-alert account scope, openable-link rules, and source refresh timing aligned.
  • Keep search result effect classes aligned with WebMCP cancellation rules, opaque-key expiry, security invalidation, live-match checks, and human-selection cancellation.
  • Keep generated RPC shapes, runtime base URLs, access context, lazy loading, and local-only boundaries aligned.
  • Keep entitlement lists aligned between configuration, panel gating, protected loaders, settings, missions, search, and activation flows.
  • Keep checkout return markers, subscription keys, Pro activation outcomes, passkey account and device ledgers, and onboarding arbitration aligned.
  • Keep GitHub prompt visit counting, iframe exclusion, dismissal persistence, entitlement re-checks, idle gating, competing overlays, locale keys, and teardown aligned.
  • Keep locale tags, direction rules, panel categories, command keywords, country aliases, brief fallback labels, brief-language settings, regulation labels, layer guide keys, live-media states, orbital labels, search text, connectivity text, and star-prompt text aligned across all locale resources.
  • Keep live source slots, ordered fallback sources, generated refresh-channel lists, feed redirect targets, and the visible channel and webcam choices aligned.
  • Keep MCP agent-client connection instructions aligned between Settings and the MCP quickstart.
  • Keep generated documentation dates, locale-aware documentation metadata, canonical graph identifiers, article injection rules, and the pages they describe aligned.

Important failure modes

TriggerConsequenceGuard
A country changes while an earlier brief request is activeOld data can appear in the new country's panelRequest tokens, country checks, and abort signals reject late work
A map supplies an invalid country codeA placeholder can replace a valid pending briefCanonical country validation runs before request ownership is claimed
An agent opens a brief while a human brief is visibleThe human's visible context can be replaced unexpectedlyExplicit request ownership preserves the human brief
A country brief is denied and access later changesThe user can remain on an outdated sign-in or upgrade stateAccess revisions retry the current brief for its existing owner
A map-opened brief keeps the earlier focused control as its return targetClosing the brief can return focus to an unrelated layer or page controlMap opens claim the map as the request's return target
A deferred panel shell uses the wrong footprintHydration causes a layout jumpNatural, saved, and locked footprints reserve space and dev checks report drift
A viewport pass repeats for the same panel instanceScrolling can refetch visible data repeatedlyThe hydration ledger records served instances and expires them by context
Multiple startup triggers request the same data passBoot can duplicate digest or panel workThe loader drains one queued pass and re-arms news only when its work signature changes
A cross-edition digest lacks one required editionA custom news panel can silently omit sourcesThe client marks the merge incomplete and retains a safer fallback
A locale key is missing for a new client stateThe feature can show blank or fallback textShared shell and full locale resources define states before exposure
A selected country has a broad or date-line-crossing map recordCountry navigation can center on the wrong land areaMap focus uses the map-specific footprint and a bounded camera calculation
A recent satellite scene is available in an archive but its crop is still processingThe user can see a permanent failure for a temporary archive delayThe imagery surface uses a distinct processing message for fresh scenes
A selected orbital point changes while archive or pass work is activeA late track or site record can appear for the wrong pointThe lookup owns abort signals and checks the current point before presentation
A headline leaves loaded news while history search still shows the old answerSearch can hide or duplicate the storyTitle identity and loaded-news matching replace only the affected history rows
A sent-alert response crosses an account or entitlement changeOne user's private alert history can appear for another userAccount keys and generations clear old rows and discard late responses
A WebMCP result is opened after access, variant, or renderer state changesAn old agent action can mutate the wrong workspaceOpaque keys carry context and are checked again at use time
A WebMCP host cannot cancel a persistent or external actionThe user cannot stop an agent side effectEffect classes mark the action and the controller denies unsupported hosts
A feed is added to the catalog without the browser slice or default policyA panel can show no source or a returning user can receive a silent source changeGenerated catalog, canonical feed resolution, migration stages, and default sets stay synchronized
A documentation page has no locale twin or known dateSearch metadata can point at a false page or claim an invented article dateHreflang requires both pages and article metadata requires a known manifest entry
The preferred map renderer failsThe workspace can lose its geographic surfaceShared map state moves to a usable fallback renderer

Key files

FileWhy to read it
index.htmlShows the first-paint shell that the dashboard replaces.
src/main.tsShows browser startup, runtime selection, update recovery, metadata setup, and entrypoint branching.
src/App.tsShows lifecycle, shared context, access, data, refresh, and account handoff.
src/…/app-context.tsDefines shared state for feature coordination and digest coverage.
src/…/panel-layout.tsShows map, panels, tabs, missions, deferred shells, access gates, storage focus, onboarding, and composition.
src/…/panel-mount-deferral.tsDefines when panels mount and how their placeholder space is reserved.
src/…/data-loader.tsShows data priority, queued hydration, viewport claims, digest selection, coverage handoff, optional domain gates, and panel handoff.
src/…/event-handlers.tsShows user actions, workspace changes, mission scroll reset, map-layer transitions, URL state, copy behavior, and storage-panel routing.
src/…/country-map-focus.tsDefines the shared camera focus used for country map navigation.
src/…/orbital-watch.tsShows the point lookup, archive evidence, pass selection, map track, shared links, and close behavior.
src/…/search-manager.tsShows search source composition, live enrichment, panel discovery, and WebMCP wiring.
src/…/search-selection-dispatcher.tsShows how human and agent selections become map, panel, country, or external actions.
src/…/headline-history-search.tsShows how older news headlines enrich the browser search index.
src/…/search-alert-source.tsShows account-scoped alert history as a human search source.
src/…/search-alert-wiring.tsShows alert access, locale-aware labels, runtime link rules, and teardown.
src/…/webmcp-search-controller.tsShows agent search result issuance, revocation, use-time checks, and cancellation.
src/…/webmcp-search-effects.tsDefines the action boundaries used for agent safety.
src/…/shell-meta.tsShows localization of title and sharing metadata for non-English pages.
src/…/country-intel.tsShows country brief ownership, cancellation, access notices, presentation, and enrichment.
src/…/passkey-offer-controller.tsShows post-sign-in passkey eligibility and prompt arbitration.
src/…/pro-activation-controller.tsShows Pro activation lifecycle and checkout-return recovery.
src/…/commands.tsDefines command search categories, country aliases, map actions, layer actions, and panel actions.
src/…/variant-meta.tsShows public identity and feature summaries for each product variant.
src/…/panels.tsShows variants, panel defaults, map layers, categories, access metadata, and optional panel registration.
src/…/feeds.tsShows browser feed selection, canonical source routing, locale policy, and cross-edition coverage.
src/…/news-catalog.browser.generated.tsShows the generated browser news catalog used by the feed view.
src/…/docs-locale-seo.tsShows locale links, canonical metadata, structured data, and documentation article dates.
src/…/docs-page-dates.generated.tsShows generated publication and modification dates used by documentation surfaces.
src/…/map-layer-glyphs.tsDefines the shared map-layer identity used by marker glyphs and tooltips.
src/…/mcp-agent-clients.tsDefines the connection choices shown for external MCP clients.
src/…/webmcp.tsDefines the browser agent tool surfaces, variant inventory, and shared contract limits.
src/…/en.shell.jsonShows the small first-load vocabulary and connectivity states.
src/…/en.jsonShows the full English vocabulary for panels, categories, map labels, search, orbital watch, prompts, brief fallback states, and language settings.
src/…/bootstrap.tsShows initial data paths and cached fallback behavior.
src/…/population-exposure.tsShows source normalization, precision handling, exposure coverage, and location grouping for the Population Exposure experience.
src/…/MapContainer.tsShows renderer choice, map startup, state handoff, and fallback behavior.
src/…/DeckGLMap.tsShows map marker glyphs, category tooltips, and layer presentation.
src/…/CountryBriefController.tsCoordinates country section loads, cancellation, and access states.
src/…/CountryBriefPanel.tsDefines the country brief contract between data services and presentation.