portal-mojo 0.1.0

package/docs/timepicker.md

@@ -0,0 +1,173 @@
+# TimePicker
+
+The stepper time input, ported from web-mojo `forms/inputs/TimePicker.js`
+(648 lines) — the source's locked **variant B**: per unit a column of
+▲ / value input / ▼ / label, with direct numeric typing on the value. Built
+on the shared [`Popover`](popover.md) and the `parseTime`/`formatTime`/
+`compareTime`/`ianaOffset` half of [`dateFns`](calendar.md). No wheels (the
+source deferred those to a future mobile mode), no library.
+
+```ts
+import { TimePicker } from 'portal-mojo/ui';
+import type { TimeValue, TimeChangeEvent, TimeOutputFormat } from 'portal-mojo/ui';
+```
+
+## Value shapes (the contract)
+
+Storage is **always canonical 24h `HH:MM` internally** — `format` only
+decides what the panel and trigger render. `outputFormat` decides what
+leaves:
+
+| `outputFormat` | with a zone | without a zone | empty |
+|---|---|---|---|
+| `'iso'` (default) | `'14:30-07:00'` | `'14:30'` | `''` |
+| `'iana'` (legacy) | `'14:30 America/Los_Angeles'` | `'14:30'` | `''` |
+| `'object'` | `{time: '14:30', timezone: 'America/Los_Angeles'}` | `'14:30'` (string!) | `null` |
+
+`'object'` only produces an object when the zone picker is enabled —
+otherwise it degrades to the `'iso'` string, exactly as the source did.
+
+**Everything above parses back in**, plus two more shapes the source
+accepted (`_parseInitial`, ported line for line):
+
+- 12h text — `'2:30 PM'` (an AM/PM tail belongs to the time, not the zone)
+- ISO offsets in every spelling — `'14:30Z'` → zone `+00:00`,
+  `'14:30+0530'` → `+05:30`, `'14:30-07:00'` → `-07:00`
+- IANA tails — `'14:30 America/New_York'`
+- bare `'14:30'` / `'9:05'`
+
+Invalid text parses to `null` (empty picker) — `parseTime` never throws.
+
+## API
+
+| Prop | Notes |
+|---|---|
+| `value` | `string \| {time, timezone} \| null` — see above. Omit entirely for an uncontrolled picker. |
+| `onChange` | `({value, formatted, oldValue})` — fires on **commit only**, and only when the serialized string actually changed |
+| `format` | `'24h'` (default) \| `'12h'`. Unknown values warn + fall back |
+| `step` | minute stepping increment, ≥1 (default 1). Hours always step by 1 |
+| `min` / `max` | time strings (`"09:00"`, `"5:30 pm"` — `parseTime` parses them); clamped on **every** commit path |
+| `placeholder` | default `'HH:MM'` / `'h:mm AM/PM'` |
+| `disabled` / `readOnly` / `required` / `invalid` | trigger states; `required` and `readOnly` also suppress the clear ✕ |
+| `inline` | render the panel in place — no trigger, no popover |
+| `showFooter` | `false` → the embeddable footerless panel (DateTimePicker's time column) |
+| `timezone` | `true` enables the zone picker; a `string[]` enables it **and is the zone list** |
+| `timezones` | zone list when `timezone` is `true` (default: Intl's full list) |
+| `outputFormat` | `'iso'` \| `'iana'` \| `'object'`. Unknown values warn + fall back |
+| `renderTimezoneSelect` | the zone-picker slot — see below |
+| `name` | renders a hidden input carrying the serialized string (native-form use) |
+| `className` | appended to the root |
+
+`TimeChangeEvent.oldValue` is always the **previous canonical serialized
+string** (`''` when empty), never the object form — it is the diffing key,
+not a mirror of `value`.
+
+## The timezone seam
+
+`TimePicker` owns every bit of the zone's value and serialization logic but
+renders the picker itself through a slot:
+
+```tsx
+<TimePicker
+  timezone
+  renderTimezoneSelect={({ value, onChange, timezones, disabled }) => (
+    <TimezoneSelect value={value} onChange={onChange} timezones={timezones} disabled={disabled} />
+  )}
+/>
+```
+
+Without the prop it falls back to a plain token-styled `<select>` built from
+`Intl.supportedValuesOf('timeZone')` (curated ~50-zone list + a `console.warn`
+when Intl can't supply one), so the feature is complete standalone. Swapping
+in the real `TimezoneSelect` changes nothing about the value pipeline — the
+slot only renders. A zone the list doesn't contain still renders as its own
+option (never "render nothing") with a warn.
+
+## Behavior invariants (from source, keep them true)
+
+- **Commit-only pipeline.** Typing into a column writes a *draft*, which can
+  never be read as the value. `onChange` fires on: stepper click, ArrowUp/
+  Down, Enter (which commits by blurring), blur, AM/PM, Now, Set-on-empty,
+  clear, zone pick. Re-committing the same value is silent.
+- **Column typing.** Digits only (the keydown blocks the rest; ⌘/^/⌥
+  shortcuts pass through — a fix over source, which ate ⌘A/⌘V). Focus
+  selects the whole field; `maxLength` is 2; a blur clamps — 12h hours
+  1–12, 24h hours 0–23, minutes 0–59 — and an empty field reverts to the
+  displayed value.
+- **12h hour math** is the fiddly part: **12 AM = 0**, **12 PM = 12**, and a
+  typed hour maps through the *current* AM/PM state (PM + `3` → `15:00`).
+  AM/PM on an empty picker seeds `00:00` / `12:00`.
+- **Minute stepping honors `step`** via total-minutes math and wraps across
+  midnight in BOTH directions (`23:45` +15 → `00:00`; `00:00` −15 →
+  `23:45`). Hours wrap 0–23. Typing is not constrained to `step`.
+- **`min`/`max` clamp is a snap, not a block** — the stepper still moves, it
+  just lands on the bound.
+- **Now** takes the local wall clock; **Set** fills `00:00` if the picker is
+  empty and closes the popover.
+- The trigger is bi-clock icon + formatted text + a clear ✕ that appears on
+  hover/focus (suppressed by `required`/`disabled`/`readOnly`). Clicking it
+  on an empty picker is a no-op.
+
+## Deviations from source (deliberate)
+
+1. **A zone change emits.** web-mojo updated its hidden input but never fired
+   `change` on a zone pick (`_syncOutputs()` called with no `oldStored`).
+   `onChange` is the only channel here — staying silent would strand the
+   owner's value.
+2. **`Now` and the AM/PM-on-empty seed are clamped** like every other commit
+   path. The source skipped `_clampToBounds` on both, so `Now` outside
+   business hours produced an out-of-bounds value.
+3. **An already-offset zone passes through** `'iso'` serialization
+   (`'14:30-07:00'` re-saves as `'14:30-07:00'`). `ianaOffset('-07:00')`
+   returns `null`, so the source silently dropped the offset on re-save.
+4. **The clear ✕ is a sibling of the trigger**, not nested inside it (the
+   source produced a `<button>` inside a `<button>`). The wrapper carries the
+   hover reveal, so the pointer sitting on the ✕ keeps it visible.
+5. `disabled`/`readOnly` are enforced at the commit boundary, so a locked
+   `inline` panel is inert (the source only guarded the popover, which a
+   locked picker could never open anyway).
+6. The dead `autoApply` option (destructured, never read in source) is not
+   carried. There is no `hasError()` stub either — pass `invalid` instead.
+
+## State ownership (read this before wiring a form)
+
+The picker holds its **own committed state**, seeded from `value` and
+re-seeded whenever the `value` prop changes to something that is not an echo
+of its own last emit — the same shape [`Calendar`](calendar.md) uses. Write
+`event.value` straight back into `value` and the two stay in lockstep; omit
+`value` entirely and it behaves as an uncontrolled picker.
+
+Why not derive purely from props: `'iso'` output carries only the **offset**,
+so re-parsing our own echo would silently degrade
+`'America/Los_Angeles'` → `'-07:00'`. The zone therefore lives in component
+state, and the echo guard is what protects it. Corollary: **a rejected write
+does not revert the panel** — if you need to refuse a value, write the value
+you *do* want (a second prop change re-seeds).
+
+One more source-parity quirk: enabling `timezone` seeds the browser's local
+zone (`Intl.DateTimeFormat().resolvedOptions().timeZone`, `'UTC'` on failure)
+**without emitting**. The owner learns the zone on the first real commit.
+
+## Styling
+
+`apps/portal/src/theme/timepicker.css` — `mojo-time-*` anatomy only
+(`trigger` / `trigger-text` / `trigger-clear` / `popover-inner` /
+`picker-inline` / `stepper*` / `ampm*` / `tz-host` / `foot`), tokens only,
+both themes. The trigger wears the house `.input` look so it lines up in a
+form grid; the popover shell (`.mojo-popover`) supplies background, border
+and shadow, and `.mojo-time-popover-inner` brings the padding
+(`.has-tz` widens it to 300px for IANA labels).
+
+## Pitfalls
+
+- Don't read the column inputs to get the value — they may hold an
+  uncommitted draft. `onChange`/`value` is the only value channel.
+- `'object'` output is `null` when empty, `''` for every other
+  `outputFormat`. Check for both if you switch formats at runtime.
+- `min`/`max` are wall-clock times, not datetimes: a range that crosses
+  midnight (`22:00`–`02:00`) is not expressible — `compareTime` is linear.
+- `ianaOffset` is evaluated at **serialization time against `new Date()`**,
+  so a DST-straddling value serializes with today's offset. Store the IANA
+  name (`'iana'` / `'object'`) when the date matters.
+- django-mojo datetimes are epoch **seconds** — that is a DateTimePicker
+  concern; this component only speaks wall-clock time strings.

package/docs/timezone-select.md

@@ -0,0 +1,147 @@
+# TimezoneSelect — the IANA zone picker
+
+```ts
+import {
+    TimezoneSelect, localTimezone, resolveTimezone, FALLBACK_TIMEZONES,
+    type TimezoneChangeEvent, type TimezoneSelectProps,
+} from 'portal-mojo/ui';
+```
+
+A searchable timezone field: the house [`ComboBox`](combobox.md) with
+`allowCustom: false`, options built from the engine's IANA zone list, each
+label annotated with the zone's **current** UTC offset. Ported from
+web-mojo `src/core/forms/inputs/TimezoneSelect.js`. Used standalone and
+embedded by the time pickers (#1269 TimePicker, DateTimePicker).
+
+## API
+
+```ts
+<TimezoneSelect
+    value={zone}                       // committed IANA string | null
+    onChange={({value, oldValue}) => …} // COMMIT only, real changes only
+    timezones={['UTC', 'Europe/London']} // fixed list overrides the engine
+    defaultToLocal                     // default true — empty displays the local zone
+    name="timezone"                    // renders a hidden input (native form posts)
+    placeholder disabled required maxSuggestions id className
+/>
+
+interface TimezoneChangeEvent { value: string; oldValue: string | null }
+
+localTimezone(): string                                  // 'UTC' when the engine can't say
+resolveTimezone(value, { timezones?, defaultToLocal? })  // → the EFFECTIVE zone (getFormValue)
+FALLBACK_TIMEZONES: readonly string[]                    // the curated 48
+```
+
+`maxSuggestions` defaults to the **whole list** (source parity — web-mojo's
+combobox scrolled every zone and never capped); pass a number to trim.
+
+## The zone list
+
+1. `timezones` prop, in the order given, when it is a non-empty array.
+2. else `Intl.supportedValuesOf('timeZone')` — ~418 zones, resolved once per
+   session and cached. `UTC` is prepended when absent: V8 omits it, and a
+   django-mojo portal whose picker cannot choose UTC is broken (a deliberate
+   one-line deviation from source; the curated list leads with UTC too).
+3. else `FALLBACK_TIMEZONES` (the curated 48, verbatim from web-mojo) with
+   ONE module-level `console.warn` — once per page load, not per instance.
+
+**The committed zone is always in the list**, prepended when the resolved
+list lacks it. This is not a nicety — V8 reports ICU-canonical ids
+(`Asia/Calcutta`, `Europe/Kiev`, `Asia/Saigon`, `America/Godthab`,
+`Asia/Rangoon`, `America/Buenos_Aires`) while Python/`zoneinfo` — and
+therefore django-mojo — stores the modern IANA primaries (`Asia/Kolkata`,
+`Europe/Kyiv`, …). Without the prepend, a stored `Asia/Kolkata` rendered
+unlabelled and could not be re-selected: the user had to change the zone to
+save the record. Engines accept the aliases as *input*, so those entries get
+a proper offset label.
+
+## Labels: offset annotation
+
+`America/New_York (UTC−05:00)` — `dateFns.ianaOffset` does the
+`formatToParts` / `timeZoneName: 'shortOffset'` work (`GMT`/`UTC` → `+00:00`,
+hours zero-padded, minutes defaulted), and the sign is rewritten to a
+**Unicode minus** (U+2212) for negatives. A zone the engine rejects labels as
+its bare name — never nothing.
+
+**Labels recompute on open.** web-mojo built them once at mount, so a
+long-lived picker kept showing pre-DST offsets. Here every gesture that can
+open the list (focus, pointer-down, ArrowDown on the wrapper) stamps a new
+reference instant, keyed into the label `useMemo`; the stamp coalesces to one
+update per second, because a single open is several DOM events and a second
+is far finer than any DST transition. Full relabel of ~420 zones is ~10ms,
+paid on open only.
+
+## Values: commit-only, and the local default
+
+`onChange` fires on a **commit** — clicking an option, Enter on the
+highlighted one, or blurring onto an exact zone name — and only when the zone
+actually changed. `allowCustom` is `false`, so typed filter text is a draft
+that reverts: it can never become a value. This is the bug that mattered —
+web-mojo's ComboBox emitted per keystroke, so fragments like `"Amer"` reached
+the picker's value and FormView's 300ms autosave saved them.
+
+The field is **fully controlled** (one pipeline, no internal value state).
+The default is a *display* resolution, not a commit:
+
+```
+effective = value || (defaultToLocal ? defaultZone : null)
+defaultZone = localTimezone(), except: a caller-supplied `timezones` list
+              that lacks the local zone falls back to its FIRST entry
+```
+
+- `getFormValue` semantics = `resolveTimezone(value, {timezones, defaultToLocal})`
+  → a plain IANA string, or `null` (never the offset label). The `name` prop's
+  hidden input posts exactly that.
+- An empty `value` therefore *displays* the local zone while the owner's state
+  is still `null`. That is deliberate: emitting a commit on mount would mark a
+  form dirty and trip inline autosave for a zone the user never chose. Seed
+  state with `localTimezone()` when you need state and display identical from
+  the first paint.
+- `oldValue` is the previously **displayed** (effective) zone, so a default
+  that was never committed still reports honestly.
+
+## Embedding (TimePicker / DateTimePicker)
+
+The mount seam is `{ value, onChange, timezones?, disabled?, name?, placeholder? }`
+— exactly what web-mojo's TimePicker/DateTimePicker passed
+(`timezone: true | string[]` collapses to `timezones` at the call site; a
+`timezone` prop of `true` means "show the picker", the array form means "show
+it with this fixed list"). Hosts render the offset-annotated field inline
+under their time strip.
+
+Until the field-type registry (#1278) wires this in, the time-picker port may
+be rendering a plain `<select>` fallback in that slot; swapping it for
+`<TimezoneSelect>` is a drop-in — value in, value out, same IANA string.
+
+## Invariants / fixed web-mojo bugs (do not reintroduce)
+
+- **Commit-only value** — inherited by construction from ComboBox plus
+  `allowCustom: false`; there is no per-keystroke path to `onChange`.
+- **Offsets are recomputed, not frozen at mount** (DST correctness).
+- **One warn, once** — the no-Intl fallback warns at module level, not per
+  instance and never per render.
+- The value is always a plain IANA string; the offset lives only in the
+  label. Never post or store the label.
+
+## Pitfalls
+
+- `Intl.supportedValuesOf('timeZone')` does **not** contain `GMT`, and (in
+  V8) not `UTC` either — hence the prepend. Other aliases (`US/Eastern`,
+  `Etc/GMT+5`) are not browsable either: they work as a *value* (prepended,
+  labelled) but a user cannot discover them. Pass `timezones` if a deployment
+  needs them listed.
+- A zone the engine cannot resolve **at all** (`ianaOffset` → null, e.g. the
+  fallback list's bogus `America/Honolulu`) warns once per instance/value and
+  is displayed verbatim, unlabelled — house rule 4's signal that stored data
+  is wrong. An alias the engine *accepts* never warns.
+- `FALLBACK_TIMEZONES` is verbatim from source, warts included:
+  `America/Honolulu` is not a real IANA zone (`Pacific/Honolulu` is, and is
+  also in the list). It labels bare instead of throwing. The list is only
+  reachable on engines without `Intl.supportedValuesOf`.
+- An empty `timezones={[]}` means "no override" (source parity), not "no
+  zones".
+- No stylesheet ships: the wrapper `.tz-select` is an unstyled hook and every
+  pixel comes from `apps/portal/src/theme/combobox.css`, which consuming apps
+  must include.
+- The dropdown is ComboBox's locally-positioned list — inside
+  `overflow:hidden` containers it clips (MERGE-WIRE: Popover primitive #1271).

package/docs/worldmap.md

@@ -0,0 +1,302 @@
+# WorldMap — dependency-free geo map
+
+```ts
+import {
+    WorldMap,
+    // country data
+    COUNTRY_CENTROIDS, COUNTRY_OPTIONS, getCountryCentroid, countryName,
+    // binding helpers
+    countrySeriesToMarkers, countryCodeFromSlug, scaleMarkerSize,
+    toneColor, landRings, MAP_TONES,
+    // basemap geometry — lazily loaded; see "The `land` seam"
+    useWorldLand,
+    // projection math
+    equirectangular, fitViewToPoints, clampView, splitAntimeridian,
+    geoArcPath, graticule, isFinitePoint,
+    DEFAULT_BOUNDS, DEFAULT_VIEW, MIN_ZOOM, MAX_ZOOM,
+} from 'portal-mojo/charts';
+```
+
+One map for every "where in the world did this happen" surface: login
+locations (#1291), geofence policy (#1287), the dashboard geography panel
+(#1292). Demos: Develop → Components → Display → **WorldMap** and **WorldMap
+routes**.
+
+## Why this is a REBUILD, not a port
+
+web-mojo drew all of its maps through `src/extensions/map/MapLibreView.js`,
+which injects `https://unpkg.com/maplibre-gl@4.7.1` as a runtime `<script>`
+(maplibre is not in its `package.json` at all) and takes basemap tiles and
+glyphs from `demotiles.maplibre.org` — MapLibre's explicitly-demo server.
+Porting that verbatim would make every admin deployment fetch a third-party
+CDN and a demo tile server at page load, which is unacceptable for the
+IP-restricted / separate-origin admin deployments independently of the
+no-library rule. The rebuild covers exactly the MapLibre surface the
+consumers used and nothing more.
+
+## Invariants
+
+1. **Presentational only.** `WorldMap` fetches NOTHING — no tiles, no CDN, no
+   `fetch`, no `useQuery`. Consumers own their TanStack queries and pass
+   `markers` / `routes` / `status` / `loading`. `verify-worldmap.mjs` asserts
+   the absence of every network affordance in the source.
+2. **Tokens, never hexes.** Every color is a `var(--…)` string resolved by
+   the browser, so a theme flip needs no re-render.
+3. **ReactNode tooltips, never HTML strings.** No `dangerouslySetInnerHTML`.
+   Both web-mojo consumers concatenated popup HTML out of unescaped server
+   values (`entry.region`, `ev.ip_address`, `ev.user.display_name`);
+   `label` + `detail?: ReactNode` + `renderTooltip` replace that.
+4. **Coordinate validity is `Number.isFinite`.** `{lat: 0, lng: 0}` is real
+   data and plots. The source's `if (!lng || !lat) return`
+   (`MapLibreView.js:223`) dropped the equator and the prime meridian.
+5. **Off-bounds points are skipped and COUNTED**, surfaced in the footer as
+   "N points outside the map view". Clamping to the frame edge would lie
+   about where the event happened; dropping them silently is the
+   silent-failure anti-pattern on the do-not-recreate list.
+6. **Unknown values fall back WITH a `console.warn`** — an unknown tone
+   becomes `accent`, an unsupported land geometry is skipped, non-array
+   `markers`/`routes` render the empty state.
+
+## `<WorldMap>`
+
+```tsx
+<WorldMap<CountryTotal>
+    markers={markers}                  // WorldMapMarker<T>[] — full replace
+    routes={routes}                    // WorldMapRoute[]
+    land={null}                        // injectable geometry; see below
+    height={320}
+    bounds={DEFAULT_BOUNDS}
+    view={view} onViewChange={setView} // controlled…
+    defaultView={DEFAULT_VIEW}         // …or uncontrolled
+    fit="none"                         // 'none' | 'markers'
+    interactive                        // wheel zoom + drag pan
+    showGraticule showLegend showTooltip
+    legend={[{ key: 'Failed', label: 'Failed', tone: 'bad' }]}
+    renderTooltip={(m) => <>…</>}
+    onMarkerHover={(m) => …} onMarkerClick={(m) => …} onMarkerDoubleClick={(m) => …}
+    animateRoutes viewTransition={600}
+    loading={query.isPending}
+    status={`${n} logins plotted`}
+    emptyText="No locations to plot"
+/>
+```
+
+| prop | type | default | notes |
+|---|---|---|---|
+| `markers` | `readonly WorldMapMarker<T>[]` | `[]` | Full replace, like `updateMarkers` |
+| `routes` | `readonly WorldMapRoute[]` | `[]` | Origin→destination arcs |
+| `land` | `WorldMapLand \| null` | `null` | Basemap geometry. Feed it `useWorldLand()`; `null` draws the graticule fallback |
+| `height` | `number` | `320` | Width is measured (ResizeObserver) |
+| `bounds` | `GeoBounds` | `{west:-180,east:180,south:-58,north:84}` | The geographic crop |
+| `view` / `defaultView` | `WorldMapView` | `DEFAULT_VIEW` | Controlled vs uncontrolled |
+| `onViewChange` | `(view) => void` | — | Fires for gestures, `fit`, and resets |
+| `fit` | `'none' \| 'markers'` | `'none'` | `'none'` = the source's `autoFitBounds: false` |
+| `interactive` | `boolean` | `true` | Wheel zoom + drag pan; markers stay live either way |
+| `showGraticule` / `showLegend` / `showTooltip` | `boolean` | `true` | |
+| `legend` | `readonly WorldMapLegendItem[]` | derived | Falls back to the markers' `legendKey`s |
+| `renderTooltip` | `(m) => ReactNode` | — | Replaces the whole tooltip body |
+| `onMarkerHover/Click/DoubleClick` | `(m) => void` | — | See the click-deferral note |
+| `animateRoutes` | `boolean` | `true` | `prefers-reduced-motion` still wins |
+| `viewTransition` | `number` | `600` | ms; the `flyTo({duration: 600})` equivalent |
+| `loading` / `status` / `emptyText` / `className` | | | `status` is the source's `setStatus()` |
+
+### `WorldMapMarker<T>`
+
+`{ id?, lat, lng, size?, tone?, intensity?, icon?, label?, value?, detail?,
+legendKey?, data? }`
+
+`data` is the typed payload every handler receives — the reason drill-down
+does not need the `_countryCode` / `_isRegion` underscore fields web-mojo
+smuggled through the marker object. `icon` is a bootstrap-icons class drawn
+inside the dot (it rides an HTML overlay layer; an icon class cannot be put
+into SVG `<text>` without knowing its codepoint).
+
+### `WorldMapRoute`
+
+`{ id?, from, to, intensity?, tone?, label?, legendKey? }`
+
+Paint follows the source ramps verbatim (`MetricsCountryMapView.js:232-260`):
+width `1.75 → 6`, opacity `0.45 → 0.95`, color teal→amber — now
+`toneColor('scale', intensity)`.
+
+### Tones
+
+| tone | token | used for |
+|---|---|---|
+| `ok` | `--ok` | successful logins |
+| `bad` | `--bad` | failed logins |
+| `warn` | `--warn` | suspicious / MFA-required |
+| `info` | `--info` | informational |
+| `accent` | `--accent` | route origin, default |
+| `mute` | `--mute` | neutral / unclassified |
+| `scale` | `color-mix(--ok → --warn)` | the value ramp |
+
+**There is deliberately no login-tone helper here.** One shipped briefly
+(`loginEventTone` / `LOGIN_EVENT_TONES`, ported from
+`LoginLocationMapView.js:31-41`) and was **removed 2026-08-06**: it keyed off a
+login "event type", and django-mojo's `UserLoginEvent` has no such field, so
+every real row fell through to grey — which is exactly why web-mojo's login map
+rendered entirely grey for years. Tone login rows with `loginRiskTone(row)` from
+`portal-mojo/admin` (`admin/security/devices`): danger on `is_new_country`,
+warning on `is_new_region`, otherwise success. `verify-worldmap.mjs` asserts the
+old names stay gone.
+
+## Projection contract
+
+`equirectangular({width, height, bounds, view})` → `{project, invert, scale,
+contains, size, bounds, view}`.
+
+- **Equirectangular (plate carrée)**: `lat`/`lng` map linearly to `y`/`x`, so
+  `invert` is exact — that is what makes a graticule-only map honest.
+- **`zoom` is a fit multiple, not a tile level.** At `zoom: 1` the whole
+  `bounds` box fits the frame; the scale is `min(width/spanLng,
+  height/spanLat)` in BOTH axes, so a mismatched container letterboxes rather
+  than stretching. Non-uniform fitting would turn markers into ellipses.
+  Range: `MIN_ZOOM` 1 … `MAX_ZOOM` 12.
+- **`invert`** exists for zoom-toward-the-cursor and for any consumer that
+  needs "what is under this pixel".
+- **`DEFAULT_BOUNDS`** crops to `south: -58, north: 84` — the framing web-mojo
+  approximated with `center [10, 20], zoom 1.3`. Antarctica (lat −77) is
+  outside it on purpose; widen `bounds` if a consumer needs it.
+- `fitViewToPoints(points, {size, bounds, padding = 50, maxZoom, fallback})`
+  replaces `fitBounds()`. Zero points returns `fallback`; ONE point recenters
+  but KEEPS the current zoom (a single-point bbox has zero span).
+- `clampView(view, bounds, size)` clamps zoom and pans so the map can never
+  leave the frame.
+- `splitAntimeridian(from, to)` returns 2 segments when the short path wraps
+  past ±180°, 1 otherwise — without it a Reston→Tokyo arc runs backwards
+  across the entire map.
+- `geoArcPath(projection, from, to, curvature = 0.22)` is a quadratic bezier
+  whose control point is perpendicular to the chord. **Named `geoArcPath`,
+  not `arcPath`,** because `charts/pie-math` already exports `arcPath`.
+
+## `countrySeriesToMarkers` and the two metrics key shapes
+
+```ts
+const markers = countrySeriesToMarkers(response.data, {
+    maxCountries: 12, tone: 'scale', metricLabel: 'events',
+});
+```
+
+Two key shapes exist in the wild and ONE rule covers both — uppercase the
+last `:`-separated segment, accept it only if it is 2 characters AND a known
+country:
+
+| shape | source | example |
+|---|---|---|
+| bare ISO2 | `MetricsCountryMapView.js:107-118` | `US` |
+| namespaced slug | `GeographyPanel.js:232-243` | `incident_events:country:US`, `firewall:blocks:country:US`, `bouncer:blocks:country:US` |
+
+`api_calls` and `ZZ` therefore both return `null`, and rows summing to zero
+are dropped. Results are sorted descending, cut to `maxCountries`, joined to
+`COUNTRY_CENTROIDS`, and sized by `scaleMarkerSize` (default range
+`[18, 42]` = the source's `18 + intensity × 24`; `LoginLocationMapView` used
+`× 26`, i.e. `[18, 44]`).
+
+## The `land` seam — SETTLED 2026-08-06
+
+Ian's call: **embed the outlines, no library.** `WORLD_LAND` in
+`charts/worldmap/world-land.ts` is Natural Earth 1:110m Admin 0 Countries —
+**public domain**, no attribution required — decoded from the `world-atlas`
+TopoJSON build, rounded to 1 decimal and stripped of sub-visible islets.
+173 countries, 10,443 positions, ~143 KB raw / **~40 KB gzipped**.
+
+It is generated **once and checked in**. There is no runtime dependency, no
+CDN fetch and no tile server — which is the whole point: web-mojo pulled
+`maplibre-gl` from unpkg at page load and drew on MapLibre's *demo* tile
+server, so its admin map could not work on an IP-restricted or offline
+deployment. Ours can.
+
+**Reach it through `useWorldLand()` — never a static import.**
+
+```ts
+import { WorldMap, useWorldLand } from 'portal-mojo/charts';
+
+const land = useWorldLand();            // or useWorldLand(hasCoords) to skip the fetch
+<WorldMap land={land} markers={markers} />
+```
+
+`world-land.ts` is deliberately **not re-exported from the charts barrel**, and
+the hook reaches it with a dynamic `import()`. That is what makes Rollup emit it
+as its own chunk. Measured on `apps/portal`: static export put the coordinates
+in the main bundle (1,472 kB / 426 kB gzipped); behind the hook the main bundle
+is 1,328 kB / 386 kB and `world-land-*.js` is a separate 144 kB / **39.8 kB
+gzipped** chunk fetched only when a map first renders. `verify-admin-devices`
+asserts the barrel never re-exports it.
+
+The hook caches at module scope, so later maps in a session get the geometry on
+first render and concurrent mounts share one request. It returns `null` until
+resolved — not a special case, since a null `land` is just the graticule
+fallback, so the map is fully readable before the coastlines arrive. A failed
+chunk fetch warns and leaves the fallback rather than blanking the map.
+
+Surfaces using it today: `LoginLocationMap` and the GeoIP dossier's mini-map.
+
+Rendering correctly **without** it remains a hard requirement — pass
+`land={null}` (the default) and the ocean + graticule fallback carries the
+markers, legend, tooltips and status line on its own. Both showcase demos keep
+a toggle so the no-geometry case stays visible.
+
+Regenerating (only if you want different precision or a different source):
+decode the TopoJSON, de-quantize with its `transform`, round, and drop outer
+rings under 0.5 square degrees. The file header records the exact parameters.
+Do not hand-edit it.
+
+Precision note: 1:110m is a *coarse* source by design. At the map's rendered
+scale one pixel is roughly 0.36° of longitude, so 0.1° rounding is sub-pixel;
+at the maximum 12× zoom the coarseness of the source itself shows before the
+rounding does. If you ever need street-level fidelity, that is a different
+dataset and a different conversation — not a rounding tweak.
+
+`land` accepts a `FeatureCollection`, a bare feature array, or a single
+`Polygon`/`MultiPolygon`. Unsupported geometry types are skipped with a
+`console.warn` and the rest still draw (`landRings` is the exported
+normalizer). A ring whose consecutive vertices jump more than 180° of
+longitude BREAKS into a new subpath instead of smearing a band across the
+map.
+
+## Pitfalls
+
+- **Double-click is drill-down, so canvas double-click does NOT zoom.** With
+  both `onMarkerClick` and `onMarkerDoubleClick` wired, a single click is
+  deferred `250ms` and cancelled by a double-click (in MapLibre the marker
+  handler `stopPropagation`'d against `doubleClickZoom`). Double-clicking the
+  canvas resets to `defaultView`.
+- **Off-bounds markers do not render.** Check the footer count before
+  concluding the data is missing; widen `bounds` to bring them in.
+- **The centroid keys were deduped.** The source table has 249 rows but 244
+  distinct ISO2 keys (`BQ`×3, `ES`×2, `TF`×3), and JS last-write-wins made
+  **`ES` resolve to "Canarias" rather than Spain** — so web-mojo's geofence
+  picker listed a Spanish island group where Spain belonged, and Spanish
+  metrics plotted in the Canaries. Duplicate keys are also a hard TS error
+  (TS1117). Here the primary territory keeps the key (`BQ`→Bonaire,
+  `ES`→Spain, `TF`→French Southern Territories) and the 5 dropped rows are
+  recorded with their coordinates in the module header.
+- **`LoginLocationMapView`'s docstring says `size=500`; the code sends
+  `size: 1000`** (`:208`). Consumers should follow the code.
+- **`map.resize()` has no equivalent** — `ResizeObserver` covers the
+  tab-activation and drawer-opening cases that forced it. A container at
+  width 0 defers rendering until the first non-zero measurement.
+- **`pitch` / `bearing` are dropped.** Cosmetic 3D tilt with no consumer
+  semantics; a fake-perspective SVG map would be dishonest.
+- **Route animation is an ADDITION.** web-mojo's routes were static
+  LineStrings; only color/width/opacity interpolated on intensity. It is
+  therefore opt-out (`animateRoutes={false}`) and lives inside
+  `@media (prefers-reduced-motion: no-preference)`.
+- **`fit="markers"` pushes through the same channel as a gesture** — it sets
+  internal state when uncontrolled and calls `onViewChange` when controlled.
+  A controlled consumer must write that value back for the fit to stick.
+
+## Verification
+
+```bash
+node scripts/verify-worldmap.mjs   # or: npm run verify:worldmap
+```
+
+Headless assertions over the projection (corner mapping, `project`∘`invert`
+round-trip, clamping, fitting, antimeridian splitting), the centroid table
+(244 unique keys, coordinate ranges, `ES` = Spain), the binding helpers
+(slug parsing, sizing, sorting/top-N/drops), tone fallbacks and their warns,
+the land normalizer, and the source invariants above (no network, no map
+library, no HTML-string tooltips, tokens-only CSS, and the two theme copies
+staying byte-identical).