@mailwoman/react 10.0.0 → 10.1.0

package/out/map/useMapLabelPick.js

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

package/out/map/useMapLabelPick.js.map

@@ -1 +1 @@
-{"version":3,"file":"useMapLabelPick.js","sourceRoot":"","sources":["../../lib/map/useMapLabelPick.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useMapLabelPick.js","sourceRoot":"","sources":["../../lib/map/useMapLabelPick.ts"],"names":[],"mappings":"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"}

package/out/map/useMapPlaceRender.d.ts

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

package/out/map/useMapPlaceRender.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useMapPlaceRender.d.ts","sourceRoot":"","sources":["../../lib/map/useMapPlaceRender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAE7E;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAAG,kBAAkB,GAAG,IAAI,CAEvG"}
+{"version":3,"file":"useMapPlaceRender.d.ts","sourceRoot":"","sources":["../../lib/map/useMapPlaceRender.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAE7E;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAAG,kBAAkB,GAAG,IAAI,CAEvG"}

package/out/map/useMapPlaceRender.js

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

package/out/map/useMapPlaceRender.js.map

@@ -1 +1 @@
-{"version":3,"file":"useMapPlaceRender.js","sourceRoot":"","sources":["../../lib/map/useMapPlaceRender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAE/B,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAA;AAG7D;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA0C;IAC3E,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,yBAAyB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;AACjF,CAAC"}
+{"version":3,"file":"useMapPlaceRender.js","sourceRoot":"","sources":["../../lib/map/useMapPlaceRender.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAE/B,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAA;AAG7D;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA0C;IAC3E,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,yBAAyB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;AACjF,CAAC"}

package/out/map/usePlaceAutocomplete.d.ts

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

package/out/map/usePlaceAutocomplete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePlaceAutocomplete.d.ts","sourceRoot":"","sources":["../../lib/map/usePlaceAutocomplete.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAoC,MAAM,OAAO,CAAA;AAG5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,MAAM,WAAW,2BAA2B;IAC3C;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IACvD;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,UAAU,CAAA;IAChB,eAAe,EAAE,OAAO,CAAA;IACxB,eAAe,EAAE,MAAM,CAAA;IACvB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,uBAAuB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3C,YAAY,EAAE,KAAK,CAAA;CACnB;AAED,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC;;OAEG;IACH,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAA;IAChE;;OAEG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7B;;OAEG;IACH,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB;;OAEG;IACH,UAAU,EAAE,sBAAsB,CAAA;IAClC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;CACnC;AAyBD,wBAAgB,oBAAoB,CAAC,EACpC,IAAI,EACJ,OAAO,EACP,YAAY,EACZ,QAAY,EACZ,UAAgB,GAChB,EAAE,2BAA2B,GAAG,oBAAoB,CAmHpD"}
+{"version":3,"file":"usePlaceAutocomplete.d.ts","sourceRoot":"","sources":["../../lib/map/usePlaceAutocomplete.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAoC,MAAM,OAAO,CAAA;AAG5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC3C;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;;OAGG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAE/B;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IAEvD;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,UAAU,CAAA;IAChB,eAAe,EAAE,OAAO,CAAA;IACxB,eAAe,EAAE,MAAM,CAAA;IACvB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,uBAAuB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3C,YAAY,EAAE,KAAK,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,WAAW,EAAE,UAAU,EAAE,CAAA;IAEzB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IAEnB;;OAEG;IACH,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAEvC;;OAEG;IACH,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAA;IAEhE;;OAEG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAE7B;;OAEG;IACH,OAAO,EAAE,MAAM,IAAI,CAAA;IAEnB;;OAEG;IACH,UAAU,EAAE,sBAAsB,CAAA;IAElC;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;CACnC;AAeD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EACpC,IAAI,EACJ,OAAO,EACP,YAAY,EACZ,QAAY,EACZ,UAAgB,GAChB,EAAE,2BAA2B,GAAG,oBAAoB,CAyGpD"}

package/out/map/usePlaceAutocomplete.js

@@ -2,52 +2,26 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `usePlaceAutocomplete` — the headless "Did you mean" combobox lifted from the demo god component
- *   (`_app.tsx:820-900`). It walks the host-supplied `autocomplete` over the locality segment the visitor
- *   is typing (the text after the last comma), owns the suggestion list + keyboard-highlighted active
- *   descendant, and rewrites the input on pick (replacing just that segment). No FST, no fetch of its own
- *   — the `autocomplete` fetcher is INJECTED (the package never imports `@mailwoman/resolver-wof-sqlite`),
- *   so this stays node-safe and testable with a synchronous fake.
- *
- *   Returns the `<input>` aria/combobox props to spread onto the reused {@link QueryForm} input plus an
- *   `onInputKeyDown` (↑/↓ move the highlight, Enter accepts it AND suppresses submit, Esc dismisses), and
- *   the presentational {@link PlaceAutocomplete} listbox renders `suggestions` / `activeIndex`.
  */
 import { useCallback, useEffect, useState } from "react";
 import { useDebouncedValue } from "#common/useDebouncedValue";
 const LISTBOX_ID = "mw-demo-suggest-list";
-/**
- * Stable empty list for the derived no-suggestions state — a fresh `[]` per render would churn the identity every
- * consumer and every useCallback dependency list sees.
- */
 const NO_SUGGESTIONS = [];
 const optionID = (index) => `mw-demo-suggest-${index}`;
-/**
- * Extract the locality segment being typed — the text after the last comma, trimmed.
- */
 function localitySegment(text) {
     return (text.includes(",") ? text.slice(text.lastIndexOf(",") + 1) : text).trim();
 }
-/**
- * Replace the locality segment (after the last comma) with `name`, preserving the address prefix.
- */
 function replaceSegment(current, name) {
     return current.includes(",") ? `${current.slice(0, current.lastIndexOf(",") + 1)} ${name}` : name;
 }
+/**
+ * Fetches debounced place suggestions for the text after the input's last comma.
+ *
+ * A pick replaces only that segment.
+ * A digit-leading segment never reaches `autocomplete`.
+ */
 export function usePlaceAutocomplete({ text, setText, autocomplete, minChars = 2, debounceMs = 150, }) {
-    /**
-     * The last COMPLETED fetch, keyed by the query that produced it. Visibility is DERIVED from this during render rather
-     * than pushed through sync setStates in the effect — the effect's only job is the async fetch, so every state write
-     * in it happens after an await and the react(set-state-in-effect) rule is satisfied by structure, not by exception.
-     */
     const [fetched, setFetched] = useState(null);
-    /**
-     * The query whose list was dismissed or picked. Suppression as DATA, replacing the one-shot ref flag: a pick stores
-     * the query the rewritten text will produce, so the post-pick fetch is skipped and the place just chosen is never
-     * re-suggested. One divergence from the ref version, accepted and small: after Esc, retyping the exact same string
-     * keeps the list hidden until the query changes.
-     */
     const [dismissed, setDismissed] = useState(null);
     const [activeIndex, setActiveIndex] = useState(-1);
     const query = localitySegment(text);
@@ -82,7 +56,6 @@ export function usePlaceAutocomplete({ text, setText, autocomplete, minChars = 2
     const pick = useCallback((value) => {
         const next = replaceSegment(text, value);
         setText(next);
-        // Suppress the fetch the rewritten text would trigger — the segment being typed IS the picked name.
         setDismissed(localitySegment(next));
         setFetched(null);
         setActiveIndex(-1);

package/out/map/usePlaceAutocomplete.js.map

@@ -1 +1 @@
-{"version":3,"file":"usePlaceAutocomplete.js","sourceRoot":"","sources":["../../lib/map/usePlaceAutocomplete.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"usePlaceAutocomplete.js","sourceRoot":"","sources":["../../lib/map/usePlaceAutocomplete.ts"],"names":[],"mappings":"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"}

package/out/map.d.ts

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

package/out/map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../lib/map.ts"],"names":[],"mappings":"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"}

package/out/map.js

@@ -0,0 +1,46 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/react/map` — the geocoder map surface, kept behind its own subpath so `maplibre-gl`
+ *   / `react-map-gl` (WebGL + DOM at import) never enter the package-root graph. This subpath import
+ *   pulls the map deps. importing `@mailwoman/react` (root) does not. Consumers who only want the
+ *   parse/POI explorers never pay for maplibre.
+ *
+ *   The host must supply `maplibre-gl` + `react-map-gl` (peer deps) and import
+ *   `maplibre-gl/dist/maplibre-gl.css` + `@mailwoman/react/styles.css` itself.
+ */
+export { MapCanvas } from "./map/MapCanvas.js";
+// ── Map chrome (node-safe presentation. The host supplies the input and reads its own map) ──
+export { MapChipRow } from "./map/MapChipRow.js";
+export { MapCompass } from "./map/MapCompass.js";
+export { useMapBearing } from "./map/useMapBearing.js";
+export { useMapLabelPick } from "./map/useMapLabelPick.js";
+export { MapControlButton, MapControlGroup, MapControlStack } from "./map/MapControlStack.js";
+export { MapFooter } from "./map/MapFooter.js";
+export { MapProgressBar } from "./map/MapProgressBar.js";
+export { MapSheet, SheetClose } from "./map/MapSheet.js";
+export { MapSearchBar, SearchGlyph } from "./map/MapSearchBar.js";
+// ── Pure geometry + render spec (node-safe. No react-map-gl at runtime) ──────
+export { approxCircleGeometry, bboxToBounds, geomBounds, radiusCircleGeometry } from "#map/geometry";
+export { cameraToViewState, computeMapPlaceRenderSpec } from "#map/place-render";
+export { useMapPlaceRender } from "#map/useMapPlaceRender";
+// ── Declarative overlays (react-map-gl `<Marker>`/`<Source>`/`<Layer>`) ──────
+export { OverlayLayers } from "./map/OverlayLayers.js";
+export { PlaceMarker } from "./map/PlaceMarker.js";
+export { ResolvedPlaceLayers } from "./map/ResolvedPlaceLayers.js";
+export { ResultCamera } from "./map/ResultCamera.js";
+export { ResultOverlay } from "./map/ResultOverlay.js";
+// ── Geocoder controls + the composed geocoder ────────────────────────────────
+export { BackendControl } from "./map/BackendControl.js";
+export { CompareToggle } from "./map/CompareToggle.js";
+export { Geocoder } from "./map/Geocoder.js";
+export { GeocoderControls } from "./map/GeocoderControls.js";
+export { PlaceAutocomplete } from "./map/PlaceAutocomplete.js";
+export { ResultPanel } from "./map/ResultPanel.js";
+export { useCompareState } from "#map/useCompareState";
+export { useGeocode } from "#map/useGeocode";
+export { usePlaceAutocomplete } from "#map/usePlaceAutocomplete";
+export { VersionPicker } from "./map/VersionPicker.js";
+//# sourceMappingURL=map.js.map

package/out/map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map.js","sourceRoot":"","sources":["../lib/map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAqB,CAAA;AAG/C,+FAA+F;AAC/F,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAsB,CAAA;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAsB,CAAA;AAEjD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC1D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,0BAA2B,CAAA;AAE9F,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAqB,CAAA;AAE/C,OAAO,EAAE,cAAc,EAAE,MAAM,yBAA0B,CAAA;AAEzD,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,mBAAoB,CAAA;AAEzD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAwB,CAAA;AAgBlE,gFAAgF;AAChF,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAEpG,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAA;AAEhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE1D,gFAAgF;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAyB,CAAA;AAEvD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAuB,CAAA;AAEnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA+B,CAAA;AAEnE,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAwB,CAAA;AAErD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAyB,CAAA;AAGvD,gFAAgF;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,yBAA0B,CAAA;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAyB,CAAA;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAoB,CAAA;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA4B,CAAA;AAE7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA6B,CAAA;AAE/D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAuB,CAAA;AAEnD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAQhE,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAyB,CAAA"}

package/out/pipeline/CandidatePicker.d.ts

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

package/out/pipeline/CandidatePicker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CandidatePicker.d.ts","sourceRoot":"","sources":["../../lib/pipeline/CandidatePicker.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,MAAM,WAAW,oBAAoB;IACpC,UAAU,EAAE,iBAAiB,EAAE,CAAA;IAC/B,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACjC;AAED,wBAAgB,eAAe,CAAC,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE,EAAE,oBAAoB,GAAG,SAAS,CAwBxG"}
+{"version":3,"file":"CandidatePicker.d.ts","sourceRoot":"","sources":["../../lib/pipeline/CandidatePicker.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,MAAM,WAAW,oBAAoB;IACpC,UAAU,EAAE,iBAAiB,EAAE,CAAA;IAC/B,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACjC;AAED,wBAAgB,eAAe,CAAC,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE,EAAE,oBAAoB,GAAG,SAAS,CAsBxG"}

package/out/pipeline/CandidatePicker.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from "#common/cx";
 export function CandidatePicker({ candidates, selectedIndex, onSelect }) {
-    return (_jsxs("div", { className: "mw-candidates", children: [_jsxs("h2", { children: ["Other candidates (", candidates.length - 1, ")"] }), _jsx("ol", { className: "mw-candidates__list", children: candidates.map((candidate, i) => (_jsx("li", { children: _jsxs("button", { type: "button", className: cx("mw-candidates__btn", { "mw-candidates__btn--active": i === selectedIndex }), onClick: () => onSelect(i), title: `${candidate.placetype} • WOF ${candidate.id} • score ${candidate.score.toFixed(3)}`, children: [_jsxs("span", { className: "mw-candidates__rank", children: ["#", i + 1] }), _jsx("span", { className: "mw-candidates__name", children: candidate.name }), _jsxs("span", { className: "mw-candidates__meta", children: [candidate.placetype, " \u00B7 ", candidate.score.toFixed(2)] })] }) }, `${candidate.id}-${i}`))) })] }));
+    return (_jsxs("div", { className: "mw-candidates", children: [_jsxs("h2", { children: ["Other candidates (", candidates.length - 1, ")"] }), _jsx("ol", { className: "mw-candidates__list", children: candidates.map((candidate, i) => (_jsx("li", { children: _jsxs("button", { type: "button", className: cx("mw-candidates__btn", { "mw-candidates__btn--active": i === selectedIndex }), onClick: () => onSelect(i), title: `${candidate.placetype} • WOF ${candidate.id} • score ${candidate.score.toFixed(3)}`, children: [_jsxs("span", { className: "mw-candidates__rank", children: ["#", i + 1] }), _jsx("span", { className: "mw-candidates__name", children: candidate.name }), _jsx("span", { className: "mw-candidates__meta", children: candidate.placetype })] }) }, `${candidate.id}-${i}`))) })] }));
 }
 //# sourceMappingURL=CandidatePicker.js.map

package/out/pipeline/CandidatePicker.js.map

@@ -1 +1 @@
-{"version":3,"file":"CandidatePicker.js","sourceRoot":"","sources":["../../lib/pipeline/CandidatePicker.tsx"],"names":[],"mappings":";AAYA,OAAO,EAAE,EAAE,EAAE,MAAM,YAAY,CAAA;AAQ/B,MAAM,UAAU,eAAe,CAAC,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAwB;IAC5F,OAAO,CACN,eAAK,SAAS,EAAC,eAAe,aAC7B,+CAAuB,UAAU,CAAC,MAAM,GAAG,CAAC,SAAO,EACnD,aAAI,SAAS,EAAC,qBAAqB,YACjC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC,CACjC,uBACC,kBACC,IAAI,EAAC,QAAQ,EACb,SAAS,EAAE,EAAE,CAAC,oBAAoB,EAAE,EAAE,4BAA4B,EAAE,CAAC,KAAK,aAAa,EAAE,CAAC,EAC1F,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,GAAG,SAAS,CAAC,SAAS,UAAU,SAAS,CAAC,EAAE,YAAY,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,aAE3F,gBAAM,SAAS,EAAC,qBAAqB,kBAAG,CAAC,GAAG,CAAC,IAAQ,EACrD,eAAM,SAAS,EAAC,qBAAqB,YAAE,SAAS,CAAC,IAAI,GAAQ,EAC7D,gBAAM,SAAS,EAAC,qBAAqB,aACnC,SAAS,CAAC,SAAS,cAAK,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAC7C,IACC,IAZD,GAAG,SAAS,CAAC,EAAE,IAAI,CAAC,EAAE,CAa1B,CACL,CAAC,GACE,IACA,CACN,CAAA;AACF,CAAC"}
+{"version":3,"file":"CandidatePicker.js","sourceRoot":"","sources":["../../lib/pipeline/CandidatePicker.tsx"],"names":[],"mappings":";AAsBA,OAAO,EAAE,EAAE,EAAE,MAAM,YAAY,CAAA;AAQ/B,MAAM,UAAU,eAAe,CAAC,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAwB;IAC5F,OAAO,CACN,eAAK,SAAS,EAAC,eAAe,aAC7B,+CAAuB,UAAU,CAAC,MAAM,GAAG,CAAC,SAAO,EACnD,aAAI,SAAS,EAAC,qBAAqB,YACjC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC,CACjC,uBACC,kBACC,IAAI,EAAC,QAAQ,EACb,SAAS,EAAE,EAAE,CAAC,oBAAoB,EAAE,EAAE,4BAA4B,EAAE,CAAC,KAAK,aAAa,EAAE,CAAC,EAC1F,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,GAAG,SAAS,CAAC,SAAS,UAAU,SAAS,CAAC,EAAE,YAAY,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,aAE3F,gBAAM,SAAS,EAAC,qBAAqB,kBAAG,CAAC,GAAG,CAAC,IAAQ,EACrD,eAAM,SAAS,EAAC,qBAAqB,YAAE,SAAS,CAAC,IAAI,GAAQ,EAC7D,eAAM,SAAS,EAAC,qBAAqB,YAAE,SAAS,CAAC,SAAS,GAAQ,IAC1D,IAVD,GAAG,SAAS,CAAC,EAAE,IAAI,CAAC,EAAE,CAW1B,CACL,CAAC,GACE,IACA,CACN,CAAA;AACF,CAAC"}

package/out/pipeline/ConfidenceCell.d.ts

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

package/out/pipeline/ConfidenceCell.js

@@ -4,7 +4,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `ConfidenceCell` — a compact confidence bar + value for the component table. The fill colour follows the shared
+ *   `ConfidenceCell` — a compact confidence bar + value for the component table. The fill color follows the shared
  *   confidence tiers. Presentational.
  */
 import { confidenceTierOrMid } from "#common/confidence-tiers";

package/out/pipeline/FailureDiagnostic.d.ts

@@ -3,13 +3,19 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `FailureDiagnostic` — what to say when nothing resolved. It reads the parsed components and names the missing
- *   piece a person can add (a city, a state), so the answer is a next step rather than "no hit".
+ *   Explains a query that resolved to no place and suggests which component, such as a city or a
+ *   state, the visitor could add.
  */
 import type { ParsedComponent } from "@mailwoman/core/pipeline/client-result";
 import type { ReactNode } from "react";
+/**
+ * Props for {@link FailureDiagnostic}.
+ */
 export interface FailureDiagnosticProps {
     nodes: ParsedComponent[];
 }
+/**
+ * Renders hints based on which components the parser found.
+ */
 export declare function FailureDiagnostic({ nodes }: FailureDiagnosticProps): ReactNode;
 //# sourceMappingURL=FailureDiagnostic.d.ts.map

package/out/pipeline/FailureDiagnostic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FailureDiagnostic.d.ts","sourceRoot":"","sources":["../../lib/pipeline/FailureDiagnostic.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,MAAM,WAAW,sBAAsB;IACtC,KAAK,EAAE,eAAe,EAAE,CAAA;CACxB;AAED,wBAAgB,iBAAiB,CAAC,EAAE,KAAK,EAAE,EAAE,sBAAsB,GAAG,SAAS,CAuC9E"}
+{"version":3,"file":"FailureDiagnostic.d.ts","sourceRoot":"","sources":["../../lib/pipeline/FailureDiagnostic.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAA;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,KAAK,EAAE,eAAe,EAAE,CAAA;CACxB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,KAAK,EAAE,EAAE,sBAAsB,GAAG,SAAS,CAuC9E"}

package/out/pipeline/FailureDiagnostic.js

@@ -1,4 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Renders hints based on which components the parser found.
+ */
 export function FailureDiagnostic({ nodes }) {
     const hasLocality = nodes.some((n) => n.tag === "locality");
     const hasPostcode = nodes.some((n) => n.tag === "postcode");