@mailwoman/react 9.1.0 → 9.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @mailwoman/react
 
-React components + headless hooks for [mailwoman](https://mailwoman.sister.software) — the
+React components + headless hooks for [mailwoman](https://mailwoman.ai) — the
 parse/geocode/POI explorers from the docs site, decomposed and packaged for use in any React app.
 
 ## What's in the box
@@ -10,7 +10,7 @@ Two composed explorers, plus the small presentational units and headless hooks t
 - **`POIExplorer`** — a self-contained POI-intent tester (classify → subject → OverpassQL). The intent
   path runs entirely offline over `@mailwoman/kind-classifier`, `@mailwoman/poi-taxonomy`, and
   `@mailwoman/query-shape` — no weights, no network. A live poi.db search is opt-in via an injected
-  `runLiveSearch` probe, so the httpvfs/worker machinery never enters this package's graph.
+  `runLiveSearch` probe, so the httpvfs/worker implementation never enters this package's graph.
 - **`PipelineExplorer`** — a parse + resolve tester driven by an **injected `PipelineRuntime`**. The
   host supplies `runParse` (compute shape → classify → resolve) and the heavy visualizers as `panels`,
   keeping onnxruntime-web, sql.js-httpvfs, and node builtins out of this package entirely.

package/{common → lib/common}/ClientOnly.tsx

@@ -8,11 +8,21 @@
  *   Remix, Docusaurus). It renders `fallback` on the server and the first client paint, then swaps to
  *   `children()` once mounted — keeping timers, clipboard, and dynamic imports off the server render.
  *
- *   The mount flag is derived from a `useEffect` that fires only in the browser; this is a legitimate
- *   external-sync effect (bridging the server/client rendering boundary), not derived state.
+ *   The mount flag comes from `useSyncExternalStore` with a constant snapshot pair — `false` on the
+ *   server, `true` in the browser — which is the store-shaped statement of exactly this boundary. The
+ *   earlier `useState(false)` + `useEffect(() => setMounted(true))` said the same thing with a
+ *   render-cascade the react(set-state-in-effect) rule rightly flags: the second render was the
+ *   mechanism, not an accident, and the store form gets the same second paint without a set-state.
  */
 
-import { type ReactNode, useEffect, useState } from "react"
+import { type ReactNode, useSyncExternalStore } from "react"
+
+/**
+ * The boundary never changes after mount, so nothing ever notifies.
+ */
+function subscribeNever(): () => void {
+	return () => {}
+}
 
 export interface ClientOnlyProps {
 	/**
@@ -26,9 +36,11 @@ export interface ClientOnlyProps {
 }
 
 export function ClientOnly({ children, fallback = null }: ClientOnlyProps): ReactNode {
-	const [mounted, setMounted] = useState(false)
-
-	useEffect(() => setMounted(true), [])
+	const mounted = useSyncExternalStore(
+		subscribeNever,
+		() => true,
+		() => false
+	)
 
 	return mounted ? children() : fallback
 }

package/{common → lib/common}/CopyButton.tsx

@@ -9,7 +9,7 @@
 
 import type { ReactNode } from "react"
 
-import { useClipboard } from "./useClipboard.ts"
+import { useClipboard } from "#common/useClipboard"
 
 export interface CopyButtonProps {
 	/**

package/{common → lib/common}/LoadingIndicator.tsx

@@ -11,7 +11,7 @@
 
 import { memo, type ReactNode } from "react"
 
-import { cx } from "./cx.ts"
+import { cx } from "#common/cx"
 
 export type LoadingMode = "pulse" | "spinner" | "staged"
 

package/{index.ts → lib/index.ts}

@@ -21,17 +21,17 @@ export { ClientOnly } from "./common/ClientOnly.tsx"
 export type { ClientOnlyProps } from "./common/ClientOnly.tsx"
 export { CopyButton } from "./common/CopyButton.tsx"
 export type { CopyButtonProps } from "./common/CopyButton.tsx"
-export { cx } from "./common/cx.ts"
-export type { ClassValue } from "./common/cx.ts"
+export { cx } from "#common/cx"
+export type { ClassValue } from "#common/cx"
 export { KindBadge } from "./common/KindBadge.tsx"
 export type { KindBadgeProps, KindBadgeResult } from "./common/KindBadge.tsx"
 export { LoadingIndicator } from "./common/LoadingIndicator.tsx"
 export type { LoadingIndicatorProps, LoadingMode } from "./common/LoadingIndicator.tsx"
 export { PresetChips } from "./common/PresetChips.tsx"
 export type { Preset, PresetChipsProps } from "./common/PresetChips.tsx"
-export { useClipboard } from "./common/useClipboard.ts"
-export type { UseClipboard } from "./common/useClipboard.ts"
-export { useDebouncedValue } from "./common/useDebouncedValue.ts"
+export { useClipboard } from "#common/useClipboard"
+export type { UseClipboard } from "#common/useClipboard"
+export { useDebouncedValue } from "#common/useDebouncedValue"
 
 // ── POI explorer ───────────────────────────────────────────────────────────
 export { AbstainPanel } from "./poi/AbstainPanel.tsx"
@@ -44,7 +44,7 @@ export { POIExplorer } from "./poi/POIExplorer.tsx"
 export type { POIExplorerProps } from "./poi/POIExplorer.tsx"
 export { QueryInput } from "./poi/QueryInput.tsx"
 export type { QueryInputProps } from "./poi/QueryInput.tsx"
-export { formatDistance, loadPOIRuntime, POI_DEFAULT_TEXT, POI_PRESETS } from "./poi/runtime.ts"
+export { formatDistance, loadPOIRuntime, POI_DEFAULT_TEXT, POI_PRESETS } from "#poi/runtime"
 export { SubjectPanel } from "./poi/SubjectPanel.tsx"
 export type { SubjectPanelProps } from "./poi/SubjectPanel.tsx"
 
@@ -62,10 +62,10 @@ export type {
 	POISubject,
 	POISubjectBase,
 	TaxonomyLookup,
-} from "./poi/types.ts"
+} from "#poi/types"
 
-export { usePOISearch } from "./poi/usePOISearch.ts"
-export type { UsePOISearch, UsePOISearchOptions } from "./poi/usePOISearch.ts"
+export { usePOISearch } from "#poi/usePOISearch"
+export type { UsePOISearch, UsePOISearchOptions } from "#poi/usePOISearch"
 
 // ── Pipeline explorer ──────────────────────────────────────────────────────
 export { CandidatePicker } from "./pipeline/CandidatePicker.tsx"
@@ -74,8 +74,8 @@ export { ComponentTable } from "./pipeline/ComponentTable.tsx"
 export type { ComponentTableProps } from "./pipeline/ComponentTable.tsx"
 export { ConfidenceCell } from "./pipeline/ConfidenceCell.tsx"
 export type { ConfidenceCellProps } from "./pipeline/ConfidenceCell.tsx"
-export { buildParsePayload } from "./pipeline/copy.ts"
-export { PIPELINE_DEFAULT_ADDRESS, PIPELINE_PRESETS } from "./pipeline/presets.ts"
+export { buildParsePayload } from "#pipeline/copy"
+export { PIPELINE_DEFAULT_ADDRESS, PIPELINE_PRESETS } from "#pipeline/presets"
 export { PipelineExplorer } from "./pipeline/PipelineExplorer.tsx"
 export type { PipelineExplorerProps } from "./pipeline/PipelineExplorer.tsx"
 export { QueryForm } from "./pipeline/QueryForm.tsx"
@@ -93,13 +93,13 @@ export type {
 	PipelineRuntime,
 	ResolvedPlaceView,
 	StageTiming,
-} from "./pipeline/types.ts"
+} from "#pipeline/types"
 
-export { useParsePipeline } from "./pipeline/useParsePipeline.ts"
-export type { UseParsePipeline, UseParsePipelineOptions } from "./pipeline/useParsePipeline.ts"
+export { useParsePipeline } from "#pipeline/useParsePipeline"
+export type { UseParsePipeline, UseParsePipelineOptions } from "#pipeline/useParsePipeline"
 
 // ── Demo runtime (shared load orchestration; node-safe — no onnx/httpvfs/maplibre) ──
-export { useDemoRuntime } from "./runtime/useDemoRuntime.ts"
+export { useDemoRuntime } from "#runtime/useDemoRuntime"
 
 export type {
 	DemoAssetsLoadContext,
@@ -107,7 +107,7 @@ export type {
 	DemoManifest,
 	DemoReleaseBase,
 	DemoRuntimeConfig,
-} from "./runtime/useDemoRuntime.ts"
+} from "#runtime/useDemoRuntime"
 
 // ── Map (types only from root) ──────────────────────────────────────────────
 // The demo-map SURFACE lives behind the `@mailwoman/react/map` subpath so `maplibre-gl` / `react-map-gl`
@@ -125,4 +125,4 @@ export type {
 	MapBias,
 	OverlaySpec,
 	Suggestion,
-} from "./map/index.ts"
+} from "#map/index"

package/{map → lib/map}/CompareToggle.tsx

@@ -13,7 +13,7 @@
 
 import type { ReactNode } from "react"
 
-import type { DemoVersionOption } from "./types.ts"
+import type { DemoVersionOption } from "#map/types"
 
 export interface CompareToggleProps {
 	/**

package/{map → lib/map}/DemoControls.tsx

@@ -16,6 +16,11 @@
 
 import type { ReactNode } from "react"
 
+import type { DemoPanels, DemoRuntime } from "#map/types"
+import type { UseCompareState } from "#map/useCompareState"
+import type { UseDemoGeocode } from "#map/useDemoGeocode"
+import type { UsePlaceAutocomplete } from "#map/usePlaceAutocomplete"
+
 import { LoadingIndicator } from "../common/LoadingIndicator.tsx"
 import { PresetChips, type Preset } from "../common/PresetChips.tsx"
 import { QueryForm } from "../pipeline/QueryForm.tsx"
@@ -23,10 +28,6 @@ import { BackendControl } from "./BackendControl.tsx"
 import { CompareToggle } from "./CompareToggle.tsx"
 import { PlaceAutocomplete } from "./PlaceAutocomplete.tsx"
 import { ResultPanel } from "./ResultPanel.tsx"
-import type { DemoPanels, DemoRuntime } from "./types.ts"
-import type { UseCompareState } from "./useCompareState.ts"
-import type { UseDemoGeocode } from "./useDemoGeocode.ts"
-import type { UsePlaceAutocomplete } from "./usePlaceAutocomplete.ts"
 import { VersionPicker } from "./VersionPicker.tsx"
 
 export interface DemoControlsProps {

package/{map → lib/map}/DemoMap.tsx

@@ -31,7 +31,7 @@ import type { MapProps, MapRef, ViewStateChangeEvent } from "react-map-gl/maplib
 export type DemoMapStyle = NonNullable<MapProps["mapStyle"]>
 
 /**
- * Escape hatch for the `<Map>` props `<DemoMap>` does not surface explicitly (e.g. `minZoom`, `attributionControl`,
+ * Override for the `<Map>` props `<DemoMap>` does not surface explicitly (e.g. `minZoom`, `attributionControl`,
  * `maplibreLogo`). The controlled fields DemoMap owns are omitted so they can't be set twice.
  */
 export type DemoMapExtraProps = Partial<
@@ -52,7 +52,7 @@ export interface DemoMapProps {
 	 */
 	viewState?: MapProps["viewState"]
 	/**
-	 * Fired on every camera change (drag/zoom/rotate) — the seam for viewport-bias persistence.
+	 * Fired on every camera change (drag/zoom/rotate) — the hook for viewport-bias persistence.
 	 */
 	onMove?: (event: ViewStateChangeEvent) => void
 	/**

package/{map → lib/map}/GeocoderDemo.tsx

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  *
  *   `<GeocoderDemo>` — the WHOLE geocoder demo, composed. It is the map analogue of `PipelineExplorer`
- *   and takes the SAME DI seam shape: an injected {@link DemoRuntime} (the host owns ONNX / httpvfs / R2 /
+ *   and takes the SAME DI shape: an injected {@link DemoRuntime} (the host owns ONNX / httpvfs / R2 /
  *   the composed map style) plus a {@link DemoPanels} bag (the host's ModelVisualizer / VersionCompare /
  *   About / Permalink). Everything here is composition + a `ClientOnly` boundary:
  *
@@ -19,20 +19,21 @@
  *   over a fake runtime (offline stub style + canned geocode) with no network, no ONNX, no gazetteer.
  */
 
-import { type ReactNode, useCallback, useRef } from "react"
+import { type ReactNode, useCallback, useEffect, useRef } from "react"
 import type { MapRef } from "react-map-gl/maplibre"
 
+import type { DemoPanels, DemoRuntime, MapBias } from "#map/types"
+import { useCompareState } from "#map/useCompareState"
+import { useDemoGeocode } from "#map/useDemoGeocode"
+import { useMapPlaceRender } from "#map/useMapPlaceRender"
+import { usePlaceAutocomplete } from "#map/usePlaceAutocomplete"
+
 import { ClientOnly } from "../common/ClientOnly.tsx"
 import type { Preset } from "../common/PresetChips.tsx"
 import { DemoControls } from "./DemoControls.tsx"
 import { DemoMap } from "./DemoMap.tsx"
 import { OverlayLayers } from "./OverlayLayers.tsx"
 import { ResolvedPlaceLayers } from "./ResolvedPlaceLayers.tsx"
-import type { DemoPanels, DemoRuntime, MapBias } from "./types.ts"
-import { useCompareState } from "./useCompareState.ts"
-import { useDemoGeocode } from "./useDemoGeocode.ts"
-import { useMapPlaceRender } from "./useMapPlaceRender.ts"
-import { usePlaceAutocomplete } from "./usePlaceAutocomplete.ts"
 
 export interface GeocoderDemoProps {
 	/**
@@ -53,7 +54,7 @@ export interface GeocoderDemoProps {
 	presets?: ReadonlyArray<Preset>
 	/**
 	 * Only hint the viewport bias once the visitor has zoomed past the global view — a whole-globe center is noise.
-	 * Matches the demo's `map.getZoom() >= 4` gate. @default 4
+	 * Matches the demo's `map.getZoom() >= 4` threshold. @default 4
 	 */
 	minBiasZoom?: number
 	/**
@@ -81,6 +82,29 @@ function GeocoderDemoInner({
 }: GeocoderDemoInnerProps): ReactNode {
 	const mapRef = useRef<MapRef>(null)
 
+	// TEST INJECTION POINT: the e2e viewport-bias suite drives the REAL map (pan + zoom past the bias threshold)
+	// before submitting, and a browser test cannot reach a React ref — so the live map handle is
+	// republished on `globalThis.__mailwomanDemoMap`, the same global the pre-port demo carried. The
+	// ref fills only after react-map-gl instantiates the map, hence the short poll; cleared on
+	// unmount so a torn-down demo never leaves a stale handle behind.
+	useEffect(() => {
+		const host = globalThis as { __mailwomanDemoMap?: ReturnType<MapRef["getMap"]> }
+
+		const timer = setInterval(() => {
+			const map = mapRef.current?.getMap()
+
+			if (map) {
+				host.__mailwomanDemoMap = map
+				clearInterval(timer)
+			}
+		}, 250)
+
+		return () => {
+			clearInterval(timer)
+			delete host.__mailwomanDemoMap
+		}
+	}, [])
+
 	// Read the viewport bias at submit time — through the map handle, never a threaded state value, so granting/zooming
 	// mid-session doesn't re-create the parse callback. Below the min-bias zoom, a whole-globe center is noise → null.
 	const getBias = useCallback((): MapBias | null => {

package/{map → lib/map}/OverlayLayers.tsx

@@ -5,10 +5,10 @@
  *
  *   `<OverlayLayers>` — renders the host-supplied {@link OverlaySpec}s (coverage "fog of war",
  *   race-dots, …) as declarative `<Source>` + `<Layer>`s. This replaces the demo's imperative
- *   `map.addSource` / `map.addLayer` overlay loops (and their `isStyleLoaded()` / `styledata` gates):
+ *   `map.addSource` / `map.addLayer` overlay loops (and their `isStyleLoaded()` / `styledata` guards):
  *   the host composes the specs, the package renders them, react-map-gl owns the add/remove lifecycle.
  *
- *   Each overlay's `visible` flag flips the layers' `visibility` layout property — the declarative seam a
+ *   Each overlay's `visible` flag flips the layers' `visibility` layout property — the declarative control a
  *   layer-toggle control drives in a later phase. NODE-IMPORT SAFETY: imports `react-map-gl/maplibre` —
  *   reachable only via `@mailwoman/react/map`.
  */
@@ -16,7 +16,7 @@
 import { Fragment, type ReactNode } from "react"
 import { Layer, Source } from "react-map-gl/maplibre"
 
-import type { OverlaySpec } from "./types.ts"
+import type { OverlaySpec } from "#map/types"
 
 export interface OverlayLayersProps {
 	/**

package/{map → lib/map}/PlaceAutocomplete.tsx

@@ -14,8 +14,8 @@
 
 import type { ReactNode } from "react"
 
-import { cx } from "../common/cx.ts"
-import type { Suggestion } from "./types.ts"
+import { cx } from "#common/cx"
+import type { Suggestion } from "#map/types"
 
 export interface PlaceAutocompleteProps {
 	/**

package/{map → lib/map}/ResolvedPlaceLayers.tsx

@@ -15,7 +15,8 @@
 
 import type { ReactNode } from "react"
 
-import type { MapPlaceRenderSpec } from "./place-render.ts"
+import type { MapPlaceRenderSpec } from "#map/place-render"
+
 import { PlaceMarker } from "./PlaceMarker.tsx"
 import { ResultCamera } from "./ResultCamera.tsx"
 import { ResultOverlay } from "./ResultOverlay.tsx"

package/{map → lib/map}/ResultCamera.tsx

@@ -23,13 +23,13 @@ import type { FitBoundsOptions } from "maplibre-gl"
 import { type ReactNode, useEffect } from "react"
 import { useMap } from "react-map-gl/maplibre"
 
-import type { MapCameraTarget } from "./place-render.ts"
+import type { MapCameraTarget } from "#map/place-render"
 
 /**
  * The `fitBounds` options for a `bounds` target — and the reason this is a named function rather than an object literal
  * at the call site.
  *
- * `duration` is present ONLY on the non-animated path, and its ABSENCE on the animated one is load-bearing. maplibre's
+ * `duration` is present ONLY on the non-animated path, and its ABSENCE on the animated one is required. maplibre's
  * `Camera.flyTo` (which `fitBounds` funnels into via `_fitInternal`) branches on `'duration' in options`, not on the
  * value: an explicitly-passed `duration: undefined` therefore survives the key test and is coerced with `+undefined` →
  * `NaN`. Every ease frame then computes `k = easing(elapsed / NaN)` → `NaN`, the flight-path math yields a `NaN` world

package/{map → lib/map}/ResultOverlay.tsx

@@ -6,7 +6,7 @@
  *   `<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
+ *   `whenStyleReady` guard: 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
@@ -16,7 +16,7 @@
 import type { ReactNode } from "react"
 import { Layer, Source } from "react-map-gl/maplibre"
 
-import type { PlaceGeometry } from "./geometry.ts"
+import type { PlaceGeometry } from "#map/geometry"
 
 /**
  * The house pink, matched to {@link PlaceMarker}.

package/{map → lib/map}/ResultPanel.tsx

@@ -16,13 +16,14 @@
 
 import type { ReactNode } from "react"
 
+import { buildParsePayload } from "#pipeline/copy"
+import type { ParseResult, ResolvedPlaceView } from "#pipeline/types"
+
 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 {
 	/**

package/{map → lib/map}/VersionPicker.tsx

@@ -14,7 +14,7 @@
 
 import type { ReactNode } from "react"
 
-import type { DemoVersionOption } from "./types.ts"
+import type { DemoVersionOption } from "#map/types"
 
 export interface VersionPickerProps {
 	/**

package/{map → lib/map}/geometry.ts

@@ -56,16 +56,16 @@ function kmPerDegLon(lat: number): number {
 }
 
 /**
- * A closed 64-segment (65-point) GeoJSON ring of `radiusKm` around `[lon, lat]`, with latitude correction.
+ * 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[][] {
+function circleRing(lat: number, lon: number, radiusKM: number): number[][] {
 	const perLon = kmPerDegLon(lat)
 	const ring: number[][] = []
 
 	for (let i = 0; i <= CIRCLE_SEGMENTS; 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])
+		ring.push([lon + (radiusKM * Math.cos(theta)) / perLon, lat + (radiusKM * Math.sin(theta)) / KM_PER_DEG_LAT])
 	}
 
 	return ring
@@ -81,9 +81,9 @@ export function approxCircleGeometry(lat: number, lon: number, bbox?: PlaceBBox)
 		? 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))
+	const radiusKM = Math.min(50, Math.max(0.5, halfDiagKm))
 
-	return { type: "Polygon", coordinates: [circleRing(lat, lon, radiusKm)] }
+	return { type: "Polygon", coordinates: [circleRing(lat, lon, radiusKM)] }
 }
 
 /**
@@ -92,9 +92,9 @@ export function approxCircleGeometry(lat: number, lon: number, bbox?: PlaceBBox)
  * 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)
+	const radiusKM = Math.max(0.008, radiusM / 1000)
 
-	return { type: "Polygon", coordinates: [circleRing(lat, lon, radiusKm)] }
+	return { type: "Polygon", coordinates: [circleRing(lat, lon, radiusKM)] }
 }
 
 /**

package/{map → lib/map}/index.ts

@@ -26,14 +26,14 @@ export type {
 	MapBias,
 	OverlaySpec,
 	Suggestion,
-} from "./types.ts"
+} from "#map/types"
 
 // ── 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"
+export { approxCircleGeometry, bboxToBounds, geomBounds, radiusCircleGeometry } from "#map/geometry"
+export type { BoundsTuple, PlaceBBox, PlaceGeometry } from "#map/geometry"
+export { cameraToViewState, computeMapPlaceRenderSpec } from "#map/place-render"
+export type { LngLat, MapCameraTarget, MapPlaceRenderSpec, PlaceTier, ResolvedMapPlace } from "#map/place-render"
+export { useMapPlaceRender } from "#map/useMapPlaceRender"
 
 // ── Declarative overlays (react-map-gl `<Marker>`/`<Source>`/`<Layer>`) ──────
 export { OverlayLayers } from "./OverlayLayers.tsx"
@@ -60,17 +60,17 @@ 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 { useCompareState } from "#map/useCompareState"
+export type { UseCompareState } from "#map/useCompareState"
+export { useDemoGeocode } from "#map/useDemoGeocode"
+export type { UseDemoGeocode, UseDemoGeocodeOptions } from "#map/useDemoGeocode"
+export { usePlaceAutocomplete } from "#map/usePlaceAutocomplete"
 
 export type {
 	AutocompleteInputProps,
 	UsePlaceAutocomplete,
 	UsePlaceAutocompleteOptions,
-} from "./usePlaceAutocomplete.ts"
+} from "#map/usePlaceAutocomplete"
 
 export { VersionPicker } from "./VersionPicker.tsx"
 export type { VersionPickerProps } from "./VersionPicker.tsx"

package/{map → lib/map}/place-render.ts

@@ -19,9 +19,9 @@
  *     5. bare point                       → no outline, fly to zoom 12
  */
 
-import type { ResolvedPlaceView } from "../pipeline/types.ts"
-import { approxCircleGeometry, bboxToBounds, geomBounds, radiusCircleGeometry } from "./geometry.ts"
-import type { BoundsTuple, PlaceBBox, PlaceGeometry } from "./geometry.ts"
+import { approxCircleGeometry, bboxToBounds, geomBounds, radiusCircleGeometry } from "#map/geometry"
+import type { BoundsTuple, PlaceBBox, PlaceGeometry } from "#map/geometry"
+import type { ResolvedPlaceView } from "#pipeline/types"
 
 /**
  * `[longitude, latitude]`.

package/{map → lib/map}/types.ts

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Types for the geocoder-demo map surface. Mirrors the pipeline seam: the package owns the UI state
+ *   Types for the geocoder-demo map surface. Mirrors the pipeline boundary: the package owns the UI state
  *   machine + the declarative map, while the host injects a {@link DemoRuntime} that owns ONNX / httpvfs
  *   / R2 and the composed map style. {@link DemoRuntime} EXTENDS {@link PipelineRuntime} so the shared
  *   `runParse` / `parseStageLabels` / `loading` contract is reused, and adds the map-specific surface
@@ -12,20 +12,23 @@
  *
  *   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 — `DemoMap`, `GeocoderDemo` —
- *   are the ones gated behind the `@mailwoman/react/map` subpath).
+ *   are the ones behind the `@mailwoman/react/map` subpath).
  */
 
 import type { ReactNode } from "react"
 import type { LayerSpecification, SourceSpecification } from "react-map-gl/maplibre"
 
-import type { ParseResult, PipelineRuntime, ResolvedPlaceView } from "../pipeline/types.ts"
+import type { LngLat, ResolvedMapPlace } from "#map/place-render"
+import type { ParseResult, PipelineRuntime, ResolvedPlaceView } from "#pipeline/types"
+
 import type { DemoMapStyle } from "./DemoMap.tsx"
-import type { ResolvedMapPlace } from "./place-render.ts"
 
 /**
  * `[longitude, latitude]`.
+ *
+ * @deprecated Alias kept for existing imports — {@link LngLat} (from `@mailwoman/react/map`) is the canonical name.
  */
-export type LngLatTuple = [number, number]
+export type LngLatTuple = LngLat
 
 /**
  * A viewport bias handed to `runParse` — the map's current center (and optionally zoom) as a soft prior.
@@ -34,7 +37,7 @@ export interface MapBias {
 	/**
 	 * Map center as `[lon, lat]`, typically read from `map.getCenter()`.
 	 */
-	center: LngLatTuple
+	center: LngLat
 	/**
 	 * Current zoom, if the host wants distance-aware biasing.
 	 */
@@ -125,7 +128,7 @@ export interface DemoRuntime extends PipelineRuntime {
 	/**
 	 * Initial map center as `[lon, lat]` (the host's browser-geolocation result).
 	 */
-	initialCenter: LngLatTuple
+	initialCenter: LngLat
 	/**
 	 * Initial zoom for the first camera.
 	 */
@@ -280,8 +283,8 @@ export interface DemoPanels {
 	compare?: (context: DemoCompareContext) => 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 gates on its own dev-mode
-	 * state and returns `null` when the drawer is closed.
+	 * 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.
 	 */
 	debugDrawer?: (context: { result: ParseResult | null }) => ReactNode
 	/**

package/{map → lib/map}/useDemoGeocode.ts

@@ -20,10 +20,10 @@
 
 import { useMemo } from "react"
 
-import type { PipelineRuntime } from "../pipeline/types.ts"
-import { useParsePipeline, type UseParsePipeline } from "../pipeline/useParsePipeline.ts"
-import type { ResolvedMapPlace } from "./place-render.ts"
-import type { DemoRuntime, MapBias } from "./types.ts"
+import type { ResolvedMapPlace } from "#map/place-render"
+import type { DemoRuntime, MapBias } from "#map/types"
+import type { PipelineRuntime } from "#pipeline/types"
+import { useParsePipeline, type UseParsePipeline } from "#pipeline/useParsePipeline"
 
 export interface UseDemoGeocodeOptions {
 	/**

package/{map → lib/map}/useMapPlaceRender.ts

@@ -12,8 +12,8 @@
 
 import { useMemo } from "react"
 
-import { computeMapPlaceRenderSpec } from "./place-render.ts"
-import type { MapPlaceRenderSpec, ResolvedMapPlace } from "./place-render.ts"
+import { computeMapPlaceRenderSpec } from "#map/place-render"
+import type { MapPlaceRenderSpec, ResolvedMapPlace } from "#map/place-render"
 
 /**
  * Memoize the render spec for a resolved place; `null` in → `null` out (nothing to draw).