@mailwoman/react 9.2.0 → 9.4.0

package/README.md

@@ -10,7 +10,7 @@ Two composed explorers, plus the small presentational units and headless hooks t
 - **`POIExplorer`** — a self-contained POI-intent tester (classify → subject → OverpassQL). The intent
   path runs entirely offline over `@mailwoman/kind-classifier`, `@mailwoman/poi-taxonomy`, and
   `@mailwoman/query-shape` — no weights, no network. A live poi.db search is opt-in via an injected
-  `runLiveSearch` probe, so the httpvfs/worker machinery never enters this package's graph.
+  `runLiveSearch` probe, so the httpvfs/worker implementation never enters this package's graph.
 - **`PipelineExplorer`** — a parse + resolve tester driven by an **injected `PipelineRuntime`**. The
   host supplies `runParse` (compute shape → classify → resolve) and the heavy visualizers as `panels`,
   keeping onnxruntime-web, sql.js-httpvfs, and node builtins out of this package entirely.

package/fonts.css

@@ -0,0 +1,59 @@
+/**
+ * The brand typeface, served from the same origin every app already preconnects to.
+ *
+ * Six faces, not the twenty the family ships. Each `@font-face` is a network fetch on first paint, and the token
+ * layer binds only these: regular and medium for running text, bold where a heading or a chip needs weight, italic
+ * for a caption, and two mono weights for the `code`, `number` and `glyph` roles. Iosevka provides no 600, so
+ * `--font-weight-semibold: 600` matches the 700 face by the CSS weight-matching rules rather than being synthesized.
+ *
+ * A rule never names a family here — it names a scale role from `tokens.css`, which names one of the five face
+ * roles. Replacing the typeface is an edit to `--font-family-*` in `styleframe.config.ts` plus this file.
+ */
+
+@font-face {
+	font-family: "Iosevka Nexus Web";
+	font-display: swap;
+	font-weight: 400;
+	font-style: normal;
+	src: url("https://public.mailwoman.ai/fonts/IoveskaNexus/WOFF2/IosevkaNexus-Regular.woff2") format("woff2");
+}
+
+@font-face {
+	font-family: "Iosevka Nexus Web";
+	font-display: swap;
+	font-weight: 450;
+	font-style: normal;
+	src: url("https://public.mailwoman.ai/fonts/IoveskaNexus/WOFF2/IosevkaNexus-Book.woff2") format("woff2");
+}
+
+@font-face {
+	font-family: "Iosevka Nexus Web";
+	font-display: swap;
+	font-weight: 700;
+	font-style: normal;
+	src: url("https://public.mailwoman.ai/fonts/IoveskaNexus/WOFF2/IosevkaNexus-Bold.woff2") format("woff2");
+}
+
+@font-face {
+	font-family: "Iosevka Nexus Web";
+	font-display: swap;
+	font-weight: 400;
+	font-style: italic;
+	src: url("https://public.mailwoman.ai/fonts/IoveskaNexus/WOFF2/IosevkaNexus-Italic.woff2") format("woff2");
+}
+
+@font-face {
+	font-family: "Iosevka Nexus Mono Web";
+	font-display: swap;
+	font-weight: 400;
+	font-style: normal;
+	src: url("https://public.mailwoman.ai/fonts/IosevkaNexusMono/WOFF2/IosevkaNexusMono-Regular.woff2") format("woff2");
+}
+
+@font-face {
+	font-family: "Iosevka Nexus Mono Web";
+	font-display: swap;
+	font-weight: 450;
+	font-style: normal;
+	src: url("https://public.mailwoman.ai/fonts/IosevkaNexusMono/WOFF2/IosevkaNexusMono-Book.woff2") format("woff2");
+}

package/lib/common/About.tsx

@@ -0,0 +1,89 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `About` — the collapsible explainer for the browser geocoder: the neural model, the confidence colours, the
+ *   gazetteer resolver, the byte-range database and the FST prior. Prose about the product a host places above or
+ *   beside the geocoder; it renders nothing live.
+ */
+
+import type { ReactNode } from "react"
+
+export function About(): ReactNode {
+	return (
+		<details className="mw-about">
+			<summary className="mw-about__summary">
+				<span className="mw-about__icon">ℹ️</span>
+				About this geocoder
+			</summary>
+			<div className="mw-about__body">
+				<section className="mw-about__section">
+					<h3 className="mw-about__heading">Neural model</h3>
+					<p>
+						A ~29M-parameter BERT-style encoder classifies each token into one of 33 BIO labels covering 16 address
+						components (street, house number, unit, locality, region, postcode, venue, country, intersection, etc.). It
+						runs entirely in your browser via <strong>onnxruntime-web</strong> (WebGPU with WASM SIMD fallback). The
+						model ships as a 37.6 MB int8-quantized ONNX bundle; fp32 weights are also available for higher accuracy.
+					</p>
+				</section>
+
+				<section className="mw-about__section">
+					<h3 className="mw-about__heading">Confidence colors</h3>
+					<p>
+						Every classified span carries a confidence score between 0 and 1. The colors in the results table give you a
+						quick visual read:
+					</p>
+					<ul className="mw-about__legend">
+						<li className="mw-about__item">
+							<span className="mw-about__swatch mw-about__swatch--high" />
+							<strong>Green</strong> (≥ 0.8) — high confidence. The model is nearly certain.
+						</li>
+						<li className="mw-about__item">
+							<span className="mw-about__swatch mw-about__swatch--mid" />
+							<strong>Amber</strong> (0.5–0.8) — moderate confidence. Worth verifying.
+						</li>
+						<li className="mw-about__item">
+							<span className="mw-about__swatch mw-about__swatch--low" />
+							<strong>Red</strong> (&lt; 0.5) — low confidence. The model is unsure — likely wrong.
+						</li>
+					</ul>
+					<p>
+						These are raw model scores. For calibrated probabilities, the library ships a per-locale isotonic calibrator
+						(<code>calibration.json</code>) that maps the raw scores to well-calibrated probability estimates.
+					</p>
+				</section>
+
+				<section className="mw-about__section">
+					<h3 className="mw-about__heading">WOF resolver</h3>
+					<p>
+						After classification, the resolver queries a <strong>Who&apos;s On First</strong> (WOF) SQLite gazetteer to
+						match the parsed components — locality, region, and postcode — against real-world places with coordinates.
+						The cascade tries postcode first (most precise), then locality, then the raw input text. The result is a
+						sorted list of candidate places with WOF IDs, placetypes, lat/lon, and bounding boxes.
+					</p>
+				</section>
+
+				<section className="mw-about__section">
+					<h3 className="mw-about__heading">Byte-range gazetteer</h3>
+					<p>
+						The gazetteer is a multi-gigabyte SQLite file served from a public bucket. It loads via{" "}
+						<strong>sql.js-httpvfs</strong>, which range-requests only the pages a lookup touches, so your browser
+						fetches a few hundred kilobytes per session instead of the whole file.
+					</p>
+				</section>
+
+				<section className="mw-about__section">
+					<h3 className="mw-about__heading">FST prior</h3>
+					<p>
+						A <strong>finite-state transducer</strong> (FST) built from ~94K US place names runs before the neural
+						classifier. It pre-annotates known locality, region, and postcode spans in the input — places like
+						&quot;Springfield&quot; or &quot;Cook County&quot; that the FST can match exactly. These &quot;FST
+						prior&quot; hits feed the classifier as strong hints, improving locality and region recall on addresses
+						where the neural model alone might miss them. The FST is active whenever the selected release includes it.
+					</p>
+				</section>
+			</div>
+		</details>
+	)
+}

package/{common → lib/common}/CopyButton.tsx

@@ -9,7 +9,7 @@
 
 import type { ReactNode } from "react"
 
-import { useClipboard } from "./useClipboard.ts"
+import { useClipboard } from "#common/useClipboard"
 
 export interface CopyButtonProps {
 	/**

package/{common → lib/common}/KindBadge.tsx

@@ -9,16 +9,11 @@
  *   pipeline's projection satisfy it without a hard type dependency.
  */
 
+import type { KindView } from "@mailwoman/core/pipeline/client-result"
 import type { ReactNode } from "react"
 
-export interface KindBadgeResult {
-	kind: string
-	confidence: number
-	alternatives: ReadonlyArray<{ kind: string; confidence: number }>
-}
-
 export interface KindBadgeProps {
-	kindResult: KindBadgeResult
+	kindResult: KindView
 }
 
 const formatPct = (n: number): string => `${Math.round(n * 100)}%`

package/{common → lib/common}/LoadingIndicator.tsx

@@ -11,7 +11,7 @@
 
 import { memo, type ReactNode } from "react"
 
-import { cx } from "./cx.ts"
+import { cx } from "#common/cx"
 
 export type LoadingMode = "pulse" | "spinner" | "staged"
 

package/lib/common/confidence-tiers.ts

@@ -0,0 +1,50 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Confidence banding shared by every component that colours a span by confidence.
+ *
+ *   It is a presentation choice, not a model one: the parser emits a continuous confidence and these
+ *   bounds only decide which colour a span is drawn in, so they live here rather than anywhere the
+ *   pipeline can see them.
+ */
+
+/**
+ * At or above this the span is drawn as high-confidence.
+ */
+export const HIGH_CONFIDENCE_MIN = 0.8
+
+/**
+ * At or above this the span is drawn as medium-confidence; below it, low.
+ */
+export const MID_CONFIDENCE_MIN = 0.5
+
+/**
+ * The banding a component applies to a span's confidence.
+ */
+export type ConfidenceTier = "high" | "mid" | "low"
+
+/**
+ * Bands a continuous confidence into the three tiers the demo styles against.
+ *
+ * @param confidence A parser confidence in `[0, 1]`.
+ *
+ * @returns The tier to style with.
+ */
+export function confidenceTier(confidence: number): ConfidenceTier {
+	if (confidence >= HIGH_CONFIDENCE_MIN) return "high"
+
+	if (confidence >= MID_CONFIDENCE_MIN) return "mid"
+
+	return "low"
+}
+
+/**
+ * {@link confidenceTier} for a possibly-absent confidence: an unmeasured span is drawn as `mid` rather than `low`, so an
+ * older model that emits no confidence never reads as uniformly wrong.
+ */
+export function confidenceTierOrMid(confidence?: number): ConfidenceTier {
+	if (confidence == null) return "mid"
+
+	return confidenceTier(confidence)
+}

package/lib/common/text-tokens.ts

@@ -0,0 +1,88 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Word tokenization + span ownership shared by the word-level visualizers.
+ *
+ *   A word-level panel splits the raw input on whitespace and assigns each word to its most specific
+ *   covering span (the shortest-span owner, the same rule a character-level highlight applies per
+ *   character). Two panels must agree for the BIO labels to line up between them, so the split and
+ *   the owner walk live here.
+ */
+
+export interface WordToken {
+	/**
+	 * The word text as it appears in the input.
+	 */
+	text: string
+	/**
+	 * Leading whitespace before this word.
+	 */
+	whitespace: string
+	/**
+	 * Start offset in the input string.
+	 */
+	start: number
+	/**
+	 * End offset in the input string (exclusive).
+	 */
+	end: number
+}
+
+/**
+ * Tokenize the raw input into words, preserving leading whitespace for each token.
+ */
+export function tokenizeWords(input: string): WordToken[] {
+	const words: WordToken[] = []
+	let i = 0
+
+	// `charAt` answers "" past the end, which no whitespace test matches, so both walks stop at the input's length.
+	while (i < input.length) {
+		let ws = ""
+
+		while (/\s/.test(input.charAt(i))) {
+			ws += input.charAt(i)
+
+			i++
+		}
+
+		if (i >= input.length) break
+		const start = i
+
+		while (i < input.length && !/\s/.test(input.charAt(i))) {
+			i++
+		}
+
+		words.push({ text: input.slice(start, i), start, end: i, whitespace: ws })
+	}
+
+	return words
+}
+
+/**
+ * A half-open `[start, end)` character range into the input.
+ */
+export interface CharSpan {
+	start: number
+	end: number
+}
+
+/**
+ * Per-word index of the most specific (shortest) span covering it, or `-1` when no span overlaps the word. A word is
+ * covered when any part of it falls within the span.
+ */
+export function shortestSpanOwners(words: readonly CharSpan[], spans: readonly CharSpan[]): number[] {
+	return words.map((word) => {
+		let best = -1
+		let bestLen = Infinity
+
+		for (const [s, sp] of spans.entries()) {
+			if (word.start < sp.end && word.end > sp.start && sp.end - sp.start < bestLen) {
+				bestLen = sp.end - sp.start
+				best = s
+			}
+		}
+
+		return best
+	})
+}

package/{index.ts → lib/index.ts}

@@ -21,17 +21,17 @@ export { ClientOnly } from "./common/ClientOnly.tsx"
 export type { ClientOnlyProps } from "./common/ClientOnly.tsx"
 export { CopyButton } from "./common/CopyButton.tsx"
 export type { CopyButtonProps } from "./common/CopyButton.tsx"
-export { cx } from "./common/cx.ts"
-export type { ClassValue } from "./common/cx.ts"
+export { cx } from "#common/cx"
+export type { ClassValue } from "#common/cx"
 export { KindBadge } from "./common/KindBadge.tsx"
-export type { KindBadgeProps, KindBadgeResult } from "./common/KindBadge.tsx"
+export type { KindBadgeProps } from "./common/KindBadge.tsx"
 export { LoadingIndicator } from "./common/LoadingIndicator.tsx"
 export type { LoadingIndicatorProps, LoadingMode } from "./common/LoadingIndicator.tsx"
 export { PresetChips } from "./common/PresetChips.tsx"
 export type { Preset, PresetChipsProps } from "./common/PresetChips.tsx"
-export { useClipboard } from "./common/useClipboard.ts"
-export type { UseClipboard } from "./common/useClipboard.ts"
-export { useDebouncedValue } from "./common/useDebouncedValue.ts"
+export { useClipboard } from "#common/useClipboard"
+export type { UseClipboard } from "#common/useClipboard"
+export { useDebouncedValue } from "#common/useDebouncedValue"
 
 // ── POI explorer ───────────────────────────────────────────────────────────
 export { AbstainPanel } from "./poi/AbstainPanel.tsx"
@@ -44,7 +44,7 @@ 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.ts"
+export { formatDistance, loadPOIRuntime, POI_DEFAULT_TEXT, POI_PRESETS } from "#poi/runtime"
 export { SubjectPanel } from "./poi/SubjectPanel.tsx"
 export type { SubjectPanelProps } from "./poi/SubjectPanel.tsx"
 
@@ -62,10 +62,22 @@ export type {
 	POISubject,
 	POISubjectBase,
 	TaxonomyLookup,
-} from "./poi/types.ts"
+} from "#poi/types"
 
-export { usePOISearch } from "./poi/usePOISearch.ts"
-export type { UsePOISearch, UsePOISearchOptions } from "./poi/usePOISearch.ts"
+export { usePOISearch } from "#poi/usePOISearch"
+export type { UsePOISearch, UsePOISearchOptions } from "#poi/usePOISearch"
+
+// ── Result visualizers ─────────────────────────────────────────────────────
+
+export { About } from "./common/About.tsx"
+export { FailureDiagnostic } from "./pipeline/FailureDiagnostic.tsx"
+export type { FailureDiagnosticProps } from "./pipeline/FailureDiagnostic.tsx"
+export { SpanHighlight } from "./pipeline/SpanHighlight.tsx"
+export type { SpanHighlightProps } from "./pipeline/SpanHighlight.tsx"
+export { TimingPanel } from "./pipeline/TimingPanel.tsx"
+export type { TimingPanelProps } from "./pipeline/TimingPanel.tsx"
+export { TreeView } from "./pipeline/TreeView.tsx"
+export type { TreeViewProps } from "./pipeline/TreeView.tsx"
 
 // ── Pipeline explorer ──────────────────────────────────────────────────────
 export { CandidatePicker } from "./pipeline/CandidatePicker.tsx"
@@ -74,8 +86,8 @@ export { ComponentTable } from "./pipeline/ComponentTable.tsx"
 export type { ComponentTableProps } from "./pipeline/ComponentTable.tsx"
 export { ConfidenceCell } from "./pipeline/ConfidenceCell.tsx"
 export type { ConfidenceCellProps } from "./pipeline/ConfidenceCell.tsx"
-export { buildParsePayload } from "./pipeline/copy.ts"
-export { PIPELINE_DEFAULT_ADDRESS, PIPELINE_PRESETS } from "./pipeline/presets.ts"
+export { buildParsePayload } from "#pipeline/copy"
+export { PIPELINE_DEFAULT_ADDRESS, PIPELINE_PRESETS } from "#pipeline/presets"
 export { PipelineExplorer } from "./pipeline/PipelineExplorer.tsx"
 export type { PipelineExplorerProps } from "./pipeline/PipelineExplorer.tsx"
 export { QueryForm } from "./pipeline/QueryForm.tsx"
@@ -83,46 +95,36 @@ export type { QueryFormProps } from "./pipeline/QueryForm.tsx"
 export { ResolvedPlace } from "./pipeline/ResolvedPlace.tsx"
 export type { ResolvedPlaceProps } from "./pipeline/ResolvedPlace.tsx"
 
-export type {
-	DualRoleView,
-	FSTProvenance,
-	ParsedComponent,
-	ParseResult,
-	PipelineLoadingState,
-	PipelinePanels,
-	PipelineRuntime,
-	ResolvedPlaceView,
-	StageTiming,
-} from "./pipeline/types.ts"
+export type { PipelineLoadingState, PipelinePanels, PipelineRuntime } from "#pipeline/types"
 
-export { useParsePipeline } from "./pipeline/useParsePipeline.ts"
-export type { UseParsePipeline, UseParsePipelineOptions } from "./pipeline/useParsePipeline.ts"
+export { useParsePipeline } from "#pipeline/useParsePipeline"
+export type { UseParsePipeline, UseParsePipelineOptions } from "#pipeline/useParsePipeline"
 
-// ── Demo runtime (shared load orchestration; node-safe — no onnx/httpvfs/maplibre) ──
-export { useDemoRuntime } from "./runtime/useDemoRuntime.ts"
+// ── Release runtime (shared load orchestration; node-safe — no onnx/httpvfs/maplibre) ──
+export { useReleaseRuntime } from "#runtime/useReleaseRuntime"
 
 export type {
-	DemoAssetsLoadContext,
-	DemoLoaderState,
-	DemoManifest,
-	DemoReleaseBase,
-	DemoRuntimeConfig,
-} from "./runtime/useDemoRuntime.ts"
+	AssetsLoadContext,
+	ReleaseBase,
+	ReleaseLoaderState,
+	ReleaseManifest,
+	ReleaseRuntimeConfig,
+} from "#runtime/useReleaseRuntime"
 
 // ── Map (types only from root) ──────────────────────────────────────────────
-// The demo-map SURFACE lives behind the `@mailwoman/react/map` subpath so `maplibre-gl` / `react-map-gl`
+// The map SURFACE lives behind the `@mailwoman/react/map` subpath so `maplibre-gl` / `react-map-gl`
 // (WebGL + DOM at import) never enter the package-root graph — a bare `import("@mailwoman/react")` in node
 // must not pull them. Only the CONTRACT types are re-exported here (fully erased at compile time, so no
-// runtime linkage): the `DemoMap` component + hooks are import-able solely via `@mailwoman/react/map`.
+// runtime linkage): the `MapCanvas` component + hooks are import-able solely via `@mailwoman/react/map`.
 export type {
-	DemoBackend,
-	DemoMapExtraProps,
-	DemoMapProps,
-	DemoMapStyle,
-	DemoRuntime,
-	DemoVersionOption,
+	GeocoderRuntime,
+	InferenceBackend,
 	LngLatTuple,
 	MapBias,
+	MapCanvasExtraProps,
+	MapCanvasProps,
+	MapCanvasStyle,
 	OverlaySpec,
 	Suggestion,
-} from "./map/index.ts"
+	VersionOption,
+} from "#map/index"

package/{map → lib/map}/CompareToggle.tsx

@@ -13,13 +13,13 @@
 
 import type { ReactNode } from "react"
 
-import type { DemoVersionOption } from "./types.ts"
+import type { VersionOption } from "#map/types"
 
 export interface CompareToggleProps {
 	/**
 	 * The selectable model bundles (the primary version is filtered out of the compare list).
 	 */
-	versions: ReadonlyArray<DemoVersionOption>
+	versions: ReadonlyArray<VersionOption>
 	/**
 	 * The primary version, excluded from the compare options.
 	 */