@mailwoman/react 9.3.0 → 9.4.0

package/lib/map/types.ts

@@ -3,25 +3,26 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Types for the geocoder-demo map surface. Mirrors the pipeline boundary: the package owns the UI state
- *   machine + the declarative map, while the host injects a {@link DemoRuntime} that owns ONNX / httpvfs
- *   / R2 and the composed map style. {@link DemoRuntime} EXTENDS {@link PipelineRuntime} so the shared
+ *   Types for the geocoder map surface. Mirrors the pipeline boundary: the package owns the UI state
+ *   machine + the declarative map, while the host injects a {@link GeocoderRuntime} that owns ONNX / httpvfs
+ *   / R2 and the composed map style. {@link GeocoderRuntime} EXTENDS {@link PipelineRuntime} so the shared
  *   `runParse` / `parseStageLabels` / `loading` contract is reused, and adds the map-specific surface
  *   (style, overlays, initial center, viewport bias, backend/version selection). Phase 4 adds the
- *   `resolveMapPlace` enricher, the {@link DemoPanels} injection bag, and the {@link DemoCompareContext}.
+ *   `resolveMapPlace` enricher, the {@link GeocoderPanels} injection bag, and the {@link CompareContext}.
  *
  *   The map-spec types are imported type-only from `react-map-gl/maplibre`; nothing here loads maplibre at
- *   runtime, so this module stays node-safe (its concrete-value CONSUMERS — `DemoMap`, `GeocoderDemo` —
+ *   runtime, so this module stays node-safe (its concrete-value CONSUMERS — `MapCanvas`, `Geocoder` —
  *   are the ones behind the `@mailwoman/react/map` subpath).
  */
 
+import type { ParseResult, ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result"
 import type { ReactNode } from "react"
 import type { LayerSpecification, SourceSpecification } from "react-map-gl/maplibre"
 
 import type { LngLat, ResolvedMapPlace } from "#map/place-render"
-import type { ParseResult, PipelineRuntime, ResolvedPlaceView } from "#pipeline/types"
+import type { PipelineRuntime } from "#pipeline/types"
 
-import type { DemoMapStyle } from "./DemoMap.tsx"
+import type { MapCanvasStyle } from "./MapCanvas.tsx"
 
 /**
  * `[longitude, latitude]`.
@@ -92,7 +93,7 @@ export interface Suggestion {
 /**
  * A selectable model bundle (version tag + a display label the picker shows).
  */
-export interface DemoVersionOption {
+export interface VersionOption {
 	/**
 	 * The version tag (e.g. a git tag or model-card version).
 	 */
@@ -104,23 +105,23 @@ export interface DemoVersionOption {
 }
 
 /**
- * Which neural backend the demo is currently running on.
+ * Which neural backend the geocoder is currently running on.
  */
-export type DemoBackend = "webgpu" | "wasm"
+export type InferenceBackend = "webgpu" | "wasm"
 
 /**
- * The injected demo runtime. Extends {@link PipelineRuntime} (shared `runParse` / `parseStageLabels` / `loading` /
- * `ready`) with the map + version/backend surface the demo needs. The host composes `mapStyle` (via cartographer's
+ * The injected geocoder runtime. Extends {@link PipelineRuntime} (shared `runParse` / `parseStageLabels` / `loading` /
+ * `ready`) with the map + version/backend surface the geocoder needs. The host composes `mapStyle` (via cartographer's
  * `StyleSpecificationComposer` + the tile-worker TileJSON), supplies the overlay specs, the initial center (from
  * geolocation), the FST autocomplete, and the calibrator — nothing in the package imports `@mailwoman/cartographer`,
- * `@mailwoman/neural-web`, httpvfs, or Docusaurus.
+ * `@mailwoman/neural`'s web loader, httpvfs, or Docusaurus.
  */
-export interface DemoRuntime extends PipelineRuntime {
+export interface GeocoderRuntime extends PipelineRuntime {
 	// ── Map ────────────────────────────────────────────────────────────────
 	/**
 	 * The composed basemap style (URL or `StyleSpecification`).
 	 */
-	mapStyle: DemoMapStyle
+	mapStyle: MapCanvasStyle
 	/**
 	 * Host-supplied overlays (coverage, race-dots, …).
 	 */
@@ -136,7 +137,7 @@ export interface DemoRuntime extends PipelineRuntime {
 
 	// ── Parse extras layered over PipelineRuntime.runParse ──────────────────
 	/**
-	 * A bias-aware parse. The map demo feeds the current viewport center as a soft prior; when absent the host falls back
+	 * A bias-aware parse. The geocoder feeds the current viewport center as a soft prior; when absent the host falls back
 	 * to the base {@link PipelineRuntime.runParse}. Kept separate so the shared `runParse` contract is unchanged.
 	 */
 	runParseWithBias?: (
@@ -154,9 +155,9 @@ export interface DemoRuntime extends PipelineRuntime {
 	calibrator?: (raw: number) => number | null
 	/**
 	 * Enrich the selected candidate into the richer {@link ResolvedMapPlace} the declarative map render consumes (bbox,
-	 * street tier + uncertainty, a pre-fetched crisp polygon) — the fields that live on the demo's `ResolvedHit` but not
+	 * street tier + uncertainty, a pre-fetched crisp polygon) — the fields that live on the host's `ResolvedHit` but not
 	 * on the shared {@link ResolvedPlaceView}. The host owns this because those extras (and the async polygon fetch in the
-	 * real demo) are host/gazetteer concerns; the package keeps {@link ParseResult} unpolluted. Absent → the candidate
+	 * real runtime) are host/gazetteer concerns; the package keeps {@link ParseResult} unpolluted. Absent → the candidate
 	 * renders as a bare point (marker + a mid-zoom fly-to). Returning `null` also renders nothing.
 	 */
 	resolveMapPlace?: (candidate: ResolvedPlaceView, result: ParseResult) => ResolvedMapPlace | null
@@ -165,7 +166,7 @@ export interface DemoRuntime extends PipelineRuntime {
 	/**
 	 * The selectable model bundles the version picker offers.
 	 */
-	availableVersions?: DemoVersionOption[]
+	availableVersions?: VersionOption[]
 	/**
 	 * The currently-selected model version.
 	 */
@@ -189,9 +190,10 @@ export interface DemoRuntime extends PipelineRuntime {
 }
 
 /**
- * The compare-mode state a {@link DemoPanels.compare} render-prop receives (the second parse itself stays host-side).
+ * The compare-mode state a {@link GeocoderPanels.compare} render-prop receives (the second parse itself stays
+ * host-side).
  */
-export interface DemoCompareContext {
+export interface CompareContext {
 	/**
 	 * The current primary parse result, or `null` before the first submit.
 	 */
@@ -207,12 +209,12 @@ export interface DemoCompareContext {
 }
 
 /**
- * The state a {@link DemoPanels.result} render-prop receives, so a host can render its OWN result block (the docs
+ * The state a {@link GeocoderPanels.result} render-prop receives, so a host can render its OWN result block (a
  * `<ResultPanel>` with its span-highlight / timing / hierarchy / precision detail) in place of the package's default
  * {@link ResultPanel}. Everything the default panel needs is passed through; the candidate-selection state stays owned
- * by the package (`useDemoGeocode`).
+ * by the package (`useGeocode`).
  */
-export interface DemoResultContext {
+export interface ResultContext {
 	/**
 	 * The current parse+resolve result.
 	 */
@@ -232,14 +234,14 @@ export interface DemoResultContext {
 }
 
 /**
- * Host-injected panels for {@link GeocoderDemo}, the map analogue of `PipelinePanels`. Each is an already-rendered
- * `ReactNode` (or a thunk of the parse result / compare state) so the package needs neither the heavy docs visualizers
- * (ModelVisualizer, VersionCompare, AboutDemo, PermalinkButton) nor their data types. Every field is optional — the
- * fake-runtime Storybook stories pass none and still render the whole demo.
+ * Host-injected panels for {@link Geocoder}, the map analogue of `PipelinePanels`. Each is an already-rendered
+ * `ReactNode` (or a thunk of the parse result / compare state) so the package needs neither the heavy host visualizers
+ * (ModelVisualizer, VersionCompare, About, PermalinkButton) nor their data types. Every field is optional — the
+ * fake-runtime Storybook stories pass none and still render the whole geocoder.
  */
-export interface DemoPanels {
+export interface GeocoderPanels {
 	/**
-	 * Rendered at the top of the control panel (e.g. the docs "About this demo").
+	 * Rendered at the top of the control panel (e.g. the host's "About this geocoder").
 	 */
 	header?: ReactNode
 	/**
@@ -251,9 +253,9 @@ export interface DemoPanels {
 	 */
 	footer?: ReactNode
 	/**
-	 * A device-location / proximity-bias control, rendered between the query form and the autocomplete list (the demo's
-	 * "📍 Use my location" row). Host-owned so the geolocation permission + the bias it feeds into the host's
-	 * {@link DemoRuntime.runParseWithBias} stay a host concern.
+	 * A device-location / proximity-bias control, rendered between the query form and the autocomplete list (the "📍 Use
+	 * my location" row). Host-owned so the geolocation permission + the bias it feeds into the host's
+	 * {@link GeocoderRuntime.runParseWithBias} stay a host concern.
 	 */
 	bias?: ReactNode
 	/**
@@ -261,17 +263,17 @@ export interface DemoPanels {
 	 */
 	extras?: (result: ParseResult) => ReactNode
 	/**
-	 * Rendered just above the result block (present or empty). The demo's opt-in display toggles live here — calibrated
+	 * Rendered just above the result block (present or empty). The opt-in display toggles live here — calibrated
 	 * confidence + dev-mode — because the host owns both the toggle state AND the {@link result} / {@link debugDrawer}
 	 * renderers those toggles drive.
 	 */
 	aboveResult?: (context: { result: ParseResult | null }) => ReactNode
 	/**
 	 * Replace the package's default {@link ResultPanel} entirely. When provided, the host renders its own result block
-	 * (the docs `<ResultPanel>` — span highlight, timing, hierarchy, precision detail, calibrated confidences) from the
-	 * {@link DemoResultContext}. Absent → the built-in panel renders.
+	 * (span highlight, timing, hierarchy, precision detail, calibrated confidences) from the {@link ResultContext}. Absent
+	 * → the built-in panel renders.
 	 */
-	result?: (context: DemoResultContext) => ReactNode
+	result?: (context: ResultContext) => ReactNode
 	/**
 	 * Rendered in place of the resolved-place panel when nothing resolved (host's FailureDiagnostic). Ignored when
 	 * {@link result} is set.
@@ -280,7 +282,7 @@ export interface DemoPanels {
 	/**
 	 * The version-compare view — the host renders its own diff from the compare state it owns.
 	 */
-	compare?: (context: DemoCompareContext) => ReactNode
+	compare?: (context: CompareContext) => ReactNode
 	/**
 	 * The model-visualizer / debug drawer, mounted beside the map (host's ModelVisualizer). A render-prop so the host can
 	 * trace the CURRENT result (its input) — the package passes the live parse result; the host decides on its own
@@ -288,7 +290,7 @@ export interface DemoPanels {
 	 */
 	debugDrawer?: (context: { result: ParseResult | null }) => ReactNode
 	/**
-	 * Extra map controls mounted as `<DemoMap>` children (host's DebugControl / LayerToggle via `useControl`).
+	 * Extra map controls mounted as `<MapCanvas>` children (host's DebugControl / LayerToggle via `useControl`).
 	 */
 	mapControls?: ReactNode
 	/**

package/lib/map/{useDemoGeocode.ts → useGeocode.ts}

@@ -3,9 +3,9 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `useDemoGeocode` — the parse+resolve state machine for the geocoder map demo. It REUSES the pipeline's
+ *   `useGeocode` — the parse+resolve state machine for the geocoder map. It REUSES the pipeline's
  *   `useParsePipeline` (text / busy / stage / result / candidate selection) and layers on the two map-only
- *   concerns the demo adds over the base explorer:
+ *   concerns the geocoder adds over the base explorer:
  *
  *     1. Viewport bias — when the runtime exposes `runParseWithBias`, the current map center (read through
  *        an injected `getBias`, itself reading the `MapRef`) rides along as a soft proximity prior. The
@@ -21,15 +21,15 @@
 import { useMemo } from "react"
 
 import type { ResolvedMapPlace } from "#map/place-render"
-import type { DemoRuntime, MapBias } from "#map/types"
+import type { GeocoderRuntime, MapBias } from "#map/types"
 import type { PipelineRuntime } from "#pipeline/types"
 import { useParsePipeline, type UseParsePipeline } from "#pipeline/useParsePipeline"
 
-export interface UseDemoGeocodeOptions {
+export interface UseGeocodeOptions {
 	/**
-	 * The injected demo runtime (extends `PipelineRuntime` with the map + bias surface).
+	 * The injected geocoder runtime (extends `PipelineRuntime` with the map + bias surface).
 	 */
-	runtime: DemoRuntime
+	runtime: GeocoderRuntime
 	/**
 	 * Address to pre-fill.
 	 */
@@ -40,14 +40,14 @@ export interface UseDemoGeocodeOptions {
 	getBias?: () => MapBias | null
 }
 
-export interface UseDemoGeocode extends UseParsePipeline {
+export interface UseGeocode extends UseParsePipeline {
 	/**
 	 * The selected candidate enriched into the map-render shape (bbox / tier / polygon), or `null`.
 	 */
 	mapPlace: ResolvedMapPlace | null
 }
 
-export function useDemoGeocode({ runtime, defaultText, getBias }: UseDemoGeocodeOptions): UseDemoGeocode {
+export function useGeocode({ runtime, defaultText, getBias }: UseGeocodeOptions): UseGeocode {
 	// Bind the viewport bias into a derived `runParse` so `useParsePipeline` is reused unchanged. When the runtime has no
 	// bias-aware parse, pass it straight through.
 	const geoRuntime = useMemo<PipelineRuntime>(() => {

package/lib/pipeline/CandidatePicker.tsx

@@ -7,10 +7,10 @@
  *   Presentational; the selected index is owned by the caller (the pipeline hook).
  */
 
+import type { ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result"
 import type { ReactNode } from "react"
 
 import { cx } from "#common/cx"
-import type { ResolvedPlaceView } from "#pipeline/types"
 
 export interface CandidatePickerProps {
 	candidates: ResolvedPlaceView[]

package/lib/pipeline/ComponentTable.tsx

@@ -6,10 +6,9 @@
  *   `ComponentTable` — the tag / value / confidence table of decoded components. Presentational.
  */
 
+import type { ParsedComponent } from "@mailwoman/core/pipeline/client-result"
 import type { ReactNode } from "react"
 
-import type { ParsedComponent } from "#pipeline/types"
-
 import { ConfidenceCell } from "./ConfidenceCell.tsx"
 
 export interface ComponentTableProps {

package/lib/pipeline/ConfidenceCell.tsx

@@ -3,28 +3,13 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `ConfidenceCell` — a compact confidence bar + value for the component table. Tiers the fill colour
- *   at 0.8 / 0.5. Presentational.
+ *   `ConfidenceCell` — a compact confidence bar + value for the component table. The fill colour follows the shared
+ *   confidence tiers. Presentational.
  */
 
+import { confidenceTierOrMid } from "#common/confidence-tiers"
 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.
- */
-const HIGH_CONFIDENCE_MIN = 0.8
-
-/**
- * At or above this the cell is drawn as medium-confidence; below it, low.
- */
-const MID_CONFIDENCE_MIN = 0.5
-
-function tier(confidence?: number): "high" | "mid" | "low" {
-	if (confidence == null) return "mid"
-
-	return confidence >= HIGH_CONFIDENCE_MIN ? "high" : confidence >= MID_CONFIDENCE_MIN ? "mid" : "low"
-}
-
 export interface ConfidenceCellProps {
 	confidence?: number
 }
@@ -36,7 +21,10 @@ export function ConfidenceCell({ confidence }: ConfidenceCellProps) {
 
 	return (
 		<div className="mw-conf">
-			<div className={cx("mw-conf__bar", `mw-conf__bar--${tier(confidence)}`)} style={{ width: `${pct}%` }} />
+			<div
+				className={cx("mw-conf__bar", `mw-conf__bar--${confidenceTierOrMid(confidence)}`)}
+				style={{ width: `${pct}%` }}
+			/>
 			<span className="mw-conf__value">{confidence.toFixed(2)}</span>
 		</div>
 	)

package/lib/pipeline/FailureDiagnostic.tsx

@@ -0,0 +1,56 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `FailureDiagnostic` — what to say when nothing resolved. It reads the parsed components and names the missing
+ *   piece a person can add (a city, a state), so the answer is a next step rather than "no hit".
+ */
+
+import type { ParsedComponent } from "@mailwoman/core/pipeline/client-result"
+import type { ReactNode } from "react"
+
+export interface FailureDiagnosticProps {
+	nodes: ParsedComponent[]
+}
+
+export function FailureDiagnostic({ nodes }: FailureDiagnosticProps): ReactNode {
+	const hasLocality = nodes.some((n) => n.tag === "locality")
+	const hasPostcode = nodes.some((n) => n.tag === "postcode")
+	const hasRegion = nodes.some((n) => n.tag === "region")
+
+	const hints: string[] = []
+
+	if (!hasLocality && !hasPostcode) {
+		hints.push(
+			"The parser found no city or postcode in this input. Try adding one — e.g. append ', Chicago, IL 60613'."
+		)
+	}
+
+	if (hasPostcode && !hasLocality) {
+		hints.push(
+			"Only a postcode was extracted. WOF ships placeholder coordinates (0, 0) for about 22% of US postcodes, and the cascade drops those."
+		)
+	}
+
+	if (hasLocality && !hasRegion) {
+		hints.push(
+			"No state in the parse. US localities share names across states (Springfield, Portland, …); add a state to disambiguate."
+		)
+	}
+
+	if (!hints.length) {
+		hints.push("The parsed components look reasonable, but the gazetteer does not index this entry.")
+	}
+
+	return (
+		<div className="mw-failure">
+			<h2>No gazetteer hit</h2>
+			<ul>
+				{hints.map((hint, i) => (
+					<li key={i}>{hint}</li>
+				))}
+			</ul>
+		</div>
+	)
+}

package/lib/pipeline/ResolvedPlace.tsx

@@ -7,10 +7,9 @@
  *   optional dual-role note. Presentational.
  */
 
+import type { DualRoleView, ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result"
 import { Fragment, type ReactNode } from "react"
 
-import type { DualRoleView, ResolvedPlaceView } from "#pipeline/types"
-
 export interface ResolvedPlaceProps {
 	place: ResolvedPlaceView
 	dualRoles?: DualRoleView[]
@@ -25,8 +24,22 @@ export function ResolvedPlace({ place, dualRoles }: ResolvedPlaceProps): ReactNo
 				<dd>{place.name}</dd>
 				<dt>placetype</dt>
 				<dd>{place.placetype}</dd>
-				<dt>WOF id</dt>
-				<dd>{place.id}</dd>
+				{place.tier ? (
+					// A street-tier answer is not a gazetteer place: it carries a precision instead of an id.
+					<>
+						<dt>precision</dt>
+						<dd>
+							{place.tier === "address_point"
+								? "📍 exact address point (≤10 m)"
+								: `≈ interpolated · ±${place.uncertaintyM ?? "?"} m`}
+						</dd>
+					</>
+				) : (
+					<>
+						<dt>WOF id</dt>
+						<dd>{place.id}</dd>
+					</>
+				)}
 				<dt>coords</dt>
 				<dd>
 					{place.lat.toFixed(4)}, {place.lon.toFixed(4)}

package/lib/pipeline/SpanHighlight.tsx

@@ -0,0 +1,97 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `SpanHighlight` — a displaCy-style span ribbon over the raw input: each tagged span is a column with the text on
+ *   top, tinted by its confidence tier, and the tag beneath. Gaps (delimiters, unparsed characters) fall through as
+ *   plain text, so a dropped span is visible as a literal break in the colour.
+ */
+
+import type { ParsedComponent } from "@mailwoman/core/pipeline/client-result"
+import type { ReactNode } from "react"
+
+import { confidenceTierOrMid } from "#common/confidence-tiers"
+import { shortestSpanOwners } from "#common/text-tokens"
+
+export interface SpanHighlightProps {
+	/**
+	 * The raw text handed to the parser — `nodes[].start/end` index into this.
+	 */
+	input: string
+	/**
+	 * Flattened parse nodes; only those with numeric `start`/`end` are rendered.
+	 */
+	nodes: ParsedComponent[]
+}
+
+interface Segment {
+	text: string
+	node: ParsedComponent | null
+}
+
+type Span = ParsedComponent & { start: number; end: number }
+
+export function SpanHighlight({ input, nodes }: SpanHighlightProps): ReactNode {
+	if (!input) return null
+
+	// Keep only well-formed spans that index into the input.
+	const spans = nodes.filter(
+		(n): n is Span =>
+			typeof n.start === "number" &&
+			typeof n.end === "number" &&
+			n.start >= 0 &&
+			n.end > n.start &&
+			n.end <= input.length
+	)
+
+	if (!spans.length) return null
+
+	// Per-character owner: the most specific (shortest) span covering it, the same rule the word-level panels apply
+	// per word. The leaf always wins whatever nesting the tree hands over, so every character renders once.
+	const characters = Array.from({ length: input.length }, (_, i) => ({ start: i, end: i + 1 }))
+	const owner = shortestSpanOwners(characters, spans)
+
+	// Coalesce runs of the same owner into segments.
+	const segments: Segment[] = []
+	let from = 0
+
+	for (let i = 1; i <= input.length; i++) {
+		if (i === input.length || owner[i] !== owner[from]) {
+			const ownerIndex = owner[from] ?? -1
+
+			segments.push({ text: input.slice(from, i), node: ownerIndex === -1 ? null : (spans[ownerIndex] ?? null) })
+
+			from = i
+		}
+	}
+
+	return (
+		<div className="mw-spans">
+			<div className="mw-spans__legend">
+				<span>confidence</span>
+				<span className="mw-spans__swatch mw-spans__swatch--low" /> low
+				<span className="mw-spans__swatch mw-spans__swatch--mid" /> mid
+				<span className="mw-spans__swatch mw-spans__swatch--high" /> high
+			</div>
+			<div className="mw-spans__track">
+				{segments.map((seg, i) =>
+					seg.node ? (
+						<span
+							key={i}
+							className={`mw-spans__seg mw-spans__seg--${confidenceTierOrMid(seg.node.confidence)}`}
+							title={`${seg.node.tag}${seg.node.confidence != null ? ` · ${seg.node.confidence.toFixed(2)}` : ""}`}
+						>
+							<span className="mw-spans__text">{seg.text}</span>
+							<span className="mw-spans__tag">{seg.node.tag}</span>
+						</span>
+					) : (
+						<span key={i} className="mw-spans__gap">
+							{seg.text}
+						</span>
+					)
+				)}
+			</div>
+		</div>
+	)
+}

package/lib/pipeline/TimingPanel.tsx

@@ -0,0 +1,65 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `TimingPanel` — the per-stage timing breakdown: a stacked bar sized by each stage's wall-clock, plus a legend.
+ *   Stage colours are distinct hues, never the confidence red/amber/green, because they encode the pipeline stage and
+ *   not quality.
+ */
+
+import type { StageTiming } from "@mailwoman/core/pipeline/client-result"
+import type { ReactNode } from "react"
+
+export interface TimingPanelProps {
+	timing: StageTiming
+}
+
+const STAGES: ReadonlyArray<{ key: keyof StageTiming; label: string }> = [
+	{ key: "shape", label: "shape + kind" },
+	{ key: "classify", label: "classify" },
+	{ key: "resolve", label: "resolve" },
+]
+
+function formatMilliseconds(ms: number): string {
+	return ms >= 100 ? `${Math.round(ms)} ms` : `${ms.toFixed(1)} ms`
+}
+
+export function TimingPanel({ timing }: TimingPanelProps): ReactNode {
+	const present = STAGES.flatMap((stage) => {
+		const ms = timing[stage.key]
+
+		return typeof ms === "number" ? [{ ...stage, ms }] : []
+	})
+
+	const total = present.reduce((sum, stage) => sum + stage.ms, 0)
+
+	if (total <= 0) return null
+
+	return (
+		<div className="mw-timing">
+			<div className="mw-timing__heading">
+				Timing <span className="mw-timing__total">{formatMilliseconds(total)} total</span>
+			</div>
+			<div className="mw-timing__bar">
+				{present.map((stage) => (
+					// The rendered width is floored so a sub-millisecond stage stays visible as a sliver.
+					<div
+						key={stage.key}
+						className={`mw-timing__seg mw-timing__seg--${stage.key}`}
+						style={{ width: `${Math.max((stage.ms / total) * 100, 1.5)}%` }}
+						title={`${stage.label}: ${formatMilliseconds(stage.ms)}`}
+					/>
+				))}
+			</div>
+			<div className="mw-timing__legend">
+				{present.map((stage) => (
+					<span key={stage.key} className="mw-timing__item">
+						<span className={`mw-timing__swatch mw-timing__seg--${stage.key}`} />
+						{stage.label} <span className="mw-timing__ms">{formatMilliseconds(stage.ms)}</span>
+					</span>
+				))}
+			</div>
+		</div>
+	)
+}

package/lib/pipeline/TreeView.tsx

@@ -0,0 +1,55 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `TreeView` — the parse's containment tree as nested lists with a guide rail per level. The tag tint follows the
+ *   confidence tier; the value and score render in monospace.
+ */
+
+import type { ReactNode } from "react"
+
+import { confidenceTierOrMid } from "#common/confidence-tiers"
+
+interface TreeNode {
+	tag?: string
+	value?: unknown
+	confidence?: number
+	children?: TreeNode[]
+}
+
+export interface TreeViewProps {
+	/**
+	 * The parser's `AddressTree` (`result.tree`): the view reads `.roots` and recurses `.children`.
+	 */
+	tree: unknown
+}
+
+function renderNode(node: TreeNode, path: string): ReactNode {
+	if (typeof node.tag !== "string") return null
+
+	const kids = Array.isArray(node.children) ? node.children : []
+
+	return (
+		<li key={path} className="mw-tree__node">
+			<span className="mw-tree__row">
+				<span className={`mw-tree__tag mw-tree__tag--${confidenceTierOrMid(node.confidence)}`}>{node.tag}</span>
+				{node.value != null && String(node.value) !== "" ? (
+					<span className="mw-tree__value">{String(node.value)}</span>
+				) : null}
+				{typeof node.confidence === "number" ? (
+					<span className="mw-tree__conf">{node.confidence.toFixed(2)}</span>
+				) : null}
+			</span>
+			{kids.length ? <ul className="mw-tree__children">{kids.map((c, i) => renderNode(c, `${path}.${i}`))}</ul> : null}
+		</li>
+	)
+}
+
+export function TreeView({ tree }: TreeViewProps): ReactNode {
+	const roots = (tree as { roots?: unknown[] } | null | undefined)?.roots
+
+	if (!Array.isArray(roots) || !roots.length) return null
+
+	return <ul className="mw-tree mw-tree__children">{(roots as TreeNode[]).map((n, i) => renderNode(n, String(i)))}</ul>
+}

package/lib/pipeline/copy.ts

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