@mailwoman/react 7.5.0 → 7.6.0

package/out/pipeline/QueryForm.d.ts

@@ -6,7 +6,7 @@
  *   `QueryForm` — the address input + submit button for the pipeline explorer. Shows a spinner while
  *   parsing. Presentational; `onSubmit` fires on form submission.
  */
-import type { ReactNode } from "react";
+import type { InputHTMLAttributes, KeyboardEvent, ReactNode } from "react";
 export interface QueryFormProps {
     value: string;
     onChange: (value: string) => void;
@@ -14,6 +14,10 @@ export interface QueryFormProps {
     disabled?: boolean;
     busy?: boolean;
     placeholder?: string;
+    /** Keydown on the input — the seam a combobox (the demo's place-autocomplete) needs for arrow/Enter/Esc nav. */
+    onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void;
+    /** Escape hatch for extra `<input>` attributes (aria-combobox props, `autoComplete`, …). Merged last. */
+    inputProps?: InputHTMLAttributes<HTMLInputElement>;
 }
-export declare function QueryForm({ value, onChange, onSubmit, disabled, busy, placeholder }: QueryFormProps): ReactNode;
+export declare function QueryForm({ value, onChange, onSubmit, disabled, busy, placeholder, onKeyDown, inputProps, }: QueryFormProps): ReactNode;
 //# sourceMappingURL=QueryForm.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"QueryForm.d.ts","sourceRoot":"","sources":["../../pipeline/QueryForm.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC,QAAQ,EAAE,MAAM,IAAI,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,wBAAgB,SAAS,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,cAAc,GAAG,SAAS,CA6B/G"}
+{"version":3,"file":"QueryForm.d.ts","sourceRoot":"","sources":["../../pipeline/QueryForm.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAI1E,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC,QAAQ,EAAE,MAAM,IAAI,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gHAAgH;IAChH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAA;IAC5D,yGAAyG;IACzG,UAAU,CAAC,EAAE,mBAAmB,CAAC,gBAAgB,CAAC,CAAA;CAClD;AAED,wBAAgB,SAAS,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,WAAW,EACX,SAAS,EACT,UAAU,GACV,EAAE,cAAc,GAAG,SAAS,CA+B5B"}

package/out/pipeline/QueryForm.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { LoadingIndicator } from "../common/LoadingIndicator.js";
-export function QueryForm({ value, onChange, onSubmit, disabled, busy, placeholder }) {
+export function QueryForm({ value, onChange, onSubmit, disabled, busy, placeholder, onKeyDown, inputProps, }) {
     return (_jsxs("form", { className: "mw-field", onSubmit: (e) => {
             e.preventDefault();
             onSubmit();
-        }, children: [_jsx("label", { htmlFor: "mw-pipeline-input", children: "Address" }), _jsx("input", { id: "mw-pipeline-input", type: "text", value: value, onChange: (e) => onChange(e.target.value), disabled: disabled, placeholder: placeholder }), _jsx("button", { type: "submit", disabled: disabled || busy, children: busy ? (_jsxs(_Fragment, { children: [_jsx(LoadingIndicator, { mode: "spinner", size: "small" }), " Parsing\u2026"] })) : ("Parse + resolve") })] }));
+        }, children: [_jsx("label", { htmlFor: "mw-pipeline-input", children: "Address" }), _jsx("input", { id: "mw-pipeline-input", type: "text", value: value, onChange: (e) => onChange(e.target.value), disabled: disabled, placeholder: placeholder, onKeyDown: onKeyDown, ...inputProps }), _jsx("button", { type: "submit", disabled: disabled || busy, children: busy ? (_jsxs(_Fragment, { children: [_jsx(LoadingIndicator, { mode: "spinner", size: "small" }), " Parsing\u2026"] })) : ("Parse + resolve") })] }));
 }
 //# sourceMappingURL=QueryForm.js.map

package/out/pipeline/QueryForm.js.map

@@ -1 +1 @@
-{"version":3,"file":"QueryForm.js","sourceRoot":"","sources":["../../pipeline/QueryForm.tsx"],"names":[],"mappings":";AAWA,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAAgC,CAAA;AAWjE,MAAM,UAAU,SAAS,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAkB;IACnG,OAAO,CACN,gBACC,SAAS,EAAC,UAAU,EACpB,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE;YACf,CAAC,CAAC,cAAc,EAAE,CAAA;YAClB,QAAQ,EAAE,CAAA;QACX,CAAC,aAED,gBAAO,OAAO,EAAC,mBAAmB,wBAAgB,EAClD,gBACC,EAAE,EAAC,mBAAmB,EACtB,IAAI,EAAC,MAAM,EACX,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EACzC,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,WAAW,GACvB,EACF,iBAAQ,IAAI,EAAC,QAAQ,EAAC,QAAQ,EAAE,QAAQ,IAAI,IAAI,YAC9C,IAAI,CAAC,CAAC,CAAC,CACP,8BACC,KAAC,gBAAgB,IAAC,IAAI,EAAC,SAAS,EAAC,IAAI,EAAC,OAAO,GAAG,sBAC9C,CACH,CAAC,CAAC,CAAC,CACH,iBAAiB,CACjB,GACO,IACH,CACP,CAAA;AACF,CAAC"}
+{"version":3,"file":"QueryForm.js","sourceRoot":"","sources":["../../pipeline/QueryForm.tsx"],"names":[],"mappings":";AAWA,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAAgC,CAAA;AAejE,MAAM,UAAU,SAAS,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,WAAW,EACX,SAAS,EACT,UAAU,GACM;IAChB,OAAO,CACN,gBACC,SAAS,EAAC,UAAU,EACpB,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE;YACf,CAAC,CAAC,cAAc,EAAE,CAAA;YAClB,QAAQ,EAAE,CAAA;QACX,CAAC,aAED,gBAAO,OAAO,EAAC,mBAAmB,wBAAgB,EAClD,gBACC,EAAE,EAAC,mBAAmB,EACtB,IAAI,EAAC,MAAM,EACX,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EACzC,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,SAAS,KAChB,UAAU,GACb,EACF,iBAAQ,IAAI,EAAC,QAAQ,EAAC,QAAQ,EAAE,QAAQ,IAAI,IAAI,YAC9C,IAAI,CAAC,CAAC,CAAC,CACP,8BACC,KAAC,gBAAgB,IAAC,IAAI,EAAC,SAAS,EAAC,IAAI,EAAC,OAAO,GAAG,sBAC9C,CACH,CAAC,CAAC,CAAC,CACH,iBAAiB,CACjB,GACO,IACH,CACP,CAAA;AACF,CAAC"}

package/out/runtime/useDemoRuntime.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `useDemoRuntime` — the headless load-orchestration hook shared by every mailwoman demo surface (the
+ *   inline doc-embeds via `DemoEmbed`, and the geocoder map page). It owns the version-selection state
+ *   machine, the per-version load SEQUENCING, cancellation, and the ready / loading / error state — but
+ *   NOTHING model- or map-specific. The actual asset fetchers (the ONNX classifier factory, the httpvfs
+ *   WOF opener, the FST fetch, the releases.json fetch) are INJECTED by the host as async functions, so
+ *   this module imports only React: no `onnxruntime-web`, no `sql.js-httpvfs`, no `maplibre-gl`, no
+ *   `fetch`-specific plumbing. That keeps it node-import-safe and root-exportable from
+ *   `@mailwoman/react` — the exact seam `PipelineRuntime` established, generalized to the loader itself.
+ *
+ *   The hook is generic over `TAssets` (the opaque bundle the host's `loadAssets` returns — classifier,
+ *   FST, WOF lookup, calibrator, …) and `TRelease` (the host's release-manifest entry). The package
+ *   never inspects either; it just holds, reveals, and re-loads them across version/backend switches.
+ */
+/** The minimal contract a release-manifest entry must satisfy. Hosts extend this with their own fields. */
+export interface DemoReleaseBase {
+    /** The version tag this entry describes (matched against `selectedVersion`). */
+    version: string;
+    /** Optional display label a version picker shows; falls back to `version`. */
+    label?: string;
+}
+/** The releases manifest the host fetches — the default version plus the selectable release entries. */
+export interface DemoManifest<TRelease extends DemoReleaseBase = DemoReleaseBase> {
+    /** The version selected on first load (before the user picks another). */
+    defaultVersion: string;
+    /** Every selectable release. */
+    releases: TRelease[];
+}
+/**
+ * The progress channel handed to the host's `loadAssets`. The host reports load progress + the resolved backend + the
+ * staged step labels/index THROUGH these setters (all no-op once the load is superseded/aborted), while the hook owns
+ * the terminal state (revealing the assets + clearing progress on success, surfacing the error on failure).
+ */
+export interface DemoAssetsLoadContext {
+    /** Aborts when this load is superseded (version/backend switch) or the provider unmounts. */
+    signal: AbortSignal;
+    /** Whether the host should force the CPU/WASM backend (opt out of WebGPU) for this load. */
+    forceWASM: boolean;
+    /** Set the human-readable progress line (e.g. `Loading v7 model (~28 MB)…`). */
+    setProgress: (progress: string) => void;
+    /** Set the staged-loader step labels (e.g. `["Loading classifier", "Loading FST gazetteer"]`). */
+    setStepLabels: (labels: string[]) => void;
+    /** Advance the staged-loader step index (0-based). */
+    setStepIndex: (index: number) => void;
+    /** Report the backend the neural runtime resolved to (e.g. `webgpu (27 MB int8)`). */
+    setBackend: (backend: string) => void;
+}
+/** The injected loaders the hook orchestrates. Nothing here is model- or map-aware — the host owns all that. */
+export interface DemoRuntimeConfig<TAssets, TRelease extends DemoReleaseBase = DemoReleaseBase> {
+    /**
+     * Fetch + normalize the releases manifest. Returns `null` when no manifest is available (the demo then shows nothing
+     * selectable). Rejecting surfaces `errorMessage`. Runs once on mount.
+     */
+    loadManifest: (signal: AbortSignal) => Promise<DemoManifest<TRelease> | null>;
+    /**
+     * Load the full asset bundle for one release — the classifier, FST, WOF lookup, calibrator, whatever the host needs.
+     * Runs on every version or `forceWASM` change. Report progress via `ctx`; return the bundle. Rejecting surfaces
+     * `errorMessage`. Bail early when `ctx.signal.aborted` — the hook discards a superseded result regardless.
+     */
+    loadAssets: (release: TRelease, ctx: DemoAssetsLoadContext) => Promise<TAssets>;
+    /** The progress line shown before the manifest arrives. @default "Loading releases…" */
+    initialProgress?: string;
+}
+/**
+ * The state `useDemoRuntime` produces — the load-orchestration state a demo surface renders + re-projects.
+ *
+ * NAMING (phase 4): this is the LOADER STATE, deliberately distinct from {@link DemoRuntime} (the injected runtime
+ * contract `<GeocoderDemo>` consumes). The two were same-stem before (`UseDemoRuntime` vs `DemoRuntime`); phase 4
+ * disambiguates by renaming the loader-state type to `DemoLoaderState`. A host builds a {@link DemoRuntime} by pairing
+ * this loader state (assets + backend + version) with the map surface (style, overlays, bias, parse) — see the map
+ * subpath's `DemoRuntime`.
+ */
+export interface DemoLoaderState<TAssets, TRelease extends DemoReleaseBase = DemoReleaseBase> {
+    /** The releases manifest, once fetched. */
+    manifest: DemoManifest<TRelease> | null;
+    /** The currently-selected version, or `null` before the manifest resolves. */
+    selectedVersion: string | null;
+    /** The release entry matching `selectedVersion` (convenience over `manifest.releases.find`). */
+    selectedRelease: TRelease | null;
+    /** The loaded asset bundle for the selected version, or `null` while (re)loading. */
+    assets: TAssets | null;
+    /** Whether the asset bundle is loaded and ready to use. */
+    ready: boolean;
+    /** Human-readable load progress (`""` when idle/ready). */
+    loadingProgress: string;
+    /** Staged-loader step index (0-based; `-1` before the first step). */
+    loadingStepIndex: number;
+    /** Staged-loader step labels. */
+    loadingStepLabels: string[];
+    /** A load error (manifest or asset), distinct from any per-parse error a consumer tracks separately. */
+    errorMessage: string | null;
+    /** The backend the neural runtime resolved to (e.g. `webgpu (27 MB int8)`), or `""` before it's known. */
+    activeBackend: string;
+    /** Whether the CPU/WASM backend is currently forced. */
+    forceWASM: boolean;
+    /** Switch to a different version (clears any error, then reloads the asset bundle). */
+    selectVersion: (version: string) => void;
+    /** Force (or unforce) the CPU/WASM backend — reloads the asset bundle. */
+    setForceWASM: (forceWASM: boolean) => void;
+}
+/**
+ * Drive the shared version → asset-bundle load state machine over a host-injected loader.
+ *
+ * Sequence: on mount `loadManifest` runs and its `defaultVersion` becomes the selection; each version (or `forceWASM`)
+ * change reloads the bundle via `loadAssets`, the previous load aborted first. The assets are revealed ATOMICALLY when
+ * `loadAssets` resolves (so `ready` flips exactly once per load), and consumers gate on `ready`.
+ */
+export declare function useDemoRuntime<TAssets, TRelease extends DemoReleaseBase = DemoReleaseBase>(config: DemoRuntimeConfig<TAssets, TRelease>): DemoLoaderState<TAssets, TRelease>;
+//# sourceMappingURL=useDemoRuntime.d.ts.map

package/out/runtime/useDemoRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDemoRuntime.d.ts","sourceRoot":"","sources":["../../runtime/useDemoRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,2GAA2G;AAC3G,MAAM,WAAW,eAAe;IAC/B,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAED,wGAAwG;AACxG,MAAM,WAAW,YAAY,CAAC,QAAQ,SAAS,eAAe,GAAG,eAAe;IAC/E,0EAA0E;IAC1E,cAAc,EAAE,MAAM,CAAA;IACtB,gCAAgC;IAChC,QAAQ,EAAE,QAAQ,EAAE,CAAA;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACrC,6FAA6F;IAC7F,MAAM,EAAE,WAAW,CAAA;IACnB,4FAA4F;IAC5F,SAAS,EAAE,OAAO,CAAA;IAClB,gFAAgF;IAChF,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,kGAAkG;IAClG,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;IACzC,sDAAsD;IACtD,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACrC,sFAAsF;IACtF,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACrC;AAED,gHAAgH;AAChH,MAAM,WAAW,iBAAiB,CAAC,OAAO,EAAE,QAAQ,SAAS,eAAe,GAAG,eAAe;IAC7F;;;OAGG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAA;IAC7E;;;;OAIG;IACH,UAAU,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,qBAAqB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/E,wFAAwF;IACxF,eAAe,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe,CAAC,OAAO,EAAE,QAAQ,SAAS,eAAe,GAAG,eAAe;IAC3F,2CAA2C;IAC3C,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAA;IACvC,8EAA8E;IAC9E,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,gGAAgG;IAChG,eAAe,EAAE,QAAQ,GAAG,IAAI,CAAA;IAChC,qFAAqF;IACrF,MAAM,EAAE,OAAO,GAAG,IAAI,CAAA;IACtB,2DAA2D;IAC3D,KAAK,EAAE,OAAO,CAAA;IACd,2DAA2D;IAC3D,eAAe,EAAE,MAAM,CAAA;IACvB,sEAAsE;IACtE,gBAAgB,EAAE,MAAM,CAAA;IACxB,iCAAiC;IACjC,iBAAiB,EAAE,MAAM,EAAE,CAAA;IAC3B,wGAAwG;IACxG,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,0GAA0G;IAC1G,aAAa,EAAE,MAAM,CAAA;IACrB,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAA;IAClB,uFAAuF;IACvF,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IACxC,0EAA0E;IAC1E,YAAY,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAA;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,QAAQ,SAAS,eAAe,GAAG,eAAe,EACzF,MAAM,EAAE,iBAAiB,CAAC,OAAO,EAAE,QAAQ,CAAC,GAC1C,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,CA2HpC"}

package/out/runtime/useDemoRuntime.js

@@ -0,0 +1,135 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `useDemoRuntime` — the headless load-orchestration hook shared by every mailwoman demo surface (the
+ *   inline doc-embeds via `DemoEmbed`, and the geocoder map page). It owns the version-selection state
+ *   machine, the per-version load SEQUENCING, cancellation, and the ready / loading / error state — but
+ *   NOTHING model- or map-specific. The actual asset fetchers (the ONNX classifier factory, the httpvfs
+ *   WOF opener, the FST fetch, the releases.json fetch) are INJECTED by the host as async functions, so
+ *   this module imports only React: no `onnxruntime-web`, no `sql.js-httpvfs`, no `maplibre-gl`, no
+ *   `fetch`-specific plumbing. That keeps it node-import-safe and root-exportable from
+ *   `@mailwoman/react` — the exact seam `PipelineRuntime` established, generalized to the loader itself.
+ *
+ *   The hook is generic over `TAssets` (the opaque bundle the host's `loadAssets` returns — classifier,
+ *   FST, WOF lookup, calibrator, …) and `TRelease` (the host's release-manifest entry). The package
+ *   never inspects either; it just holds, reveals, and re-loads them across version/backend switches.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+/**
+ * Drive the shared version → asset-bundle load state machine over a host-injected loader.
+ *
+ * Sequence: on mount `loadManifest` runs and its `defaultVersion` becomes the selection; each version (or `forceWASM`)
+ * change reloads the bundle via `loadAssets`, the previous load aborted first. The assets are revealed ATOMICALLY when
+ * `loadAssets` resolves (so `ready` flips exactly once per load), and consumers gate on `ready`.
+ */
+export function useDemoRuntime(config) {
+    const { initialProgress = "Loading releases…" } = config;
+    const [manifest, setManifest] = useState(null);
+    const [selectedVersion, setSelectedVersion] = useState(null);
+    const [assets, setAssets] = useState(null);
+    const [loadingProgress, setLoadingProgress] = useState(initialProgress);
+    const [loadingStepIndex, setLoadingStepIndex] = useState(-1);
+    const [loadingStepLabels, setLoadingStepLabels] = useState([]);
+    const [errorMessage, setErrorMessage] = useState(null);
+    const [activeBackend, setActiveBackend] = useState("");
+    const [forceWASM, setForceWASMState] = useState(false);
+    // Latest-ref the injected loaders: a host that re-creates them each render (an inline arrow) must NOT retrigger the
+    // load effects, which key ONLY on version/backend. The effects read `.current` at run time.
+    const loadManifestRef = useRef(config.loadManifest);
+    loadManifestRef.current = config.loadManifest;
+    const loadAssetsRef = useRef(config.loadAssets);
+    loadAssetsRef.current = config.loadAssets;
+    // Latest manifest for the version-load effect, so it can resolve the release WITHOUT depending on `manifest`
+    // identity — which would double-fire the load the instant the manifest first arrives (the selection transition
+    // null → defaultVersion already fires it once).
+    const manifestRef = useRef(null);
+    manifestRef.current = manifest;
+    // Mount: fetch the manifest, then select the default version.
+    useEffect(() => {
+        const controller = new AbortController();
+        void (async () => {
+            try {
+                const data = await loadManifestRef.current(controller.signal);
+                if (controller.signal.aborted)
+                    return;
+                if (data) {
+                    setManifest(data);
+                    setSelectedVersion(data.defaultVersion);
+                }
+            }
+            catch (error) {
+                if (controller.signal.aborted)
+                    return;
+                setErrorMessage(error instanceof Error ? error.message : String(error));
+            }
+        })();
+        return () => controller.abort();
+    }, []);
+    // Load the per-version asset bundle when the version (or the backend force) changes.
+    useEffect(() => {
+        if (!selectedVersion)
+            return;
+        const release = manifestRef.current?.releases.find((r) => r.version === selectedVersion) ?? null;
+        if (!release)
+            return;
+        const controller = new AbortController();
+        const { signal } = controller;
+        const guard = (fn) => {
+            if (!signal.aborted) {
+                fn();
+            }
+        };
+        void (async () => {
+            try {
+                setAssets(null);
+                setLoadingStepIndex(-1);
+                setLoadingStepLabels([]);
+                setActiveBackend("");
+                const ctx = {
+                    signal,
+                    forceWASM,
+                    setProgress: (progress) => guard(() => setLoadingProgress(progress)),
+                    setStepLabels: (labels) => guard(() => setLoadingStepLabels(labels)),
+                    setStepIndex: (index) => guard(() => setLoadingStepIndex(index)),
+                    setBackend: (backend) => guard(() => setActiveBackend(backend)),
+                };
+                const loaded = await loadAssetsRef.current(release, ctx);
+                if (signal.aborted)
+                    return;
+                setAssets(loaded);
+                setLoadingProgress("");
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return;
+                setErrorMessage(error instanceof Error ? error.message : String(error));
+                setLoadingProgress("");
+            }
+        })();
+        return () => controller.abort();
+    }, [selectedVersion, forceWASM]);
+    const selectVersion = useCallback((version) => {
+        setSelectedVersion(version);
+        setErrorMessage(null);
+    }, []);
+    const setForceWASM = useCallback((next) => setForceWASMState(next), []);
+    const selectedRelease = useMemo(() => manifest?.releases.find((r) => r.version === selectedVersion) ?? null, [manifest, selectedVersion]);
+    return {
+        manifest,
+        selectedVersion,
+        selectedRelease,
+        assets,
+        ready: assets !== null,
+        loadingProgress,
+        loadingStepIndex,
+        loadingStepLabels,
+        errorMessage,
+        activeBackend,
+        forceWASM,
+        selectVersion,
+        setForceWASM,
+    };
+}
+//# sourceMappingURL=useDemoRuntime.js.map

package/out/runtime/useDemoRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDemoRuntime.js","sourceRoot":"","sources":["../../runtime/useDemoRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AA6FzE;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC7B,MAA4C;IAE5C,MAAM,EAAE,eAAe,GAAG,mBAAmB,EAAE,GAAG,MAAM,CAAA;IAExD,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAgC,IAAI,CAAC,CAAA;IAC7E,MAAM,CAAC,eAAe,EAAE,kBAAkB,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAA;IAC3E,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAiB,IAAI,CAAC,CAAA;IAC1D,MAAM,CAAC,eAAe,EAAE,kBAAkB,CAAC,GAAG,QAAQ,CAAS,eAAe,CAAC,CAAA;IAC/E,MAAM,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAA;IAC5D,MAAM,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,GAAG,QAAQ,CAAW,EAAE,CAAC,CAAA;IACxE,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAA;IACrE,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAAS,EAAE,CAAC,CAAA;IAC9D,MAAM,CAAC,SAAS,EAAE,iBAAiB,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IAEtD,oHAAoH;IACpH,4FAA4F;IAC5F,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;IACnD,eAAe,CAAC,OAAO,GAAG,MAAM,CAAC,YAAY,CAAA;IAC7C,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;IAC/C,aAAa,CAAC,OAAO,GAAG,MAAM,CAAC,UAAU,CAAA;IAEzC,6GAA6G;IAC7G,+GAA+G;IAC/G,gDAAgD;IAChD,MAAM,WAAW,GAAG,MAAM,CAAgC,IAAI,CAAC,CAAA;IAC/D,WAAW,CAAC,OAAO,GAAG,QAAQ,CAAA;IAE9B,8DAA8D;IAC9D,SAAS,CAAC,GAAG,EAAE;QACd,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;QAExC,KAAK,CAAC,KAAK,IAAI,EAAE;YAChB,IAAI,CAAC;gBACJ,MAAM,IAAI,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;gBAE7D,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO;oBAAE,OAAM;gBAErC,IAAI,IAAI,EAAE,CAAC;oBACV,WAAW,CAAC,IAAI,CAAC,CAAA;oBACjB,kBAAkB,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;gBACxC,CAAC;YACF,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO;oBAAE,OAAM;gBACrC,eAAe,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;YACxE,CAAC;QACF,CAAC,CAAC,EAAE,CAAA;QAEJ,OAAO,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,CAAA;IAChC,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,qFAAqF;IACrF,SAAS,CAAC,GAAG,EAAE;QACd,IAAI,CAAC,eAAe;YAAE,OAAM;QAE5B,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,eAAe,CAAC,IAAI,IAAI,CAAA;QAEhG,IAAI,CAAC,OAAO;YAAE,OAAM;QAEpB,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;QACxC,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAA;QAC7B,MAAM,KAAK,GAAG,CAAC,EAAc,EAAE,EAAE;YAChC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACrB,EAAE,EAAE,CAAA;YACL,CAAC;QACF,CAAC,CAAA;QAED,KAAK,CAAC,KAAK,IAAI,EAAE;YAChB,IAAI,CAAC;gBACJ,SAAS,CAAC,IAAI,CAAC,CAAA;gBACf,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAA;gBACvB,oBAAoB,CAAC,EAAE,CAAC,CAAA;gBACxB,gBAAgB,CAAC,EAAE,CAAC,CAAA;gBAEpB,MAAM,GAAG,GAA0B;oBAClC,MAAM;oBACN,SAAS;oBACT,WAAW,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;oBACpE,aAAa,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;oBACpE,YAAY,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;oBAChE,UAAU,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;iBAC/D,CAAA;gBAED,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;gBAExD,IAAI,MAAM,CAAC,OAAO;oBAAE,OAAM;gBAC1B,SAAS,CAAC,MAAM,CAAC,CAAA;gBACjB,kBAAkB,CAAC,EAAE,CAAC,CAAA;YACvB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,IAAI,MAAM,CAAC,OAAO;oBAAE,OAAM;gBAC1B,eAAe,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;gBACvE,kBAAkB,CAAC,EAAE,CAAC,CAAA;YACvB,CAAC;QACF,CAAC,CAAC,EAAE,CAAA;QAEJ,OAAO,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,CAAA;IAChC,CAAC,EAAE,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC,CAAA;IAEhC,MAAM,aAAa,GAAG,WAAW,CAAC,CAAC,OAAe,EAAE,EAAE;QACrD,kBAAkB,CAAC,OAAO,CAAC,CAAA;QAC3B,eAAe,CAAC,IAAI,CAAC,CAAA;IACtB,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,MAAM,YAAY,GAAG,WAAW,CAAC,CAAC,IAAa,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAA;IAEhF,MAAM,eAAe,GAAG,OAAO,CAC9B,GAAG,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,eAAe,CAAC,IAAI,IAAI,EAC3E,CAAC,QAAQ,EAAE,eAAe,CAAC,CAC3B,CAAA;IAED,OAAO;QACN,QAAQ;QACR,eAAe;QACf,eAAe;QACf,MAAM;QACN,KAAK,EAAE,MAAM,KAAK,IAAI;QACtB,eAAe;QACf,gBAAgB;QAChB,iBAAiB;QACjB,YAAY;QACZ,aAAa;QACb,SAAS;QACT,aAAa;QACb,YAAY;KACZ,CAAA;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/react",
-  "version": "7.5.0",
+  "version": "7.6.0",
   "description": "React components + headless hooks for mailwoman — parse/geocode/POI explorers, Storybook-tested, Docusaurus-independent.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
@@ -39,6 +39,10 @@
     ".": {
       "types": "./out/index.d.ts",
       "default": "./out/index.js"
+    },
+    "./map": {
+      "types": "./out/map/index.d.ts",
+      "default": "./out/map/index.js"
     }
   },
   "publishConfig": {
@@ -49,18 +53,23 @@
       ".": {
         "types": "./out/index.d.ts",
         "default": "./out/index.js"
+      },
+      "./map": {
+        "types": "./out/map/index.d.ts",
+        "default": "./out/map/index.js"
       }
     }
   },
   "scripts": {
     "storybook": "storybook dev -p 6007 --no-open",
     "build-storybook": "storybook build",
-    "test:browser": "vitest run --config vitest.config.ts"
+    "test:browser": "vitest run --config vitest.config.ts",
+    "test:node": "vitest run --config vitest.node.config.ts"
   },
   "dependencies": {
-    "@mailwoman/kind-classifier": "7.5.0",
-    "@mailwoman/poi-taxonomy": "7.5.0",
-    "@mailwoman/query-shape": "7.5.0"
+    "@mailwoman/kind-classifier": "7.6.0",
+    "@mailwoman/poi-taxonomy": "7.6.0",
+    "@mailwoman/query-shape": "7.6.0"
   },
   "devDependencies": {
     "@storybook/addon-docs": "^10.5.2",
@@ -70,15 +79,27 @@
     "@vitejs/plugin-react": "^6.0.3",
     "@vitest/browser": "4.1.10",
     "@vitest/browser-playwright": "4.1.10",
+    "maplibre-gl": "^5.24.0",
     "playwright": "^1.61.1",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
+    "react-map-gl": "^8.1.1",
     "storybook": "^10.5.2",
     "vite": "^8.1.5",
     "vitest": "4.1.10"
   },
   "peerDependencies": {
+    "maplibre-gl": ">=5",
     "react": ">=18",
-    "react-dom": ">=18"
+    "react-dom": ">=18",
+    "react-map-gl": ">=8"
+  },
+  "peerDependenciesMeta": {
+    "maplibre-gl": {
+      "optional": true
+    },
+    "react-map-gl": {
+      "optional": true
+    }
   }
 }

package/pipeline/QueryForm.tsx

@@ -7,7 +7,7 @@
  *   parsing. Presentational; `onSubmit` fires on form submission.
  */
 
-import type { ReactNode } from "react"
+import type { InputHTMLAttributes, KeyboardEvent, ReactNode } from "react"
 
 import { LoadingIndicator } from "../common/LoadingIndicator.tsx"
 
@@ -18,9 +18,22 @@ export interface QueryFormProps {
 	disabled?: boolean
 	busy?: boolean
 	placeholder?: string
+	/** Keydown on the input — the seam a combobox (the demo's place-autocomplete) needs for arrow/Enter/Esc nav. */
+	onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void
+	/** Escape hatch for extra `<input>` attributes (aria-combobox props, `autoComplete`, …). Merged last. */
+	inputProps?: InputHTMLAttributes<HTMLInputElement>
 }
 
-export function QueryForm({ value, onChange, onSubmit, disabled, busy, placeholder }: QueryFormProps): ReactNode {
+export function QueryForm({
+	value,
+	onChange,
+	onSubmit,
+	disabled,
+	busy,
+	placeholder,
+	onKeyDown,
+	inputProps,
+}: QueryFormProps): ReactNode {
 	return (
 		<form
 			className="mw-field"
@@ -37,6 +50,8 @@ export function QueryForm({ value, onChange, onSubmit, disabled, busy, placehold
 				onChange={(e) => onChange(e.target.value)}
 				disabled={disabled}
 				placeholder={placeholder}
+				onKeyDown={onKeyDown}
+				{...inputProps}
 			/>
 			<button type="submit" disabled={disabled || busy}>
 				{busy ? (