@mailwoman/react 10.0.0 → 10.2.0

package/out/map/place-render.js

@@ -2,49 +2,22 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `computeMapPlaceRenderSpec` — the PURE core that replaces the docs demo's ~100-line imperative
- *   marker/bbox/camera redraw effect (`_app.tsx:601-705`). It takes an ALREADY-RESOLVED place (the async
- *   polygon-DB fetch is a host/runtime concern — a later phase — so a crisp polygon arrives pre-fetched
- *   as `place.geometry`) and returns a declarative render spec: the marker position(s), the outline
- *   geometry to draw, and the camera target. No map instance, no DOM, no `react-map-gl` — so it is
- *   node-testable (see `place-render.node.test.ts`). The declarative components in this folder render
- *   the spec; a controlled-viewport consumer applies the camera.
- *
- *   The decision cascade is a faithful, side-effect-free transcription of the imperative effect:
- *     1. street tier (situs / interp)  → exact-radius circle, fly to a tight zoom
- *     2. crisp admin polygon (pre-fetched) → draw the polygon, fit its bounds
- *     3. anchor-centroid postcode (no bbox) → ~3 km "around here" circle, fly to zoom 11
- *     4. bbox with real extent            → bbox-sized approximate circle, fit the bbox
- *     5. bare point                       → no outline, fly to zoom 12
  */
 import { approxCircleGeometry, bboxToBounds, geomBounds, radiusCircleGeometry } from "#map/geometry";
-/**
- * Zoom levels the imperative effect flew to, kept named so the cascade reads as intent, not magic numbers.
- */
 const ZOOM = {
     addressPoint: 17,
     interpolated: 15,
     postcode: 11,
     point: 12,
 };
-/**
- * Padding (px) `fitBounds` insets a fitted box by, matching the ported effect.
- */
 const FIT_PADDING = 40;
-/**
- * The minimum lat/lon span (degrees) a bbox must exceed to be treated as a real extent rather than a point.
- */
 const MIN_EXTENT_DEG = 0.001;
 /**
- * Map a resolved place to its declarative render spec. Pure — same input, same output, no side effects. The `place`
- * arrives fully resolved (crisp polygon pre-fetched into `place.geometry` when available), so this is the honest
- * inverse of the old redraw effect with the imperative map mutation and the async DB load removed.
+ * Computes the markers, outline and camera target for a resolved place without loading data,
+ * so the caller must put any fetched polygon in `place.geometry` first.
  */
 export function computeMapPlaceRenderSpec(place) {
     const markers = [[place.lon, place.lat]];
-    // 1. Street tier (#377): the honest uncertainty circle (exact meter radius) + a tight zoom. Takes precedence over
-    //    the admin polygon/bbox paths — a precise point gets no admin boundary.
     if (place.tier && place.uncertaintyM != null) {
         return {
             markers,
@@ -56,7 +29,6 @@ export function computeMapPlaceRenderSpec(place) {
             },
         };
     }
-    // 2. Crisp admin polygon (host pre-fetched it from the polygon DB) — draw the real boundary and fit it.
     if (place.geometry) {
         return {
             markers,
@@ -64,8 +36,6 @@ export function computeMapPlaceRenderSpec(place) {
             camera: { kind: "bounds", bounds: bboxToBounds(geomBounds(place.geometry)), padding: FIT_PADDING },
         };
     }
-    // 3. Anchor-centroid postcode: no bbox, no polygon — a default ~3 km circle says "approximately here" without
-    //    inventing a boundary.
     if (!place.bbox && place.placetype === "postcode") {
         return {
             markers,
@@ -73,8 +43,6 @@ export function computeMapPlaceRenderSpec(place) {
             camera: { kind: "center", center: [place.lon, place.lat], zoom: ZOOM.postcode },
         };
     }
-    // 4. A bbox with real extent — draw an approximate CIRCLE sized from the bbox (a rectangle would read as a wrong,
-    //    real boundary) and fit the bbox.
     const bbox = place.bbox;
     if (bbox && Math.max(bbox.maxLat - bbox.minLat, bbox.maxLon - bbox.minLon) > MIN_EXTENT_DEG) {
         return {
@@ -83,7 +51,6 @@ export function computeMapPlaceRenderSpec(place) {
             camera: { kind: "bounds", bounds: bboxToBounds(bbox), padding: FIT_PADDING },
         };
     }
-    // 5. A bare point (no tier, no polygon, no meaningful bbox) — just a marker and a mid zoom.
     return {
         markers,
         outline: null,
@@ -91,10 +58,8 @@ export function computeMapPlaceRenderSpec(place) {
     };
 }
 /**
- * The DECLARATIVE camera path: reshape a `center` target into a `viewState` patch a controlled `<MapCanvas viewState>`
- * can apply directly (a hard jump, no animation). Returns `null` for a `bounds` target — fitting a box to the viewport
- * needs the map's pixel dimensions, which only the live map has, so that case is applied imperatively by
- * `<ResultCamera>`. Pure + node-testable.
+ * Converts a `center` camera target into a `viewState` patch for a controlled `<MapCanvas>`,
+ * returning `null` for a `bounds` target that `<ResultCamera>` must fit imperatively.
  */
 export function cameraToViewState(camera) {
     if (camera.kind !== "center")

package/out/map/place-render.js.map

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

package/out/map/types.d.ts

@@ -3,16 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Types for the geocoder map surface. Mirrors the pipeline boundary: the package owns the UI state
- *   machine + the declarative map, while the host injects a {@link GeocoderRuntime} that owns ONNX / httpvfs
- *   / R2 and the composed map style. {@link GeocoderRuntime} EXTENDS {@link PipelineRuntime} so the shared
- *   `runParse` / `parseStageLabels` / `loading` contract is reused, and adds the map-specific surface
- *   (style, overlays, initial center, viewport bias, backend/version selection). Phase 4 adds the
- *   `resolveMapPlace` enricher, the {@link GeocoderPanels} injection bag, and the {@link CompareContext}.
- *
- *   The map-spec types are imported type-only from `react-map-gl/maplibre`; nothing here loads maplibre at
- *   runtime, so this module stays node-safe (its concrete-value CONSUMERS — `MapCanvas`, `Geocoder` —
- *   are the ones behind the `@mailwoman/react/map` subpath).
+ *   Types for the geocoder map surface. Its `react-map-gl/maplibre` imports are type-only, so the module stays node-safe.
  */
 import type { ParseResult, ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result";
 import type { ReactNode } from "react";
@@ -21,48 +12,33 @@ import type { LngLat, ResolvedMapPlace } from "#map/place-render";
 import type { PipelineRuntime } from "#pipeline/types";
 import type { MapCanvasStyle } from "./MapCanvas.tsx";
 /**
- * `[longitude, latitude]`.
+ * An alias for {@link LngLat}.
  *
- * @deprecated Alias kept for existing imports — {@link LngLat} (from `@mailwoman/react/map`) is the canonical name.
+ * @deprecated Alias kept for existing imports — {@link LngLat}
+ * (from `@mailwoman/react/map`) is the canonical name.
  */
 export type LngLatTuple = LngLat;
 /**
  * A viewport bias handed to `runParse` — the map's current center (and optionally zoom) as a soft prior.
  */
 export interface MapBias {
-    /**
-     * Map center as `[lon, lat]`, typically read from `map.getCenter()`.
-     */
     center: LngLat;
-    /**
-     * Current zoom, if the host wants distance-aware biasing.
-     */
     zoom?: number;
 }
 /**
- * A host-supplied overlay: one map `<Source>` plus one or more `<Layer>`s laid over the basemap (coverage "fog of war",
- * race-dots, …). The host composes the specs; the package renders them declaratively in a later phase.
+ * A host-supplied overlay: one map `<Source>` plus one or more `<Layer>`s laid over the basemap.
  */
 export interface OverlaySpec {
     /**
      * Stable id — used as the `<Source>` id and the layer-id prefix.
      */
     id: string;
-    /**
-     * The map source spec (vector/geojson/raster).
-     */
     source: SourceSpecification;
-    /**
-     * The layers drawn from that source.
-     */
     layers: LayerSpecification[];
     /**
-     * Whether the overlay is visible initially. @default true
+     * @defaultValue `true`
      */
     visible?: boolean;
-    /**
-     * Human label for a layer-toggle control.
-     */
     label?: string;
 }
 /**
@@ -87,45 +63,36 @@ export interface Suggestion {
  */
 export interface VersionOption {
     /**
-     * The version tag (e.g. a git tag or model-card version).
+     * The version tag, such as a git tag or model-card version.
      */
     version: string;
     /**
-     * Display label; falls back to `version`.
+     * Display label.
+     * The picker falls back to `version`.
      */
     label?: string;
 }
 /**
- * Which neural backend the geocoder is currently running on.
- */
-export type InferenceBackend = "webgpu" | "wasm";
-/**
- * The injected geocoder runtime. Extends {@link PipelineRuntime} (shared `runParse` / `parseStageLabels` / `loading` /
- * `ready`) with the map + version/backend surface the geocoder needs. The host composes `mapStyle` (via cartographer's
- * `StyleSpecificationComposer` + the tile-worker TileJSON), supplies the overlay specs, the initial center (from
- * geolocation), the FST autocomplete, and the calibrator — nothing in the package imports `@mailwoman/cartographer`,
- * `@mailwoman/neural`'s web loader, httpvfs, or Docusaurus.
+ * The injected geocoder runtime extends {@link PipelineRuntime} with the map.
+ * It also supplies version and backend controls.
+ *
+ * The package imports no `@mailwoman/cartographer`, `@mailwoman/neural` web loader, httpvfs, or Docusaurus.
  */
 export interface GeocoderRuntime extends PipelineRuntime {
     /**
      * The composed basemap style (URL or `StyleSpecification`).
      */
     mapStyle: MapCanvasStyle;
-    /**
-     * Host-supplied overlays (coverage, race-dots, …).
-     */
     overlays?: OverlaySpec[];
     /**
-     * Initial map center as `[lon, lat]` (the host's browser-geolocation result).
+     * Initial map center as `[lon, lat]`.
      */
     initialCenter: LngLat;
-    /**
-     * Initial zoom for the first camera.
-     */
     initialZoom?: number;
     /**
-     * A bias-aware parse. The geocoder feeds the current viewport center as a soft prior; when absent the host falls back
-     * to the base {@link PipelineRuntime.runParse}. Kept separate so the shared `runParse` contract is unchanged.
+     * A bias-aware parse that feeds the current viewport center as a soft prior.
+     *
+     * Absent, the host falls back to {@link PipelineRuntime.runParse}.
      */
     runParseWithBias?: (input: string, bias: MapBias | null, hooks: {
         onStage: (stage: number) => void;
@@ -139,50 +106,42 @@ export interface GeocoderRuntime extends PipelineRuntime {
      */
     calibrator?: (raw: number) => number | null;
     /**
-     * Enrich the selected candidate into the richer {@link ResolvedMapPlace} the declarative map render consumes (bbox,
-     * street tier + uncertainty, a pre-fetched crisp polygon) — the fields that live on the host's `ResolvedHit` but not
-     * on the shared {@link ResolvedPlaceView}. The host owns this because those extras (and the async polygon fetch in the
-     * real runtime) are host/gazetteer concerns; the package keeps {@link ParseResult} unpolluted. Absent → the candidate
-     * renders as a bare point (marker + a mid-zoom fly-to). Returning `null` also renders nothing.
+     * Enrich the selected candidate into the richer {@link ResolvedMapPlace} the declarative
+     * map render consumes (bbox, street tier + uncertainty, a pre-fetched crisp polygon) —
+     * the fields that live on the host's `ResolvedHit` but not on the shared {@link ResolvedPlaceView}.
+     *
+     * The host owns this because those extras (and the async polygon fetch in the real runtime)
+     * are host/gazetteer concerns.
+     * The package keeps {@link ParseResult} unpolluted.
+     *
+     * Absent → the candidate renders as a bare point (marker + a mid-zoom fly-to).
+     *
+     * A `null` result also renders no overlay.
      */
     resolveMapPlace?: (candidate: ResolvedPlaceView, result: ParseResult) => ResolvedMapPlace | null;
     /**
      * The selectable model bundles the version picker offers.
      */
     availableVersions?: VersionOption[];
-    /**
-     * The currently-selected model version.
-     */
     selectedVersion?: string;
     /**
      * Switch the active model bundle (re-loads weights/tokenizer/gazetteer).
      */
     selectVersion?: (version: string) => void;
     /**
-     * The backend the neural runtime resolved to (e.g. `webgpu (28 MB int8)`); free-form for the label.
+     * The neural runtime's backend and model size (e.g. `wasm (28 MB int8)`); free-form for the label.
      */
     activeBackend?: string;
-    /**
-     * Whether the CPU/WASM backend is currently forced (the controlled value for the backend toggle).
-     */
-    forceWASM?: boolean;
-    /**
-     * Force the WASM backend (opt out of WebGPU), for the backend toggle.
-     */
-    setForceWASM?: (forceWASM: boolean) => void;
 }
 /**
- * The compare-mode state a {@link GeocoderPanels.compare} render-prop receives (the second parse itself stays
- * host-side).
+ * The compare-mode state a {@link GeocoderPanels.compare} render-prop receives.
+ * the second parse itself stays host-side.
  */
 export interface CompareContext {
     /**
      * The current primary parse result, or `null` before the first submit.
      */
     result: ParseResult | null;
-    /**
-     * Whether the compare toggle is on.
-     */
     compareMode: boolean;
     /**
      * The version selected to compare against, or `null` when none is chosen.
@@ -190,38 +149,28 @@ export interface CompareContext {
     compareVersion: string | null;
 }
 /**
- * The state a {@link GeocoderPanels.result} render-prop receives, so a host can render its OWN result block (a
- * `<ResultPanel>` with its span-highlight / timing / hierarchy / precision detail) in place of the package's default
- * {@link ResultPanel}. Everything the default panel needs is passed through; the candidate-selection state stays owned
- * by the package (`useGeocode`).
+ * The state a {@link GeocoderPanels.result} render-prop receives, so a host can render its own result block.
+ *
+ * The candidate-selection state stays owned by the package (`useGeocode`).
  */
 export interface ResultContext {
-    /**
-     * The current parse+resolve result.
-     */
     result: ParseResult;
     /**
      * The selected candidate (falls back to the first), enriched for the resolved-place detail.
      */
     selectedCandidate: ResolvedPlaceView | null;
-    /**
-     * The selected candidate index, for the picker's active state.
-     */
     selectedCandidateIndex: number;
-    /**
-     * Fired when a candidate in the picker is chosen.
-     */
     onSelectCandidate: (index: number) => void;
 }
 /**
- * Host-injected panels for {@link Geocoder}, the map analogue of `PipelinePanels`. Each is an already-rendered
- * `ReactNode` (or a thunk of the parse result / compare state) so the package needs neither the heavy host visualizers
- * (ModelVisualizer, VersionCompare, About, PermalinkButton) nor their data types. Every field is optional — the
- * fake-runtime Storybook stories pass none and still render the whole geocoder.
+ * Host-injected panels for {@link Geocoder}, the map analogue of `PipelinePanels`.
+ *
+ * Each is an already-rendered `ReactNode` or a thunk.
+ * Every field is optional.
  */
 export interface GeocoderPanels {
     /**
-     * Rendered at the top of the control panel (e.g. the host's "About this geocoder").
+     * Rendered at the top of the control panel, such as the host's "About this geocoder".
      */
     header?: ReactNode;
     /**
@@ -229,13 +178,13 @@ export interface GeocoderPanels {
      */
     releaseInfo?: ReactNode;
     /**
-     * Rendered at the bottom of the control panel (e.g. a guided tour).
+     * Rendered at the bottom of the control panel, such as a guided tour.
      */
     footer?: ReactNode;
     /**
-     * A device-location / proximity-bias control, rendered between the query form and the autocomplete list (the "📍 Use
-     * my location" row). Host-owned so the geolocation permission + the bias it feeds into the host's
-     * {@link GeocoderRuntime.runParseWithBias} stay a host concern.
+     * A device-location / proximity-bias control, rendered between the query form and the autocomplete list.
+     *
+     * Host-owned because the geolocation permission feeds {@link GeocoderRuntime.runParseWithBias}.
      */
     bias?: ReactNode;
     /**
@@ -243,28 +192,27 @@ export interface GeocoderPanels {
      */
     extras?: (result: ParseResult) => ReactNode;
     /**
-     * Rendered just above the result block (present or empty), for content that reads on THIS answer.
-     *
-     * A control that reads on the model rather than on an address belongs in {@link developerExtras}: above the result it
-     * is the first thing a visitor meets, and on a phone it pushes the answer below the fold.
+     * Rendered just above the result block for content that reads on this answer. a
+     * control that reads on the model belongs in {@link developerExtras}.
      */
     aboveResult?: (context: {
         result: ParseResult | null;
     }) => ReactNode;
     /**
-     * Host controls appended to the Developer sheet — the opt-in display toggles, whose state and the renderers they
-     * drive both belong to the host.
+     * Host controls appended to the Developer sheet.
+     * The host owns their state and renderers.
      */
     developerExtras?: ReactNode;
     /**
-     * Replace the package's default {@link ResultPanel} entirely. When provided, the host renders its own result block
-     * (span highlight, timing, hierarchy, precision detail, calibrated confidences) from the {@link ResultContext}. Absent
-     * → the built-in panel renders.
+     * Replaces the package's default {@link ResultPanel}.
+     *
+     * When absent, the built-in panel renders.
+     * When provided, the host renders from {@link ResultContext}.
      */
     result?: (context: ResultContext) => ReactNode;
     /**
-     * Rendered in place of the resolved-place panel when nothing resolved (host's FailureDiagnostic). Ignored when
-     * {@link result} is set.
+     * Rendered in place of the resolved-place panel when no place resolved. ignored
+     * when {@link result} is set.
      */
     failure?: (result: ParseResult) => ReactNode;
     /**
@@ -272,9 +220,8 @@ export interface GeocoderPanels {
      */
     compare?: (context: CompareContext) => ReactNode;
     /**
-     * The model-visualizer / debug drawer, mounted beside the map (host's ModelVisualizer). A render-prop so the host can
-     * trace the CURRENT result (its input) — the package passes the live parse result; the host decides on its own
-     * dev-mode state and returns `null` when the drawer is closed.
+     * The model-visualizer / debug drawer mounted beside the map, as a render-prop
+     * receiving the live result and returning `null` when closed.
      */
     debugDrawer?: (context: {
         result: ParseResult | null;
@@ -284,11 +231,8 @@ export interface GeocoderPanels {
      */
     mapControls?: ReactNode;
     /**
-     * A layer control, rendered in the chrome's top column under the example chips rather than in a MapLibre corner.
-     *
-     * A render-prop taking the live map handle, because a layer control reads `getStyle().layers` and writes
-     * `setLayoutProperty` — it cannot be a static node. The handle is `null` until the map instantiates, so the host
-     * returns `null` for that first frame rather than rendering an empty control.
+     * A layer control rendered in the chrome's top column, as a render-prop over the
+     * live map handle (null until the map instantiates).
      */
     layers?: (context: {
         map: MapInstance | null;

package/out/map/types.d.ts.map

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

package/out/map/types.js

@@ -3,16 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Types for the geocoder map surface. Mirrors the pipeline boundary: the package owns the UI state
- *   machine + the declarative map, while the host injects a {@link GeocoderRuntime} that owns ONNX / httpvfs
- *   / R2 and the composed map style. {@link GeocoderRuntime} EXTENDS {@link PipelineRuntime} so the shared
- *   `runParse` / `parseStageLabels` / `loading` contract is reused, and adds the map-specific surface
- *   (style, overlays, initial center, viewport bias, backend/version selection). Phase 4 adds the
- *   `resolveMapPlace` enricher, the {@link GeocoderPanels} injection bag, and the {@link CompareContext}.
- *
- *   The map-spec types are imported type-only from `react-map-gl/maplibre`; nothing here loads maplibre at
- *   runtime, so this module stays node-safe (its concrete-value CONSUMERS — `MapCanvas`, `Geocoder` —
- *   are the ones behind the `@mailwoman/react/map` subpath).
+ *   Types for the geocoder map surface. Its `react-map-gl/maplibre` imports are type-only, so the module stays node-safe.
  */
 export {};
 //# sourceMappingURL=types.js.map

package/out/map/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../lib/map/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../lib/map/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/out/map/useCompareState.d.ts

@@ -4,9 +4,9 @@
  * @author Teffen Ellis, et al.
  *
  *   `useCompareState` — the small headless state machine behind the demo's compare toggle
- *   (`_app.tsx:142-143, 1238-1305`): whether compare mode is on, and which version to compare against.
- *   Turning compare off clears the chosen version; selecting a compare version equal to the primary is
- *   rejected (the picker filters it out, this guards the programmatic path). The SECOND parse itself is a
+ *   (`_app.tsx:142-143, 1238-1305`): whether compare mode is on and which version to compare against.
+ *   The off state clears the chosen version. A selected compare version equal to the primary is
+ *   rejected (the picker filters it out, this guards the programmatic path). The second parse itself is a
  *   host concern surfaced through `panels.compare` — this hook owns only the toggle + selection.
  */
 export interface UseCompareState {
@@ -19,7 +19,8 @@ export interface UseCompareState {
      */
     compareVersion: string | null;
     /**
-     * Flip compare mode; turning it off clears the chosen version.
+     * Flip compare mode.
+     * The off state clears the chosen version.
      */
     setCompareMode: (compareMode: boolean) => void;
     /**

package/out/map/useCompareState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCompareState.d.ts","sourceRoot":"","sources":["../../lib/map/useCompareState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,WAAW,EAAE,OAAO,CAAA;IACpB;;OAEG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B;;OAEG;IACH,cAAc,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,IAAI,CAAA;IAC9C;;OAEG;IACH,iBAAiB,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IACnD;;OAEG;IACH,cAAc,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,IAAI,CAAA;CAChD;AAED,wBAAgB,eAAe,IAAI,eAAe,CAiBjD"}
+{"version":3,"file":"useCompareState.d.ts","sourceRoot":"","sources":["../../lib/map/useCompareState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,WAAW,EAAE,OAAO,CAAA;IACpB;;OAEG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B;;;OAGG;IACH,cAAc,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,IAAI,CAAA;IAC9C;;OAEG;IACH,iBAAiB,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IACnD;;OAEG;IACH,cAAc,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,IAAI,CAAA;CAChD;AAED,wBAAgB,eAAe,IAAI,eAAe,CAiBjD"}

package/out/map/useCompareState.js

@@ -4,9 +4,9 @@
  * @author Teffen Ellis, et al.
  *
  *   `useCompareState` — the small headless state machine behind the demo's compare toggle
- *   (`_app.tsx:142-143, 1238-1305`): whether compare mode is on, and which version to compare against.
- *   Turning compare off clears the chosen version; selecting a compare version equal to the primary is
- *   rejected (the picker filters it out, this guards the programmatic path). The SECOND parse itself is a
+ *   (`_app.tsx:142-143, 1238-1305`): whether compare mode is on and which version to compare against.
+ *   The off state clears the chosen version. A selected compare version equal to the primary is
+ *   rejected (the picker filters it out, this guards the programmatic path). The second parse itself is a
  *   host concern surfaced through `panels.compare` — this hook owns only the toggle + selection.
  */
 import { useCallback, useState } from "react";

package/out/map/useCompareState.js.map

@@ -1 +1 @@
-{"version":3,"file":"useCompareState.js","sourceRoot":"","sources":["../../lib/map/useCompareState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAyB7C,MAAM,UAAU,eAAe;IAC9B,MAAM,CAAC,WAAW,EAAE,mBAAmB,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC1D,MAAM,CAAC,cAAc,EAAE,iBAAiB,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAA;IAEzE,MAAM,cAAc,GAAG,WAAW,CAAC,CAAC,IAAa,EAAE,EAAE;QACpD,mBAAmB,CAAC,IAAI,CAAC,CAAA;QAEzB,IAAI,CAAC,IAAI,EAAE,CAAC;YACX,iBAAiB,CAAC,IAAI,CAAC,CAAA;QACxB,CAAC;IACF,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,MAAM,cAAc,GAAG,WAAW,CAAC,CAAC,cAAsB,EAAE,EAAE;QAC7D,iBAAiB,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;IACrE,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,cAAc,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAA;AAC1F,CAAC"}
+{"version":3,"file":"useCompareState.js","sourceRoot":"","sources":["../../lib/map/useCompareState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AA0B7C,MAAM,UAAU,eAAe;IAC9B,MAAM,CAAC,WAAW,EAAE,mBAAmB,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC1D,MAAM,CAAC,cAAc,EAAE,iBAAiB,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAA;IAEzE,MAAM,cAAc,GAAG,WAAW,CAAC,CAAC,IAAa,EAAE,EAAE;QACpD,mBAAmB,CAAC,IAAI,CAAC,CAAA;QAEzB,IAAI,CAAC,IAAI,EAAE,CAAC;YACX,iBAAiB,CAAC,IAAI,CAAC,CAAA;QACxB,CAAC;IACF,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,MAAM,cAAc,GAAG,WAAW,CAAC,CAAC,cAAsB,EAAE,EAAE;QAC7D,iBAAiB,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;IACrE,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,cAAc,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAA;AAC1F,CAAC"}

package/out/map/useGeocode.d.ts

@@ -3,12 +3,12 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `useGeocode` — the parse+resolve state machine for the geocoder map. It REUSES the pipeline's
+ *   `useGeocode` — the parse+resolve state machine for the geocoder map. It reuses the pipeline's
  *   `useParsePipeline` (text / busy / stage / result / candidate selection) and layers on the two map-only
  *   concerns the geocoder adds over the base explorer:
  *
  *     1. Viewport bias — when the runtime exposes `runParseWithBias`, the current map center (read through
- *        an injected `getBias`, itself reading the `MapRef`) rides along as a soft proximity prior. The
+ *        an injected `getBias`, itself reading the `MapRef`) supplies a soft proximity prior. The
  *        bias is injected by deriving a `runParse` that binds it, so `useParsePipeline` is reused verbatim.
  *     2. The map render place — the selected candidate, enriched by the host's `resolveMapPlace` into the
  *        richer {@link ResolvedMapPlace} the declarative overlays consume (bbox / tier / polygon). Absent
@@ -30,7 +30,9 @@ export interface UseGeocodeOptions {
      */
     defaultText: string;
     /**
-     * Read the current viewport bias (the map center) at submit time. Absent → no bias.
+     * Read the current viewport bias (the map center) at submit time.
+     *
+     * Absent → no bias.
      */
     getBias?: () => MapBias | null;
 }

package/out/map/useGeocode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useGeocode.d.ts","sourceRoot":"","sources":["../../lib/map/useGeocode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAE1D,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAEpF,MAAM,WAAW,iBAAiB;IACjC;;OAEG;IACH,OAAO,EAAE,eAAe,CAAA;IACxB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,GAAG,IAAI,CAAA;CAC9B;AAED,MAAM,WAAW,UAAW,SAAQ,gBAAgB;IACnD;;OAEG;IACH,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAA;CACjC;AAED,wBAAgB,UAAU,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,iBAAiB,GAAG,UAAU,CAyB3F"}
+{"version":3,"file":"useGeocode.d.ts","sourceRoot":"","sources":["../../lib/map/useGeocode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAE1D,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAEpF,MAAM,WAAW,iBAAiB;IACjC;;OAEG;IACH,OAAO,EAAE,eAAe,CAAA;IACxB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,GAAG,IAAI,CAAA;CAC9B;AAED,MAAM,WAAW,UAAW,SAAQ,gBAAgB;IACnD;;OAEG;IACH,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAA;CACjC;AAED,wBAAgB,UAAU,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,iBAAiB,GAAG,UAAU,CAyB3F"}

package/out/map/useGeocode.js

@@ -3,12 +3,12 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `useGeocode` — the parse+resolve state machine for the geocoder map. It REUSES the pipeline's
+ *   `useGeocode` — the parse+resolve state machine for the geocoder map. It reuses the pipeline's
  *   `useParsePipeline` (text / busy / stage / result / candidate selection) and layers on the two map-only
  *   concerns the geocoder adds over the base explorer:
  *
  *     1. Viewport bias — when the runtime exposes `runParseWithBias`, the current map center (read through
- *        an injected `getBias`, itself reading the `MapRef`) rides along as a soft proximity prior. The
+ *        an injected `getBias`, itself reading the `MapRef`) supplies a soft proximity prior. The
  *        bias is injected by deriving a `runParse` that binds it, so `useParsePipeline` is reused verbatim.
  *     2. The map render place — the selected candidate, enriched by the host's `resolveMapPlace` into the
  *        richer {@link ResolvedMapPlace} the declarative overlays consume (bbox / tier / polygon). Absent
@@ -20,8 +20,8 @@
 import { useMemo } from "react";
 import { useParsePipeline } from "#pipeline/useParsePipeline";
 export function useGeocode({ runtime, defaultText, getBias }) {
-    // Bind the viewport bias into a derived `runParse` so `useParsePipeline` is reused unchanged. When the runtime has no
-    // bias-aware parse, pass it straight through.
+    // Bind the viewport bias into a derived `runParse` so `useParsePipeline` is reused unchanged.
+    // When the runtime has no bias-aware parse, pass it straight through.
     const geoRuntime = useMemo(() => {
         const withBias = runtime.runParseWithBias;
         if (!withBias)

package/out/map/useGeocode.js.map

@@ -1 +1 @@
-{"version":3,"file":"useGeocode.js","sourceRoot":"","sources":["../../lib/map/useGeocode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAK/B,OAAO,EAAE,gBAAgB,EAAyB,MAAM,4BAA4B,CAAA;AAwBpF,MAAM,UAAU,UAAU,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAqB;IAC9E,sHAAsH;IACtH,8CAA8C;IAC9C,MAAM,UAAU,GAAG,OAAO,CAAkB,GAAG,EAAE;QAChD,MAAM,QAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAA;QAEzC,IAAI,CAAC,QAAQ;YAAE,OAAO,OAAO,CAAA;QAE7B,OAAO;YACN,GAAG,OAAO;YACV,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,IAAI,EAAE,KAAK,CAAC;SACvE,CAAA;IACF,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAA;IAEtB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAA;IAEvE,MAAM,QAAQ,GAAG,OAAO,CAA0B,GAAG,EAAE;QACtD,IAAI,CAAC,QAAQ,CAAC,iBAAiB,IAAI,CAAC,QAAQ,CAAC,MAAM;YAAE,OAAO,IAAI,CAAA;QAEhE,OAAO,OAAO,CAAC,eAAe;YAC7B,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC;YACtE,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAA;IAC9B,CAAC,EAAE,CAAC,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAE1D,OAAO,EAAE,GAAG,QAAQ,EAAE,QAAQ,EAAE,CAAA;AACjC,CAAC"}
+{"version":3,"file":"useGeocode.js","sourceRoot":"","sources":["../../lib/map/useGeocode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAK/B,OAAO,EAAE,gBAAgB,EAAyB,MAAM,4BAA4B,CAAA;AA0BpF,MAAM,UAAU,UAAU,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAqB;IAC9E,8FAA8F;IAC9F,sEAAsE;IACtE,MAAM,UAAU,GAAG,OAAO,CAAkB,GAAG,EAAE;QAChD,MAAM,QAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAA;QAEzC,IAAI,CAAC,QAAQ;YAAE,OAAO,OAAO,CAAA;QAE7B,OAAO;YACN,GAAG,OAAO;YACV,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,IAAI,EAAE,KAAK,CAAC;SACvE,CAAA;IACF,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAA;IAEtB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAA;IAEvE,MAAM,QAAQ,GAAG,OAAO,CAA0B,GAAG,EAAE;QACtD,IAAI,CAAC,QAAQ,CAAC,iBAAiB,IAAI,CAAC,QAAQ,CAAC,MAAM;YAAE,OAAO,IAAI,CAAA;QAEhE,OAAO,OAAO,CAAC,eAAe;YAC7B,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC;YACtE,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAA;IAC9B,CAAC,EAAE,CAAC,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAE1D,OAAO,EAAE,GAAG,QAAQ,EAAE,QAAQ,EAAE,CAAA;AACjC,CAAC"}

package/out/map/useMapBearing.d.ts

@@ -3,26 +3,26 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `useMapBearing` — the map's rotation as React state, for a compass that appears off north and fades back.
- *
- *   The map is an external store, so it is read through `useSyncExternalStore` rather than mirrored into state by an
- *   effect: the bearing is a number, which makes a stable snapshot, and React tears nothing during a concurrent
- *   render.
- *
- *   It listens on `rotate` rather than `rotateend`, because the needle has to track the gesture rather than snap once
- *   the gesture is over. `move` is subscribed too: a `flyTo` or an `easeTo` carrying a bearing rotates the map without
- *   firing a rotate event, and a compass that misses those stays pointing north over a turned map.
+ *   The map's rotation as React state, read through `useSyncExternalStore` and subscribed to `move` as well as `rotate`, since a `flyTo` or `easeTo` carrying a direction fires no rotate event.
  */
 import type { MapInstance } from "react-map-gl/maplibre";
+/**
+ * The map's bearing and a callback that returns the map to north.
+ */
 export interface UseMapBearing {
     /**
-     * Degrees off north, as MapLibre reports it. Zero while there is no map.
+     * Degrees off north, as MapLibre reports it.
+     * Zero while there is no map.
      */
     bearing: number;
     /**
-     * Rotate the map back to north. A no-op while there is no map.
+     * Rotate the map back to north.
+     * A no-op while there is no map.
      */
     resetNorth: () => void;
 }
+/**
+ * Reads the live map bearing and exposes `resetNorth`.
+ */
 export declare function useMapBearing(map: MapInstance | null): UseMapBearing;
 //# sourceMappingURL=useMapBearing.d.ts.map