@mailwoman/react 10.0.0 → 10.1.0

package/lib/poi/usePOISearch.ts

@@ -2,11 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `usePOISearch` — the headless core of the POI explorer. Owns the taxonomy-runtime load, the
- *   debounced classify → subject → OverpassQL derivation, and the "Search live" state machine. The
- *   runtime loader and the live-search probe are both INJECTABLE, so stories/tests drive it with mocks
- *   and no network or db. Presentation is entirely the caller's concern.
  */
 
 import { matchPOISubject } from "@mailwoman/kind-classifier"
@@ -19,58 +14,73 @@ import { useDebouncedValue } from "#common/useDebouncedValue"
 import { loadPOIRuntime } from "#poi/runtime"
 import type { LiveSearchState, LoadPOIRuntime, POIExplorerResult, POILiveSearch, POIRuntime } from "#poi/types"
 
+/**
+ * Options for {@link usePOISearch}.
+ */
 export interface UsePOISearchOptions {
 	/**
-	 * The current query text (controlled by the caller).
+	 * The current query text, owned and updated by the caller.
 	 */
 	text: string
+
 	/**
-	 * Runtime loader. @default loadPOIRuntime
+	 * The loader that the hook calls once on mount.
+	 * It defaults to `loadPOIRuntime`.
 	 */
 	loadRuntime?: LoadPOIRuntime
+
 	/**
-	 * Injected live-search probe. Absent ⇒ the live-results affordance is disabled.
+	 * The live-search probe.
+	 * Live search is unavailable when it is absent.
 	 */
 	runLiveSearch?: POILiveSearch
+
 	/**
-	 * Whether the injected probe can serve BRAND subjects (fetch by Wikidata QID). Default false: brand subjects show the
-	 * intent + QID chip but no live-search affordance. The docs' httpvfs probe leaves this off — brand-wide row hydration
-	 * is pathological over byte-range (measured) — so brand live search is a server-side-backend capability. Category
-	 * live search is unaffected either way.
+	 * Whether the probe can search for brand subjects by Wikidata ID, defaulting to
+	 * false. enable it only for a server-side backend, since fetching every row for
+	 * a brand over an HTTP range-request database is too slow.
 	 */
 	brandLiveSearch?: boolean
+
 	/**
-	 * Debounce before (re)classifying. @default 250
+	 * The delay in milliseconds before the text is classified.
+	 * Defaults to 250.
 	 */
 	debounceMs?: number
 }
 
+/**
+ * The state that {@link usePOISearch} returns.
+ */
 export interface UsePOISearch {
 	/**
 	 * True once the taxonomy runtime has loaded.
 	 */
 	runtimeReady: boolean
+
 	/**
-	 * The intent result for the current (debounced) query, or null for empty input.
+	 * The classification for the current debounced text, `null` for empty text
+	 * and while classification is pending.
 	 */
 	result: POIExplorerResult | null
+
 	/**
-	 * State of the on-demand live poi.db search.
+	 * The live-search state for the current debounced text, `idle` until a search runs.
 	 */
 	liveSearch: LiveSearchState
+
 	/**
-	 * Whether a live search can run right now (a probe is wired + there's a resolved subject with an anchor).
+	 * Whether a probe is wired and the subject supports live search with a non-empty place anchor.
 	 */
 	canSearchLive: boolean
+
 	/**
-	 * Kick off a live search for the current subject. No-op when {@link canSearchLive} is false.
+	 * Starts a live search for the current subject.
+	 * It starts no search when `canSearchLive` is false.
 	 */
 	searchLive: () => Promise<void>
 }
 
-/**
- * Compute the OverpassQL export for a matched subject, capturing any emitter error rather than throwing.
- */
 function buildOverpass(
 	runtime: POIRuntime,
 	categoryID: string,
@@ -95,6 +105,12 @@ function buildOverpass(
 	}
 }
 
+/**
+ * Classifies debounced query text as a POI category or brand request and runs live searches on demand.
+ *
+ * Each result is keyed to the query that produced it, live search requires a non-empty anchor.
+ * Brands need `brandLiveSearch` plus a Wikidata ID.
+ */
 export function usePOISearch({
 	text,
 	loadRuntime = loadPOIRuntime,
@@ -103,25 +119,14 @@ export function usePOISearch({
 	debounceMs = 250,
 }: UsePOISearchOptions): UsePOISearch {
 	const [runtime, setRuntime] = useState<POIRuntime | null>(null)
-	/**
-	 * The classify result KEYED BY the query that produced it. The visible result is derived during render
-	 * (`storedResult.query === trimmedText ? … : null`), so a new query invalidates the old answer by derivation — the
-	 * effect never writes state synchronously to "reset", which is the react(set-state-in-effect) shape the lint bump
-	 * rightly flags.
-	 */
+
 	const [storedResult, setStoredResult] = useState<{ query: string; value: POIExplorerResult } | null>(null)
-	/**
-	 * Live-search state, keyed the same way: launched FOR a query, visible only while that query stands.
-	 */
+
 	const [storedLive, setStoredLive] = useState<{ query: string; state: LiveSearchState } | null>(null)
 
 	const debouncedText = useDebouncedValue(text, debounceMs)
 	const trimmedText = debouncedText.trim()
 
-	// The load fires exactly ONCE on mount regardless of whether the caller passes a fresh `loadRuntime`
-	// closure each render (an inline `async () => …` would otherwise retrigger the effect → reload →
-	// re-render loop). `useEffectEvent` reads the LATEST closure without joining the dependency list —
-	// the runtime is a load-once resource.
 	const loadRuntimeEvent = useEffectEvent(() => loadRuntime())
 
 	useEffect(() => {
@@ -138,9 +143,6 @@ export function usePOISearch({
 		}
 	}, [])
 
-	// Classify the debounced query and derive the subject + OverpassQL (async, so it lives in an effect).
-	// Every state write below happens after an await — invalidation on query change is handled by the
-	// key derivation above, not by a synchronous reset here.
 	useEffect(() => {
 		if (!runtime) return
 
@@ -164,8 +166,6 @@ export function usePOISearch({
 				return
 			}
 
-			// Brand subject: the lexicon carries the brand's canonical name as `categoryID` + its Wikidata QID. No category
-			// record, no OverpassQL (brands are searched by QID against the layer's `brand_wikidata` index, not OSM tags).
 			if ((matched.match.kind ?? "category") === "brand") {
 				setStoredResult({
 					query: trimmed,
@@ -215,16 +215,11 @@ export function usePOISearch({
 		}
 	}, [trimmedText, runtime])
 
-	// Derived visibility: an answer stands only while its query does. A new query reads as null/idle
-	// with no reset write anywhere.
 	const result = storedResult?.query === trimmedText ? storedResult.value : null
 	const liveSearch: LiveSearchState = storedLive?.query === trimmedText ? storedLive.state : { status: "idle" }
 
 	const subject = result?.subject
 
-	// A subject is live-searchable when a probe is wired, it has an anchor, and: a CATEGORY that isn't build-local, or a
-	// BRAND with a QID AND a brand-capable probe (`brandLiveSearch`). Brands without a QID / without a brand probe show
-	// the intent + QID chip but no live affordance.
 	const subjectLiveCapable =
 		subject !== undefined &&
 		(subject.kind === "brand" ? brandLiveSearch && subject.wikidata !== undefined : !subject.buildLocal)
@@ -251,7 +246,7 @@ export function usePOISearch({
 						}
 					: {
 							categoryID: subject.category.id,
-							// Fan the canonical seed id out over its Overture leaves — the same translation the Node reader uses.
+
 							overtureCategoryIDs: runtime.lookup.resolveOvertureCategories(subject.category.id),
 							anchor: subject.remainder,
 						}

package/lib/poi.ts

@@ -0,0 +1,39 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file POI explorer components, hooks, runtime and interfaces.
+ */
+
+export { AbstainPanel } from "./poi/AbstainPanel.tsx"
+export type { AbstainPanelProps } from "./poi/AbstainPanel.tsx"
+export { LiveResultsBlock } from "./poi/LiveResultsBlock.tsx"
+export type { LiveResultsBlockProps } from "./poi/LiveResultsBlock.tsx"
+export { OverpassBlock } from "./poi/OverpassBlock.tsx"
+export type { OverpassBlockProps } from "./poi/OverpassBlock.tsx"
+export { POIExplorer } from "./poi/POIExplorer.tsx"
+export type { POIExplorerProps } from "./poi/POIExplorer.tsx"
+export { QueryInput } from "./poi/QueryInput.tsx"
+export type { QueryInputProps } from "./poi/QueryInput.tsx"
+export { formatDistance, loadPOIRuntime, POI_DEFAULT_TEXT, POI_PRESETS } from "#poi/runtime"
+export { SubjectPanel } from "./poi/SubjectPanel.tsx"
+export type { SubjectPanelProps } from "./poi/SubjectPanel.tsx"
+
+export type {
+	CategoryRecord,
+	LiveSearchState,
+	LoadPOIRuntime,
+	POIBrandSubject,
+	POICategorySubject,
+	POIExplorerResult,
+	POILiveSearch,
+	POILiveSearchResult,
+	POIRuntime,
+	POISearchHit,
+	POISubject,
+	POISubjectBase,
+	TaxonomyLookup,
+} from "#poi/types"
+
+export { usePOISearch } from "#poi/usePOISearch"
+export type { UsePOISearch, UsePOISearchOptions } from "#poi/usePOISearch"

package/lib/runtime/useReleaseRuntime.ts

@@ -2,172 +2,195 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `useReleaseRuntime` — the headless load-orchestration hook shared by every mailwoman browser surface (the
- *   inline doc-embeds via `RuntimeEmbed`, and the geocoder). It owns the version-selection state
- *   machine, the per-version load SEQUENCING, cancellation, and the ready / loading / error state — but
- *   NOTHING model- or map-specific. The actual asset fetchers (the ONNX classifier factory, the httpvfs
- *   WOF opener, the FST fetch, the releases.json fetch) are INJECTED by the host as async functions, so
- *   this module imports only React: no `onnxruntime-web`, no `sql.js-httpvfs`, no `maplibre-gl`, no
- *   `fetch`-specific plumbing. That keeps it node-import-safe and root-exportable from
- *   `@mailwoman/react` — the exact interface `PipelineRuntime` established, generalized to the loader itself.
- *
- *   The hook is generic over `TAssets` (the opaque bundle the host's `loadAssets` returns — classifier,
- *   FST, WOF lookup, calibrator, …) and `TRelease` (the host's release-manifest entry). The package
- *   never inspects either; it just holds, reveals, and re-loads them across version/backend switches.
  */
 
 import { useCallback, useEffect, useMemo, useRef, useState } from "react"
 
 /**
- * The minimal contract a release-manifest entry must satisfy. Hosts extend this with their own fields.
+ * The minimal fields of a release-manifest entry.
+ * Hosts can add their own fields.
  */
 export interface ReleaseBase {
-	/**
-	 * The version tag this entry describes (matched against `selectedVersion`).
-	 */
 	version: string
+
 	/**
-	 * Optional display label a version picker shows; falls back to `version`.
+	 * The version picker's display label, falling back to `version`.
 	 */
 	label?: string
 }
 
 /**
- * The releases manifest the host fetches — the default version plus the selectable release entries.
+ * The releases manifest that the host fetches.
  */
 export interface ReleaseManifest<TRelease extends ReleaseBase = ReleaseBase> {
 	/**
-	 * The version selected on first load (before the user picks another).
+	 * The version that the hook selects when the manifest first loads.
 	 */
 	defaultVersion: string
-	/**
-	 * Every selectable release.
-	 */
+
 	releases: TRelease[]
 }
 
 /**
- * The progress channel handed to the host's `loadAssets`. The host reports load progress + the resolved backend + the
- * staged step labels/index THROUGH these setters (all no-op once the load is superseded/aborted), while the hook owns
- * the terminal state (revealing the assets + clearing progress on success, surfacing the error on failure).
+ * The abort signal and progress setters that the hook passes to a host's `loadAssets`.
+ *
+ * The setters stop affecting state after abort or supersession.
+ * The hook sets the final ready or error state.
  */
 export interface AssetsLoadContext {
 	/**
-	 * Aborts when this load is superseded (version/backend switch) or the provider unmounts.
+	 * The signal aborts when a version or backend switch supersedes this load or when the component unmounts.
 	 */
 	signal: AbortSignal
+
 	/**
-	 * Whether the host should force the CPU/WASM backend (opt out of WebGPU) for this load.
+	 * Whether this load should use the CPU WASM backend instead of WebGPU.
 	 */
 	forceWASM: boolean
+
 	/**
-	 * Set the human-readable progress line (e.g. `Loading v7 model (~28 MB)…`).
+	 * Sets the progress line, such as `Loading v7 model (~28 MB)…`.
 	 */
 	setProgress: (progress: string) => void
-	/**
-	 * Set the staged-loader step labels (e.g. `["Loading classifier", "Loading FST gazetteer"]`).
-	 */
+
 	setStepLabels: (labels: string[]) => void
+
 	/**
-	 * Advance the staged-loader step index (0-based).
+	 * Sets the zero-based index of the current loader step.
 	 */
 	setStepIndex: (index: number) => void
+
 	/**
-	 * Report the backend the neural runtime resolved to (e.g. `webgpu (27 MB int8)`).
+	 * Reports the backend that the neural runtime resolved to, such as `webgpu (27 MB int8)`.
 	 */
 	setBackend: (backend: string) => void
+
+	/**
+	 * Reports the fraction of the current download received so far, in [0, 1], or `null`
+	 * when no download is in progress or the response declares no length.
+	 *
+	 * The step index cannot show it because the model is fetched before the first step begins.
+	 */
+	setByteFraction: (fraction: number | null) => void
 }
 
 /**
- * The injected loaders the hook orchestrates. Nothing here is model- or map-aware — the host owns all that.
+ * The host's manifest loader, asset loader and optional asset disposer for {@link useReleaseRuntime}.
  */
 export interface ReleaseRuntimeConfig<TAssets, TRelease extends ReleaseBase = ReleaseBase> {
 	/**
-	 * Fetch + normalize the releases manifest. Returns `null` when no manifest is available (the surface then shows
-	 * nothing selectable). Rejecting surfaces `errorMessage`. Runs once on mount.
+	 * Fetches the releases manifest once on mount.
+	 *
+	 * It returns `null` when the manifest is unavailable.
+	 * The hook reports a rejection through `errorMessage`.
 	 */
 	loadManifest: (signal: AbortSignal) => Promise<ReleaseManifest<TRelease> | null>
+
 	/**
-	 * Load the full asset bundle for one release — the classifier, FST, WOF lookup, calibrator, whatever the host needs.
-	 * Runs on every version or `forceWASM` change. Report progress via `ctx`; return the bundle. Rejecting surfaces
-	 * `errorMessage`. Bail early when `ctx.signal.aborted` — the hook discards a superseded result regardless.
+	 * 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.
 	 */
 	loadAssets: (release: TRelease, ctx: AssetsLoadContext) => Promise<TAssets>
+
+	/**
+	 * Releases resources the garbage collector does not own, such as an ONNX
+	 * session's WASM heap or a GPU buffer.
+	 *
+	 * The hook calls it when replacing a bundle.
+	 * It also calls it if a bundle resolves after abort or when unmounting.
+	 *
+	 * Without this function, each reload leaves the model resident.
+	 */
+	disposeAssets?: (assets: TAssets) => void | Promise<void>
+
 	/**
-	 * The progress line shown before the manifest arrives. @default "Loading releases…"
+	 * The progress line shown before the manifest arrives.
+	 * Defaults to `Loading releases…`.
 	 */
 	initialProgress?: string
 }
 
 /**
- * The state `useReleaseRuntime` produces — the load-orchestration state a surface renders + re-projects.
+ * The release-loading state that {@link useReleaseRuntime} returns.
  *
- * This is the LOADER STATE, deliberately distinct from {@link GeocoderRuntime} (the injected runtime contract
- * `<Geocoder>` consumes). A host builds a {@link GeocoderRuntime} by pairing this loader state (assets + backend +
- * version) with the map surface (style, overlays, bias, parse) — see the map subpath's `GeocoderRuntime`.
+ * A host pairs it with its map surface to build a `GeocoderRuntime`.
  */
 export interface ReleaseLoaderState<TAssets, TRelease extends ReleaseBase = ReleaseBase> {
 	/**
-	 * The releases manifest, once fetched.
+	 * The releases manifest, `null` until it loads or when none is available.
 	 */
 	manifest: ReleaseManifest<TRelease> | null
+
 	/**
-	 * The currently-selected version, or `null` before the manifest resolves.
+	 * The selected version, `null` before the manifest loads.
 	 */
 	selectedVersion: string | null
+
 	/**
-	 * The release entry matching `selectedVersion` (convenience over `manifest.releases.find`).
+	 * The manifest entry that matches `selectedVersion`, or `null` when none matches.
 	 */
 	selectedRelease: TRelease | null
+
 	/**
-	 * The loaded asset bundle for the selected version, or `null` while (re)loading.
+	 * The asset bundle for the selected version, `null` while it loads.
 	 */
 	assets: TAssets | null
-	/**
-	 * Whether the asset bundle is loaded and ready to use.
-	 */
+
 	ready: boolean
+
 	/**
-	 * Human-readable load progress (`""` when idle/ready).
+	 * The load progress line, empty once loading finishes or fails.
 	 */
 	loadingProgress: string
+
 	/**
-	 * Staged-loader step index (0-based; `-1` before the first step).
+	 * The zero-based loader step index, `-1` before the first step.
 	 */
 	loadingStepIndex: number
+
+	loadingStepLabels: string[]
+
 	/**
-	 * Staged-loader step labels.
+	 * The fraction of the current download received so far, in [0, 1], or `null`
+	 * when no download is in progress or the length is unknown.
 	 */
-	loadingStepLabels: string[]
+	loadingByteFraction: number | null
+
 	/**
-	 * A load error (manifest or asset), distinct from any per-parse error a consumer tracks separately.
+	 * A manifest or asset load error, separate from any parse error a consumer tracks.
 	 */
 	errorMessage: string | null
+
 	/**
-	 * The backend the neural runtime resolved to (e.g. `webgpu (27 MB int8)`), or `""` before it's known.
+	 * The backend the neural runtime resolved to, such as `webgpu (27 MB int8)`;
+	 * it is `""` before the backend is known.
 	 */
 	activeBackend: string
+
 	/**
-	 * Whether the CPU/WASM backend is currently forced.
+	 * Whether the CPU WASM backend is forced instead of WebGPU.
 	 */
 	forceWASM: boolean
+
 	/**
-	 * Switch to a different version (clears any error, then reloads the asset bundle).
+	 * Switches to another version, clearing any error and reloading the asset bundle.
 	 */
 	selectVersion: (version: string) => void
+
 	/**
-	 * Force (or unforce) the CPU/WASM backend — reloads the asset bundle.
+	 * Forces or releases the CPU WASM backend.
+	 * Either change reloads the asset bundle.
 	 */
 	setForceWASM: (forceWASM: boolean) => void
 }
 
 /**
- * Drive the shared version → asset-bundle load state machine over a host-injected loader.
+ * Loads the release manifest on mount and the selected release's assets whenever
+ * the version or `forceWASM` changes.
  *
- * Sequence: on mount `loadManifest` runs and its `defaultVersion` becomes the selection; each version (or `forceWASM`)
- * change reloads the bundle via `loadAssets`, the previous load aborted first. The assets are revealed ATOMICALLY when
- * `loadAssets` resolves (so `ready` flips exactly once per load), and consumers wait on `ready`.
+ * Each reload aborts the previous load and disposes the old assets.
+ * `ready` becomes true after the new assets load.
  */
 export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = ReleaseBase>(
 	config: ReleaseRuntimeConfig<TAssets, TRelease>
@@ -182,25 +205,24 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 	const [loadingStepLabels, setLoadingStepLabels] = useState<string[]>([])
 	const [errorMessage, setErrorMessage] = useState<string | null>(null)
 	const [activeBackend, setActiveBackend] = useState<string>("")
+	const [loadingByteFraction, setLoadingByteFraction] = useState<number | null>(null)
 	const [forceWASM, setForceWASMState] = useState(false)
 
-	// Latest-ref the injected loaders: a host that re-creates them each render (an inline arrow) must NOT retrigger the
-	// load effects, which key ONLY on version/backend. The effects read `.current` at run time.
 	const loadManifestRef = useRef(config.loadManifest)
 	const loadAssetsRef = useRef(config.loadAssets)
+	const disposeAssetsRef = useRef(config.disposeAssets)
+
+	const liveAssetsRef = useRef<TAssets | null>(null)
 
-	// Latest manifest for the version-load effect, so it can resolve the release WITHOUT depending on `manifest`
-	// identity — which would double-fire the load the instant the manifest first arrives (the selection transition
-	// null → defaultVersion already fires it once).
 	const manifestRef = useRef<ReleaseManifest<TRelease> | null>(null)
 
 	useEffect(() => {
 		loadManifestRef.current = config.loadManifest
 		loadAssetsRef.current = config.loadAssets
+		disposeAssetsRef.current = config.disposeAssets
 		manifestRef.current = manifest
-	}, [config.loadAssets, config.loadManifest, manifest])
+	}, [config.disposeAssets, config.loadAssets, config.loadManifest, manifest])
 
-	// Mount: fetch the manifest, then select the default version.
 	useEffect(() => {
 		const controller = new AbortController()
 
@@ -223,7 +245,6 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 		return () => controller.abort()
 	}, [])
 
-	// Load the per-version asset bundle when the version (or the backend force) changes.
 	useEffect(() => {
 		if (!selectedVersion) return
 
@@ -242,10 +263,19 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 
 		void (async () => {
 			try {
+				const outgoing = liveAssetsRef.current
+
+				liveAssetsRef.current = null
+
+				if (outgoing) {
+					await disposeAssetsRef.current?.(outgoing)
+				}
+
 				setAssets(null)
 				setLoadingStepIndex(-1)
 				setLoadingStepLabels([])
 				setActiveBackend("")
+				setLoadingByteFraction(null)
 
 				const ctx: AssetsLoadContext = {
 					signal,
@@ -254,13 +284,21 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 					setStepLabels: (labels) => guard(() => setLoadingStepLabels(labels)),
 					setStepIndex: (index) => guard(() => setLoadingStepIndex(index)),
 					setBackend: (backend) => guard(() => setActiveBackend(backend)),
+					setByteFraction: (fraction) => guard(() => setLoadingByteFraction(fraction)),
 				}
 
 				const loaded = await loadAssetsRef.current(release, ctx)
 
-				if (signal.aborted) return
+				if (signal.aborted) {
+					await disposeAssetsRef.current?.(loaded)
+
+					return
+				}
+
+				liveAssetsRef.current = loaded
 				setAssets(loaded)
 				setLoadingProgress("")
+				setLoadingByteFraction(null)
 			} catch (error) {
 				if (signal.aborted) return
 				setErrorMessage(error instanceof Error ? error.message : String(error))
@@ -271,6 +309,18 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 		return () => controller.abort()
 	}, [selectedVersion, forceWASM])
 
+	useEffect(() => {
+		return () => {
+			const live = liveAssetsRef.current
+
+			liveAssetsRef.current = null
+
+			if (live) {
+				void disposeAssetsRef.current?.(live)
+			}
+		}
+	}, [])
+
 	const selectVersion = useCallback((version: string) => {
 		setSelectedVersion(version)
 		setErrorMessage(null)
@@ -292,6 +342,7 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 		loadingProgress,
 		loadingStepIndex,
 		loadingStepLabels,
+		loadingByteFraction,
 		errorMessage,
 		activeBackend,
 		forceWASM,