@mailwoman/react 9.2.0 → 9.4.0

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

@@ -3,18 +3,18 @@
  * @license AGPL-3.0
  * @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 /
- *   the composed map style) plus a {@link DemoPanels} bag (the host's ModelVisualizer / VersionCompare /
+ *   `<Geocoder>` — the WHOLE geocoder, composed. It is the map analogue of `PipelineExplorer`
+ *   and takes the SAME DI shape: an injected {@link GeocoderRuntime} (the host owns ONNX / httpvfs / R2 /
+ *   the composed map style) plus a {@link GeocoderPanels} bag (the host's ModelVisualizer / VersionCompare /
  *   About / Permalink). Everything here is composition + a `ClientOnly` boundary:
  *
- *     - the floating {@link DemoControls} panel (version / compare / backend / query+autocomplete / result),
- *     - the declarative {@link DemoMap} with the phase-2 overlays ({@link OverlayLayers}) and the
+ *     - the floating {@link GeocoderControls} panel (version / compare / backend / query+autocomplete / result),
+ *     - the declarative {@link MapCanvas} with the phase-2 overlays ({@link OverlayLayers}) and the
  *       resolved-place marker/outline/camera ({@link ResolvedPlaceLayers}) driven by the parse state,
- *     - the hooks that wire them: {@link useDemoGeocode} (parse + viewport bias + map place),
+ *     - the hooks that wire them: {@link useGeocode} (parse + viewport bias + map place),
  *       {@link usePlaceAutocomplete}, {@link useCompareState}.
  *
- *   Because it pulls {@link DemoMap} (→ `react-map-gl` → `maplibre-gl`, WebGL + DOM at import), it lives on
+ *   Because it pulls {@link MapCanvas} (→ `react-map-gl` → `maplibre-gl`, WebGL + DOM at import), it lives on
  *   the `@mailwoman/react/map` subpath ONLY — never the package root. The whole thing renders in Storybook
  *   over a fake runtime (offline stub style + canned geocode) with no network, no ONNX, no gazetteer.
  */
@@ -22,27 +22,28 @@
 import { type ReactNode, useCallback, useEffect, useRef } from "react"
 import type { MapRef } from "react-map-gl/maplibre"
 
+import type { GeocoderPanels, GeocoderRuntime, MapBias } from "#map/types"
+import { useCompareState } from "#map/useCompareState"
+import { useGeocode } from "#map/useGeocode"
+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 { GeocoderControls } from "./GeocoderControls.tsx"
+import { MapCanvas } from "./MapCanvas.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 {
+export interface GeocoderProps {
 	/**
-	 * The injected demo runtime (map style + overlays + parse + version/backend).
+	 * The injected geocoder runtime (map style + overlays + parse + version/backend).
 	 */
-	runtime: DemoRuntime
+	runtime: GeocoderRuntime
 	/**
 	 * Host-injected panels (about, release blurb, compare, permalink, debug drawer, map controls, …).
 	 */
-	panels?: DemoPanels
+	panels?: GeocoderPanels
 	/**
 	 * Address to pre-fill.
 	 */
@@ -53,54 +54,54 @@ 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 `map.getZoom() >= 4` threshold. @default 4
 	 */
 	minBiasZoom?: number
 	/**
 	 * Fly/fit the map to the resolved place on each result (via {@link ResolvedPlaceLayers}). @default true. Set false
-	 * for a host that drives the camera itself (a controlled `<DemoMap viewState>`), or to keep a headless test
+	 * for a host that drives the camera itself (a controlled `<MapCanvas viewState>`), or to keep a headless test
 	 * deterministic — the marker + outline still render, only the animated camera move is skipped.
 	 */
 	applyResultCamera?: boolean
 }
 
-interface GeocoderDemoInnerProps extends Required<
-	Pick<GeocoderDemoProps, "runtime" | "defaultAddress" | "minBiasZoom" | "applyResultCamera">
+interface GeocoderInnerProps extends Required<
+	Pick<GeocoderProps, "runtime" | "defaultAddress" | "minBiasZoom" | "applyResultCamera">
 > {
-	panels: DemoPanels
+	panels: GeocoderPanels
 	presets: ReadonlyArray<Preset>
 }
 
-function GeocoderDemoInner({
+function GeocoderInner({
 	runtime,
 	panels,
 	defaultAddress,
 	presets,
 	minBiasZoom,
 	applyResultCamera,
-}: GeocoderDemoInnerProps): ReactNode {
+}: GeocoderInnerProps): ReactNode {
 	const mapRef = useRef<MapRef>(null)
 
-	// TEST SEAM: the e2e viewport-bias suite drives the REAL map (pan + zoom past the bias gate)
+	// 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 seam 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.
+	// republished on `globalThis.__mailwomanMapCanvas`. The ref fills only after react-map-gl instantiates
+	// the map, hence the short poll; cleared on unmount so a torn-down geocoder never leaves a stale
+	// handle behind.
 	useEffect(() => {
-		const seam = globalThis as { __mailwomanDemoMap?: ReturnType<MapRef["getMap"]> }
+		const host = globalThis as { __mailwomanMapCanvas?: ReturnType<MapRef["getMap"]> }
 
 		const timer = setInterval(() => {
 			const map = mapRef.current?.getMap()
 
 			if (map) {
-				seam.__mailwomanDemoMap = map
+				host.__mailwomanMapCanvas = map
 				clearInterval(timer)
 			}
 		}, 250)
 
 		return () => {
 			clearInterval(timer)
-			delete seam.__mailwomanDemoMap
+			delete host.__mailwomanMapCanvas
 		}
 	}, [])
 
@@ -118,7 +119,7 @@ function GeocoderDemoInner({
 		return { center: [center.lng, center.lat], zoom }
 	}, [minBiasZoom])
 
-	const geocode = useDemoGeocode({ runtime, defaultText: defaultAddress, getBias })
+	const geocode = useGeocode({ runtime, defaultText: defaultAddress, getBias })
 	const compare = useCompareState()
 
 	const autocomplete = usePlaceAutocomplete({
@@ -142,7 +143,7 @@ function GeocoderDemoInner({
 	return (
 		<div className="mw-geocoder-demo">
 			<div className="mw-geocoder-demo__map">
-				<DemoMap
+				<MapCanvas
 					mapStyle={runtime.mapStyle}
 					mapRef={mapRef}
 					initialViewState={{
@@ -151,17 +152,17 @@ function GeocoderDemoInner({
 						zoom: runtime.initialZoom ?? 3,
 					}}
 					style={{ width: "100%", height: "100%" }}
-					// Match the live demo's chrome: one compact attribution pill (the map's own default is a wide, always-open
-					// "MapLibre | © …" bar), no maplibre wordmark logo.
+					// One compact attribution pill (the map's own default is a wide, always-open "MapLibre | © …" bar), no
+					// maplibre wordmark logo.
 					mapProps={{ attributionControl: { compact: true }, maplibreLogo: false }}
 				>
 					<OverlayLayers overlays={runtime.overlays} />
 					<ResolvedPlaceLayers spec={spec} applyCamera={applyResultCamera} />
 					{panels.mapControls}
-				</DemoMap>
+				</MapCanvas>
 			</div>
 
-			<DemoControls
+			<GeocoderControls
 				runtime={runtime}
 				geocode={geocode}
 				autocomplete={autocomplete}
@@ -181,30 +182,30 @@ function GeocoderDemoInner({
 /**
  * Stable empty defaults — a fresh `{}`/`[]` per render would churn every downstream memo dep.
  */
-const NO_PANELS: DemoPanels = {}
+const NO_PANELS: GeocoderPanels = {}
 const NO_PRESETS: ReadonlyArray<Preset> = []
 
 /**
- * The composed geocoder demo, behind a `ClientOnly` SSR boundary (the map is intrinsically a client component).
+ * The composed geocoder, behind a `ClientOnly` SSR boundary (the map is intrinsically a client component).
  */
-export function GeocoderDemo({
+export function Geocoder({
 	runtime,
 	panels = NO_PANELS,
 	defaultAddress = "",
 	presets = NO_PRESETS,
 	minBiasZoom = 4,
 	applyResultCamera = true,
-}: GeocoderDemoProps): ReactNode {
+}: GeocoderProps): ReactNode {
 	return (
 		<ClientOnly
 			fallback={
 				<div className="mw-geocoder-demo">
-					<p>Loading demo…</p>
+					<p>Loading the geocoder…</p>
 				</div>
 			}
 		>
 			{() => (
-				<GeocoderDemoInner
+				<GeocoderInner
 					runtime={runtime}
 					panels={panels}
 					defaultAddress={defaultAddress}

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

@@ -3,19 +3,23 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `<DemoControls>` — the geocoder demo's floating control panel, assembled from the demo-specific units
+ *   `<GeocoderControls>` — the geocoder's floating control panel, assembled from the geocoder-specific units
  *   (VersionPicker / CompareToggle / BackendControl / PlaceAutocomplete / ResultPanel) and the REUSED
- *   pipeline units (QueryForm / PresetChips / LoadingIndicator). It is the presentational composition the
- *   `_app.tsx` control `<section>` (`:1222-1514`) becomes — it reads the injected {@link DemoRuntime} for
- *   ready/version/backend/loading state and threads the {@link useDemoGeocode} + {@link usePlaceAutocomplete}
- *   + {@link useCompareState} hooks into the controls. Host-specific visualizers arrive via {@link DemoPanels}.
+ *   pipeline units (QueryForm / PresetChips / LoadingIndicator). It reads the injected {@link GeocoderRuntime}
+ *   for ready/version/backend/loading state and threads the {@link useGeocode} + {@link usePlaceAutocomplete}
+ *   + {@link useCompareState} hooks into the controls. Host-specific visualizers arrive via {@link GeocoderPanels}.
  *
- *   NODE-SAFE: pure React + the shared/demo units, no maplibre. It rides `@mailwoman/react/map` as a
- *   demo-specific control, not for WebGL.
+ *   NODE-SAFE: pure React + the shared/geocoder units, no maplibre. It rides `@mailwoman/react/map` as a
+ *   geocoder-specific control, not for WebGL.
  */
 
 import type { ReactNode } from "react"
 
+import type { GeocoderPanels, GeocoderRuntime } from "#map/types"
+import type { UseCompareState } from "#map/useCompareState"
+import type { UseGeocode } from "#map/useGeocode"
+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,21 +27,17 @@ 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 {
+export interface GeocoderControlsProps {
 	/**
-	 * The injected demo runtime.
+	 * The injected geocoder runtime.
 	 */
-	runtime: DemoRuntime
+	runtime: GeocoderRuntime
 	/**
 	 * The parse+resolve state machine.
 	 */
-	geocode: UseDemoGeocode
+	geocode: UseGeocode
 	/**
 	 * The place-autocomplete combobox state.
 	 */
@@ -49,7 +49,7 @@ export interface DemoControlsProps {
 	/**
 	 * Host-injected panels (about, release blurb, compare, permalink, extras, failure).
 	 */
-	panels: DemoPanels
+	panels: GeocoderPanels
 	/**
 	 * Example chips.
 	 */
@@ -59,7 +59,7 @@ export interface DemoControlsProps {
 	 */
 	placeholder: string
 	/**
-	 * Select a model version (the composed demo also clears a now-colliding compare selection).
+	 * Select a model version (the composed geocoder also clears a now-colliding compare selection).
 	 */
 	onSelectVersion: (version: string) => void
 	/**
@@ -71,7 +71,7 @@ export interface DemoControlsProps {
 /**
  * The floating control panel.
  */
-export function DemoControls({
+export function GeocoderControls({
 	runtime,
 	geocode,
 	autocomplete,
@@ -81,7 +81,7 @@ export function DemoControls({
 	placeholder,
 	onSelectVersion,
 	onForceWASMChange,
-}: DemoControlsProps): ReactNode {
+}: GeocoderControlsProps): ReactNode {
 	const versions = runtime.availableVersions ?? []
 	const { busy, result, selectedCandidate } = geocode
 	const loading = runtime.loading

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

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `<DemoMap>` — the declarative map shell for the geocoder demo, over `react-map-gl/maplibre` (v8).
+ *   `<MapCanvas>` — the declarative map shell for the geocoder demo, over `react-map-gl/maplibre` (v8).
  *   Phase 1 is the shell only: a `<Map>` that takes a host-composed `mapStyle`, an initial (or
  *   controlled) view state, and a `children` slot for the overlays/markers that land in later phases.
  *   No overlay/marker/camera logic lives here yet.
@@ -15,10 +15,10 @@
  *   the root barrel.
  *
  *   CSS: the package imports no CSS from its modules (the node-safe invariant), so a host that renders
- *   `<DemoMap>` must import `maplibre-gl/dist/maplibre-gl.css` itself (plus `@mailwoman/react/styles.css`
- *   for the `.mw-demo-map` container). `<DemoMap>` is intrinsically a client component — a host that
+ *   `<MapCanvas>` must import `maplibre-gl/dist/maplibre-gl.css` itself (plus `@mailwoman/react/styles.css`
+ *   for the `.mw-demo-map` container). `<MapCanvas>` is intrinsically a client component — a host that
  *   server-renders should wrap it in a client boundary (the package's `ClientOnly`), exactly as the
- *   composed `GeocoderDemo` will in a later phase.
+ *   composed `Geocoder` will in a later phase.
  */
 
 import type { CSSProperties, ReactNode, Ref } from "react"
@@ -26,23 +26,23 @@ import { Map } from "react-map-gl/maplibre"
 import type { MapProps, MapRef, ViewStateChangeEvent } from "react-map-gl/maplibre"
 
 /**
- * The style a `<DemoMap>` renders — a style URL or an inline/composed `StyleSpecification`.
+ * The style a `<MapCanvas>` renders — a style URL or an inline/composed `StyleSpecification`.
  */
-export type DemoMapStyle = NonNullable<MapProps["mapStyle"]>
+export type MapCanvasStyle = NonNullable<MapProps["mapStyle"]>
 
 /**
- * Escape hatch 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.
+ * Override for the `<Map>` props `<MapCanvas>` does not surface explicitly (e.g. `minZoom`, `attributionControl`,
+ * `maplibreLogo`). The controlled fields MapCanvas owns are omitted so they can't be set twice.
  */
-export type DemoMapExtraProps = Partial<
+export type MapCanvasExtraProps = Partial<
 	Omit<MapProps, "mapStyle" | "initialViewState" | "viewState" | "onMove" | "children" | "style" | "ref">
 >
 
-export interface DemoMapProps {
+export interface MapCanvasProps {
 	/**
 	 * The map style — host-composed `StyleSpecification` or a style URL.
 	 */
-	mapStyle: DemoMapStyle
+	mapStyle: MapCanvasStyle
 	/**
 	 * Uncontrolled initial camera. Use this OR `viewState`, not both.
 	 */
@@ -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
 	/**
@@ -76,9 +76,9 @@ export interface DemoMapProps {
 	 */
 	style?: CSSProperties
 	/**
-	 * Remaining `<Map>` props DemoMap does not surface explicitly.
+	 * Remaining `<Map>` props MapCanvas does not surface explicitly.
 	 */
-	mapProps?: DemoMapExtraProps
+	mapProps?: MapCanvasExtraProps
 }
 
 const FILL: CSSProperties = { width: "100%", height: "100%" }
@@ -87,7 +87,7 @@ const FILL: CSSProperties = { width: "100%", height: "100%" }
  * The controlled-viewport map shell. Renders a sized wrapper around a `react-map-gl/maplibre` `<Map>`; everything
  * host-specific (the composed `mapStyle`, the initial center) is injected, and overlays ride in as `children`.
  */
-export function DemoMap({
+export function MapCanvas({
 	mapStyle,
 	initialViewState,
 	viewState,
@@ -98,7 +98,7 @@ export function DemoMap({
 	className,
 	style,
 	mapProps,
-}: DemoMapProps): ReactNode {
+}: MapCanvasProps): ReactNode {
 	const wrapperClassName = className ? `mw-demo-map ${className}` : "mw-demo-map"
 
 	return (

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}/PlaceMarker.tsx

@@ -6,7 +6,7 @@
  *   `<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>`.
+ *   is now React's job, keyed on the resolved candidate. Renders as a child of `<MapCanvas>`.
  *
  *   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.

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

@@ -3,10 +3,10 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `<ResolvedPlaceLayers>` — the drop-in that renders a whole {@link MapPlaceRenderSpec} as `<DemoMap>`
+ *   `<ResolvedPlaceLayers>` — the drop-in that renders a whole {@link MapPlaceRenderSpec} as `<MapCanvas>`
  *   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>`.
+ *   with `useMapPlaceRender(place)` and drops `<ResolvedPlaceLayers spec={spec} />` inside `<MapCanvas>`.
  *
  *   `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
@@ -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"
@@ -27,7 +28,7 @@ export interface ResolvedPlaceLayersProps {
 	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}).
+	 * camera itself (e.g. a controlled `<MapCanvas viewState>` fed by {@link cameraToViewState}).
 	 */
 	applyCamera?: boolean
 	/**

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

@@ -11,7 +11,7 @@
  *   `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
+ *   {@link cameraToViewState} into a controlled `<MapCanvas 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
@@ -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

@@ -7,22 +7,23 @@
  *   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
+ *   result block PipelineExplorer inlines), so `Geocoder` 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 { ParseResult, ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result"
 import type { ReactNode } from "react"
 
+import { buildParsePayload } from "#pipeline/copy"
+
 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

@@ -5,7 +5,7 @@
  *
  *   `<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
+ *   goes out through `onSelect`. No load state, no manifest fetch — the host (via `useReleaseRuntime`) 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
@@ -14,13 +14,13 @@
 
 import type { ReactNode } from "react"
 
-import type { DemoVersionOption } from "./types.ts"
+import type { VersionOption } from "#map/types"
 
 export interface VersionPickerProps {
 	/**
 	 * The selectable model bundles.
 	 */
-	versions: ReadonlyArray<DemoVersionOption>
+	versions: ReadonlyArray<VersionOption>
 	/**
 	 * The currently-selected version tag.
 	 */