@mailwoman/react 10.1.0 → 10.2.0

package/lib/map/place-render.ts

@@ -29,17 +29,17 @@ export interface ResolvedMapPlace extends ResolvedPlaceView {
 	 * The place's bounding box.
 	 * Postcodes located by an anchor centroid have none.
 	 */
-	bbox?: LatLonBounds
+	bbox: LatLonBounds | null
 
 	/**
 	 * The street-level tier, set only for results from address points or interpolation.
 	 */
-	tier?: PlaceTier
+	tier: PlaceTier | null
 
 	/**
 	 * The uncertainty radius in meters of a street-level result, drawn as a circle when `tier` is set.
 	 */
-	uncertaintyM?: number
+	uncertaintyM: number | null
 
 	/**
 	 * The admin polygon, if the host has already fetched it.

package/lib/map/types.ts

@@ -42,7 +42,7 @@ export interface OverlaySpec {
 	source: SourceSpecification
 	layers: LayerSpecification[]
 	/**
-	 * @default true
+	 * @defaultValue `true`
 	 */
 	visible?: boolean
 	label?: string
@@ -81,11 +81,6 @@ export interface VersionOption {
 	label?: string
 }
 
-/**
- * Which neural backend the geocoder is currently running on.
- */
-export type InferenceBackend = "webgpu" | "wasm"
-
 /**
  * The injected geocoder runtime extends {@link PipelineRuntime} with the map.
  * It also supplies version and backend controls.
@@ -148,17 +143,9 @@ export interface GeocoderRuntime extends PipelineRuntime {
 	 */
 	selectVersion?: (version: string) => void
 	/**
-	 * The backend the neural runtime resolved to (e.g. `webgpu (28 MB int8)`); free-form for the label.
+	 * The neural runtime's backend and model size (e.g. `wasm (28 MB int8)`); free-form for the label.
 	 */
 	activeBackend?: string
-	/**
-	 * Whether the CPU/wasm backend is currently forced (the controlled value for the backend toggle).
-	 */
-	forceWASM?: boolean
-	/**
-	 * Force the wasm backend (opt out of WebGPU), for the backend toggle.
-	 */
-	setForceWASM?: (forceWASM: boolean) => void
 }
 
 /**

package/lib/map/useMapPlaceRender.ts

@@ -14,6 +14,6 @@ import type { MapPlaceRenderSpec, ResolvedMapPlace } from "#map/place-render"
 /**
  * Memoize the render spec for a resolved place; `null` in → `null` out (no geometry to draw).
  */
-export function useMapPlaceRender(place: ResolvedMapPlace | null | undefined): MapPlaceRenderSpec | null {
+export function useMapPlaceRender(place: ResolvedMapPlace | null): MapPlaceRenderSpec | null {
 	return useMemo(() => (place ? computeMapPlaceRenderSpec(place) : null), [place])
 }

package/lib/map/usePlaceAutocomplete.ts

@@ -32,12 +32,12 @@ export interface UsePlaceAutocompleteOptions {
 	autocomplete?: (query: string) => Promise<Suggestion[]>
 
 	/**
-	 * @default 2
+	 * @defaultValue `2`
 	 */
 	minChars?: number
 
 	/**
-	 * @default 150
+	 * @defaultValue `150`
 	 */
 	debounceMs?: number
 }

package/lib/map.ts

@@ -38,7 +38,6 @@ export type {
 	CompareContext,
 	GeocoderPanels,
 	GeocoderRuntime,
-	InferenceBackend,
 	LngLatTuple,
 	MapBias,
 	OverlaySpec,
@@ -67,8 +66,6 @@ export { ResultOverlay } from "./map/ResultOverlay.tsx"
 export type { ResultOverlayProps } from "./map/ResultOverlay.tsx"
 
 // ── Geocoder controls + the composed geocoder ────────────────────────────────
-export { BackendControl } from "./map/BackendControl.tsx"
-export type { BackendControlProps } from "./map/BackendControl.tsx"
 export { CompareToggle } from "./map/CompareToggle.tsx"
 export type { CompareToggleProps } from "./map/CompareToggle.tsx"
 export { Geocoder } from "./map/Geocoder.tsx"

package/lib/pipeline/ConfidenceCell.tsx

@@ -11,7 +11,7 @@ import { confidenceTierOrMid } from "#common/confidence-tiers"
 import { cx } from "#common/cx"
 
 export interface ConfidenceCellProps {
-	confidence?: number
+	confidence?: number | null
 }
 
 export function ConfidenceCell({ confidence }: ConfidenceCellProps) {

package/lib/pipeline/PipelineExplorer.tsx

@@ -32,11 +32,15 @@ export interface PipelineExplorerProps {
 	 */
 	runtime: PipelineRuntime
 	/**
-	 * Address to pre-fill. @default the White House
+	 * Address to pre-fill.
+	 *
+	 * @defaultValue the White House
 	 */
 	defaultAddress?: string
 	/**
-	 * Example chips. @default the built-in address presets
+	 * Example chips.
+	 *
+	 * @defaultValue the built-in address presets
 	 */
 	presets?: ReadonlyArray<Preset>
 	/**
@@ -62,7 +66,6 @@ function PipelineExplorerInner({ runtime, defaultAddress, presets, panels }: Pip
 			{panels.header}
 			{panels.releaseInfo}
 			{panels.versionControl}
-			{panels.backendControl}
 
 			<QueryForm
 				value={text}

package/lib/pipeline/ResolvedPlace.tsx

@@ -12,7 +12,7 @@ import { Fragment, type ReactNode } from "react"
 
 export interface ResolvedPlaceProps {
 	place: ResolvedPlaceView
-	dualRoles?: DualRoleView[]
+	dualRoles?: DualRoleView[] | null
 }
 
 export function ResolvedPlace({ place, dualRoles }: ResolvedPlaceProps): ReactNode {

package/lib/pipeline/TreeView.tsx

@@ -47,7 +47,7 @@ function renderNode(node: TreeNode, path: string): ReactNode {
 }
 
 export function TreeView({ tree }: TreeViewProps): ReactNode {
-	const roots = (tree as { roots?: unknown[] } | null | undefined)?.roots
+	const roots = (tree as { roots?: unknown[] } | null)?.roots
 
 	if (!Array.isArray(roots) || !roots.length) return null
 

package/lib/pipeline/types.ts

@@ -73,10 +73,6 @@ export interface PipelinePanels {
 	 * Model-version selector, wired to the host's bundle state.
 	 */
 	versionControl?: ReactNode
-	/**
-	 * Backend indicator + wasm toggle.
-	 */
-	backendControl?: ReactNode
 	/**
 	 * One-line release blurb.
 	 */

package/lib/poi/POIExplorer.tsx

@@ -30,7 +30,7 @@ export interface POIExplorerProps {
 	/**
 	 * The example chips.
 	 *
-	 * @default POI_PRESETS
+	 * @defaultValue POI_PRESETS
 	 */
 	presets?: ReadonlyArray<Preset>
 	/**
@@ -80,7 +80,7 @@ function POIExplorerInner({
 	const showLiveBlock = Boolean(
 		runLiveSearch &&
 		subject &&
-		(subject.kind === "brand" ? brandLiveSearch && subject.wikidata !== undefined : !subject.buildLocal)
+		(subject.kind === "brand" ? brandLiveSearch && subject.wikidata !== null : !subject.buildLocal)
 	)
 
 	return (
@@ -96,7 +96,10 @@ function POIExplorerInner({
 						<>
 							<SubjectPanel subject={subject} />
 							{subject.kind === "category" ? (
-								<OverpassBlock overpassQL={result.overpassQL} overpassError={result.overpassError} />
+								<OverpassBlock
+									overpassQL={result.overpassQL ?? undefined}
+									overpassError={result.overpassError ?? undefined}
+								/>
 							) : null}
 
 							{showLiveBlock ? (

package/lib/poi/runtime.ts

@@ -34,6 +34,11 @@ export async function loadPOIRuntime(): Promise<POIRuntime> {
 				categoryID: match.category.id,
 				matchedPhrase: match.matchedPhrase,
 				confidence: match.confidence,
+				mechanism: "exact",
+				inputPhrase: phrase,
+				wikidata: null,
+				reading: "preference",
+				countryScope: null,
 			}))
 		}
 
@@ -43,6 +48,10 @@ export async function loadPOIRuntime(): Promise<POIRuntime> {
 			wikidata: match.brand.wikidata,
 			matchedPhrase: match.matchedPhrase,
 			confidence: match.confidence,
+			mechanism: "exact",
+			inputPhrase: phrase,
+			reading: "preference",
+			countryScope: null,
 		}))
 	}
 

package/lib/poi/types.ts

@@ -8,6 +8,7 @@
  */
 
 import type { QueryKindResult } from "@mailwoman/core/pipeline"
+import type { POIDistanceHit } from "@mailwoman/core/resolver"
 import type { POIPhraseLookup, createKindClassifier } from "@mailwoman/kind-classifier"
 import type { createPOITaxonomyLookup } from "@mailwoman/poi-taxonomy/table"
 
@@ -67,9 +68,9 @@ export interface POIBrandSubject extends POISubjectBase {
 	name: string
 	/**
 	 * The brand's Wikidata QID.
-	 * It is absent when the lexicon had no QID for the brand.
+	 * It is `null` when the lexicon had no QID for the brand.
 	 */
-	wikidata?: string
+	wikidata: string | null
 }
 
 /**
@@ -84,22 +85,15 @@ export type POISubject = POICategorySubject | POIBrandSubject
  */
 export interface POIExplorerResult {
 	kindResult: QueryKindResult
-	subject?: POISubject
-	overpassQL?: string
-	overpassError?: string
+	subject: POISubject | null
+	overpassQL: string | null
+	overpassError: string | null
 }
 
 /**
  * One live poi.db hit, as the results list renders it.
  */
-export interface POISearchHit {
-	name: string
-	lat: number
-	lon: number
-	distanceM: number
-	country: string
-	confidence: number
-}
+export type POISearchHit = POIDistanceHit
 
 /**
  * The result of an injected live search.
@@ -112,28 +106,33 @@ export type POILiveSearchResult =
 	| { status: "unplaced"; anchor: string }
 	| { status: "unavailable" }
 
+/**
+ * What a live search looks for near `anchor`: a taxonomy category with its Overture
+ * leaf categories, or a chain brand identified by its Wikidata QID.
+ */
+export type POILiveSearchRequest =
+	| {
+			kind: "category"
+			categoryID: string
+			overtureCategoryIDs: string[]
+			anchor: string
+	  }
+	| {
+			kind: "brand"
+			brandName: string
+			wikidata: string
+			anchor: string
+	  }
+
 /**
  * The injected live-search function.
  *
- * It probes the published poi.db for the resolved category, its Overture leaf
- * categories and the anchor text.
+ * It probes the published poi.db for the request's subject and the anchor text.
  * The explorer runs intent-only when this function is absent.
  *
- * For a brand subject, `brandWikidata` contains the QID and the probe fetches by it.
- * In that case `categoryID` holds the brand name and `overtureCategoryIDs` is empty.
- *
  * A probe that cannot serve brands should leave `usePOISearch`'s `brandLiveSearch` option unset.
  */
-export type POILiveSearch = (params: {
-	categoryID: string
-	overtureCategoryIDs: string[]
-	anchor: string
-	/**
-	 * The brand's Wikidata QID.
-	 * It is present only when the subject is a chain brand.
-	 */
-	brandWikidata?: string
-}) => Promise<POILiveSearchResult>
+export type POILiveSearch = (request: POILiveSearchRequest) => Promise<POILiveSearchResult>
 
 /**
  * The state of a "Search live" request.

package/lib/poi/usePOISearch.ts

@@ -12,7 +12,14 @@ import { useCallback, useEffect, useEffectEvent, useState } from "react"
 
 import { useDebouncedValue } from "#common/useDebouncedValue"
 import { loadPOIRuntime } from "#poi/runtime"
-import type { LiveSearchState, LoadPOIRuntime, POIExplorerResult, POILiveSearch, POIRuntime } from "#poi/types"
+import type {
+	LiveSearchState,
+	LoadPOIRuntime,
+	POIExplorerResult,
+	POILiveSearch,
+	POILiveSearchRequest,
+	POIRuntime,
+} from "#poi/types"
 
 /**
  * Options for {@link usePOISearch}.
@@ -25,7 +32,8 @@ export interface UsePOISearchOptions {
 
 	/**
 	 * The loader that the hook calls once on mount.
-	 * It defaults to `loadPOIRuntime`.
+	 *
+	 * @defaultValue `loadPOIRuntime`
 	 */
 	loadRuntime?: LoadPOIRuntime
 
@@ -44,7 +52,8 @@ export interface UsePOISearchOptions {
 
 	/**
 	 * The delay in milliseconds before the text is classified.
-	 * Defaults to 250.
+	 *
+	 * @defaultValue `250`
 	 */
 	debounceMs?: number
 }
@@ -83,25 +92,26 @@ export interface UsePOISearch {
 
 function buildOverpass(
 	runtime: POIRuntime,
-	categoryID: string,
-	matchedPhrase: string,
-	remainder: string
-): { overpassQL?: string; overpassError?: string } {
+	categoryID: string
+): { overpassQL: string | null; overpassError: string | null } {
 	const category = runtime.lookup.getPOICategory(categoryID)
 
 	if (!category) {
-		return {}
+		return { overpassQL: null, overpassError: null }
 	}
 
 	const intent: OverpassIntentLike = {
-		subject: { kind: "category", categoryIDs: [categoryID], matched: matchedPhrase },
-		...(remainder ? { anchor: { text: remainder } } : {}),
+		subject: { kind: "category", categoryIDs: [categoryID] },
+		anchor: null,
 	}
 
 	try {
-		return { overpassQL: emitOverpassQL(intent, category.osmTag ? { osmTags: [category.osmTag] } : {}) }
+		return {
+			overpassQL: emitOverpassQL(intent, category.osmTag ? { osmTags: [category.osmTag] } : {}),
+			overpassError: null,
+		}
 	} catch (error) {
-		return { overpassError: error instanceof Error ? error.message : String(error) }
+		return { overpassQL: null, overpassError: error instanceof Error ? error.message : String(error) }
 	}
 }
 
@@ -158,10 +168,10 @@ export function usePOISearch({
 		runtime.classify(input, shape).then((kindResult) => {
 			if (cancelled) return
 
-			const matched = kindResult.kind === "poi_query" ? matchPOISubject(trimmed, undefined, runtime.lexicon) : null
+			const matched = kindResult.kind === "poi_query" ? matchPOISubject(trimmed, null, runtime.lexicon) : null
 
 			if (!matched) {
-				setStoredResult({ query: trimmed, value: { kindResult } })
+				setStoredResult({ query: trimmed, value: { kindResult, subject: null, overpassQL: null, overpassError: null } })
 
 				return
 			}
@@ -174,11 +184,13 @@ export function usePOISearch({
 						subject: {
 							kind: "brand",
 							name: matched.match.categoryID,
-							...(matched.match.wikidata ? { wikidata: matched.match.wikidata } : {}),
+							wikidata: matched.match.wikidata || null,
 							matchedPhrase: matched.match.matchedPhrase,
 							confidence: matched.match.confidence,
 							remainder: matched.remainder,
 						},
+						overpassQL: null,
+						overpassError: null,
 					},
 				})
 
@@ -188,7 +200,7 @@ export function usePOISearch({
 			const category = runtime.lookup.getPOICategory(matched.match.categoryID)
 
 			if (!category) {
-				setStoredResult({ query: trimmed, value: { kindResult } })
+				setStoredResult({ query: trimmed, value: { kindResult, subject: null, overpassQL: null, overpassError: null } })
 
 				return
 			}
@@ -205,7 +217,7 @@ export function usePOISearch({
 						remainder: matched.remainder,
 						buildLocal: runtime.lookup.requiresBuildLocalLayer(category),
 					},
-					...buildOverpass(runtime, matched.match.categoryID, matched.match.matchedPhrase, matched.remainder),
+					...buildOverpass(runtime, matched.match.categoryID),
 				},
 			})
 		})
@@ -218,11 +230,10 @@ export function usePOISearch({
 	const result = storedResult?.query === trimmedText ? storedResult.value : null
 	const liveSearch: LiveSearchState = storedLive?.query === trimmedText ? storedLive.state : { status: "idle" }
 
-	const subject = result?.subject
+	const subject = result?.subject ?? null
 
 	const subjectLiveCapable =
-		subject !== undefined &&
-		(subject.kind === "brand" ? brandLiveSearch && subject.wikidata !== undefined : !subject.buildLocal)
+		subject !== null && (subject.kind === "brand" ? brandLiveSearch && subject.wikidata !== null : !subject.buildLocal)
 
 	const canSearchLive = Boolean(
 		runLiveSearch && runtime && subject && subjectLiveCapable && subject.remainder.trim().length > 0
@@ -231,34 +242,37 @@ export function usePOISearch({
 	const searchLive = useCallback(async () => {
 		if (!runLiveSearch || !runtime || !subject || !subject.remainder.trim()) return
 
-		if (subject.kind === "category" ? subject.buildLocal : !(brandLiveSearch && subject.wikidata)) return
+		let request: POILiveSearchRequest
+
+		if (subject.kind === "brand") {
+			if (!brandLiveSearch || !subject.wikidata) return
+			request = { kind: "brand", brandName: subject.name, wikidata: subject.wikidata, anchor: subject.remainder }
+		} else {
+			if (subject.buildLocal) return
+
+			request = {
+				kind: "category",
+				categoryID: subject.category.id,
+				overtureCategoryIDs: runtime.lookup.resolveOvertureCategories(subject.category.id),
+				anchor: subject.remainder,
+			}
+		}
 
 		setStoredLive({ query: trimmedText, state: { status: "loading" } })
 
 		try {
-			const outcome = await runLiveSearch(
-				subject.kind === "brand"
-					? {
-							categoryID: subject.name,
-							overtureCategoryIDs: [],
-							anchor: subject.remainder,
-							brandWikidata: subject.wikidata,
-						}
-					: {
-							categoryID: subject.category.id,
-
-							overtureCategoryIDs: runtime.lookup.resolveOvertureCategories(subject.category.id),
-							anchor: subject.remainder,
-						}
-			)
-
-			if (outcome.status === "success") {
+			const response = await runLiveSearch(request)
+
+			if (response.status === "success") {
+				setStoredLive({
+					query: trimmedText,
+					state: { status: "success", hits: response.hits, centerName: response.centerName },
+				})
+			} else if (response.status === "unplaced") {
 				setStoredLive({
 					query: trimmedText,
-					state: { status: "success", hits: outcome.hits, centerName: outcome.centerName },
+					state: { status: "error", message: `couldn't place "${response.anchor}"` },
 				})
-			} else if (outcome.status === "unplaced") {
-				setStoredLive({ query: trimmedText, state: { status: "error", message: `couldn't place "${outcome.anchor}"` } })
 			} else {
 				setStoredLive({
 					query: trimmedText,

package/lib/poi.ts

@@ -27,6 +27,7 @@ export type {
 	POICategorySubject,
 	POIExplorerResult,
 	POILiveSearch,
+	POILiveSearchRequest,
 	POILiveSearchResult,
 	POIRuntime,
 	POISearchHit,

package/lib/runtime/useReleaseRuntime.ts

@@ -39,15 +39,10 @@ export interface ReleaseManifest<TRelease extends ReleaseBase = ReleaseBase> {
  */
 export interface AssetsLoadContext {
 	/**
-	 * The signal aborts when a version or backend switch supersedes this load or when the component unmounts.
+	 * The signal aborts when a version switch supersedes this load or when the component unmounts.
 	 */
 	signal: AbortSignal
 
-	/**
-	 * Whether this load should use the CPU WASM backend instead of WebGPU.
-	 */
-	forceWASM: boolean
-
 	/**
 	 * Sets the progress line, such as `Loading v7 model (~28 MB)…`.
 	 */
@@ -61,7 +56,7 @@ export interface AssetsLoadContext {
 	setStepIndex: (index: number) => void
 
 	/**
-	 * Reports the backend that the neural runtime resolved to, such as `webgpu (27 MB int8)`.
+	 * Reports the neural runtime's backend and model size, such as `wasm (27 MB int8)`.
 	 */
 	setBackend: (backend: string) => void
 
@@ -87,9 +82,12 @@ export interface ReleaseRuntimeConfig<TAssets, TRelease extends ReleaseBase = Re
 	loadManifest: (signal: AbortSignal) => Promise<ReleaseManifest<TRelease> | null>
 
 	/**
-	 * Loads the asset bundle for one release and reports progress through `ctx`;
-	 * the hook calls it on every version or `forceWASM` change, reports a rejection through
-	 * `errorMessage`, and disposes a result that resolves after `ctx.signal` aborts.
+	 * Loads the asset bundle for one release and reports progress through `ctx`.
+	 *
+	 * The hook calls it on every version change.
+	 * It reports a rejection through `errorMessage`.
+	 *
+	 * It disposes a result that resolves after `ctx.signal` aborts.
 	 */
 	loadAssets: (release: TRelease, ctx: AssetsLoadContext) => Promise<TAssets>
 
@@ -106,7 +104,8 @@ export interface ReleaseRuntimeConfig<TAssets, TRelease extends ReleaseBase = Re
 
 	/**
 	 * The progress line shown before the manifest arrives.
-	 * Defaults to `Loading releases…`.
+	 *
+	 * @defaultValue `"Loading releases…"`
 	 */
 	initialProgress?: string
 }
@@ -163,31 +162,19 @@ export interface ReleaseLoaderState<TAssets, TRelease extends ReleaseBase = Rele
 	errorMessage: string | null
 
 	/**
-	 * The backend the neural runtime resolved to, such as `webgpu (27 MB int8)`;
-	 * it is `""` before the backend is known.
+	 * The neural runtime's backend and model size, such as `wasm (27 MB int8)`;
+	 * it is `""` before the model loads.
 	 */
 	activeBackend: string
 
-	/**
-	 * Whether the CPU WASM backend is forced instead of WebGPU.
-	 */
-	forceWASM: boolean
-
 	/**
 	 * Switches to another version, clearing any error and reloading the asset bundle.
 	 */
 	selectVersion: (version: string) => void
-
-	/**
-	 * Forces or releases the CPU WASM backend.
-	 * Either change reloads the asset bundle.
-	 */
-	setForceWASM: (forceWASM: boolean) => void
 }
 
 /**
- * Loads the release manifest on mount and the selected release's assets whenever
- * the version or `forceWASM` changes.
+ * Loads the release manifest on mount and the selected release's assets whenever the version changes.
  *
  * Each reload aborts the previous load and disposes the old assets.
  * `ready` becomes true after the new assets load.
@@ -206,7 +193,6 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 	const [errorMessage, setErrorMessage] = useState<string | null>(null)
 	const [activeBackend, setActiveBackend] = useState<string>("")
 	const [loadingByteFraction, setLoadingByteFraction] = useState<number | null>(null)
-	const [forceWASM, setForceWASMState] = useState(false)
 
 	const loadManifestRef = useRef(config.loadManifest)
 	const loadAssetsRef = useRef(config.loadAssets)
@@ -279,7 +265,6 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 
 				const ctx: AssetsLoadContext = {
 					signal,
-					forceWASM,
 					setProgress: (progress) => guard(() => setLoadingProgress(progress)),
 					setStepLabels: (labels) => guard(() => setLoadingStepLabels(labels)),
 					setStepIndex: (index) => guard(() => setLoadingStepIndex(index)),
@@ -307,7 +292,7 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 		})()
 
 		return () => controller.abort()
-	}, [selectedVersion, forceWASM])
+	}, [selectedVersion])
 
 	useEffect(() => {
 		return () => {
@@ -326,8 +311,6 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 		setErrorMessage(null)
 	}, [])
 
-	const setForceWASM = useCallback((next: boolean) => setForceWASMState(next), [])
-
 	const selectedRelease = useMemo(
 		() => manifest?.releases.find((r) => r.version === selectedVersion) ?? null,
 		[manifest, selectedVersion]
@@ -345,8 +328,6 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 		loadingByteFraction,
 		errorMessage,
 		activeBackend,
-		forceWASM,
 		selectVersion,
-		setForceWASM,
 	}
 }