@mailwoman/react 10.0.0 → 10.1.0

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,33 +3,32 @@
  * @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 (

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,

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

package/lib/map/Geocoder.tsx

@@ -2,21 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `<Geocoder>` — the WHOLE geocoder, composed. It is the map analogue of `PipelineExplorer`
- *   and takes the SAME DI shape: an injected {@link GeocoderRuntime} (the host owns ONNX / httpvfs / R2 /
- *   the composed map style) plus a {@link GeocoderPanels} bag (the host's ModelVisualizer / VersionCompare /
- *   About / Permalink). Everything here is composition + a `ClientOnly` boundary:
- *
- *     - the floating {@link GeocoderControls} panel (version / compare / backend / query+autocomplete / result),
- *     - the declarative {@link MapCanvas} with the phase-2 overlays ({@link OverlayLayers}) and the
- *       resolved-place marker/outline/camera ({@link ResolvedPlaceLayers}) driven by the parse state,
- *     - the hooks that wire them: {@link useGeocode} (parse + viewport bias + map place),
- *       {@link usePlaceAutocomplete}, {@link useCompareState}.
- *
- *   Because it pulls {@link MapCanvas} (→ `react-map-gl` → `maplibre-gl`, WebGL + DOM at import), it lives on
- *   the `@mailwoman/react/map` subpath ONLY — never the package root. The whole thing renders in Storybook
- *   over a fake runtime (offline stub style + canned geocode) with no network, no ONNX, no gazetteer.
  */
 
 import { type ReactNode, useCallback, useEffect, useRef, useState } from "react"
@@ -31,46 +16,69 @@ import { usePlaceAutocomplete } from "#map/usePlaceAutocomplete"
 import { ClientOnly } from "../common/ClientOnly.tsx"
 import type { Preset } from "../common/PresetChips.tsx"
 import { GeocoderControls } from "./GeocoderControls.tsx"
+import { GraticuleLayer } from "./GraticuleLayer.tsx"
 import { MapCanvas } from "./MapCanvas.tsx"
 import { OverlayLayers } from "./OverlayLayers.tsx"
 import { ResolvedPlaceLayers } from "./ResolvedPlaceLayers.tsx"
 
+/**
+ * Props for {@linkcode Geocoder}.
+ */
 export interface GeocoderProps {
 	/**
-	 * The injected geocoder runtime (map style + overlays + parse + version/backend).
+	 * The geocoder runtime supplies the map style and overlays.
+	 *
+	 * It also supplies the parser and version and backend controls.
 	 */
 	runtime: GeocoderRuntime
 	/**
-	 * Host-injected panels (about, release blurb, compare, permalink, debug drawer, map controls, …).
+	 * Panels supplied by the host.
 	 */
 	panels?: GeocoderPanels
 	/**
-	 * Address to pre-fill.
+	 * The address that pre-fills the search field.
+	 * It is not run automatically.
 	 */
 	defaultAddress?: string
 	/**
-	 * Example chips. @default the empty set (host supplies its own).
+	 * A query to run once when the runtime is ready, such as a permalink's `?q=` value.
+	 *
+	 * Unlike {@link GeocoderProps.defaultAddress}, this query is submitted,
+	 * so a shared link reproduces its result.
+	 */
+	initialQuery?: string | null
+	/**
+	 * The example chips.
+	 *
+	 * @default []
 	 */
 	presets?: ReadonlyArray<Preset>
 	/**
-	 * Open the developer disclosure on mount — the model version, the backend readout and compare. Collapsed by default
-	 * so the address field is the first thing a visitor meets. @default false
+	 * Whether the developer panel starts open.
+	 *
+	 * @default false
 	 */
 	developer?: boolean
 	/**
-	 * Fired with the query each time one is submitted. The host writes it into its own URL — this package never touches
-	 * `location`, because which parameter carries a query is the app's decision.
+	 * Called with each user-submitted query.
+	 *
+	 * The host decides how to write the query to its URL.
+	 * This package never touches `location`.
 	 */
 	onSubmitQuery?: (query: string) => void
 	/**
-	 * Only hint the viewport bias once the visitor has zoomed past the global view — a whole-globe center is noise.
-	 * Matches the `map.getZoom() >= 4` threshold. @default 4
+	 * The minimum map zoom at which the viewport is sent as a location bias.
+	 *
+	 * @default 4
 	 */
 	minBiasZoom?: number
 	/**
-	 * Fly/fit the map to the resolved place on each result (via {@link ResolvedPlaceLayers}). @default true. Set false
-	 * for a host that drives the camera itself (a controlled `<MapCanvas viewState>`), or to keep a headless test
-	 * deterministic — the marker + outline still render, only the animated camera move is skipped.
+	 * Whether the map moves to each resolved place.
+	 *
+	 * Set it to false when the host controls the camera or a test needs a fixed view.
+	 * The marker and outline render either way.
+	 *
+	 * @default true
 	 */
 	applyResultCamera?: boolean
 }
@@ -80,6 +88,7 @@ interface GeocoderInnerProps extends Required<
 > {
 	panels: GeocoderPanels
 	presets: ReadonlyArray<Preset>
+	initialQuery: string | null
 	onSubmitQuery?: (query: string) => void
 }
 
@@ -91,23 +100,25 @@ function GeocoderInner({
 	minBiasZoom,
 	applyResultCamera,
 	developer,
+	initialQuery,
 	onSubmitQuery,
 }: GeocoderInnerProps): ReactNode {
 	const mapRef = useRef<MapRef>(null)
-	// The chrome sits OUTSIDE `<MapCanvas>`, so it cannot take the handle from `useMap()`. A ref alone does not
-	// re-render the compass or the layer control when the map arrives, so the same poll that publishes the test
-	// handle also puts it in state — one poll, two consumers.
+	// The controls render outside `<MapCanvas>` and cannot call `useMap()`.
+	// The map is kept in state so they re-render when it loads.
 	const [map, setMap] = useState<ReturnType<MapRef["getMap"]> | null>(null)
 
-	// The map announces itself; nothing polls for it. `onLoad` carries the instance, so the compass and the layer
-	// control render on the frame the map is ready rather than up to an interval later.
-	//
-	// TEST INJECTION POINT: the e2e viewport-bias suite drives the REAL map (pan + zoom past the bias threshold)
-	// before submitting, and a browser test cannot reach a React ref — so the same handle is republished on
-	// `globalThis.__mailwomanMapCanvas`, and cleared on unmount so a torn-down geocoder leaves no stale handle.
+	// The graticule is inserted before the first non-background layer, so it draws under the data layers.
+	const [baseLayerID, setBaseLayerID] = useState<string | undefined>(undefined)
+
 	const onMapLoad = useCallback((event: { target: ReturnType<MapRef["getMap"]> }) => {
+		// Browser tests read the map from this global.
 		;(globalThis as { __mailwomanMapCanvas?: ReturnType<MapRef["getMap"]> }).__mailwomanMapCanvas = event.target
 		setMap(event.target)
+
+		const layers = event.target.getStyle()?.layers ?? []
+
+		setBaseLayerID(layers.find((layer) => layer.type !== "background")?.id)
 	}, [])
 
 	useEffect(
@@ -118,8 +129,6 @@ function GeocoderInner({
 		[]
 	)
 
-	// Read the viewport bias at submit time — through the map handle, never a threaded state value, so granting/zooming
-	// mid-session doesn't re-create the parse callback. Below the min-bias zoom, a whole-globe center is noise → null.
 	const getBias = useCallback((): MapBias | null => {
 		const live = mapRef.current?.getMap()
 
@@ -165,10 +174,11 @@ function GeocoderInner({
 						zoom: runtime.initialZoom ?? 3,
 					}}
 					style={{ width: "100%", height: "100%" }}
-					// One compact attribution pill (the map's own default is a wide, always-open "MapLibre | © …" bar), no
-					// maplibre wordmark logo.
+					// The attribution is compact.
+					// The MapLibre logo is hidden.
 					mapProps={{ attributionControl: { compact: true }, maplibreLogo: false, onLoad: onMapLoad }}
 				>
+					<GraticuleLayer beforeID={baseLayerID} />
 					<OverlayLayers overlays={runtime.overlays} />
 					<ResolvedPlaceLayers spec={spec} applyCamera={applyResultCamera} />
 					{panels.mapControls}
@@ -183,26 +193,28 @@ function GeocoderInner({
 				panels={panels}
 				presets={presets}
 				placeholder={defaultAddress}
+				initialQuery={initialQuery}
 				map={map}
 				onSubmitQuery={onSubmitQuery}
 				onSelectVersion={onSelectVersion}
 				onForceWASMChange={onForceWASMChange}
 				developer={developer}
 			/>
-
 			{panels.debugDrawer ? panels.debugDrawer({ result: geocode.result }) : null}
 		</div>
 	)
 }
 
-/**
- * Stable empty defaults — a fresh `{}`/`[]` per render would churn every downstream memo dep.
- */
+// These defaults are module constants so each render sees the same reference and memo dependencies stay stable.
 const NO_PANELS: GeocoderPanels = {}
 const NO_PRESETS: ReadonlyArray<Preset> = []
 
 /**
- * The composed geocoder, behind a `ClientOnly` SSR boundary (the map is intrinsically a client component).
+ * Renders the map and search controls as one geocoder.
+ * It also renders host panels.
+ *
+ * It renders only on the client because MapLibre needs browser APIs.
+ * Import it from `@mailwoman/react/map`.
  */
 export function Geocoder({
 	runtime,
@@ -212,6 +224,7 @@ export function Geocoder({
 	minBiasZoom = 4,
 	applyResultCamera = true,
 	developer = false,
+	initialQuery = null,
 	onSubmitQuery,
 }: GeocoderProps): ReactNode {
 	return (
@@ -231,6 +244,7 @@ export function Geocoder({
 					minBiasZoom={minBiasZoom}
 					applyResultCamera={applyResultCamera}
 					developer={developer}
+					initialQuery={initialQuery}
 					onSubmitQuery={onSubmitQuery}
 				/>
 			)}