@mailwoman/react 9.3.0 → 9.4.0

package/fonts.css

@@ -0,0 +1,59 @@
+/**
+ * The brand typeface, served from the same origin every app already preconnects to.
+ *
+ * Six faces, not the twenty the family ships. Each `@font-face` is a network fetch on first paint, and the token
+ * layer binds only these: regular and medium for running text, bold where a heading or a chip needs weight, italic
+ * for a caption, and two mono weights for the `code`, `number` and `glyph` roles. Iosevka provides no 600, so
+ * `--font-weight-semibold: 600` matches the 700 face by the CSS weight-matching rules rather than being synthesized.
+ *
+ * A rule never names a family here — it names a scale role from `tokens.css`, which names one of the five face
+ * roles. Replacing the typeface is an edit to `--font-family-*` in `styleframe.config.ts` plus this file.
+ */
+
+@font-face {
+	font-family: "Iosevka Nexus Web";
+	font-display: swap;
+	font-weight: 400;
+	font-style: normal;
+	src: url("https://public.mailwoman.ai/fonts/IoveskaNexus/WOFF2/IosevkaNexus-Regular.woff2") format("woff2");
+}
+
+@font-face {
+	font-family: "Iosevka Nexus Web";
+	font-display: swap;
+	font-weight: 450;
+	font-style: normal;
+	src: url("https://public.mailwoman.ai/fonts/IoveskaNexus/WOFF2/IosevkaNexus-Book.woff2") format("woff2");
+}
+
+@font-face {
+	font-family: "Iosevka Nexus Web";
+	font-display: swap;
+	font-weight: 700;
+	font-style: normal;
+	src: url("https://public.mailwoman.ai/fonts/IoveskaNexus/WOFF2/IosevkaNexus-Bold.woff2") format("woff2");
+}
+
+@font-face {
+	font-family: "Iosevka Nexus Web";
+	font-display: swap;
+	font-weight: 400;
+	font-style: italic;
+	src: url("https://public.mailwoman.ai/fonts/IoveskaNexus/WOFF2/IosevkaNexus-Italic.woff2") format("woff2");
+}
+
+@font-face {
+	font-family: "Iosevka Nexus Mono Web";
+	font-display: swap;
+	font-weight: 400;
+	font-style: normal;
+	src: url("https://public.mailwoman.ai/fonts/IosevkaNexusMono/WOFF2/IosevkaNexusMono-Regular.woff2") format("woff2");
+}
+
+@font-face {
+	font-family: "Iosevka Nexus Mono Web";
+	font-display: swap;
+	font-weight: 450;
+	font-style: normal;
+	src: url("https://public.mailwoman.ai/fonts/IosevkaNexusMono/WOFF2/IosevkaNexusMono-Book.woff2") format("woff2");
+}

package/lib/common/About.tsx

@@ -0,0 +1,89 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `About` — the collapsible explainer for the browser geocoder: the neural model, the confidence colours, the
+ *   gazetteer resolver, the byte-range database and the FST prior. Prose about the product a host places above or
+ *   beside the geocoder; it renders nothing live.
+ */
+
+import type { ReactNode } from "react"
+
+export function About(): ReactNode {
+	return (
+		<details className="mw-about">
+			<summary className="mw-about__summary">
+				<span className="mw-about__icon">ℹ️</span>
+				About this geocoder
+			</summary>
+			<div className="mw-about__body">
+				<section className="mw-about__section">
+					<h3 className="mw-about__heading">Neural model</h3>
+					<p>
+						A ~29M-parameter BERT-style encoder classifies each token into one of 33 BIO labels covering 16 address
+						components (street, house number, unit, locality, region, postcode, venue, country, intersection, etc.). It
+						runs entirely in your browser via <strong>onnxruntime-web</strong> (WebGPU with WASM SIMD fallback). The
+						model ships as a 37.6 MB int8-quantized ONNX bundle; fp32 weights are also available for higher accuracy.
+					</p>
+				</section>
+
+				<section className="mw-about__section">
+					<h3 className="mw-about__heading">Confidence colors</h3>
+					<p>
+						Every classified span carries a confidence score between 0 and 1. The colors in the results table give you a
+						quick visual read:
+					</p>
+					<ul className="mw-about__legend">
+						<li className="mw-about__item">
+							<span className="mw-about__swatch mw-about__swatch--high" />
+							<strong>Green</strong> (≥ 0.8) — high confidence. The model is nearly certain.
+						</li>
+						<li className="mw-about__item">
+							<span className="mw-about__swatch mw-about__swatch--mid" />
+							<strong>Amber</strong> (0.5–0.8) — moderate confidence. Worth verifying.
+						</li>
+						<li className="mw-about__item">
+							<span className="mw-about__swatch mw-about__swatch--low" />
+							<strong>Red</strong> (&lt; 0.5) — low confidence. The model is unsure — likely wrong.
+						</li>
+					</ul>
+					<p>
+						These are raw model scores. For calibrated probabilities, the library ships a per-locale isotonic calibrator
+						(<code>calibration.json</code>) that maps the raw scores to well-calibrated probability estimates.
+					</p>
+				</section>
+
+				<section className="mw-about__section">
+					<h3 className="mw-about__heading">WOF resolver</h3>
+					<p>
+						After classification, the resolver queries a <strong>Who&apos;s On First</strong> (WOF) SQLite gazetteer to
+						match the parsed components — locality, region, and postcode — against real-world places with coordinates.
+						The cascade tries postcode first (most precise), then locality, then the raw input text. The result is a
+						sorted list of candidate places with WOF IDs, placetypes, lat/lon, and bounding boxes.
+					</p>
+				</section>
+
+				<section className="mw-about__section">
+					<h3 className="mw-about__heading">Byte-range gazetteer</h3>
+					<p>
+						The gazetteer is a multi-gigabyte SQLite file served from a public bucket. It loads via{" "}
+						<strong>sql.js-httpvfs</strong>, which range-requests only the pages a lookup touches, so your browser
+						fetches a few hundred kilobytes per session instead of the whole file.
+					</p>
+				</section>
+
+				<section className="mw-about__section">
+					<h3 className="mw-about__heading">FST prior</h3>
+					<p>
+						A <strong>finite-state transducer</strong> (FST) built from ~94K US place names runs before the neural
+						classifier. It pre-annotates known locality, region, and postcode spans in the input — places like
+						&quot;Springfield&quot; or &quot;Cook County&quot; that the FST can match exactly. These &quot;FST
+						prior&quot; hits feed the classifier as strong hints, improving locality and region recall on addresses
+						where the neural model alone might miss them. The FST is active whenever the selected release includes it.
+					</p>
+				</section>
+			</div>
+		</details>
+	)
+}

package/lib/common/KindBadge.tsx

@@ -9,16 +9,11 @@
  *   pipeline's projection satisfy it without a hard type dependency.
  */
 
+import type { KindView } from "@mailwoman/core/pipeline/client-result"
 import type { ReactNode } from "react"
 
-export interface KindBadgeResult {
-	kind: string
-	confidence: number
-	alternatives: ReadonlyArray<{ kind: string; confidence: number }>
-}
-
 export interface KindBadgeProps {
-	kindResult: KindBadgeResult
+	kindResult: KindView
 }
 
 const formatPct = (n: number): string => `${Math.round(n * 100)}%`

package/lib/common/confidence-tiers.ts

@@ -0,0 +1,50 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Confidence banding shared by every component that colours a span by confidence.
+ *
+ *   It is a presentation choice, not a model one: the parser emits a continuous confidence and these
+ *   bounds only decide which colour a span is drawn in, so they live here rather than anywhere the
+ *   pipeline can see them.
+ */
+
+/**
+ * At or above this the span is drawn as high-confidence.
+ */
+export const HIGH_CONFIDENCE_MIN = 0.8
+
+/**
+ * At or above this the span is drawn as medium-confidence; below it, low.
+ */
+export const MID_CONFIDENCE_MIN = 0.5
+
+/**
+ * The banding a component applies to a span's confidence.
+ */
+export type ConfidenceTier = "high" | "mid" | "low"
+
+/**
+ * Bands a continuous confidence into the three tiers the demo styles against.
+ *
+ * @param confidence A parser confidence in `[0, 1]`.
+ *
+ * @returns The tier to style with.
+ */
+export function confidenceTier(confidence: number): ConfidenceTier {
+	if (confidence >= HIGH_CONFIDENCE_MIN) return "high"
+
+	if (confidence >= MID_CONFIDENCE_MIN) return "mid"
+
+	return "low"
+}
+
+/**
+ * {@link confidenceTier} for a possibly-absent confidence: an unmeasured span is drawn as `mid` rather than `low`, so an
+ * older model that emits no confidence never reads as uniformly wrong.
+ */
+export function confidenceTierOrMid(confidence?: number): ConfidenceTier {
+	if (confidence == null) return "mid"
+
+	return confidenceTier(confidence)
+}

package/lib/common/text-tokens.ts

@@ -0,0 +1,88 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Word tokenization + span ownership shared by the word-level visualizers.
+ *
+ *   A word-level panel splits the raw input on whitespace and assigns each word to its most specific
+ *   covering span (the shortest-span owner, the same rule a character-level highlight applies per
+ *   character). Two panels must agree for the BIO labels to line up between them, so the split and
+ *   the owner walk live here.
+ */
+
+export interface WordToken {
+	/**
+	 * The word text as it appears in the input.
+	 */
+	text: string
+	/**
+	 * Leading whitespace before this word.
+	 */
+	whitespace: string
+	/**
+	 * Start offset in the input string.
+	 */
+	start: number
+	/**
+	 * End offset in the input string (exclusive).
+	 */
+	end: number
+}
+
+/**
+ * Tokenize the raw input into words, preserving leading whitespace for each token.
+ */
+export function tokenizeWords(input: string): WordToken[] {
+	const words: WordToken[] = []
+	let i = 0
+
+	// `charAt` answers "" past the end, which no whitespace test matches, so both walks stop at the input's length.
+	while (i < input.length) {
+		let ws = ""
+
+		while (/\s/.test(input.charAt(i))) {
+			ws += input.charAt(i)
+
+			i++
+		}
+
+		if (i >= input.length) break
+		const start = i
+
+		while (i < input.length && !/\s/.test(input.charAt(i))) {
+			i++
+		}
+
+		words.push({ text: input.slice(start, i), start, end: i, whitespace: ws })
+	}
+
+	return words
+}
+
+/**
+ * A half-open `[start, end)` character range into the input.
+ */
+export interface CharSpan {
+	start: number
+	end: number
+}
+
+/**
+ * Per-word index of the most specific (shortest) span covering it, or `-1` when no span overlaps the word. A word is
+ * covered when any part of it falls within the span.
+ */
+export function shortestSpanOwners(words: readonly CharSpan[], spans: readonly CharSpan[]): number[] {
+	return words.map((word) => {
+		let best = -1
+		let bestLen = Infinity
+
+		for (const [s, sp] of spans.entries()) {
+			if (word.start < sp.end && word.end > sp.start && sp.end - sp.start < bestLen) {
+				bestLen = sp.end - sp.start
+				best = s
+			}
+		}
+
+		return best
+	})
+}

package/lib/index.ts

@@ -24,7 +24,7 @@ export type { CopyButtonProps } from "./common/CopyButton.tsx"
 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 type { KindBadgeProps } from "./common/KindBadge.tsx"
 export { LoadingIndicator } from "./common/LoadingIndicator.tsx"
 export type { LoadingIndicatorProps, LoadingMode } from "./common/LoadingIndicator.tsx"
 export { PresetChips } from "./common/PresetChips.tsx"
@@ -67,6 +67,18 @@ export type {
 export { usePOISearch } from "#poi/usePOISearch"
 export type { UsePOISearch, UsePOISearchOptions } from "#poi/usePOISearch"
 
+// ── Result visualizers ─────────────────────────────────────────────────────
+
+export { About } from "./common/About.tsx"
+export { FailureDiagnostic } from "./pipeline/FailureDiagnostic.tsx"
+export type { FailureDiagnosticProps } from "./pipeline/FailureDiagnostic.tsx"
+export { SpanHighlight } from "./pipeline/SpanHighlight.tsx"
+export type { SpanHighlightProps } from "./pipeline/SpanHighlight.tsx"
+export { TimingPanel } from "./pipeline/TimingPanel.tsx"
+export type { TimingPanelProps } from "./pipeline/TimingPanel.tsx"
+export { TreeView } from "./pipeline/TreeView.tsx"
+export type { TreeViewProps } from "./pipeline/TreeView.tsx"
+
 // ── Pipeline explorer ──────────────────────────────────────────────────────
 export { CandidatePicker } from "./pipeline/CandidatePicker.tsx"
 export type { CandidatePickerProps } from "./pipeline/CandidatePicker.tsx"
@@ -83,46 +95,36 @@ export type { QueryFormProps } from "./pipeline/QueryForm.tsx"
 export { ResolvedPlace } from "./pipeline/ResolvedPlace.tsx"
 export type { ResolvedPlaceProps } from "./pipeline/ResolvedPlace.tsx"
 
-export type {
-	DualRoleView,
-	FSTProvenance,
-	ParsedComponent,
-	ParseResult,
-	PipelineLoadingState,
-	PipelinePanels,
-	PipelineRuntime,
-	ResolvedPlaceView,
-	StageTiming,
-} from "#pipeline/types"
+export type { PipelineLoadingState, PipelinePanels, PipelineRuntime } from "#pipeline/types"
 
 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"
+// ── Release runtime (shared load orchestration; node-safe — no onnx/httpvfs/maplibre) ──
+export { useReleaseRuntime } from "#runtime/useReleaseRuntime"
 
 export type {
-	DemoAssetsLoadContext,
-	DemoLoaderState,
-	DemoManifest,
-	DemoReleaseBase,
-	DemoRuntimeConfig,
-} from "#runtime/useDemoRuntime"
+	AssetsLoadContext,
+	ReleaseBase,
+	ReleaseLoaderState,
+	ReleaseManifest,
+	ReleaseRuntimeConfig,
+} from "#runtime/useReleaseRuntime"
 
 // ── Map (types only from root) ──────────────────────────────────────────────
-// The demo-map SURFACE lives behind the `@mailwoman/react/map` subpath so `maplibre-gl` / `react-map-gl`
+// The 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`.
+// runtime linkage): the `MapCanvas` component + hooks are import-able solely via `@mailwoman/react/map`.
 export type {
-	DemoBackend,
-	DemoMapExtraProps,
-	DemoMapProps,
-	DemoMapStyle,
-	DemoRuntime,
-	DemoVersionOption,
+	GeocoderRuntime,
+	InferenceBackend,
 	LngLatTuple,
 	MapBias,
+	MapCanvasExtraProps,
+	MapCanvasProps,
+	MapCanvasStyle,
 	OverlaySpec,
 	Suggestion,
+	VersionOption,
 } from "#map/index"

package/lib/map/CompareToggle.tsx

@@ -13,13 +13,13 @@
 
 import type { ReactNode } from "react"
 
-import type { DemoVersionOption } from "#map/types"
+import type { VersionOption } from "#map/types"
 
 export interface CompareToggleProps {
 	/**
 	 * The selectable model bundles (the primary version is filtered out of the compare list).
 	 */
-	versions: ReadonlyArray<DemoVersionOption>
+	versions: ReadonlyArray<VersionOption>
 	/**
 	 * The primary version, excluded from the compare options.
 	 */

package/lib/map/{GeocoderDemo.tsx → 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 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,28 +22,28 @@
 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 type { GeocoderPanels, GeocoderRuntime, MapBias } from "#map/types"
 import { useCompareState } from "#map/useCompareState"
-import { useDemoGeocode } from "#map/useDemoGeocode"
+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"
 
-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.
 	 */
@@ -54,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` threshold. @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 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.
+	// 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 host = globalThis as { __mailwomanDemoMap?: ReturnType<MapRef["getMap"]> }
+		const host = globalThis as { __mailwomanMapCanvas?: ReturnType<MapRef["getMap"]> }
 
 		const timer = setInterval(() => {
 			const map = mapRef.current?.getMap()
 
 			if (map) {
-				host.__mailwomanDemoMap = map
+				host.__mailwomanMapCanvas = map
 				clearInterval(timer)
 			}
 		}, 250)
 
 		return () => {
 			clearInterval(timer)
-			delete host.__mailwomanDemoMap
+			delete host.__mailwomanMapCanvas
 		}
 	}, [])
 
@@ -119,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({
@@ -143,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={{
@@ -152,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}
@@ -182,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}