# Data Globe

A small globe and flat view of the world you can add with one script tag and a `<div>` of CSV, for showing
a few hundred points with Leaflet-style interaction.

> **Status:** pre-production, awaiting cartographic clearance. Editable renderer source: `v1.0.0/`; builder: `prototype/`. The cartographic
> presentation, names, designations and disclaimers are still under review. Do not publish or
> distribute the demo or generated embeds on public pages. Preset locations are sample data.

- **Parent issue**: [web-backlog #3092](https://gitlab.com/undrr/web-backlog/-/work_items/3092)
- **Builder and demo**: [`prototype/builder.html`](./prototype/builder.html). Start from a preset, adjust the options with a live preview, paste your CSV, copy the embed code. Link straight to a preset with `?preset=offices`, `site-theme`, `mcr`, `points`, `still` or `flat`
- **Sample data**: [`prototype/data/sample-points.csv`](./prototype/data/sample-points.csv)

The presets are curated starting points. Selecting one resets the settings and sample data;
manual edits and saved custom links keep their own configuration. Globe presets rotate until you interact; Static overview and Flat world overview stay still.
The first two presets also use regional-office highlights. True-colour presets use dot sizes of
0.6 zoomed out and 4.0 zoomed in; the light city preset uses 0.4 zoomed out.

| Preset | Starting point |
| --- | --- |
| `offices` — Office network: true colour | Natural-colour land dots on a steady dark ocean, office legend and regional-office highlights |
| `site-theme` — Brand globe: site theme | Stronger brand-colour land on a solid dark ocean; follows the host theme, with legend and highlights |
| `mcr` — City network: light | Purple land dots on a light page, centred on the sample cities in the Americas |
| `points` — Regional detail: dark | East Africa at closer zoom, separated land dots, steady dark ocean and office legend |
| `still` — Static overview | Natural-colour land dots on a steady dark ocean, office legend, rotation and highlights off |
| `flat` — Flat world overview | Equal Earth overview, theme-colour land dots and an office legend, with animation off |

Existing preset URL keys are retained. The Globe / Flat switch changes the live projection;
the Starting projection setting and “Use current view” still define the saved starting view.

The builder previews `v1.0.0` and uses the same CSS and JavaScript paths in generated embeds.
This pre-production build can be updated in place while cartographic clearance is pending.
See [Maintaining the review build](#maintaining-the-review-build) for visual review, data checks and updating the build.

Custom builder configurations are saved to a versioned `#state=` URL fragment, including all
controls, custom tint, CSV and the saved starting view. Copy the address to share or resume work;
reloads and fragment navigation restore the configuration. “Use current view” saves the displayed
camera and projection; ordinary globe dragging does not overwrite the chosen starting view.
Appearance, Locations and Behaviour disclosures group the controls, with Appearance open first.
Dot sizes have synchronized sliders and number fields; background colours offer theme defaults,
brand swatches, a native picker and custom hex entry. “Edit location data” under Locations opens
the full-width CSV editor below the preview, next to the embed code. Editing CSV updates the
preview without resetting the camera; opening control groups preserves the custom-state fragment.
Selecting a preset clears custom state. Malformed or unsupported state versions fall back to the
preset/default. Fragments are not sent to the server, but anyone with the link can read the data.

## Embed

The embed markup is the stable contract. The renderer behind it can change without breaking pages
that use it.

```html
<link rel="stylesheet" href="https://assets.undrr.org/projects/data-globe/v1.0.0/data-globe.css">

<div data-undrr-globe data-legend="true">
  <script type="text/csv">
lat,lng,size,label,url,category,description,shape,color
46.2044,6.1432,14,Geneva,https://www.undrr.org/,Headquarters,UNDRR headquarters,diamond,#ffc629
13.7563,100.5018,11,Bangkok,,Regional office,Regional Office for Asia and the Pacific,ring,#46c3f2
  </script>
</div>

<script type="module" src="https://assets.undrr.org/projects/data-globe/v1.0.0/data-globe.js"></script>
```

- The script finds every `[data-undrr-globe]` on the page and gives each its own instance, so several
  globes can share a page.
- Plain JavaScript (ES modules) with no dependencies, no framework, no import map and no build step.
  Load it with `type="module"`. It works in a Drupal Custom HTML block or any static page. Framework
  wrappers (React etc.) are out of scope until someone needs one.
- The module and CSS load with the page; the image and area data load when the globe comes within
  200px of the viewport.
- **CPU friendly**: the frame loop stops completely when the globe is scrolled off screen, the tab is
  in the background, or nothing is moving, and any interaction wakes it. When only the highlight is
  running, it sleeps on a timer between pulses instead of drawing every frame. Auto-rotation alone
  runs at about 30fps; dragging, zooming and fly-to get the full frame rate.
- **Start-up cost**: the dot cloud is built into typed arrays with lookup tables and cached, so
  several identical globes on a page (or the builder switching settings) build it once.
- **Many globes on one page**: browsers allow only about 8–16 live WebGL contexts per page. A globe
  that stays off screen for 10 seconds releases its context and restores it when scrolled back into
  view. If the browser takes a context away and doesn't give it back, that globe falls back to the list.
- **Mangrove**: the embed works with or without Mangrove on the page. When Mangrove is present, the
  brand tint, marker colour and UI neutrals pick up its tokens. The control icons follow the Mangrove
  icon set (Lucide style), inlined so there's no dependency. The builder page uses Mangrove components
  throughout.

### CSV columns

| Column | Required | Meaning |
| ------ | -------- | ------- |
| `lat`, `lng` | yes | WGS 84 decimal degrees. `latitude` / `longitude` / `lon` also work |
| `label` | yes | Short name, shown in the tooltip, popover and list |
| `size` | no | Marker diameter in px, 4–40 (default 10) |
| `url` | no | "Read more" link. Only `http:` and `https:` are allowed; anything else is dropped |
| `link_label` | no | Text for the link in place of "Read more", e.g. `About the Regional Office for Africa`. Make it say where the link goes, since it's also the screen reader name. `link_text` also works |
| `category` | no | Shown in the popover, and added as a class (`data-globe__marker--regional-office`) for styling |
| `description` | no | One or two sentences for the tooltip, popover, highlight label and list |
| `shape` | no | `dot` (default), `ring`, `diamond` or `square`. Use shape as well as colour to tell categories apart |
| `color` | no | Marker colour, any CSS colour (`#ffc629`, `rgb(70 195 242)`). Defaults to `--data-globe-marker` |

Values are always treated as text, never HTML. Quote a value that contains a comma. Invalid rows are
skipped with a console warning giving their line numbers.

### Options (`data-*` attributes)

| Attribute | Default | Meaning |
| --------- | ------- | ------- |
| `data-attribution` | `below` | Credits and disclaimers `below` the map (default) or in a compact `inset` at bottom inline-end. Inset text aligns to the end and follows host RTL direction; use `below` where the small text or overlap is unsuitable |
| `data-language` | `auto` | UI language: `en`, `fr` or `es`. `auto` inherits the nearest `lang` attribute at initialisation. Regional tags such as `fr-CA` use the base language; unsupported languages fall back to English |
| `data-projection` | `globe` | Initial view: `globe` or `flat`. The flat view keeps the Blue Marble dots, colour modes and markers in the same renderer |
| `data-projection-toggle` | `true` | Show the control for switching between globe and flat views. Set `false` to lock the chosen initial projection in the UI |
| `data-colour` | `true` | `true` for NASA Blue Marble colours on land dots, `brand` for a dark-to-light gradient of the tint, `brand-light` for tinted land dots on a pale ocean (for light pages) |
| `data-layout` | `grid` | Dot arrangement: `scatter` (even, organic), `rows` (latitude rows), `grid` (lat/lng graticule) |
| `data-dots` | `auto` | Number of dots in the point cloud, 5,000–250,000. `auto` scales it to the stage: 220k at 480px, fewer on small screens. Above ~250k the 1024px source image adds no colour detail |
| `data-dot-size` | `1` | Dot-size multiplier at the fitted/zoomed-out view (0.3–6), or the fixed size when dynamic scaling is off. Density compensation still applies |
| `data-dynamic-dot-size` | `true` | Interpolate dot size between the zoomed-out and zoomed-in sizes as the camera zooms; `false` uses a fixed size |
| `data-dot-size-zoomed` | `2` | Dot-size multiplier at maximum zoom (0.3–6). May be smaller or larger than `data-dot-size`; used only with dynamic scaling |
| `data-spotlight` | `random` | Pulse one marker at a time with a label: `random`, `off`, or a category name to cycle through it |
| `data-auto-rotate` | `true` | Slow spin until the user interacts |
| `data-zoom` | `true` | Zoom buttons, +/- keys, pinch, and the mouse wheel once the globe has been clicked (or Ctrl/Cmd + wheel) |
| `data-center` | `40,18` | Initial view, `lng,lat` |
| `data-zoom-level` | `0` | Initial zoom, in levels above the fitted view (-0.8 to 3.5) |
| `data-height` | `480` | Stage height in px |
| `data-transparent-background` | `true` | Set `false` to restore the solid ocean backdrop. By default, remove the solid ocean backdrop at the fitted overview, revealing the page between dots; `data-opaque-on-zoom` controls its return as you zoom in. Atmosphere remains independently controlled; use `data-atmosphere="false"` and `data-opaque-on-zoom="false"` for dots only. Ocean-coloured dots remain in `brand` mode; true-colour and `brand-light` modes draw land dots only |
| `data-opaque-on-zoom` | `true` | Fade in the solid ocean backdrop between the fitted view and 1.8 zoom levels above it, in globe, flat and transition views. Set `false` to keep the background transparent at every zoom. When `data-transparent-background="false"`, the backdrop stays solid at every zoom regardless of this option |
| `data-background-color` | `auto` | Overview ocean backdrop colour: a three- or six-digit hex colour, or `auto` for the theme / `--data-globe-ocean` colour. Visible when the backdrop is opaque |
| `data-background-color-zoomed` | `auto` | Zoomed-in ocean backdrop colour, with the same format. Blends from the overview colour across the first 1.8 zoom levels. Does not change the imagery or dot colours |
| `data-atmosphere` | `true` | Soft glow around the globe |
| `data-legend` | `false` | Legend of the CSV categories, with their colours, shapes and counts |
| `data-list` | `closed` | `open` to expand the location list by default. `hidden` takes it off the page visually but keeps it for screen readers, shows it while a keyboard user tabs into it, and shows it as usual when the globe can't render |
| `data-hover-buffer` | `12` | Padding in screen px around small islands for the country-name hover, over the sea only (0–40, `0` turns it off). See "Country name on hover" below |
| `data-area-hover` | `false` | Show country and geographic area names under the mouse pointer. Off by default; location-marker hover and focus tooltips are independent and stay available |
| `data-assets` | script folder + `data/` | Where to load `earth.jpg` and `areas.*` from |

Animation (rotation, highlight, momentum) is off when `prefers-reduced-motion` is set, and a
pause/play button is shown whenever any animation is enabled.

### Translation and cartographic disclaimers

`lib/i18n.js` centralises UI messages. The builder lets reviewers choose English, French or Spanish
for the preview and generated `data-language` attribute. Controls, motion buttons, projection and
keyboard labels, location-list headings, link defaults, territorial status labels, fallback messages
and the generic short disclaimer are translated. Generated elements carry their resolved `lang`.
CSV labels, categories, descriptions, custom link labels and UN area names are not translated.
Use a separate translated CSV when needed. Change a running embed with `globe.update({ language: "fr" })`.
The builder and preview gate remain in English. Additional languages can be added to the message
catalogue and builder selector; all translations require editorial review before publication.

Every rendered globe/map carries the **verbatim generic short UN disclaimer** in its credits,
including its reference to boundaries. Credits appear below the stage by default; `data-attribution="inset"`
moves the same complete credits and notices into a compact box inside the map. Logical positioning
and `text-align: end` follow RTL hosts. This placement option never removes or truncates the notices.
The inset is also avoided by spotlight callouts; choose `below` when text size, a small viewport or
map content makes an inset unsuitable. The default below-map placement follows the cartographic
guidance supplied for review; the inset remains an option for clearance review. The guidance says
the generic short disclaimer belongs below all maps; the long form is for detailed regional mapping
and is not normally used on world or continental maps. Adding a disclaimer does not grant clearance.

No national boundaries or Line of Control are drawn, so the line-specific Jammu and Kashmir and
Sudan/South Sudan notices are not appended to every world view. The Falkland Islands (Malvinas)
sovereignty notice and Abyei final-status notice are included in the credits on every map, since the worldwide
view includes those areas and the country hover identifies territories. These notices use the
wording supplied in the review guidance. Reassess all four special notices for regional views
or future boundary layers. The builder explains these pending decisions; this is not a statement
that clearance has been granted.

### Theming (CSS custom properties)

Set these on the globe's element or any ancestor.

| Property | Default | Meaning |
| -------- | ------- | ------- |
| `--data-globe-tint` | `var(--mg-color-interactive, 0 79 145)` | Brand-mode colour. Follows the Mangrove theme: UNDRR `0 79 145`, PreventionWeb `10 105 105`, IRP `15 120 191`, MCR `89 26 97`. Accepts an `r g b` triplet or any CSS colour |
| `--data-globe-ocean` | dark navy; dark tint in `brand`; pale tint in `brand-light` | Ocean colour behind the dots |
| `--data-globe-marker` | Mangrove accent (`254 193 36`) | Marker fill, when the CSV has no `color` |
| `--data-globe-marker-outline` | `#041a33` | Marker outline |
| `--data-globe-focus` | `#ffd24a` | Focus ring and selected marker |

Target a category with its class, for example
`.data-globe__marker--headquarters { --data-globe-marker: gold; }`.

### JavaScript API

```js
let globe = DataGlobe.init(element, { height: 400 }); // or read back element.dataGlobe
globe.select(0);          // open the popover for the first CSV row and fly to it
globe.setProjection("flat"); // smoothly flatten the globe; "globe" reverses it
globe.getProjection();    // "globe" or "flat"
globe.flyTo(100, 13, 1);  // lng, lat, zoom levels above the fitted view
globe.getView();          // { lng, lat, zoomLevel }, e.g. for data-center and data-zoom-level
globe.setData(csvText);   // swap the points in place, keeping the globe and the view
globe = globe.update({ colour: "brand" }); // structural change: rebuilds, keeps the view, returns the new API
globe = globe.update({ dotSize: 0.8, dotSizeZoomed: 2.4 }); // updates in place; same API, canvas and view
globe.destroy();          // frees the WebGL context and removes what the globe added; init() works again after

DataGlobe.options;        // the option schema (frozen): name, data-* attribute, type, range, default
DataGlobe.defaults;       // frozen defaults
DataGlobe.readOptions(el);   // validated options from an element's data-* attributes
DataGlobe.parsePoints(csv);  // validated points from CSV text
DataGlobe.version;
```

Language, dot size (including dynamic scaling and the zoomed-in endpoint), height, geographic hover, hover padding,
background transparency, backdrop colours (including the zoom-dependent backdrop) and credit placement update in place via `update()`. The canvas, WebGL context, shaders,
markers, list and current camera are retained. Height changes may regenerate/upload the dot cloud
when automatic density changes, while reusing shaders and buffers. Changes to geometry, source
assets or control structure still rebuild. `update()` returns the current API for in-place changes
or its replacement after a rebuild; keep its return value. Successive updates retain earlier options.
Permanent rendering fallback releases GPU resources/context when supported and disconnects its
observers; the translated accessible list remains usable.

Options passed from JavaScript use the schema names (`dotSize`, `autoRotate`, ...) and go through the
same validation as attributes. `DataGlobe.options` is the single definition of every option: the
attribute parser, the builder and this README are all driven by or checked against it
(`npm test` fails if an option is missing from the table above).

If the script is included twice (a repeated tag, or two versions on one page), the second copy does
nothing and logs a warning; the first copy initialises every globe.

## Behaviour

- **The Earth**: a pointillist cloud, each mark coloured from the Blue Marble pixel under it.
  True-colour mode draws land dots with a dense centre and a soft edge, over a continuous ocean
  backdrop. It omits ocean dots and the broad pigment wash, keeping the geography clear.
  The three true-colour presets use a solid dark ocean with matching colour endpoints, so it stays
  steady as you zoom. Custom transparency and endpoint colours remain configurable.
  Brand modes retain the broader overview pigment treatment, resolving into separate stipple
  dots across the first 1.8 zoom levels. Ocean dots in brand mode have lower opacity than land dots;
  brand-light mode draws land dots only. Upper-left lighting gives the sphere depth, with a narrow
  atmospheric rim; lighting fades away in flat view. The optional ocean backdrop follows the
  background transparency and zoom-colour settings above.
  Dynamic dot scaling is on by default: the diameter multiplier blends linearly in zoom levels from
  `data-dot-size` (default 1) at the fitted view to `data-dot-size-zoomed` (default 2) at maximum zoom.
  Sizes clamp at those endpoints, and may increase or decrease with zoom. Turn off
  `data-dynamic-dot-size` for a fixed screen-space diameter; in brand modes only the soft pigment edge profile
  still resolves into stipple as you zoom.
- **Flat view**: the Globe / Flat switch opens the sphere into a continuous curved sheet, then an
  Equal Earth world map centred on the current longitude. Equal Earth preserves relative areas
  and has curved outer meridians; shapes and distances are distorted, as on any flat world map. The far side becomes visible as the
  surface turns toward the viewer. Blue Marble dots, the ocean and markers share the same geometry
  throughout. Switching again smoothly reverses direction; dragging and zooming remain available
  during the transition. A damped spring settles exactly, allowing the frame loop to sleep.
  Markers, zoom and hover stay aligned; arrow keys and dragging pan the map.
  Switching views pauses auto-rotation.
  With reduced motion enabled, the switch is immediate. Set `data-projection="flat"` for a flat initial
  view, and `data-projection-toggle="false"` to keep either view fixed for readers.
- **Highlight**: every few seconds one visible marker pulses and a label pops up above it. It's either
  random or cycles through one category, whose other members pulse softly. Labels stay inside the
  stage and avoid controls and the legend; a label is hidden when neither placement fits.
- **Markers**: HTML buttons over the canvas. Hover or focus shows a tooltip; click opens a popover with
  the description and link, and flies to the point. Escape or clicking the globe closes it.
- **Country name on hover**: optional, off by default (`data-area-hover="true"` enables it).
  The tooltip names the UN area under the pointer, with applicable
  source status categories. Reviewed display labels replace ambiguous short names (see the
  area-label audit below). No parent-country relationship is inferred from map colour codes.
  There's no outline or highlight, so the data stays the focus.
- **Hover buffer for small islands**: at about 39 km per pixel, many small island states cover one
  raster pixel or none. When the pointer is over the sea, the globe looks for the nearest small area
  within `data-hover-buffer` screen pixels and names it. It never overrides land, so neighbouring
  countries (China and Russia, say) are unaffected, and only areas the build script flags as small
  (under 40 raster pixels) take part, via one representative point per island group. The feature is
  self-contained in `lib/hover-buffer.js`.
- **Controls**: a labelled Globe / Flat switch, grouped zoom/reset/pause buttons with 40px targets,
  and drag to rotate (with momentum). On touch screens,
  horizontal drags rotate and vertical swipes still scroll the page.
- **Keyboard**: the globe is focusable. Arrow keys rotate, +/- zoom, Tab moves through the visible markers.
- **Accessible list**: a `<details>` list of the same locations under the globe is the canonical
  content. When WebGL is missing or fails, the globe is hidden and the list opens with a short note.

## Code structure

`v1.0.0/data-globe.js` is the entry point and public API. The implementation is in `v1.0.0/lib/`:

| Module | What it does |
| ------ | ------------ |
| `builder-presets.js` | Curated preset settings, descriptions and stable URL keys (builder only) |
| `builder-state.js` | Versioned custom configuration fragment encoding and validation (builder only) |
| `i18n.js` | English, French and Spanish UI messages, language resolution and plain-text interpolation |
| `options.js` | The option schema, defaults and `data-*` parsing (no DOM; tested in Node) |
| `csv.js` | CSV parsing and point validation (no DOM; tested in Node) |
| `assets.js` | Loads and decodes the data files, shared between globes |
| `dot-size.js` | Clamped linear interpolation between fitted-view and maximum-zoom dot sizes |
| `dots.js` | Builds and caches the pointillist dot cloud |
| `camera.js` | View state, projection maths, fly-to |
| `projection.js` | Shared curved surface equations for shaders and HTML marker projection |
| `renderer.js` | All WebGL drawing, behind `createRenderer(gl)` → `{ upload, draw, maxPoint }`. The swap point for another renderer or extra layers |
| `dom.js` | Stage, controls, popover, legend, attribution, location list, fallback |
| `markers.js` | Markers, tooltip, popover placement, country-name hover |
| `area-labels.js` | Reviewed area display names and tooltip status policy, shared with the data builder |
| `hover-buffer.js` | The small-island hover padding (optional, self-contained) |
| `spotlight.js` | Highlight pulses and labels |
| `controls.js` | Pointer, wheel, keyboard and pause state |
| `loop.js` | Frame loop that sleeps off screen and when idle; WebGL context release |
| `icons.js`, `util.js` | Inline icons and small helpers |
| `globe.js` | One globe instance: lifecycle and the state the modules share |

Each behaviour module exports methods that `globe.js` mixes into the `Globe` class, so they share one
instance's state without depending on each other directly.

## Limits and design decisions

- **Up to a few hundred points.** Each marker is an HTML element repositioned every frame. **Beyond a few
  hundred points, revisit this**: draw the markers on the GPU and keep HTML only for the hovered or
  selected one.
- **Plain WebGL, no Three.js.** With the country lookup precomputed, the globe uses two draw calls: an ocean surface and a
  point cloud. During the transition, a static 96 × 48 mesh (about 216 KB on the GPU) replaces the
  analytic disc; it shares the dot projection and requires no per-frame geometry uploads. The mesh
  is unused at rest, and all its resources are rebuilt after context restoration and freed on destroy. The earlier prototype needed Three.js (~170 KB gzipped) plus d3 (~92 KB). Moving to
  Three.js later means replacing `lib/renderer.js` and doesn't affect the embed contract.
- **ES modules, no build step.** The browser loads about a dozen small files (fine over HTTP/3 from
  the asset library). If that ever matters, a bundled single file can be produced from the same source
  without changing it.
- **No boundary lines.** Drawing UN boundaries means UNDRR has to get clearance from the UN Geospatial
  Information Section before publishing. The hover lookup uses UN names but draws nothing.
- **Payload** (gzipped, approximate): JavaScript modules 30 KB (17 files), `data-globe.css` 3 KB, `earth.jpg` 26 KB,
  `areas.bin` 17 KB, `areas.json` 9 KB. About 85 KB in total, against about 700 KB for the earlier
  Three.js/d3 prototype.

## Projection guidance

Equal Earth is the choice for this component’s flat world overview because it preserves relative
areas. The [UN Geospatial FAQ, question 5](https://www.un.org/geospatial/node/744) states that the
Secretariat has no prescribed projection. The draft resolution
[A/80/L.104](https://docs.un.org/en/A/80/L.104), adopted as A/RES/80/307, encourages Equal Earth
and other equal-area methods where continental sizes matter (paragraph 5), and explaining each
projection’s limitations and applications (paragraph 10). It does not ban Mercator or mandate one
replacement for every map; its preamble preserves established navigational uses. Projection choice
remains separate from UN map clearance, names, boundaries and disclaimer requirements.

## Data files

`v1.0.0/data/` holds files generated by `scripts/build-data-globe.js`:

| File | What it is |
| ---- | ---------- |
| `earth.jpg` | NASA Blue Marble (land_shallow_topo), 1024 × 512 |
| `areas.bin` | UN area index raster, 1024 × 512 equirectangular, run-length encoded (format in the script header) |
| `areas.json` | Reviewed display name, source status code, source `isoclr` colour-group code and ISO3 for each area id, plus `small`: `[areaId, lng, lat]` points for the hover buffer. The colour-group code is metadata, never an administering-State assertion |

Rebuild them with:

```bash
npm run build-data-globe   # fetches UN Geodata and Blue Marble; the JPEG resize needs macOS `sips`
```

### Sources

| Data | Source | Terms |
| ---- | ------ | ----- |
| Area names, status, shapes for the hover lookup | [UN Geodata simplified](https://geoservices.un.org/arcgis/rest/services/Hosted/UN_Geodata_simplified/FeatureServer), layer `BNDA_simplified`, United Nations Geospatial | Credit the United Nations; no commercial use; see the [terms of use](https://developers.google.com/earth-engine/datasets/papers/BNDA_terms_of_use.pdf) |
| Globe imagery | [Blue Marble](https://visibleearth.nasa.gov/images/57752), NASA Visible Earth | Public domain, credit NASA |

Status codes (`stscod`): 0 Antarctica, 1 State, 2 Occupied Palestinian Territory, 3 Non-Self-Governing
Territory, 4 Territory, 5 Special region or province, 99 undetermined. The globe shows the attribution
and the UN's short disclaimer under the stage.

### Area-label audit (27 October 2026)

Compared all 262 stored records with the live `BNDA_simplified` service, including all 65 records
outside its State and Antarctica categories. Before applying the corrections below, every short
name, status code and ISO3 matched the live source in the same raster order. This validates source
consistency, not cartographic clearance or a separate UNTERM review of every name.

| Source record | Display policy | Evidence |
| --- | --- | --- |
| Taiwan, code 5 / TWN | Taiwan Province of China; no generic status subtitle | [UN editorial guidance](https://ft.dfs.un.org/sites/default/files/editorial_guidelines_summary.pdf) and the [UNSD M49 FAQ](https://unstats.un.org/unsd/methodology/m49/) use this name. A standalone UNTERM record was not retrieved during review |
| Hong Kong, code 5 / HKG | Hong Kong, China; no generic status subtitle | The source's `lbl_en` cartographic label |
| Macao, code 5 / MAC | Macao, China; no generic status subtitle | The source's `lbl_en` cartographic label |
| United States of America, code 4 / USA | Hawaii (USA); no generic Territory subtitle | The separate Hawaii polygon's `lbl_en` is Hawaii (USA). The mainland USA record remains unchanged |
| Other 35 code-4 records | Keep source names and Territory category; remove inferred parent-country suffixes | Compared `nam_en`, `lbl_en`, `stscod`, `iso3cd` and `isoclr` in the live source |
| 17 code-3 records | Keep source names and Non-Self-Governing Territory category; remove inferred parent-country suffixes | Live source status domain and the [UN list of Non-Self-Governing Territories](https://www.un.org/dppa/decolonization/en/nsgt); the sets match, including Western Sahara and Falkland Islands (Malvinas) |
| Gaza and West Bank, code 2 / PSE | Keep distinct source area names and Occupied Palestinian Territory subtitle | Live source records; do not collapse these regional polygons into a country-level M49 label |
| Seven code-99 records | Preserve source names, including Jammu and Kashmir; unnamed polygons show Area of undetermined status | Live source records; no parent-country attribution or invented names |

The [source layer](https://geoservices.un.org/arcgis/rest/services/Hosted/UN_Geodata_simplified/FeatureServer/2)
exposes separate short-name (`nam_en`) and cartographic-label (`lbl_en`) fields. Other cartographic
labels contain abbreviations and asterisks tied to a printed map legend, so they are not substituted
wholesale into tooltips. The three code-5 names and the separate Hawaii polygon use the explicit
policy in `area-labels.js`, at build time and at runtime (including older cached data files).
Display names remain English when the UI language changes, as with the other source names.

The earlier `administeringState` field was derived from `isoclr`, rather than sourced from an
explicit administering-State field. It is replaced by `colourGroup`, containing the original
code. Tooltips ignore this slot, including in older data files, and retain all existing map disclaimers.

## Out of scope for v1

Candidates for follow-up tickets:

- Raster and polygon data layers
- Boundary lines in UN line styles (needs clearance)
- A complete UNTERM reconciliation of country and area names beyond the reviewed cases above
- Marker clustering and GPU-drawn markers for larger datasets
- Framework wrappers

## Local development

```bash
npm run dev
# http://localhost:8000/projects/data-globe/prototype/builder.html
```

## Maintaining the review build

`v1.0.0/` is an editable pre-production build, not an immutable release. Keep updating it in place
until cartographic clearance. The builder previews it and generates embeds pointing to it.

Edit the renderer directly under `v1.0.0/`, then run:

```bash
npm test
```

Use the builder to check natural, brand and brand-light treatments in globe and flat views,
at overview and detail zoom. Check coastlines, land/ocean contrast, dot texture, markers, controls and credits.
Keep the supported scope to a few hundred locations and the existing visual treatments.

When changing geographic metadata, run `node projects/data-globe/tools/audit-labels.js`. This
read-only check compares source names, status codes and colour groups with UN Geospatial metadata;
it does not provide cartographic clearance or a full UNTERM review. Rebuild geometry and metadata
together with the existing `npm run build-data-globe` command when needed.

Use the normal repository MR and deployment workflow. After deployment, clear changed URLs in
[Cloudflare Caching → Configuration](https://dash.cloudflare.com/0684bcc589f557a6f3ae5a5f31c060c8/undrr.org/caching/configuration)
and verify the ordinary public URLs; query strings do not bypass this cache.
