---
id: "packages/active-geo/api"
title: "API reference"
description: "The public contract of active-geo - the package's own reference, and every export of both entries generated from the source."
url: "/packages/active-geo/api"
locale: "en"
revision: "9a6777f2ad6994ba"
---

# API reference

> [!NOTE]
> **Two views of one API**
>
> First the package's own `docs/API.md`, included unchanged: the contract. Then
> an index of every export of both entry points, generated from the source, with
> a page per topic.

The supported contract of `@workspace/active-geo` since the public switch to P1 (P1e, `[Unreleased]`): the P1 projection of the API-first design v0.5 (D-42 to D-47). Two entries: the runtime `.` and the optional starter collection `./collections/world-50m` (§ 15); both export lists are pinned by `src/__tests__/public-api.test.ts`. Version 0.x: workable, not yet stable. **V1 is not accepted.** The 0.4 API (the `presentation` prop, the object card, the footer's Table and Export, the layer value fields, state v1 as output, CSV v1) is gone; the migration table maps every part of it.

**Phases.** P1 publishes only what works. An input of a later phase does not exist in these types, and a JavaScript caller that passes one gets `GeoConfigurationError` with `GEO_OPTION_UNAVAILABLE` (§ 9): symbols and shapes, rotation, `paint`, shared scales (`scales`), the legend filter (`legend.interaction: 'filter'`, `filter` props), legend overflow (P2); line layers, `useGeoProjection`, `project`/`invert`, a React tooltip (P3); continuous colour, image symbols, clusters, insets (P4). OUTPUT types keep the full target unions (a `line` layer type, the channels `shape`/`rotation`/`color`/`width`, gradient and line keys, cluster targets), so an exhaustive switch keeps compiling when a later phase makes them live; P1 never produces them.

| Export | Kind |
| --- | --- |
| `GeoMap`, `GeoDefaults`, `GeoMapScope`, `GeoLegendOutlet`, `GeoTableOutlet` | Component |
| `useGeoLegend` | Hook |
| `englishGeoTranslator` | Function |
| `englishGeoMessages` | Constant |
| `GeoConfigurationError`, `GeoExportError` | Class |
| `GeoMapProps`, `GeoDefaultsProps`, `GeoMapScopeProps`, `GeoOutletProps`, `GeoConfigSource` | Types |
| Layers and data: `GeoLayer`, `GeoAreaLayer`, `GeoPointLayer`, `GeoContextLayer`, `GeoAreaFeature`, `GeoPointDatum`, `GeoDataRecord`, `GeoMeasure`, `GeoNumberMeasure`, `GeoCategoryMeasure`, `GeoCategoryDefinition`, `GeoValues`, `GeoValueInput`, `GeoSuppressed`, `GeoDetail`, `GeoDescribe`, `GeoObjectTextContext`, `GeoTextField`, `GeoLabelOptions`, `GeoLayerTooltipOptions` | Types |
| Encodings: `GeoFill`, `GeoColorMapping`, `GeoClassScale`, `GeoDivergingScale`, `GeoPalette`, `GeoMarker`, `GeoSizeMapping`, `GeoExplanationOptions`, `GeoExplanationPart`, `GeoInputChannel`, `GeoChannel` | Types |
| Readings (output): `GeoMeasurementReading`, `GeoMeasurementStatus`, `GeoInvalidReason`, `GeoEncodingReading`, `GeoEncodingStatus`, `GeoVisualValue`, `GeoUnrepresentableReason`, `GeoSpecialStatus` | Types |
| Legend: `GeoLegendOptions`, `GeoLegendPosition`, `GeoLegendSection`, `GeoLegendSectionItem`, `GeoCustomLegendEntry`, `GeoLegendModel`, `GeoLegendModelEntry`, `GeoLegendKey`, `GeoResolvedVectorSymbol`, `GeoLegendHook`, `GeoLegendActivation`, `GeoExplanationRef`, `GeoExplanationRefInput`, `GeoScaleEntry`, `GeoLegendEntryRef`, `GeoHighlight`, `GeoHighlightTarget`, `GeoHighlightChange` | Types |
| Options: `GeoZoomOptions`, `GeoZoomControls`, `GeoNavigationAction`, `GeoCorner`, `GeoContextMenuOptions`, `GeoMenuFeatures`, `GeoMenuGroup`, `GeoMenuItem`, `GeoMenuContext`, `GeoMenuTarget`, `GeoClusterSnapshot`, `GeoTableOptions`, `GeoTooltipOptions`, `GeoHeaderOptions`, `GeoAttribution`, `GeoSelectionOptions`, `GeoComponents`, `GeoButtonSlotProps`, `GeoToggleSlotProps`, `GeoInputSlotProps`, `FeatureOption`, `Resettable`, `GeoId`, `GeoColor` | Types |
| View and events: `GeoView`, `GeoViewMode`, `GeoHome`, `GeoViewChange`, `GeoViewCause`, `GeoSelectionChange`, `GeoItem`, `GeoItemRef`, `GeoKey`, `GeoDataLayerType` | Types |
| Rows: `GeoFeatureSnapshot`, `GeoLayerSnapshot`, `GeoRowSnapshot`, `GeoObjectSnapshot`, `GeoRecordSnapshot`, `GeoEncodingSnapshot`, `GeoKeyReading`, `GeoGeometryStatus`, `GeoLinkStatus`, `GeoRecordLink`, `GeoRowIssue`, `GeoFeatureQuery` | Types |
| Handle and state: `GeoMapHandle`, `GeoMapState`, `GeoApplyStateOptions`, `GeoApplyStateResult`, `GeoStateField`, `GeoStateFieldResult`, `GeoStateEntryResult`, `GeoStateDisposition`, `GeoStateReason`, `GeoDatasetIdentity`, `GeoEffectivePresentation`, `GeoTableRequest`, `GeoTableRequestOutcome`, `GeoTableRevealResult`, `GeoTableRevealFailure`, `GeoFocusReturn` | Types |
| Export: `GeoExportOptions`, `GeoImageExportDefaults`, `GeoImageExportOptions`, `GeoExportLegendLayout`, `GeoCsvExportOptions`, `GeoExportResult`, `GeoExportWarning`, `GeoExportWarningCode`, `GeoExportFormat`, `GeoExportTheme`, `GeoExportThemes`, `GeoExportThemeMarker`, `GeoExportLimits`, `GeoExportErrorCode`, `GeoExportErrorOptions` | Types |
| Geometry and projection: `GeoAreaGeometry`, `GeoContextGeometry`, `GeoPolygon`, `GeoMultiPolygon`, `GeoLineString`, `GeoMultiLineString`, `GeoRing`, `GeoPosition`, `GeoRingConvention`, `GeoProjection`, `GeoPointRenderer` | Types |
| Words, notation, diagnostics, levels: `GeoTranslateFn`, `GeoTranslationKey`, `GeoTranslationVariables`, `GeoPresentation`, `GeoValueSemantics`, `GeoDiagnostic`, `GeoDiagnosticLevel`, `GeoDiagnosticSink`, `GeoLevel`, `GeoLevelRequest`, `GeoConfigurationErrorCode`, `GeoConfigurationErrorOptions` | Types |

## 1. `GeoMap`

```tsx
<GeoMap
  title="…"                  // the map's accessible name; shown in the header by default; required
  subtitle="…"               // a short visible line under the title (header.subtitle)
  description="…"            // for assistive technology, and the export's description
  layers={[…]}               // GeoLayer[], bottom first (§ 2)
  projection="conic-equal-area"
  height={420}               // CSS px of the stage (default 420); the width follows the container
  graticule                  // meridians and parallels
  locale="nl-NL"             // the notation of numbers; prop, else GeoDefaults; required
  t={translate}              // the host's words; prop, else GeoDefaults; required (§ 7)
  diagnostics={sink}         // prop, else GeoDefaults, else the console (§ 8)
  // configuration (each also from GeoDefaults, § 6):
  header legend tooltip zoom contextMenu table export attribution selection components
  // state, controlled or not (§ 4):
  selectedItems defaultSelectedItems onSelectionChange
  view defaultView home onViewChange
  highlight defaultHighlight onHighlightChange onLegendActivate
  onItemActivate onTableRequest
  dataset levelPath onLevelRequest
  onExportComplete onExportError
  ref={handle}               // GeoMapHandle (§ 5)
  className="…"
/>
```

**The package default is quiet (D-45).** In rest: the title (and subtitle) above the map, the map, and the source line (`attribution`); nothing else. The navigation appears on demand (pointer over the map, keyboard focus, a touch) in a corner over the map, keeps its place and its tab stop, and never shifts the layout. The legend appears only when there is something to explain (an encoding, a status). The menu opens on a right click, a long press, Shift+F10 or the ContextMenu key; export and the table live in the menu and the handle (D-44), never in a mandatory footer. Every part is configurable or replaceable by the host (§ 3, § 11).

**Keyboard.** The map is one tab stop with `aria-activedescendant` over the drawn objects in walking order (also Canvas points, through proxies). Arrows move, Home and End go to the first and last object, Space selects (when selection is on), Enter activates (`onItemActivate`; also selects when selection is on), Shift+F10 and the ContextMenu key open the menu on the object (or the map), Escape closes the tooltip and then clears a highlight, + and − zoom (`zoom.keyboardShortcuts`). A key typed in the menu, the legend or the table is theirs, never the map's. One announcement per action; a controlled map that refuses a change announces nothing.

**Pointer and touch.** A click on an object selects (when on) and shows its tooltip; one finger belongs to the page (`touch-action`), two fingers pan and zoom; the wheel zooms with Ctrl or Command by default (`zoom.gestures.wheel`); a hint says how when a gesture is not the map's. Picking follows the drawn symbol plus a tolerance (D-19); several objects at one place are offered in the menu (`atPlace`).

**Failure.** A configuration the map cannot run with throws a `GeoConfigurationError` during render (§ 9). Data problems never throw: they exclude objects with a reason, shown in the table's "not on the map" tab and the data alternative, and reported once to the diagnostics sink.

## 2. Layers, measures and encodings

```ts
type GeoLayer = GeoAreaLayer | GeoPointLayer | GeoContextLayer;
```

Every data layer has `id`, `title`, and optionally `visible`, `fit`, `measures`, `detailOrder`, `tooltip`, `label`, `legend` (`boolean | {title?: string | false}`) and `describe`.

- **Area layer** (`type: 'area'`): `features: {key, name?, geometry, values?, details?, meta?}[]`, optional `data: {key, values?, details?}[]` (records joined by key; never together with inline `values`: `GEO_DATA_SOURCE_CONFLICT`), `convention` (`rfc7946` default, or `spherical`), `fill` (a colour or a `GeoColorMapping`), `stroke`.
- **Point layer** (`type: 'point'`): `points: {key, latitude, longitude, name?, values?, details?, meta?}[]`, `marker: {size?, fill?, stroke?, opacity?}` (circles in P1), `renderer` (`'auto'` default, `'svg'`, `'canvas'`; Canvas above the threshold of D-18).
- **Context layer** (`type: 'context'`): `geometries` of areas and lines; drawn, never interactive, never in the legend or the table.

**Measures (W-1, D-43).** A layer knows measures: `{id, label, semantics?}` (a number; `semantics` is the family's `GeoValueSemantics`, § 13) or `{id, label, kind: 'category', categories: [{id, label?}]}`. A value per object (or record) in `values`, keyed by measure id: a number, a category id, `null`/absent (missing) or `{suppressed: true}` (withheld). Ids are `GeoId`s (`/^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$/`, `GEO_ID_INVALID`). A reading is `value` (with its formatted `text`), `missing`, `invalid` (with a reason) or `suppressed`. **A withheld value is never shown as a number anywhere**: not in the map, the tooltip, labels, the table, the copied text, CSV or an export.

**Encodings.** Areas encode `fill`; points `marker.fill` and `marker.size`.

- `fill: {measure, scale, palette?, legend?}` with an own classed scale: `{type: 'threshold', thresholds, classLabels?}`, `{type: 'quantize', classes, domain?, classLabels?}`, `{type: 'category'}`, or diverging (`{type: 'diverging', reference, …}`, D-28). End classes are open. `palette` overrides the token colours (an array by class, or a record by category id).
- `size: {measure, domainMax?, maxRadius?, legend?}`: the AREA of a circle is proportional to the value; zero, missing, withheld and negative sizes draw a hollow marker at the hollow radius.
- A constant is a plain value (`fill: '#2a6'`, `size: 6`).
- An encoding's status is separate from the measurement: `encoded`, the special statuses, `unrepresentable` (with a reason) or `constant`.

**Text fields.** Tooltip, labels and `describe` read the same fields: `'name'`, `{measure}`, `{encoding: 'fill' | 'size', show?: 'class' | 'value-and-class'}`, `{detail}`, `'details'`. `tooltip: {title?: 'name' | false, fields?}` per layer; `label: {fields?, max?, placement?}` per layer (area labels D-30; point labels D-31; placement order `end, start, above, below` by default); `describe(context) => {name?, description?}` overrides an object's accessible name and description (a throwing callback falls back to the default and is reported once). A label never shows a withheld value.

## 3. Configuration props

Every one is a `FeatureOption`: absent inherits, `false` switches the part off, `true` switches it on with its defaults, an object refines.

| Prop | P1 fields (package default) |
| --- | --- |
| `header` | `{subtitle}` (`true`). `false` hides the visible header; `title` stays the accessible name and the export title |
| `legend` | `position` (`bottom`; `top`, `start`, `end`, a corner over the map, `outlet`), `offset`, `align` (`start`), `arrangement` (`row`/`stack`), `sections` (explanations, status blocks, custom entries), `order`, `unplaced` (`append`), `explanations` (title, parts, statuses, counts, display `compact`/`list`, direction, samples), `customEntries` (swatch or circle), `interaction` (`highlight`; `none`, `host`), `highlightChip` (`auto`) |
| `tooltip` | `anchor` (`object`; `pointer`), `delay` (0), `pinOnTap` (`true`) |
| `zoom` | `controls`: `{visibility: 'on-demand', keepWhileZoomed: true, position: 'bottom-end', orientation: 'horizontal', actions: ['zoom-in', 'zoom-out', 'fit', 'pan']}`, `{visibility: 'always', …}` or `false`; `gestures` (`wheel: 'modifier'`, `drag`, `pinch`, `doubleClick: false`); `keyboardShortcuts` (`true`); `minZoom` (1), `maxZoom` (32) |
| `contextMenu` | `items(context) => GeoMenuItem[]` (the host's items, first by default), `features` (`copy`, `table`, `navigation`, `export`, `level`: all `true`), `groupOrder` (`host, copy, table, navigation, level, export`), `trigger` (`none`; `button` adds a menu button) |
| `table` | `position` (`below`; `outlet`), `open`/`defaultOpen` (`false`), `onOpenChange(open, cause)`, `layers`. `false`: no table; the hidden data alternative stays |
| `export` | `formats` (`png`, `svg`, `csv`), `image` (`theme: 'light'`, `extent: 'current'`, `legend: 'presentation'`, `attribution: true`, `background: 'theme'`, `labels: true`, `scale: 2`, `title`, `description`), `csv` (`details: true`, `text: false`), `limits`, `themes` |
| `attribution` | a text, or `{text, position: corner \| 'below' \| 'none'}`; always under an exported image |
| `selection` | `false` by default; `true` or `{enabled?, mode: 'single' \| 'multiple'}` |
| `components` | the host's `Button`, `Toggle`, `Input` (§ 11) |

**The menu (D-44).** The family's menu (the shared `menu-items` pipeline of Charts and Grid) on Base UI's context menu, composed from one frozen `GeoMenuContext` per opening (`target`: an object with every object at its place, the map at a position, or a legend entry; `source`; `selectedItemCount`; `view`; `level`; `getMeta`). Groups: `host` (the host's items), `copy` (an object's values in words; a withheld value is its status word), `table` ("Show in table", "Show the table"/"Hide the table"), `navigation` (place-bound only: "Zoom to …", "Zoom in here", "Fit the map", the starting view; never a second zoom in/out), `level` (the levels above the current one), `export` (the allowed formats, current view or whole map, one CSV per data layer, all records or the selection). An item that exists but cannot run now stays, disabled with its reason. A host item: `{label, action?(context), icon?, variant?, disabled?, disabledReason?, shortcut?, keepOpen?, visible?(context), separatorBefore?, children?}` or `'separator'`. A keyboard opening focuses the first item; focus returns to the opener, or to the target an action claims (a table row).

**The table (D-46).** The package's own accessible table: one tab per data layer plus "not on the map", search, pages of 100 rows, "Show on map", reasons in words, end-aligned number columns; the hidden data alternative reads the same rows. Opened from the menu, by `table.open`/`defaultOpen`, or by `revealInTable`. Escape in a row returns the focus to its object on the map.

## 4. State, events and the controlled pattern

Each piece of interactive state is uncontrolled (`default…`) or controlled (the value prop). A controlled value is the host's: the map draws the prop and only ASKS (`requested: true` in the change); `getState()` right after a refused request still reports the prop.

- **Selection**: `selectedItems`/`defaultSelectedItems`, `onSelectionChange(selection, change)`; `change.source` is `pointer`, `keyboard`, `update` (objects that left the data, with `removed`), `restore` or `api`.
- **View (W-9)**: `view`/`defaultView`: `{mode: 'frame'}` (fitted to the layers) or `{mode: 'free', center, zoom}`; `onViewChange(view, {cause, requested})`. `home`: `'frame'`, a fixed view, or `{fit: 'layers', layers}` (where `home()` goes; `fit()` is always the frame).
- **Highlight**: `highlight`/`defaultHighlight` (`GeoHighlight | null`: legend entry targets with their meaning fingerprints), `onHighlightChange(highlight, {cause, requested})`. The callback value can be fed back into the prop without a cast. A target whose MEANING changed (a different scale) is cleared with `cause: 'reconcile'`; mere absence keeps it dormant.
- **Legend activation**: `onLegendActivate(activation)` runs before the effect of a legend entry, Geo's own or a host legend's (`useGeoLegend`, `activateLegendEntry`), and may `preventDefault()`.
- **Items**: `onItemActivate(item, source)` on Enter (keyboard) or the pointer and touch activation of an object.
- **Host table**: `onTableRequest(request)` (`{item, focus, source, requestId, revision, dataset, signal, returnFocus}`) returns or resolves `{status: 'shown', focus: 'host' | 'none' | 'package'}` or `{status: 'unavailable', reason?}`. With `focus: false` the host must not move the focus. A newer request or unmounting aborts `signal`; every reveal settles exactly once (`revealed`, or `unavailable` with `no-table`, `item-unknown`, `host-refused`, `host-failed`, `not-opened`, `outlet-hidden`, `not-focusable`, `superseded`, `unmounted`, `stale-data`).
- **Levels (D-25)**: `levelPath` (top first; the last is current) and `onLevelRequest(request)`; the request carries `{level, item?, source, requestId, signal}`; applying the answer is the host's.
- **Exports**: `onExportComplete(format)`, `onExportError(format, error)`.

Callbacks are read at the moment of the event (a new callback after a re-render receives the next event); a re-render with equal props reports nothing.

## 5. The handle

```ts
interface GeoMapHandle {
  zoomIn(): void;
  zoomOut(): void;
  fit(options?: {layers?}): void;
  home(): void;
  pan(direction: 'up' | 'down' | 'left' | 'right'): void;
  zoomTo(items: GeoItemRef | readonly GeoItemRef[]): boolean;
  focusItem(item: GeoItemRef): boolean;
  revealInTable(
    item: GeoItemRef,
    options?: {focus?: boolean},
  ): Promise<GeoTableRevealResult>;
  exportAsPng(options?: GeoImageExportOptions): Promise<GeoExportResult>;
  exportAsSvg(options?: GeoImageExportOptions): Promise<GeoExportResult>;
  exportAsCsv(options: GeoCsvExportOptions): Promise<GeoExportResult>;
  getFeatures(query?: GeoFeatureQuery): GeoFeatureSnapshot;
  getLegendModel(): GeoLegendModel;
  activateLegendEntry(entryId: string): boolean;
  getEffectivePresentation(): GeoEffectivePresentation;
  getState(): GeoMapState;
  applyState(
    state: unknown,
    options?: GeoApplyStateOptions,
  ): GeoApplyStateResult;
  requestLevel(level: GeoLevel, options?: {item?: GeoItemRef}): void;
}
```

Every method runs the same route as the package's own control for it (one route per action: a button, a key, a menu item and the handle produce the same events). In a controlled map the navigation methods are requests. `getFeatures` returns the one row model (§ 10) the table, the data alternative, the tooltip and CSV read. `getEffectivePresentation` says what is shown after defaults, fallbacks and the container width.

**State v2 (D-47).** `getState()` returns `{version: 2, dataset, level, view, selection, layers, encodings, scales, highlight, filter}` (`filter` is always empty in P1). `applyState(state, {fields?, isCompatible?})` validates unknown input, the schema, the version (a version 1 state is migrated: `reason: 'migrated-v1'`) and the dataset (`isCompatible`; default: equal identity), then restores field by field and reports per field (`applied`, `adjusted`, `delegated`, `dropped`, `unchanged`, with a reason) and per entry. Without `fields`: every restorable field present in the state. A controlled field is delegated as a request. A non-empty `filter` is `dropped` with `capability-unavailable` (per target and as a field) while other fields restore (`partial`); `filter: []` is "no filter" (`unchanged`). A highlight with a later-phase target is dropped as a whole group. The result `status` is `applied`, `partial` or `rejected`.

## 6. `GeoDefaults`

`<GeoDefaults {...GeoConfigSource}>`: defaults for every map below, nested. The map hands every provider's source (outermost first) and its own props to one schema-aware merge (v0.5 § 8): `undefined` inherits; `false` switches a feature off and clears the inherited feature configuration; `true` switches it on; arrays replace; `[]` is explicitly empty; the declared records merge field by field (`legend.explanations`/`counts`, `zoom.gestures`, `contextMenu.features`, `export.image`/`csv`, `tooltip`, `header`); a `zoom.controls` of another variant replaces the whole variant (foreign variant fields are dropped with `variant-field-ignored`). **`null` resets** a declared `Resettable` path to the package (or instance) default past every provider; an undeclared `null` is `GEO_OPTION_CONFLICT`. `locale`, `t`, `diagnostics` and `components` are atomic. There is no default language and no default notation.

## 7. Words and notation

The package owns the keys (`GeoTranslationKey`), the host the words: `t(key, variables)`; `count` selects the plural form (`one`/`other`). `t` is required: there is no default language and no hidden English fallback. `englishGeoTranslator` is the package's English, passed on purpose. **`englishGeoMessages`** is the complete catalogue (every key with its English words, a plural key as `{one, other}`), for a host that writes its own translator: the keys and their `{{variables}}` are versioned public contract. Wherever the map joins a label and a value, or several texts, it asks the language (`geo.text.pair`, `geo.text.list`); it never concatenates words with its own punctuation. Host data (layer titles, measure and category labels, names, details) is the host's text and is never sent through `t`.

`locale` is the notation (`GeoPresentation`, the family's `ValuePresentation`: a BCP 47 tag or a presentation object with its number format); words and notation are independent: a German translator with an English notation is legitimate. Formatting runs through the inlined `@workspace/active-format`; the same declaration and value give the same text as in Charts.

**Direction.** The map takes the page's `dir`. Controls, legend, menu, table and the reading side of point labels follow it; the geography and the order of the host's objects never mirror. Every visible text run is an isolated run; no bidi control character is inserted. An image export is a left-to-right document.

P1e adds the keys `geo.nav.home`, `geo.nav.controlsHint`, `geo.nav.keysHint`, `geo.keyboardHintMenu`, `geo.menu.label`, `geo.menu.labelFor`, `geo.menu.showTable`, `geo.menu.hideTable`, `geo.menu.zoomHere`, `geo.menu.zoomTo`; removed keys are listed in the CHANGELOG.

## 8. Diagnostics

`GeoDiagnostic {level, source: 'ActiveGeo.GeoMap', message, data?}` to the sink, once per (code, path, value), never per render; `data` carries the code and the configuration path, never keys, names or values. Codes: `presentation-value-ignored` (a configuration value outside its contract, ignored), `variant-field-ignored`, `reference-pending` (a legend section names an explanation that is not there yet), `text-callback-failed`, `data-excluded`, `table-focus-violation` (a host moved the focus while asked not to), `table-request-failed`, `outlet-missing`, `scope-second-map`, `export-failed`.

## 9. Errors

`GeoConfigurationError {code, field, constraint, value?, message}`, thrown during render. Codes: `GEO_PRESENTATION_MISSING` (no `locale`), `GEO_TRANSLATOR_MISSING` (no `t`), `GEO_PROJECTION_INVALID`, `GEO_LAYER_INVALID`, `GEO_LAYER_ID_DUPLICATE`, `GEO_LAYER_OPTION_INVALID`, `GEO_ID_INVALID`, `GEO_MEASURE_INVALID`, `GEO_MEASURE_ID_DUPLICATE`, `GEO_ENCODING_REFERENCE_INVALID`, `GEO_SCALE_INCOMPATIBLE`, `GEO_PALETTE_INVALID`, `GEO_DATA_SOURCE_CONFLICT`, `GEO_LEGEND_GROUP_ID_DUPLICATE`, `GEO_OPTION_CONFLICT`, `GEO_OPTION_UNAVAILABLE` (an input of a later phase; `constraint` names the phase).

`GeoExportError {code, format, …}` rejects an export (and reaches `onExportError`): `EXPORT_BUSY`, `EXPORT_TOO_LARGE`, `EXPORT_CAPTURE_FAILED`, `EXPORT_NO_DATA`, `EXPORT_CANCELLED`, `EXPORT_INVALID_OPTION` (§ 12).

## 10. Rows, identity and exclusions

**One row model** (v0.5 § 11) for the snapshot, the table, the data alternative, the tooltip, CSV and a host grid: per data layer `{layerType, layerId, visible, measures, detailOrder, encodings, rows}`; an object row `{kind: 'object', rowId, ref, keyReading, name, geometry, geometryReason, link, linkReason, issues, position?, measurements, encodings, details, selected, highlighted, filteredOut}`; a record row (a value record without a drawn object) `{kind: 'record', …, link, linkReason}`. `rowId` is stable within one `revision`.

**Keys (D-9).** `GeoKey = string | number`: a non-empty string (exact, case-sensitive) or a finite number; `1` and `"1"` are two objects; `0` and `-0` one. The machine identity is `v1:` plus the JSON of the typed key (`keyReading.encoded`). Every holder of a key repeated within a layer is excluded (`duplicate-key`).

**Exclusion reasons:** `missing-key`, `invalid-key`, `duplicate-key`, `missing-geometry`, `unsupported-geometry`, `ring-too-short`, `non-finite-position`, `position-out-of-range`, `ring-not-closed`, `antimeridian-uncut`, `ring-zero-net-area`, `hole-outside-shell`, `densify-limit`, `object-empty`, `invalid-coordinate`, `latitude-out-of-range`, `longitude-out-of-range`, `not-projectable`. A degenerate exterior part is excluded from its area (`partial`); a degenerate hole is dropped.

## 11. Host composition

**Host components (D-36).** `components: {Button?, Toggle?, Input?}` render the map's own controls (navigation buttons, legend toggles, the table's search and pager, the menu button) in the host's design system. The map owns every action, its state, words, ARIA, keyboard and focus routes and layout, and checks an unavailable action again before it acts; the component owns only how the control looks. Spread the DOM props onto ONE interactive element and send `ref` to it; render `disabled` as `aria-disabled` (focusable), never native `disabled`; keep the given `className`; define the components once, at module scope. The menu, the tooltip, the table's tabs and rows, the steps of a compact scale and labels are Geo's own and not replaceable. Datyx's adapters for the Active UI Button, Toggle and Input: `apps/admin/components/shared/geo-components.tsx`.

| Slot | Props (besides `ref`, `id`, `className`, `aria-*`, `data-*`) |
| --- | --- |
| `Button` | `children`, `appearance: 'outline' \| 'quiet'`, `size: 'default' \| 'icon'`, `disabled`, `onClick`, `onFocus`, `tabIndex` |
| `Toggle` | `children`, `pressed`, `onPressedChange` |
| `Input` | `type: 'search'`, `value`, `onValueChange`, `placeholder` |

**Outlets (D-41).** `GeoMapScope` binds one map to a `GeoLegendOutlet` and a `GeoTableOutlet` anywhere inside it (`legend: {position: 'outlet'}`, `table: {position: 'outlet'}`). The map renders its own legend and table there through a portal: the same part, the same state and ARIA, never a copy; an image export never reads an outlet. One map per scope (a second one is reported, `scope-second-map`). A missing outlet makes the part fall back to the map's own layout and is reported (`outlet-missing`); a hidden outlet answers a reveal with `outlet-hidden` and takes no focus.

**A host legend.** Inside a `GeoMapScope`, `useGeoLegend()` returns `{model, activate}`: the map's own resolved legend model (sections, entries with `id`, `role`, `label`, `description`, `key`, `count`, `interactive`, `highlighted`) and the map's own activation route (`onLegendActivate` first, cancellable, then the effect). `null` model outside a scope or before the first frame.

**A host toolbar.** Switch the package parts off (`zoom: {controls: false}`, `contextMenu: {features: {export: false}}`) and call the handle; every handle method is the same route as the package's control.

```tsx
<GeoMapScope>
  <nav>
    <button onClick={() => void map.current?.exportAsPng()}>PNG</button>
    <button onClick={() => map.current?.home()}>Home</button>
  </nav>
  <GeoMap
    ref={map}
    title="Sales"
    projection="conic-equal-area"
    layers={layers}
    zoom={{controls: false}}
    contextMenu={{features: {export: false}}}
    legend={{position: 'outlet'}}
    table={{position: 'outlet'}}
  />
  <aside>
    <GeoLegendOutlet />
  </aside>
  <HostTab title="Table">
    <GeoTableOutlet />
  </HostTab>
</GeoMapScope>
```

## 12. Export

`exportAsPng`/`exportAsSvg(options?)` and `exportAsCsv({layerId, scope?, details?, text?, filename?, download?})`, and the menu's export group, which runs the same operation. One export at a time (a second one while one runs rejects with `GeoExportError` `EXPORT_BUSY`; the menu shows its items disabled meanwhile).

- **Image** (`GeoImageExportOptions`: the `export.image` fields plus `filename` and `download`, default `true`): the current view or the fitted map; the title, description and attribution; the legend `'presentation'` (what the screen explains), `'all'`, `false`, or a layout `{content, position: 'bottom' | 'end', arrangement, sections}`; labels placed by the export's own placement (D-30, W-7); an explicit theme (`light`, `dark`, `current`; `export.themes` declares how a host's mode is an attribute); `scale` (PNG pixel ratio); system fonts only (D-32). A PNG within `limits.pngMaxPixels`, an SVG within `limits.svgMaxBytes` (else `GeoExportError` `EXPORT_TOO_LARGE`; the menu shows the item disabled with its reason).
- **CSV v2** (D-43): one file per data layer, one row per snapshot row. Columns `csv_version` (2), `layer`, `level`, `row_kind` (`object`, `record`), `key`, `key_type`, `key_encoded`, `name`, `geometry`, `geometry_reason`, `link_status`, `link_reason`, `issues`, `longitude`, `latitude`; per measure `measure:<id>:value`, `:unit` (money and price: the currency; percent: its source), `:status`, and with `text: true` `:text`; with `details: true` one `detail:<id>` per detail id. Text passes the family's delimited-text boundary (quoting, formula neutralisation); numbers the machine number form; a category is written as its id; a withheld value is never written. `scope: 'selected'` exports the selected objects.
- **Result** `{format, filename, blob, downloadStarted, frame?, revision, presentationRevision, warnings}`: the revisions captured. An export captures one consistent frame: props that change while it runs do not mix into it.

## 13. `GeoValueSemantics`

Exactly the shape of `ChartValueSemantics` (active-charts): `number` (`format?`), `count`, `money` (`currency`, `decimals?`), `price` (`currency`, `decimals`), `percent` (`source`, `preset?`). Without it: integer or two decimals.

## 14. Styling

One stylesheet, imported by the entry (a side effect, as in Charts), every rule under `.active-geo`; the private defaults on `:root` and `.dark`. Colour tokens and the font are listed in the README. The package defaults follow the host's `.dark` class; any host value for a `--geo-*` token wins. States never share a cue (D-27): selection is a solid line over the halo, focus a dashed line, highlight dims the rest of the layer, a missing value is hatched, a withheld value has its own pattern. On-demand controls are transparent and without pointer events in rest but keep their place and tab stop; reduced motion switches transitions off; forced colours map strokes, selection and focus to system colours. A host restyles the map through tokens and `components`, never by hiding package parts with its own CSS.

## 15. Starter collection (D-26)

An optional second entry, `@workspace/active-geo/collections/world-50m`: Natural Earth Admin 0 – Countries at 1:50m (theme version 5.1.1, release tag v5.1.2), 242 areas. The runtime entry `.` never reaches it; a host that does not import it carries no geography.

| Export | Kind |
| --- | --- |
| `world50m` | Constant |
| `loadWorld50m` | Function |
| `GeoWorld50mMetadata`, `GeoCountryFeature`, `GeoCountryCodes`, `GeoCountryAttributes`, `GeoCountryGeometry`, `GeoCountryRing`, `GeoCountryPosition` | Types |

```tsx
import {GeoMap, englishGeoTranslator} from '@workspace/active-geo';
import {
  loadWorld50m,
  world50m,
} from '@workspace/active-geo/collections/world-50m';

const features = await loadWorld50m();
<GeoMap
  title="Sales by country"
  projection="equal-earth"
  locale="en-US"
  t={englishGeoTranslator}
  dataset={world50m.dataset}
  attribution={world50m.attribution}
  layers={[
    {
      type: 'area',
      id: 'world',
      title: 'Countries',
      features,
      measures: [{id: 'sales', label: 'Sales'}],
      data: records, // [{key: 'NLD', values: {sales: 120}}, …], joined by key
      fill: {measure: 'sales', scale: {type: 'quantize', classes: 5}},
    },
  ]}
/>;
```

**Metadata, no geometry.** `world50m` is available synchronously and loads no geometry: `dataset` (`{id: 'active-geo/world-50m', version: 'ne-5.1.1+r1'}`, for `dataset` and restorable state), `source`, `rights` (public domain), `attribution`, `boundaryPolicy`, `featureCount` (242), `bounds`, `crs`, `convention` (`rfc7946`), `key` and `transformation`.

**Loading.** `loadWorld50m()` imports the geometry on its first call (a separate chunk with a code-splitting bundler, about 236 KB gzip) and resolves to the 242 areas in source order. Every call resolves to the same frozen array. A failed load rejects; the next call tries again. The package makes no network request of its own.

**Areas and joining.** A `GeoCountryFeature` is an area feature: `key` (`ADM0_A3`, the join key), `name` (English, display only), `geometry`, `codes` (`neId`, `isoA3`, `isoA2`, `isoN3`, `wikidata`), `attributes`. Records join by `key` only: no name matching, no code translation. The codes are no key (`isoA3` `AUS` belongs to three areas). The collection follows Natural Earth's default de facto representation and takes no position on sovereignty. Known limits: 1:50m generalisation; no names in other languages.

**Rebuilding.** `node packages/active-geo/scripts/build-world-50m.mjs fetch | build | check` (sources and rights: `scripts/world-50m.sources.json`).

## 16. Environment and distribution

Modern browsers with ES2022, `ResizeObserver`, Canvas 2D, `Path2D` and `Intl.NumberFormat`; a client component (SSR renders the container, the map draws after hydration). Peer dependencies React and React DOM 19; runtime `d3-geo`, `d3-scale`, `@base-ui/react` (menu, direction), and `date-fns` and `@date-fns/tz`, which the formatter owner reaches (standard `RPS-R8`). The owner entries `@workspace/active-format`, `@workspace/active-utils/menu-items` and `/serialization` are the closure `lint-portable-closure` guards (D-1, v0.5 § 14). In another repository the owners arrive as managed packages through `rps:transfer` and `rps-apply`, `active-utils` as the compatibility selection `portable-helpers`; `@workspace/active-i18n` is not required. **Not yet proved:** an external example consumer and a recorded release (ROADMAP R-69); the manifest is `private: true` with source exports. Transfer: `docs/platform/HERBRUIKBARE-PACKAGES.md` (source repository: `docs/platform/HERBRUIKBARE-PACKAGES.md`).

## All exports, from the source

### `@workspace/active-geo`

**[React](/packages/active-geo/api/react)**

| Export | Kind | Description |
| --- | --- | --- |
| [`GeoMap`](/packages/active-geo/api/react#api-geomap) | component |  |
| [`GeoMapProps`](/packages/active-geo/api/react#active-geo-geomapprops) | interface |  |
| [`GeoDefaults`](/packages/active-geo/api/react#api-geodefaults) | component | Supplies configuration to every map rendered in its subtree. |
| [`GeoDefaultsProps`](/packages/active-geo/api/react#active-geo-geodefaultsprops) | interface |  |
| [`useGeoLegend`](/packages/active-geo/api/react#active-geo-usegeolegend) | hook |  |

**[Exports](/packages/active-geo/api/exports)**

| Export | Kind | Description |
| --- | --- | --- |
| [`GeoLegendOutlet`](/packages/active-geo/api/exports#api-geolegendoutlet) | component | Where the scope's map shows its legend (`placement: 'outlet'`). |
| [`GeoMapScope`](/packages/active-geo/api/exports#api-geomapscope) | component | Binds one map to the legend and table outlets placed anywhere inside it. |
| [`GeoTableOutlet`](/packages/active-geo/api/exports#api-geotableoutlet) | component | Where the scope's map shows its table (`table: 'outlet'`). |
| [`GeoMapScopeProps`](/packages/active-geo/api/exports#active-geo-geomapscopeprops) | interface |  |
| [`GeoOutletProps`](/packages/active-geo/api/exports#active-geo-geooutletprops) | interface |  |
| [`GeoAreaGeometry`](/packages/active-geo/api/exports#active-geo-geoareageometry) | type | The geometry of an area: a polygon or a multipolygon. |
| [`GeoButtonSlotProps`](/packages/active-geo/api/exports#active-geo-geobuttonslotprops) | interface | What the map hands a host BUTTON. |
| [`GeoComponents`](/packages/active-geo/api/exports#active-geo-geocomponents) | interface | Host components for the map's standard controls. |
| [`GeoContextGeometry`](/packages/active-geo/api/exports#active-geo-geocontextgeometry) | type | The geometry a context layer draws: areas and lines, nothing else. |
| [`GeoContextLayer`](/packages/active-geo/api/exports#active-geo-geocontextlayer) | interface | Geographic context: drawn, never interactive, never in the legend. |
| [`GeoDatasetIdentity`](/packages/active-geo/api/exports#active-geo-geodatasetidentity) | interface | The identity of the data a map shows, declared by the host. |
| [`GeoDivergingScale`](/packages/active-geo/api/exports#active-geo-geodivergingscale) | interface | Classes on either side of a reference value the host names. |
| [`GeoExportFormat`](/packages/active-geo/api/exports#active-geo-geoexportformat) | type | The formats a map exports. |
| [`GeoExportLimits`](/packages/active-geo/api/exports#active-geo-geoexportlimits) | interface | The limits of the map's exports. |
| [`GeoExportTheme`](/packages/active-geo/api/exports#active-geo-geoexporttheme) | type | The colours of an exported image: `light` (default) and `dark` are explicit export themes, independent of what the screen shows; `current` is the theme the map shows now. |
| [`GeoExportThemeMarker`](/packages/active-geo/api/exports#active-geo-geoexportthememarker) | interface | How a host whose colour modes are an ATTRIBUTE (for example `data-theme="dark"` on the document root) expresses one mode, so an explicit `light` or `dark` export can reproduce it. |
| [`GeoExportThemes`](/packages/active-geo/api/exports#active-geo-geoexportthemes) | interface | The host's attribute for each colour mode (`exportThemes`). |
| [`GeoInputSlotProps`](/packages/active-geo/api/exports#active-geo-geoinputslotprops) | interface | What the map hands a host text INPUT (the table's search). |
| [`GeoItemRef`](/packages/active-geo/api/exports#active-geo-geoitemref) | interface | A reference to one map object: its layer and its key in that layer. |
| [`GeoKey`](/packages/active-geo/api/exports#active-geo-geokey) | type | The key of a map object: a non-empty string or a finite number. |
| [`GeoLevel`](/packages/active-geo/api/exports#active-geo-geolevel) | interface | One level of the host's geographic hierarchy, as the map names it. |
| [`GeoLevelRequest`](/packages/active-geo/api/exports#active-geo-geolevelrequest) | interface | The map asks the host for a level: from the level path, or from the host's own action (`requestLevel`, for example an object action that drills into an area). |
| [`GeoLineString`](/packages/active-geo/api/exports#active-geo-geolinestring) | interface | A GeoJSON `LineString` of at least two positions. |
| [`GeoMultiLineString`](/packages/active-geo/api/exports#active-geo-geomultilinestring) | interface | A GeoJSON `MultiLineString`. |
| [`GeoMultiPolygon`](/packages/active-geo/api/exports#active-geo-geomultipolygon) | interface | A GeoJSON `MultiPolygon`: one or more polygons. |
| [`GeoPointRenderer`](/packages/active-geo/api/exports#active-geo-geopointrenderer) | type | How a point layer is drawn. |
| [`GeoPolygon`](/packages/active-geo/api/exports#active-geo-geopolygon) | interface | A GeoJSON `Polygon`: an exterior ring followed by its holes. |
| [`GeoPosition`](/packages/active-geo/api/exports#active-geo-geoposition) | type | A GeoJSON position: `[longitude, latitude]` in degrees. |
| [`GeoPresentation`](/packages/active-geo/api/exports#active-geo-geopresentation) | type | How values and coordinates are formatted: a BCP 47 locale tag or an explicit presentation context (`@workspace/active-format`). |
| [`GeoProjection`](/packages/active-geo/api/exports#active-geo-geoprojection) | type | The projection of a map. |
| [`GeoRing`](/packages/active-geo/api/exports#active-geo-georing) | type | A closed ring: the first and last position are equal. |
| [`GeoRingConvention`](/packages/active-geo/api/exports#active-geo-georingconvention) | type | How the rings and edges of a layer are meant, declared by the host: |
| [`GeoSelectionOptions`](/packages/active-geo/api/exports#active-geo-geoselectionoptions) | interface | Selection behaviour of a map. |
| [`GeoToggleSlotProps`](/packages/active-geo/api/exports#active-geo-geotoggleslotprops) | interface | What the map hands a host TOGGLE (a two-state button: a legend entry). |
| [`GeoValueSemantics`](/packages/active-geo/api/exports#active-geo-geovaluesemantics) | type | What a numeric value means, declared once per layer. |

**[Types](/packages/active-geo/api/types)**

| Export | Kind | Description |
| --- | --- | --- |
| [`FeatureOption`](/packages/active-geo/api/types#active-geo-featureoption) | type | `true` on (the farther object kept), `false` off, an object refines. |
| [`GeoApplyStateOptions`](/packages/active-geo/api/types#active-geo-geoapplystateoptions) | interface |  |
| [`GeoApplyStateResult`](/packages/active-geo/api/types#active-geo-geoapplystateresult) | interface |  |
| [`GeoAreaFeature`](/packages/active-geo/api/types#active-geo-geoareafeature) | interface |  |
| [`GeoAreaLayer`](/packages/active-geo/api/types#active-geo-geoarealayer) | interface |  |
| [`GeoAttribution`](/packages/active-geo/api/types#active-geo-geoattribution) | type |  |
| [`GeoCategoryDefinition`](/packages/active-geo/api/types#active-geo-geocategorydefinition) | interface |  |
| [`GeoCategoryMeasure`](/packages/active-geo/api/types#active-geo-geocategorymeasure) | interface |  |
| [`GeoChannel`](/packages/active-geo/api/types#active-geo-geochannel) | type | Every channel. |
| [`GeoClassScale`](/packages/active-geo/api/types#active-geo-geoclassscale) | type | Classed colour scales; `classLabels` by class index. |
| [`GeoClusterSnapshot`](/packages/active-geo/api/types#active-geo-geoclustersnapshot) | interface | OUTPUT, dormant before P4: a cluster as a menu target and in events. |
| [`GeoColor`](/packages/active-geo/api/types#active-geo-geocolor) | type |  |
| [`GeoColorMapping`](/packages/active-geo/api/types#active-geo-geocolormapping) | interface | P1 colour: an own classed scale (no continuous, no shared reference). |
| [`GeoConfigSource`](/packages/active-geo/api/types#active-geo-geoconfigsource) | interface | The configuration a source (package, provider, props) can carry. |
| [`GeoContextMenuOptions`](/packages/active-geo/api/types#active-geo-geocontextmenuoptions) | interface |  |
| [`GeoCorner`](/packages/active-geo/api/types#active-geo-geocorner) | type |  |
| [`GeoCsvExportOptions`](/packages/active-geo/api/types#active-geo-geocsvexportoptions) | interface |  |
| [`GeoCustomLegendEntry`](/packages/active-geo/api/types#active-geo-geocustomlegendentry) | interface | P1 custom key: a swatch or a circle. |
| [`GeoDataLayerType`](/packages/active-geo/api/types#active-geo-geodatalayertype) | type |  |
| [`GeoDataRecord`](/packages/active-geo/api/types#active-geo-geodatarecord) | interface | A value record joined by key; never together with inline `values`. |
| [`GeoDescribe`](/packages/active-geo/api/types#active-geo-geodescribe) | type |  |
| [`GeoDetail`](/packages/active-geo/api/types#active-geo-geodetail) | interface |  |
| [`GeoEffectivePresentation`](/packages/active-geo/api/types#active-geo-geoeffectivepresentation) | interface | What `getEffectivePresentation()` reports. |
| [`GeoEncodingReading`](/packages/active-geo/api/types#active-geo-geoencodingreading) | type |  |
| [`GeoEncodingSnapshot`](/packages/active-geo/api/types#active-geo-geoencodingsnapshot) | interface |  |
| [`GeoEncodingStatus`](/packages/active-geo/api/types#active-geo-geoencodingstatus) | type |  |
| [`GeoExplanationOptions`](/packages/active-geo/api/types#active-geo-geoexplanationoptions) | interface |  |
| [`GeoExplanationPart`](/packages/active-geo/api/types#active-geo-geoexplanationpart) | type |  |
| [`GeoExplanationRef`](/packages/active-geo/api/types#active-geo-geoexplanationref) | type |  |
| [`GeoExplanationRefInput`](/packages/active-geo/api/types#active-geo-geoexplanationrefinput) | type | The explanation references a P1 host can write. |
| [`GeoExportLegendLayout`](/packages/active-geo/api/types#active-geo-geoexportlegendlayout) | interface |  |
| [`GeoExportOptions`](/packages/active-geo/api/types#active-geo-geoexportoptions) | interface |  |
| [`GeoExportResult`](/packages/active-geo/api/types#active-geo-geoexportresult) | interface |  |
| [`GeoExportWarning`](/packages/active-geo/api/types#active-geo-geoexportwarning) | interface |  |
| [`GeoExportWarningCode`](/packages/active-geo/api/types#active-geo-geoexportwarningcode) | type |  |
| [`GeoFeatureQuery`](/packages/active-geo/api/types#active-geo-geofeaturequery) | interface |  |
| [`GeoFeatureSnapshot`](/packages/active-geo/api/types#active-geo-geofeaturesnapshot) | interface |  |
| [`GeoFill`](/packages/active-geo/api/types#active-geo-geofill) | type |  |
| [`GeoFocusReturn`](/packages/active-geo/api/types#active-geo-geofocusreturn) | interface |  |
| [`GeoGeometryStatus`](/packages/active-geo/api/types#active-geo-geogeometrystatus) | type |  |
| [`GeoHeaderOptions`](/packages/active-geo/api/types#active-geo-geoheaderoptions) | interface |  |
| [`GeoHighlight`](/packages/active-geo/api/types#active-geo-geohighlight) | interface | A non-empty set of targets; `fingerprints` binds them to their meaning. |
| [`GeoHighlightChange`](/packages/active-geo/api/types#active-geo-geohighlightchange) | interface |  |
| [`GeoHighlightTarget`](/packages/active-geo/api/types#active-geo-geohighlighttarget) | interface | One highlight target a P1 host can write: an entry of an own explanation (`encoding`, `layer`, `custom`). |
| [`GeoHome`](/packages/active-geo/api/types#active-geo-geohome) | type | Where `home()` goes; `fit()` is always the frame. |
| [`GeoId`](/packages/active-geo/api/types#active-geo-geoid) | type | A host-chosen identifier (measures, categories, details, sections, custom entries, status blocks): `/^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$/`. |
| [`GeoImageExportDefaults`](/packages/active-geo/api/types#active-geo-geoimageexportdefaults) | interface |  |
| [`GeoImageExportOptions`](/packages/active-geo/api/types#active-geo-geoimageexportoptions) | interface | One image export of the handle or the menu (P1 projection of § 15). |
| [`GeoInputChannel`](/packages/active-geo/api/types#active-geo-geoinputchannel) | type | The channels a P1 host can encode. |
| [`GeoInvalidReason`](/packages/active-geo/api/types#active-geo-geoinvalidreason) | type |  |
| [`GeoItem`](/packages/active-geo/api/types#active-geo-geoitem) | interface | A map object as reported. |
| [`GeoKeyReading`](/packages/active-geo/api/types#active-geo-geokeyreading) | interface | A key with its machine identity (`v1:` + JSON). |
| [`GeoLabelOptions`](/packages/active-geo/api/types#active-geo-geolabeloptions) | interface |  |
| [`GeoLayer`](/packages/active-geo/api/types#active-geo-geolayer) | type |  |
| [`GeoLayerSnapshot`](/packages/active-geo/api/types#active-geo-geolayersnapshot) | interface |  |
| [`GeoLayerTooltipOptions`](/packages/active-geo/api/types#active-geo-geolayertooltipoptions) | interface |  |
| [`GeoLegendActivation`](/packages/active-geo/api/types#active-geo-geolegendactivation) | interface | Activation of one resolved legend entry, cancellable. |
| [`GeoLegendEntryRef`](/packages/active-geo/api/types#active-geo-geolegendentryref) | interface |  |
| [`GeoLegendHook`](/packages/active-geo/api/types#active-geo-geolegendhook) | interface | Inside a `GeoMapScope`: the legend model and its action, for a host legend. |
| [`GeoLegendKey`](/packages/active-geo/api/types#active-geo-geolegendkey) | type | OUTPUT: `line` and `gradient` keys dormant in P1. |
| [`GeoLegendModel`](/packages/active-geo/api/types#active-geo-geolegendmodel) | interface |  |
| [`GeoLegendModelEntry`](/packages/active-geo/api/types#active-geo-geolegendmodelentry) | interface |  |
| [`GeoLegendOptions`](/packages/active-geo/api/types#active-geo-geolegendoptions) | interface |  |
| [`GeoLegendPosition`](/packages/active-geo/api/types#active-geo-geolegendposition) | type |  |
| [`GeoLegendSection`](/packages/active-geo/api/types#active-geo-geolegendsection) | interface |  |
| [`GeoLegendSectionItem`](/packages/active-geo/api/types#active-geo-geolegendsectionitem) | type |  |
| [`GeoLinkStatus`](/packages/active-geo/api/types#active-geo-geolinkstatus) | type |  |
| [`GeoMapHandle`](/packages/active-geo/api/types#active-geo-geomaphandle) | interface | The map's handle (P1 projection: no `project`/`invert`). |
| [`GeoMapState`](/packages/active-geo/api/types#active-geo-geomapstate) | interface |  |
| [`GeoMarker`](/packages/active-geo/api/types#active-geo-geomarker) | interface | P1 marker: circles only. |
| [`GeoMeasure`](/packages/active-geo/api/types#active-geo-geomeasure) | type |  |
| [`GeoMeasurementReading`](/packages/active-geo/api/types#active-geo-geomeasurementreading) | type |  |
| [`GeoMeasurementStatus`](/packages/active-geo/api/types#active-geo-geomeasurementstatus) | type |  |
| [`GeoMenuContext`](/packages/active-geo/api/types#active-geo-geomenucontext) | interface | One opening of the menu, frozen while it stays open. |
| [`GeoMenuFeatures`](/packages/active-geo/api/types#active-geo-geomenufeatures) | interface |  |
| [`GeoMenuGroup`](/packages/active-geo/api/types#active-geo-geomenugroup) | type |  |
| [`GeoMenuItem`](/packages/active-geo/api/types#active-geo-geomenuitem) | type | One item of the map's menu: the family's item (active-helpers `menu-items`), acting on the opening's `GeoMenuContext`. |
| [`GeoMenuTarget`](/packages/active-geo/api/types#active-geo-geomenutarget) | type | OUTPUT: what a menu was opened on; `cluster` is dormant before P4. |
| [`GeoNavigationAction`](/packages/active-geo/api/types#active-geo-geonavigationaction) | type |  |
| [`GeoNumberMeasure`](/packages/active-geo/api/types#active-geo-geonumbermeasure) | interface |  |
| [`GeoObjectSnapshot`](/packages/active-geo/api/types#active-geo-geoobjectsnapshot) | interface |  |
| [`GeoObjectTextContext`](/packages/active-geo/api/types#active-geo-geoobjecttextcontext) | interface | What a text callback sees. |
| [`GeoPalette`](/packages/active-geo/api/types#active-geo-geopalette) | type |  |
| [`GeoPointDatum`](/packages/active-geo/api/types#active-geo-geopointdatum) | interface |  |
| [`GeoPointLayer`](/packages/active-geo/api/types#active-geo-geopointlayer) | interface |  |
| [`GeoRecordLink`](/packages/active-geo/api/types#active-geo-georecordlink) | type |  |
| [`GeoRecordSnapshot`](/packages/active-geo/api/types#active-geo-georecordsnapshot) | interface |  |
| [`GeoResolvedVectorSymbol`](/packages/active-geo/api/types#active-geo-georesolvedvectorsymbol) | interface | OUTPUT: the vector form of a symbol, fully resolved. |
| [`GeoRowIssue`](/packages/active-geo/api/types#active-geo-georowissue) | type |  |
| [`GeoRowSnapshot`](/packages/active-geo/api/types#active-geo-georowsnapshot) | type |  |
| [`GeoScaleEntry`](/packages/active-geo/api/types#active-geo-geoscaleentry) | type |  |
| [`GeoSelectionChange`](/packages/active-geo/api/types#active-geo-geoselectionchange) | type | OUTPUT: `cluster` is dormant in P1. |
| [`GeoSizeMapping`](/packages/active-geo/api/types#active-geo-geosizemapping) | interface | Area ∝ value; the radius of the equal-area circle. |
| [`GeoSpecialStatus`](/packages/active-geo/api/types#active-geo-geospecialstatus) | type |  |
| [`GeoStateDisposition`](/packages/active-geo/api/types#active-geo-geostatedisposition) | type |  |
| [`GeoStateEntryResult`](/packages/active-geo/api/types#active-geo-geostateentryresult) | type |  |
| [`GeoStateField`](/packages/active-geo/api/types#active-geo-geostatefield) | type |  |
| [`GeoStateFieldResult`](/packages/active-geo/api/types#active-geo-geostatefieldresult) | interface |  |
| [`GeoStateReason`](/packages/active-geo/api/types#active-geo-geostatereason) | type |  |
| [`GeoSuppressed`](/packages/active-geo/api/types#active-geo-geosuppressed) | interface |  |
| [`GeoTableOptions`](/packages/active-geo/api/types#active-geo-geotableoptions) | interface |  |
| [`GeoTableRequest`](/packages/active-geo/api/types#active-geo-geotablerequest) | interface |  |
| [`GeoTableRequestOutcome`](/packages/active-geo/api/types#active-geo-geotablerequestoutcome) | type |  |
| [`GeoTableRevealFailure`](/packages/active-geo/api/types#active-geo-geotablerevealfailure) | type |  |
| [`GeoTableRevealResult`](/packages/active-geo/api/types#active-geo-geotablerevealresult) | type | Every reveal settles exactly once with one of these. |
| [`GeoTextField`](/packages/active-geo/api/types#active-geo-geotextfield) | type | P1 text fields: encoding fields on P1 channels only. |
| [`GeoTooltipOptions`](/packages/active-geo/api/types#active-geo-geotooltipoptions) | interface |  |
| [`GeoUnrepresentableReason`](/packages/active-geo/api/types#active-geo-geounrepresentablereason) | type | OUTPUT: `negative-width` and `not-rotatable` dormant in P1. |
| [`GeoValueInput`](/packages/active-geo/api/types#active-geo-geovalueinput) | type | A number, a category id, `null`/absent (missing) or `{suppressed: true}`. |
| [`GeoValues`](/packages/active-geo/api/types#active-geo-geovalues) | type |  |
| [`GeoView`](/packages/active-geo/api/types#active-geo-geoview) | type | One value for coordinates AND mode, controlled or uncontrolled. |
| [`GeoViewCause`](/packages/active-geo/api/types#active-geo-geoviewcause) | type |  |
| [`GeoViewChange`](/packages/active-geo/api/types#active-geo-geoviewchange) | interface |  |
| [`GeoViewMode`](/packages/active-geo/api/types#active-geo-geoviewmode) | type |  |
| [`GeoVisualValue`](/packages/active-geo/api/types#active-geo-geovisualvalue) | type | OUTPUT: `width`, `shape`, `rotation` dormant in P1. |
| [`GeoZoomControls`](/packages/active-geo/api/types#active-geo-geozoomcontrols) | type |  |
| [`GeoZoomOptions`](/packages/active-geo/api/types#active-geo-geozoomoptions) | interface |  |
| [`Resettable`](/packages/active-geo/api/types#active-geo-resettable) | type | `null` on a declared path resets it to the package or instance default. |

**[Configuration error](/packages/active-geo/api/configuration-error)**

| Export | Kind | Description |
| --- | --- | --- |
| [`GeoConfigurationError`](/packages/active-geo/api/configuration-error#active-geo-geoconfigurationerror) | class | A map configuration the map cannot run with. |
| [`GeoConfigurationErrorCode`](/packages/active-geo/api/configuration-error#active-geo-geoconfigurationerrorcode) | type | The closed set of configuration mistakes the map refuses. |
| [`GeoConfigurationErrorOptions`](/packages/active-geo/api/configuration-error#active-geo-geoconfigurationerroroptions) | interface |  |

**[Export](/packages/active-geo/api/export)**

| Export | Kind | Description |
| --- | --- | --- |
| [`GeoExportError`](/packages/active-geo/api/export#active-geo-geoexporterror) | class | An export that produced no file. |
| [`GeoExportErrorCode`](/packages/active-geo/api/export#active-geo-geoexporterrorcode) | type |  |
| [`GeoExportErrorOptions`](/packages/active-geo/api/export#active-geo-geoexporterroroptions) | interface |  |

**[Translator](/packages/active-geo/api/translator)**

| Export | Kind | Description |
| --- | --- | --- |
| [`englishGeoMessages`](/packages/active-geo/api/translator#active-geo-englishgeomessages) | constant | The package's key catalogue with its English words, for a host that writes its own translator: every key, its `{{variables}}`, and a plural key as `one`/`other`. |
| [`englishGeoTranslator`](/packages/active-geo/api/translator#active-geo-englishgeotranslator) | function | The package's English, with `{{name}}` interpolation and one/other plurals. |
| [`GeoTranslateFn`](/packages/active-geo/api/translator#active-geo-geotranslatefn) | type |  |
| [`GeoTranslationKey`](/packages/active-geo/api/translator#active-geo-geotranslationkey) | type | Every key the package asks for. |
| [`GeoTranslationVariables`](/packages/active-geo/api/translator#active-geo-geotranslationvariables) | type | Interpolation values; `count` also selects a plural form. |

**[Diagnostics](/packages/active-geo/api/diagnostics)**

| Export | Kind | Description |
| --- | --- | --- |
| [`GeoDiagnostic`](/packages/active-geo/api/diagnostics#active-geo-geodiagnostic) | interface |  |
| [`GeoDiagnosticLevel`](/packages/active-geo/api/diagnostics#active-geo-geodiagnosticlevel) | type | Diagnostics go to a sink the host passes (`diagnostics` on the map), the same contract as the Active chart and grid packages. |
| [`GeoDiagnosticSink`](/packages/active-geo/api/diagnostics#active-geo-geodiagnosticsink) | type |  |

### `@workspace/active-geo/collections/world-50m`

**[World 50m](/packages/active-geo/api/world-50m)**

| Export | Kind | Description |
| --- | --- | --- |
| [`GeoCountryAttributes`](/packages/active-geo/api/world-50m#world-50m-geocountryattributes) | interface | Source attributes with their Natural Earth meaning; no hierarchy. |
| [`GeoCountryCodes`](/packages/active-geo/api/world-50m#world-50m-geocountrycodes) | interface | Codes of the source, for a host that maps its own records to keys. |
| [`GeoCountryFeature`](/packages/active-geo/api/world-50m#world-50m-geocountryfeature) | interface | One area of the collection. |
| [`GeoCountryGeometry`](/packages/active-geo/api/world-50m#world-50m-geocountrygeometry) | type |  |
| [`GeoCountryPosition`](/packages/active-geo/api/world-50m#world-50m-geocountryposition) | type | The public shapes of the world-50m collection. |
| [`GeoCountryRing`](/packages/active-geo/api/world-50m#world-50m-geocountryring) | type |  |
| [`GeoWorld50mMetadata`](/packages/active-geo/api/world-50m#world-50m-geoworld50mmetadata) | type | The collection's provenance and identity; loads no geometry. |
| [`world50m`](/packages/active-geo/api/world-50m#world-50m-world50m) | constant | Source, version, rights, boundary policy, bounds and build of the collection. |
| [`loadWorld50m`](/packages/active-geo/api/world-50m#world-50m-loadworld50m) | function | Loads and decodes the collection's 242 areas, in source order. |