@mailwoman/react 9.1.0 → 9.3.0

package/{map → lib/map}/usePlaceAutocomplete.ts

@@ -15,10 +15,10 @@
  *   the presentational {@link PlaceAutocomplete} listbox renders `suggestions` / `activeIndex`.
  */
 
-import { type KeyboardEvent, useCallback, useEffect, useRef, useState } from "react"
+import { type KeyboardEvent, useCallback, useEffect, useState } from "react"
 
-import { useDebouncedValue } from "../common/useDebouncedValue.ts"
-import type { Suggestion } from "./types.ts"
+import { useDebouncedValue } from "#common/useDebouncedValue"
+import type { Suggestion } from "#map/types"
 
 export interface UsePlaceAutocompleteOptions {
 	/**
@@ -95,6 +95,12 @@ export interface UsePlaceAutocomplete {
 }
 
 const LISTBOX_ID = "mw-demo-suggest-list"
+
+/**
+ * Stable empty list for the derived no-suggestions state — a fresh `[]` per render would churn the identity every
+ * consumer and every useCallback dependency list sees.
+ */
+const NO_SUGGESTIONS: Suggestion[] = []
 const optionID = (index: number) => `mw-demo-suggest-${index}`
 
 /**
@@ -118,30 +124,33 @@ export function usePlaceAutocomplete({
 	minChars = 2,
 	debounceMs = 150,
 }: UsePlaceAutocompleteOptions): UsePlaceAutocomplete {
-	const [suggestions, setSuggestions] = useState<Suggestion[]>([])
+	/**
+	 * The last COMPLETED fetch, keyed by the query that produced it. Visibility is DERIVED from this during render rather
+	 * than pushed through sync setStates in the effect — the effect's only job is the async fetch, so every state write
+	 * in it happens after an await and the react(set-state-in-effect) rule is satisfied by structure, not by exception.
+	 */
+	const [fetched, setFetched] = useState<{ query: string; suggestions: Suggestion[] } | null>(null)
+	/**
+	 * The query whose list was dismissed or picked. Suppression as DATA, replacing the one-shot ref flag: a pick stores
+	 * the query the rewritten text will produce, so the post-pick fetch is skipped and the place just chosen is never
+	 * re-suggested. One divergence from the ref version, accepted and small: after Esc, retyping the exact same string
+	 * keeps the list hidden until the query changes.
+	 */
+	const [dismissed, setDismissed] = useState<string | null>(null)
 	const [activeIndex, setActiveIndex] = useState(-1)
-	// One-shot guard: a pick rewrites `text` to the chosen name, which would otherwise re-trigger the fetch and
-	// immediately re-suggest the place just chosen. Set on pick, consumed by the next effect run.
-	const suppressRef = useRef(false)
 
 	const query = localitySegment(text)
 	const debouncedQuery = useDebouncedValue(query, debounceMs)
 
-	useEffect(() => {
-		if (suppressRef.current) {
-			suppressRef.current = false
-			setSuggestions([])
-			setActiveIndex(-1)
+	const eligible = Boolean(autocomplete) && debouncedQuery.length >= minChars && !/^\d/.test(debouncedQuery)
 
-			return
-		}
+	const suggestions =
+		eligible && fetched?.query === debouncedQuery && dismissed !== debouncedQuery ? fetched.suggestions : NO_SUGGESTIONS
 
-		if (!autocomplete || debouncedQuery.length < minChars || /^\d/.test(debouncedQuery)) {
-			setSuggestions([])
-			setActiveIndex(-1)
+	useEffect(() => {
+		if (!autocomplete || debouncedQuery.length < minChars || /^\d/.test(debouncedQuery)) return
 
-			return
-		}
+		if (dismissed === debouncedQuery) return
 
 		let cancelled = false
 
@@ -150,11 +159,11 @@ export function usePlaceAutocomplete({
 				const next = await autocomplete(debouncedQuery)
 
 				if (cancelled) return
-				setSuggestions(next)
+				setFetched({ query: debouncedQuery, suggestions: next })
 				setActiveIndex(-1)
 			} catch {
 				if (cancelled) return
-				setSuggestions([])
+				setFetched({ query: debouncedQuery, suggestions: [] })
 				setActiveIndex(-1)
 			}
 		})()
@@ -162,22 +171,25 @@ export function usePlaceAutocomplete({
 		return () => {
 			cancelled = true
 		}
-	}, [debouncedQuery, autocomplete, minChars])
+	}, [debouncedQuery, autocomplete, minChars, dismissed])
 
 	const pick = useCallback(
 		(value: string) => {
-			suppressRef.current = true
-			setText(replaceSegment(text, value))
-			setSuggestions([])
+			const next = replaceSegment(text, value)
+
+			setText(next)
+			// Suppress the fetch the rewritten text would trigger — the segment being typed IS the picked name.
+			setDismissed(localitySegment(next))
+			setFetched(null)
 			setActiveIndex(-1)
 		},
 		[text, setText]
 	)
 
 	const dismiss = useCallback(() => {
-		setSuggestions([])
+		setDismissed(debouncedQuery)
 		setActiveIndex(-1)
-	}, [])
+	}, [debouncedQuery])
 
 	const onInputKeyDown = useCallback(
 		(event: KeyboardEvent<HTMLInputElement>) => {

package/{pipeline → lib/pipeline}/CandidatePicker.tsx

@@ -9,8 +9,8 @@
 
 import type { ReactNode } from "react"
 
-import { cx } from "../common/cx.ts"
-import type { ResolvedPlaceView } from "./types.ts"
+import { cx } from "#common/cx"
+import type { ResolvedPlaceView } from "#pipeline/types"
 
 export interface CandidatePickerProps {
 	candidates: ResolvedPlaceView[]

package/{pipeline → lib/pipeline}/ComponentTable.tsx

@@ -8,8 +8,9 @@
 
 import type { ReactNode } from "react"
 
+import type { ParsedComponent } from "#pipeline/types"
+
 import { ConfidenceCell } from "./ConfidenceCell.tsx"
-import type { ParsedComponent } from "./types.ts"
 
 export interface ComponentTableProps {
 	nodes: ParsedComponent[]

package/{pipeline → lib/pipeline}/ConfidenceCell.tsx

@@ -7,7 +7,7 @@
  *   at 0.8 / 0.5. Presentational.
  */
 
-import { cx } from "../common/cx.ts"
+import { cx } from "#common/cx"
 
 /**
  * At or above this the cell is drawn as high-confidence. Presentation only — see docs/src/shared/confidence-tiers.ts.

package/{pipeline → lib/pipeline}/PipelineExplorer.tsx

@@ -11,6 +11,11 @@
 
 import type { ReactNode } from "react"
 
+import { buildParsePayload } from "#pipeline/copy"
+import { PIPELINE_DEFAULT_ADDRESS, PIPELINE_PRESETS } from "#pipeline/presets"
+import type { PipelinePanels, PipelineRuntime } from "#pipeline/types"
+import { useParsePipeline } from "#pipeline/useParsePipeline"
+
 import { ClientOnly } from "../common/ClientOnly.tsx"
 import { CopyButton } from "../common/CopyButton.tsx"
 import { KindBadge } from "../common/KindBadge.tsx"
@@ -18,12 +23,8 @@ import { LoadingIndicator } from "../common/LoadingIndicator.tsx"
 import { PresetChips, type Preset } from "../common/PresetChips.tsx"
 import { CandidatePicker } from "./CandidatePicker.tsx"
 import { ComponentTable } from "./ComponentTable.tsx"
-import { buildParsePayload } from "./copy.ts"
-import { PIPELINE_DEFAULT_ADDRESS, PIPELINE_PRESETS } from "./presets.ts"
 import { QueryForm } from "./QueryForm.tsx"
 import { ResolvedPlace } from "./ResolvedPlace.tsx"
-import type { PipelinePanels, PipelineRuntime } from "./types.ts"
-import { useParsePipeline } from "./useParsePipeline.ts"
 
 export interface PipelineExplorerProps {
 	/**

package/{pipeline → lib/pipeline}/QueryForm.tsx

@@ -19,11 +19,11 @@ export interface QueryFormProps {
 	busy?: boolean
 	placeholder?: string
 	/**
-	 * Keydown on the input — the seam a combobox (the demo's place-autocomplete) needs for arrow/Enter/Esc nav.
+	 * Keydown on the input — the hook a combobox (the demo's place-autocomplete) needs for arrow/Enter/Esc nav.
 	 */
 	onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void
 	/**
-	 * Escape hatch for extra `<input>` attributes (aria-combobox props, `autoComplete`, …). Merged last.
+	 * Override for extra `<input>` attributes (aria-combobox props, `autoComplete`, …). Merged last.
 	 */
 	inputProps?: InputHTMLAttributes<HTMLInputElement>
 }

package/{pipeline → lib/pipeline}/ResolvedPlace.tsx

@@ -9,7 +9,7 @@
 
 import { Fragment, type ReactNode } from "react"
 
-import type { DualRoleView, ResolvedPlaceView } from "./types.ts"
+import type { DualRoleView, ResolvedPlaceView } from "#pipeline/types"
 
 export interface ResolvedPlaceProps {
 	place: ResolvedPlaceView

package/{pipeline → lib/pipeline}/copy.ts

@@ -7,7 +7,7 @@
  *   pretty-printed. Pure; shared by the explorer's copy button.
  */
 
-import type { ParseResult, ResolvedPlaceView } from "./types.ts"
+import type { ParseResult, ResolvedPlaceView } from "#pipeline/types"
 
 export function buildParsePayload(result: ParseResult, selected: ResolvedPlaceView | null): string {
 	return JSON.stringify(

package/{pipeline → lib/pipeline}/presets.ts

@@ -30,6 +30,7 @@ export const PIPELINE_PRESETS: ReadonlyArray<Preset> = [
 	{ label: "Space Needle", value: "400 Broad St, Seattle, WA 98109", country: "us" },
 	{ label: "ZIP only", value: "90210", country: "us" },
 	{ label: "Berlin (native order)", value: "Straußstraße 27, 12623 Berlin", country: "de" },
+	{ label: "Berlin city-state (int'l order)", value: "5 Hauptstraße, Berlin, Berlin 10115", country: "de" },
 	{ label: "Paris (street fall-through)", value: "181 Rue du Chevaleret, Paris", country: "fr" },
 	// GB dependent_locality (placetype-pair-prior arc) — "Henbury" flips to dependent_locality via the en-gb pair-index
 	// prior; the UK postcode is also structurally detectable (parity with docs EXAMPLE_ADDRESSES).
@@ -40,7 +41,7 @@ export const PIPELINE_PRESETS: ReadonlyArray<Preset> = [
 	},
 	// NZ dependent_locality (en-nz pair-prior arc) — Plimmerton is a suburb (dependent_locality) of Porirua. Postcode
 	// DELIBERATELY OMITTED: a trailing "Porirua 5026" folds "porirua 5026" in segment mode and misses the index's bare
-	// "porirua" key (tracked as #1308). The `country: "nz"` pin is load-bearing — locale-gate can't structurally detect
+	// "porirua" key (tracked as #1308). The `country: "nz"` pin is required — locale-hint can't structurally detect
 	// NZ (4-digit postcode isn't distinctive), so only the pin selects the nz index; free-typed NZ stays unfired.
 	{ label: "Plimmerton (NZ dependent_locality)", value: "35 Steyne Avenue, Plimmerton, Porirua", country: "nz" },
 ]

package/{pipeline → lib/pipeline}/useParsePipeline.ts

@@ -11,7 +11,7 @@
 
 import { useCallback, useState } from "react"
 
-import type { ParseResult, PipelineRuntime, ResolvedPlaceView } from "./types.ts"
+import type { ParseResult, PipelineRuntime, ResolvedPlaceView } from "#pipeline/types"
 
 export interface UseParsePipelineOptions {
 	runtime: PipelineRuntime

package/{poi → lib/poi}/LiveResultsBlock.tsx

@@ -10,8 +10,8 @@
 
 import type { ReactNode } from "react"
 
-import { formatDistance } from "./runtime.ts"
-import type { LiveSearchState } from "./types.ts"
+import { formatDistance } from "#poi/runtime"
+import type { LiveSearchState } from "#poi/types"
 
 export interface LiveResultsBlockProps {
 	/**

package/{poi → lib/poi}/POIExplorer.tsx

@@ -11,6 +11,10 @@
 
 import { type ReactNode, useState } from "react"
 
+import { POI_DEFAULT_TEXT, POI_PRESETS } from "#poi/runtime"
+import type { LoadPOIRuntime, POILiveSearch } from "#poi/types"
+import { usePOISearch } from "#poi/usePOISearch"
+
 import { ClientOnly } from "../common/ClientOnly.tsx"
 import { KindBadge } from "../common/KindBadge.tsx"
 import { PresetChips, type Preset } from "../common/PresetChips.tsx"
@@ -18,10 +22,7 @@ import { AbstainPanel } from "./AbstainPanel.tsx"
 import { LiveResultsBlock } from "./LiveResultsBlock.tsx"
 import { OverpassBlock } from "./OverpassBlock.tsx"
 import { QueryInput } from "./QueryInput.tsx"
-import { POI_DEFAULT_TEXT, POI_PRESETS } from "./runtime.ts"
 import { SubjectPanel } from "./SubjectPanel.tsx"
-import type { LoadPOIRuntime, POILiveSearch } from "./types.ts"
-import { usePOISearch } from "./usePOISearch.ts"
 
 export interface POIExplorerProps {
 	/**

package/{poi → lib/poi}/SubjectPanel.tsx

@@ -10,7 +10,7 @@
 
 import type { ReactNode } from "react"
 
-import type { POISubject } from "./types.ts"
+import type { POISubject } from "#poi/types"
 
 export interface SubjectPanelProps {
 	subject: POISubject

package/{poi → lib/poi}/runtime.ts

@@ -13,7 +13,7 @@ import { createKindClassifier } from "@mailwoman/kind-classifier"
 import type { POIPhraseLookup } from "@mailwoman/kind-classifier"
 import { createPOIBrandLookup, createPOITaxonomyLookup } from "@mailwoman/poi-taxonomy/table"
 
-import type { POIRuntime } from "./types.ts"
+import type { POIRuntime } from "#poi/types"
 
 /**
  * Build the POI runtime, dynamically importing the taxonomy + brand JSON so the tables land in their own chunk. A
@@ -31,8 +31,8 @@ export async function loadPOIRuntime(): Promise<POIRuntime> {
 		import("@mailwoman/poi-taxonomy/data/brands.json").then((m) => m.default),
 	])
 
-	const lookup = createPOITaxonomyLookup(table as unknown as Parameters<typeof createPOITaxonomyLookup>[0])
-	const brands = createPOIBrandLookup(brandTable as unknown as Parameters<typeof createPOIBrandLookup>[0])
+	const lookup = createPOITaxonomyLookup(table as Parameters<typeof createPOITaxonomyLookup>[0])
+	const brands = createPOIBrandLookup(brandTable as Parameters<typeof createPOIBrandLookup>[0])
 
 	// Adapt the taxonomy + brand lookups to the `POIPhraseLookup` shape the classifier expects: categories first, brands
 	// on a category miss.

package/{poi → lib/poi}/types.ts

@@ -5,7 +5,7 @@
  *
  *   Types for the POI explorer. The intent path (classification → subject → OverpassQL) is fully
  *   self-contained over the pure `@mailwoman/*` packages; the live poi.db path is expressed only as an
- *   INJECTED async function ({@link POILiveSearch}) so the httpvfs/worker machinery stays out of this
+ *   INJECTED async function ({@link POILiveSearch}) so the httpvfs/worker implementation stays out of this
  *   package's browser graph (it lives in the docs site, which knows where the layer is served).
  */
 

package/{poi → lib/poi}/usePOISearch.ts

@@ -13,11 +13,11 @@ import { matchPOISubject } from "@mailwoman/kind-classifier"
 import { emitOverpassQL } from "@mailwoman/poi-taxonomy/overpass"
 import type { OverpassIntentLike } from "@mailwoman/poi-taxonomy/overpass"
 import { computeQueryShape } from "@mailwoman/query-shape"
-import { useCallback, useEffect, useRef, useState } from "react"
+import { useCallback, useEffect, useEffectEvent, useState } from "react"
 
-import { useDebouncedValue } from "../common/useDebouncedValue.ts"
-import { loadPOIRuntime } from "./runtime.ts"
-import type { LiveSearchState, LoadPOIRuntime, POIExplorerResult, POILiveSearch, POIRuntime } from "./types.ts"
+import { useDebouncedValue } from "#common/useDebouncedValue"
+import { loadPOIRuntime } from "#poi/runtime"
+import type { LiveSearchState, LoadPOIRuntime, POIExplorerResult, POILiveSearch, POIRuntime } from "#poi/types"
 
 export interface UsePOISearchOptions {
 	/**
@@ -84,12 +84,12 @@ function buildOverpass(
 	}
 
 	const intent: OverpassIntentLike = {
-		subject: { kind: "category", categoryID, matched: matchedPhrase },
+		subject: { kind: "category", categoryIDs: [categoryID], matched: matchedPhrase },
 		...(remainder ? { anchor: { text: remainder } } : {}),
 	}
 
 	try {
-		return { overpassQL: emitOverpassQL(intent, category.osmTag ? { osmTag: category.osmTag } : {}) }
+		return { overpassQL: emitOverpassQL(intent, category.osmTag ? { osmTags: [category.osmTag] } : {}) }
 	} catch (error) {
 		return { overpassError: error instanceof Error ? error.message : String(error) }
 	}
@@ -103,21 +103,31 @@ export function usePOISearch({
 	debounceMs = 250,
 }: UsePOISearchOptions): UsePOISearch {
 	const [runtime, setRuntime] = useState<POIRuntime | null>(null)
-	const [result, setResult] = useState<POIExplorerResult | null>(null)
-	const [liveSearch, setLiveSearch] = useState<LiveSearchState>({ status: "idle" })
+	/**
+	 * 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()
 
-	// Capture the loader in a ref so 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). The runtime is a load-once resource.
-	const loadRuntimeRef = useRef(loadRuntime)
-	loadRuntimeRef.current = loadRuntime
+	// 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(() => {
 		let cancelled = false
 
-		loadRuntimeRef.current().then((loaded) => {
+		void loadRuntimeEvent().then((loaded) => {
 			if (!cancelled) {
 				setRuntime(loaded)
 			}
@@ -129,20 +139,16 @@ 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
 
-		let cancelled = false
-		const trimmed = debouncedText.trim()
-
-		// A new query invalidates live results from the previous one.
-		setLiveSearch({ status: "idle" })
+		const trimmed = trimmedText
 
-		if (!trimmed) {
-			setResult(null)
+		if (!trimmed) return
 
-			return
-		}
+		let cancelled = false
 
 		const input = { raw: trimmed, normalized: trimmed }
 		const shape = computeQueryShape(trimmed)
@@ -153,7 +159,7 @@ export function usePOISearch({
 			const matched = kindResult.kind === "poi_query" ? matchPOISubject(trimmed, undefined, runtime.lexicon) : null
 
 			if (!matched) {
-				setResult({ kindResult })
+				setStoredResult({ query: trimmed, value: { kindResult } })
 
 				return
 			}
@@ -161,15 +167,18 @@ export function usePOISearch({
 			// 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") {
-				setResult({
-					kindResult,
-					subject: {
-						kind: "brand",
-						name: matched.match.categoryID,
-						...(matched.match.wikidata ? { wikidata: matched.match.wikidata } : {}),
-						matchedPhrase: matched.match.matchedPhrase,
-						confidence: matched.match.confidence,
-						remainder: matched.remainder,
+				setStoredResult({
+					query: trimmed,
+					value: {
+						kindResult,
+						subject: {
+							kind: "brand",
+							name: matched.match.categoryID,
+							...(matched.match.wikidata ? { wikidata: matched.match.wikidata } : {}),
+							matchedPhrase: matched.match.matchedPhrase,
+							confidence: matched.match.confidence,
+							remainder: matched.remainder,
+						},
 					},
 				})
 
@@ -179,29 +188,37 @@ export function usePOISearch({
 			const category = runtime.lookup.getPOICategory(matched.match.categoryID)
 
 			if (!category) {
-				setResult({ kindResult })
+				setStoredResult({ query: trimmed, value: { kindResult } })
 
 				return
 			}
 
-			setResult({
-				kindResult,
-				subject: {
-					kind: "category",
-					category,
-					matchedPhrase: matched.match.matchedPhrase,
-					confidence: matched.match.confidence,
-					remainder: matched.remainder,
-					buildLocal: runtime.lookup.requiresBuildLocalLayer(category),
+			setStoredResult({
+				query: trimmed,
+				value: {
+					kindResult,
+					subject: {
+						kind: "category",
+						category,
+						matchedPhrase: matched.match.matchedPhrase,
+						confidence: matched.match.confidence,
+						remainder: matched.remainder,
+						buildLocal: runtime.lookup.requiresBuildLocalLayer(category),
+					},
+					...buildOverpass(runtime, matched.match.categoryID, matched.match.matchedPhrase, matched.remainder),
 				},
-				...buildOverpass(runtime, matched.match.categoryID, matched.match.matchedPhrase, matched.remainder),
 			})
 		})
 
 		return () => {
 			cancelled = true
 		}
-	}, [debouncedText, runtime])
+	}, [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
 
@@ -221,7 +238,7 @@ export function usePOISearch({
 
 		if (subject.kind === "category" ? subject.buildLocal : !(brandLiveSearch && subject.wikidata)) return
 
-		setLiveSearch({ status: "loading" })
+		setStoredLive({ query: trimmedText, state: { status: "loading" } })
 
 		try {
 			const outcome = await runLiveSearch(
@@ -241,16 +258,25 @@ export function usePOISearch({
 			)
 
 			if (outcome.status === "success") {
-				setLiveSearch({ status: "success", hits: outcome.hits, centerName: outcome.centerName })
+				setStoredLive({
+					query: trimmedText,
+					state: { status: "success", hits: outcome.hits, centerName: outcome.centerName },
+				})
 			} else if (outcome.status === "unplaced") {
-				setLiveSearch({ status: "error", message: `couldn't place "${outcome.anchor}"` })
+				setStoredLive({ query: trimmedText, state: { status: "error", message: `couldn't place "${outcome.anchor}"` } })
 			} else {
-				setLiveSearch({ status: "error", message: "the published POI layer isn't reachable" })
+				setStoredLive({
+					query: trimmedText,
+					state: { status: "error", message: "the published POI layer isn't reachable" },
+				})
 			}
 		} catch {
-			setLiveSearch({ status: "error", message: "the published POI layer isn't reachable" })
+			setStoredLive({
+				query: trimmedText,
+				state: { status: "error", message: "the published POI layer isn't reachable" },
+			})
 		}
-	}, [runLiveSearch, runtime, subject, brandLiveSearch])
+	}, [runLiveSearch, runtime, subject, brandLiveSearch, trimmedText])
 
 	return { runtimeReady: runtime !== null, result, liveSearch, canSearchLive, searchLive }
 }

package/{runtime → lib/runtime}/useDemoRuntime.ts

@@ -10,7 +10,7 @@
  *   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 seam `PipelineRuntime` established, generalized to the loader itself.
+ *   `@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
@@ -169,7 +169,7 @@ export interface DemoLoaderState<TAssets, TRelease extends DemoReleaseBase = Dem
  *
  * 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 gate on `ready`.
+ * `loadAssets` resolves (so `ready` flips exactly once per load), and consumers wait on `ready`.
  */
 export function useDemoRuntime<TAssets, TRelease extends DemoReleaseBase = DemoReleaseBase>(
 	config: DemoRuntimeConfig<TAssets, TRelease>
@@ -189,15 +189,18 @@ export function useDemoRuntime<TAssets, TRelease extends DemoReleaseBase = DemoR
 	// 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)
-	loadManifestRef.current = config.loadManifest
 	const loadAssetsRef = useRef(config.loadAssets)
-	loadAssetsRef.current = config.loadAssets
 
 	// 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<DemoManifest<TRelease> | null>(null)
-	manifestRef.current = manifest
+
+	useEffect(() => {
+		loadManifestRef.current = config.loadManifest
+		loadAssetsRef.current = config.loadAssets
+		manifestRef.current = manifest
+	}, [config.loadAssets, config.loadManifest, manifest])
 
 	// Mount: fetch the manifest, then select the default version.
 	useEffect(() => {

package/out/common/ClientOnly.d.ts

@@ -8,8 +8,11 @@
  *   Remix, Docusaurus). It renders `fallback` on the server and the first client paint, then swaps to
  *   `children()` once mounted — keeping timers, clipboard, and dynamic imports off the server render.
  *
- *   The mount flag is derived from a `useEffect` that fires only in the browser; this is a legitimate
- *   external-sync effect (bridging the server/client rendering boundary), not derived state.
+ *   The mount flag comes from `useSyncExternalStore` with a constant snapshot pair — `false` on the
+ *   server, `true` in the browser — which is the store-shaped statement of exactly this boundary. The
+ *   earlier `useState(false)` + `useEffect(() => setMounted(true))` said the same thing with a
+ *   render-cascade the react(set-state-in-effect) rule rightly flags: the second render was the
+ *   mechanism, not an accident, and the store form gets the same second paint without a set-state.
  */
 import { type ReactNode } from "react";
 export interface ClientOnlyProps {

package/out/common/ClientOnly.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClientOnly.d.ts","sourceRoot":"","sources":["../../common/ClientOnly.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAuB,MAAM,OAAO,CAAA;AAE3D,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,QAAQ,EAAE,MAAM,SAAS,CAAA;IACzB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;CACpB;AAED,wBAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,QAAe,EAAE,EAAE,eAAe,GAAG,SAAS,CAMpF"}
+{"version":3,"file":"ClientOnly.d.ts","sourceRoot":"","sources":["../../lib/common/ClientOnly.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAwB,MAAM,OAAO,CAAA;AAS5D,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,QAAQ,EAAE,MAAM,SAAS,CAAA;IACzB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;CACpB;AAED,wBAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,QAAe,EAAE,EAAE,eAAe,GAAG,SAAS,CAQpF"}

package/out/common/ClientOnly.js

@@ -8,13 +8,21 @@
  *   Remix, Docusaurus). It renders `fallback` on the server and the first client paint, then swaps to
  *   `children()` once mounted — keeping timers, clipboard, and dynamic imports off the server render.
  *
- *   The mount flag is derived from a `useEffect` that fires only in the browser; this is a legitimate
- *   external-sync effect (bridging the server/client rendering boundary), not derived state.
+ *   The mount flag comes from `useSyncExternalStore` with a constant snapshot pair — `false` on the
+ *   server, `true` in the browser — which is the store-shaped statement of exactly this boundary. The
+ *   earlier `useState(false)` + `useEffect(() => setMounted(true))` said the same thing with a
+ *   render-cascade the react(set-state-in-effect) rule rightly flags: the second render was the
+ *   mechanism, not an accident, and the store form gets the same second paint without a set-state.
  */
-import { useEffect, useState } from "react";
+import { useSyncExternalStore } from "react";
+/**
+ * The boundary never changes after mount, so nothing ever notifies.
+ */
+function subscribeNever() {
+    return () => { };
+}
 export function ClientOnly({ children, fallback = null }) {
-    const [mounted, setMounted] = useState(false);
-    useEffect(() => setMounted(true), []);
+    const mounted = useSyncExternalStore(subscribeNever, () => true, () => false);
     return mounted ? children() : fallback;
 }
 //# sourceMappingURL=ClientOnly.js.map

package/out/common/ClientOnly.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClientOnly.js","sourceRoot":"","sources":["../../common/ClientOnly.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAkB,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAa3D,MAAM,UAAU,UAAU,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,EAAmB;IACxE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IAE7C,SAAS,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAA;IAErC,OAAO,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAA;AACvC,CAAC"}
+{"version":3,"file":"ClientOnly.js","sourceRoot":"","sources":["../../lib/common/ClientOnly.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAkB,oBAAoB,EAAE,MAAM,OAAO,CAAA;AAE5D;;GAEG;AACH,SAAS,cAAc;IACtB,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;AAChB,CAAC;AAaD,MAAM,UAAU,UAAU,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,EAAmB;IACxE,MAAM,OAAO,GAAG,oBAAoB,CACnC,cAAc,EACd,GAAG,EAAE,CAAC,IAAI,EACV,GAAG,EAAE,CAAC,KAAK,CACX,CAAA;IAED,OAAO,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAA;AACvC,CAAC"}