@mailwoman/react 10.0.0 → 10.2.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.
 
@@ -23,20 +24,21 @@ units (`QueryInput`, `SubjectPanel`, `OverpassBlock`, `LiveResultsBlock`, `Compo
 
 ```tsx
 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,19 +3,19 @@
  * @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.
+ * `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 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.
+	 * Wraps the prose in its own `<details>` disclosure.
 	 *
-	 * @default true
+	 * Set false where the host is already the disclosure, because a summary repeating
+	 * an About button's words is one control too many.
+	 *
+	 * @defaultValue `true`
 	 */
 	collapsible?: boolean
 }
@@ -28,8 +28,8 @@ export function About({ collapsible = true }: AboutProps = {}): ReactNode {
 				<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.
+					runs entirely in your browser via <strong>onnxruntime-web</strong> on its WASM SIMD backend. The model ships
+					as a 37.6 MB int8-quantized ONNX bundle; fp32 weights are also available for higher accuracy.
 				</p>
 			</section>
 
@@ -73,8 +73,8 @@ export function About({ collapsible = true }: AboutProps = {}): ReactNode {
 				<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.
+					<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>
 

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,15 +13,21 @@ 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)
 	/**
-	 * Label in the idle state. @default "Copy"
+	 * Label in the idle state.
+	 *
+	 * @defaultValue `"Copy"`
 	 */
 	label?: ReactNode
 	/**
-	 * Label shown briefly after a successful copy. @default "✓ Copied"
+	 * Label shown briefly after a successful copy.
+	 *
+	 * @defaultValue `"✓ Copied"`
 	 */
 	copiedLabel?: ReactNode
 	className?: string

package/lib/common/LoadingIndicator.tsx

@@ -17,19 +17,24 @@ export type LoadingMode = "pulse" | "spinner" | "staged"
 
 export interface LoadingIndicatorProps extends React.HTMLAttributes<HTMLDivElement> {
 	/**
-	 * @default "spinner"
+	 * @defaultValue `"spinner"`
 	 */
 	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
 	/**
-	 * Number of skeleton bars (pulse mode). @default 3
+	 * Number of skeleton bars (pulse mode).
+	 *
+	 * @defaultValue `3`
 	 */
 	barCount?: number
 	/**
-	 * Spinner ring size. @default "medium"
+	 * Spinner ring size.
+	 *
+	 * @defaultValue `"medium"`
 	 */
 	size?: "small" | "medium" | "large"
 	/**
@@ -37,7 +42,10 @@ 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.
+	 *
+	 * @defaultValue `-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,14 @@ export interface PresetChipsProps {
 	onPick: (value: string) => void
 	disabled?: boolean
 	/**
-	 * Leading label. @default "Try:"
+	 * The label shown before the choices.
+	 *
+	 * @defaultValue `"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,10 +41,10 @@ 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 {
+export function confidenceTierOrMid(confidence?: number | null): ConfidenceTier {
 	if (confidence == null) return "mid"
 
 	return confidenceTier(confidence)

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

@@ -10,13 +10,15 @@
  *   the owner walk live here.
  */
 
+import type { CharRange } from "@mailwoman/query-shape"
+
 export interface WordToken {
 	/**
 	 * The word text as it appears in the input.
 	 */
 	text: string
 	/**
-	 * Leading whitespace before this word.
+	 * Whitespace before this word.
 	 */
 	whitespace: string
 	/**
@@ -36,7 +38,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 = ""
 
@@ -60,18 +64,11 @@ export function tokenizeWords(input: string): WordToken[] {
 }
 
 /**
- * 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.
+ * 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[] {
+export function shortestSpanOwners(words: readonly CharRange[], spans: readonly CharRange[]): number[] {
 	return words.map((word) => {
 		let best = -1
 		let bestLen = Infinity

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
+}

package/lib/common/useClipboard.ts

@@ -3,24 +3,17 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `useClipboard` — headless copy-to-clipboard with the async Clipboard API and a legacy
- *   `execCommand` fallback (for insecure contexts / older browsers), plus a transient "copied" flag
- *   that auto-resets. Extracted from the two explorers' duplicated `onCopy` handlers.
+ * `useClipboard` — headless copy-to-clipboard with the async Clipboard API and a legacy `execCommand` fallback for insecure contexts, plus a transient "copied" flag that auto-resets.
  */
 
 import { useCallback, useEffect, useRef, useState } from "react"
 
-/**
- * Best-effort clipboard write: async Clipboard API first, hidden-textarea `execCommand` fallback.
- */
 async function writeToClipboard(value: string): Promise<void> {
 	try {
 		await navigator.clipboard.writeText(value)
 
 		return
-	} catch {
-		// Fall through to the legacy path below.
-	}
+	} catch {}
 
 	const textarea = document.createElement("textarea")
 	textarea.value = value
@@ -32,7 +25,6 @@ async function writeToClipboard(value: string): Promise<void> {
 	try {
 		document.execCommand("copy")
 	} catch {
-		// Nothing else to try — leave `copied` false via the caller's error path.
 	} finally {
 		document.body.removeChild(textarea)
 	}
@@ -50,7 +42,6 @@ export function useClipboard(resetMs = 1500): UseClipboard {
 	const [copied, setCopied] = useState(false)
 	const timer = useRef<ReturnType<typeof setTimeout> | null>(null)
 
-	// Clear a pending reset timer on unmount so it never fires against a torn-down component.
 	useEffect(
 		() => () => {
 			if (timer.current) {

package/lib/common.ts

@@ -0,0 +1,22 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Common React 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 } 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"