@mailwoman/react 10.1.0 → 10.2.0

package/README.md

@@ -24,6 +24,7 @@ units (`QueryInput`, `SubjectPanel`, `OverpassBlock`, `LiveResultsBlock`, `Compo
 
 ```tsx
 import { POIExplorer, PipelineExplorer } from "@mailwoman/react"
+
 import "@mailwoman/react/styles.css"
 ```
 

package/lib/common/About.tsx

@@ -15,7 +15,7 @@ export interface AboutProps {
 	 * Set false where the host is already the disclosure, because a summary repeating
 	 * an About button's words is one control too many.
 	 *
-	 * @default true
+	 * @defaultValue `true`
 	 */
 	collapsible?: boolean
 }
@@ -28,8 +28,8 @@ export function About({ collapsible = true }: AboutProps = {}): ReactNode {
 				<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.
+					runs entirely in your browser via <strong>onnxruntime-web</strong> on its WASM SIMD backend. The model ships
+					as a 37.6 MB int8-quantized ONNX bundle; fp32 weights are also available for higher accuracy.
 				</p>
 			</section>
 

package/lib/common/CopyButton.tsx

@@ -19,11 +19,15 @@ export interface CopyButtonProps {
 	 */
 	value: string | (() => string)
 	/**
-	 * Label in the idle state. @default "Copy"
+	 * Label in the idle state.
+	 *
+	 * @defaultValue `"Copy"`
 	 */
 	label?: ReactNode
 	/**
-	 * Label shown briefly after a successful copy. @default "✓ Copied"
+	 * Label shown briefly after a successful copy.
+	 *
+	 * @defaultValue `"✓ Copied"`
 	 */
 	copiedLabel?: ReactNode
 	className?: string

package/lib/common/LoadingIndicator.tsx

@@ -17,7 +17,7 @@ export type LoadingMode = "pulse" | "spinner" | "staged"
 
 export interface LoadingIndicatorProps extends React.HTMLAttributes<HTMLDivElement> {
 	/**
-	 * @default "spinner"
+	 * @defaultValue `"spinner"`
 	 */
 	mode?: LoadingMode
 	/**
@@ -26,11 +26,15 @@ export interface LoadingIndicatorProps extends React.HTMLAttributes<HTMLDivEleme
 	 */
 	label?: string
 	/**
-	 * Number of skeleton bars (pulse mode). @default 3
+	 * Number of skeleton bars (pulse mode).
+	 *
+	 * @defaultValue `3`
 	 */
 	barCount?: number
 	/**
-	 * Spinner ring size. @default "medium"
+	 * Spinner ring size.
+	 *
+	 * @defaultValue `"medium"`
 	 */
 	size?: "small" | "medium" | "large"
 	/**
@@ -39,7 +43,9 @@ export interface LoadingIndicatorProps extends React.HTMLAttributes<HTMLDivEleme
 	steps?: string[]
 	/**
 	 * 0-based index of the active step.
-	 * Earlier steps are complete, later ones pending. @default -1
+	 * Earlier steps are complete, later ones pending.
+	 *
+	 * @defaultValue `-1`
 	 */
 	activeStep?: number
 }

package/lib/common/PresetChips.tsx

@@ -26,7 +26,9 @@ export interface PresetChipsProps {
 	onPick: (value: string) => void
 	disabled?: boolean
 	/**
-	 * The label shown before the choices. @default "Try:"
+	 * The label shown before the choices.
+	 *
+	 * @defaultValue `"Try:"`
 	 */
 	caption?: string
 	/**

package/lib/common/confidence-tiers.ts

@@ -44,7 +44,7 @@ export function confidenceTier(confidence: number): ConfidenceTier {
  * {@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 {
+export function confidenceTierOrMid(confidence?: number | null): ConfidenceTier {
 	if (confidence == null) return "mid"
 
 	return confidenceTier(confidence)

package/lib/common/text-tokens.ts

@@ -10,6 +10,8 @@
  *   the owner walk live here.
  */
 
+import type { CharRange } from "@mailwoman/query-shape"
+
 export interface WordToken {
 	/**
 	 * The word text as it appears in the input.
@@ -61,20 +63,12 @@ export function tokenizeWords(input: string): WordToken[] {
 	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[] {
+export function shortestSpanOwners(words: readonly CharRange[], spans: readonly CharRange[]): number[] {
 	return words.map((word) => {
 		let best = -1
 		let bestLen = Infinity

package/lib/index.ts

@@ -33,7 +33,6 @@ export * from "#runtime"
  */
 export type {
 	GeocoderRuntime,
-	InferenceBackend,
 	LngLatTuple,
 	MapBias,
 	MapCanvasExtraProps,

package/lib/map/AppIdentity.tsx

@@ -30,11 +30,15 @@ export interface AppIdentityProps {
 	 */
 	docsURL?: string
 	/**
-	 * The documentation link's text. @default "Developer Documentation"
+	 * The documentation link's text.
+	 *
+	 * @defaultValue `"Developer Documentation"`
 	 */
 	docsLabel?: string
 	/**
-	 * The URL of the build record. @default "/build.json"
+	 * The URL of the build record.
+	 *
+	 * @defaultValue `"/build.json"`
 	 */
 	buildInfoURL?: string
 	/**

package/lib/map/DebugInfo.tsx

@@ -4,7 +4,6 @@
  * @author Teffen Ellis, et al.
  *
  *   Display and log build, model and runtime details for bug reports.
- *   Report the actual execution backend because successful loading does not imply WebGPU ran.
  */
 
 import { type ReactNode, useEffect, useMemo } from "react"
@@ -13,15 +12,9 @@ import { useBuildInfo } from "#common/useBuildInfo"
 
 export interface DebugInfoProps {
 	/**
-	 * The backend the runtime resolved to (e.g. `webgpu (28 MB int8)`); empty before it is known.
+	 * The runtime's backend and model size (e.g. `wasm (28 MB int8)`); empty before the model loads.
 	 */
 	activeBackend?: string
-	/**
-	 * Whether the CPU/wasm backend is currently forced.
-	 *
-	 * This explains a `wasm` backend that would otherwise indicate a WebGPU failure.
-	 */
-	forceWASM?: boolean
 	/**
 	 * The model version the runtime loaded.
 	 *
@@ -47,7 +40,7 @@ function Row({ label, value }: { label: string; value: string }): ReactNode {
 	)
 }
 
-export function DebugInfo({ activeBackend, forceWASM, selectedVersion, ready }: DebugInfoProps): ReactNode {
+export function DebugInfo({ activeBackend, selectedVersion, ready }: DebugInfoProps): ReactNode {
 	const build = useBuildInfo()
 
 	// Memoized on the primitives it reads, so the log below fires when a value changes
@@ -60,11 +53,9 @@ export function DebugInfo({ activeBackend, forceWASM, selectedVersion, ready }:
 			buildTime: build?.buildTime ?? "—",
 			model: selectedVersion ?? "—",
 			backend: activeBackend || (ready ? "unknown" : "loading…"),
-			forceWASM: Boolean(forceWASM),
-			webgpuInBrowser: typeof navigator !== "undefined" && "gpu" in navigator,
 			userAgent: typeof navigator !== "undefined" ? navigator.userAgent : "—",
 		}),
-		[build?.app, build?.commit, build?.revision, build?.buildTime, selectedVersion, activeBackend, forceWASM, ready]
+		[build?.app, build?.commit, build?.revision, build?.buildTime, selectedVersion, activeBackend, ready]
 	)
 
 	useEffect(() => {
@@ -79,10 +70,6 @@ export function DebugInfo({ activeBackend, forceWASM, selectedVersion, ready }:
 			<Row label="Built" value={record.buildTime} />
 			<Row label="Model" value={record.model} />
 			<Row label="Backend" value={record.backend} />
-			{/* A browser with no WebGPU at all explains a `wasm` backend that is otherwise indistinguishable from a
-			    WebGPU session that threw. */}
-			<Row label="WebGPU available" value={record.webgpuInBrowser ? "yes" : "no"} />
-			<Row label="Force WASM" value={record.forceWASM ? "on" : "off"} />
 		</div>
 	)
 }

package/lib/map/Geocoder.tsx

@@ -50,13 +50,13 @@ export interface GeocoderProps {
 	/**
 	 * The example chips.
 	 *
-	 * @default []
+	 * @defaultValue []
 	 */
 	presets?: ReadonlyArray<Preset>
 	/**
 	 * Whether the developer panel starts open.
 	 *
-	 * @default false
+	 * @defaultValue `false`
 	 */
 	developer?: boolean
 	/**
@@ -69,7 +69,7 @@ export interface GeocoderProps {
 	/**
 	 * The minimum map zoom at which the viewport is sent as a location bias.
 	 *
-	 * @default 4
+	 * @defaultValue `4`
 	 */
 	minBiasZoom?: number
 	/**
@@ -78,7 +78,7 @@ export interface GeocoderProps {
 	 * Set it to false when the host controls the camera or a test needs a fixed view.
 	 * The marker and outline render either way.
 	 *
-	 * @default true
+	 * @defaultValue `true`
 	 */
 	applyResultCamera?: boolean
 }
@@ -111,6 +111,9 @@ function GeocoderInner({
 	// The graticule is inserted before the first non-background layer, so it draws under the data layers.
 	const [baseLayerID, setBaseLayerID] = useState<string | undefined>(undefined)
 
+	// Overlays are inserted before the first label layer, so place names stay readable over a fill.
+	const [labelLayerID, setLabelLayerID] = useState<string | undefined>(undefined)
+
 	const onMapLoad = useCallback((event: { target: ReturnType<MapRef["getMap"]> }) => {
 		// Browser tests read the map from this global.
 		;(globalThis as { __mailwomanMapCanvas?: ReturnType<MapRef["getMap"]> }).__mailwomanMapCanvas = event.target
@@ -119,6 +122,7 @@ function GeocoderInner({
 		const layers = event.target.getStyle()?.layers ?? []
 
 		setBaseLayerID(layers.find((layer) => layer.type !== "background")?.id)
+		setLabelLayerID(layers.find((layer) => layer.type === "symbol")?.id)
 	}, [])
 
 	useEffect(
@@ -160,8 +164,6 @@ function GeocoderInner({
 		[runtime, compare]
 	)
 
-	const onForceWASMChange = useCallback((forceWASM: boolean) => runtime.setForceWASM?.(forceWASM), [runtime])
-
 	return (
 		<div className="mw-geocoder-demo">
 			<div className="mw-geocoder-demo__map">
@@ -179,7 +181,7 @@ function GeocoderInner({
 					mapProps={{ attributionControl: { compact: true }, maplibreLogo: false, onLoad: onMapLoad }}
 				>
 					<GraticuleLayer beforeID={baseLayerID} />
-					<OverlayLayers overlays={runtime.overlays} />
+					<OverlayLayers overlays={runtime.overlays} beforeID={labelLayerID} />
 					<ResolvedPlaceLayers spec={spec} applyCamera={applyResultCamera} />
 					{panels.mapControls}
 				</MapCanvas>
@@ -197,7 +199,6 @@ function GeocoderInner({
 				map={map}
 				onSubmitQuery={onSubmitQuery}
 				onSelectVersion={onSelectVersion}
-				onForceWASMChange={onForceWASMChange}
 				developer={developer}
 			/>
 			{panels.debugDrawer ? panels.debugDrawer({ result: geocode.result }) : null}

package/lib/map/GeocoderControls.tsx

@@ -17,7 +17,6 @@ import type { UsePlaceAutocomplete } from "#map/usePlaceAutocomplete"
 
 import { LoadingIndicator } from "../common/LoadingIndicator.tsx"
 import type { Preset } from "../common/PresetChips.tsx"
-import { BackendControl } from "./BackendControl.tsx"
 import { CompareToggle } from "./CompareToggle.tsx"
 import { DebugInfo } from "./DebugInfo.tsx"
 import { MapChipRow } from "./MapChipRow.tsx"
@@ -56,11 +55,10 @@ export interface GeocoderControlsProps {
 	 */
 	onSubmitQuery?: (query: string) => void
 	onSelectVersion: (version: string) => void
-	onForceWASMChange: (forceWASM: boolean) => void
 	/**
 	 * Whether the developer panel starts open.
 	 *
-	 * @default false
+	 * @defaultValue `false`
 	 */
 	developer?: boolean
 }
@@ -100,7 +98,6 @@ export function GeocoderControls({
 	initialQuery = null,
 	onSubmitQuery,
 	onSelectVersion,
-	onForceWASMChange,
 	developer = false,
 }: GeocoderControlsProps): ReactNode {
 	const versions = runtime.availableVersions ?? []
@@ -608,19 +605,10 @@ export function GeocoderControls({
 						/>
 					</div>
 
-					<div className="mw-map-sheet__row">
-						<BackendControl
-							activeBackend={runtime.activeBackend}
-							forceWASM={runtime.forceWASM ?? false}
-							onForceWASMChange={onForceWASMChange}
-						/>
-					</div>
-
 					<div className="mw-map-sheet__row">
 						<span className="mw-map-sheet__label">Debug info</span>
 						<DebugInfo
 							activeBackend={runtime.activeBackend}
-							forceWASM={runtime.forceWASM}
 							selectedVersion={runtime.selectedVersion}
 							ready={runtime.ready}
 						/>

package/lib/map/GraticuleLayer.tsx

@@ -22,7 +22,9 @@ export interface GraticuleLayerProps {
 	 */
 	beforeID?: string
 	/**
-	 * Hides the grid. @default false
+	 * Hides the grid.
+	 *
+	 * @defaultValue `false`
 	 */
 	hidden?: boolean
 }

package/lib/map/MapCanvas.tsx

@@ -62,7 +62,9 @@ export interface MapCanvasProps {
 	 */
 	onMove?: (event: ViewStateChangeEvent) => void
 	/**
-	 * Map projection. @default "globe" (matches the docs `DashboardMap`).
+	 * Map projection.
+	 *
+	 * @defaultValue `"globe"` (matches the docs `DashboardMap`).
 	 */
 	projection?: MapProps["projection"]
 	/**

package/lib/map/MapChipRow.tsx

@@ -18,7 +18,7 @@ export interface MapChip {
 	/**
 	 * The query the chip stands for, handed back on press.
 	 *
-	 * Defaults to the label.
+	 * @defaultValue the label.
 	 */
 	value?: string
 	/**

package/lib/map/MapCompass.tsx

@@ -31,7 +31,9 @@ export interface MapCompassProps {
 	 */
 	onResetNorth: () => void
 	/**
-	 * The control's accessible name. @default "Reset bearing to north"
+	 * The control's accessible name.
+	 *
+	 * @defaultValue `"Reset bearing to north"`
 	 */
 	label?: string
 	className?: string

package/lib/map/MapControlStack.tsx

@@ -74,7 +74,9 @@ export interface MapControlStackProps {
 	 */
 	children: ReactNode
 	/**
-	 * Which edge the column sits against. @default "right"
+	 * Which edge the column sits against.
+	 *
+	 * @defaultValue `"right"`
 	 */
 	side?: "left" | "right"
 	className?: string

package/lib/map/MapFooter.tsx

@@ -22,7 +22,9 @@ export interface MapFooterProps {
 	 */
 	attribution?: ReactNode[]
 	/**
-	 * What the attribution button reads. @default "Sources"
+	 * What the attribution button reads.
+	 *
+	 * @defaultValue `"Sources"`
 	 */
 	attributionLabel?: string
 	className?: string

package/lib/map/OverlayLayers.tsx

@@ -23,12 +23,18 @@ export interface OverlayLayersProps {
 	 * The overlays to render, in draw order (first is drawn first / lowest).
 	 */
 	overlays?: OverlaySpec[]
+	/**
+	 * The basemap layer every overlay layer is inserted beneath, such as the first
+	 * label layer, so labels stay readable over a fill.
+	 * Omitted, the layers go on top of the style.
+	 */
+	beforeID?: string
 }
 
 /**
  * Render each overlay as one `<Source>` and its `<Layer>`s, honoring the `visible` flag via `visibility`.
  */
-export function OverlayLayers({ overlays }: OverlayLayersProps): ReactNode {
+export function OverlayLayers({ overlays, beforeID }: OverlayLayersProps): ReactNode {
 	if (!overlays || !overlays.length) return null
 
 	return (
@@ -40,7 +46,12 @@ export function OverlayLayers({ overlays }: OverlayLayersProps): ReactNode {
 					<Fragment key={overlay.id}>
 						<Source id={overlay.id} {...overlay.source} />
 						{overlay.layers.map((layer) => (
-							<Layer key={layer.id} {...layer} layout={{ ...layer.layout, visibility }} />
+							<Layer
+								key={layer.id}
+								{...layer}
+								{...(beforeID ? { beforeId: beforeID } : {})}
+								layout={{ ...layer.layout, visibility }}
+							/>
 						))}
 					</Fragment>
 				)

package/lib/map/PlaceAutocomplete.tsx

@@ -31,7 +31,9 @@ export interface PlaceAutocompleteProps {
 	 */
 	optionID: (index: number) => string
 	/**
-	 * The label before the suggestions. @default "Did you mean:"
+	 * The label before the suggestions.
+	 *
+	 * @defaultValue `"Did you mean:"`
 	 */
 	caption?: string
 }

package/lib/map/PlaceMarker.tsx

@@ -30,11 +30,15 @@ export interface PlaceMarkerProps {
 	 */
 	latitude: number
 	/**
-	 * Pin color. @default the house pink.
+	 * Pin color.
+	 *
+	 * @defaultValue the house pink.
 	 */
 	color?: string
 	/**
-	 * Which part of the marker sits on the coordinate. @default "center" (a symmetric dot).
+	 * Which part of the marker sits on the coordinate.
+	 *
+	 * @defaultValue `"center"` (a symmetric dot).
 	 */
 	anchor?: "center" | "top" | "bottom" | "left" | "right"
 }

package/lib/map/ResolvedPlaceLayers.tsx

@@ -18,20 +18,28 @@ export interface ResolvedPlaceLayersProps {
 	 */
 	spec: MapPlaceRenderSpec | null
 	/**
-	 * Apply the computed camera target via {@link ResultCamera}; set false when the consumer drives the camera
-	 * itself (e.g. a controlled `<MapCanvas viewState>` fed by {@link cameraToViewState}). @default true
+	 * Apply the computed camera target via {@link ResultCamera}; set false when the consumer drives the
+	 * camera itself (e.g. a controlled `<MapCanvas viewState>` fed by {@link cameraToViewState}).
+	 *
+	 * @defaultValue `true`
 	 */
 	applyCamera?: boolean
 	/**
-	 * Animate the camera move, forwarded to {@link ResultCamera}. @default true
+	 * Animate the camera move, forwarded to {@link ResultCamera}.
+	 *
+	 * @defaultValue `true`
 	 */
 	animateCamera?: boolean
 	/**
-	 * Source/layer id prefix for the outline. @default "mw-result"
+	 * Source/layer id prefix for the outline.
+	 *
+	 * @defaultValue `"mw-result"`
 	 */
 	outlineID?: string
 	/**
-	 * Marker color. @default the house pink.
+	 * Marker color.
+	 *
+	 * @defaultValue the house pink.
 	 */
 	markerColor?: string
 }

package/lib/map/ResultCamera.tsx

@@ -28,7 +28,9 @@ export interface ResultCameraProps {
 	 */
 	target: MapCameraTarget | null
 	/**
-	 * Whether to animate the move. @default true
+	 * Whether to animate the move.
+	 *
+	 * @defaultValue `true`
 	 */
 	animate?: boolean
 }

package/lib/map/ResultOverlay.tsx

@@ -20,19 +20,27 @@ export interface ResultOverlayProps {
 	 */
 	outline: PlaceGeometry | null
 	/**
-	 * Source/layer id prefix — override to render more than one outline on a map. @default "mw-result"
+	 * Source/layer id prefix — override to render more than one outline on a map.
+	 *
+	 * @defaultValue `"mw-result"`
 	 */
 	id?: string
 	/**
-	 * Fill color. @default the house pink.
+	 * Fill color.
+	 *
+	 * @defaultValue the house pink.
 	 */
 	color?: string
 	/**
-	 * Fill opacity. @default 0.12
+	 * Fill opacity.
+	 *
+	 * @defaultValue `0.12`
 	 */
 	fillOpacity?: number
 	/**
-	 * Outline stroke width (px). @default 2
+	 * Outline stroke width (px).
+	 *
+	 * @defaultValue `2`
 	 */
 	lineWidth?: number
 }

package/lib/map/VersionPicker.tsx

@@ -22,7 +22,7 @@ export interface VersionPickerProps {
 	 */
 	disabled?: boolean
 	/**
-	 * @default "Model version"
+	 * @defaultValue `"Model version"`
 	 */
 	label?: string
 }

package/lib/map/fake-runtime.ts

@@ -58,9 +58,7 @@ export function makeFakeGeocoderRuntime(overrides: Partial<GeocoderRuntime> = {}
 		],
 		selectedVersion: "v7.2.0",
 		selectVersion: () => {},
-		activeBackend: "webgpu (28 MB int8)",
-		forceWASM: false,
-		setForceWASM: () => {},
+		activeBackend: "wasm (28 MB int8)",
 
 		resolveMapPlace: (candidate): ResolvedMapPlace => ({
 			...candidate,
@@ -86,17 +84,48 @@ export function makeFakeParseResult(input = "350 5th Ave, New York, NY 10118"):
 		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 },
+			{ tag: "locality", value: "New York", confidence: 0.71, start: null, end: null },
 		],
 		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 },
+		resolved: {
+			id: 85_977_539,
+			name: "New York",
+			placetype: "locality",
+			lat: 40.7128,
+			lon: -74.006,
+			score: 0.82,
+			bbox: null,
+			tier: null,
+			uncertaintyM: null,
+		},
 		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 },
+			{
+				id: 85_977_539,
+				name: "New York",
+				placetype: "locality",
+				lat: 40.7128,
+				lon: -74.006,
+				score: 0.82,
+				bbox: null,
+				tier: null,
+				uncertaintyM: null,
+			},
+			{
+				id: 101_715_829,
+				name: "New York",
+				placetype: "region",
+				lat: 43,
+				lon: -75,
+				score: 0.55,
+				bbox: null,
+				tier: null,
+				uncertaintyM: null,
+			},
 		],
 		fstActive: true,
 		fstProvenance: { builtAt: "2026-07-01T00:00:00Z", stateCount: 51, placeCount: 94_000, importanceMatches: 12_000 },
+		dualRoles: null,
 	}
 }
 

package/lib/map/map-debug.ts

@@ -18,7 +18,9 @@ export interface DebugControlBaseOptions {
 	 */
 	className?: string
 	/**
-	 * Where MapLibre docks the control. @default "bottom-left"
+	 * Where MapLibre docks the control.
+	 *
+	 * @defaultValue `"bottom-left"`
 	 */
 	position?: ControlPosition
 }