@mailwoman/react 7.4.0 → 7.6.0

package/common/PresetChips.tsx

@@ -20,9 +20,11 @@ export interface PresetChipsProps {
 	disabled?: boolean
 	/** Leading label. @default "Try:" */
 	caption?: string
+	/** Optional trailing content rendered inside the chip row after the presets (e.g. an inline permalink button). */
+	trailing?: ReactNode
 }
 
-export function PresetChips({ presets, onPick, disabled, caption = "Try:" }: PresetChipsProps): ReactNode {
+export function PresetChips({ presets, onPick, disabled, caption = "Try:", trailing }: PresetChipsProps): ReactNode {
 	return (
 		<div className="mw-presets">
 			<span className="mw-presets__label">{caption}</span>
@@ -38,6 +40,7 @@ export function PresetChips({ presets, onPick, disabled, caption = "Try:" }: Pre
 					{preset.label}
 				</button>
 			))}
+			{trailing}
 		</div>
 	)
 }

package/index.ts

@@ -51,12 +51,15 @@ export type {
 	CategoryRecord,
 	LiveSearchState,
 	LoadPOIRuntime,
+	POIBrandSubject,
+	POICategorySubject,
 	POIExplorerResult,
 	POILiveSearch,
 	POILiveSearchResult,
 	POIRuntime,
 	POISearchHit,
 	POISubject,
+	POISubjectBase,
 	TaxonomyLookup,
 } from "./poi/types.ts"
 export { usePOISearch } from "./poi/usePOISearch.ts"
@@ -90,3 +93,31 @@ export type {
 } from "./pipeline/types.ts"
 export { useParsePipeline } from "./pipeline/useParsePipeline.ts"
 export type { UseParsePipeline, UseParsePipelineOptions } from "./pipeline/useParsePipeline.ts"
+
+// ── Demo runtime (shared load orchestration; node-safe — no onnx/httpvfs/maplibre) ──
+export { useDemoRuntime } from "./runtime/useDemoRuntime.ts"
+export type {
+	DemoAssetsLoadContext,
+	DemoLoaderState,
+	DemoManifest,
+	DemoReleaseBase,
+	DemoRuntimeConfig,
+} from "./runtime/useDemoRuntime.ts"
+
+// ── Map (types only from root) ──────────────────────────────────────────────
+// The demo-map SURFACE lives behind the `@mailwoman/react/map` subpath so `maplibre-gl` / `react-map-gl`
+// (WebGL + DOM at import) never enter the package-root graph — a bare `import("@mailwoman/react")` in node
+// must not pull them. Only the CONTRACT types are re-exported here (fully erased at compile time, so no
+// runtime linkage): the `DemoMap` component + hooks are import-able solely via `@mailwoman/react/map`.
+export type {
+	DemoBackend,
+	DemoMapExtraProps,
+	DemoMapProps,
+	DemoMapStyle,
+	DemoRuntime,
+	DemoVersionOption,
+	LngLatTuple,
+	MapBias,
+	OverlaySpec,
+	Suggestion,
+} from "./map/index.ts"

package/map/BackendControl.tsx

@@ -0,0 +1,39 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<BackendControl>` — the neural-backend indicator + "Force WASM" checkbox from the demo's control
+ *   panel (`_app.tsx:1255-1280`), as a dumb presentational unit. It shows which backend the runtime
+ *   resolved to (WebGPU / WASM, with the int8 size the host formats into the label) and lets the visitor
+ *   opt out of WebGPU. Props in, one boolean event out — the host re-loads the bundle on the toggle.
+ *
+ *   NODE-SAFE: pure React, no maplibre.
+ */
+
+import type { ReactNode } from "react"
+
+export interface BackendControlProps {
+	/** The backend the runtime resolved to (e.g. `webgpu (28 MB int8)`); empty before it is known. */
+	activeBackend?: string
+	/** Whether the CPU/WASM backend is currently forced. */
+	forceWASM: boolean
+	/** Fired when the visitor toggles the "Force WASM" checkbox. */
+	onForceWASMChange: (forceWASM: boolean) => void
+}
+
+/** The backend indicator + WASM opt-out. */
+export function BackendControl({ activeBackend, forceWASM, onForceWASMChange }: BackendControlProps): ReactNode {
+	return (
+		<div className="mw-demo-backend">
+			{activeBackend ? (
+				<span className="mw-demo-backend__active">
+					Backend: <code>{activeBackend}</code>
+				</span>
+			) : null}
+			<label className="mw-demo-backend__toggle">
+				<input type="checkbox" checked={forceWASM} onChange={(e) => onForceWASMChange(e.target.checked)} /> Force WASM
+			</label>
+		</div>
+	)
+}

package/map/CompareToggle.tsx

@@ -0,0 +1,81 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<CompareToggle>` — the "Compare" checkbox plus the compare-version `<select>` from the demo's
+ *   control panel (`_app.tsx:1281-1339`), as a dumb presentational unit. Turning it on reveals a second
+ *   version picker (the primary version filtered out); the actual second parse is a host concern the
+ *   composed demo surfaces through `panels.compare`. Props in, two events out.
+ *
+ *   NODE-SAFE: pure React, no maplibre.
+ */
+
+import type { ReactNode } from "react"
+
+import type { DemoVersionOption } from "./types.ts"
+
+export interface CompareToggleProps {
+	/** The selectable model bundles (the primary version is filtered out of the compare list). */
+	versions: ReadonlyArray<DemoVersionOption>
+	/** The primary version, excluded from the compare options. */
+	primaryVersion: string | null
+	/** Whether compare mode is on. */
+	compareMode: boolean
+	/** Fired when the visitor flips compare mode. */
+	onCompareModeChange: (compareMode: boolean) => void
+	/** The version chosen to compare against, or `null` when none is chosen. */
+	compareVersion: string | null
+	/** Fired with the chosen compare version (or `null` when the empty option is picked). */
+	onCompareVersionChange: (version: string | null) => void
+	/** Disable the compare-version select (e.g. while a parse or compare load runs). */
+	disabled?: boolean
+	/** A status line rendered under the select (e.g. the compare backend, or a "Loading…" line). */
+	status?: ReactNode
+}
+
+/** The compare toggle + (when on) the compare-version selector. Renders `null` with fewer than two versions. */
+export function CompareToggle({
+	versions,
+	primaryVersion,
+	compareMode,
+	onCompareModeChange,
+	compareVersion,
+	onCompareVersionChange,
+	disabled,
+	status,
+}: CompareToggleProps): ReactNode {
+	if (versions.length < 2) return null
+
+	const options = versions.filter((v) => v.version !== primaryVersion)
+
+	return (
+		<div className="mw-demo-compare">
+			<label className="mw-demo-compare__toggle">
+				<input type="checkbox" checked={compareMode} onChange={(e) => onCompareModeChange(e.target.checked)} /> Compare
+			</label>
+			{compareMode ? (
+				<div className="mw-demo-control">
+					<label className="mw-demo-control__label" htmlFor="mw-demo-compare-version">
+						Compare with
+					</label>
+					<select
+						id="mw-demo-compare-version"
+						className="mw-demo-control__select"
+						value={compareVersion ?? ""}
+						onChange={(e) => onCompareVersionChange(e.target.value || null)}
+						disabled={disabled}
+					>
+						<option value="">Select version…</option>
+						{options.map((v) => (
+							<option key={v.version} value={v.version}>
+								{v.label ?? v.version}
+							</option>
+						))}
+					</select>
+					{status ? <p className="mw-demo-compare__status">{status}</p> : null}
+				</div>
+			) : null}
+		</div>
+	)
+}

package/map/DemoControls.tsx

@@ -0,0 +1,173 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<DemoControls>` — the geocoder demo's floating control panel, assembled from the demo-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}.
+ *
+ *   NODE-SAFE: pure React + the shared/demo units, no maplibre. It rides `@mailwoman/react/map` as a
+ *   demo-specific control, not for WebGL.
+ */
+
+import type { ReactNode } from "react"
+
+import { LoadingIndicator } from "../common/LoadingIndicator.tsx"
+import { PresetChips, type Preset } from "../common/PresetChips.tsx"
+import { QueryForm } from "../pipeline/QueryForm.tsx"
+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 {
+	/** The injected demo runtime. */
+	runtime: DemoRuntime
+	/** The parse+resolve state machine. */
+	geocode: UseDemoGeocode
+	/** The place-autocomplete combobox state. */
+	autocomplete: UsePlaceAutocomplete
+	/** The compare-mode state. */
+	compare: UseCompareState
+	/** Host-injected panels (about, release blurb, compare, permalink, extras, failure). */
+	panels: DemoPanels
+	/** Example chips. */
+	presets: ReadonlyArray<Preset>
+	/** Input placeholder. */
+	placeholder: string
+	/** Select a model version (the composed demo also clears a now-colliding compare selection). */
+	onSelectVersion: (version: string) => void
+	/** Toggle the forced WASM backend. */
+	onForceWASMChange: (forceWASM: boolean) => void
+}
+
+/** The floating control panel. */
+export function DemoControls({
+	runtime,
+	geocode,
+	autocomplete,
+	compare,
+	panels,
+	presets,
+	placeholder,
+	onSelectVersion,
+	onForceWASMChange,
+}: DemoControlsProps): ReactNode {
+	const versions = runtime.availableVersions ?? []
+	const { busy, result, selectedCandidate } = geocode
+	const loading = runtime.loading
+	const errorMessage = geocode.parseError ?? runtime.errorMessage ?? null
+
+	return (
+		<section className="mw-demo-controls">
+			{panels.header}
+			{panels.releaseInfo}
+
+			<VersionPicker
+				versions={versions}
+				selected={runtime.selectedVersion ?? null}
+				onSelect={onSelectVersion}
+				disabled={busy}
+			/>
+
+			<BackendControl
+				activeBackend={runtime.activeBackend}
+				forceWASM={runtime.forceWASM ?? false}
+				onForceWASMChange={onForceWASMChange}
+			/>
+
+			<CompareToggle
+				versions={versions}
+				primaryVersion={runtime.selectedVersion ?? null}
+				compareMode={compare.compareMode}
+				onCompareModeChange={compare.setCompareMode}
+				compareVersion={compare.compareVersion}
+				onCompareVersionChange={compare.setCompareVersion}
+				disabled={busy}
+			/>
+
+			<QueryForm
+				value={geocode.text}
+				onChange={geocode.setText}
+				onSubmit={geocode.submit}
+				disabled={!runtime.ready}
+				busy={busy}
+				placeholder={placeholder}
+				onKeyDown={autocomplete.onInputKeyDown}
+				inputProps={autocomplete.inputProps}
+			/>
+
+			{panels.bias}
+
+			<PlaceAutocomplete
+				suggestions={autocomplete.suggestions}
+				activeIndex={autocomplete.activeIndex}
+				onPick={autocomplete.pick}
+				onHover={autocomplete.setActiveIndex}
+				listboxId={autocomplete.listboxId}
+				optionId={autocomplete.optionId}
+			/>
+
+			<PresetChips
+				presets={presets}
+				disabled={!runtime.ready || busy}
+				onPick={(value) => {
+					geocode.setText(value)
+					geocode.reset()
+				}}
+				trailing={panels.permalink ? panels.permalink(geocode.text) : null}
+			/>
+
+			{loading && !runtime.ready ? (
+				<LoadingIndicator
+					mode="staged"
+					steps={loading.stepLabels.length > 0 ? loading.stepLabels : undefined}
+					activeStep={loading.stepIndex}
+					label={loading.progress}
+				/>
+			) : null}
+			{errorMessage ? <p className="mw-error">{errorMessage}</p> : null}
+
+			{panels.aboveResult ? panels.aboveResult({ result }) : null}
+
+			{busy ? (
+				<div className="mw-result">
+					<LoadingIndicator mode="staged" steps={runtime.parseStageLabels} activeStep={geocode.parseStage} />
+				</div>
+			) : result ? (
+				panels.result ? (
+					panels.result({
+						result,
+						selectedCandidate,
+						selectedCandidateIndex: geocode.selectedCandidateIndex,
+						onSelectCandidate: geocode.selectCandidate,
+					})
+				) : (
+					<ResultPanel
+						result={result}
+						selectedCandidate={selectedCandidate}
+						selectedCandidateIndex={geocode.selectedCandidateIndex}
+						onSelectCandidate={geocode.selectCandidate}
+						extras={panels.extras}
+						failure={panels.failure}
+					/>
+				)
+			) : null}
+
+			{panels.compare
+				? panels.compare({ result, compareMode: compare.compareMode, compareVersion: compare.compareVersion })
+				: null}
+
+			{panels.footer}
+		</section>
+	)
+}

package/map/DemoMap.tsx

@@ -0,0 +1,98 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<DemoMap>` — 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.
+ *
+ *   NODE-IMPORT SAFETY: this module imports `react-map-gl/maplibre` (which pulls `maplibre-gl` — WebGL
+ *   + DOM at import) at module scope, so it is reachable ONLY through the `@mailwoman/react/map`
+ *   subpath, never from the package root (`index.ts`). The bare `import("@mailwoman/react")` a node
+ *   consumer (or the CI smoke IMPORT_CHECK) runs must never transitively load this file. Keep it out of
+ *   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
+ *   server-renders should wrap it in a client boundary (the package's `ClientOnly`), exactly as the
+ *   composed `GeocoderDemo` will in a later phase.
+ */
+
+import type { CSSProperties, ReactNode, Ref } from "react"
+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`. */
+export type DemoMapStyle = 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.
+ */
+export type DemoMapExtraProps = Partial<
+	Omit<MapProps, "mapStyle" | "initialViewState" | "viewState" | "onMove" | "children" | "style" | "ref">
+>
+
+export interface DemoMapProps {
+	/** The map style — host-composed `StyleSpecification` or a style URL. */
+	mapStyle: DemoMapStyle
+	/** Uncontrolled initial camera. Use this OR `viewState`, not both. */
+	initialViewState?: MapProps["initialViewState"]
+	/** Controlled camera. Pair with `onMove` to persist it. */
+	viewState?: MapProps["viewState"]
+	/** Fired on every camera change (drag/zoom/rotate) — the seam for viewport-bias persistence. */
+	onMove?: (event: ViewStateChangeEvent) => void
+	/** Map projection. @default "globe" (matches the docs `DashboardMap`). */
+	projection?: MapProps["projection"]
+	/** Forwarded to the underlying `<Map>` for imperative access (`useMap`/`flyTo` in later phases). */
+	mapRef?: Ref<MapRef>
+	/** Overlays, markers, and controls — rendered as `<Map>` children. Empty in phase 1. */
+	children?: ReactNode
+	/** Class on the wrapper element. */
+	className?: string
+	/** Inline style on the wrapper element (sizing lives here or on `.mw-demo-map`). */
+	style?: CSSProperties
+	/** Remaining `<Map>` props DemoMap does not surface explicitly. */
+	mapProps?: DemoMapExtraProps
+}
+
+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({
+	mapStyle,
+	initialViewState,
+	viewState,
+	onMove,
+	projection = "globe",
+	mapRef,
+	children,
+	className,
+	style,
+	mapProps,
+}: DemoMapProps): ReactNode {
+	const wrapperClassName = className ? `mw-demo-map ${className}` : "mw-demo-map"
+
+	return (
+		<div className={wrapperClassName} style={style}>
+			<Map
+				{...mapProps}
+				ref={mapRef}
+				mapStyle={mapStyle}
+				initialViewState={initialViewState}
+				viewState={viewState}
+				onMove={onMove}
+				projection={projection}
+				style={FILL}
+			>
+				{children}
+			</Map>
+		</div>
+	)
+}

package/map/GeocoderDemo.tsx

@@ -0,0 +1,178 @@
+/**
+ * @copyright Sister Software
+ * @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 /
+ *   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
+ *       resolved-place marker/outline/camera ({@link ResolvedPlaceLayers}) driven by the parse state,
+ *     - the hooks that wire them: {@link useDemoGeocode} (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
+ *   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.
+ */
+
+import { type ReactNode, useCallback, useRef } from "react"
+import type { MapRef } from "react-map-gl/maplibre"
+
+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 {
+	/** The injected demo runtime (map style + overlays + parse + version/backend). */
+	runtime: DemoRuntime
+	/** Host-injected panels (about, release blurb, compare, permalink, debug drawer, map controls, …). */
+	panels?: DemoPanels
+	/** Address to pre-fill. */
+	defaultAddress?: string
+	/** Example chips. @default the empty set (host supplies its own). */
+	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
+	 */
+	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
+	 * 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">
+> {
+	panels: DemoPanels
+	presets: ReadonlyArray<Preset>
+}
+
+function GeocoderDemoInner({
+	runtime,
+	panels,
+	defaultAddress,
+	presets,
+	minBiasZoom,
+	applyResultCamera,
+}: GeocoderDemoInnerProps): ReactNode {
+	const mapRef = useRef<MapRef>(null)
+
+	// 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 => {
+		const map = mapRef.current?.getMap()
+
+		if (!map) return null
+		const zoom = map.getZoom()
+
+		if (zoom < minBiasZoom) return null
+		const center = map.getCenter()
+
+		return { center: [center.lng, center.lat], zoom }
+	}, [minBiasZoom])
+
+	const geocode = useDemoGeocode({ runtime, defaultText: defaultAddress, getBias })
+	const compare = useCompareState()
+	const autocomplete = usePlaceAutocomplete({
+		text: geocode.text,
+		setText: geocode.setText,
+		autocomplete: runtime.autocomplete,
+	})
+
+	const spec = useMapPlaceRender(geocode.mapPlace)
+
+	const onSelectVersion = useCallback(
+		(version: string) => {
+			runtime.selectVersion?.(version)
+			compare.clearIfPrimary(version)
+		},
+		[runtime, compare]
+	)
+
+	const onForceWASMChange = useCallback((forceWASM: boolean) => runtime.setForceWASM?.(forceWASM), [runtime])
+
+	return (
+		<div className="mw-geocoder-demo">
+			<div className="mw-geocoder-demo__map">
+				<DemoMap
+					mapStyle={runtime.mapStyle}
+					mapRef={mapRef}
+					initialViewState={{
+						longitude: runtime.initialCenter[0],
+						latitude: runtime.initialCenter[1],
+						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.
+					mapProps={{ attributionControl: { compact: true }, maplibreLogo: false }}
+				>
+					<OverlayLayers overlays={runtime.overlays} />
+					<ResolvedPlaceLayers spec={spec} applyCamera={applyResultCamera} />
+					{panels.mapControls}
+				</DemoMap>
+			</div>
+
+			<DemoControls
+				runtime={runtime}
+				geocode={geocode}
+				autocomplete={autocomplete}
+				compare={compare}
+				panels={panels}
+				presets={presets}
+				placeholder={defaultAddress}
+				onSelectVersion={onSelectVersion}
+				onForceWASMChange={onForceWASMChange}
+			/>
+
+			{panels.debugDrawer ? panels.debugDrawer({ result: geocode.result }) : null}
+		</div>
+	)
+}
+
+/** The composed geocoder demo, behind a `ClientOnly` SSR boundary (the map is intrinsically a client component). */
+export function GeocoderDemo({
+	runtime,
+	panels = {},
+	defaultAddress = "",
+	presets = [],
+	minBiasZoom = 4,
+	applyResultCamera = true,
+}: GeocoderDemoProps): ReactNode {
+	return (
+		<ClientOnly
+			fallback={
+				<div className="mw-geocoder-demo">
+					<p>Loading demo…</p>
+				</div>
+			}
+		>
+			{() => (
+				<GeocoderDemoInner
+					runtime={runtime}
+					panels={panels}
+					defaultAddress={defaultAddress}
+					presets={presets}
+					minBiasZoom={minBiasZoom}
+					applyResultCamera={applyResultCamera}
+				/>
+			)}
+		</ClientOnly>
+	)
+}

package/map/OverlayLayers.tsx

@@ -0,0 +1,46 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<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):
+ *   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
+ *   layer-toggle control drives in a later phase. NODE-IMPORT SAFETY: imports `react-map-gl/maplibre` —
+ *   reachable only via `@mailwoman/react/map`.
+ */
+
+import { Fragment, type ReactNode } from "react"
+import { Layer, Source } from "react-map-gl/maplibre"
+
+import type { OverlaySpec } from "./types.ts"
+
+export interface OverlayLayersProps {
+	/** The overlays to render, in draw order (first is drawn first / lowest). */
+	overlays?: OverlaySpec[]
+}
+
+/** Render each overlay as one `<Source>` and its `<Layer>`s, honoring the `visible` flag via `visibility`. */
+export function OverlayLayers({ overlays }: OverlayLayersProps): ReactNode {
+	if (!overlays || overlays.length === 0) return null
+
+	return (
+		<>
+			{overlays.map((overlay) => {
+				const visibility = overlay.visible === false ? "none" : "visible"
+
+				return (
+					<Fragment key={overlay.id}>
+						<Source id={overlay.id} {...overlay.source} />
+						{overlay.layers.map((layer) => (
+							<Layer key={layer.id} {...layer} layout={{ ...layer.layout, visibility }} />
+						))}
+					</Fragment>
+				)
+			})}
+		</>
+	)
+}