# Geography, facts, and source attribution

## Shared-border revision (October 2026)

Current mainland display geometry uses geoBoundaries CGAZ ADM0 (CC BY 4.0),
simplified as a common coverage to preserve matching international borders.
This supersedes the individual country-boundary refinements described below
for IDs listed in `public/data/shared-boundary-provenance.json`. Selected shapes
and close-zoom neighbor layers share the same inland coordinates. Regional
files are loaded on demand from `public/data/map-shared/`; original geometry
remains in source for provenance and regeneration. Read
[the method, political conventions and precision limits](docs/SHARED_BOUNDARIES.md).

## Small-island coastline registration (October 2026)

Silhouettes of many small and remote islands sat beside the satellite imagery,
often by 0.5–2 km. The imagery and renderer were checked and are correct: a
known-correct test raster lines up with the silhouette layer to the pixel, and
fresh Sentinel-2 L2A scenes agree with well-surveyed coasts (Malta, Barbados,
Mauritius, Havana, Reykjanes) to within ~150 m. The offset was in the legacy
GSHHG / Natural Earth island geometry itself, which places some islands in the
wrong spot (Funafuti 1.6 km, Majuro ~1 km, Palau 0.9 km). The direction varies
from island to island; it is not a datum or tiling shift.

`scripts/repair-osm-island-coastlines.py` registers every small-island group
(components under 5,000 km², clustered within ~5 km) against OpenStreetMap
`natural=coastline` land, read from the Overture Maps base/land theme (ODbL 1.0).
Groups that are offset by 250 m or more, or that overlap their OSM coast poorly,
receive whole, unshifted OSM islands assigned to their nearest atlas component.
Islands with a land border, large landmasses, and groups whose OSM coverage is
missing or disagrees in area are left unchanged. Each asset applies its usual
tolerance (15 m below 25 km², 50 m below 1,000 km², capped by the asset's own)
and minimum island area, and untouched components keep their exact coordinates.
Display, shared-map, overview and canonical files change together, so the
silhouette, the close-zoom outline and scoring keep using one shape, and the
existing 3 km close-zoom transition is unchanged. The per-group measurements are
in `public/data/coastline-repairs/osm-island-coastlines.json`.


Current atlas snapshot: **13 October 2026**. This document distinguishes source detail, additional simplification, political grouping, and the actual geometry used by the games. Live services and source dates differ; no layer is presented as a uniform, current survey.

## Current game geometry

The active games use 195 countries, 52 qualifying territory shapes representing 50 administrative groups, and sourced capital/seat identities. The broader atlas contains **277 context entries** including the countries; the metropolitan index contains **202 capital records** across all 195 countries. Historical holdings, ordinary subdivisions, associated states, and flagged disputed claims are not silently included in the current-territory count. The count follows this app's documented grouping policy.

Four geometry levels are deliberately separate:

| Metadata / asset | Purpose and limits |
|---|---|
| `world-countries.geojson`, `world-territories.geojson` | Startup overview, derived from the same home extent as the game. Additional simplification is 15 m for areas under 25 km², 150 m under 1,000 km², 1,000 m under 10,000 km², and 5,000 m for larger countries; large countries omit components below 3 km². Effective tolerance is at least that already present in display geometry. |
| `homeGeometryUrl`, `mainlandGeometryUrl`, `displayGeometryUrl`, `mapGeometryUrl` | Aliases of the **same bounded canonical game geometry**, stored under `public/data/display`. Silhouettes and nearest-boundary scoring use this shape. Files are at most 880,373 bytes in this snapshot. Additional tolerance is 15 m for tiny states, 50 m for small places, and 150–1,800 m for larger files; some large-country files omit offshore components below 1, 3, or 5 km². Each feature records its actual tolerance and minimum component area. |
| `homeDetailedGeometryUrl` | Preserved detailed home coastline under `public/data/home`, loaded by the map worker only at close zoom. It is not parsed to begin a world-scale round. |
| `geometryUrl` | Full national/context source-derived geometry under `public/data/countries`, retaining source provenance and any remote holdings. |

The word `mainland` in a URL field denotes the game's focused home extent: it does **not** discard a home archipelago. Reviewed component selections include France's European land and Corsica; Spain's mainland and Balearics (Canary Islands, Ceuta and Melilla are separate); continental Portugal; Norway without Svalbard/Jan Mayen; New Zealand's main islands; continental Chile/Ecuador; Australia with Tasmania; and the United States with Alaska but without Hawaii. Selection boxes choose whole sourced components rather than drawing replacement coastlines. Geographic label anchors lie on the dominant home land.

The Morocco home shape is cut against the sourced northern Western Sahara boundary. Western Sahara is a separate complete disputed context shape, avoiding presenting its internal control line as an undisputed international border. The Vatican enclave cut uses the actual Vatican feature. Country labels, fills and game borders use the same atlas source rather than mixing another basemap's geopolitical interpretation.

Find distances use closest great-circle boundary segments on a mean-radius Earth sphere, including holes and containment. They are exact to the scoring geometry and numerical method, **not to an unsimplified legal or physical boundary**. These additional LOD tolerances and omitted tiny components can affect near-zero distances and are disclosed by the game. A contour is an adaptively sampled distance field from the same geometry, with stated rendering resolution and numerical tolerance; truncated results must not be displayed as complete. `nearestCountryIds` is only a precomputed approximate choice-list aid: it uses further 1 km simplification and up to 10 km boundary samples. It never replaces the scoring worker's segment distance.

## Earlier island collections retained for expansion

The app deliberately separates political places from physical islands:

| Pool file | Contents | What the answer names |
| --- | --- | --- |
| `countries.geojson` | 45 curated independent island countries | The country, including its island group and its actual portion of any shared island |
| `territories.geojson` | The same 45 countries plus 37 island territories, states, and regions | One political or regional group per answer |
| `islands.geojson` | 126 curated notable physical islands | One actual named island, regardless of political ownership |
| `world-countries.geojson` | Exactly 195 countries | UN 193 member states plus the Holy See and State of Palestine |
| `world-territories.geojson` | 277 context targets | The same 195 countries plus dependencies, disputed administrative areas, and curated regional groups |

This is a supported selection, not an exhaustive inventory of every country,
territory, rock, or cay. The original 73 geographic-island IDs are retained. The
broader selection includes Barbados, Dominica, Grenada, Saint Lucia, Malta, Nauru,
Bahrain Island, Singapore Island, and other notable islands that were missing from
the initial pool. Australia is treated as a continent rather than a quiz island.

In the country pools, **Haiti and the Dominican Republic are separate answers**;
neither accepts “Hispaniola.” The United Kingdom includes Great Britain and Northern
Ireland. Japan and Indonesia each form one multipart country target. In ALL islands,
Hispaniola, Honshu, and individual Indonesian islands remain geographic targets.
Country IDs use `country-` plus Natural Earth's three-letter admin code. Territory
IDs use `territory-`; country entries retain identical IDs and geometry in both
political pools, so progress can be shared between them.

**Hawaii is one grouped answer in the territories pool**, with `kind: territory`
and `status: US state`. Its constituent islands are separate answers in ALL islands.
Here `territory` is a broad UI category that also includes clearly labeled states,
overseas regions, Crown Dependencies, and freely associated states. It does not
claim these places all have the same constitutional status. Mainland countries
such as the United States and France are not added as country targets merely
because they have island territories. Cook Islands and Niue are labeled as
self-governing states in free association with New Zealand in the broader pool.

## Physical-island coastlines

The playable islands use **real land–ocean coastline polygons from GSHHG 2.3.7**,
released 15 June 2017 by Paul Wessel (University of Hawaiʻi, SOEST) and Walter H. F.
Smith (NOAA). GSHHG combines World Vector Shorelines and other geographic sources.
The bundled island geometry is a derived extract of its full-resolution coastlines,
not administrative country borders. Shared islands such as Borneo, Hispaniola,
New Guinea, and Tierra del Fuego therefore remain whole islands.

- [GSHHG official project and download page](https://www.soest.hawaii.edu/wessel/gshhg/)
- [Original shapefile archive](https://www.soest.hawaii.edu/pwessel/gshhg/gshhg-shp-2.3.7.zip)
- [Official dataset documentation](https://www.soest.hawaii.edu/wessel/gshhg/README.TXT)
- Wessel, P., and W. H. F. Smith (1996), *A global, self-consistent, hierarchical,
  high-resolution shoreline database*, Journal of Geophysical Research 101(B4),
  8741–8743. [DOI: 10.1029/96JB00104](https://doi.org/10.1029/96JB00104).

## License

The source archive's `LICENSE.TXT` licenses GSHHG under **GNU LGPL version 3 or
later**. The original license, LGPL text, README, and shapefile notes are reproduced
in `public/data/GSHHG-*`. The source README contains an older conflicting reference
to “v3 or any earlier version”; this project follows the explicit `LICENSE.TXT`.
The derived geometry retains the GSHHG license. Keep these notices when distributing
the dataset. The application source code is separate from this licensed data.

Suggested on-map attribution: **Coastlines: GSHHG · Wessel & Smith · LGPL**,
linked to the official project. The app's background map has its own attribution
and terms, separate from these bundled island polygons.

## How the extract is made

`public/data/island-catalog.json` is a human-readable selection catalog containing
names, accepted aliases, an interior point, region, ocean, country/territory label,
practice difficulty, and a short geographic fact. Names and grouping are curated
application metadata; GSHHG identifies polygons with numeric IDs, not island names.
Regions are practice groupings, not claims about sovereignty: Hawaii is grouped
with Oceania, Cyprus with Europe, Rapa Nui with South America, and subantarctic
South Georgia with Antarctica. Country fields are descriptive labels; they do not
attempt to adjudicate territorial disputes.

The generator:

1. Downloads the original archive into the operating system's temporary directory
   or opens a supplied copy. The archive is not required when running the app.
2. Reads `GSHHS_shp/f/GSHHS_f_L1`, the **full-resolution land/ocean coastlines**, and
   `GSHHS_shp/f/GSHHS_f_L5`, the Antarctic ice-front coastline layer.
3. Selects the actual polygon containing each catalog interior coordinate. It fails
   if no source polygon contains a point. Missing islands are never approximated.
4. Preserves every source vertex for islands with 1,200 or fewer vertices. Outlines
   with 1,201–20,000 vertices receive a topology-preserving 40-meter simplification;
   very large outlines with more than 20,000 vertices use 150 meters. Distances use
   a local equirectangular projection at the catalog latitude to reduce delivery size.
5. Orients exterior rings counterclockwise, rounds coordinates to six decimal
   degrees, and writes a compact WGS84 GeoJSON `FeatureCollection`.
6. Records upstream polygon ID, source layer, original vertex count, and
   simplification tolerance on each feature. `public/data/provenance.json` records
   the source URL, downloaded archive's SHA-256 digest, feature count, and byte size.

The **same final feature geometry** drives both the map highlight and silhouette.
The current map uses the actual tiny coastline as a thin waymark rather than point
circles. Holes and multipart geometries are supported by the schema.
The source's separate inland-lake layer is not incorporated: this is specifically
a coastline recognition dataset, so inland lakes are not cut out of silhouettes.

## Accuracy and limits

“Full resolution” means the original GSHHG resolution, not a uniform survey accuracy
or a promise that every shoreline vertex is within 40 meters of today's shore. The
40/150-meter values are **additional simplification tolerances**, not source accuracy.
GSHHG's source surveys vary in age and detail. The upstream documentation notes
that some old coastlines are offset relative to modern imagery, and that coastlines
and ice fronts change. Small islands retain all the detail present in the source;
zoom does not invent additional detail. This educational map is not for navigation.

## Rebuild or add an island

Use Python 3.11 or newer:

```sh
python -m pip install shapely pyshp
python scripts/generate-islands.py
```

Reuse an existing archive or change simplification explicitly:

```sh
python scripts/generate-islands.py --archive /path/to/gshhg-shp-2.3.7.zip
python scripts/generate-islands.py --tolerance 0
```

To add an island, append an entry to `public/data/island-catalog.json`, choosing a
unique stable `id` and a `center` in `[longitude, latitude]` order **on the island's
land polygon**. Use one of the existing seven region labels and `easy`, `medium`,
or `hard` difficulty. Give the island's name, not an archipelago name. Run the
generator and inspect both the selected coastline and silhouette. Verify that the
source polygon ID differs from existing entries and its bounds match the intended
island. Islands crossing the antimeridian need explicit multipart reassembly before
being added: this initial selection avoids that ambiguity.

The generator validates polygon topology and center containment. Runtime testing
also checks ring closure, numeric coordinate ranges, duplicate IDs, all seven
regions, and the required small islands.

## Political boundaries and grouped places

The political answer pools combine GSHHG with **Natural Earth version 5.1.1,
1:10,000,000 admin-0 countries and map units**. “10m” in Natural Earth's filenames
means **10 million scale, not 10-meter accuracy**. Natural Earth data is public
domain. It is a cartographic source, not an official survey of legal boundaries.

- [Natural Earth admin-0 countries documentation](https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-0-countries/)
- [Natural Earth map-unit documentation](https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-0-details/)
- [Natural Earth terms of use](https://www.naturalearthdata.com/about/terms-of-use/)
- [Countries source archive](https://naciscdn.org/naturalearth/10m/cultural/ne_10m_admin_0_countries.zip)
- [Map-unit source archive](https://naciscdn.org/naturalearth/10m/cultural/ne_10m_admin_0_map_units.zip)

Natural Earth's default boundaries represent **de facto control**. For example,
the Cyprus country target follows the source's Republic of Cyprus footprint; it
is not the complete geographic island of Cyprus. The geographic pool contains the
whole island. Labels and geometry are educational cartography rather than a claim
to settle disputed sovereignty.

`scripts/generate-places.py` associates full-resolution GSHHG coastlines with the
Natural Earth country or map-unit footprints. A 0.025-degree search buffer allows
for differing source coastline registration; it is only a search aid and is never
rendered. Small islets near two units are assigned to the closest/best-overlapping
actual footprint, rather than both. GSHHG land polygons below 0.02 km² are omitted
from the grouped pools to avoid an excessive number of minute coastal rocks.

For shared islands, the generator extracts the actual shared land-border lines
from adjacent Natural Earth polygons and splits the GSHHG coastline with those
lines. It extends each border's end segment by up to 0.12 degrees into the sea so
that small differences in shoreline registration do not prevent a split. The
interior border follows the source coordinates; this preserves actual detailed
coastlines while separating Haiti/Dominican Republic, Ireland/United Kingdom,
Indonesia/Malaysia/Brunei, Indonesia/Papua New Guinea, and Timor-Leste/Indonesia.
If a reliable split cannot be formed, the intersecting Natural Earth political
polygon supplies the clipping boundary. If a Natural Earth island component has
no corresponding GSHHG component, its **real Natural Earth polygon** is retained
and identified as a fallback. This matters especially for tiny atoll components.

Each political feature records `sourceTypes`, `sourceIds`, `sourceAdmin`, and
`boundaryMethods`, including fallback counts. `places-provenance.json` records
source archive URLs and SHA-256 digests. Large coastlines use the same 40/150-meter
additional simplification rules described above. This process does not raise the
accuracy of Natural Earth's political borders to GSHHG coastline detail.

Hawaii uses the Natural Earth United States footprint within the Hawaiian island
chain's geographic bounds; the source separately classifies US Minor Outlying
Islands, so Midway is excluded from the state group. Réunion, Mayotte, Guadeloupe,
Martinique, Madeira, and the Azores use explicit map-unit records. Easter Island
uses the Chilean footprint in Rapa Nui's geographic bounds, rather than the entire
country of Chile. Saint Helena, Ascension Island and Tristan da Cunha now have
separate atlas cards and outlines, extracted from the existing detailed `SHN`
source. Their shared `administrativeGroupId: 'shn'` counts once under the
[2009 constitution](https://www.legislation.gov.uk/uksi/2009/1751/contents).
No country/territory outlines are drawn as fabricated circles,
rectangles, or manually invented silhouettes.

Grouped archipelagos such as Fiji and Kiribati cross the antimeridian. Coordinates
remain canonical WGS84 longitude/latitude; display code must compute wrap-aware
bounds rather than using a naïve -180-to-180 rectangle.

Rebuild the political pools and optionally refresh the physical-island supplement:

```sh
python scripts/generate-places.py
python scripts/generate-places.py --expand-islands
```

After the supplement has been added to the shared `island-catalog.json`, the original
`generate-islands.py` can also rebuild the entire geographic pool from GSHHG. The
`SUPPLEMENT` table in `generate-places.py` documents the initial additional named
islands and their interior selection coordinates. Add future political targets to
the explicit `COUNTRIES`, `TERRITORIES`, or `MAP_UNITS` lists and review their status,
aliases, border cuts, island coverage, and map/silhouette rendering before release.

## Bundled world basemap

`public/data/world-land.geojson` is Natural Earth's **1:50 million land** dataset,
downloaded from its official repository:
[ne_50m_land.geojson](https://github.com/nvkelso/natural-earth-vector/blob/master/geojson/ne_50m_land.geojson).
Natural Earth data is [public domain](https://www.naturalearthdata.com/about/terms-of-use/).
This contextual world map is deliberately less detailed than the selected target's
coastline. It remains a local fallback. The normal street-map view adds detailed
OpenStreetMap water, roads and buildings through OpenFreeMap, and the
optional satellite view uses EOX's openly licensed 2016–17 Sentinel-2 mosaic.
Online context is independent of the bundled answer geometry. The local graticule,
country labels, silhouettes and answer checking require no tile key or paid service.
See [MAP_SOURCES.md](MAP_SOURCES.md) for provider URLs, exact attribution, imagery
dates, resolution limits, NASA fallback, and custom licensed imagery configuration.

## Worldwide atlas and lazy detailed geometry

`scripts/generate-world.py` builds the exact **195-country core** defined by the
[193 United Nations members](https://www.un.org/about-us/member-states) and the
[two non-member observer states](https://www.un.org/en/about-us/non-member-states):
the Holy See (represented by Vatican City's territory) and the State of Palestine.
Taiwan, Kosovo, Western Sahara, Northern Cyprus, dependencies and other separately
administered areas are context targets outside this core, with explicit status
labels. These labels do not resolve sovereignty disputes. The context index also
retains the curated regional targets, including Hawaii as a US state.

Region labels were audited for **all 195 countries** against the
[UN M49 geographic regions](https://unstats.un.org/unsd/methodology/m49/) on
2026-10-12. The game combines Caribbean, Central American and Northern American
countries under North America. The resulting country counts are Africa 54,
Asia 48, Europe 44, North America 23, South America 12 and Oceania 14.
In particular, Mauritius, Seychelles and Comoros are African; Maldives and
Sri Lanka are Asian. A Natural Earth `Seven seas (open ocean)` value is never
treated as a continent or silently converted to Oceania.

Dependencies are grouped by their own geography rather than the sovereign
country's continent: Greenland and the Caribbean dependencies are North American,
Réunion and Mayotte African, Azores European, and Hawaii and Polynesian Rapa Nui
(Easter Island) Oceanian. For the seven-region study filters, the existing physical
geography convention puts Madeira in Africa, Australia's Christmas/Cocos group
in Asia, and the subantarctic French Southern, Heard/McDonald and South Georgia
groups in Antarctica. These explicit conventions differ from UN statistical
groupings for some dependencies; they are filters, not political status claims.
The mixed US Minor Outlying Islands group is assigned to its predominantly Pacific
location, Oceania. British Indian Ocean Territory follows M49's Africa grouping.

`python scripts/audit-regions.py` compares every core country with an independent
reviewed ISO3 roster and checks the context targets against the generator policy.
`--write` repairs region metadata, matching region sentences and provenance across
all quiz indexes and individual detail files; it verifies that geometry hashes
are unchanged. `scripts/validate-world.py` also checks all 195 assignments and
cross-pool/index/detail consistency, including the Indian Ocean regression cases.

Brunei remains a worldwide country, but is intentionally excluded from the curated
island-country collection: it occupies part of Borneo. The island collection keeps
the previously requested shared-island countries, including Haiti, the Dominican
Republic, Papua New Guinea and Timor-Leste; `islandType: shared-island` distinguishes
them from countries made up of whole islands. “All islands” is still the curated
126 physical islands, never a claim to enumerate every island on Earth.

The two world indexes contain overview polygons, names, on-land centers, statistics,
capital points, flag paths, aliases and geometry URLs. Their current overview is a
simplification of the home/display geometry described at the top of this document,
not the older national-footprint overview. It is for distant rendering; the
selected silhouette loads canonical display geometry. Each full `geometryUrl`
still points to a local GeoJSON **Feature** under `public/data/countries/`.

For coastal countries, detailed polygons combine GSHHG full-resolution shorelines
with Natural Earth's political boundaries. The generator expands each country's
source footprint into surrounding ocean by 0.075 degrees, excludes adjacent
countries' actual source land, then intersects that selection mask with GSHHG.
The expansion is a source-registration aid, never a displayed outline. GSHHG
coordinates supply the real coast. Shared land borders remain at their sourced
Natural Earth positions. The GSHHG shorelines receive **at most 40 m** additional
topology-preserving simplification, measured in a local equirectangular projection;
small coastlines are kept at full source detail. Missing GSHHG components retain
their genuine Natural Earth outline, counted in `fallbackComponents`. This method
cannot manufacture modern survey accuracy, resolve every political dispute, or
recover land reclamation absent from the 2017 shoreline source. Narrow coastal
border junctions can reflect differences between the two source datasets.

For landlocked countries, the generator uses the full-resolution open ADM0 releases
from [geoBoundaries](https://www.geoboundaries.org/api.html), with at most 40 m
additional simplification. Source dates and precision vary by country: “full
resolution” describes the supplied file, not uniform survey accuracy. Each feature
retains `geoBoundaries.boundaryID`, year represented, original source, license and
pinned download URL. The current metadata snapshot points to release commit
`9469f09`. Its Git LFS geometry is downloaded through GitHub's media endpoint.
Original licenses include ODbL, Creative Commons attribution/share-alike variants,
public domain, Open Government Licence and swisstopo's license. The individual
source attribution and license links travel with each detailed Feature; these
files must not be redistributed under a blanket application-code license.

## Population, land area, capitals and flags

Population uses the latest non-null [World Bank SP.POP.TOTL value](https://data.worldbank.org/indicator/SP.POP.TOTL)
and land area uses [AG.LND.TOTL.K2](https://data.worldbank.org/indicator/AG.LND.TOTL.K2),
retrieved from the official API over 2015–2026. Every value carries its actual
observation year and source URL; a 2024 land-area observation is not labeled 2026.
World Bank land area excludes inland waters. The indicator definitions and
[World Bank dataset license](https://datacatalog.worldbank.org/public-licenses#cc-by)
apply (CC BY 4.0 with the cited upstream sources). Where population is unavailable,
Natural Earth's explicitly dated estimate is retained. Vatican City instead uses
its government's [882 residents at 31 December 2024](https://vaticanstate.va/en/state-and-government/general-informations/population.html)
and [official stated territory of 0.44 km²](https://www.vaticanstate.va/it/stato-e-governo/note-generali/geografia.html).

Capital points come from [Natural Earth populated places](https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-populated-places/)
(public domain), with reviewed current corrections and role labels. Notable
corrections include Gitega, Dodoma, Ngerulmud and **Ciudad de la Paz**, designated
Equatorial Guinea's capital on [2 January 2026 by the national government](https://www.guineaecuatorialpress.com/noticias/el_presidente_de_la_republica_proclama_la_ciudad_de_la_paz_como_capital_de_la_republica_de_guinea_ecuatorial_con_la_firma_de_un_decreto_ley).
South Africa's three capitals and Bolivia's constitutional/administrative roles
are recorded separately. Nauru's Yaren is a seat of government, not an invented
official capital. Bern is labeled federal city. Palestine records claimed East
Jerusalem and administrative Ramallah; Jerusalem's disputed status is explicit.
These are real named city points, not guessed city extents.

`scripts/generate-capital-boundaries.py` provides verified administrative outlines
for **60 primary capitals**, including municipal extents, clearly labeled capital
regions, federal districts and city-states. Discovery links the Natural Earth city
identity through Wikidata's P402 identifier to an OpenStreetMap administrative
relation. The relation must match the city's identity, contain its recorded point,
and have complete closed outer/inner ways. Ambiguous or incomplete candidates are
left unavailable. Examples include **Paris (7444), Berlin (62422), and the District
of Columbia (162069)**. The generator uses cached, sequential, batched requests at
dataset-build time; the browser never queries Overpass.

Outer and inner way members are polygonized without fabricating a hull or radius.
The files preserve relation IDs, administrative levels, extent labels, source
timestamps and © OpenStreetMap contributors attribution, and are licensed under
[ODbL 1.0](https://www.openstreetmap.org/copyright). Vatican City and Monaco reuse
their coincident city-state boundaries. `capital-boundary-index.json` records
availability for all 195 primary capitals, and `merge-capital-boundaries.py` adds
only the correctly matching city's outline to each country record. Secondary
capitals never inherit a different city's polygon. Unavailable records say that no
municipal outline is bundled. Administrative extent can differ from continuous
built-up urban area; a point or satellite image is never presented as a city boundary.

### Capital metropolitan/built-up footprints

The current capital games use a separate complete set of **202 source-derived urban footprints**, not the older partial municipal index. `public/data/metropolitan-index.json` retains source URLs, observation year, resolution, method and caveats for every record. `metropolitan-overview.geojson` is about 1.45 MB; individual files are lazy loaded. These footprints represent settlement patterns, not official metropolitan commuting regions or municipal jurisdiction.

- **175 urban centres and 18 dense urban clusters** use [GHSL GHS-SMOD R2023A, V2-0](https://human-settlement.emergency.copernicus.eu/ghs_smod2023.php), observed in 2020, from its 1 km Mollweide settlement grid. The polygon edges retain that grid's scale; a finer-looking satellite background does not make these 1 km boundaries precise street edges. License: CC BY 4.0. Cite the European Commission Joint Research Centre dataset and **Pesaresi et al. (2024), “Advances on the Global Human Settlement Layer by joint assessment of Earth observation and population survey data,” International Journal of Digital Earth, 17(1)**, under the [GHSL citation guidance](https://human-settlement.emergency.copernicus.eu/GHSLhowToCite.php).
- **Seven small or exceptional capitals** use the [DLR World Settlement Footprint 2019](https://geoservice.dlr.de/eoc/ogc/stac/v1/collections/WSF_2019?f=html), a 10 m binary settlement product, CC BY 4.0. Ciudad de la Paz, Palikir and Ngerulmud retain the 10 m working grid. Vaduz, Lobamba, Yaren and Canberra use 40 m maximum aggregation and documented connected-component selection after gap closing (320 m, or 800 m for Canberra). These operations join observed settlement patches; they do not create a circular or convex-hull city. The source and processing limitations remain on each feature.
- **Monaco and Vatican City** use their coincident city-state outlines, retaining those source licenses, to avoid incorrectly treating Nice or Rome as the capital footprint.

Tokyo's source urban agglomeration is cut by verified OSM city polygons for Yokohama (relation 2689482), Kawasaki (2689476) and Chiba (2679956); those exception cuts carry ODbL attribution. Brazzaville and Kinshasa are clipped at their national boundary rather than merging both cities across the river. Gitega's point is corrected using [Wikidata Q167551](https://www.wikidata.org/wiki/Q167551). These are documented exceptions, not hand-drawn silhouettes. Sourced capital names/roles remain independent of the footprint method.

### Current, historical, and disputed relationships

`home-geography-index.json` and feature metadata preserve `parentCountryId`, `relationshipType`, `countsAsTerritory`, `relationshipSource`, `relationshipAsOf`, and `disputeNote`. The 2026-10-13 count policy includes 50 separately represented current overseas dependencies/regions and excludes ordinary subdivisions, associated states, historical holdings, and every flagged unresolved claim. Special statuses—including Crown Dependencies, freely associated states, and overseas constituent countries—remain explicit.

`connections.json` contains **65 current relationship links** and **18 curated historical examples**. Current links include context relationships that are deliberately not part of the narrower count. Dated arrangements, historical periods, concise relationship facts and their sources remain explicit; constitutional status dates are not assumed to begin every historical connection. Modern outlines linked by an arc do not depict a historical empire's borders. The historical set is a documented sample, not a complete colonial history.

The Dominican Republic's four historical links use one route per partner. Semicolon-separated ranges explicitly preserve interrupted Spanish rule and separate US interventions. Sources include the [Dominican foreign ministry's history](https://mirex.gob.do/historia-rd/), [Spanish state archives](https://www.cultura.gob.es/cultura/archivos/difusion/mc-difusion/bicentenarios/contexto-historico/las-ultimas-posesiones/santo-domingo.html), and the [US Army's 1965–1966 expedition history](https://history.army.mil/Research/Reference-Topics/Army-Campaigns/Brief-Summaries/Armed-Forces-Expeditions/Dominican-Republic/); additional record-level sources support the early settlement and 1809–1821 period. The French range begins with the 1795 treaty claim, which preceded effective control. Start/end fields bound the relationship for color legends; the displayed ranges define the actual listed periods.

`disputed-areas.geojson` contains **29 curated source-based context shapes**, using Natural Earth's disputed-area release and applicable documented atlas components. A white hatch identifies dispute context without choosing a winner. Resolved/stale Hans Island, Tiran, Artsakh and Mbanie entries are excluded, as is an indiscriminate hatch across the entirety of Israel. This is not a live front-line or universal recognition map. Gray hatching identifies current dependent/context areas separately. Neither hatching nor a grouping guide manufactures an actual boundary.

Local 4:3 flag SVGs come from [flag-icons 7.5.0](https://github.com/lipis/flag-icons),
copyright Panayiotis Lipiridis and contributors, under its
[MIT license](https://github.com/lipis/flag-icons/blob/main/LICENSE). The exact npm
release tarball is cached during generation; `public/flags/LICENSE.txt` accompanies
the assets. These are real SVG flag illustrations, not platform-dependent emoji.

Rebuild in this order (downloads are cached in the operating system temp directory):

```sh
python scripts/generate-islands.py
python scripts/generate-places.py
python scripts/generate-world.py
python scripts/generate-capital-boundaries.py
python scripts/merge-capital-boundaries.py
python scripts/generate-home-geography.py
python scripts/finalize-home-geography.py
python scripts/refresh-relationships.py
python scripts/generate-metropolitan.py
python scripts/generate-home-overview.py
python scripts/revise-small-islands.py
python scripts/generate-connections.py
python scripts/generate-disputed-areas.py
python scripts/validate-home-geography.py
python scripts/validate-world.py
```

Use `generate-world.py --rebuild` to regenerate coastal geometry after an intentional
source or geometry-algorithm change. Its ordinary rerun refreshes metadata and
reuses previously built coastal detail. Add countries only to the explicitly
reviewed canonical `CORE` list if the UN definition changes; add other places as
context targets, preserving namespaces and source status. Check real capital names,
alias ambiguity, local SVG availability, on-land centers, detail URLs, ring closure,
antimeridian behavior and disputed/shared borders before publishing a new dataset.

The full metropolitan rebuild needs `numpy`, `scipy`, `pyproj`, `rasterio`, `shapely`, and `pyshp`. `generate-metropolitan.py --merge-only` reattaches an already generated metropolitan index without redownloading source grids. Geography scripts cache downloads; these GIS tools are not shipped to the browser.

## Compare countries graphs (October 2026)

`public/data/statistics/history/*.json`, built by `node scripts/build-country-history.mjs`, hold yearly country series for the sidebar's Compare countries graphs: population, density, life expectancy, children per woman, infant deaths, urban share, internet use, GDP per person, unemployment and CO₂ per person from the World Bank World Development Indicators (CC BY 4.0), and tax revenue from the UNU-WIDER Government Revenue Dataset via Our World in Data. Population, life expectancy and fertility continue to 2050 with the UN World Population Prospects projection as published in the World Bank's Population estimates and projections database; density's projection scales today's density by that projected population. Years from `projectedFrom` onward are projections. Other metrics show the last 15 years' trend carried forward, labelled as a trend rather than a forecast. HDI, murder rate and crime reuse `hdi.json`, `homicide-rate.json` and `crime-control.json`.

## Scientific layers, facts, and media

[MAP_SOURCES.md](MAP_SOURCES.md) documents the keyless OpenFreeMap/OSM background, licensed EOX 2016–17 imagery, NASA fallback, and each optional scientific study layer: Mapzen open DEM terrain, Copernicus ERA5 1990–2019 average temperature (CC BY 4.0; 0.25° grid), GLiM 2012 lithology (CC BY 3.0; 0.5° cells), NASA MODIS 2024 IGBP land cover (500 m), and RESOLVE 2017 ecoregions (CC BY 4.0; simplified 820-region redistribution). Geographic layers are lazy and never represented as contemporary field surveys or species-count maps. Full DEM national-source credits are bundled at `data/study/terrain-attribution.html`.

World Bank GDP, WHR life evaluation, highest-point records, archaeology and historical milestones retain source years, definitions and uncertainty. [docs/COUNTRY_FACTS.md](docs/COUNTRY_FACTS.md) describes underlying facts imports. The current UI deliberately does not substitute Happy Planet Index for **Gallup Positive Experience**: the latter's dated reusable global table has not been licensed/verified and is marked unavailable. Curated archaeology and state dates cover subsets, not all-country rankings. Wikipedia text is shortened with contributor/source attribution under CC BY-SA 4.0; Wikidata facts are CC0. No unavailable value becomes zero.

Gallery media comes from Wikimedia Commons' [Imageinfo API](https://www.mediawiki.org/wiki/API:Imageinfo), retaining each image's creator, license and original file-description link. Only supported photographs with explicit CC BY, CC BY-SA, CC0 or public-domain metadata are accepted; noncommercial/restricted files and PDF thumbnails are excluded. The editorial collection covers **63 countries, including all 45 supported island countries, plus the three separate Saint Helena-group cards**. Each has three distinct named subjects and short captions; 153 subjects have a reviewed exact-file crosswalk, with additional files pinned directly in the original key-case records. Semantic search results must match the subject in their filename. Maps, signs, portraits, official meetings, drawings and unnamed-road exports are rejected. There is no broad country or nearby-place fallback. Missing images remain unavailable, and uncurated places do not show an empty gallery. Remote photographs remain remote. The source link discloses that an external clue page can reveal the capital. See [docs/COUNTRY_FACTS.md](docs/COUNTRY_FACTS.md) for the editorial update procedure and coverage limits.

### Live hazards: earthquakes, tsunamis and tropical cyclones

The Weather & ocean panel's **Live hazards** overlays read public, keyless government feeds through `/api/hazards` (`server/hazards.ts`), which caches each layer at the edge (1 minute for earthquakes and tsunamis, 10 minutes for cyclones) and serves a saved copy for up to a day if every source is down. Each source is optional; the panel names any that did not answer. No third-party apps are scraped or reverse engineered.

- **Earthquakes:** [USGS Earthquake Hazards Program](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) GeoJSON summary feeds (past day, all magnitudes; past week, M2.5+; past month, M4.5+). U.S. public domain. Plate boundaries are Peter Bird's PB2002 model (Bird 2003, *G³* 4(3):1027) via [Hugo Ahlenius's conversion](https://github.com/fraxen/tectonicplates), ODC-By 1.0, built by `scripts/build-plate-boundaries.mjs` into `public/data/plate-boundaries.json`.
- **Tsunamis:** the latest bulletins from NOAA's [National and Pacific Tsunami Warning Centers](https://www.tsunami.gov/) (Atom feeds), active U.S. tsunami warnings, advisories and watches with their coastal zones from the [National Weather Service API](https://www.weather.gov/documentation/services-web-api), NOAA NDBC's [DART buoy](https://www.ndbc.noaa.gov/dart/dart.shtml) network, and USGS M6.5+ quakes carrying the USGS tsunami flag (a flag for large ocean quakes, not a confirmed tsunami). Regions outside these centers' areas rely on national warning centers, which the map does not yet read.
- **Tropical cyclones:** the [National Hurricane Center / Central Pacific Hurricane Center](https://www.nhc.noaa.gov/) storm list and its [tropical weather map service](https://mapservices.weather.noaa.gov/tropical/rest/services/tropical/NHC_tropical_weather/MapServer) (cone, track, forecast points, coastal watches and warnings, past track, 7-day outlook areas); the [Joint Typhoon Warning Center](https://www.metoc.navy.mil/jtwc/jtwc.html) warnings for the western Pacific, Indian Ocean and Southern Hemisphere (forecast track, past track, 34-knot wind radii drawn as a corridor); and [GDACS](https://www.gdacs.org/) (UN / European Commission) for impact alert levels and storms the U.S. centers do not warn on.

`npx tsx scripts/check-hazard-feeds.ts` runs the same readers against the live feeds, and the post-deploy smoke test calls `/api/hazards` for each layer.

### Clouds over Earth

The satellite **Style → Clouds** option (`src/components/CloudGlobeStyle.tsx`) shows one seamless global cloud map instead of daily polar-orbit swaths. The clouds are Matt Eason's [live cloud maps](https://github.com/matteason/live-cloud-maps) (CC0; "Contains modified EUMETSAT data"), stitched from geostationary weather satellites every three hours; the poles are mirrored in the source because those satellites cannot see them. `/api/clouds` (`server/cloudGlobe.ts`) saves the 4096 × 2048 map in D1 (`cloud_frames`, base64 parts under the 2 MB row limit) and keeps seven days, so the layer can play the last 24 hours. Each picture is filed under the three-hour slot that started before it was published (a 14:33 UTC upload is 12:00 UTC). The `Save cloud maps` workflow asks the live site for the list every hour so no slot is missed when nobody visits. Under the clouds are NASA's Blue Marble by day and the 2016 Black Marble city lights by night, through NASA GIBS, with a solar terminator for each frame's time. Computers zooming in on the newest picture read the 8192 × 4096 map straight from the source when it is still the same slot.

### October 2026 small-island and coastline corrections

`scripts/revise-small-islands.py` is a targeted post-processing step after the home
overview build. It retains Gran Roque from Venezuela's existing GSHHG detail,
using 63 coastline vertices in the bounded display instead of the former 18;
the upstream detailed component has 64. Venezuela's overview keeps these tiny
components instead of dropping them under the normal 3 km² filter. The reusable
simplifier caps additional simplification at 15 m for components under 25 km² and
50 m below 1,000 km²; it cannot recover detail already absent from its input.

The northern Guyana mismatch was a source-registration problem: Natural Earth's
Essequibo dispute polygon carried a separate, coarser coastline from Guyana's
GSHHG-derived country outline. Roughly 176 km² protruded beyond that outline.
`generate-disputed-areas.py` now retains Natural Earth's inland claim line but
splits the actual Guyana display geometry along it, so the dispute and country
share the same coast. This does not adjudicate Venezuela's claim; the context
links the [ICJ case](https://www.icj-cij.org/case/171).

Wildlife images use [GBIF occurrence records](https://www.gbif.org/occurrence/search) and their individually licensed media. A recorded occurrence does not establish that a species is endemic, nationally representative, or currently common. National animal/plant labels appear only for explicitly verified curated official examples. Both gallery and wildlife metadata load only on their corresponding visible disclosure.

The application has its own code dependencies and licenses; no blanket application license supersedes GSHHG, geoBoundaries, OSM, raster, or media licenses. Preserve all per-feature provenance and bundled notices when redistributing the datasets.

### Postcard location references

`src/lib/postcardLocations.json` contains 230 editorially matched place names and coordinates, with a source URL for each record. Most coordinates come from the named English Wikipedia article through its GeoData API; Wikipedia attribution and revision history remain available at those links. Alternatives are linked Wikidata records (CC0), GeoNames records (CC BY 4.0), actual Commons file GPS metadata, JICA's Varirata National Park conservation plan, and an NYBG locality record for Kepirohi. These sources provide factual locations, not copied map imagery. Each photograph retains its own Commons license and creator credit.

Precision is explicit: a named landmark, a regional location, or the photographer's recorded viewpoint. A regional marker does not claim an exact camera position; for a landmark, the subject's position takes precedence over camera GPS. Captions use the location actually supported by the selected image. The location review also replaced three mismatched images: Palau's bai is now Airai Bai, Guyana's water lilies are in Georgetown Botanical Gardens (a 1958 photograph), and the Seychelles tortoise is at Alibel Tortoise Park on Mahé. No live location search is required to render the pins.

### Historical name origins

`public/data/name-origins.json` contains 354 attributed explanations: all 195 sovereign countries, 58 territories and 101 physical islands. The remaining 49 catalog entries have explicit source gaps. Most are excerpts from Wikipedia's country-name etymology list and actual Etymology, Toponymy, Name or Naming sections of individual articles. Contributors' text is redistributed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/); each record links to the original article or section and its revision history. Reviewed editorial entries in `src/lib/curatedNameOrigins.json` also cover origins stated in article introductions or history sections, with individual source links. Some cite government, tourism or academic histories directly. Excerpts retain qualifications such as “uncertain”, “probably” and competing theories. They describe names, not the beginning of human settlement or national identity. Grenada has an editorial explanation of the likely Granada-city connection, also checked against the [Government of Grenada's history](https://www.gov.gd/grenada).

Regenerate with `node scripts/generate-name-origins.mjs`; add `--cached-only` to rebuild from stored responses without network access. The script checks every atlas and physical-island catalog entry, caches public API responses in `.cache/name-origins`, serializes requests and respects rate-limit delays. A missing or disambiguation article, absent name-origin section or unsupported cross-reference is recorded as unavailable rather than inferred from spelling. A successfully loaded subject-specific live article takes precedence over the general snapshot. This bundle loads only after the facts disclosure opens, and `loadNameOrigin(id)` can display the local explanation while slower context requests are still pending.

### Arable land quality

`public/data/earth/arable-land/{z}/{x}/{y}.png` (Web Mercator tiles, z0–z4) is derived from FAO & IIASA [Global Agro-Ecological Zones v4](https://gaez.fao.org/pages/theme-details-theme-4), theme 4 crop suitability index (`res05/CRUTS32/Hist/8110L/sxLr_*.tif`): rainfed, low-input farming under the 1981–2010 climate on a 5 arc-minute grid. Low input means no fertilizer, so the index rates the land itself (climate, soil and terrain). Each cell keeps its best index among wheat, maize, dryland and wetland rice, soybean, barley and sorghum, banded into FAO's standard GAEZ classes (very high ≥85 down to not suitable) in FAO's own class colors. On country averages Moldova and Ukraine rank first and second. The layer does not show irrigation or current land use. Credit: FAO & IIASA, GAEZ v4. FAO and IIASA allow noncommercial reuse with full acknowledgement; their v3.0 user agreement required written permission for commercial use, and the v4 terms were not confirmed from the cloud, so check them before the site runs ads.

Regenerate with `python3 -I scripts/build-arable-land.py`, which downloads the seven source rasters into `.cache/gaez`, rewrites the tiles and prints the country ranking.

### Annual rainfall

`public/data/earth/annual-rainfall/{z}/{x}/{y}.png` (Web Mercator tiles, z0–z4), `public/data/earth/annual-rainfall/months/01.png`–`12.png` (whole-globe 1024 px animation frames) and `public/data/annual-rainfall.json` (country averages and the wettest and driest places) come from two climatologies. Land uses the Deutscher Wetterdienst's [GPCC Global Precipitation Climatology 1991–2020, version 2025](https://opendata.dwd.de/climate_environment/GPCC/GPCC_Precipitation_Analysis_Climatology/Version_2025/) at 0.25°, the gauge-based monthly normals summed to a year. Oceans, Antarctica and any land cell GPCC leaves empty use the [ERA5](https://cds.climate.copernicus.eu/datasets/reanalysis-era5-single-levels) 1990–2019 climatology of 24-hour total precipitation from the public [WeatherBench 2](https://weatherbench2.readthedocs.io/en/latest/data-guide.html) copy; near coasts and the edge of GPCC's coverage the ERA5 values are scaled toward GPCC over about 1.5° so the seam fades. Colours are on a log scale from 1 to 12,000 mm a year in 250 bins that the hover readout decodes; month frames are coloured at twelve times the month's total so they share the annual scale. A 0.25° cell averages about 28 km, so the wettest single gauges (such as Mount Waiʻaleʻale) read lower here. Credit: Deutscher Wetterdienst, Global Precipitation Climatology Centre (CC BY 4.0); contains modified Copernicus Climate Change Service information (ERA5, CC BY 4.0).

Regenerate with `python3 -I scripts/build-annual-rainfall.py [cache-dir]` (needs numpy, Pillow, netCDF4 and numcodecs). It downloads about 250 MB from DWD and 3.4 GB from WeatherBench 2, rewrites the tiles, month frames and JSON, checks each named place lies in its listed country (`scripts/data/rainfall-places.json`) and prints the driest and wettest countries.