Web application shell and composition
World Monitor uses a set of focused browser surfaces around one shared web product. The main dashboard provides the full monitoring workspace, while settings, live channels, embeds, browser-plugin views, MCP consent, and claim verification start only the services needed for their task. See client experience for the wider client model and monitoring dashboards for dashboard behavior.
Surface entrypoints
Each page starts from a dedicated browser entrypoint. The main entry prepares shared browser services and chooses between the dashboard and focused management windows. Separate plugin and verification entrypoints keep host-facing and public workflows independent from the full dashboard.
flowchart TD
Request[Browser request] --> Surface{Web surface}
Surface --> Dashboard[Primary dashboard]
Surface --> Focused[Settings or live channels]
Surface --> Embed[Partner embed]
Surface --> Grant[MCP consent]
Surface --> PluginNews[Browser-plugin news view]
Surface --> PluginCountry[Browser-plugin country view]
Surface --> Verify[Claim verification]
Dashboard --> Main[src/main.ts]
Main --> App[App composition]
Focused --> Main
PluginNews --> Plugin[Plugin composition]
PluginCountry --> CountryPlugin[Country plugin composition]
Verify --> VerifyEntry[src/verify-main.ts]
Primary dashboard
The primary dashboard starts the full monitoring workspace. src/main.ts prepares presentation, request routing, reporting, service-worker behavior, and the WebMCP boundary before App creates the map and panel system. App owns the WebMCP controller during initialization, so a failed boot can remove agent tools and destroy the partial workspace before the shell shows the failure state. Deep links can select a country, story, chokepoint, search, or stock research view.
References: src/main.ts• L700-746 src/App.ts• L2600-2636 src/App.ts• L3829-3915
Focused web surfaces
Settings and live-channel management avoid constructing the full dashboard. URL flags select their focused startup after localization is ready. The settings window manages saved product choices and feature readiness. The live-channel window manages built-in regional channels and user-defined sources. The embed and MCP grant pages serve partner display and authorization workflows without carrying the main map and panel lifecycle.
References: src/main.ts• L676-699 src/settings-main.ts• L872-974 src/live-channels-window.ts• L48-73 src/…/embed-url.ts• L221-235 src/mcp-grant-main.ts• L45-105
Claim verification surface
The /verify surface gives signed-out users a shareable way to check whether World Monitor sources report a claim. It searches fresh headline caches and builds a coverage card that describes publishers and stated figures without judging whether the claim is true. Published fact-check results load beside the coverage result and do not replace it. A claim in the URL makes the result reproducible and supports browser history navigation.
References: verify.html• L81-114 src/verify-main.ts• L23-47 src/verify-main.ts• L61-130 src/…/verify-claim.ts• L19-24 src/…/verify-claim.ts• L77-134
Web build delivery
The web build keeps the dashboard, focused windows, embeds, MCP consent, and verification as separate browser paths while sharing common code where that does not increase the critical startup cost. The dashboard applies its large stylesheet after the first paint and loads heavy views when they are needed. Service-worker registration waits until after the first paint, then supports later update checks for web users while avoiding desktop and unsafe browser contexts.
References: src/main.ts• L35-53 src/main.ts• L586-620 src/main.ts• L764-856 vite.config.ts• L302-323 vite.config.ts• L1007-1138
Dashboard composition
App is the central coordinator for the primary dashboard. It gives layout, data, user actions, country views, account state, and refresh work one shared application state so the map and panels respond to the same preferences and lifecycle.
Application lifecycle
The dashboard starts in stages. It opens browser storage and translations, localizes the document shell, creates the visible map-and-panel workspace, and prepares account and network state. Fast bootstrap data supports early content. A bounded wait gives slower bootstrap data time to arrive before the visible-data fan-out; if it does not arrive, the dashboard continues and loads visible panels through their normal paths. Below-fold panels load when they approach the viewport.
Slower intelligence work runs after the first usable workspace. Country geometry supports later country analysis, and the correlation engine loads independently after the initial data pass. Optional local AI also starts in the background and does not block layout or basic panels. Connectivity state distinguishes live, cached, and unavailable data so the workspace can explain a degraded start.
The lifecycle keeps access state attached to the running workspace. Account and entitlement changes reconcile saved limits and premium data after the active account is known. Sign-out or downgrade clears account-bound data instead of leaving it visible. Destroying the application first invalidates detached work and agent access, then cancels waits, removes listeners, stops background work, and tears down managers and map services.
flowchart LR
Runtime[Prepare browser runtime] --> Storage[Open local storage and translations]
Storage --> Workspace[Create map and panels]
Workspace --> Fast[Hydrate fast bootstrap data]
Fast --> Slow[Wait for bounded slow-tier checkpoint]
Slow --> Visible[Load visible data]
Visible --> Background[Load geometry and intelligence work]
Background --> Refresh[Start refresh work]
Refresh --> Access[Reconcile account access]
Access --> Running[Running dashboard]
Running --> Destroy[Cancel and tear down]
Workspace -. independent .-> LocalAI[Optional local AI]
References: src/App.ts• L2600-2636 src/App.ts• L2660-2801 src/App.ts• L2803-2831 src/App.ts• L2089-2134 src/App.ts• L3262-3305 src/App.ts• L3829-3915
Shared dashboard managers
The shell assigns separate responsibilities to managers while keeping their state connected through AppContext. Layout owns the workspace. Data loading supplies panel content. Event handling links user actions to URL and saved state. Country intelligence supports country views. Refresh scheduling keeps active data current. This separation lets one surface coordinate many product views without giving each panel its own application lifecycle.
Account and entitlement changes use the same manager links. The dashboard re-runs premium loaders when access becomes available and removes account-bound results when access ends. Country results and other delayed work check the current application and selection before publishing, so a late response cannot replace newer user state.
References: src/App.ts• L1700-1847 src/App.ts• L2831-3106 src/…/app-context.ts• L29-149 src/…/country-intel.ts• L179-244 src/…/event-handlers.ts• L270-454 src/…/data-loader.ts• L1263-1365
Panel and tab composition
Panel layout turns the active variant, saved settings, and account access into a responsive map-and-panel workspace. It supports multiple dashboard tabs, user panel order, collapsed and full-screen states, and deferred heavy panels. Each tab owns its panel selection and focus state, while shared map state remains outside the tab snapshot. Teardown removes observers, timers, controls, and panel resources when the dashboard is replaced.
References: src/…/panel-layout.ts• L259-419 src/…/panel-layout.ts• L817-942 src/…/panel-layout.ts• L1032-1329 src/…/panel-layout.ts• L1960-2137
Focus and map synchronization
Dashboard focus defines the countries that the active tab is about. The shared focus state narrows panel presentation and drives map outlines and fitting. A saved team map view takes priority over automatic fitting, while focus outlines remain visible. The sync waits for the map to exist and drops superseded movement so user navigation stays in control.
References: src/…/focus-map-sync.ts• L3-82 src/…/tab-focus.ts• L22-107 src/…/panel-layout.ts• L1636-1667 src/…/MapContainer.ts• L1900-1930
Agent dashboard interface
WebMCP gives an AI client a controlled interface to inspect and operate the dashboard. It exposes the current map, panels, layers, mission presets, monitor navigation, settings actions, and country views through the same managers used by the human UI. Access checks include account focus and plan access, so the agent sees only actions the current workspace can use.
Actions wait for their owning UI manager and report denied, unavailable, invalid, applied, or unchanged outcomes. They wait for UI and map readiness when needed. App teardown aborts registration, resolves pending waits, and prevents a replaced dashboard from accepting actions.
References: src/App.ts• L2216-2597 src/App.ts• L2600-2606 src/App.ts• L4021-4057 src/…/webmcp-dashboard.ts• L71-160 src/…/webmcp-dashboard.ts• L316-526
Shared runtime services
The shell places common browser concerns around each surface-specific startup. These services set presentation state early, route requests to the correct runtime, collect useful failure and performance signals, and recover from stale deployed assets.
Presentation state
The shell applies theme, variant, font, and font scale before the dashboard is constructed. After translations load, it updates the document title, description, social metadata, and accessible heading. This keeps the first visible frame close to the user’s saved presentation while larger dashboard styles load later.
References: src/main.ts• L646-670 src/App.ts• L2631-2658 src/main.ts• L35-53
Request routing and recovery
The browser installs request attribution and runtime routing before dashboard data work begins. Web deployments use the web API route, while desktop deployments can use a local sidecar. Stale chunk checks and service-worker update checks help an open tab move to a current build after deployment. A boot error is reported, the partial app is destroyed, and the user receives a clear failure screen.
References: src/main.ts• L628-644 src/main.ts• L709-746 src/App.ts• L2763-2801 src/App.ts• L3829-3915
Error and performance reporting
The shell buffers early errors until deferred monitoring services are ready. It reports page and interaction timing and filters known browser-generated policy noise before sending useful violations to telemetry. Sensitive URL values are removed before analytics vendors start.
References: src/main.ts• L56-75 src/main.ts• L84-566 src/main.ts• L609-623
Partner embed composition
The embed surface is a small World Monitor view for a partner page. URL values select the panel, layers, center, zoom, theme, and variant. The surface normalizes these values before mounting the view and reports clear ready or error states to its parent frame.
Embed access and data flow
The embed paints a public view first. If the parent supplies a partner key, the browser exchanges it for a short-lived grant and upgrades the existing view. The frame response controls data readiness, granted layers, and refresh timing. Paid panels check entitlement before rendering, so denied access is visible rather than appearing as incomplete data.
sequenceDiagram
participant Parent as Partner page
participant Embed as Embed view
participant Grant as Grant service
participant Frame as Frame service
Parent->>Embed: Supply view parameters
Embed->>Frame: Request public frame
Frame-->>Embed: Data and layer state
Embed-->>Parent: Show public view
Parent->>Embed: Supply partner key
Embed->>Grant: Exchange key
Grant-->>Embed: Grant or denial
Embed->>Frame: Request granted frame
Frame-->>Embed: Entitled data and refresh timing
References: src/…/embed-url.ts• L11-29 src/…/embed-url.ts• L168-235 src/…/embed-fetch.ts• L99-187 src/…/embed-data-loader.ts• L102-175 src/…/map.ts• L18-77
Embed failure handling
The embed keeps terminal denial separate from temporary service failure. A denied grant returns to the public view. A temporary renewal or frame failure keeps the last usable display and retries later. Keyed requests omit browser cookies so the viewer’s World Monitor account does not become the partner identity.
References: src/…/embed-fetch.ts• L15-71 src/…/embed-data-loader.ts• L178-281
Browser-plugin composition
Browser-plugin composition adapts shared World Monitor views to a host that can provide data, tools, and link actions. The plugin does not own the upstream intelligence services. It validates host messages and turns them into visible news, map, and country-brief state.
News and map view
The news view combines a host-provided news snapshot with panels, filters, search, and map state. It can request a bounded hazard snapshot for natural events or fires and reports effective filters, map state, and data coverage back to the host. Partial or stale data remains visible with an explicit status.
References: src/plugin-main.ts• L32-145 src/plugin-main.ts• L151-217 src/plugin-main.ts• L234-372 src/…/plugin-map-snapshot.ts• L44-85
Country brief view
The country view turns a host-selected country into a source-backed brief. Sections load independently, so an unavailable assessment or signal does not hide sections that remain usable. Revision and cancellation checks keep late results from an earlier country out of the current brief. The view reports section state and source context to the host and uses host capabilities for links, downloads, and model context.
The host handshake establishes tools, link opening, display mode, and model-context support before the view reports readiness. Host actions can change the country, topic, or selected energy asset. Context updates are bounded and marked as acknowledged only when the host confirms them.
References: src/plugin-country-main.ts• L354-440 src/plugin-country-main.ts• L442-532 src/plugin-country-main.ts• L629-787 src/plugin-country-main.ts• L789-914
Management and consent surfaces
Focused management and consent pages keep short workflows separate from the main dashboard. They reuse shared language, account, and network rules where needed, but they do not carry the full map and panel lifecycle.
Settings and live-channel management
The settings surface controls product and presentation choices that the dashboard reads later. It groups optional feature switches and service secrets by product area, shows readiness, and lets users search settings. Values stay staged until required fields and service checks pass, then the surface commits them as one save action.
The live-channel surface controls the saved channel list used by the live news experience. It supports regional built-in channels and custom video and secure HLS sources. Users can search, add, remove, edit, restore, and reorder entries. Source type and secure transport are checked before save.
References: src/main.ts• L676-699 src/settings-main.ts• L84-145 src/settings-main.ts• L288-394 src/settings-main.ts• L780-974 src/live-channels-window.ts• L48-83 src/live-channels-window.ts• L293-425
MCP consent
The MCP consent surface confirms an external AI client’s requested access. It uses a URL nonce and a live session to load request details, then follows only a trusted server redirect after approval. Signed-out users receive a sign-in path. Context and optional profile questions can load separately so the consent action remains available when non-essential data is slow.
References: src/mcp-grant-main.ts• L1-22 src/mcp-grant-main.ts• L45-105 src/mcp-grant-main.ts• L138-249 src/mcp-grant-main.ts• L388-549
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the dashboard entry, deferred stylesheet marker, output document, and production route rewrite aligned.
- Keep focused URL flags separate from normal dashboard startup so settings and live-channel windows do not construct
App. - Keep WebMCP registration, app binding readiness, action readiness, viewport settling, and teardown aligned.
- Keep
AppContextfields and manager callbacks aligned so layout, data, event, country, account, and refresh managers share live state. - Keep bootstrap hydration before the first visible-data fan-out so one-time data is not missed.
- Keep the slow-tier timeout path and the later viewport-trigger path aligned so below-fold panels still load after a degraded bootstrap.
- Keep account handoff ordering aligned with entitlement and premium loader fan-out so one account cannot retain another account’s data.
- Keep optional local AI continuations behind current settings, boot epochs, and app-lifetime checks.
- Keep service-worker registration, stale-bundle recovery, API routing, and cache behavior aligned with the shell each surface needs.
- Keep embed URL aliases, layer IDs, public requests, grants, response readiness, and refresh timing aligned.
- Keep plugin host initialization, capability checks, message validation, revision guards, model-context limits, and pagehide cleanup aligned.
- Keep verification URL state, latest-run guards, coverage results, and fact-check results separate so stale work cannot overwrite a newer claim.
- Keep trusted redirect validation and nonce handling aligned with the MCP authorization service.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Dashboard boot fails after WebMCP registration | An AI client can call tools bound to a dead application | Destroy the partial App and abort its WebMCP controller before showing the boot failure |
| Visible data fan-out runs before slow bootstrap hydration | One-time data is missed and panels make avoidable requests | Wait for the bounded slow-tier checkpoint before the initial fan-out |
| Slow bootstrap times out and no later viewport pass runs | Below-fold panels can remain empty after the first usable view | Keep the deferred fan-out and arm scroll and resize triggers after the initial pass |
| Optional local-AI work resolves after the app is destroyed | A dead app can download a model or restart shared worker state | Invalidate the boot epoch and check app lifetime before each continuation acts |
| Account access changes without clearing or reloading account-bound data | A user can see stale premium or prior-account results | Reconcile access after account handoff and clear data on downgrade or sign-out |
| A late country result ignores revision or cancellation state | The brief shows data for an earlier country | Check the active country, revision, abort signal, and app lifetime before publishing |
| A keyed embed request includes browser cookies | The viewer’s account can become the partner identity | Omit credentials from keyed frame requests |
| A temporary embed failure is treated as terminal denial | A paid view drops to the public layer set during a short outage | Preserve the last usable frame and retry temporary failures |
| A plugin host returns malformed data or denies a required capability | The embedded view can show the wrong state or fail without explanation | Validate host records, track capability state, and expose unavailable or unconfirmed status |
| A stale verification search resolves after a newer claim | Results for an earlier claim replace the current result | Gate every status and render update with the latest run identifier |
| Fact-check lookup failure is treated as no matching fact checks | A service outage looks like evidence that no fact check exists | Return an explicit unavailable state and render it separately from an empty result |
| Consent follows an untrusted redirect | The authorization flow can send the user to an attacker-controlled host | Accept only the trusted API origin returned by the authorization contract |
Key files
| File | Why to read it |
|---|---|
| src/main.ts | Shows shared browser startup, focused surface selection, dashboard boot, routing, reporting, stale-build recovery, and service-worker timing. |
| src/App.ts | Shows central dashboard lifecycle, staged bootstrap and viewport loading, manager composition, account handoff, WebMCP bindings, optional local AI, and teardown. |
| src/…/app-context.ts | Defines the shared dashboard state contract used by the map, panels, data, country views, account state, and refresh work. |
| src/…/panel-layout.ts | Shows map and panel composition, tabs, deferred panels, focus, persistence, access gates, and cleanup. |
| src/…/data-loader.ts | Shows staged bootstrap use and viewport-aware loading for dashboard content. |
| vite.config.ts | Shows web entrypoints, output variants, deferred styles, lazy delivery, and service-worker policy. |
| src/…/embed-url.ts | Defines the partner view contract and accepted URL and snippet forms. |
| src/…/embed-fetch.ts | Defines public frame requests, grant exchange, retry meaning, and credential boundaries. |
| src/…/embed-data-loader.ts | Shows how an embed applies frame data, changes access tier, refreshes, and preserves usable state. |
| src/plugin-main.ts | Shows the plugin news and map lifecycle, host messages, shared UI composition, and cleanup. |
| src/plugin-country-main.ts | Shows country selection, independent brief sections, host capability use, bounded context, cancellation, and cleanup. |
| src/verify-main.ts | Shows the claim verification workflow, shareable URL state, independent fact-check loading, and stale-result protection. |
| src/…/verify-claim.ts | Defines claim search and fact-check contracts and the difference between unavailable and empty results. |
| src/mcp-grant-main.ts | Shows MCP sign-in, consent, context loading, retry handling, and trusted redirect flow. |