@mailwoman/react 9.4.0 → 10.1.0

package/lib/map/place-render.ts

@@ -2,93 +2,78 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `computeMapPlaceRenderSpec` — the PURE core that replaces the docs demo's ~100-line imperative
- *   marker/bbox/camera redraw effect (`_app.tsx:601-705`). It takes an ALREADY-RESOLVED place (the async
- *   polygon-DB fetch is a host/runtime concern — a later phase — so a crisp polygon arrives pre-fetched
- *   as `place.geometry`) and returns a declarative render spec: the marker position(s), the outline
- *   geometry to draw, and the camera target. No map instance, no DOM, no `react-map-gl` — so it is
- *   node-testable (see `place-render.node.test.ts`). The declarative components in this folder render
- *   the spec; a controlled-viewport consumer applies the camera.
- *
- *   The decision cascade is a faithful, side-effect-free transcription of the imperative effect:
- *     1. street tier (situs / interp)  → exact-radius circle, fly to a tight zoom
- *     2. crisp admin polygon (pre-fetched) → draw the polygon, fit its bounds
- *     3. anchor-centroid postcode (no bbox) → ~3 km "around here" circle, fly to zoom 11
- *     4. bbox with real extent            → bbox-sized approximate circle, fit the bbox
- *     5. bare point                       → no outline, fly to zoom 12
  */
 
 import type { ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result"
+import type { LatLonBounds } from "@mailwoman/spatial"
 
 import { approxCircleGeometry, bboxToBounds, geomBounds, radiusCircleGeometry } from "#map/geometry"
-import type { BoundsTuple, PlaceBBox, PlaceGeometry } from "#map/geometry"
+import type { BoundsTuple, PlaceGeometry } from "#map/geometry"
 
 /**
- * `[longitude, latitude]`.
+ * A coordinate pair as `[longitude, latitude]`.
  */
 export type LngLat = [number, number]
 
 /**
- * The street-level resolution tier (#377): `address_point` = exact building; `interpolated` = TIGER estimate.
+ * How a street-level result was located: `address_point` is an exact building point
+ * and `interpolated` an estimate from a TIGER address range.
  */
 export type PlaceTier = "address_point" | "interpolated"
 
 /**
- * The resolved-place shape the map render consumes — the pipeline {@link ResolvedPlaceView} plus the map-only extras the
- * demo's `ResolvedHit` carries (bbox, street tier + uncertainty), and an optional PRE-FETCHED crisp polygon. Extending
- * `ResolvedPlaceView` keeps the map render aligned with the shared parse result; the extras are additive.
+ * A resolved place with the extra fields the map uses to draw it.
  */
 export interface ResolvedMapPlace extends ResolvedPlaceView {
 	/**
-	 * The place's bounding box, when the gazetteer carries one (admin places). Absent for anchor-centroid postcodes.
+	 * The place's bounding box.
+	 * Postcodes located by an anchor centroid have none.
 	 */
-	bbox?: PlaceBBox
+	bbox?: LatLonBounds
+
 	/**
-	 * Street-level tier, when this hit came from the situs/interp tier rather than the WOF admin cascade.
+	 * The street-level tier, set only for results from address points or interpolation.
 	 */
 	tier?: PlaceTier
+
 	/**
-	 * Honest uncertainty radius in meters for a street-level tier (10 m situs floor; calibrated interp).
+	 * The uncertainty radius in meters of a street-level result, drawn as a circle when `tier` is set.
 	 */
 	uncertaintyM?: number
+
 	/**
-	 * The crisp admin polygon, when the host has ALREADY fetched it from the sibling polygon DB. Its presence drives the
-	 * polygon path; the async fetch itself stays out of this pure function (a runtime concern in a later phase).
+	 * The admin polygon, if the host has already fetched it.
+	 * When present the outline and camera follow it.
 	 */
 	geometry?: PlaceGeometry
 }
 
 /**
- * The camera target the render computes. `center` (fly to a point at a zoom) HAS a declarative equivalent — a consumer
- * can feed it to a controlled `viewState` (see {@link cameraToViewState}). `bounds` (fit a box with pixel padding) does
- * NOT — `fitBounds` needs the map's pixel dimensions, so it is applied imperatively by `<ResultCamera>`.
+ * Only a `center` target can be applied declaratively through {@link cameraToViewState};
+ * fitting bounds needs the map's pixel size, so `<ResultCamera>` applies it imperatively.
  */
 export type MapCameraTarget =
 	| { kind: "center"; center: LngLat; zoom: number }
 	| { kind: "bounds"; bounds: BoundsTuple; padding: number }
 
 /**
- * The declarative render spec for one resolved place — the pure output of {@link computeMapPlaceRenderSpec}.
+ * The markers, outline and camera target for one resolved place, as returned
+ * by {@link computeMapPlaceRenderSpec}.
  */
 export interface MapPlaceRenderSpec {
 	/**
-	 * Marker position(s) as `[lon, lat]`. Single-element today; an array leaves room for multi-marker later.
+	 * The marker positions as `[lon, lat]`; there is always exactly one marker.
 	 */
 	markers: LngLat[]
+
 	/**
-	 * The outline geometry (polygon / circle) to draw, or `null` when the place renders as a bare point.
+	 * The polygon or circle outline to draw, or `null` when the place renders as a bare point.
 	 */
 	outline: PlaceGeometry | null
-	/**
-	 * The camera target — animate or fit to this.
-	 */
+
 	camera: MapCameraTarget
 }
 
-/**
- * Zoom levels the imperative effect flew to, kept named so the cascade reads as intent, not magic numbers.
- */
 const ZOOM = {
 	addressPoint: 17,
 	interpolated: 15,
@@ -96,26 +81,17 @@ const ZOOM = {
 	point: 12,
 } as const
 
-/**
- * Padding (px) `fitBounds` insets a fitted box by, matching the ported effect.
- */
 const FIT_PADDING = 40
 
-/**
- * The minimum lat/lon span (degrees) a bbox must exceed to be treated as a real extent rather than a point.
- */
 const MIN_EXTENT_DEG = 0.001
 
 /**
- * Map a resolved place to its declarative render spec. Pure — same input, same output, no side effects. The `place`
- * arrives fully resolved (crisp polygon pre-fetched into `place.geometry` when available), so this is the honest
- * inverse of the old redraw effect with the imperative map mutation and the async DB load removed.
+ * Computes the markers, outline and camera target for a resolved place without loading data,
+ * so the caller must put any fetched polygon in `place.geometry` first.
  */
 export function computeMapPlaceRenderSpec(place: ResolvedMapPlace): MapPlaceRenderSpec {
 	const markers: LngLat[] = [[place.lon, place.lat]]
 
-	// 1. Street tier (#377): the honest uncertainty circle (exact meter radius) + a tight zoom. Takes precedence over
-	//    the admin polygon/bbox paths — a precise point gets no admin boundary.
 	if (place.tier && place.uncertaintyM != null) {
 		return {
 			markers,
@@ -128,7 +104,6 @@ export function computeMapPlaceRenderSpec(place: ResolvedMapPlace): MapPlaceRend
 		}
 	}
 
-	// 2. Crisp admin polygon (host pre-fetched it from the polygon DB) — draw the real boundary and fit it.
 	if (place.geometry) {
 		return {
 			markers,
@@ -137,8 +112,6 @@ export function computeMapPlaceRenderSpec(place: ResolvedMapPlace): MapPlaceRend
 		}
 	}
 
-	// 3. Anchor-centroid postcode: no bbox, no polygon — a default ~3 km circle says "approximately here" without
-	//    inventing a boundary.
 	if (!place.bbox && place.placetype === "postcode") {
 		return {
 			markers,
@@ -147,8 +120,6 @@ export function computeMapPlaceRenderSpec(place: ResolvedMapPlace): MapPlaceRend
 		}
 	}
 
-	// 4. A bbox with real extent — draw an approximate CIRCLE sized from the bbox (a rectangle would read as a wrong,
-	//    real boundary) and fit the bbox.
 	const bbox = place.bbox
 
 	if (bbox && Math.max(bbox.maxLat - bbox.minLat, bbox.maxLon - bbox.minLon) > MIN_EXTENT_DEG) {
@@ -159,7 +130,6 @@ export function computeMapPlaceRenderSpec(place: ResolvedMapPlace): MapPlaceRend
 		}
 	}
 
-	// 5. A bare point (no tier, no polygon, no meaningful bbox) — just a marker and a mid zoom.
 	return {
 		markers,
 		outline: null,
@@ -168,10 +138,8 @@ export function computeMapPlaceRenderSpec(place: ResolvedMapPlace): MapPlaceRend
 }
 
 /**
- * The DECLARATIVE camera path: reshape a `center` target into a `viewState` patch a controlled `<MapCanvas viewState>`
- * can apply directly (a hard jump, no animation). Returns `null` for a `bounds` target — fitting a box to the viewport
- * needs the map's pixel dimensions, which only the live map has, so that case is applied imperatively by
- * `<ResultCamera>`. Pure + node-testable.
+ * Converts a `center` camera target into a `viewState` patch for a controlled `<MapCanvas>`,
+ * returning `null` for a `bounds` target that `<ResultCamera>` must fit imperatively.
  */
 export function cameraToViewState(
 	camera: MapCameraTarget

package/lib/map/types.ts

@@ -3,21 +3,12 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Types for the geocoder map surface. Mirrors the pipeline boundary: the package owns the UI state
- *   machine + the declarative map, while the host injects a {@link GeocoderRuntime} that owns ONNX / httpvfs
- *   / R2 and the composed map style. {@link GeocoderRuntime} EXTENDS {@link PipelineRuntime} so the shared
- *   `runParse` / `parseStageLabels` / `loading` contract is reused, and adds the map-specific surface
- *   (style, overlays, initial center, viewport bias, backend/version selection). Phase 4 adds the
- *   `resolveMapPlace` enricher, the {@link GeocoderPanels} injection bag, and the {@link CompareContext}.
- *
- *   The map-spec types are imported type-only from `react-map-gl/maplibre`; nothing here loads maplibre at
- *   runtime, so this module stays node-safe (its concrete-value CONSUMERS — `MapCanvas`, `Geocoder` —
- *   are the ones behind the `@mailwoman/react/map` subpath).
+ *   Types for the geocoder map surface. Its `react-map-gl/maplibre` imports are type-only, so the module stays node-safe.
  */
 
 import type { ParseResult, ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result"
 import type { ReactNode } from "react"
-import type { LayerSpecification, SourceSpecification } from "react-map-gl/maplibre"
+import type { LayerSpecification, MapInstance, SourceSpecification } from "react-map-gl/maplibre"
 
 import type { LngLat, ResolvedMapPlace } from "#map/place-render"
 import type { PipelineRuntime } from "#pipeline/types"
@@ -25,9 +16,10 @@ import type { PipelineRuntime } from "#pipeline/types"
 import type { MapCanvasStyle } from "./MapCanvas.tsx"
 
 /**
- * `[longitude, latitude]`.
+ * An alias for {@link LngLat}.
  *
- * @deprecated Alias kept for existing imports — {@link LngLat} (from `@mailwoman/react/map`) is the canonical name.
+ * @deprecated Alias kept for existing imports — {@link LngLat}
+ * (from `@mailwoman/react/map`) is the canonical name.
  */
 export type LngLatTuple = LngLat
 
@@ -35,40 +27,24 @@ export type LngLatTuple = LngLat
  * A viewport bias handed to `runParse` — the map's current center (and optionally zoom) as a soft prior.
  */
 export interface MapBias {
-	/**
-	 * Map center as `[lon, lat]`, typically read from `map.getCenter()`.
-	 */
 	center: LngLat
-	/**
-	 * Current zoom, if the host wants distance-aware biasing.
-	 */
 	zoom?: number
 }
 
 /**
- * A host-supplied overlay: one map `<Source>` plus one or more `<Layer>`s laid over the basemap (coverage "fog of war",
- * race-dots, …). The host composes the specs; the package renders them declaratively in a later phase.
+ * A host-supplied overlay: one map `<Source>` plus one or more `<Layer>`s laid over the basemap.
  */
 export interface OverlaySpec {
 	/**
 	 * Stable id — used as the `<Source>` id and the layer-id prefix.
 	 */
 	id: string
-	/**
-	 * The map source spec (vector/geojson/raster).
-	 */
 	source: SourceSpecification
-	/**
-	 * The layers drawn from that source.
-	 */
 	layers: LayerSpecification[]
 	/**
-	 * Whether the overlay is visible initially. @default true
+	 * @default true
 	 */
 	visible?: boolean
-	/**
-	 * Human label for a layer-toggle control.
-	 */
 	label?: string
 }
 
@@ -95,11 +71,12 @@ export interface Suggestion {
  */
 export interface VersionOption {
 	/**
-	 * The version tag (e.g. a git tag or model-card version).
+	 * The version tag, such as a git tag or model-card version.
 	 */
 	version: string
 	/**
-	 * Display label; falls back to `version`.
+	 * Display label.
+	 * The picker falls back to `version`.
 	 */
 	label?: string
 }
@@ -110,35 +87,27 @@ export interface VersionOption {
 export type InferenceBackend = "webgpu" | "wasm"
 
 /**
- * The injected geocoder runtime. Extends {@link PipelineRuntime} (shared `runParse` / `parseStageLabels` / `loading` /
- * `ready`) with the map + version/backend surface the geocoder needs. The host composes `mapStyle` (via cartographer's
- * `StyleSpecificationComposer` + the tile-worker TileJSON), supplies the overlay specs, the initial center (from
- * geolocation), the FST autocomplete, and the calibrator — nothing in the package imports `@mailwoman/cartographer`,
- * `@mailwoman/neural`'s web loader, httpvfs, or Docusaurus.
+ * The injected geocoder runtime extends {@link PipelineRuntime} with the map.
+ * It also supplies version and backend controls.
+ *
+ * The package imports no `@mailwoman/cartographer`, `@mailwoman/neural` web loader, httpvfs, or Docusaurus.
  */
 export interface GeocoderRuntime extends PipelineRuntime {
-	// ── Map ────────────────────────────────────────────────────────────────
 	/**
 	 * The composed basemap style (URL or `StyleSpecification`).
 	 */
 	mapStyle: MapCanvasStyle
-	/**
-	 * Host-supplied overlays (coverage, race-dots, …).
-	 */
 	overlays?: OverlaySpec[]
 	/**
-	 * Initial map center as `[lon, lat]` (the host's browser-geolocation result).
+	 * Initial map center as `[lon, lat]`.
 	 */
 	initialCenter: LngLat
-	/**
-	 * Initial zoom for the first camera.
-	 */
 	initialZoom?: number
 
-	// ── Parse extras layered over PipelineRuntime.runParse ──────────────────
 	/**
-	 * A bias-aware parse. The geocoder feeds the current viewport center as a soft prior; when absent the host falls back
-	 * to the base {@link PipelineRuntime.runParse}. Kept separate so the shared `runParse` contract is unchanged.
+	 * A bias-aware parse that feeds the current viewport center as a soft prior.
+	 *
+	 * Absent, the host falls back to {@link PipelineRuntime.runParse}.
 	 */
 	runParseWithBias?: (
 		input: string,
@@ -154,11 +123,17 @@ export interface GeocoderRuntime extends PipelineRuntime {
 	 */
 	calibrator?: (raw: number) => number | null
 	/**
-	 * Enrich the selected candidate into the richer {@link ResolvedMapPlace} the declarative map render consumes (bbox,
-	 * street tier + uncertainty, a pre-fetched crisp polygon) — the fields that live on the host's `ResolvedHit` but not
-	 * on the shared {@link ResolvedPlaceView}. The host owns this because those extras (and the async polygon fetch in the
-	 * real runtime) are host/gazetteer concerns; the package keeps {@link ParseResult} unpolluted. Absent → the candidate
-	 * renders as a bare point (marker + a mid-zoom fly-to). Returning `null` also renders nothing.
+	 * Enrich the selected candidate into the richer {@link ResolvedMapPlace} the declarative
+	 * map render consumes (bbox, street tier + uncertainty, a pre-fetched crisp polygon) —
+	 * the fields that live on the host's `ResolvedHit` but not on the shared {@link ResolvedPlaceView}.
+	 *
+	 * The host owns this because those extras (and the async polygon fetch in the real runtime)
+	 * are host/gazetteer concerns.
+	 * The package keeps {@link ParseResult} unpolluted.
+	 *
+	 * Absent → the candidate renders as a bare point (marker + a mid-zoom fly-to).
+	 *
+	 * A `null` result also renders no overlay.
 	 */
 	resolveMapPlace?: (candidate: ResolvedPlaceView, result: ParseResult) => ResolvedMapPlace | null
 
@@ -167,9 +142,6 @@ export interface GeocoderRuntime extends PipelineRuntime {
 	 * The selectable model bundles the version picker offers.
 	 */
 	availableVersions?: VersionOption[]
-	/**
-	 * The currently-selected model version.
-	 */
 	selectedVersion?: string
 	/**
 	 * Switch the active model bundle (re-loads weights/tokenizer/gazetteer).
@@ -180,27 +152,24 @@ export interface GeocoderRuntime extends PipelineRuntime {
 	 */
 	activeBackend?: string
 	/**
-	 * Whether the CPU/WASM backend is currently forced (the controlled value for the backend toggle).
+	 * Whether the CPU/wasm backend is currently forced (the controlled value for the backend toggle).
 	 */
 	forceWASM?: boolean
 	/**
-	 * Force the WASM backend (opt out of WebGPU), for the backend toggle.
+	 * Force the wasm backend (opt out of WebGPU), for the backend toggle.
 	 */
 	setForceWASM?: (forceWASM: boolean) => void
 }
 
 /**
- * The compare-mode state a {@link GeocoderPanels.compare} render-prop receives (the second parse itself stays
- * host-side).
+ * The compare-mode state a {@link GeocoderPanels.compare} render-prop receives.
+ * the second parse itself stays host-side.
  */
 export interface CompareContext {
 	/**
 	 * The current primary parse result, or `null` before the first submit.
 	 */
 	result: ParseResult | null
-	/**
-	 * Whether the compare toggle is on.
-	 */
 	compareMode: boolean
 	/**
 	 * The version selected to compare against, or `null` when none is chosen.
@@ -209,39 +178,29 @@ export interface CompareContext {
 }
 
 /**
- * The state a {@link GeocoderPanels.result} render-prop receives, so a host can render its OWN result block (a
- * `<ResultPanel>` with its span-highlight / timing / hierarchy / precision detail) in place of the package's default
- * {@link ResultPanel}. Everything the default panel needs is passed through; the candidate-selection state stays owned
- * by the package (`useGeocode`).
+ * The state a {@link GeocoderPanels.result} render-prop receives, so a host can render its own result block.
+ *
+ * The candidate-selection state stays owned by the package (`useGeocode`).
  */
 export interface ResultContext {
-	/**
-	 * The current parse+resolve result.
-	 */
 	result: ParseResult
 	/**
 	 * The selected candidate (falls back to the first), enriched for the resolved-place detail.
 	 */
 	selectedCandidate: ResolvedPlaceView | null
-	/**
-	 * The selected candidate index, for the picker's active state.
-	 */
 	selectedCandidateIndex: number
-	/**
-	 * Fired when a candidate in the picker is chosen.
-	 */
 	onSelectCandidate: (index: number) => void
 }
 
 /**
- * Host-injected panels for {@link Geocoder}, the map analogue of `PipelinePanels`. Each is an already-rendered
- * `ReactNode` (or a thunk of the parse result / compare state) so the package needs neither the heavy host visualizers
- * (ModelVisualizer, VersionCompare, About, PermalinkButton) nor their data types. Every field is optional — the
- * fake-runtime Storybook stories pass none and still render the whole geocoder.
+ * Host-injected panels for {@link Geocoder}, the map analogue of `PipelinePanels`.
+ *
+ * Each is an already-rendered `ReactNode` or a thunk.
+ * Every field is optional.
  */
 export interface GeocoderPanels {
 	/**
-	 * Rendered at the top of the control panel (e.g. the host's "About this geocoder").
+	 * Rendered at the top of the control panel, such as the host's "About this geocoder".
 	 */
 	header?: ReactNode
 	/**
@@ -249,13 +208,13 @@ export interface GeocoderPanels {
 	 */
 	releaseInfo?: ReactNode
 	/**
-	 * Rendered at the bottom of the control panel (e.g. a guided tour).
+	 * Rendered at the bottom of the control panel, such as a guided tour.
 	 */
 	footer?: ReactNode
 	/**
-	 * A device-location / proximity-bias control, rendered between the query form and the autocomplete list (the "📍 Use
-	 * my location" row). Host-owned so the geolocation permission + the bias it feeds into the host's
-	 * {@link GeocoderRuntime.runParseWithBias} stay a host concern.
+	 * A device-location / proximity-bias control, rendered between the query form and the autocomplete list.
+	 *
+	 * Host-owned because the geolocation permission feeds {@link GeocoderRuntime.runParseWithBias}.
 	 */
 	bias?: ReactNode
 	/**
@@ -263,20 +222,25 @@ export interface GeocoderPanels {
 	 */
 	extras?: (result: ParseResult) => ReactNode
 	/**
-	 * Rendered just above the result block (present or empty). The opt-in display toggles live here — calibrated
-	 * confidence + dev-mode — because the host owns both the toggle state AND the {@link result} / {@link debugDrawer}
-	 * renderers those toggles drive.
+	 * Rendered just above the result block for content that reads on this answer. a
+	 * control that reads on the model belongs in {@link developerExtras}.
 	 */
 	aboveResult?: (context: { result: ParseResult | null }) => ReactNode
 	/**
-	 * Replace the package's default {@link ResultPanel} entirely. When provided, the host renders its own result block
-	 * (span highlight, timing, hierarchy, precision detail, calibrated confidences) from the {@link ResultContext}. Absent
-	 * → the built-in panel renders.
+	 * Host controls appended to the Developer sheet.
+	 * The host owns their state and renderers.
+	 */
+	developerExtras?: ReactNode
+	/**
+	 * Replaces the package's default {@link ResultPanel}.
+	 *
+	 * When absent, the built-in panel renders.
+	 * When provided, the host renders from {@link ResultContext}.
 	 */
 	result?: (context: ResultContext) => ReactNode
 	/**
-	 * Rendered in place of the resolved-place panel when nothing resolved (host's FailureDiagnostic). Ignored when
-	 * {@link result} is set.
+	 * Rendered in place of the resolved-place panel when no place resolved. ignored
+	 * when {@link result} is set.
 	 */
 	failure?: (result: ParseResult) => ReactNode
 	/**
@@ -284,15 +248,19 @@ export interface GeocoderPanels {
 	 */
 	compare?: (context: CompareContext) => ReactNode
 	/**
-	 * The model-visualizer / debug drawer, mounted beside the map (host's ModelVisualizer). A render-prop so the host can
-	 * trace the CURRENT result (its input) — the package passes the live parse result; the host decides on its own
-	 * dev-mode state and returns `null` when the drawer is closed.
+	 * The model-visualizer / debug drawer mounted beside the map, as a render-prop
+	 * receiving the live result and returning `null` when closed.
 	 */
 	debugDrawer?: (context: { result: ParseResult | null }) => ReactNode
 	/**
 	 * Extra map controls mounted as `<MapCanvas>` children (host's DebugControl / LayerToggle via `useControl`).
 	 */
 	mapControls?: ReactNode
+	/**
+	 * A layer control rendered in the chrome's top column, as a render-prop over the
+	 * live map handle (null until the map instantiates).
+	 */
+	layers?: (context: { map: MapInstance | null }) => ReactNode
 	/**
 	 * A permalink control for the current address (host's PermalinkButton).
 	 */

package/lib/map/useCompareState.ts

@@ -4,9 +4,9 @@
  * @author Teffen Ellis, et al.
  *
  *   `useCompareState` — the small headless state machine behind the demo's compare toggle
- *   (`_app.tsx:142-143, 1238-1305`): whether compare mode is on, and which version to compare against.
- *   Turning compare off clears the chosen version; selecting a compare version equal to the primary is
- *   rejected (the picker filters it out, this guards the programmatic path). The SECOND parse itself is a
+ *   (`_app.tsx:142-143, 1238-1305`): whether compare mode is on and which version to compare against.
+ *   The off state clears the chosen version. A selected compare version equal to the primary is
+ *   rejected (the picker filters it out, this guards the programmatic path). The second parse itself is a
  *   host concern surfaced through `panels.compare` — this hook owns only the toggle + selection.
  */
 
@@ -22,7 +22,8 @@ export interface UseCompareState {
 	 */
 	compareVersion: string | null
 	/**
-	 * Flip compare mode; turning it off clears the chosen version.
+	 * Flip compare mode.
+	 * The off state clears the chosen version.
 	 */
 	setCompareMode: (compareMode: boolean) => void
 	/**

package/lib/map/useGeocode.ts

@@ -3,12 +3,12 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `useGeocode` — the parse+resolve state machine for the geocoder map. It REUSES the pipeline's
+ *   `useGeocode` — the parse+resolve state machine for the geocoder map. It reuses the pipeline's
  *   `useParsePipeline` (text / busy / stage / result / candidate selection) and layers on the two map-only
  *   concerns the geocoder adds over the base explorer:
  *
  *     1. Viewport bias — when the runtime exposes `runParseWithBias`, the current map center (read through
- *        an injected `getBias`, itself reading the `MapRef`) rides along as a soft proximity prior. The
+ *        an injected `getBias`, itself reading the `MapRef`) supplies a soft proximity prior. The
  *        bias is injected by deriving a `runParse` that binds it, so `useParsePipeline` is reused verbatim.
  *     2. The map render place — the selected candidate, enriched by the host's `resolveMapPlace` into the
  *        richer {@link ResolvedMapPlace} the declarative overlays consume (bbox / tier / polygon). Absent
@@ -35,7 +35,9 @@ export interface UseGeocodeOptions {
 	 */
 	defaultText: string
 	/**
-	 * Read the current viewport bias (the map center) at submit time. Absent → no bias.
+	 * Read the current viewport bias (the map center) at submit time.
+	 *
+	 * Absent → no bias.
 	 */
 	getBias?: () => MapBias | null
 }
@@ -48,8 +50,8 @@ export interface UseGeocode extends UseParsePipeline {
 }
 
 export function useGeocode({ runtime, defaultText, getBias }: UseGeocodeOptions): UseGeocode {
-	// Bind the viewport bias into a derived `runParse` so `useParsePipeline` is reused unchanged. When the runtime has no
-	// bias-aware parse, pass it straight through.
+	// Bind the viewport bias into a derived `runParse` so `useParsePipeline` is reused unchanged.
+	// When the runtime has no bias-aware parse, pass it straight through.
 	const geoRuntime = useMemo<PipelineRuntime>(() => {
 		const withBias = runtime.runParseWithBias
 

package/lib/map/useMapBearing.ts

@@ -0,0 +1,56 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The map's rotation as React state, read through `useSyncExternalStore` and subscribed to `move` as well as `rotate`, since a `flyTo` or `easeTo` carrying a direction fires no rotate event.
+ */
+
+import { useCallback, useSyncExternalStore } from "react"
+import type { MapInstance } from "react-map-gl/maplibre"
+
+/**
+ * The map's bearing and a callback that returns the map to north.
+ */
+export interface UseMapBearing {
+	/**
+	 * Degrees off north, as MapLibre reports it.
+	 * Zero while there is no map.
+	 */
+	bearing: number
+	/**
+	 * Rotate the map back to north.
+	 * A no-op while there is no map.
+	 */
+	resetNorth: () => void
+}
+
+/**
+ * Reads the live map bearing and exposes `resetNorth`.
+ */
+export function useMapBearing(map: MapInstance | null): UseMapBearing {
+	const subscribe = useCallback(
+		(onChange: () => void) => {
+			if (!map) return () => undefined
+
+			map.on("rotate", onChange)
+			map.on("move", onChange)
+
+			return () => {
+				map.off("rotate", onChange)
+				map.off("move", onChange)
+			}
+		},
+		[map]
+	)
+
+	// The server snapshot is the same reading: the server renders no map.
+	// and north is what a compass shows with no bearing to report.
+	const readBearing = useCallback(() => map?.getBearing() ?? 0, [map])
+
+	const bearing = useSyncExternalStore(subscribe, readBearing, () => 0)
+
+	const resetNorth = useCallback(() => map?.easeTo({ bearing: 0, pitch: 0 }), [map])
+
+	return { bearing, resetNorth }
+}