@mailwoman/react 7.4.0 → 7.6.0

package/map/PlaceAutocomplete.tsx

@@ -0,0 +1,69 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<PlaceAutocomplete>` — the "Did you mean" suggestion listbox from the demo (`_app.tsx:1394-1418`), as
+ *   a dumb presentational unit. It renders the current suggestions with the keyboard-highlighted active
+ *   descendant; the state + keyboard nav live in {@link usePlaceAutocomplete}. Renders `null` when there
+ *   is nothing to suggest, so the row only appears when useful. Wire the ids from the hook so the input's
+ *   `aria-controls` / `aria-activedescendant` match this listbox.
+ *
+ *   NODE-SAFE: pure React, no maplibre.
+ */
+
+import type { ReactNode } from "react"
+
+import { cx } from "../common/cx.ts"
+import type { Suggestion } from "./types.ts"
+
+export interface PlaceAutocompleteProps {
+	/** The suggestions to render (from {@link usePlaceAutocomplete}). */
+	suggestions: Suggestion[]
+	/** The keyboard-highlighted index; `-1` for none. */
+	activeIndex: number
+	/** Fired (with the suggestion `value`) when one is clicked. */
+	onPick: (value: string) => void
+	/** Fired with the index a pointer entered, so hover matches keyboard highlight. */
+	onHover?: (index: number) => void
+	/** The listbox element id — pass `listboxId` from the hook (matches the input's `aria-controls`). */
+	listboxId: string
+	/** Build the option element id — pass `optionId` from the hook. */
+	optionId: (index: number) => string
+	/** Leading label. @default "Did you mean:" */
+	caption?: string
+}
+
+/** The suggestion listbox. */
+export function PlaceAutocomplete({
+	suggestions,
+	activeIndex,
+	onPick,
+	onHover,
+	listboxId,
+	optionId,
+	caption = "Did you mean:",
+}: PlaceAutocompleteProps): ReactNode {
+	if (suggestions.length === 0) return null
+
+	return (
+		<div className="mw-demo-suggest" id={listboxId} role="listbox" aria-label="Place suggestions">
+			<span className="mw-demo-suggest__label">{caption}</span>
+			{suggestions.map((s, i) => (
+				<button
+					key={`${s.value}-${i}`}
+					id={optionId(i)}
+					type="button"
+					role="option"
+					aria-selected={i === activeIndex}
+					className={cx("mw-chip", { "mw-chip--active": i === activeIndex })}
+					onMouseEnter={() => onHover?.(i)}
+					onClick={() => onPick(s.value)}
+					title={s.placetype}
+				>
+					{s.label ?? s.value}
+				</button>
+			))}
+		</div>
+	)
+}

package/map/PlaceMarker.tsx

@@ -0,0 +1,40 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<PlaceMarker>` — the resolved-place pin, as a declarative `react-map-gl/maplibre` `<Marker>`. This
+ *   replaces the old imperative `new maplibre.Marker(...).setLngLat(...).addTo(map)` (+ the manual
+ *   `markerRef.current.remove()` teardown) from the demo's redraw effect: mounting/unmounting the marker
+ *   is now React's job, keyed on the resolved candidate. Renders as a child of `<DemoMap>`.
+ *
+ *   NODE-IMPORT SAFETY: imports `react-map-gl/maplibre` at module scope, so it is reachable ONLY through
+ *   the `@mailwoman/react/map` subpath, never the package root.
+ */
+
+import type { ReactNode } from "react"
+import { Marker } from "react-map-gl/maplibre"
+
+/** The house pink the demo has always drawn the resolved-place marker in. */
+const MARKER_COLOR = "#e0367c"
+
+export interface PlaceMarkerProps {
+	/** Marker longitude. */
+	longitude: number
+	/** Marker latitude. */
+	latitude: number
+	/** Pin color. @default the house pink. */
+	color?: string
+	/** Which part of the marker sits on the coordinate. @default "center" (a symmetric dot). */
+	anchor?: "center" | "top" | "bottom" | "left" | "right"
+}
+
+/** A single resolved-place marker. Wraps `react-map-gl`'s `<Marker>` with the demo's default color. */
+export function PlaceMarker({
+	longitude,
+	latitude,
+	color = MARKER_COLOR,
+	anchor = "center",
+}: PlaceMarkerProps): ReactNode {
+	return <Marker longitude={longitude} latitude={latitude} color={color} anchor={anchor} />
+}

package/map/ResolvedPlaceLayers.tsx

@@ -0,0 +1,63 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<ResolvedPlaceLayers>` — the drop-in that renders a whole {@link MapPlaceRenderSpec} as `<DemoMap>`
+ *   children: the marker(s), the outline, and (optionally) the camera move. This is the declarative
+ *   replacement for the demo's imperative marker/bbox/camera redraw effect — a consumer computes the spec
+ *   with `useMapPlaceRender(place)` and drops `<ResolvedPlaceLayers spec={spec} />` inside `<DemoMap>`.
+ *
+ *   `spec = null` (no result / no candidate) renders nothing, which also unmounts the previous marker +
+ *   outline — the teardown the old effect did by hand (`markerRef.remove()`, `clearBbox`) is now just
+ *   React unmounting. NODE-IMPORT SAFETY: pulls the map components — `@mailwoman/react/map` only.
+ */
+
+import type { ReactNode } from "react"
+
+import type { MapPlaceRenderSpec } from "./place-render.ts"
+import { PlaceMarker } from "./PlaceMarker.tsx"
+import { ResultCamera } from "./ResultCamera.tsx"
+import { ResultOverlay } from "./ResultOverlay.tsx"
+
+export interface ResolvedPlaceLayersProps {
+	/** The render spec (from {@link useMapPlaceRender}); `null` renders nothing. */
+	spec: MapPlaceRenderSpec | null
+	/**
+	 * Apply the computed camera target via {@link ResultCamera}. @default true. Set false when the consumer drives the
+	 * camera itself (e.g. a controlled `<DemoMap viewState>` fed by {@link cameraToViewState}).
+	 */
+	applyCamera?: boolean
+	/** Animate the camera move. Forwarded to {@link ResultCamera}. @default true */
+	animateCamera?: boolean
+	/** Source/layer id prefix for the outline. @default "mw-result" */
+	outlineId?: string
+	/** Marker color. @default the house pink. */
+	markerColor?: string
+}
+
+/** Render the marker(s), outline, and (optional) camera move for one resolved place. */
+export function ResolvedPlaceLayers({
+	spec,
+	applyCamera = true,
+	animateCamera = true,
+	outlineId,
+	markerColor,
+}: ResolvedPlaceLayersProps): ReactNode {
+	if (!spec) return null
+
+	return (
+		<>
+			{spec.markers.map(([longitude, latitude], index) => (
+				<PlaceMarker
+					key={`${longitude},${latitude},${index}`}
+					longitude={longitude}
+					latitude={latitude}
+					color={markerColor}
+				/>
+			))}
+			<ResultOverlay outline={spec.outline} id={outlineId} color={markerColor} />
+			{applyCamera ? <ResultCamera target={spec.camera} animate={animateCamera} /> : null}
+		</>
+	)
+}

package/map/ResultCamera.tsx

@@ -0,0 +1,60 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<ResultCamera>` — applies the {@link MapCameraTarget} a {@link MapPlaceRenderSpec} computes, by
+ *   animating the live map to it. This is the ONE deliberately-imperative touch in the phase-2 overlays,
+ *   and it is justified: maplibre exposes animated camera moves (`flyTo`) and viewport-fitting
+ *   (`fitBounds`, which needs the map's PIXEL dimensions + padding) ONLY imperatively — react-map-gl has
+ *   no declarative prop for "animate to these bounds". It is applied the v8-idiomatic way, through
+ *   `useMap()` (exactly as `DashboardMap`/`GeoJSONClipboardLayer` reach the map), never a threaded handle.
+ *
+ *   A consumer that prefers a hard, declarative jump can instead feed the target through
+ *   {@link cameraToViewState} into a controlled `<DemoMap viewState>` and skip this component — the
+ *   `center` case has that declarative path; only `bounds` strictly requires this. Renders nothing.
+ *
+ *   `target` is expected to be the STABLE, memoized `camera` off a `useMapPlaceRender` spec, so listing it
+ *   as the effect dependency re-runs the camera move exactly when the resolved place changes — no
+ *   value-key dance, no dependency-lint suppression.
+ */
+
+import { type ReactNode, useEffect } from "react"
+import { useMap } from "react-map-gl/maplibre"
+
+import type { MapCameraTarget } from "./place-render.ts"
+
+export interface ResultCameraProps {
+	/** The camera target to animate to. `null` leaves the camera untouched (no result yet). */
+	target: MapCameraTarget | null
+	/**
+	 * Animate (`flyTo`/`fitBounds`) vs jump. @default true. When false, a `center` target jumps with `jumpTo`; a `bounds`
+	 * target still uses `fitBounds` (no instantaneous fit exists) but with `duration: 0`.
+	 */
+	animate?: boolean
+}
+
+/** Drive the live map to `target`. No DOM of its own — it is a behavior mounted as a `<Map>` child. */
+export function ResultCamera({ target, animate = true }: ResultCameraProps): ReactNode {
+	const map = useMap()
+
+	useEffect(() => {
+		const instance = map.current?.getMap()
+
+		if (!instance || !target) return
+
+		if (target.kind === "center") {
+			if (animate) {
+				instance.flyTo({ center: target.center, zoom: target.zoom })
+			} else {
+				instance.jumpTo({ center: target.center, zoom: target.zoom })
+			}
+
+			return
+		}
+
+		instance.fitBounds(target.bounds, { padding: target.padding, duration: animate ? undefined : 0 })
+	}, [map, target, animate])
+
+	return null
+}

package/map/ResultOverlay.tsx

@@ -0,0 +1,61 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<ResultOverlay>` — the resolved-place outline (crisp admin polygon, or an approximate/exact-radius
+ *   circle) as a declarative `<Source>` + fill/line `<Layer>`s. This replaces the demo's imperative
+ *   `setPlaceOutline` / `drawApproxCircle` / `drawPlaceGeometry` / `clearBbox` helpers and their
+ *   `whenStyleReady` gate: react-map-gl owns the "add source/layer once the style is loaded, remove on
+ *   unmount" lifecycle, so the hand-rolled `isStyleLoaded()` / `styledata` races disappear.
+ *
+ *   Pass the `outline` straight from a {@link MapPlaceRenderSpec}; a `null` outline renders nothing (the
+ *   bare-point case). NODE-IMPORT SAFETY: imports `react-map-gl/maplibre` — `@mailwoman/react/map` only.
+ */
+
+import type { ReactNode } from "react"
+import { Layer, Source } from "react-map-gl/maplibre"
+
+import type { PlaceGeometry } from "./geometry.ts"
+
+/** The house pink, matched to {@link PlaceMarker}. */
+const OUTLINE_COLOR = "#e0367c"
+
+export interface ResultOverlayProps {
+	/** The outline geometry to draw, or `null` to draw nothing (the bare-point result). */
+	outline: PlaceGeometry | null
+	/** Source/layer id prefix — override to render more than one outline on a map. @default "mw-result" */
+	id?: string
+	/** Fill color. @default the house pink. */
+	color?: string
+	/** Fill opacity. @default 0.12 */
+	fillOpacity?: number
+	/** Outline stroke width (px). @default 2 */
+	lineWidth?: number
+}
+
+/**
+ * Render the resolved-place outline. One geojson `<Source>` feeds a translucent fill `<Layer>` and a solid line
+ * `<Layer>` — the same two layers the imperative `setPlaceOutline` created, now declarative and self-cleaning.
+ */
+export function ResultOverlay({
+	outline,
+	id = "mw-result",
+	color = OUTLINE_COLOR,
+	fillOpacity = 0.12,
+	lineWidth = 2,
+}: ResultOverlayProps): ReactNode {
+	if (!outline) return null
+
+	const data = {
+		type: "FeatureCollection" as const,
+		features: [{ type: "Feature" as const, geometry: outline, properties: {} }],
+	}
+
+	return (
+		<Source id={id} type="geojson" data={data}>
+			<Layer id={`${id}-fill`} type="fill" paint={{ "fill-color": color, "fill-opacity": fillOpacity }} />
+			<Layer id={`${id}-line`} type="line" paint={{ "line-color": color, "line-width": lineWidth }} />
+		</Source>
+	)
+}

package/map/ResultPanel.tsx

@@ -0,0 +1,84 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<ResultPanel>` — the demo's parse+resolve result block, assembled from the SHARED pipeline
+ *   presentational units (it does not re-implement any of them): `KindBadge`, `ComponentTable`,
+ *   `ResolvedPlace`, `CandidatePicker`, plus the `CopyButton` + `buildParsePayload` copy affordance. This
+ *   is the standalone, story-testable unit the demo's floating panel renders (the map analogue of the
+ *   result block PipelineExplorer inlines), so `GeocoderDemo` composes ONE panel instead of duplicating
+ *   the marker/table/candidate glue. Heavy host visualizers (span highlight, tree, timing) slot in via
+ *   `extras`; the no-resolve diagnostic via `failure`.
+ *
+ *   NODE-SAFE: pure React + the shared units, no maplibre.
+ */
+
+import type { ReactNode } from "react"
+
+import { CopyButton } from "../common/CopyButton.tsx"
+import { KindBadge } from "../common/KindBadge.tsx"
+import { CandidatePicker } from "../pipeline/CandidatePicker.tsx"
+import { ComponentTable } from "../pipeline/ComponentTable.tsx"
+import { buildParsePayload } from "../pipeline/copy.ts"
+import { ResolvedPlace } from "../pipeline/ResolvedPlace.tsx"
+import type { ParseResult, ResolvedPlaceView } from "../pipeline/types.ts"
+
+export interface ResultPanelProps {
+	/** The parse+resolve result to render. */
+	result: ParseResult
+	/** The selected candidate (falls back to the first), used for the resolved-place detail + copy payload. */
+	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 heavy visualizers (span highlight, tree, timing, …), rendered from the result. */
+	extras?: (result: ParseResult) => ReactNode
+	/** Host-injected no-resolve diagnostic, rendered when nothing resolved. */
+	failure?: (result: ParseResult) => ReactNode
+}
+
+/** The composed result block for the geocoder demo. */
+export function ResultPanel({
+	result,
+	selectedCandidate,
+	selectedCandidateIndex,
+	onSelectCandidate,
+	extras,
+	failure,
+}: ResultPanelProps): ReactNode {
+	return (
+		<div className="mw-result">
+			<div className="mw-result__header">
+				<h2>Parsed components</h2>
+				<CopyButton
+					value={() => buildParsePayload(result, selectedCandidate)}
+					label="Copy JSON"
+					copiedLabel="✓ Copied"
+				/>
+			</div>
+
+			{result.kindResult ? <KindBadge kindResult={result.kindResult} /> : null}
+
+			{extras ? extras(result) : null}
+
+			<ComponentTable nodes={result.nodes} />
+
+			{selectedCandidate ? (
+				<>
+					<ResolvedPlace place={selectedCandidate} dualRoles={result.dualRoles} />
+					{result.candidates.length > 1 ? (
+						<CandidatePicker
+							candidates={result.candidates}
+							selectedIndex={selectedCandidateIndex}
+							onSelect={onSelectCandidate}
+						/>
+					) : null}
+				</>
+			) : failure ? (
+				failure(result)
+			) : null}
+		</div>
+	)
+}

package/map/VersionPicker.tsx

@@ -0,0 +1,62 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<VersionPicker>` — the model-version `<select>` from the demo's control panel (`_app.tsx:1230-1254`),
+ *   as a dumb presentational unit: the available bundles + current selection come in as props, the choice
+ *   goes out through `onSelect`. No load state, no manifest fetch — the host (via `useDemoRuntime`) owns
+ *   that. Renders nothing when there is fewer than two versions to choose between.
+ *
+ *   NODE-SAFE: pure React + a `<select>`, no maplibre. It rides the `@mailwoman/react/map` subpath only
+ *   because it is a demo-specific control, not because it needs WebGL.
+ */
+
+import type { ReactNode } from "react"
+
+import type { DemoVersionOption } from "./types.ts"
+
+export interface VersionPickerProps {
+	/** The selectable model bundles. */
+	versions: ReadonlyArray<DemoVersionOption>
+	/** The currently-selected version tag. */
+	selected: string | null
+	/** Fired with the chosen version tag. */
+	onSelect: (version: string) => void
+	/** Disable the control (e.g. while a parse is running). */
+	disabled?: boolean
+	/** Field label. @default "Model version" */
+	label?: string
+}
+
+/** The model-version selector. Renders `null` when there is nothing meaningful to pick. */
+export function VersionPicker({
+	versions,
+	selected,
+	onSelect,
+	disabled,
+	label = "Model version",
+}: VersionPickerProps): ReactNode {
+	if (versions.length < 2) return null
+
+	return (
+		<div className="mw-demo-control">
+			<label className="mw-demo-control__label" htmlFor="mw-demo-version">
+				{label}
+			</label>
+			<select
+				id="mw-demo-version"
+				className="mw-demo-control__select"
+				value={selected ?? ""}
+				onChange={(e) => onSelect(e.target.value)}
+				disabled={disabled}
+			>
+				{versions.map((v) => (
+					<option key={v.version} value={v.version}>
+						{v.label ?? v.version}
+					</option>
+				))}
+			</select>
+		</div>
+	)
+}

package/map/geometry.ts

@@ -0,0 +1,135 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Pure map geometry for the geocoder demo — the resolved-place outline math, lifted verbatim from the
+ *   docs demo's `_map-helpers.ts`. Zero imports: no React, no `react-map-gl`, no `maplibre-gl`, no DOM.
+ *   Every function takes plain numbers and returns plain GeoJSON, so the whole module runs (and is
+ *   tested) under bare node — see `geometry.node.test.ts`.
+ *
+ *   WHY NOT `@mailwoman/spatial`: the only truly-spatial primitive here is the bbox half-diagonal (a
+ *   great-circle-ish distance). `@mailwoman/spatial` exposes `haversineKm`, but ONLY via its root barrel,
+ *   which pulls `@mailwoman/core` + `h3-js` + `wkx` — a heavy, partly node-only graph — into what must
+ *   stay a lightweight, browser-only map bundle (the `@mailwoman/react/map` subpath). The original
+ *   `_map-helpers.ts` made the same call: a planar `kmPerDeg` approximation, local, no dependency. We
+ *   preserve it so the ported behavior is byte-identical and the browser graph stays clean.
+ */
+
+/** Mean km per degree of latitude (WGS84 average). */
+const KM_PER_DEG_LAT = 111.32
+
+/** A GeoJSON Polygon / MultiPolygon — what the polygon DB stores and the map draws as the place outline. */
+export type PlaceGeometry =
+	| { type: "Polygon"; coordinates: number[][][] }
+	| { type: "MultiPolygon"; coordinates: number[][][][] }
+
+/** A place bounding box in the demo's object form (the WOF points DB carries only these four numbers). */
+export interface PlaceBBox {
+	minLat: number
+	maxLat: number
+	minLon: number
+	maxLon: number
+}
+
+/** A `[west, south, east, north]` → `[[minLon, minLat], [maxLon, maxLat]]` pair, the shape `fitBounds` wants. */
+export type BoundsTuple = [[number, number], [number, number]]
+
+/** Km per degree of longitude at a given latitude — the meridians converge toward the poles. */
+function kmPerDegLon(lat: number): number {
+	return KM_PER_DEG_LAT * Math.cos((lat * Math.PI) / 180)
+}
+
+/** A closed 64-segment (65-point) GeoJSON ring of `radiusKm` around `[lon, lat]`, with latitude correction. */
+function circleRing(lat: number, lon: number, radiusKm: number): number[][] {
+	const perLon = kmPerDegLon(lat)
+	const ring: number[][] = []
+
+	for (let i = 0; i <= 64; i++) {
+		const theta = (2 * Math.PI * i) / 64
+
+		ring.push([lon + (radiusKm * Math.cos(theta)) / perLon, lat + (radiusKm * Math.sin(theta)) / KM_PER_DEG_LAT])
+	}
+
+	return ring
+}
+
+/**
+ * Approximate-extent circle for places without a crisp polygon: centered on the place point, radius from the bbox
+ * half-diagonal (clamped 0.5–50 km). 64-point ring with latitude correction — visually a circle anywhere outside the
+ * poles. With no bbox (anchor-centroid postcodes carry no extent) it defaults to a ~ZIP-sized 3 km radius.
+ */
+export function approxCircleGeometry(lat: number, lon: number, bbox?: PlaceBBox): PlaceGeometry {
+	const halfDiagKm = bbox
+		? Math.hypot((bbox.maxLat - bbox.minLat) * KM_PER_DEG_LAT, (bbox.maxLon - bbox.minLon) * kmPerDegLon(lat)) / 2
+		: 3
+	const radiusKm = Math.min(50, Math.max(0.5, halfDiagKm))
+
+	return { type: "Polygon", coordinates: [circleRing(lat, lon, radiusKm)] }
+}
+
+/**
+ * A circle of an EXACT radius in meters — for the street-level uncertainty (#377): a 10 m situs floor or a calibrated
+ * interp radius. Unlike {@link approxCircleGeometry} (clamped to a ~ZIP-sized 0.5 km floor for admin fallbacks), this
+ * honors small radii so an exact building reads as a tight dot (an ~8 m floor keeps a 10 m situs circle visible).
+ */
+export function radiusCircleGeometry(lat: number, lon: number, radiusM: number): PlaceGeometry {
+	const radiusKm = Math.max(0.008, radiusM / 1000)
+
+	return { type: "Polygon", coordinates: [circleRing(lat, lon, radiusKm)] }
+}
+
+/**
+ * Bounding box of a Polygon / MultiPolygon, for `fitBounds`. Walks the nested coordinate arrays, so it handles both a
+ * single-ring polygon and a multi-part polygon uniformly. Antimeridian-crossing geometry is NOT normalized (the naive
+ * min/max is returned) — matching the ported behavior; callers that need a wrapped bbox must handle it upstream.
+ */
+export function geomBounds(geometry: PlaceGeometry): PlaceBBox {
+	let minLon = Infinity
+	let minLat = Infinity
+	let maxLon = -Infinity
+	let maxLat = -Infinity
+
+	const visit = (node: unknown): void => {
+		if (Array.isArray(node) && typeof node[0] === "number" && typeof node[1] === "number") {
+			const lon: number = node[0]
+			const lat: number = node[1]
+
+			if (lon < minLon) {
+				minLon = lon
+			}
+
+			if (lon > maxLon) {
+				maxLon = lon
+			}
+
+			if (lat < minLat) {
+				minLat = lat
+			}
+
+			if (lat > maxLat) {
+				maxLat = lat
+			}
+
+			return
+		}
+
+		if (Array.isArray(node)) {
+			for (const child of node) {
+				visit(child)
+			}
+		}
+	}
+
+	visit(geometry.coordinates)
+
+	return { minLon, minLat, maxLon, maxLat }
+}
+
+/** Reshape a {@link PlaceBBox} into the `[[minLon, minLat], [maxLon, maxLat]]` pair `fitBounds` expects. */
+export function bboxToBounds(bbox: PlaceBBox): BoundsTuple {
+	return [
+		[bbox.minLon, bbox.minLat],
+		[bbox.maxLon, bbox.maxLat],
+	]
+}

package/map/index.ts

@@ -0,0 +1,73 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/react/map` — the geocoder-demo map surface, kept behind its OWN subpath so `maplibre-gl`
+ *   / `react-map-gl` (WebGL + DOM at import) never enter the package-root graph. Importing this subpath
+ *   pulls the map deps; importing `@mailwoman/react` (root) does not. Consumers who only want the
+ *   parse/POI explorers never pay for maplibre.
+ *
+ *   The host must supply `maplibre-gl` + `react-map-gl` (peer deps) and import
+ *   `maplibre-gl/dist/maplibre-gl.css` + `@mailwoman/react/styles.css` itself.
+ */
+
+export { DemoMap } from "./DemoMap.tsx"
+export type { DemoMapExtraProps, DemoMapProps, DemoMapStyle } from "./DemoMap.tsx"
+export type {
+	DemoBackend,
+	DemoCompareContext,
+	DemoPanels,
+	DemoResultContext,
+	DemoRuntime,
+	DemoVersionOption,
+	LngLatTuple,
+	MapBias,
+	OverlaySpec,
+	Suggestion,
+} from "./types.ts"
+
+// ── Pure geometry + render spec (node-safe; no react-map-gl at runtime) ──────
+export { approxCircleGeometry, bboxToBounds, geomBounds, radiusCircleGeometry } from "./geometry.ts"
+export type { BoundsTuple, PlaceBBox, PlaceGeometry } from "./geometry.ts"
+export { cameraToViewState, computeMapPlaceRenderSpec } from "./place-render.ts"
+export type { LngLat, MapCameraTarget, MapPlaceRenderSpec, PlaceTier, ResolvedMapPlace } from "./place-render.ts"
+export { useMapPlaceRender } from "./useMapPlaceRender.ts"
+
+// ── Declarative overlays (react-map-gl `<Marker>`/`<Source>`/`<Layer>`) ──────
+export { OverlayLayers } from "./OverlayLayers.tsx"
+export type { OverlayLayersProps } from "./OverlayLayers.tsx"
+export { PlaceMarker } from "./PlaceMarker.tsx"
+export type { PlaceMarkerProps } from "./PlaceMarker.tsx"
+export { ResolvedPlaceLayers } from "./ResolvedPlaceLayers.tsx"
+export type { ResolvedPlaceLayersProps } from "./ResolvedPlaceLayers.tsx"
+export { ResultCamera } from "./ResultCamera.tsx"
+export type { ResultCameraProps } from "./ResultCamera.tsx"
+export { ResultOverlay } from "./ResultOverlay.tsx"
+export type { ResultOverlayProps } from "./ResultOverlay.tsx"
+
+// ── Demo controls + composed demo (phase 4) ─────────────────────────────────
+export { BackendControl } from "./BackendControl.tsx"
+export type { BackendControlProps } from "./BackendControl.tsx"
+export { CompareToggle } from "./CompareToggle.tsx"
+export type { CompareToggleProps } from "./CompareToggle.tsx"
+export { DemoControls } from "./DemoControls.tsx"
+export type { DemoControlsProps } from "./DemoControls.tsx"
+export { GeocoderDemo } from "./GeocoderDemo.tsx"
+export type { GeocoderDemoProps } from "./GeocoderDemo.tsx"
+export { PlaceAutocomplete } from "./PlaceAutocomplete.tsx"
+export type { PlaceAutocompleteProps } from "./PlaceAutocomplete.tsx"
+export { ResultPanel } from "./ResultPanel.tsx"
+export type { ResultPanelProps } from "./ResultPanel.tsx"
+export { useCompareState } from "./useCompareState.ts"
+export type { UseCompareState } from "./useCompareState.ts"
+export { useDemoGeocode } from "./useDemoGeocode.ts"
+export type { UseDemoGeocode, UseDemoGeocodeOptions } from "./useDemoGeocode.ts"
+export { usePlaceAutocomplete } from "./usePlaceAutocomplete.ts"
+export type {
+	AutocompleteInputProps,
+	UsePlaceAutocomplete,
+	UsePlaceAutocompleteOptions,
+} from "./usePlaceAutocomplete.ts"
+export { VersionPicker } from "./VersionPicker.tsx"
+export type { VersionPickerProps } from "./VersionPicker.tsx"