@mailwoman/react 9.3.0 → 10.0.0

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,105 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `About` — the 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 interface AboutProps {
+	/**
+	 * Wrap the prose in its own `<details>` disclosure. Set false where the host is already the disclosure — inside a
+	 * sheet opened by an About button, a summary repeating that button's words is one control too many.
+	 *
+	 * @default true
+	 */
+	collapsible?: boolean
+}
+
+export function About({ collapsible = true }: AboutProps = {}): ReactNode {
+	const body = (
+		<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>
+	)
+
+	if (!collapsible) return body
+
+	return (
+		<details className="mw-about">
+			<summary className="mw-about__summary">
+				<span className="mw-about__icon">ℹ️</span>
+				About this geocoder
+			</summary>
+			{body}
+		</details>
+	)
+}

package/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/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/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Common React primitives.
+ */
+
+export { ClientOnly } from "./ClientOnly.tsx"
+export type { ClientOnlyProps } from "./ClientOnly.tsx"
+export { CopyButton } from "./CopyButton.tsx"
+export type { CopyButtonProps } from "./CopyButton.tsx"
+export { cx } from "#common/cx"
+export type { ClassValue } from "#common/cx"
+export { KindBadge } from "./KindBadge.tsx"
+export type { KindBadgeProps } from "./KindBadge.tsx"
+export { LoadingIndicator } from "./LoadingIndicator.tsx"
+export type { LoadingIndicatorProps, LoadingMode } from "./LoadingIndicator.tsx"
+export { PresetChips } from "./PresetChips.tsx"
+export type { Preset, PresetChipsProps } from "./PresetChips.tsx"
+export { useClipboard } from "#common/useClipboard"
+export type { UseClipboard } from "#common/useClipboard"
+export { useDebouncedValue } from "#common/useDebouncedValue"

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/lib/index.ts

@@ -16,113 +16,20 @@
  *   aware) — no CSS is imported by the component modules, so the bare package import is node-safe.
  */
 
-// ── Common primitives ──────────────────────────────────────────────────────
-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"
-export type { ClassValue } from "#common/cx"
-export { KindBadge } from "./common/KindBadge.tsx"
-export type { KindBadgeProps, KindBadgeResult } 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"
-export type { UseClipboard } from "#common/useClipboard"
-export { useDebouncedValue } from "#common/useDebouncedValue"
+export * from "#common/index"
+export * from "#poi/index"
+export * from "#pipeline/index"
+export * from "#runtime/index"
 
-// ── POI explorer ───────────────────────────────────────────────────────────
-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"
-
-// ── Pipeline explorer ──────────────────────────────────────────────────────
-export { CandidatePicker } from "./pipeline/CandidatePicker.tsx"
-export type { CandidatePickerProps } from "./pipeline/CandidatePicker.tsx"
-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"
-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"
-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"
-
-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"
-
-export type {
-	DemoAssetsLoadContext,
-	DemoLoaderState,
-	DemoManifest,
-	DemoReleaseBase,
-	DemoRuntimeConfig,
-} from "#runtime/useDemoRuntime"
-
-// ── Map (types only from root) ──────────────────────────────────────────────
-// The demo-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`.
 export type {
-	DemoBackend,
-	DemoMapExtraProps,
-	DemoMapProps,
-	DemoMapStyle,
-	DemoRuntime,
-	DemoVersionOption,
+	GeocoderRuntime,
+	InferenceBackend,
 	LngLatTuple,
 	MapBias,
+	MapCanvasExtraProps,
+	MapCanvasProps,
+	MapCanvasStyle,
 	OverlaySpec,
 	Suggestion,
+	VersionOption,
 } from "#map/index"

package/lib/map/BackendControl.tsx

@@ -34,13 +34,17 @@ export interface BackendControlProps {
 export function BackendControl({ activeBackend, forceWASM, onForceWASMChange }: BackendControlProps): ReactNode {
 	return (
 		<div className="mw-demo-backend">
+			<span className="mw-map-sheet__label">Inference backend</span>
+
 			{activeBackend ? (
 				<span className="mw-demo-backend__active">
-					Backend: <code>{activeBackend}</code>
+					Running on <code>{activeBackend}</code>
 				</span>
 			) : null}
-			<label className="mw-demo-backend__toggle">
-				<input type="checkbox" checked={forceWASM} onChange={(e) => onForceWASMChange(e.target.checked)} /> Force WASM
+
+			<label className="mw-map-sheet__check mw-demo-backend__toggle">
+				<input type="checkbox" checked={forceWASM} onChange={(event) => onForceWASMChange(event.target.checked)} />
+				Force WASM
 			</label>
 		</div>
 	)

package/lib/map/CompareToggle.tsx

@@ -13,13 +13,13 @@
 
 import type { ReactNode } from "react"
 
-import type { DemoVersionOption } from "#map/types"
+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.
 	 */
@@ -69,8 +69,9 @@ export function CompareToggle({
 
 	return (
 		<div className="mw-demo-compare">
-			<label className="mw-demo-compare__toggle">
-				<input type="checkbox" checked={compareMode} onChange={(e) => onCompareModeChange(e.target.checked)} /> Compare
+			<label className="mw-map-sheet__check mw-demo-compare__toggle">
+				<input type="checkbox" checked={compareMode} onChange={(event) => onCompareModeChange(event.target.checked)} />
+				Compare two model versions
 			</label>
 			{compareMode ? (
 				<div className="mw-demo-control">