@mailwoman/react 9.4.0 → 10.1.0

package/README.md

@@ -1,21 +1,22 @@
 # @mailwoman/react
 
-React components + headless hooks for [mailwoman](https://mailwoman.ai) — the
-parse/geocode/POI explorers from the docs site, decomposed and packaged for use in any React app.
+This package provides React components and headless hooks for [mailwoman](https://mailwoman.ai). It
+packages the parse/geocode/POI explorers from the docs site as smaller parts for use in any React app.
 
 ## What's in the box
 
-Two composed explorers, plus the small presentational units and headless hooks they decompose into:
+The package contains two composed explorers, plus the small presentational units and headless hooks
+they are built from:
 
-- **`POIExplorer`** — a self-contained POI-intent tester (classify → subject → OverpassQL). The intent
+- **`POIExplorer`** is 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 implementation never enters this package's graph.
-- **`PipelineExplorer`** — a parse + resolve tester driven by an **injected `PipelineRuntime`**. The
+  `@mailwoman/query-shape`, without weights or network access. A live poi.db search is opt-in through an
+  injected `runLiveSearch` probe, so the httpvfs/worker implementation never enters this package's graph.
+- **`PipelineExplorer`** is a parse and 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.
+  which keeps onnxruntime-web, sqlite-wasm, and node builtins out of this package entirely.
 
-The headless hooks — `usePOISearch`, `useParsePipeline` — own the state machines; the presentational
+The headless hooks, `usePOISearch` and `useParsePipeline`, own the state machines. The presentational
 units (`QueryInput`, `SubjectPanel`, `OverpassBlock`, `LiveResultsBlock`, `ComponentTable`,
 `ResolvedPlace`, `CandidatePicker`, `KindBadge`, `LoadingIndicator`, …) are pure and prop-driven.
 
@@ -26,17 +27,17 @@ import { POIExplorer, PipelineExplorer } from "@mailwoman/react"
 import "@mailwoman/react/styles.css"
 ```
 
-Styling ships as a standalone stylesheet (`@mailwoman/react/styles.css`) — plain, `mw-`-prefixed, and
-Infima-token-aware, so it looks right both inside Docusaurus and standalone. No component imports CSS,
-so the bare package import stays node-safe.
+The stylesheet ships as a standalone file (`@mailwoman/react/styles.css`). It is plain CSS with a `mw-`
+prefix and reads Infima tokens, so it renders correctly both inside Docusaurus and standalone. No
+component imports CSS, so the bare package import stays safe to load in Node.
 
 ## Development
 
-- `yarn workspace @mailwoman/react storybook` — Storybook (Vite) for every unit + the composed
-  explorers, with mocked runtimes (no network/db).
-- `yarn workspace @mailwoman/react test:browser` — Vitest browser-mode component + hook tests
+- `yarn workspace @mailwoman/react storybook` runs Storybook (Vite) for every unit and the composed
+  explorers, with mocked runtimes that need no network or database.
+- `yarn workspace @mailwoman/react test:browser` runs the Vitest browser-mode component and hook tests
   (Playwright / headless Chromium).
 
 ## License
 
-AGPL-3.0-only OR LicenseRef-Commercial — see the [mailwoman repository](https://github.com/sister-software/mailwoman).
+AGPL-3.0-only OR LicenseRef-Commercial. See the [mailwoman repository](https://github.com/sister-software/mailwoman).

package/fonts.css

@@ -1,59 +1,134 @@
 /**
- * The brand typeface, served from the same origin every app already preconnects to.
+ * The brand typefaces, 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.
+ * The token layer binds five faces: Bliss Pro regular, medium and bold for running text and headings, Bliss Pro
+ * italic for a caption, and the variable Fira Code face (weights 300 to 700) for the `code`, `number` and `glyph`
+ * roles. Bliss Pro's figures are proportional and it has no `tnum` feature, so `number` sets in Fira Code. Bliss Pro
+ * provides no 600, so `--font-weight-semibold: 600` matches the 700 face by the CSS weight-matching rules rather than
+ * being synthesized.
+ *
+ * Each Bliss Pro face is split by `unicode-range` into a Latin file and an extended file (Latin Extended-A, Greek,
+ * Cyrillic, math), and the browser downloads the extended file only when a page uses one of its codepoints.
+ * "Bliss Pro Fallback" scales Arial to Bliss Pro's average advance and vertical metrics, so text keeps its line
+ * breaks when the web font swaps in.
  *
  * 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-family: "Bliss Pro Fallback";
+	src: local("Arial");
+	size-adjust: 92%;
+	ascent-override: 103.6%;
+	descent-override: 26.2%;
+	line-gap-override: 0%;
+}
+
+@font-face {
+	font-family: "Bliss Pro Web";
 	font-display: swap;
 	font-weight: 400;
 	font-style: normal;
-	src: url("https://public.mailwoman.ai/fonts/IoveskaNexus/WOFF2/IosevkaNexus-Regular.woff2") format("woff2");
+	src: url("https://public.mailwoman.ai/fonts/BlissPro/WOFF2/BlissPro-Latin.woff2") format("woff2");
+	unicode-range:
+		U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC,
+		U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD, U+FB01-FB02;
 }
 
 @font-face {
-	font-family: "Iosevka Nexus Web";
+	font-family: "Bliss Pro Web";
 	font-display: swap;
-	font-weight: 450;
+	font-weight: 400;
 	font-style: normal;
-	src: url("https://public.mailwoman.ai/fonts/IoveskaNexus/WOFF2/IosevkaNexus-Book.woff2") format("woff2");
+	src: url("https://public.mailwoman.ai/fonts/BlissPro/WOFF2/BlissPro-Extended.woff2") format("woff2");
+	unicode-range:
+		U+0100-0129, U+012B-012C, U+012E-0130, U+0132-0137, U+0139-0148, U+014A-0151, U+0154-017E, U+0192, U+01FA-01FF,
+		U+0218-0219, U+02C7, U+02D8-02D9, U+02DB, U+02DD, U+0315, U+0326, U+0386, U+0388-038A, U+038C, U+038E-0393,
+		U+0395-03A1, U+03A3-03CE, U+0400-045F, U+0462-0463, U+0472-0475, U+0490-0491, U+1E80-1E85, U+1EF2-1EF3, U+2070,
+		U+2074-2089, U+208D-208E, U+2113, U+2116-2117, U+212E, U+2153-2154, U+215B-215E, U+2202, U+2206, U+220F, U+2211,
+		U+221A, U+221E, U+222B, U+2248, U+2260, U+2264-2265, U+25CA;
 }
 
 @font-face {
-	font-family: "Iosevka Nexus Web";
+	font-family: "Bliss Pro 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-weight: 400;
+	font-style: italic;
+	src: url("https://public.mailwoman.ai/fonts/BlissPro/WOFF2/BlissPro-Italic-Latin.woff2") format("woff2");
+	unicode-range:
+		U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC,
+		U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD, U+FB01-FB02;
 }
 
 @font-face {
-	font-family: "Iosevka Nexus Web";
+	font-family: "Bliss Pro Web";
 	font-display: swap;
 	font-weight: 400;
 	font-style: italic;
-	src: url("https://public.mailwoman.ai/fonts/IoveskaNexus/WOFF2/IosevkaNexus-Italic.woff2") format("woff2");
+	src: url("https://public.mailwoman.ai/fonts/BlissPro/WOFF2/BlissPro-Italic-Extended.woff2") format("woff2");
+	unicode-range:
+		U+0100-0129, U+012B-012C, U+012E-0130, U+0132-0137, U+0139-0148, U+014A-0151, U+0154-017E, U+0192, U+01FA-01FF,
+		U+0218-0219, U+02C7, U+02D8-02D9, U+02DB, U+02DD, U+0315, U+0326, U+0386, U+0388-038A, U+038C, U+038E-0393,
+		U+0395-03A1, U+03A3-03CE, U+0400-045F, U+0462-0463, U+0472-0475, U+0490-0491, U+1E80-1E85, U+1EF2-1EF3, U+2070,
+		U+2074-2089, U+208D-208E, U+2113, U+2116-2117, U+212E, U+2153-2154, U+215B-215E, U+2202, U+2206, U+220F, U+2211,
+		U+221A, U+221E, U+222B, U+2248, U+2260, U+2264-2265, U+25CA;
 }
 
 @font-face {
-	font-family: "Iosevka Nexus Mono Web";
+	font-family: "Bliss Pro Web";
 	font-display: swap;
-	font-weight: 400;
+	font-weight: 500;
+	font-style: normal;
+	src: url("https://public.mailwoman.ai/fonts/BlissPro/WOFF2/BlissPro-Medium-Latin.woff2") format("woff2");
+	unicode-range:
+		U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC,
+		U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD, U+FB01-FB02;
+}
+
+@font-face {
+	font-family: "Bliss Pro Web";
+	font-display: swap;
+	font-weight: 500;
+	font-style: normal;
+	src: url("https://public.mailwoman.ai/fonts/BlissPro/WOFF2/BlissPro-Medium-Extended.woff2") format("woff2");
+	unicode-range:
+		U+0100-0129, U+012B-012C, U+012E-0130, U+0132-0137, U+0139-0148, U+014A-0151, U+0154-017E, U+0192, U+01FA-01FF,
+		U+0218-0219, U+02C7, U+02D8-02D9, U+02DB, U+02DD, U+0315, U+0326, U+0386, U+0388-038A, U+038C, U+038E-0393,
+		U+0395-03A1, U+03A3-03CE, U+0400-045F, U+0462-0463, U+0472-0475, U+0490-0491, U+1E80-1E85, U+1EF2-1EF3, U+2070,
+		U+2074-2089, U+208D-208E, U+2113, U+2116-2117, U+212E, U+2153-2154, U+215B-215E, U+2202, U+2206, U+220F, U+2211,
+		U+221A, U+221E, U+222B, U+2248, U+2260, U+2264-2265, U+25CA;
+}
+
+@font-face {
+	font-family: "Bliss Pro Web";
+	font-display: swap;
+	font-weight: 700;
+	font-style: normal;
+	src: url("https://public.mailwoman.ai/fonts/BlissPro/WOFF2/BlissPro-Bold-Latin.woff2") format("woff2");
+	unicode-range:
+		U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC,
+		U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD, U+FB01-FB02;
+}
+
+@font-face {
+	font-family: "Bliss Pro Web";
+	font-display: swap;
+	font-weight: 700;
 	font-style: normal;
-	src: url("https://public.mailwoman.ai/fonts/IosevkaNexusMono/WOFF2/IosevkaNexusMono-Regular.woff2") format("woff2");
+	src: url("https://public.mailwoman.ai/fonts/BlissPro/WOFF2/BlissPro-Bold-Extended.woff2") format("woff2");
+	unicode-range:
+		U+0100-0129, U+012B-012C, U+012E-0130, U+0132-0137, U+0139-0148, U+014A-0151, U+0154-017E, U+0192, U+01FA-01FF,
+		U+0218-0219, U+02C7, U+02D8-02D9, U+02DB, U+02DD, U+0315, U+0326, U+0386, U+0388-038A, U+038C, U+038E-0393,
+		U+0395-03A1, U+03A3-03CE, U+0400-045F, U+0462-0463, U+0472-0475, U+0490-0491, U+1E80-1E85, U+1EF2-1EF3, U+2070,
+		U+2074-2089, U+208D-208E, U+2113, U+2116-2117, U+212E, U+2153-2154, U+215B-215E, U+2202, U+2206, U+220F, U+2211,
+		U+221A, U+221E, U+222B, U+2248, U+2260, U+2264-2265, U+25CA;
 }
 
 @font-face {
-	font-family: "Iosevka Nexus Mono Web";
+	font-family: "Fira Code Web";
 	font-display: swap;
-	font-weight: 450;
+	font-weight: 300 700;
 	font-style: normal;
-	src: url("https://public.mailwoman.ai/fonts/IosevkaNexusMono/WOFF2/IosevkaNexusMono-Book.woff2") format("woff2");
+	src: url("https://public.mailwoman.ai/fonts/FiraCode/WOFF2/FiraCode-VF.woff2") format("woff2");
 }

package/lib/common/About.tsx

@@ -3,87 +3,103 @@
  * @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.
+ * `About` — the explainer for the browser geocoder: the neural model, the confidence colors, the gazetteer resolver, the byte-range database and the FST prior. It renders no live content.
  */
 
 import type { ReactNode } from "react"
 
-export function About(): ReactNode {
+export interface AboutProps {
+	/**
+	 * Wraps the prose in its own `<details>` disclosure.
+	 *
+	 * Set false where the host is already the disclosure, because a summary repeating
+	 * an About 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>sqlite-wasm</strong> over a read-only HTTP file system. It range-requests only the pages a lookup
+					touches. Therefore, 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>
-			<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>
+			{body}
 		</details>
 	)
 }

package/lib/common/ClientOnly.tsx

@@ -3,30 +3,18 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `ClientOnly` — a portable SSR boundary. The docs explorers wrapped Docusaurus's `<BrowserOnly>`;
- *   this is the framework-agnostic equivalent so the components stay usable in any React app (Next,
- *   Remix, Docusaurus). It renders `fallback` on the server and the first client paint, then swaps to
- *   `children()` once mounted — keeping timers, clipboard, and dynamic imports off the server render.
- *
- *   The mount flag comes from `useSyncExternalStore` with a constant snapshot pair — `false` on the
- *   server, `true` in the browser — which is the store-shaped statement of exactly this boundary. The
- *   earlier `useState(false)` + `useEffect(() => setMounted(true))` said the same thing with a
- *   render-cascade the react(set-state-in-effect) rule rightly flags: the second render was the
- *   mechanism, not an accident, and the store form gets the same second paint without a set-state.
+ * `ClientOnly` — a portable SSR boundary that renders `fallback` on the server and first client paint. It swaps to `children()` after mounting, keeping timers, clipboard and dynamic imports off the server render.
  */
 
 import { type ReactNode, useSyncExternalStore } from "react"
 
-/**
- * The boundary never changes after mount, so nothing ever notifies.
- */
 function subscribeNever(): () => void {
 	return () => {}
 }
 
 export interface ClientOnlyProps {
 	/**
-	 * Rendered once mounted in the browser. A thunk so its (browser-only) imports never run on the server.
+	 * Rendered once mounted in the browser, as a thunk so its browser-only imports never run on the server.
 	 */
 	children: () => ReactNode
 	/**

package/lib/common/CopyButton.tsx

@@ -13,7 +13,9 @@ import { useClipboard } from "#common/useClipboard"
 
 export interface CopyButtonProps {
 	/**
-	 * The text to copy. If a thunk, it's evaluated at click time (so callers can copy the latest value).
+	 * The text to copy.
+	 *
+	 * If a thunk, it's evaluated at click time (so callers can copy the latest value).
 	 */
 	value: string | (() => string)
 	/**

package/lib/common/LoadingIndicator.tsx

@@ -21,7 +21,8 @@ export interface LoadingIndicatorProps extends React.HTMLAttributes<HTMLDivEleme
 	 */
 	mode?: LoadingMode
 	/**
-	 * Optional label; in staged mode it renders above the step list.
+	 * Optional label.
+	 * In staged mode it renders above the step list.
 	 */
 	label?: string
 	/**
@@ -37,7 +38,8 @@ export interface LoadingIndicatorProps extends React.HTMLAttributes<HTMLDivEleme
 	 */
 	steps?: string[]
 	/**
-	 * 0-based index of the active step; earlier steps are complete, later ones pending. @default -1
+	 * 0-based index of the active step.
+	 * Earlier steps are complete, later ones pending. @default -1
 	 */
 	activeStep?: number
 }

package/lib/common/PresetChips.tsx

@@ -3,8 +3,8 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `PresetChips` — the "Try:" row of example buttons shared by both explorers. Presentational: it
- *   renders a labelled list and calls `onPick` with the chosen preset's value.
+ *   `PresetChips` is the "Try:" row of example buttons shared by both explorers. Presentational: it
+ *   renders a labeled list and calls `onPick` with the chosen preset's value.
  */
 
 import type { ReactNode } from "react"
@@ -13,10 +13,10 @@ export interface Preset {
 	label: string
 	value: string
 	/**
-	 * ISO country code for the placetype-pair country pin (#1278 phase 2's `{country}` override). Optional: a host that
-	 * wires the pair prior hands this to `selectPairIndexForText` when the input still equals this preset's text, so a
-	 * locale structural routing can't detect (NZ's 4-digit postcode isn't distinctive) still fires the dependent_locality
-	 * prior. Purely descriptive to `PresetChips` itself (which only emits `value`).
+	 * ISO country code for the placetype-pair country pin.
+	 *
+	 * A host that wires the pair prior hands this to `selectPairIndexForText`
+	 * when the input still equals this preset's text.
 	 */
 	country?: string
 }
@@ -26,11 +26,12 @@ export interface PresetChipsProps {
 	onPick: (value: string) => void
 	disabled?: boolean
 	/**
-	 * Leading label. @default "Try:"
+	 * The label shown before the choices. @default "Try:"
 	 */
 	caption?: string
 	/**
-	 * Optional trailing content rendered inside the chip row after the presets (e.g. an inline permalink button).
+	 * Optional trailing content rendered inside the chip row after the presets
+	 * (e.g. an inline permalink button).
 	 */
 	trailing?: ReactNode
 }

package/lib/common/confidence-tiers.ts

@@ -2,10 +2,10 @@
  * @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.
+ * @file Confidence banding shared by every component that colors 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
+ *   It is a presentation choice rather than a model one: the parser emits a continuous confidence and these
+ *   bounds only decide which color a span is drawn in, so they live here rather than anywhere the
  *   pipeline can see them.
  */
 
@@ -15,7 +15,8 @@
 export const HIGH_CONFIDENCE_MIN = 0.8
 
 /**
- * At or above this the span is drawn as medium-confidence; below it, low.
+ * At or above this the span is drawn as medium-confidence.
+ * Below it, low.
  */
 export const MID_CONFIDENCE_MIN = 0.5
 
@@ -40,8 +41,8 @@ export function confidenceTier(confidence: number): ConfidenceTier {
 }
 
 /**
- * {@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.
+ * {@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"

package/lib/common/cx.ts

@@ -11,7 +11,9 @@
 export type ClassValue = string | number | false | null | undefined | Record<string, boolean>
 
 /**
- * Join truthy class tokens; object entries contribute their key when the value is truthy.
+ * Join truthy class tokens.
+ *
+ * Object entries contribute their key when the value is truthy.
  */
 export function cx(...values: ClassValue[]): string {
 	const out: string[] = []

package/lib/common/text-tokens.ts

@@ -16,7 +16,7 @@ export interface WordToken {
 	 */
 	text: string
 	/**
-	 * Leading whitespace before this word.
+	 * Whitespace before this word.
 	 */
 	whitespace: string
 	/**
@@ -36,7 +36,9 @@ 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.
+	// `charAt` answers "" past the end.
+	// It no whitespace test matches.
+	// Therefore, both walks stop at the input's length.
 	while (i < input.length) {
 		let ws = ""
 
@@ -68,8 +70,9 @@ export interface CharSpan {
 }
 
 /**
- * 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.
+ * 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) => {

package/lib/common/useBuildInfo.ts

@@ -0,0 +1,54 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * `useBuildInfo()` — reads the deployment's own `build.json`, resolving a failed fetch to `null` because a dev server has no such file and the page must not show an error strip.
+ */
+
+import { useEffect, useState } from "react"
+
+export interface BuildInfoRecord {
+	/**
+	 * The deployment's name: `mailwoman-earth`, `mailwoman-moon`, `mailwoman-mars`.
+	 */
+	app: string
+	revision: string
+	/**
+	 * The same revision, full length — what a commit URL wants.
+	 */
+	commit?: string
+	/**
+	 * ISO-8601 seconds, `Z` suffix.
+	 */
+	buildTime: string
+}
+
+/**
+ * The deployment record, or `null` while it loads and whenever it cannot be read.
+ */
+export function useBuildInfo(url = "/build.json"): BuildInfoRecord | null {
+	const [info, setInfo] = useState<BuildInfoRecord | null>(null)
+
+	useEffect(() => {
+		const controller = new AbortController()
+
+		void (async () => {
+			try {
+				const response = await fetch(url, { signal: controller.signal })
+
+				if (!response.ok) return
+
+				const record = (await response.json()) as BuildInfoRecord
+
+				if (!controller.signal.aborted && record?.revision) {
+					setInfo(record)
+				}
+			} catch {}
+		})()
+
+		return () => controller.abort()
+	}, [url])
+
+	return info
+}