@mailwoman/react 9.3.0 → 10.0.0

package/lib/map/ResultPanel.tsx

@@ -7,17 +7,17 @@
  *   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 type { ParseResult, ResolvedPlaceView } from "#pipeline/types"
 
 import { CopyButton } from "../common/CopyButton.tsx"
 import { KindBadge } from "../common/KindBadge.tsx"

package/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 "#map/types"
+import type { VersionOption } from "#map/types"
 
 export interface VersionPickerProps {
 	/**
 	 * The selectable model bundles.
 	 */
-	versions: ReadonlyArray<DemoVersionOption>
+	versions: ReadonlyArray<VersionOption>
 	/**
 	 * The currently-selected version tag.
 	 */

package/lib/map/fake-runtime.ts

@@ -0,0 +1,122 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   A fake geocoder runtime: canned parse + resolve, an offline stub map style, canned autocomplete, a version list.
+ *   No network, no ONNX, no maplibre at run time — everything is data. It is what the stories and component tests
+ *   mount, and what a host mounts to show the UI without the model.
+ */
+
+import type { ParseResult } from "@mailwoman/core/pipeline/client-result"
+
+import type { ResolvedMapPlace } from "#map/place-render"
+import type { GeocoderRuntime, Suggestion } from "#map/types"
+import type { PipelineRuntime } from "#pipeline/types"
+
+import type { MapCanvasStyle } from "./MapCanvas.tsx"
+
+/**
+ * An offline stub map style — one solid `background` layer, zero sources, zero network. Safe for headless Storybook.
+ */
+export const STUB_MAP_STYLE: MapCanvasStyle = {
+	version: 8,
+	name: "demo-runtime-stub",
+	sources: {},
+	layers: [{ id: "background", type: "background", paint: { "background-color": "#dfe7ee" } }],
+}
+
+/**
+ * Canned place-autocomplete suggestions — a synchronous fake for the FST prefix-walk.
+ */
+export const FAKE_SUGGESTIONS: Suggestion[] = [
+	{ value: "New York", placetype: "locality" },
+	{ value: "New Orleans", placetype: "locality" },
+	{ value: "Newark", placetype: "locality" },
+]
+
+/**
+ * A fake DEMO runtime — the map analogue of {@link makePipelineRuntime}. It composes the pipeline fake (canned
+ * parse+resolve) with the map surface: the offline stub style, a version list, a backend, an injected autocomplete, and
+ * a `resolveMapPlace` that hands the selected candidate a bbox so the declarative overlays draw a marker + outline. No
+ * network, no ONNX, no maplibre-at-runtime — everything is data. `runParseWithBias` delegates to the base parse (the
+ * bias is ignored by the fake but present so the parameter is exercised).
+ */
+export function makeFakeGeocoderRuntime(overrides: Partial<GeocoderRuntime> = {}): GeocoderRuntime {
+	const base = makePipelineRuntime()
+
+	return {
+		...base,
+		mapStyle: STUB_MAP_STYLE,
+		initialCenter: [-74.006, 40.7128],
+		initialZoom: 3,
+		overlays: [],
+		runParseWithBias: (input, _bias, hooks) => base.runParse(input, hooks),
+		autocomplete: async (query: string) =>
+			FAKE_SUGGESTIONS.filter((s) => s.value.toLowerCase().startsWith(query.toLowerCase())),
+		availableVersions: [
+			{ version: "v7.2.0", label: "v7.2.0 (latest)" },
+			{ version: "v7.1.0", label: "v7.1.0" },
+			{ version: "v6.4.0", label: "v6.4.0" },
+		],
+		selectedVersion: "v7.2.0",
+		selectVersion: () => {},
+		activeBackend: "webgpu (28 MB int8)",
+		forceWASM: false,
+		setForceWASM: () => {},
+		// Enrich the selected candidate with a bbox so an outline renders (case 4: bbox → approximate circle + fit).
+		resolveMapPlace: (candidate): ResolvedMapPlace => ({
+			...candidate,
+			bbox: {
+				minLat: candidate.lat - 0.15,
+				maxLat: candidate.lat + 0.15,
+				minLon: candidate.lon - 0.15,
+				maxLon: candidate.lon + 0.15,
+			},
+		}),
+		...overrides,
+	}
+}
+
+/**
+ * A fixed, fully-populated parse+resolve result — the shared fixture behind the pipeline runtime + the result panel.
+ */
+export function makeFakeParseResult(input = "350 5th Ave, New York, NY 10118"): ParseResult {
+	return {
+		input,
+		tree: { roots: [{ tag: "locality", value: "New York" }] },
+		nodes: [
+			{ tag: "house_number", value: "350", confidence: 0.97, start: 0, end: 3 },
+			{ tag: "street", value: "5th Ave", confidence: 0.88, start: 4, end: 11 },
+			{ tag: "locality", value: "New York", confidence: 0.71 },
+		],
+		kindResult: { kind: "structured_address", confidence: 0.95, alternatives: [] },
+		timing: { shape: 0.4, classify: 12.1, resolve: 4.2 },
+		resolved: { id: 85_977_539, name: "New York", placetype: "locality", lat: 40.7128, lon: -74.006, score: 0.82 },
+		candidates: [
+			{ id: 85_977_539, name: "New York", placetype: "locality", lat: 40.7128, lon: -74.006, score: 0.82 },
+			{ id: 101_715_829, name: "New York", placetype: "region", lat: 43, lon: -75, score: 0.55 },
+		],
+		fstActive: true,
+		fstProvenance: { builtAt: "2026-07-01T00:00:00Z", stateCount: 51, placeCount: 94_000, importanceMatches: 12_000 },
+	}
+}
+
+/**
+ * A fake parse+resolve runtime that returns a fixed, fully-populated result.
+ */
+export function makePipelineRuntime(overrides: Partial<PipelineRuntime> = {}): PipelineRuntime {
+	return {
+		ready: true,
+		parseStageLabels: ["Analyzing input shape…", "Running neural classifier…", "Resolving in gazetteer…"],
+		errorMessage: null,
+		loading: null,
+		runParse: async (input, { onStage }): Promise<ParseResult> => {
+			onStage(1)
+			onStage(2)
+
+			return makeFakeParseResult(input)
+		},
+		...overrides,
+	}
+}

package/lib/map/index.ts

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `@mailwoman/react/map` — the geocoder-demo map surface, kept behind its OWN subpath so `maplibre-gl`
+ *   `@mailwoman/react/map` — the geocoder map surface, kept behind its OWN subpath so `maplibre-gl`
  *   / `react-map-gl` (WebGL + DOM at import) never enter the package-root graph. Importing this subpath
  *   pulls the map deps; importing `@mailwoman/react` (root) does not. Consumers who only want the
  *   parse/POI explorers never pay for maplibre.
@@ -12,20 +12,39 @@
  *   `maplibre-gl/dist/maplibre-gl.css` + `@mailwoman/react/styles.css` itself.
  */
 
-export { DemoMap } from "./DemoMap.tsx"
-export type { DemoMapExtraProps, DemoMapProps, DemoMapStyle } from "./DemoMap.tsx"
+export { MapCanvas } from "./MapCanvas.tsx"
+export type { MapCanvasExtraProps, MapCanvasProps, MapCanvasStyle } from "./MapCanvas.tsx"
+
+// ── Map chrome (node-safe presentation; the host supplies the input and reads its own map) ──
+export { MapChipRow } from "./MapChipRow.tsx"
+export type { MapChip, MapChipRowProps } from "./MapChipRow.tsx"
+export { MapCompass } from "./MapCompass.tsx"
+export type { MapCompassProps } from "./MapCompass.tsx"
+export { useMapBearing } from "./useMapBearing.ts"
+export type { UseMapBearing } from "./useMapBearing.ts"
+export { useMapLabelPick } from "./useMapLabelPick.ts"
+export { MapControlButton, MapControlGroup, MapControlStack } from "./MapControlStack.tsx"
+export type { MapControlButtonProps, MapControlGroupProps, MapControlStackProps } from "./MapControlStack.tsx"
+export { MapFooter } from "./MapFooter.tsx"
+export type { MapFooterProps } from "./MapFooter.tsx"
+export { MapProgressBar } from "./MapProgressBar.tsx"
+export type { MapProgressBarProps } from "./MapProgressBar.tsx"
+export { MapSheet } from "./MapSheet.tsx"
+export type { MapSheetProps } from "./MapSheet.tsx"
+export { MapSearchBar } from "./MapSearchBar.tsx"
+export type { MapSearchBarProps } from "./MapSearchBar.tsx"
 
 export type {
-	DemoBackend,
-	DemoCompareContext,
-	DemoPanels,
-	DemoResultContext,
-	DemoRuntime,
-	DemoVersionOption,
+	CompareContext,
+	GeocoderPanels,
+	GeocoderRuntime,
+	InferenceBackend,
 	LngLatTuple,
 	MapBias,
 	OverlaySpec,
+	ResultContext,
 	Suggestion,
+	VersionOption,
 } from "#map/types"
 
 // ── Pure geometry + render spec (node-safe; no react-map-gl at runtime) ──────
@@ -47,23 +66,23 @@ export type { ResultCameraProps } from "./ResultCamera.tsx"
 export { ResultOverlay } from "./ResultOverlay.tsx"
 export type { ResultOverlayProps } from "./ResultOverlay.tsx"
 
-// ── Demo controls + composed demo (phase 4) ─────────────────────────────────
+// ── Geocoder controls + the composed geocoder ────────────────────────────────
 export { BackendControl } from "./BackendControl.tsx"
 export type { BackendControlProps } from "./BackendControl.tsx"
 export { CompareToggle } from "./CompareToggle.tsx"
 export type { CompareToggleProps } from "./CompareToggle.tsx"
-export { DemoControls } from "./DemoControls.tsx"
-export type { DemoControlsProps } from "./DemoControls.tsx"
-export { GeocoderDemo } from "./GeocoderDemo.tsx"
-export type { GeocoderDemoProps } from "./GeocoderDemo.tsx"
+export { Geocoder } from "./Geocoder.tsx"
+export type { GeocoderProps } from "./Geocoder.tsx"
+export { GeocoderControls } from "./GeocoderControls.tsx"
+export type { GeocoderControlsProps } from "./GeocoderControls.tsx"
 export { PlaceAutocomplete } from "./PlaceAutocomplete.tsx"
 export type { PlaceAutocompleteProps } from "./PlaceAutocomplete.tsx"
 export { ResultPanel } from "./ResultPanel.tsx"
 export type { ResultPanelProps } from "./ResultPanel.tsx"
 export { useCompareState } from "#map/useCompareState"
 export type { UseCompareState } from "#map/useCompareState"
-export { useDemoGeocode } from "#map/useDemoGeocode"
-export type { UseDemoGeocode, UseDemoGeocodeOptions } from "#map/useDemoGeocode"
+export { useGeocode } from "#map/useGeocode"
+export type { UseGeocode, UseGeocodeOptions } from "#map/useGeocode"
 export { usePlaceAutocomplete } from "#map/usePlaceAutocomplete"
 
 export type {

package/lib/map/map-debug.ts

@@ -0,0 +1,51 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file The bare MapLibre control both debug panels portal into.
+ *
+ *   `DashboardMap`'s inspector and the demo page's `_debug.tsx` panel each need an `IControl` whose
+ *   only job is to own a container element for `createPortal`. The class was duplicated in both;
+ *   the position and container class are the only differences, so they are parameters here.
+ */
+
+import type { ControlPosition } from "maplibre-gl"
+import type { IControl, MapInstance } from "react-map-gl/maplibre"
+
+export interface DebugControlBaseOptions {
+	/**
+	 * Class applied to the portal container.
+	 */
+	className?: string
+	/**
+	 * Where MapLibre docks the control. @default "bottom-left"
+	 */
+	position?: ControlPosition
+}
+
+export class DebugControlBase implements IControl {
+	public readonly container: HTMLElement
+	readonly #position: ControlPosition
+
+	constructor({ className, position = "bottom-left" }: DebugControlBaseOptions = {}) {
+		this.container = document.createElement("div")
+
+		if (className) {
+			this.container.classList.add(className)
+		}
+
+		this.#position = position
+	}
+
+	public onAdd(_map: MapInstance): HTMLElement {
+		return this.container
+	}
+
+	public onRemove(_map: MapInstance): void {
+		this.container.remove()
+	}
+
+	public getDefaultPosition(): ControlPosition {
+		return this.#position
+	}
+}

package/lib/map/place-render.ts

@@ -19,9 +19,10 @@
  *     5. bare point                       → no outline, fly to zoom 12
  */
 
+import type { ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result"
+
 import { approxCircleGeometry, bboxToBounds, geomBounds, radiusCircleGeometry } from "#map/geometry"
 import type { BoundsTuple, PlaceBBox, PlaceGeometry } from "#map/geometry"
-import type { ResolvedPlaceView } from "#pipeline/types"
 
 /**
  * `[longitude, latitude]`.
@@ -167,7 +168,7 @@ export function computeMapPlaceRenderSpec(place: ResolvedMapPlace): MapPlaceRend
 }
 
 /**
- * The DECLARATIVE camera path: reshape a `center` target into a `viewState` patch a controlled `<DemoMap viewState>`
+ * The DECLARATIVE camera path: reshape a `center` target into a `viewState` patch a controlled `<MapCanvas viewState>`
  * can apply directly (a hard jump, no animation). Returns `null` for a `bounds` target — fitting a box to the viewport
  * needs the map's pixel dimensions, which only the live map has, so that case is applied imperatively by
  * `<ResultCamera>`. Pure + node-testable.

package/lib/map/types.ts

@@ -3,25 +3,26 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   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
+ *   Types for the geocoder map surface. Mirrors the pipeline boundary: the package owns the UI state
+ *   machine + the declarative map, while the host injects a {@link GeocoderRuntime} that owns ONNX / httpvfs
+ *   / R2 and the composed map style. {@link GeocoderRuntime} EXTENDS {@link PipelineRuntime} so the shared
  *   `runParse` / `parseStageLabels` / `loading` contract is reused, and adds the map-specific surface
  *   (style, overlays, initial center, viewport bias, backend/version selection). Phase 4 adds the
- *   `resolveMapPlace` enricher, the {@link DemoPanels} injection bag, and the {@link DemoCompareContext}.
+ *   `resolveMapPlace` enricher, the {@link GeocoderPanels} injection bag, and the {@link CompareContext}.
  *
  *   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` —
+ *   runtime, so this module stays node-safe (its concrete-value CONSUMERS — `MapCanvas`, `Geocoder` —
  *   are the ones behind the `@mailwoman/react/map` subpath).
  */
 
+import type { ParseResult, ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result"
 import type { ReactNode } from "react"
-import type { LayerSpecification, SourceSpecification } from "react-map-gl/maplibre"
+import type { LayerSpecification, MapInstance, SourceSpecification } from "react-map-gl/maplibre"
 
 import type { LngLat, ResolvedMapPlace } from "#map/place-render"
-import type { ParseResult, PipelineRuntime, ResolvedPlaceView } from "#pipeline/types"
+import type { PipelineRuntime } from "#pipeline/types"
 
-import type { DemoMapStyle } from "./DemoMap.tsx"
+import type { MapCanvasStyle } from "./MapCanvas.tsx"
 
 /**
  * `[longitude, latitude]`.
@@ -92,7 +93,7 @@ export interface Suggestion {
 /**
  * A selectable model bundle (version tag + a display label the picker shows).
  */
-export interface DemoVersionOption {
+export interface VersionOption {
 	/**
 	 * The version tag (e.g. a git tag or model-card version).
 	 */
@@ -104,23 +105,23 @@ export interface DemoVersionOption {
 }
 
 /**
- * Which neural backend the demo is currently running on.
+ * Which neural backend the geocoder is currently running on.
  */
-export type DemoBackend = "webgpu" | "wasm"
+export type InferenceBackend = "webgpu" | "wasm"
 
 /**
- * The injected demo runtime. Extends {@link PipelineRuntime} (shared `runParse` / `parseStageLabels` / `loading` /
- * `ready`) with the map + version/backend surface the demo needs. The host composes `mapStyle` (via cartographer's
+ * The injected geocoder runtime. Extends {@link PipelineRuntime} (shared `runParse` / `parseStageLabels` / `loading` /
+ * `ready`) with the map + version/backend surface the geocoder needs. The host composes `mapStyle` (via cartographer's
  * `StyleSpecificationComposer` + the tile-worker TileJSON), supplies the overlay specs, the initial center (from
  * geolocation), the FST autocomplete, and the calibrator — nothing in the package imports `@mailwoman/cartographer`,
- * `@mailwoman/neural-web`, httpvfs, or Docusaurus.
+ * `@mailwoman/neural`'s web loader, httpvfs, or Docusaurus.
  */
-export interface DemoRuntime extends PipelineRuntime {
+export interface GeocoderRuntime extends PipelineRuntime {
 	// ── Map ────────────────────────────────────────────────────────────────
 	/**
 	 * The composed basemap style (URL or `StyleSpecification`).
 	 */
-	mapStyle: DemoMapStyle
+	mapStyle: MapCanvasStyle
 	/**
 	 * Host-supplied overlays (coverage, race-dots, …).
 	 */
@@ -136,7 +137,7 @@ export interface DemoRuntime extends PipelineRuntime {
 
 	// ── Parse extras layered over PipelineRuntime.runParse ──────────────────
 	/**
-	 * A bias-aware parse. The map demo feeds the current viewport center as a soft prior; when absent the host falls back
+	 * A bias-aware parse. The geocoder feeds the current viewport center as a soft prior; when absent the host falls back
 	 * to the base {@link PipelineRuntime.runParse}. Kept separate so the shared `runParse` contract is unchanged.
 	 */
 	runParseWithBias?: (
@@ -154,9 +155,9 @@ export interface DemoRuntime extends PipelineRuntime {
 	calibrator?: (raw: number) => number | null
 	/**
 	 * Enrich the selected candidate into the richer {@link ResolvedMapPlace} the declarative map render consumes (bbox,
-	 * street tier + uncertainty, a pre-fetched crisp polygon) — the fields that live on the demo's `ResolvedHit` but not
+	 * street tier + uncertainty, a pre-fetched crisp polygon) — the fields that live on the host's `ResolvedHit` but not
 	 * on the shared {@link ResolvedPlaceView}. The host owns this because those extras (and the async polygon fetch in the
-	 * real demo) are host/gazetteer concerns; the package keeps {@link ParseResult} unpolluted. Absent → the candidate
+	 * real runtime) are host/gazetteer concerns; the package keeps {@link ParseResult} unpolluted. Absent → the candidate
 	 * renders as a bare point (marker + a mid-zoom fly-to). Returning `null` also renders nothing.
 	 */
 	resolveMapPlace?: (candidate: ResolvedPlaceView, result: ParseResult) => ResolvedMapPlace | null
@@ -165,7 +166,7 @@ export interface DemoRuntime extends PipelineRuntime {
 	/**
 	 * The selectable model bundles the version picker offers.
 	 */
-	availableVersions?: DemoVersionOption[]
+	availableVersions?: VersionOption[]
 	/**
 	 * The currently-selected model version.
 	 */
@@ -189,9 +190,10 @@ export interface DemoRuntime extends PipelineRuntime {
 }
 
 /**
- * The compare-mode state a {@link DemoPanels.compare} render-prop receives (the second parse itself stays host-side).
+ * The compare-mode state a {@link GeocoderPanels.compare} render-prop receives (the second parse itself stays
+ * host-side).
  */
-export interface DemoCompareContext {
+export interface CompareContext {
 	/**
 	 * The current primary parse result, or `null` before the first submit.
 	 */
@@ -207,12 +209,12 @@ export interface DemoCompareContext {
 }
 
 /**
- * The state a {@link DemoPanels.result} render-prop receives, so a host can render its OWN result block (the docs
+ * The state a {@link GeocoderPanels.result} render-prop receives, so a host can render its OWN result block (a
  * `<ResultPanel>` with its span-highlight / timing / hierarchy / precision detail) in place of the package's default
  * {@link ResultPanel}. Everything the default panel needs is passed through; the candidate-selection state stays owned
- * by the package (`useDemoGeocode`).
+ * by the package (`useGeocode`).
  */
-export interface DemoResultContext {
+export interface ResultContext {
 	/**
 	 * The current parse+resolve result.
 	 */
@@ -232,14 +234,14 @@ export interface DemoResultContext {
 }
 
 /**
- * Host-injected panels for {@link GeocoderDemo}, the map analogue of `PipelinePanels`. Each is an already-rendered
- * `ReactNode` (or a thunk of the parse result / compare state) so the package needs neither the heavy docs visualizers
- * (ModelVisualizer, VersionCompare, AboutDemo, PermalinkButton) nor their data types. Every field is optional — the
- * fake-runtime Storybook stories pass none and still render the whole demo.
+ * Host-injected panels for {@link Geocoder}, the map analogue of `PipelinePanels`. Each is an already-rendered
+ * `ReactNode` (or a thunk of the parse result / compare state) so the package needs neither the heavy host visualizers
+ * (ModelVisualizer, VersionCompare, About, PermalinkButton) nor their data types. Every field is optional — the
+ * fake-runtime Storybook stories pass none and still render the whole geocoder.
  */
-export interface DemoPanels {
+export interface GeocoderPanels {
 	/**
-	 * Rendered at the top of the control panel (e.g. the docs "About this demo").
+	 * Rendered at the top of the control panel (e.g. the host's "About this geocoder").
 	 */
 	header?: ReactNode
 	/**
@@ -251,9 +253,9 @@ export interface DemoPanels {
 	 */
 	footer?: ReactNode
 	/**
-	 * A device-location / proximity-bias control, rendered between the query form and the autocomplete list (the demo's
-	 * "📍 Use my location" row). Host-owned so the geolocation permission + the bias it feeds into the host's
-	 * {@link DemoRuntime.runParseWithBias} stay a host concern.
+	 * A device-location / proximity-bias control, rendered between the query form and the autocomplete list (the "📍 Use
+	 * my location" row). Host-owned so the geolocation permission + the bias it feeds into the host's
+	 * {@link GeocoderRuntime.runParseWithBias} stay a host concern.
 	 */
 	bias?: ReactNode
 	/**
@@ -261,17 +263,23 @@ export interface DemoPanels {
 	 */
 	extras?: (result: ParseResult) => ReactNode
 	/**
-	 * Rendered just above the result block (present or empty). The demo's opt-in display toggles live here — calibrated
-	 * confidence + dev-mode — because the host owns both the toggle state AND the {@link result} / {@link debugDrawer}
-	 * renderers those toggles drive.
+	 * Rendered just above the result block (present or empty), for content that reads on THIS answer.
+	 *
+	 * A control that reads on the model rather than on an address belongs in {@link developerExtras}: above the result it
+	 * is the first thing a visitor meets, and on a phone it pushes the answer below the fold.
 	 */
 	aboveResult?: (context: { result: ParseResult | null }) => ReactNode
+	/**
+	 * Host controls appended to the Developer sheet — the opt-in display toggles, whose state and the renderers they
+	 * drive both belong to the host.
+	 */
+	developerExtras?: ReactNode
 	/**
 	 * Replace the package's default {@link ResultPanel} entirely. When provided, the host renders its own result block
-	 * (the docs `<ResultPanel>` — span highlight, timing, hierarchy, precision detail, calibrated confidences) from the
-	 * {@link DemoResultContext}. Absent → the built-in panel renders.
+	 * (span highlight, timing, hierarchy, precision detail, calibrated confidences) from the {@link ResultContext}. Absent
+	 * → the built-in panel renders.
 	 */
-	result?: (context: DemoResultContext) => ReactNode
+	result?: (context: ResultContext) => ReactNode
 	/**
 	 * Rendered in place of the resolved-place panel when nothing resolved (host's FailureDiagnostic). Ignored when
 	 * {@link result} is set.
@@ -280,7 +288,7 @@ export interface DemoPanels {
 	/**
 	 * The version-compare view — the host renders its own diff from the compare state it owns.
 	 */
-	compare?: (context: DemoCompareContext) => ReactNode
+	compare?: (context: CompareContext) => 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 decides on its own
@@ -288,9 +296,17 @@ export interface DemoPanels {
 	 */
 	debugDrawer?: (context: { result: ParseResult | null }) => ReactNode
 	/**
-	 * Extra map controls mounted as `<DemoMap>` children (host's DebugControl / LayerToggle via `useControl`).
+	 * Extra map controls mounted as `<MapCanvas>` children (host's DebugControl / LayerToggle via `useControl`).
 	 */
 	mapControls?: ReactNode
+	/**
+	 * A layer control, rendered in the chrome's top column under the example chips rather than in a MapLibre corner.
+	 *
+	 * A render-prop taking the live map handle, because a layer control reads `getStyle().layers` and writes
+	 * `setLayoutProperty` — it cannot be a static node. The handle is `null` until the map instantiates, so the host
+	 * returns `null` for that first frame rather than rendering an empty control.
+	 */
+	layers?: (context: { map: MapInstance | null }) => ReactNode
 	/**
 	 * A permalink control for the current address (host's PermalinkButton).
 	 */

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

@@ -3,9 +3,9 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `useDemoGeocode` — the parse+resolve state machine for the geocoder map demo. It REUSES the pipeline's
+ *   `useGeocode` — the parse+resolve state machine for the geocoder map. It REUSES the pipeline's
  *   `useParsePipeline` (text / busy / stage / result / candidate selection) and layers on the two map-only
- *   concerns the demo adds over the base explorer:
+ *   concerns the geocoder adds over the base explorer:
  *
  *     1. Viewport bias — when the runtime exposes `runParseWithBias`, the current map center (read through
  *        an injected `getBias`, itself reading the `MapRef`) rides along as a soft proximity prior. The
@@ -21,15 +21,15 @@
 import { useMemo } from "react"
 
 import type { ResolvedMapPlace } from "#map/place-render"
-import type { DemoRuntime, MapBias } from "#map/types"
+import type { GeocoderRuntime, MapBias } from "#map/types"
 import type { PipelineRuntime } from "#pipeline/types"
 import { useParsePipeline, type UseParsePipeline } from "#pipeline/useParsePipeline"
 
-export interface UseDemoGeocodeOptions {
+export interface UseGeocodeOptions {
 	/**
-	 * The injected demo runtime (extends `PipelineRuntime` with the map + bias surface).
+	 * The injected geocoder runtime (extends `PipelineRuntime` with the map + bias surface).
 	 */
-	runtime: DemoRuntime
+	runtime: GeocoderRuntime
 	/**
 	 * Address to pre-fill.
 	 */
@@ -40,14 +40,14 @@ export interface UseDemoGeocodeOptions {
 	getBias?: () => MapBias | null
 }
 
-export interface UseDemoGeocode extends UseParsePipeline {
+export interface UseGeocode extends UseParsePipeline {
 	/**
 	 * The selected candidate enriched into the map-render shape (bbox / tier / polygon), or `null`.
 	 */
 	mapPlace: ResolvedMapPlace | null
 }
 
-export function useDemoGeocode({ runtime, defaultText, getBias }: UseDemoGeocodeOptions): UseDemoGeocode {
+export function useGeocode({ runtime, defaultText, getBias }: UseGeocodeOptions): UseGeocode {
 	// Bind the viewport bias into a derived `runParse` so `useParsePipeline` is reused unchanged. When the runtime has no
 	// bias-aware parse, pass it straight through.
 	const geoRuntime = useMemo<PipelineRuntime>(() => {

package/lib/map/useMapBearing.ts

@@ -0,0 +1,56 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `useMapBearing` — the map's rotation as React state, for a compass that appears off north and fades back.
+ *
+ *   The map is an external store, so it is read through `useSyncExternalStore` rather than mirrored into state by an
+ *   effect: the bearing is a number, which makes a stable snapshot, and React tears nothing during a concurrent
+ *   render.
+ *
+ *   It listens on `rotate` rather than `rotateend`, because the needle has to track the gesture rather than snap once
+ *   the gesture is over. `move` is subscribed too: a `flyTo` or an `easeTo` carrying a bearing rotates the map without
+ *   firing a rotate event, and a compass that misses those stays pointing north over a turned map.
+ */
+
+import { useCallback, useSyncExternalStore } from "react"
+import type { MapInstance } from "react-map-gl/maplibre"
+
+export interface UseMapBearing {
+	/**
+	 * Degrees off north, as MapLibre reports it. Zero while there is no map.
+	 */
+	bearing: number
+	/**
+	 * Rotate the map back to north. A no-op while there is no map.
+	 */
+	resetNorth: () => void
+}
+
+export function useMapBearing(map: MapInstance | null): UseMapBearing {
+	const subscribe = useCallback(
+		(onChange: () => void) => {
+			if (!map) return () => undefined
+
+			map.on("rotate", onChange)
+			map.on("move", onChange)
+
+			return () => {
+				map.off("rotate", onChange)
+				map.off("move", onChange)
+			}
+		},
+		[map]
+	)
+
+	// The server snapshot is the same reading: there is no map during a server render, and north is what a compass
+	// shows when it has nothing to report.
+	const readBearing = useCallback(() => map?.getBearing() ?? 0, [map])
+
+	const bearing = useSyncExternalStore(subscribe, readBearing, () => 0)
+
+	const resetNorth = useCallback(() => map?.easeTo({ bearing: 0, pitch: 0 }), [map])
+
+	return { bearing, resetNorth }
+}