Browser plugin country intelligence
The browser-plugin country intelligence surface gives an external host a country brief without loading the primary WorldMonitor application. It combines a small country-view page with a fixed host transport, progressive country data, bounded map, news, and market companion surfaces, and host-managed display modes. See Desktop and external clients, Tauri desktop application, CLI terminal dashboard, SDK client libraries, AI agent plugin integration, and Zapier automation integration for related client flows.
External country-view surface
The country view is a host-rendered WorldMonitor app for country research. A host opens it with a country name or code, and the view presents a country brief with topic navigation, source evidence, risk, resilience, security, economy, resources, and society sections.
Country-view entrypoint
home/…/country.html is the standalone document loaded for the country experience. Its controls let a user enter a country, refresh the country view, or request a new AI assessment. src/plugin-country-main.ts mounts the shared country panel and connects it to the host rather than to the primary application's map context.
The view is designed for an embedded host. It negotiates the host capabilities that it needs, reports its size, accepts the host theme and layout context, opens source links through the host when that capability exists, and can send a rendered snapshot back as model context. Host actions can change the country or topic and open a loaded atlas asset such as a pipeline, storage facility, or fuel shortage. Navigation and credentials remain under host control.
References: country.html• L8-16 src/plugin-country-main.ts• L352-398 src/plugin-country-main.ts• L883-907
Country topics and sections
The country brief groups its data into user-facing topics instead of showing one large undifferentiated report. A topic selects a view of the same country while each section keeps its own loading, ready, locked, or unavailable state.
| Topic | Main question |
|---|---|
| Overview | What is the current country situation? |
| Resilience | How can the country absorb stress? |
| Security | What security signals and activity matter? |
| Economy & trade | What economic and trade conditions matter? |
| Resources & infrastructure | What assets and dependencies matter? |
| Society | What facts and demographic conditions matter? |
| Sources | Which evidence supports the view? |
The shared section map assigns sections to one or more topics. This lets a host request a topic without changing the country identity or inventing a second country-data contract.
References: shared/country-brief-sections.ts• L1-42 src/plugin-country-main.ts• L818-821 src/plugin-country-main.ts• L823-831
Host and transport contracts
The external country view uses JSON-RPC messages over window.postMessage. The page asks the host to initialize the app, call approved server tools, open links, update model context, download a country export, and report its rendered size. The host sends tool input, tool results, theme and layout changes, and responses back to the page.
View lifecycle
When the host starts the page, the country view follows this sequence:
sequenceDiagram
participant Host
participant View as Country view
participant Data as Fixed country readers
Host->>View: ui/initialize
View-->>Host: ui/notifications/initialized
Host->>View: ui/notifications/tool-input
View->>Host: open_country_brief
Host-->>View: country admission
View->>Host: get_country_brief_section
Host->>Data: Fixed reader
Data-->>Host: ready, locked, or unavailable
Host-->>View: section result
View-->>Host: size and model-context updates
The view can queue the requested country until initialization finishes. A country admission is a short-lived host receipt for the selected country. The view passes it with section calls and tracks the request use that the host reports. It cancels stale work when the user changes country or closes the view. This prevents a late response from replacing a newer country. A host without server-tool support can still load the shell, but it cannot hydrate the country sections.
References: src/plugin-country-main.ts• L400-432 src/plugin-country-main.ts• L627-713 src/plugin-country-main.ts• L786-836 src/plugin-country-main.ts• L883-908
Fixed reader contract
shared/country-brief-host.ts defines the trust boundary between the embedded view and country data. The outer view request accepts a country name or code plus a known topic. Section reads select a named reader with bounded arguments; they do not accept arbitrary URLs, headers, methods, or RPC paths.
Every section result carries its section identity and one of three states:
readyincludes the source value and a retrieval time.lockedmeans the host is not authorized for that section.unavailablemeans the source cannot provide the section.
Native observation dates stay inside the returned value. The retrieval time describes when WorldMonitor obtained the value and does not claim that the underlying observation is current.
References: shared/country-brief-host.ts• L4-7 shared/country-brief-host.ts• L9-18 shared/country-brief-host.ts• L40-49 api/…/country-view.ts• L11-37 api/…/country-view.ts• L40-81
Host fetch boundary
The country source presents the approved readers as a normal data client to the shared country controller. createHostCountryFetch converts only allowed WorldMonitor GET requests into get_country_brief_section calls. It checks the returned section and country identity before the result reaches the view.
The boundary limits three active reads and shares in-flight work for the same reader and arguments. It removes aborted requests from its queue, reuses short-lived complete results, and avoids caching incomplete or unavailable upstream data. Country signal families have a bounded read budget so new signal work does not displace the reads needed for the main brief. Raw signal results also have their own envelope limit. This supports progressive loading without allowing a burst of section requests to overwhelm the host. The host supplies authorization; browser credentials and arbitrary request authority do not cross the frame boundary.
References: src/…/country-brief-host-transport.ts• L7-18 src/…/country-brief-host-transport.ts• L23-36 src/…/country-brief-host-transport.ts• L43-87 src/…/country-brief-host-transport.ts• L111-135
Host display modes
The view accepts host layout context as a separate contract from country data. The host can set a theme, safe-area insets, container dimensions, and an inline or fullscreen display mode. The view applies those values to its page, fills a positive-height fullscreen container, reports its content height when it does not fill the container, and shows an expand action only when the host offers fullscreen.
Fullscreen requests must start from the expand button click because the host requires a user gesture. The view keeps the latest host display state when the response arrives and reports a refusal when the host does not grant fullscreen. A revision on display-mode updates prevents a late request result from overwriting a newer host decision.
References: src/plugin-host-context.ts• L6-19 src/plugin-host-context.ts• L43-77 src/plugin-display-mode.ts• L8-27 src/plugin-display-mode.ts• L29-65 src/plugin-country-main.ts• L376-386 src/plugin-country-main.ts• L832-835
Country source modes
The country source gives the shared brief controller one data shape for both the main website and the external host. Website mode uses WorldMonitor's normal service access. Host mode routes service reads through the host fetch boundary and makes raw signals available only through a country host connection.
The source also exposes qualified country signal families and country activity reads through the same boundary. It checks country and family identity before accepting a result. This lets the external view reuse intelligence, supply chain, resilience, risk, market, military, maritime, economic, trade, and prediction data without giving the embedded page a general network client. Host atlas reads bind the requested country before returning asset details, and disruption results are filtered to that country. The controller therefore keeps one country-data shape while the access path changes with the client.
References: src/…/country-brief-source.ts• L13-25 src/…/country-brief-source.ts• L25-56 src/…/country-brief-source.ts• L65-100 src/…/country-brief-source.ts• L148-151
Country intelligence experience
The external country view reuses the country brief model used by the main application but changes where data comes from. It presents the country first, then fills sections independently so one missing or restricted source does not make the whole brief look empty. The host source adapter gives the shared brief controller the same broad country capabilities while routing approved reads through the host.
Progressive country brief
Opening a country normalizes the requested identity, obtains or reuses its host admission, shows the country shell, and starts independent work for risk, assessment, news coverage, timeline events, infrastructure, military activity, raw signals, and country-specific signals. Topic changes reuse the visible brief. Refresh actions can request new source data or a new AI assessment without discarding already visible observations.
The primary application follows the same country-intelligence goal from map clicks, context-menu actions, or agent requests. Its manager owns map highlighting, request ownership, cancellation, and enrichment around the shared country panel. It also projects military activity and other qualified signal families into explicit observed, locked, unavailable, or partial states. A refresh can retain earlier observed families when a new source read fails, while keeping their original observation clocks. The plugin keeps only the part needed for an external host and does not depend on the primary application's map lifecycle. It also sends bounded signal coverage and selected country details back to the host so the external conversation can use the view without receiving an unbounded page dump.
Country economics combine live market and risk context with IMF country indicators when those data are available. The IMF bundle is shared across the economic cards and records source dates so a displayed value is not mistaken for a current observation.
The primary application also builds a compact country timeline from recent coverage and local intelligence. It merges news coverage with structured protest, natural-event, military, conflict, and strike observations, then limits the visible window to recent events. Country matching uses country identity or geographic bounds so the timeline does not treat nearby or unrelated events as local evidence. The same data supports the country story flow when an engineer opens a country narrative from current signals.
References: src/plugin-country-main.ts• L627-783 src/…/country-brief-source.ts• L21-35 src/…/country-intel.ts• L389-617 src/…/country-intel.ts• L1109-1207 src/…/country-intel.ts• L1559-1579 src/…/country-signal-projection.ts• L6-22 src/…/imf-country-data.ts• L93-124 src/…/imf-country-data.ts• L201-207
Evidence and degraded states
The country view treats source state as part of the user-facing result. It keeps dates and source provenance visible, labels access denial separately from source failure, and leaves earlier observations on screen when a refresh fails. A missing section is therefore not presented as zero activity.
Qualified military data combines flight, vessel, and fleet observations only when their scope and time checks pass. It reports partial coverage when one source is missing, stale, denied, or contains invalid dates. The same rule applies to country signal families: an unavailable refresh can retain a prior observed family as partial data, but it does not turn an unknown result into zero activity.
The AI assessment is one part of the brief, not the whole brief. If it is unavailable, other country sections can remain usable. The rendered model context records section states, signal coverage, selected atlas context, and the fact that loading, locked, and unavailable sections are not evidence of no activity. It can also include bounded details for open commodity rows and China decision-signal groups. Large country detail is reduced or omitted before it is sent to the host.
The primary application treats aviation disruption as a bounded country signal. It uses cached flight-delay data when available and can load a short-lived bootstrap snapshot when the aviation layer has not populated that cache. If that read fails or times out, the brief keeps the signal unavailable instead of treating the country as disruption-free.
References: src/plugin-country-main.ts• L103-349 src/plugin-country-main.ts• L440-518 src/plugin-country-main.ts• L699-741 src/…/country-qualified-military.ts• L51-86 src/…/country-signal-projection.ts• L11-22 src/…/country-qualified-signals-harness.ts• L9-16 src/…/country-intel.ts• L1349-1371
Map snapshot integration
The external news plugin provides the map context that can lead a user to country intelligence. It supports news filters, country focus, a country brief handoff, and selected reference or hazard layers without copying the full live application state into the host.
News and country handoff
home/…/plugin.html is the separate news-and-map entrypoint. Its map can focus a country and highlight its geography. Once a country is selected, the plugin enables a country-brief action that asks the host to open the country view in the conversation.
This makes the two external surfaces complementary: the news plugin supports broad scanning and map focus, while the country view supports a structured country investigation. The handoff uses a host message instead of opening an unrestricted page or passing browser credentials to the country view.
References: plugin.html• L10-20 src/plugin-main.ts• L303-317 src/plugin-main.ts• L449-482 src/plugin-main.ts• L495-522
Bounded hazard snapshot
The news map can request a bounded global snapshot for natural events and fires. The snapshot is separate from the news country filter: country filtering changes news, while the hazard request returns selected global map data with a per-source limit. The map view keeps the selected layer state and accepted snapshot coverage together so the host can tell which data is on screen.
The snapshot loader retries with smaller limits when the host reports that the tool result is too large. It validates locations and times before map rendering, records accepted and skipped rows, and keeps earlier map data visible when the new snapshot is denied, unavailable, or invalid.
References: src/plugin-main.ts• L231-270 src/plugin-main.ts• L332-358 src/…/plugin-map-snapshot.ts• L35-55 src/…/plugin-map-snapshot.ts• L57-85 shared/plugin-news-view.ts• L3-18
External market surface
The market plugin is a separate host-rendered surface for compact market snapshots. It lets an external client show selected quote groups and a market sentiment score without loading the primary application.
Market snapshot experience
The market surface receives one host result and turns it into a bounded view of equities, commodities, crypto, Gulf assets, sectors, and projected quotes. It shows source coverage, observed dates, stale state, rate limits, and missing data as part of the snapshot instead of presenting an absent quote as zero.
Rows with an available series can expand to show a chart. The chart reuses the loaded snapshot, so expansion does not create another data request. The surface follows host theme changes and reports its rendered height so it can fit the embedding client.
References: src/plugin-market-main.ts• L11-18 src/plugin-market-main.ts• L38-72 src/plugin-market-main.ts• L75-176 src/plugin-market-main.ts• L178-200
MCP Apps delivery
The MCP surface publishes the country view as a static UI resource and connects it to the open_country_brief tool. The host first receives a validated country and topic, then loads the fixed country document and supplies live data through the section reader.
Resource discovery
The resource URI is ui://worldmonitor/country-view-v1.html. The MCP server fetches the deployed country.html build from the WorldMonitor plugin origin, checks that it is the expected document, adds a base URL, and returns it with a country-view CSP. The static shell is public and data-free; live country data still passes through normal tool calls.
The resource has no frame origins and allows only its WorldMonitor asset origin, the required image source, and data URLs. This keeps the embedded surface narrower than a general web page.
References: api/…/news-dashboard-app.ts• L4-9 api/…/news-dashboard-app.ts• L27-29 api/…/news-dashboard-app.ts• L35-68 tests/mcp-country-view.test.mjs• L66-86
Text and interactive brief boundaries
The interactive country view is intended for requests to open and explore a country. The separate text brief remains the choice when a user asks for a written assessment only. The interactive surface renders the brief, source list, and evidence links while the full country view supports follow-up topic navigation and section reads.
This distinction prevents a host from treating an interactive shell as a plain text answer. It also keeps the data contract clear: open_country_brief selects the view, while get_country_brief_section supplies one reviewed dataset at a time.
References: api/…/country-view.ts• L11-17 api/…/country-view.ts• L40-66 api/…/country-brief-app.ts• L1-19 api/…/country-brief-app.ts• L122-190
Change checklist
When these files or sections are changed, remember to consider these:
- Keep
countryViewSchema,COUNTRY_READERS, the generated client request shapes, andcreateHostCountryFetchaligned. A reader can fail before the host is called when one side changes its argument names or value rules. - Keep the country signal wire-family names, family outcome schema, byte limits, and qualified projection aligned. A mismatch can turn a valid family into an unavailable section or allow a result for the wrong country.
- Keep the host reader cache, in-flight request sharing, read budget, and shared source adapter aligned with section freshness rules. Reuse must not preserve an upstream-unavailable or incomplete country result.
- Keep host and website source modes aligned with the shared country controller. A new service must use the host boundary when the external view needs it.
- Keep military geographic projection, source freshness checks, denied fields, and coverage notes aligned. A zero count is valid only when the source has enough coverage to support absence.
- Keep the country admission receipt aligned with
open_country_brief, section calls, usage reporting, expiry checks, and refresh behavior. A stale or wrong-country receipt must not authorize a new view. - Keep the country-view-v1.html URI, the MCP tool metadata, resource discovery registry, deployed country.html entrypoint, and server card aligned. A mismatch can leave the tool pointing to a resource that the host cannot load.
- Keep
CountrySectionErrorstates mapped to the view'slockedandunavailablestates. Converting either state to an empty success result hides access or source failures. - Keep IMF indicator fields, release metadata, and the economic-card row limit aligned. Missing bootstrap data must remain a missing indicator rather than a zero value.
- Keep map layer names and hazard snapshot coverage fields aligned with the news plugin receipt. The map can otherwise show a layer as active without a valid snapshot for it.
- Preserve country identity checks when adding a reader or changing its response shape. A response for a different country must not update the visible brief.
- Keep market group names, snapshot field shapes, and usage metadata aligned with the host result. A valid response can otherwise render as an empty market surface.
- Keep the primary country signal counts aligned with timeline event inputs and aviation fallback behavior. A new signal can appear in the brief while remaining absent from the timeline or incorrectly reported as zero when the layer cache is cold.
- Keep host-context fields, display-mode revisions, layout flags, and the expand request aligned. A stale fullscreen response must not replace a newer host layout update.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Host does not advertise server tools | The country shell loads but cannot fill its sections | The view reports that connected country tools are unavailable and does not treat the shell as a loaded brief |
| A country admission is expired, malformed, or for another country | The view could use a receipt for the wrong request or fail to open the selected country | The view validates the receipt country and expiry before use and obtains a new admission when needed |
A section reader returns locked or unavailable | One section cannot show data | The view keeps the state distinct and leaves other sections available |
| A reader returns the wrong section or country | Data could appear under the wrong heading or country | The host transport rejects section and country identity mismatches |
| More than three country reads are active | A burst of progressive loads could overload the host | The transport queues later reads and removes aborted work |
| New qualified signal families consume the reserved read budget | Existing country sections can be delayed or a new family can be deferred | The transport reserves budget for mandatory reads and reports deferred families as unavailable rather than as zero |
| All subscribers cancel an in-flight country read | Work can continue without a visible consumer | The transport aborts the shared host call when its last subscriber leaves |
| Military flight, AIS, or fleet input is stale, denied, or incomplete | The brief can show a partial view of military activity | Source time checks, denied-field tracking, and coverage notes keep unsupported absence as unknown |
| A qualified signal refresh fails after an earlier observation | A current failure could erase useful prior evidence or imply no activity | Projection retains an earlier observed family as partial data and keeps its original clock |
| A hazard response exceeds the host output budget | The map refresh cannot apply new hazard data | The snapshot loader retries with smaller limits and preserves prior map data on failure |
| The country view changes while a read is pending | Late data could overwrite the new country | The view aborts stale requests and checks the current country and revision before updates |
| IMF bootstrap data is missing or has no value for a country | Economic cards have incomplete coverage | The bundle returns null entries and the panel omits unsupported indicators instead of displaying zero |
| A market response is projected, stale, rate limited, or missing a quote group | The user can mistake a partial snapshot for complete market coverage | The market surface labels snapshot state and source coverage and only charts loaded series |
| The primary app opens a country while its signal aggregator or aviation data is unavailable | The brief can lose cluster-derived or airport disruption context | Independent caches degrade to partial signal coverage, and the aviation read is bounded rather than blocking indefinitely |
| Timeline inputs use stale, invalid, or out-of-country events | The country timeline can show false local activity | The timeline filters by recent time and country identity or geographic bounds before reconciliation |
| The host changes display mode while a fullscreen request is pending | The view can apply an old mode or show the wrong expand control | Display-mode revisions preserve newer host state, and layout flags derive the control from the latest context |
| The host refuses a fullscreen request | The view remains embedded even though the user selected expand | The expand control reports the refusal and keeps the host's current display mode |
Key files
| File | Why to read it |
|---|---|
| country.html | Shows the standalone country-view entrypoint and its user actions. |
| src/plugin-country-main.ts | Explains the country-view lifecycle, host messages, admissions, progressive loading, display modes, host actions, and rendered context. |
| src/plugin-host-context.ts | Defines the host theme, display-mode, size, and safe-area context used by external views. |
| src/plugin-display-mode.ts | Applies host layout state and defines the user-gesture fullscreen request. |
| shared/country-brief-host.ts | Defines the approved country input, reader, and result contracts. |
| src/…/country-brief-host-transport.ts | Shows how approved browser fetches become bounded and shared host tool calls. |
| src/…/country-brief-source.ts | Connects the shared country controller to either the website or the external host. |
| src/…/country-qualified-military.ts | Shows how country military observations become bounded, time-checked, and qualified results. |
| src/…/country-signal-projection.ts | Shows how signal families are combined and how prior observed data survives a failed refresh. |
| src/…/country-intel.ts | Shows how the primary application opens, enriches, timelines, and refreshes the same country experience. |
| src/…/imf-country-data.ts | Explains the shared IMF economic bundle and its source-date-aware indicators. |
| src/…/country-qualified-signals-harness.ts | Provides a controlled observed or unavailable country-signal view for checking degraded states. |
| src/plugin-main.ts | Explains the companion news plugin, country handoff, and map state. |
| src/…/plugin-map-snapshot.ts | Defines the bounded hazard snapshot used by the external map. |
| src/plugin-market-main.ts | Explains the separate market snapshot surface and its host result handling. |
| api/…/country-view.ts | Defines the MCP tools that select a country view and read its fixed sections. |
| api/…/news-dashboard-app.ts | Defines the country resource URI, CSP, and deployed document loading. |
| api/…/country-brief-app.ts | Shows the separate compact text-brief presentation contract. |