@mailwoman/react 0.0.1 → 7.5.0

package/pipeline/useParsePipeline.ts

@@ -0,0 +1,84 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `useParsePipeline` — the headless core of the pipeline explorer. Owns the query text, the
+ *   busy/stage flags, the parse result, and the candidate selection; delegates the actual parse+resolve
+ *   to the injected {@link PipelineRuntime}. No model or gazetteer code lives here — it just drives the
+ *   contract and shapes the UI state.
+ */
+
+import { useCallback, useState } from "react"
+
+import type { ParseResult, PipelineRuntime, ResolvedPlaceView } from "./types.ts"
+
+export interface UseParsePipelineOptions {
+	runtime: PipelineRuntime
+	defaultText: string
+}
+
+export interface UseParsePipeline {
+	text: string
+	setText: (text: string) => void
+	busy: boolean
+	/** 0-based index into `runtime.parseStageLabels`; -1 when idle. */
+	parseStage: number
+	result: ParseResult | null
+	parseError: string | null
+	selectedCandidateIndex: number
+	selectCandidate: (index: number) => void
+	/** The currently-selected candidate (falls back to the first), or null. */
+	selectedCandidate: ResolvedPlaceView | null
+	/** Run a parse for the current text. Safe to bind to a form's `onSubmit`. */
+	submit: () => Promise<void>
+	/** Clear the result (used when a preset replaces the input). */
+	reset: () => void
+}
+
+export function useParsePipeline({ runtime, defaultText }: UseParsePipelineOptions): UseParsePipeline {
+	const [text, setText] = useState(defaultText)
+	const [busy, setBusy] = useState(false)
+	const [parseStage, setParseStage] = useState(-1)
+	const [result, setResult] = useState<ParseResult | null>(null)
+	const [selectedCandidateIndex, setSelectedCandidateIndex] = useState(0)
+	const [parseError, setParseError] = useState<string | null>(null)
+
+	const submit = useCallback(async () => {
+		if (!runtime.ready || busy) return
+
+		setBusy(true)
+		setParseStage(0)
+		setParseError(null)
+
+		try {
+			const parsed = await runtime.runParse(text, { onStage: setParseStage })
+			setSelectedCandidateIndex(0)
+			setResult(parsed)
+		} catch (err) {
+			setParseError(err instanceof Error ? err.message : String(err))
+		} finally {
+			setBusy(false)
+			setParseStage(-1)
+		}
+	}, [runtime, text, busy])
+
+	const reset = useCallback(() => setResult(null), [])
+
+	// Derived during render — no effect needed.
+	const selectedCandidate = result ? (result.candidates[selectedCandidateIndex] ?? result.candidates[0] ?? null) : null
+
+	return {
+		text,
+		setText,
+		busy,
+		parseStage,
+		result,
+		parseError,
+		selectedCandidateIndex,
+		selectCandidate: setSelectedCandidateIndex,
+		selectedCandidate,
+		submit,
+		reset,
+	}
+}

package/poi/AbstainPanel.tsx

@@ -0,0 +1,22 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `AbstainPanel` — shown when the query carries no POI intent (it parses as an address). Names the
+ *   classifier's kind so the abstention is legible. Presentational.
+ */
+
+import type { ReactNode } from "react"
+
+export interface AbstainPanelProps {
+	kind: string
+}
+
+export function AbstainPanel({ kind }: AbstainPanelProps): ReactNode {
+	return (
+		<p className="mw-muted">
+			No POI intent detected — parses as an address (kind <code>{kind}</code>).
+		</p>
+	)
+}

package/poi/LiveResultsBlock.tsx

@@ -0,0 +1,70 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `LiveResultsBlock` — the on-demand live poi.db search affordance: a "Search live" button plus the
+ *   idle / loading / error / results states. Presentational — all behavior comes in via props (the
+ *   `usePOISearch` hook owns the state machine + the injected probe).
+ */
+
+import type { ReactNode } from "react"
+
+import { formatDistance } from "./runtime.ts"
+import type { LiveSearchState } from "./types.ts"
+
+export interface LiveResultsBlockProps {
+	/** Subject label for empty-state copy — a category ("No hospital results near …") or a brand ("No chevron results …"). */
+	subjectLabel: string
+	/** The location anchor the search runs against (empty ⇒ the button is disabled with a hint). */
+	anchor: string
+	state: LiveSearchState
+	onSearch: () => void
+}
+
+export function LiveResultsBlock({ subjectLabel, anchor, state, onSearch }: LiveResultsBlockProps): ReactNode {
+	const hasAnchor = anchor.trim().length > 0
+
+	return (
+		<div className="mw-live">
+			<div className="mw-panel__header">
+				<h3>Live results</h3>
+				<button
+					type="button"
+					className="mw-btn"
+					onClick={onSearch}
+					disabled={!hasAnchor || state.status === "loading"}
+					title={hasAnchor ? "Search the published poi.db layer" : 'Needs a location anchor (e.g. "near Springfield")'}
+				>
+					{state.status === "loading" ? "Searching…" : "Search live"}
+				</button>
+			</div>
+
+			{!hasAnchor ? (
+				<p className="mw-muted">Add a location anchor (e.g. "near Springfield") to search live.</p>
+			) : state.status === "error" ? (
+				<p className="mw-error">{state.message}</p>
+			) : state.status === "success" ? (
+				state.hits.length === 0 ? (
+					<p className="mw-muted">
+						No {subjectLabel.toLowerCase()} results near {state.centerName}.
+					</p>
+				) : (
+					<>
+						<p className="mw-live__caption">Near {state.centerName}, ranked by distance:</p>
+						<ul className="mw-live__results">
+							{state.hits.map((hit, i) => (
+								<li key={`${hit.name}-${i}`}>
+									<span className="mw-live__name">{hit.name}</span>
+									<span className="mw-live__meta">
+										{formatDistance(hit.distanceM)} · {hit.country}
+									</span>
+								</li>
+							))}
+						</ul>
+					</>
+				)
+			) : null}
+		</div>
+	)
+}

package/poi/OverpassBlock.tsx

@@ -0,0 +1,37 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `OverpassBlock` — the OverpassQL export panel: a header with a copy button and the query in a code
+ *   block. Renders the emitter error instead when the export failed. Presentational.
+ */
+
+import type { ReactNode } from "react"
+
+import { CopyButton } from "../common/CopyButton.tsx"
+
+export interface OverpassBlockProps {
+	overpassQL?: string
+	overpassError?: string
+}
+
+export function OverpassBlock({ overpassQL, overpassError }: OverpassBlockProps): ReactNode {
+	if (overpassQL) {
+		return (
+			<div className="mw-overpass">
+				<div className="mw-panel__header">
+					<h3>OverpassQL export</h3>
+					<CopyButton value={overpassQL} className="mw-btn" />
+				</div>
+				<pre className="mw-overpass__code">
+					<code>{overpassQL}</code>
+				</pre>
+			</div>
+		)
+	}
+
+	if (overpassError) return <p className="mw-error">{overpassError}</p>
+
+	return null
+}

package/poi/POIExplorer.tsx

@@ -0,0 +1,133 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `POIExplorer` — the composed POI-intent tester. Detects a POI subject in free text, shows the
+ *   category + OverpassQL export, and (when a live-search probe is injected) searches the published
+ *   poi.db layer. The intent path is self-contained — no weights, no network. All runtime concerns are
+ *   in {@link usePOISearch}; this file is composition + a `ClientOnly` SSR boundary.
+ */
+
+import { type ReactNode, useState } from "react"
+
+import { ClientOnly } from "../common/ClientOnly.tsx"
+import { KindBadge } from "../common/KindBadge.tsx"
+import { PresetChips, type Preset } from "../common/PresetChips.tsx"
+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 {
+	/** Query to pre-fill in the input. */
+	defaultText?: string
+	/** Example chips. @default the built-in POI presets */
+	presets?: ReadonlyArray<Preset>
+	/** Override the taxonomy-runtime loader (stories/tests inject a mock). */
+	loadRuntime?: LoadPOIRuntime
+	/** Live poi.db probe. Absent ⇒ intent-only (no live-results affordance). */
+	runLiveSearch?: POILiveSearch
+	/**
+	 * Whether {@link runLiveSearch} can serve BRAND subjects (fetch by QID). Default false: a brand subject shows the
+	 * intent + QID chip but no live block. The docs' httpvfs probe leaves this off (brand-wide byte-range hydration is
+	 * pathological — measured); a server-side backend can enable it.
+	 */
+	brandLiveSearch?: boolean
+}
+
+interface POIExplorerInnerProps extends POIExplorerProps {
+	defaultText: string
+	presets: ReadonlyArray<Preset>
+}
+
+function POIExplorerInner({
+	defaultText,
+	presets,
+	loadRuntime,
+	runLiveSearch,
+	brandLiveSearch,
+}: POIExplorerInnerProps): ReactNode {
+	const [text, setText] = useState(defaultText)
+	const { result, liveSearch, searchLive } = usePOISearch({
+		text,
+		loadRuntime,
+		runLiveSearch,
+		brandLiveSearch,
+	})
+
+	const subject = result?.subject
+	// The live block appears whenever the subject COULD be live-searched with an anchor — i.e. capable minus the
+	// anchor-present requirement (`canSearchLive` also requires an anchor; the block itself renders the "add an anchor"
+	// hint, so it must show one step earlier). Category: not build-local. Brand: brand-capable probe + a QID.
+	const showLiveBlock = Boolean(
+		runLiveSearch &&
+		subject &&
+		(subject.kind === "brand" ? brandLiveSearch && subject.wikidata !== undefined : !subject.buildLocal)
+	)
+
+	return (
+		<div className="mw-poi-explorer">
+			<QueryInput id="mw-poi-input" label="Query" value={text} onChange={setText} placeholder={POI_DEFAULT_TEXT} />
+			<PresetChips presets={presets} onPick={setText} />
+
+			{result ? (
+				<div className="mw-result">
+					<KindBadge kindResult={result.kindResult} />
+
+					{subject ? (
+						<>
+							<SubjectPanel subject={subject} />
+							{subject.kind === "category" ? (
+								<OverpassBlock overpassQL={result.overpassQL} overpassError={result.overpassError} />
+							) : null}
+
+							{showLiveBlock ? (
+								<LiveResultsBlock
+									subjectLabel={subject.kind === "brand" ? subject.name : subject.category.label}
+									anchor={subject.remainder}
+									state={liveSearch}
+									onSearch={searchLive}
+								/>
+							) : null}
+						</>
+					) : (
+						<AbstainPanel kind={result.kindResult.kind} />
+					)}
+				</div>
+			) : null}
+		</div>
+	)
+}
+
+export function POIExplorer({
+	defaultText = POI_DEFAULT_TEXT,
+	presets = POI_PRESETS,
+	loadRuntime,
+	runLiveSearch,
+	brandLiveSearch,
+}: POIExplorerProps): ReactNode {
+	return (
+		<ClientOnly
+			fallback={
+				<div className="mw-poi-explorer">
+					<p>Loading POI tester…</p>
+				</div>
+			}
+		>
+			{() => (
+				<POIExplorerInner
+					defaultText={defaultText}
+					presets={presets}
+					loadRuntime={loadRuntime}
+					runLiveSearch={runLiveSearch}
+					brandLiveSearch={brandLiveSearch}
+				/>
+			)}
+		</ClientOnly>
+	)
+}

package/poi/QueryInput.tsx

@@ -0,0 +1,26 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `QueryInput` — the labelled text field for the POI explorer. Controlled; presentational only.
+ */
+
+import type { ReactNode } from "react"
+
+export interface QueryInputProps {
+	id: string
+	label: string
+	value: string
+	onChange: (value: string) => void
+	placeholder?: string
+}
+
+export function QueryInput({ id, label, value, onChange, placeholder }: QueryInputProps): ReactNode {
+	return (
+		<div className="mw-field">
+			<label htmlFor={id}>{label}</label>
+			<input id={id} type="text" value={value} onChange={(e) => onChange(e.target.value)} placeholder={placeholder} />
+		</div>
+	)
+}

package/poi/SubjectPanel.tsx

@@ -0,0 +1,79 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `SubjectPanel` — renders the detected POI subject. For a CATEGORY: the category chip, the optional
+ *   build-local badge + note. For a BRAND: the brand-name chip + a Wikidata QID chip (linked). Both
+ *   share the match-detail list (matched phrase, confidence, anchor). Presentational.
+ */
+
+import type { ReactNode } from "react"
+
+import type { POISubject } from "./types.ts"
+
+export interface SubjectPanelProps {
+	subject: POISubject
+}
+
+/** The shared match-detail list (matched phrase, confidence, anchor) — identical for category + brand subjects. */
+function MatchDetail({ subject }: SubjectPanelProps): ReactNode {
+	return (
+		<dl className="mw-subject__detail">
+			<dt>matched phrase</dt>
+			<dd>
+				<code>{subject.matchedPhrase}</code>
+			</dd>
+			<dt>confidence</dt>
+			<dd>{Math.round(subject.confidence * 100)}%</dd>
+			<dt>anchor</dt>
+			<dd>{subject.remainder ? subject.remainder : <em>none — global query</em>}</dd>
+		</dl>
+	)
+}
+
+export function SubjectPanel({ subject }: SubjectPanelProps): ReactNode {
+	if (subject.kind === "brand") {
+		return (
+			<>
+				<div className="mw-subject__row">
+					<span className="mw-subject__chip">{subject.name}</span>
+					<span className="mw-subject__badge mw-subject__badge--brand">brand</span>
+					{subject.wikidata ? (
+						<a
+							className="mw-subject__qid"
+							href={`https://www.wikidata.org/wiki/${subject.wikidata}`}
+							target="_blank"
+							rel="noreferrer"
+						>
+							{subject.wikidata}
+						</a>
+					) : null}
+				</div>
+
+				<MatchDetail subject={subject} />
+
+				<p className="mw-subject__note">
+					Matched as a chain brand — resolved by Wikidata QID against the layer's brand index.
+				</p>
+			</>
+		)
+	}
+
+	return (
+		<>
+			<div className="mw-subject__row">
+				<span className="mw-subject__chip">{subject.category.label}</span>
+				{subject.buildLocal ? <span className="mw-subject__badge">build-local</span> : null}
+			</div>
+
+			<MatchDetail subject={subject} />
+
+			{subject.buildLocal ? (
+				<p className="mw-subject__note">
+					Requires the locally-built OSM layer (ODbL) — mailwoman ships the builder, not the data.
+				</p>
+			) : null}
+		</>
+	)
+}

package/poi/runtime.ts

@@ -0,0 +1,78 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The default POI runtime loader + presentation helpers. `loadPOIRuntime` dynamically imports the
+ *   ~2k-record Overture taxonomy snapshot (so bundlers code-split it into its own chunk, fetched only
+ *   when the explorer actually mounts) and wires the kind classifier over it. Pure + browser-safe: no
+ *   network, no DOM — the whole intent path runs offline.
+ */
+
+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"
+
+/**
+ * Build the POI runtime, dynamically importing the taxonomy + brand JSON so the tables land in their own chunk. A
+ * static import would inline the whole snapshot into every consumer's bundle.
+ *
+ * The lexicon unions categories then brands, mirroring the Node runtime's `poiTaxonomyLookup` precedence: a phrase that
+ * matches a taxonomy CATEGORY wins (the curated set); only on a category miss does the chain-brand table fire,
+ * returning a `kind: "brand"` match carrying the brand's canonical name + Wikidata QID. (The Node path also chains
+ * `@mailwoman/variant-aliases` regional slang; the browser tester leaves that out — one fewer package + data table for
+ * a demo, and the QID-keyed brand table already covers the headline brands.)
+ */
+export async function loadPOIRuntime(): Promise<POIRuntime> {
+	const [table, brandTable] = await Promise.all([
+		import("@mailwoman/poi-taxonomy/data/taxonomy.json").then((m) => m.default),
+		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])
+
+	// Adapt the taxonomy + brand lookups to the `POIPhraseLookup` shape the classifier expects: categories first, brands
+	// on a category miss.
+	const lexicon: POIPhraseLookup = (phrase, locale) => {
+		const categoryHits = lookup.lookupPOICategory(phrase, locale)
+
+		if (categoryHits.length > 0) {
+			return categoryHits.map((match) => ({
+				kind: "category",
+				categoryID: match.category.id,
+				matchedPhrase: match.matchedPhrase,
+				confidence: match.confidence,
+			}))
+		}
+
+		return brands.lookupPOIBrand(phrase).map((match) => ({
+			kind: "brand",
+			categoryID: match.brand.name,
+			wikidata: match.brand.wikidata,
+			matchedPhrase: match.matchedPhrase,
+			confidence: match.confidence,
+		}))
+	}
+
+	return { lookup, lexicon, classify: createKindClassifier({ poiLexicon: lexicon }) }
+}
+
+/** Default example queries for the POI explorer — a mix of category, build-local, and chain-brand subjects. */
+export const POI_PRESETS = [
+	{ label: "Drinking fountain", value: "drinking fountain near Springfield" },
+	{ label: "Fire hydrant", value: "fire hydrant" },
+	{ label: "Hospital + address", value: "hospital, 350 5th Ave, New York" },
+	{ label: "Chevron (brand)", value: "chevron near Houston" },
+	{ label: "Applebee's (brand)", value: "applebee's near Chicago" },
+] as const
+
+export const POI_DEFAULT_TEXT = POI_PRESETS[0].value
+
+/** `742 m` under 1 km, `1.9 km` past it — matches the demo's distance captions. */
+export function formatDistance(distanceM: number): string {
+	if (distanceM < 1000) return `${Math.round(distanceM)} m`
+
+	return `${(distanceM / 1000).toFixed(1)} km`
+}

package/poi/types.ts

@@ -0,0 +1,112 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   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
+ *   package's browser graph (it lives in the docs site, which knows where the layer is served).
+ */
+
+import type { POIPhraseLookup, QueryKindResult } from "@mailwoman/kind-classifier"
+import type { createKindClassifier } from "@mailwoman/kind-classifier"
+import type { createPOITaxonomyLookup } from "@mailwoman/poi-taxonomy/table"
+
+export type TaxonomyLookup = ReturnType<typeof createPOITaxonomyLookup>
+export type CategoryRecord = NonNullable<ReturnType<TaxonomyLookup["getPOICategory"]>>
+
+/** The lazily-loaded POI runtime: the taxonomy lookup, the adapted lexicon, and the kind classifier over it. */
+export interface POIRuntime {
+	lookup: TaxonomyLookup
+	lexicon: POIPhraseLookup
+	classify: ReturnType<typeof createKindClassifier>
+}
+
+/** Fields shared by every resolved POI subject, category or brand. */
+export interface POISubjectBase {
+	matchedPhrase: string
+	confidence: number
+	/** The non-subject remainder of the query (the location anchor, e.g. "near Springfield"). */
+	remainder: string
+}
+
+/** A resolved POI subject that names a taxonomy CATEGORY (`cafe`, `hospital`, `drinking fountain`). */
+export interface POICategorySubject extends POISubjectBase {
+	kind: "category"
+	category: CategoryRecord
+	/** Whether this category needs the locally-built OSM (ODbL) layer — precomputed off the runtime. */
+	buildLocal: boolean
+}
+
+/**
+ * A resolved POI subject that names a chain BRAND (`chevron`, `applebee's`). Brands carry a Wikidata QID and are
+ * searched by that QID, NOT by category k-ring — see `@mailwoman/poi-taxonomy`'s brand table + the layer's
+ * `brand_wikidata` index.
+ */
+export interface POIBrandSubject extends POISubjectBase {
+	kind: "brand"
+	/** The brand's canonical display name. */
+	name: string
+	/** Wikidata QID, when the lexicon carried one (`Q319642` = Chevron). Absent ⇒ matched by name alone. */
+	wikidata?: string
+}
+
+/** A resolved POI subject — a taxonomy category or a chain brand — plus its match metadata. */
+export type POISubject = POICategorySubject | POIBrandSubject
+
+/** The intent-only result: the kind verdict plus (when a subject was detected) its OverpassQL export (category only). */
+export interface POIExplorerResult {
+	kindResult: QueryKindResult
+	subject?: POISubject
+	overpassQL?: string
+	overpassError?: string
+}
+
+/** 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
+}
+
+/**
+ * Result of an injected live search. Preserves the original tester's two failure modes — the anchor not resolving vs
+ * the published layer being unreachable — so the UI can word them differently.
+ */
+export type POILiveSearchResult =
+	| { status: "success"; hits: POISearchHit[]; centerName: string }
+	| { status: "unplaced"; anchor: string }
+	| { status: "unavailable" }
+
+/**
+ * The injected live-search function. Given the resolved category (+ its Overture leaf fan-out) and the anchor text, it
+ * probes the published poi.db and returns hits. Absent ⇒ the explorer runs intent-only (no "Search live" button).
+ *
+ * Brand support is ADDITIVE: when the resolved subject is a chain brand, `brandWikidata` carries its QID and the probe
+ * fetches by that QID instead of a category k-ring (`categoryID`/`overtureCategoryIDs` are then the brand name / empty
+ * and unused). The category path is byte-identical to before. A probe that can't serve brands simply leaves brand live
+ * search unwired at the call site (see `usePOISearch`'s `brandLiveSearch` option) — the docs' httpvfs probe does
+ * exactly that, brand-wide row hydration being pathological over byte-range (measured; the brand path is server-side
+ * only).
+ */
+export type POILiveSearch = (params: {
+	categoryID: string
+	overtureCategoryIDs: string[]
+	anchor: string
+	/** Present when the subject is a chain brand — the probe fetches by this QID, not a category k-ring. */
+	brandWikidata?: string
+}) => Promise<POILiveSearchResult>
+
+/** "Search live" state machine. */
+export type LiveSearchState =
+	| { status: "idle" }
+	| { status: "loading" }
+	| { status: "error"; message: string }
+	| { status: "success"; hits: POISearchHit[]; centerName: string }
+
+/** A single-argument runtime loader — injectable so stories/tests can substitute a mock taxonomy. */
+export type LoadPOIRuntime = () => Promise<POIRuntime>