@mailwoman/react 9.4.0 → 10.1.0

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"

package/lib/index.ts

@@ -2,120 +2,35 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `@mailwoman/react` — React components + headless hooks for mailwoman.
- *
- *   Two composed explorers plus the small presentational units and headless hooks they decompose into:
- *
- *   - `POIExplorer` — a self-contained POI-intent tester (classify → subject → OverpassQL), with an
- *     optional injected live poi.db search. No weights, no network on the intent path.
- *   - `PipelineExplorer` — a parse+resolve tester driven by an INJECTED `PipelineRuntime`, so the
- *     model/gazetteer plumbing (ONNX, httpvfs, node builtins) stays in the host, never in this graph.
- *
- *   Styling ships separately as `@mailwoman/react/styles.css` (plain, `mw-`-prefixed, Infima-token
- *   aware) — no CSS is imported by the component modules, so the bare package import is node-safe.
  */
 
-// ── Common primitives ──────────────────────────────────────────────────────
-export { ClientOnly } from "./common/ClientOnly.tsx"
-export type { ClientOnlyProps } from "./common/ClientOnly.tsx"
-export { CopyButton } from "./common/CopyButton.tsx"
-export type { CopyButtonProps } from "./common/CopyButton.tsx"
-export { cx } from "#common/cx"
-export type { ClassValue } from "#common/cx"
-export { KindBadge } from "./common/KindBadge.tsx"
-export type { KindBadgeProps } 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"
-
-// ── POI explorer ───────────────────────────────────────────────────────────
-export { AbstainPanel } from "./poi/AbstainPanel.tsx"
-export type { AbstainPanelProps } from "./poi/AbstainPanel.tsx"
-export { LiveResultsBlock } from "./poi/LiveResultsBlock.tsx"
-export type { LiveResultsBlockProps } from "./poi/LiveResultsBlock.tsx"
-export { OverpassBlock } from "./poi/OverpassBlock.tsx"
-export type { OverpassBlockProps } from "./poi/OverpassBlock.tsx"
-export { POIExplorer } from "./poi/POIExplorer.tsx"
-export type { POIExplorerProps } from "./poi/POIExplorer.tsx"
-export { QueryInput } from "./poi/QueryInput.tsx"
-export type { QueryInputProps } from "./poi/QueryInput.tsx"
-export { formatDistance, loadPOIRuntime, POI_DEFAULT_TEXT, POI_PRESETS } from "#poi/runtime"
-export { SubjectPanel } from "./poi/SubjectPanel.tsx"
-export type { SubjectPanelProps } from "./poi/SubjectPanel.tsx"
-
-export type {
-	CategoryRecord,
-	LiveSearchState,
-	LoadPOIRuntime,
-	POIBrandSubject,
-	POICategorySubject,
-	POIExplorerResult,
-	POILiveSearch,
-	POILiveSearchResult,
-	POIRuntime,
-	POISearchHit,
-	POISubject,
-	POISubjectBase,
-	TaxonomyLookup,
-} from "#poi/types"
-
-export { usePOISearch } from "#poi/usePOISearch"
-export type { UsePOISearch, UsePOISearchOptions } from "#poi/usePOISearch"
-
-// ── Result visualizers ─────────────────────────────────────────────────────
-
-export { About } from "./common/About.tsx"
-export { FailureDiagnostic } from "./pipeline/FailureDiagnostic.tsx"
-export type { FailureDiagnosticProps } from "./pipeline/FailureDiagnostic.tsx"
-export { SpanHighlight } from "./pipeline/SpanHighlight.tsx"
-export type { SpanHighlightProps } from "./pipeline/SpanHighlight.tsx"
-export { TimingPanel } from "./pipeline/TimingPanel.tsx"
-export type { TimingPanelProps } from "./pipeline/TimingPanel.tsx"
-export { TreeView } from "./pipeline/TreeView.tsx"
-export type { TreeViewProps } from "./pipeline/TreeView.tsx"
-
-// ── Pipeline explorer ──────────────────────────────────────────────────────
-export { CandidatePicker } from "./pipeline/CandidatePicker.tsx"
-export type { CandidatePickerProps } from "./pipeline/CandidatePicker.tsx"
-export { ComponentTable } from "./pipeline/ComponentTable.tsx"
-export type { ComponentTableProps } from "./pipeline/ComponentTable.tsx"
-export { ConfidenceCell } from "./pipeline/ConfidenceCell.tsx"
-export type { ConfidenceCellProps } from "./pipeline/ConfidenceCell.tsx"
-export { buildParsePayload } from "#pipeline/copy"
-export { PIPELINE_DEFAULT_ADDRESS, PIPELINE_PRESETS } from "#pipeline/presets"
-export { PipelineExplorer } from "./pipeline/PipelineExplorer.tsx"
-export type { PipelineExplorerProps } from "./pipeline/PipelineExplorer.tsx"
-export { QueryForm } from "./pipeline/QueryForm.tsx"
-export type { QueryFormProps } from "./pipeline/QueryForm.tsx"
-export { ResolvedPlace } from "./pipeline/ResolvedPlace.tsx"
-export type { ResolvedPlaceProps } from "./pipeline/ResolvedPlace.tsx"
-
-export type { PipelineLoadingState, PipelinePanels, PipelineRuntime } from "#pipeline/types"
-
-export { useParsePipeline } from "#pipeline/useParsePipeline"
-export type { UseParsePipeline, UseParsePipelineOptions } from "#pipeline/useParsePipeline"
-
-// ── Release runtime (shared load orchestration; node-safe — no onnx/httpvfs/maplibre) ──
-export { useReleaseRuntime } from "#runtime/useReleaseRuntime"
-
-export type {
-	AssetsLoadContext,
-	ReleaseBase,
-	ReleaseLoaderState,
-	ReleaseManifest,
-	ReleaseRuntimeConfig,
-} from "#runtime/useReleaseRuntime"
+/**
+ * Re-exports the shared presentational components and hooks that both explorers are built from.
+ *
+ * No module in the root graph imports CSS, so the bare package import is Node-safe
+ * and hosts load `@mailwoman/react/styles.css` themselves.
+ */
+export * from "#common"
+/**
+ * Re-exports `POIExplorer`, a POI-intent tester that needs no weights or network, with its related exports.
+ */
+export * from "#poi"
+/**
+ * Re-exports `PipelineExplorer`, a parse-and-resolve tester with model
+ * and gazetteer access injected by the host.
+ * It also exports the explorer's related declarations.
+ */
+export * from "#pipeline"
+/**
+ * Re-exports `useReleaseRuntime`, the Node-safe hook that loads a release manifest
+ * and each selected version's assets through a host-injected loader.
+ */
+export * from "#runtime"
 
-// ── Map (types only from root) ──────────────────────────────────────────────
-// The map SURFACE lives behind the `@mailwoman/react/map` subpath so `maplibre-gl` / `react-map-gl`
-// (WebGL + DOM at import) never enter the package-root graph — a bare `import("@mailwoman/react")` in node
-// must not pull them. Only the CONTRACT types are re-exported here (fully erased at compile time, so no
-// runtime linkage): the `MapCanvas` component + hooks are import-able solely via `@mailwoman/react/map`.
+/**
+ * Re-exports the map surface's types only, because its runtime lives behind the
+ * `@mailwoman/react/map` subpath so that MapLibre stays out of the root import graph.
+ */
 export type {
 	GeocoderRuntime,
 	InferenceBackend,
@@ -127,4 +42,4 @@ export type {
 	OverlaySpec,
 	Suggestion,
 	VersionOption,
-} from "#map/index"
+} from "#map"

package/lib/map/AppIdentity.tsx

@@ -0,0 +1,85 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Renders the footer identity with the app name, an optional documentation link and the build
+ *   commit. This component does not depend on the map.
+ */
+
+import type { ReactNode } from "react"
+
+import { useBuildInfo } from "#common/useBuildInfo"
+
+/**
+ * The number of commit characters shown in the footer.
+ */
+const DISPLAYED_LENGTH = 6
+
+/**
+ * Props for {@link AppIdentity}.
+ */
+export interface AppIdentityProps {
+	/**
+	 * The app's display name, such as `Mailwoman Earth`.
+	 */
+	name: ReactNode
+	/**
+	 * The documentation link's target.
+	 * The link is omitted when this is unset.
+	 */
+	docsURL?: string
+	/**
+	 * The documentation link's text. @default "Developer Documentation"
+	 */
+	docsLabel?: string
+	/**
+	 * The URL of the build record. @default "/build.json"
+	 */
+	buildInfoURL?: string
+	/**
+	 * Builds the commit link.
+	 * Without it, the commit is shown as plain text.
+	 */
+	commitHref?: (commit: string) => string
+}
+
+/**
+ * Renders the app name, documentation link and short build commit.
+ * The commit is omitted when no build record loads.
+ */
+export function AppIdentity({
+	name,
+	docsURL,
+	docsLabel = "Developer Documentation",
+	buildInfoURL,
+	commitHref,
+}: AppIdentityProps): ReactNode {
+	const build = useBuildInfo(buildInfoURL)
+	const commit = build?.commit
+
+	return (
+		<>
+			<strong>{name}</strong>
+			{docsURL ? (
+				<>
+					{" "}
+					<a href={docsURL}>{docsLabel}</a>
+				</>
+			) : null}
+			{commit ? (
+				<>
+					{" ("}
+					{commitHref ? (
+						<a href={commitHref(commit)} title={`Built from ${commit}`}>
+							<code>{commit.slice(0, DISPLAYED_LENGTH)}</code>
+						</a>
+					) : (
+						<code title={`Built from ${commit}`}>{commit.slice(0, DISPLAYED_LENGTH)}</code>
+					)}
+					{")"}
+				</>
+			) : null}
+		</>
+	)
+}

package/lib/map/BackendControl.tsx

@@ -3,44 +3,47 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `<BackendControl>` — the neural-backend indicator + "Force WASM" checkbox from the demo's control
- *   panel (`_app.tsx:1255-1280`), as a dumb presentational unit. It shows which backend the runtime
- *   resolved to (WebGPU / WASM, with the int8 size the host formats into the label) and lets the visitor
- *   opt out of WebGPU. Props in, one boolean event out — the host re-loads the bundle on the toggle.
- *
- *   NODE-SAFE: pure React, no maplibre.
+ *   Shows the active inference backend and a checkbox that forces WASM. The host applies the change.
  */
 
 import type { ReactNode } from "react"
 
+/**
+ * Props for {@link BackendControl}.
+ */
 export interface BackendControlProps {
 	/**
-	 * The backend the runtime resolved to (e.g. `webgpu (28 MB int8)`); empty before it is known.
+	 * The backend the runtime chose, such as `webgpu (28 MB int8)`.
+	 * It is empty until known.
 	 */
 	activeBackend?: string
 	/**
-	 * Whether the CPU/WASM backend is currently forced.
+	 * Whether the WASM backend is forced.
 	 */
 	forceWASM: boolean
 	/**
-	 * Fired when the visitor toggles the "Force WASM" checkbox.
+	 * Called when the visitor toggles the "Force WASM" checkbox.
 	 */
 	onForceWASMChange: (forceWASM: boolean) => void
 }
 
 /**
- * The backend indicator + WASM opt-out.
+ * Renders the backend indicator and the "Force WASM" checkbox.
  */
 export function BackendControl({ activeBackend, forceWASM, onForceWASMChange }: BackendControlProps): ReactNode {
 	return (
 		<div className="mw-demo-backend">
+			<span className="mw-map-sheet__label">Inference backend</span>
+
 			{activeBackend ? (
 				<span className="mw-demo-backend__active">
-					Backend: <code>{activeBackend}</code>
+					Running on <code>{activeBackend}</code>
 				</span>
 			) : null}
-			<label className="mw-demo-backend__toggle">
-				<input type="checkbox" checked={forceWASM} onChange={(e) => onForceWASMChange(e.target.checked)} /> Force WASM
+
+			<label className="mw-map-sheet__check mw-demo-backend__toggle">
+				<input type="checkbox" checked={forceWASM} onChange={(event) => onForceWASMChange(event.target.checked)} />
+				Force WASM
 			</label>
 		</div>
 	)

package/lib/map/CompareToggle.tsx

@@ -3,55 +3,32 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `<CompareToggle>` — the "Compare" checkbox plus the compare-version `<select>` from the demo's
- *   control panel (`_app.tsx:1281-1339`), as a dumb presentational unit. Turning it on reveals a second
- *   version picker (the primary version filtered out); the actual second parse is a host concern the
- *   composed demo surfaces through `panels.compare`. Props in, two events out.
- *
- *   NODE-SAFE: pure React, no maplibre.
+ * Renders a compare-mode checkbox and a selector for the second model version, leaving the comparison itself to the host.
  */
 
 import type { ReactNode } from "react"
 
 import type { VersionOption } from "#map/types"
 
+/**
+ * Props for {@link CompareToggle}.
+ */
 export interface CompareToggleProps {
-	/**
-	 * The selectable model bundles (the primary version is filtered out of the compare list).
-	 */
 	versions: ReadonlyArray<VersionOption>
-	/**
-	 * The primary version, excluded from the compare options.
-	 */
 	primaryVersion: string | null
-	/**
-	 * Whether compare mode is on.
-	 */
 	compareMode: boolean
-	/**
-	 * Fired when the visitor flips compare mode.
-	 */
 	onCompareModeChange: (compareMode: boolean) => void
-	/**
-	 * The version chosen to compare against, or `null` when none is chosen.
-	 */
 	compareVersion: string | null
-	/**
-	 * Fired with the chosen compare version (or `null` when the empty option is picked).
-	 */
 	onCompareVersionChange: (version: string | null) => void
-	/**
-	 * Disable the compare-version select (e.g. while a parse or compare load runs).
-	 */
 	disabled?: boolean
-	/**
-	 * A status line rendered under the select (e.g. the compare backend, or a "Loading…" line).
-	 */
 	status?: ReactNode
 }
 
 /**
- * The compare toggle + (when on) the compare-version selector. Renders `null` with fewer than two versions.
+ * Renders the compare checkbox.
+ *
+ * In compare mode, it also renders the version selector. and no control at all
+ * when fewer than two versions exist.
  */
 export function CompareToggle({
 	versions,
@@ -69,8 +46,9 @@ export function CompareToggle({
 
 	return (
 		<div className="mw-demo-compare">
-			<label className="mw-demo-compare__toggle">
-				<input type="checkbox" checked={compareMode} onChange={(e) => onCompareModeChange(e.target.checked)} /> Compare
+			<label className="mw-map-sheet__check mw-demo-compare__toggle">
+				<input type="checkbox" checked={compareMode} onChange={(event) => onCompareModeChange(event.target.checked)} />
+				Compare two model versions
 			</label>
 			{compareMode ? (
 				<div className="mw-demo-control">

package/lib/map/DebugInfo.tsx

@@ -0,0 +1,88 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Display and log build, model and runtime details for bug reports.
+ *   Report the actual execution backend because successful loading does not imply WebGPU ran.
+ */
+
+import { type ReactNode, useEffect, useMemo } from "react"
+
+import { useBuildInfo } from "#common/useBuildInfo"
+
+export interface DebugInfoProps {
+	/**
+	 * The backend the runtime resolved to (e.g. `webgpu (28 MB int8)`); empty before it is known.
+	 */
+	activeBackend?: string
+	/**
+	 * Whether the CPU/wasm backend is currently forced.
+	 *
+	 * This explains a `wasm` backend that would otherwise indicate a WebGPU failure.
+	 */
+	forceWASM?: boolean
+	/**
+	 * The model version the runtime loaded.
+	 *
+	 * The training series.
+	 * It differs from the npm version.
+	 */
+	selectedVersion?: string | null
+	/**
+	 * Whether the asset bundle finished loading.
+	 */
+	ready?: boolean
+}
+
+/**
+ * One row of the record, as a label and a value.
+ */
+function Row({ label, value }: { label: string; value: string }): ReactNode {
+	return (
+		<div className="mw-debug-info__row">
+			<span className="mw-debug-info__label">{label}</span>
+			<code className="mw-debug-info__value">{value}</code>
+		</div>
+	)
+}
+
+export function DebugInfo({ activeBackend, forceWASM, selectedVersion, ready }: DebugInfoProps): ReactNode {
+	const build = useBuildInfo()
+
+	// Memoized on the primitives it reads, so the log below fires when a value changes
+	// rather than on every render.
+	// A record rebuilt each render would be a new object each time and log continuously.
+	const record = useMemo(
+		() => ({
+			app: build?.app ?? "—",
+			commit: build?.commit ?? build?.revision ?? "—",
+			buildTime: build?.buildTime ?? "—",
+			model: selectedVersion ?? "—",
+			backend: activeBackend || (ready ? "unknown" : "loading…"),
+			forceWASM: Boolean(forceWASM),
+			webgpuInBrowser: typeof navigator !== "undefined" && "gpu" in navigator,
+			userAgent: typeof navigator !== "undefined" ? navigator.userAgent : "—",
+		}),
+		[build?.app, build?.commit, build?.revision, build?.buildTime, selectedVersion, activeBackend, forceWASM, ready]
+	)
+
+	useEffect(() => {
+		// eslint-disable-next-line no-console -- this is the feature: the record has to reach the console a reporter copies.
+		console.info("[mailwoman] debug info", record)
+	}, [record])
+
+	return (
+		<div className="mw-debug-info">
+			<Row label="Build" value={record.app} />
+			<Row label="Commit" value={record.commit.slice(0, 12)} />
+			<Row label="Built" value={record.buildTime} />
+			<Row label="Model" value={record.model} />
+			<Row label="Backend" value={record.backend} />
+			{/* A browser with no WebGPU at all explains a `wasm` backend that is otherwise indistinguishable from a
+			    WebGPU session that threw. */}
+			<Row label="WebGPU available" value={record.webgpuInBrowser ? "yes" : "no"} />
+			<Row label="Force WASM" value={record.forceWASM ? "on" : "off"} />
+		</div>
+	)
+}