@mailwoman/react 7.4.0 → 7.6.0

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.4.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,36 +53,53 @@
       ".": {
         "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.4.0",
-    "@mailwoman/poi-taxonomy": "7.4.0",
-    "@mailwoman/query-shape": "7.4.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.0",
-    "@storybook/react-vite": "^10.5.0",
+    "@storybook/addon-docs": "^10.5.2",
+    "@storybook/react-vite": "^10.5.2",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@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",
-    "storybook": "^10.5.0",
-    "vite": "^8.0.16",
+    "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 ? (

package/poi/LiveResultsBlock.tsx

@@ -14,15 +14,15 @@ import { formatDistance } from "./runtime.ts"
 import type { LiveSearchState } from "./types.ts"
 
 export interface LiveResultsBlockProps {
-	/** Category label for empty-state copy ("No hospital results near …"). */
-	categoryLabel: string
+	/** Subject label for empty-state copy — a category ("No hospital results near …") or a brand ("No chevron results …"). */
+	subjectLabel: string
 	/** The location anchor the search runs against (empty ⇒ the button is disabled with a hint). */
 	anchor: string
 	state: LiveSearchState
 	onSearch: () => void
 }
 
-export function LiveResultsBlock({ categoryLabel, anchor, state, onSearch }: LiveResultsBlockProps): ReactNode {
+export function LiveResultsBlock({ subjectLabel, anchor, state, onSearch }: LiveResultsBlockProps): ReactNode {
 	const hasAnchor = anchor.trim().length > 0
 
 	return (
@@ -47,7 +47,7 @@ export function LiveResultsBlock({ categoryLabel, anchor, state, onSearch }: Liv
 			) : state.status === "success" ? (
 				state.hits.length === 0 ? (
 					<p className="mw-muted">
-						No {categoryLabel.toLowerCase()} results near {state.centerName}.
+						No {subjectLabel.toLowerCase()} results near {state.centerName}.
 					</p>
 				) : (
 					<>

package/poi/POIExplorer.tsx

@@ -32,6 +32,12 @@ export interface POIExplorerProps {
 	loadRuntime?: LoadPOIRuntime
 	/** Live poi.db probe. Absent ⇒ intent-only (no live-results affordance). */
 	runLiveSearch?: POILiveSearch
+	/**
+	 * Whether {@link runLiveSearch} can serve BRAND subjects (fetch by QID). Default false: a brand subject shows the
+	 * intent + QID chip but no live block. The docs' httpvfs probe leaves this off (brand-wide byte-range hydration is
+	 * pathological — measured); a server-side backend can enable it.
+	 */
+	brandLiveSearch?: boolean
 }
 
 interface POIExplorerInnerProps extends POIExplorerProps {
@@ -39,9 +45,30 @@ interface POIExplorerInnerProps extends POIExplorerProps {
 	presets: ReadonlyArray<Preset>
 }
 
-function POIExplorerInner({ defaultText, presets, loadRuntime, runLiveSearch }: POIExplorerInnerProps): ReactNode {
+function POIExplorerInner({
+	defaultText,
+	presets,
+	loadRuntime,
+	runLiveSearch,
+	brandLiveSearch,
+}: POIExplorerInnerProps): ReactNode {
 	const [text, setText] = useState(defaultText)
-	const { result, liveSearch, searchLive } = usePOISearch({ text, loadRuntime, runLiveSearch })
+	const { result, liveSearch, searchLive } = usePOISearch({
+		text,
+		loadRuntime,
+		runLiveSearch,
+		brandLiveSearch,
+	})
+
+	const subject = result?.subject
+	// The live block appears whenever the subject COULD be live-searched with an anchor — i.e. capable minus the
+	// anchor-present requirement (`canSearchLive` also requires an anchor; the block itself renders the "add an anchor"
+	// hint, so it must show one step earlier). Category: not build-local. Brand: brand-capable probe + a QID.
+	const showLiveBlock = Boolean(
+		runLiveSearch &&
+		subject &&
+		(subject.kind === "brand" ? brandLiveSearch && subject.wikidata !== undefined : !subject.buildLocal)
+	)
 
 	return (
 		<div className="mw-poi-explorer">
@@ -52,15 +79,17 @@ function POIExplorerInner({ defaultText, presets, loadRuntime, runLiveSearch }:
 				<div className="mw-result">
 					<KindBadge kindResult={result.kindResult} />
 
-					{result.subject ? (
+					{subject ? (
 						<>
-							<SubjectPanel subject={result.subject} />
-							<OverpassBlock overpassQL={result.overpassQL} overpassError={result.overpassError} />
+							<SubjectPanel subject={subject} />
+							{subject.kind === "category" ? (
+								<OverpassBlock overpassQL={result.overpassQL} overpassError={result.overpassError} />
+							) : null}
 
-							{runLiveSearch && !result.subject.buildLocal ? (
+							{showLiveBlock ? (
 								<LiveResultsBlock
-									categoryLabel={result.subject.category.label}
-									anchor={result.subject.remainder}
+									subjectLabel={subject.kind === "brand" ? subject.name : subject.category.label}
+									anchor={subject.remainder}
 									state={liveSearch}
 									onSearch={searchLive}
 								/>
@@ -80,6 +109,7 @@ export function POIExplorer({
 	presets = POI_PRESETS,
 	loadRuntime,
 	runLiveSearch,
+	brandLiveSearch,
 }: POIExplorerProps): ReactNode {
 	return (
 		<ClientOnly
@@ -95,6 +125,7 @@ export function POIExplorer({
 					presets={presets}
 					loadRuntime={loadRuntime}
 					runLiveSearch={runLiveSearch}
+					brandLiveSearch={brandLiveSearch}
 				/>
 			)}
 		</ClientOnly>

package/poi/SubjectPanel.tsx

@@ -3,8 +3,9 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `SubjectPanel` — renders the detected POI subject: the category chip, the optional build-local
- *   badge + note, and the match-detail list (matched phrase, confidence, anchor). Presentational.
+ *   `SubjectPanel` — renders the detected POI subject. For a CATEGORY: the category chip, the optional
+ *   build-local badge + note. For a BRAND: the brand-name chip + a Wikidata QID chip (linked). Both
+ *   share the match-detail list (matched phrase, confidence, anchor). Presentational.
  */
 
 import type { ReactNode } from "react"
@@ -15,7 +16,50 @@ export interface SubjectPanelProps {
 	subject: POISubject
 }
 
+/** The shared match-detail list (matched phrase, confidence, anchor) — identical for category + brand subjects. */
+function MatchDetail({ subject }: SubjectPanelProps): ReactNode {
+	return (
+		<dl className="mw-subject__detail">
+			<dt>matched phrase</dt>
+			<dd>
+				<code>{subject.matchedPhrase}</code>
+			</dd>
+			<dt>confidence</dt>
+			<dd>{Math.round(subject.confidence * 100)}%</dd>
+			<dt>anchor</dt>
+			<dd>{subject.remainder ? subject.remainder : <em>none — global query</em>}</dd>
+		</dl>
+	)
+}
+
 export function SubjectPanel({ subject }: SubjectPanelProps): ReactNode {
+	if (subject.kind === "brand") {
+		return (
+			<>
+				<div className="mw-subject__row">
+					<span className="mw-subject__chip">{subject.name}</span>
+					<span className="mw-subject__badge mw-subject__badge--brand">brand</span>
+					{subject.wikidata ? (
+						<a
+							className="mw-subject__qid"
+							href={`https://www.wikidata.org/wiki/${subject.wikidata}`}
+							target="_blank"
+							rel="noreferrer"
+						>
+							{subject.wikidata}
+						</a>
+					) : null}
+				</div>
+
+				<MatchDetail subject={subject} />
+
+				<p className="mw-subject__note">
+					Matched as a chain brand — resolved by Wikidata QID against the layer's brand index.
+				</p>
+			</>
+		)
+	}
+
 	return (
 		<>
 			<div className="mw-subject__row">
@@ -23,16 +67,7 @@ export function SubjectPanel({ subject }: SubjectPanelProps): ReactNode {
 				{subject.buildLocal ? <span className="mw-subject__badge">build-local</span> : null}
 			</div>
 
-			<dl className="mw-subject__detail">
-				<dt>matched phrase</dt>
-				<dd>
-					<code>{subject.matchedPhrase}</code>
-				</dd>
-				<dt>confidence</dt>
-				<dd>{Math.round(subject.confidence * 100)}%</dd>
-				<dt>anchor</dt>
-				<dd>{subject.remainder ? subject.remainder : <em>none — global query</em>}</dd>
-			</dl>
+			<MatchDetail subject={subject} />
 
 			{subject.buildLocal ? (
 				<p className="mw-subject__note">

package/poi/runtime.ts

@@ -11,36 +11,61 @@
 
 import { createKindClassifier } from "@mailwoman/kind-classifier"
 import type { POIPhraseLookup } from "@mailwoman/kind-classifier"
-import { createPOITaxonomyLookup } from "@mailwoman/poi-taxonomy/table"
+import { createPOIBrandLookup, createPOITaxonomyLookup } from "@mailwoman/poi-taxonomy/table"
 
 import type { POIRuntime } from "./types.ts"
 
 /**
- * Build the POI runtime, dynamically importing the taxonomy JSON so the ~2k-record table lands in its own chunk. A
+ * Build the POI runtime, dynamically importing the taxonomy + brand JSON so the tables land in their own chunk. A
  * static import would inline the whole snapshot into every consumer's bundle.
+ *
+ * The lexicon unions categories then brands, mirroring the Node runtime's `poiTaxonomyLookup` precedence: a phrase that
+ * matches a taxonomy CATEGORY wins (the curated set); only on a category miss does the chain-brand table fire,
+ * returning a `kind: "brand"` match carrying the brand's canonical name + Wikidata QID. (The Node path also chains
+ * `@mailwoman/variant-aliases` regional slang; the browser tester leaves that out — one fewer package + data table for
+ * a demo, and the QID-keyed brand table already covers the headline brands.)
  */
 export async function loadPOIRuntime(): Promise<POIRuntime> {
-	const table = (await import("@mailwoman/poi-taxonomy/data/taxonomy.json")).default
+	const [table, brandTable] = await Promise.all([
+		import("@mailwoman/poi-taxonomy/data/taxonomy.json").then((m) => m.default),
+		import("@mailwoman/poi-taxonomy/data/brands.json").then((m) => m.default),
+	])
 	const lookup = createPOITaxonomyLookup(table as unknown as Parameters<typeof createPOITaxonomyLookup>[0])
+	const brands = createPOIBrandLookup(brandTable as unknown as Parameters<typeof createPOIBrandLookup>[0])
+
+	// Adapt the taxonomy + brand lookups to the `POIPhraseLookup` shape the classifier expects: categories first, brands
+	// on a category miss.
+	const lexicon: POIPhraseLookup = (phrase, locale) => {
+		const categoryHits = lookup.lookupPOICategory(phrase, locale)
+
+		if (categoryHits.length > 0) {
+			return categoryHits.map((match) => ({
+				kind: "category",
+				categoryID: match.category.id,
+				matchedPhrase: match.matchedPhrase,
+				confidence: match.confidence,
+			}))
+		}
 
-	// Adapt `POITaxonomyLookup.lookupPOICategory` to the `POIPhraseLookup` shape the classifier expects.
-	const lexicon: POIPhraseLookup = (phrase, locale) =>
-		lookup.lookupPOICategory(phrase, locale).map((match) => ({
-			kind: "category",
-			categoryID: match.category.id,
+		return brands.lookupPOIBrand(phrase).map((match) => ({
+			kind: "brand",
+			categoryID: match.brand.name,
+			wikidata: match.brand.wikidata,
 			matchedPhrase: match.matchedPhrase,
 			confidence: match.confidence,
 		}))
+	}
 
 	return { lookup, lexicon, classify: createKindClassifier({ poiLexicon: lexicon }) }
 }
 
-/** Default example queries for the POI explorer. */
+/** Default example queries for the POI explorer — a mix of category, build-local, and chain-brand subjects. */
 export const POI_PRESETS = [
 	{ label: "Drinking fountain", value: "drinking fountain near Springfield" },
 	{ label: "Fire hydrant", value: "fire hydrant" },
 	{ label: "Hospital + address", value: "hospital, 350 5th Ave, New York" },
-	{ label: "Biking trails", value: "biking trails near Portland" },
+	{ label: "Chevron (brand)", value: "chevron near Houston" },
+	{ label: "Applebee's (brand)", value: "applebee's near Chicago" },
 ] as const
 
 export const POI_DEFAULT_TEXT = POI_PRESETS[0].value