@mailwoman/react 10.0.0 → 10.1.0

package/lib/map/useMapLabelPick.ts

@@ -3,43 +3,31 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `useMapLabelPick` — clicking a place label on the map searches for it, the way the reference map apps behave.
- *
- *   A label on a map looks like a link, so a visitor clicks it. Without this the click reaches the map's pan handler
- *   and nothing happens, which reads as the label being decoration.
- *
- *   It reads the label's OWN name from the rendered feature rather than reverse-geocoding the click point: the name
- *   is what the visitor pointed at, and a lookup by coordinate answers whatever is nearest instead, which on a dense
- *   basemap is regularly not the thing under the cursor.
- *
- *   THE QUERY IS SCOPED, AND THE HOVER QUERY IS THROTTLED. `queryRenderedFeatures` with no `layers` walks the whole
- *   style: measured at 64.3 ms per call returning 4,819 features over the 79-layer basemap at zoom 14 in Manhattan,
- *   against 4.9 ms and 44 features scoped to that style's 11 label layers. At one call per pointer move the unscoped
- *   form is the map's whole frame budget, so the layer list is resolved once per style and the hover query runs at
- *   most once per animation frame. The click query is not throttled — there is one of those per click.
+ *   A place-label click searches for its own name. The hook resolves the layer list once per style and throttles the hover query to one per animation frame.
  */
 
 import { useEffect, useEffectEvent } from "react"
 import type { MapInstance, MapLayerMouseEvent } from "react-map-gl/maplibre"
 
 /**
- * The layers whose features carry a place name. Protomaps names its label layers `<theme>_label` and its settlement
- * layers `places_*`; anything else in the style is geometry, not a label a visitor can read and point at.
+ * The protomaps label layers (`<theme>_label`, `places_*`); other layers are geometry
+ * rather than readable place names.
  */
 const LABEL_LAYER = /_label|^places_/
 
 /**
- * Properties a label carries its text under, in the order they are trusted. `name` is protomaps' own; the localized
- * variants appear on styles built for a specific script.
+ * Properties that may contain a label's text, in trust order.
+ *
+ * `name` comes from Protomaps.
+ * Localized variants appear in script-specific styles.
  */
 const NAME_KEYS = ["name", "name:en", "name_en"] as const
 
 /**
- * The style's label layers, by id.
+ * The style's label layer ids.
  *
- * A style with none answers an EMPTY ARRAY, and the caller must treat that as "no labels to pick" rather than passing
- * it to `queryRenderedFeatures` — an empty `layers` option is not the same as an absent one there, and the difference
- * between "this style has no labels" and "query everything" is the 64 ms this hook exists to avoid.
+ * An empty result must stay unqueried, since an empty `layers` option is not the
+ * same as an absent one in `queryRenderedFeatures`.
  */
 function labelLayerIDs(map: MapInstance): string[] {
 	const layers = map.getStyle()?.layers ?? []
@@ -50,8 +38,7 @@ function labelLayerIDs(map: MapInstance): string[] {
 function labelNameAt(map: MapInstance, point: MapLayerMouseEvent["point"], layers: string[]): string | null {
 	if (!layers.length) return null
 
-	// `queryRenderedFeatures` answers in paint order with the topmost first, which is the label drawn over the others
-	// and therefore the one a click landed on.
+	// `queryRenderedFeatures` answers topmost-first, so the first feature with a label is the one the click landed on.
 	for (const feature of map.queryRenderedFeatures(point, { layers })) {
 		for (const key of NAME_KEYS) {
 			const value = feature.properties?.[key]
@@ -63,17 +50,20 @@ function labelNameAt(map: MapInstance, point: MapLayerMouseEvent["point"], layer
 	return null
 }
 
+/**
+ * Routes clicks on map labels to `onPick` with the clicked label's own name.
+ */
 export function useMapLabelPick(map: MapInstance | null, onPick: (name: string) => void): void {
-	// The subscription depends on the MAP alone. `useGeocode` returns a fresh object every render, so a callback built
-	// from it is new every render too — with `onPick` in the dependency list these map listeners were torn down and
-	// re-added on every keystroke in the search field. `useEffectEvent` is the shape for exactly this: an event
-	// handler that always sees the latest props without being a reactive dependency.
+	// The subscription depends only on the map.
+	// `onPick` changes on every render.
+	// `useEffectEvent` reads the latest callback without adding it as a reactive dependency.
 	const pick = useEffectEvent((name: string) => onPick(name))
 
 	useEffect(() => {
 		if (!map) return
 
-		// Recomputed when the style swaps (a theme change, a version switch) and not once per pointer move.
+		// Recomputed when the style swaps.
+		// Pointer moves read the cached list.
 		let layers = labelLayerIDs(map)
 
 		const readLayers = () => {
@@ -98,7 +88,8 @@ export function useMapLabelPick(map: MapInstance | null, onPick: (name: string)
 
 				const canvas = map.getCanvas()
 
-				// The drag cursor belongs to the pan gesture; overriding it mid-drag would fight the map for the pointer.
+				// The drag cursor belongs to the pan gesture.
+				// An override mid-drag would fight the map for the pointer.
 				if (canvas.style.cursor === "grabbing") return
 
 				canvas.style.cursor = labelNameAt(map, event.point, layers) ? "pointer" : ""

package/lib/map/useMapPlaceRender.ts

@@ -3,11 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `useMapPlaceRender` — the thin React memo wrapper over the pure {@link computeMapPlaceRenderSpec}. It
- *   recomputes the render spec only when the resolved place changes, so the declarative overlays render a
- *   stable spec object. The MATH lives in `place-render.ts` (pure, node-tested); this file adds nothing
- *   but memoization, so it stays trivially correct. A `null` place (no result yet, or a result with no
- *   candidate) yields `null` — the overlays render nothing.
+ *   The thin React memo wrapper over the pure {@link computeMapPlaceRenderSpec}; a `null` place yields `null`.
  */
 
 import { useMemo } from "react"
@@ -16,7 +12,7 @@ import { computeMapPlaceRenderSpec } from "#map/place-render"
 import type { MapPlaceRenderSpec, ResolvedMapPlace } from "#map/place-render"
 
 /**
- * Memoize the render spec for a resolved place; `null` in → `null` out (nothing to draw).
+ * Memoize the render spec for a resolved place; `null` in → `null` out (no geometry to draw).
  */
 export function useMapPlaceRender(place: ResolvedMapPlace | null | undefined): MapPlaceRenderSpec | null {
 	return useMemo(() => (place ? computeMapPlaceRenderSpec(place) : null), [place])

package/lib/map/usePlaceAutocomplete.ts

@@ -2,17 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `usePlaceAutocomplete` — the headless "Did you mean" combobox lifted from the demo god component
- *   (`_app.tsx:820-900`). It walks the host-supplied `autocomplete` over the locality segment the visitor
- *   is typing (the text after the last comma), owns the suggestion list + keyboard-highlighted active
- *   descendant, and rewrites the input on pick (replacing just that segment). No FST, no fetch of its own
- *   — the `autocomplete` fetcher is INJECTED (the package never imports `@mailwoman/resolver-wof-sqlite`),
- *   so this stays node-safe and testable with a synchronous fake.
- *
- *   Returns the `<input>` aria/combobox props to spread onto the reused {@link QueryForm} input plus an
- *   `onInputKeyDown` (↑/↓ move the highlight, Enter accepts it AND suppresses submit, Esc dismisses), and
- *   the presentational {@link PlaceAutocomplete} listbox renders `suggestions` / `activeIndex`.
  */
 
 import { type KeyboardEvent, useCallback, useEffect, useState } from "react"
@@ -20,31 +9,41 @@ import { type KeyboardEvent, useCallback, useEffect, useState } from "react"
 import { useDebouncedValue } from "#common/useDebouncedValue"
 import type { Suggestion } from "#map/types"
 
+/**
+ * Options for {@linkcode usePlaceAutocomplete}.
+ */
 export interface UsePlaceAutocompleteOptions {
 	/**
-	 * The current input text.
+	 * The controlled input text.
+	 * The segment after the last comma is the query.
 	 */
 	text: string
+
 	/**
-	 * Setter for the input text (a pick rewrites the last-comma segment).
+	 * Sets the input text.
+	 * A pick calls it with the last segment replaced.
 	 */
 	setText: (text: string) => void
+
 	/**
-	 * The host's autocomplete fetcher (FST prefix-walk). Absent → the combobox is inert.
+	 * Fetches suggestions for a query.
+	 * Without it the hook never suggests anything.
 	 */
 	autocomplete?: (query: string) => Promise<Suggestion[]>
+
 	/**
-	 * Minimum query length before suggesting. @default 2
+	 * @default 2
 	 */
 	minChars?: number
+
 	/**
-	 * Debounce before firing the fetcher. @default 150
+	 * @default 150
 	 */
 	debounceMs?: number
 }
 
 /**
- * The combobox aria props to spread onto the input the suggestions describe.
+ * The combobox ARIA props to spread onto the input.
  */
 export interface AutocompleteInputProps {
 	role: "combobox"
@@ -55,68 +54,73 @@ export interface AutocompleteInputProps {
 	autoComplete: "off"
 }
 
+/**
+ * The state and handlers that {@linkcode usePlaceAutocomplete} returns.
+ */
 export interface UsePlaceAutocomplete {
 	/**
-	 * The current suggestions (empty when nothing matches — the listbox then hides).
+	 * The current suggestions, empty when none match or the visitor dismissed the list.
 	 */
 	suggestions: Suggestion[]
+
 	/**
-	 * The keyboard-highlighted suggestion index; `-1` when none is highlighted.
+	 * The index highlighted by the keyboard, or `-1` for none.
 	 */
 	activeIndex: number
+
 	/**
-	 * Set the highlighted index (the listbox calls this on mouse-enter).
+	 * Sets the highlighted index, such as when the pointer enters an option.
 	 */
 	setActiveIndex: (index: number) => void
+
 	/**
-	 * Keydown handler for the input: ↑/↓ highlight, Enter accepts (+ suppresses submit), Esc dismisses.
+	 * Handles input keys: arrows move the highlight, Enter picks instead of submitting and Escape dismisses.
 	 */
 	onInputKeyDown: (event: KeyboardEvent<HTMLInputElement>) => void
+
 	/**
-	 * Accept a suggestion by value (rewrites the last-comma segment, closes the list).
+	 * Replaces the text after the last comma with the suggestion and closes the list.
 	 */
 	pick: (value: string) => void
+
 	/**
-	 * Close the list without picking.
+	 * Closes the list without picking until the query changes.
 	 */
 	dismiss: () => void
+
 	/**
-	 * Aria/combobox props for the input the suggestions describe.
+	 * The combobox ARIA props to spread onto the input.
 	 */
 	inputProps: AutocompleteInputProps
+
 	/**
-	 * The listbox element id (matches `inputProps["aria-controls"]`).
+	 * The listbox element ID.
+	 * It matches `inputProps["aria-controls"]`.
 	 */
 	listboxID: string
-	/**
-	 * Build the option element id for suggestion `index`.
-	 */
+
 	optionID: (index: number) => string
 }
 
 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}`
 
-/**
- * Extract the locality segment being typed — the text after the last comma, trimmed.
- */
 function localitySegment(text: string): string {
 	return (text.includes(",") ? text.slice(text.lastIndexOf(",") + 1) : text).trim()
 }
 
-/**
- * Replace the locality segment (after the last comma) with `name`, preserving the address prefix.
- */
 function replaceSegment(current: string, name: string): string {
 	return current.includes(",") ? `${current.slice(0, current.lastIndexOf(",") + 1)} ${name}` : name
 }
 
+/**
+ * Fetches debounced place suggestions for the text after the input's last comma.
+ *
+ * A pick replaces only that segment.
+ * A digit-leading segment never reaches `autocomplete`.
+ */
 export function usePlaceAutocomplete({
 	text,
 	setText,
@@ -124,18 +128,8 @@ export function usePlaceAutocomplete({
 	minChars = 2,
 	debounceMs = 150,
 }: UsePlaceAutocompleteOptions): UsePlaceAutocomplete {
-	/**
-	 * 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)
 
@@ -178,7 +172,7 @@ export function usePlaceAutocomplete({
 			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)

package/lib/map.ts

@@ -0,0 +1,95 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/react/map` — the geocoder map surface, kept behind its own subpath so `maplibre-gl`
+ *   / `react-map-gl` (WebGL + DOM at import) never enter the package-root graph. This subpath import
+ *   pulls the map deps. importing `@mailwoman/react` (root) does not. Consumers who only want the
+ *   parse/POI explorers never pay for maplibre.
+ *
+ *   The host must supply `maplibre-gl` + `react-map-gl` (peer deps) and import
+ *   `maplibre-gl/dist/maplibre-gl.css` + `@mailwoman/react/styles.css` itself.
+ */
+
+export { MapCanvas } from "./map/MapCanvas.tsx"
+export type { MapCanvasExtraProps, MapCanvasProps, MapCanvasStyle } from "./map/MapCanvas.tsx"
+
+// ── Map chrome (node-safe presentation. The host supplies the input and reads its own map) ──
+export { MapChipRow } from "./map/MapChipRow.tsx"
+export type { MapChip, MapChipRowProps } from "./map/MapChipRow.tsx"
+export { MapCompass } from "./map/MapCompass.tsx"
+export type { MapCompassProps } from "./map/MapCompass.tsx"
+export { useMapBearing } from "./map/useMapBearing.ts"
+export type { UseMapBearing } from "./map/useMapBearing.ts"
+export { useMapLabelPick } from "./map/useMapLabelPick.ts"
+export { MapControlButton, MapControlGroup, MapControlStack } from "./map/MapControlStack.tsx"
+export type { MapControlButtonProps, MapControlGroupProps, MapControlStackProps } from "./map/MapControlStack.tsx"
+export { MapFooter } from "./map/MapFooter.tsx"
+export type { MapFooterProps } from "./map/MapFooter.tsx"
+export { MapProgressBar } from "./map/MapProgressBar.tsx"
+export type { MapProgressBarProps } from "./map/MapProgressBar.tsx"
+export { MapSheet, SheetClose } from "./map/MapSheet.tsx"
+export type { MapSheetProps } from "./map/MapSheet.tsx"
+export { MapSearchBar, SearchGlyph } from "./map/MapSearchBar.tsx"
+export type { MapSearchBarProps } from "./map/MapSearchBar.tsx"
+
+export type {
+	CompareContext,
+	GeocoderPanels,
+	GeocoderRuntime,
+	InferenceBackend,
+	LngLatTuple,
+	MapBias,
+	OverlaySpec,
+	ResultContext,
+	Suggestion,
+	VersionOption,
+} from "#map/types"
+
+// ── Pure geometry + render spec (node-safe. No react-map-gl at runtime) ──────
+export { approxCircleGeometry, bboxToBounds, geomBounds, radiusCircleGeometry } from "#map/geometry"
+export type { BoundsTuple, PlaceGeometry } from "#map/geometry"
+export { cameraToViewState, computeMapPlaceRenderSpec } from "#map/place-render"
+export type { LngLat, MapCameraTarget, MapPlaceRenderSpec, PlaceTier, ResolvedMapPlace } from "#map/place-render"
+export { useMapPlaceRender } from "#map/useMapPlaceRender"
+
+// ── Declarative overlays (react-map-gl `<Marker>`/`<Source>`/`<Layer>`) ──────
+export { OverlayLayers } from "./map/OverlayLayers.tsx"
+export type { OverlayLayersProps } from "./map/OverlayLayers.tsx"
+export { PlaceMarker } from "./map/PlaceMarker.tsx"
+export type { PlaceMarkerProps } from "./map/PlaceMarker.tsx"
+export { ResolvedPlaceLayers } from "./map/ResolvedPlaceLayers.tsx"
+export type { ResolvedPlaceLayersProps } from "./map/ResolvedPlaceLayers.tsx"
+export { ResultCamera } from "./map/ResultCamera.tsx"
+export type { ResultCameraProps } from "./map/ResultCamera.tsx"
+export { ResultOverlay } from "./map/ResultOverlay.tsx"
+export type { ResultOverlayProps } from "./map/ResultOverlay.tsx"
+
+// ── Geocoder controls + the composed geocoder ────────────────────────────────
+export { BackendControl } from "./map/BackendControl.tsx"
+export type { BackendControlProps } from "./map/BackendControl.tsx"
+export { CompareToggle } from "./map/CompareToggle.tsx"
+export type { CompareToggleProps } from "./map/CompareToggle.tsx"
+export { Geocoder } from "./map/Geocoder.tsx"
+export type { GeocoderProps } from "./map/Geocoder.tsx"
+export { GeocoderControls } from "./map/GeocoderControls.tsx"
+export type { GeocoderControlsProps } from "./map/GeocoderControls.tsx"
+export { PlaceAutocomplete } from "./map/PlaceAutocomplete.tsx"
+export type { PlaceAutocompleteProps } from "./map/PlaceAutocomplete.tsx"
+export { ResultPanel } from "./map/ResultPanel.tsx"
+export type { ResultPanelProps } from "./map/ResultPanel.tsx"
+export { useCompareState } from "#map/useCompareState"
+export type { UseCompareState } from "#map/useCompareState"
+export { useGeocode } from "#map/useGeocode"
+export type { UseGeocode, UseGeocodeOptions } from "#map/useGeocode"
+export { usePlaceAutocomplete } from "#map/usePlaceAutocomplete"
+
+export type {
+	AutocompleteInputProps,
+	UsePlaceAutocomplete,
+	UsePlaceAutocompleteOptions,
+} from "#map/usePlaceAutocomplete"
+
+export { VersionPicker } from "./map/VersionPicker.tsx"
+export type { VersionPickerProps } from "./map/VersionPicker.tsx"

package/lib/pipeline/CandidatePicker.tsx

@@ -3,8 +3,18 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `CandidatePicker` — the ranked list of alternate gazetteer candidates; clicking one selects it.
- *   Presentational; the selected index is owned by the caller (the pipeline hook).
+ *   `CandidatePicker` — the ranked list of alternate gazetteer candidates. clicking one selects it.
+ *   Presentational. the selected index is owned by the caller (the pipeline hook).
+ *
+ *   The row shows the rank rather than the score. `ResolvedPlaceView.score` is implementation-defined. Its type specifies
+ *   "callers should treat as ordinal" — and the backends do not agree on a scale: the FTS regime is a negated bm25
+ *   plus additive tiers, while the candidate regime is exactly `log10(population + 1)`. Both regimes put
+ *   "New York · 6.95" (log10 of 8.9M) directly under "350 5th Ave · 1.00" from a bounded blend. That reads as one
+ *   number beating another by a factor of seven rather than as two numbers that never shared a scale.
+ *   `docs/records/reviews/2026-08-04-resolver-score-abstention.md` measures this in full.
+ *
+ *   The raw value stays on the button's `title`, at full precision, because it is exactly the right thing to have
+ *   when you are debugging a ranking and exactly the wrong thing to put in a visitor's eyeline.
  */
 
 import type { ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result"
@@ -33,9 +43,7 @@ export function CandidatePicker({ candidates, selectedIndex, onSelect }: Candida
 						>
 							<span className="mw-candidates__rank">#{i + 1}</span>
 							<span className="mw-candidates__name">{candidate.name}</span>
-							<span className="mw-candidates__meta">
-								{candidate.placetype} · {candidate.score.toFixed(2)}
-							</span>
+							<span className="mw-candidates__meta">{candidate.placetype}</span>
 						</button>
 					</li>
 				))}

package/lib/pipeline/ConfidenceCell.tsx

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `ConfidenceCell` — a compact confidence bar + value for the component table. The fill colour follows the shared
+ *   `ConfidenceCell` — a compact confidence bar + value for the component table. The fill color follows the shared
  *   confidence tiers. Presentational.
  */
 

package/lib/pipeline/FailureDiagnostic.tsx

@@ -3,17 +3,23 @@
  * @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".
+ *   Explains a query that resolved to no place and suggests which component, such as a city or a
+ *   state, the visitor could add.
  */
 
 import type { ParsedComponent } from "@mailwoman/core/pipeline/client-result"
 import type { ReactNode } from "react"
 
+/**
+ * Props for {@link FailureDiagnostic}.
+ */
 export interface FailureDiagnosticProps {
 	nodes: ParsedComponent[]
 }
 
+/**
+ * Renders hints based on which components the parser found.
+ */
 export function FailureDiagnostic({ nodes }: FailureDiagnosticProps): ReactNode {
 	const hasLocality = nodes.some((n) => n.tag === "locality")
 	const hasPostcode = nodes.some((n) => n.tag === "postcode")

package/lib/pipeline/QueryForm.tsx

@@ -19,11 +19,14 @@ export interface QueryFormProps {
 	busy?: boolean
 	placeholder?: string
 	/**
-	 * Keydown on the input — the hook 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
 	/**
-	 * Override 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/lib/pipeline/ResolvedPlace.tsx

@@ -25,7 +25,7 @@ export function ResolvedPlace({ place, dualRoles }: ResolvedPlaceProps): ReactNo
 				<dt>placetype</dt>
 				<dd>{place.placetype}</dd>
 				{place.tier ? (
-					// A street-tier answer is not a gazetteer place: it carries a precision instead of an id.
+					// A street-tier answer is not a gazetteer place: it has a precision instead of an id.
 					<>
 						<dt>precision</dt>
 						<dd>

package/lib/pipeline/SpanHighlight.tsx

@@ -4,8 +4,8 @@
  * @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.
+ *   top, tinted by its confidence tier, with the tag beneath. Gaps (delimiters, unparsed characters) fall through as
+ *   plain text, so a dropped span is visible as a literal break in the color.
  */
 
 import type { ParsedComponent } from "@mailwoman/core/pipeline/client-result"
@@ -20,7 +20,8 @@ export interface SpanHighlightProps {
 	 */
 	input: string
 	/**
-	 * Flattened parse nodes; only those with numeric `start`/`end` are rendered.
+	 * Flattened parse nodes.
+	 * Only those with numeric `start`/`end` are rendered.
 	 */
 	nodes: ParsedComponent[]
 }
@@ -47,8 +48,9 @@ export function SpanHighlight({ input, nodes }: SpanHighlightProps): ReactNode {
 
 	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.
+	// 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)
 

package/lib/pipeline/TimingPanel.tsx

@@ -4,7 +4,7 @@
  * @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
+ *   Stage colors are distinct hues, never the confidence red/amber/green, because they encode the pipeline stage and
  *   not quality.
  */
 

package/lib/pipeline/TreeView.tsx

@@ -4,7 +4,7 @@
  * @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.
+ *   confidence tier. the value and score render in monospace.
  */
 
 import type { ReactNode } from "react"

package/lib/pipeline/copy.ts

@@ -4,34 +4,31 @@
  * @author Teffen Ellis, et al.
  *
  *   Builds the "Copy JSON" payload for a parse result — the components + the selected resolved place,
- *   pretty-printed. Pure; shared by the explorer's copy button.
+ *   pretty-printed. Pure. shared by the explorer's copy button.
  */
 
+import { prettyJSON } from "@mailwoman/core/json"
 import type { ParseResult, ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result"
 
 export function buildParsePayload(result: ParseResult, selected: ResolvedPlaceView | null): string {
-	return JSON.stringify(
-		{
-			input: result.input,
-			components: result.nodes.map((node) => ({
-				tag: node.tag,
-				value: node.value ?? null,
-				confidence: node.confidence ?? null,
-				start: node.start ?? null,
-				end: node.end ?? null,
-			})),
-			resolved: selected
-				? {
-						name: selected.name,
-						placetype: selected.placetype,
-						id: selected.id,
-						lat: selected.lat,
-						lon: selected.lon,
-						score: selected.score,
-					}
-				: null,
-		},
-		null,
-		2
-	)
+	return prettyJSON({
+		input: result.input,
+		components: result.nodes.map((node) => ({
+			tag: node.tag,
+			value: node.value ?? null,
+			confidence: node.confidence ?? null,
+			start: node.start ?? null,
+			end: node.end ?? null,
+		})),
+		resolved: selected
+			? {
+					name: selected.name,
+					placetype: selected.placetype,
+					id: selected.id,
+					lat: selected.lat,
+					lon: selected.lon,
+					score: selected.score,
+				}
+			: null,
+	})
 }