wovvmap-webview-bridge 1.0.28 → 1.0.39

package/README.md

@@ -1,282 +1,1624 @@
 # wovvmap-webview-bridge
 
-A typed bridge between React Native and a WebView for Wovvmap maps. It provides:
-- WebViewScreen wrapper for React Native WebView
-- BridgeService helpers to send events to the WebView
-- Zustand store (useBridgeStorage) that keeps incoming state in sync
-- Strongly typed message contracts
+`wovvmap-webview-bridge` is the host-side SDK for embedding a WovvMap viewer inside a web iframe or a React Native WebView.
+
+It gives the host app:
+
+- iframe/WebView components
+- typed bridge command services
+- synced Zustand stores for viewer data
+- event handlers for viewer interactions
+- TypeScript types for categories, stores, directions, floors, navigation, and viewer configuration
+
+The package is designed so a host developer does not need to create bridge command services manually. UI code should call the exported `*BridgeService` classes and read state from the exported stores.
+
+## Entry Points
+
+Use the web entry point in React web apps:
+
+```ts
+import {
+  WebIframeScreen,
+  DirectionBridgeService,
+  useCategoryStore,
+} from "wovvmap-webview-bridge/web";
+```
+
+Use the root entry point in React Native apps:
+
+```ts
+import {
+  WebViewScreen,
+  DirectionBridgeService,
+  useCategoryStore,
+} from "wovvmap-webview-bridge";
+```
 
 ## Installation
 
+For web iframe hosts:
+
 ```bash
-npm install react-native-webview zustand
-# or
-yarn add react-native-webview zustand
+npm install wovvmap-webview-bridge zustand
 ```
 
-## Quick start
+For React Native hosts:
+
+```bash
+npm install wovvmap-webview-bridge zustand react-native-webview
+```
 
-### Web (React TS) usage
+## Basic Web Iframe Setup
 
-Use the web entrypoint so you don't need `react-native` or `react-native-webview` in your web app.
+The host app owns the map id. The package does not store `mapId` because each host decides which map to open.
 
 ```tsx
-import React from "react";
 import { WebIframeScreen } from "wovvmap-webview-bridge/web";
 
-export default function App() {
+export function MapHost({ mapId }: { mapId: string | null }) {
+  if (!mapId) {
+    return null;
+  }
+
   return (
     <WebIframeScreen
-      url="https://your-map-app-url.com"
-      origin="https://your-map-app-url.com"
-      onload={() => console.log("iframe loaded")}
-      style={{ width: "100%", height: "100vh" }}
+      url={`https://viewer.example.com/viewer/${mapId}?v=v2&template=embedded`}
+      origin="https://viewer.example.com"
+      onload={() => console.log("Viewer iframe loaded")}
+      style={{ width: "100%", height: "100%", border: "none" }}
     />
   );
 }
 ```
 
-You can also attach to your own iframe ref:
+For local development this can look like:
 
 ```tsx
-import React, { useEffect, useRef } from "react";
-import {
-  attachIframeBridge,
-  registerBridgeHandler,
-  sendStartPointToBridge,
-} from "wovvmap-webview-bridge/web";
+<WebIframeScreen
+  url={`http://localhost:5174/viewer/${mapId}?v=v2&template=embedded`}
+  origin="http://localhost:5174"
+  style={{ width: "100%", height: "100%", border: "none" }}
+/>
+```
+
+## Basic React Native Setup
+
+```tsx
+import { WebViewScreen } from "wovvmap-webview-bridge";
+
+export function MapWebView({ mapId }: { mapId: string }) {
+  return (
+    <WebViewScreen
+      url={`https://viewer.example.com/viewer/${mapId}?v=v2&template=embedded`}
+      onload={() => console.log("Viewer loaded")}
+    />
+  );
+}
+```
+
+## Optional Manual Iframe Setup
+
+Use `attachIframeBridge` when you already render your own iframe.
+
+```tsx
+import { useEffect, useRef } from "react";
+import { attachIframeBridge } from "wovvmap-webview-bridge/web";
 
-export default function App() {
+export function CustomIframe({ url }: { url: string }) {
   const iframeRef = useRef<HTMLIFrameElement>(null);
 
   useEffect(() => {
     if (!iframeRef.current) return;
 
-    const cleanup = attachIframeBridge({
+    return attachIframeBridge({
       iframe: iframeRef.current,
-      origin: "https://your-map-app-url.com",
-      onLoad: () => sendStartPointToBridge("A1"),
+      origin: "https://viewer.example.com",
+      onLoad: () => console.log("loaded"),
     });
+  }, []);
 
-    registerBridgeHandler("isSceneClick", (payload) => {
-      console.log("Scene clicked", payload);
-    });
+  return <iframe ref={iframeRef} src={url} title="Wovv Map" />;
+}
+```
 
-    return cleanup;
-  }, []);
+## Recommended Import Surface
+
+Most apps should import only from `"wovvmap-webview-bridge/web"` or `"wovvmap-webview-bridge"`.
+
+```ts
+import {
+  WebIframeScreen,
+  DirectionBridgeService,
+  SelectionBridgeService,
+  FloorBridgeService,
+  StepNavigationBridgeService,
+  ZoomBridgeService,
+  ViewerBridgeService,
+  useBridgeStorage,
+  useViewerStore,
+  useCategoryStore,
+  useSubCategoryStore,
+  useAmenityStore,
+  useNodePointStore,
+  useSelectionStore,
+  useDirectionStore,
+  useFloorStore,
+  useNavigationStore,
+  useDirectionsRouteRequestStore,
+  registerBridgeHandler,
+} from "wovvmap-webview-bridge/web";
+```
+
+## Exported Components
+
+### `WebIframeScreen`
+
+Web-only component for embedding the WovvMap viewer in an iframe.
+
+Props:
+
+```ts
+type WebIframeScreenProps = {
+  url: string;
+  origin?: string;
+  onload?: () => void;
+  title?: string;
+  style?: React.CSSProperties;
+};
+```
+
+Use this in React web apps.
+
+### `WebViewScreen`
+
+React Native component for embedding the WovvMap viewer in `react-native-webview`.
+
+Props:
+
+```ts
+type WebViewScreenProps = {
+  url: string;
+  onload?: () => void;
+};
+```
+
+Use this in React Native apps.
+
+### `attachIframeBridge`
+
+Manual bridge attachment for custom iframe implementations.
+
+```ts
+attachIframeBridge({
+  iframe,
+  origin,
+  onLoad,
+});
+```
+
+## Command Services
+
+Use these services from host UI. They update host-side package stores when needed and send the correct bridge event to the embedded viewer.
+
+### `DirectionBridgeService`
+
+Controls origin, destination, route generation, path clearing, and origin/destination swap.
+
+Methods:
+
+```ts
+DirectionBridgeService.configure(config);
+DirectionBridgeService.setDestination(nodeId, cameraAnimate, clearSelection);
+DirectionBridgeService.setOrigin(nodeId, cameraAnimate, clearSelection);
+DirectionBridgeService.clearDestination(clearQuery);
+DirectionBridgeService.clearOrigin();
+DirectionBridgeService.swapOriginDestination();
+DirectionBridgeService.generateDirectionsRoute(callbacks);
+DirectionBridgeService.clearActivePath();
+```
+
+Parameters:
+
+- `nodeId`: a node key string. Multiple store locations can be joined with `"<->"`, for example `"2105,1601,3<->3166,1570,3"`.
+- `cameraAnimate`: when `true`, viewer camera animates to the point.
+- `clearSelection`: when `true`, viewer clears active category/subcategory/amenity selection.
+- `clearQuery`: when `true`, your host input adapter clears the visible input text.
+
+Basic destination example:
+
+```ts
+DirectionBridgeService.setDestination("2105,1601,3", true, false);
+```
+
+Basic origin example:
+
+```ts
+DirectionBridgeService.setOrigin("4360,2330,5", true, true);
+```
+
+Clear destination:
+
+```ts
+DirectionBridgeService.clearDestination(true);
+```
+
+Generate route:
+
+```ts
+DirectionBridgeService.generateDirectionsRoute({
+  onSuccess: (result) => {
+    console.log("Route ready", result.navigationResult);
+  },
+  onError: (result) => {
+    console.log("Route failed", result.error);
+  },
+});
+```
+
+Swap from/to:
+
+```ts
+DirectionBridgeService.swapOriginDestination();
+```
+
+Clear drawn path:
+
+```ts
+DirectionBridgeService.clearActivePath();
+```
+
+#### Direction Input Adapter
+
+The package does not own your input UI state. If your app has local "From" and "To" input text, connect it once with `configure`.
+
+```ts
+import {
+  DirectionBridgeService,
+  SelectionBridgeService,
+  useNodePointStore,
+} from "wovvmap-webview-bridge/web";
+import { useDirectionInputStore } from "./store/useDirectionInputStore";
+
+DirectionBridgeService.configure({
+  directionInputAdapter: {
+    setDestinationState: (query, selectedId) => {
+      useDirectionInputStore.getState().setDestinationState(query, selectedId);
+    },
+    setOriginState: (query, selectedId) => {
+      useDirectionInputStore.getState().setOriginState(query, selectedId);
+    },
+    clearDestinationState: (clearQuery) => {
+      useDirectionInputStore.getState().clearDestinationState(clearQuery);
+    },
+    clearOriginState: () => {
+      useDirectionInputStore.getState().clearOriginState();
+    },
+    setActiveDirectionField: (field) => {
+      useDirectionInputStore.getState().setActiveDirectionField(field);
+    },
+    getOriginQuery: () => useDirectionInputStore.getState().originQuery,
+    getDestinationQuery: () => useDirectionInputStore.getState().destinationQuery,
+  },
+  resolveLocationName: (nodeId) => {
+    const nodeKey = nodeId.split("<->")[0];
+    const node = useNodePointStore.getState().getNodePointByKey(nodeKey);
+    return node?.assets?.locationName?.text || nodeKey;
+  },
+  onClearSelection: () => {
+    SelectionBridgeService.clearSelection();
+  },
+});
+```
+
+Why this exists:
+
+- different companies can build different input UIs
+- the SDK still updates local input text when `setOrigin`, `setDestination`, or `swapOriginDestination` is called
+- SDK code does not import app-specific stores
+
+If you do not configure an adapter, direction commands still work. Only local input text will not auto-update.
+
+### `SelectionBridgeService`
+
+Controls category, subcategory, amenity, offers, and clear selection.
+
+Methods:
+
+```ts
+SelectionBridgeService.selectCategory(category);
+SelectionBridgeService.selectSubCategory(subCategory);
+SelectionBridgeService.selectAmenity(amenity);
+SelectionBridgeService.toggleOffers();
+SelectionBridgeService.clearSelection();
+SelectionBridgeService.syncHighlightsWithState();
+```
+
+Category example:
+
+```tsx
+import { SelectionBridgeService, useCategoryStore } from "wovvmap-webview-bridge/web";
+
+function CategoryButton({ code }: { code: string }) {
+  const category = useCategoryStore((s) => s.categories[code]);
+  const activeSelection = useSelectionStore((s) => s.activeSelection);
+
+  if (!category) return null;
+
+  const isActive =
+    activeSelection.type === "Category" &&
+    activeSelection.id === category.code.toString();
 
   return (
-    <iframe
-      ref={iframeRef}
-      src="https://your-map-app-url.com"
-      style={{ width: "100%", height: "100%", border: 0 }}
-      title="Wovv Map"
-    />
+    <button
+      className={isActive ? "active" : ""}
+      onClick={() => SelectionBridgeService.selectCategory(category)}
+    >
+      {category.name}
+    </button>
   );
 }
 ```
 
-### 1) Render the WebView
+Subcategory example:
 
 ```tsx
-import React from "react";
-import { WebViewScreen } from "wovvmap-webview-bridge";
+SelectionBridgeService.selectSubCategory(subCategory);
+```
+
+Amenity example:
+
+```tsx
+SelectionBridgeService.selectAmenity(amenity);
+```
+
+Amenity selection also sets the destination with the amenity node keys:
+
+```ts
+DirectionBridgeService.setDestination(amenity.nodePointsKey.join("<->"), true, false);
+```
+
+Offers button example:
+
+```tsx
+import { SelectionBridgeService, useNodePointStore, useSelectionStore } from "wovvmap-webview-bridge/web";
+
+export function OffersButton() {
+  const offersNodeMap = useNodePointStore((s) => s.offersNodeMap);
+  const isOfferSelected = useSelectionStore((s) => s.isOfferSelected);
+  const hasOffers = (offersNodeMap.all_offers?.nodePointsKey?.length ?? 0) > 0;
 
-export default function App() {
-  return <WebViewScreen url="https://your-map-app-url.com" />;
+  if (!hasOffers) return null;
+
+  return (
+    <button
+      className={isOfferSelected ? "active" : ""}
+      onClick={() => SelectionBridgeService.toggleOffers()}
+    >
+      Offers
+    </button>
+  );
 }
 ```
 
-### 2) Send events to the WebView (RN -> Web)
+Important selection states:
+
+- Category active: `useSelectionStore((s) => s.activeSelection.type === "Category")`
+- Selected category id: `useSelectionStore((s) => s.activeSelection.id)`
+- Active category object: `useSelectionStore((s) => s.activeCategory)`
+- Subcategory active: `activeSelection.type === "SubCategory"`
+- Amenity active: `activeSelection.type === "Amenity"`
+- Offers active: `useSelectionStore((s) => s.isOfferSelected)`
+
+### `FloorBridgeService`
+
+Controls active floor.
+
+```ts
+FloorBridgeService.changeFloor(floorIndex, animateCamera);
+```
+
+Floor selector example:
 
 ```tsx
-import {
-  sendStartPointToBridge,
-  sendEndPointToBridge,
-  sendActiveFloorToBridge,
-  sendPathNextBtnClick,
-  sendPathPreBtnClick,
-  sendPathFinishBtnClick,
-  sendSelectCategory,
-  sendZoomIn,
-  sendZoomOut,
-  sendClearStartAndEndPoint,
-  sendPathFilter,
-  sendGetDirectionToBridge,
-  sendNavigateToBridge,
-  sendMapThemeToBridge,
-} from "wovvmap-webview-bridge";
+import { FloorBridgeService, useFloorStore } from "wovvmap-webview-bridge/web";
+
+export function FloorSelector() {
+  const floors = useFloorStore((s) => s.floors);
+  const activeFloor = useFloorStore((s) => s.activeFloor);
 
-sendStartPointToBridge("A1");
-sendEndPointToBridge("B5");
-sendActiveFloorToBridge(2);
-sendPathNextBtnClick();
-sendPathPreBtnClick();
-sendPathFinishBtnClick();
-sendSelectCategory(["Food", "Fashion"]);
-sendZoomIn();
-sendZoomOut();
-sendClearStartAndEndPoint();
-sendPathFilter();
-sendGetDirectionToBridge();
-sendNavigateToBridge("map-id-123");
-sendMapThemeToBridge({ "theme-path-color": "#00AAFF" });
+  return (
+    <select
+      value={activeFloor ?? ""}
+      onChange={(event) => FloorBridgeService.changeFloor(Number(event.target.value), true)}
+    >
+      {floors.map((floor) => (
+        <option key={floor.index ?? floor.FloorNumber} value={floor.index}>
+          {floor.FloorName}
+        </option>
+      ))}
+    </select>
+  );
+}
 ```
 
-### 3) Handle events from the WebView (Web -> RN)
+### `StepNavigationBridgeService`
+
+Controls current step in step-by-step navigation.
+
+```ts
+StepNavigationBridgeService.goToStep(index);
+StepNavigationBridgeService.nextStep();
+StepNavigationBridgeService.prevStep();
+StepNavigationBridgeService.finishStep();
+```
 
-You can register handlers for click events. All other events are stored in the Zustand store.
+Step list example:
 
 ```tsx
-import { registerBridgeHandler } from "wovvmap-webview-bridge";
+import { StepNavigationBridgeService, useNavigationStore } from "wovvmap-webview-bridge/web";
 
-registerBridgeHandler("isSceneClick", (payload) => {
-  console.log("Scene clicked", payload);
-});
+export function StepList() {
+  const result = useNavigationStore((s) => s.navigationResult);
+  const currentStepIndex = useNavigationStore((s) => s.currentStepIndex);
 
-registerBridgeHandler("isShapeClick", (payload) => {
-  console.log("Shape clicked", payload.value);
-});
+  if (!result) return null;
+
+  return (
+    <div>
+      {result.steps.map((step, index) => (
+        <button
+          key={step.id}
+          className={currentStepIndex === index ? "active" : ""}
+          onClick={() => StepNavigationBridgeService.goToStep(index)}
+        >
+          {step.instruction}
+        </button>
+      ))}
+    </div>
+  );
+}
 ```
 
-### 4) Read synced state from the store
-
-```tsx
-import { useBridgeStorage } from "wovvmap-webview-bridge";
-
-const state = useBridgeStorage((s) => ({
-  isBridgeLoaded: s.isBridgeLoaded,
-  isMapLoaded: s.isMapLoaded,
-  searchablePoints: s.searchablePoints,
-  amenities: s.amenities,
-  allOffers: s.allOffers,
-  activeFloor: s.activeFloor,
-  stepByStepList: s.stepByStepList,
-  pathSummary: s.pathSummary,
-  categories: s.categories,
-  subCategories: s.subCategories,
-}));
-```
-
-Store fields:
-- isBridgeLoaded
-- isMapLoaded
-- searchablePoints
-- amenities
-- allOffers
-- activeFloor
-- elevator, escalator
-- floorImages
-- stepByStepList
-- pathSummary
-- nextPreState
-- pointsByKey
-- categories
-- subCategories
-- cameraControllerState
-
-## Bridge message contracts
-
-### IncomingMessage (Web -> RN)
-Keys and payloads:
-- pong: boolean
-- isConnection: boolean
-- mapLoaded: boolean
-- _searchablePoints: NodePoint[]
-- _allAmenities: AmenityWithNodePoint[]
-- _allOffers: string[]
-- _activeFloor: number
-- FloorImg: FloorImage[]
-- categories: Record<ExternalId, Category>
-- subCategories: Record<ExternalId, SubCategory>
-- isSceneClick: no value
-- isShapeClick: NodePoint
-- stepByStepList: StepByStepResult
-- pathNextPreState: NavState
-- cameraControllerState: { cameraPosition: CameraPosition; controlsPosition: ControlsPosition }
-
-### OutgoingMessage (RN -> Web)
-Keys and payloads:
-- applyCSS: { selector: string; style: Partial<CSSStyleDeclaration> }
-- ping: boolean
-- setEndPoint: string
-- setStartPoint: string
-- setActiveFloor: number
-- pathNextBtnClick: no value
-- pathPreBtnClick: no value
-- pathFinishBtnClick: no value
-- setSelectCategory: string | string[] | null
-- zoomIn: no value
-- zoomOut: no value
-- clearStartAndEndPoint: no value
-- setPathFilter: filterPath
-- getDirection: no value
-- setMapTheme: Theme | null
-- navigateTo: string
-- editableView: MapApiResponse
-- pathHighlightByStepIndex: number
-
-## Exported API
+Next/previous example:
 
-### Components
-- WebViewScreen
-- WebIframeScreen (web only)
-
-### Bridge helpers
-- sendStartPointToBridge
-- sendEndPointToBridge
-- sendActiveFloorToBridge
-- sendPathNextBtnClick
-- sendPathPreBtnClick
-- sendPathFinishBtnClick
-- sendSelectCategory
-- sendZoomIn
-- sendZoomOut
-- sendClearStartAndEndPoint
-- sendGetDirectionToBridge
-- sendPathFilter
-- sendNavigateToBridge
-- sendMapThemeToBridge
+```tsx
+<button onClick={() => StepNavigationBridgeService.prevStep()}>Previous</button>
+<button onClick={() => StepNavigationBridgeService.nextStep()}>Next</button>
+<button onClick={() => StepNavigationBridgeService.finishStep()}>Finish</button>
+```
 
-### Handlers
-- registerBridgeHandler
+### `ZoomBridgeService`
 
-### Store
-- useBridgeStorage (Zustand)
+Controls viewer zoom.
 
-### Types
-- IncomingMessage, OutgoingMessage
-- NodePoint
-- AmenityWithNodePoint
-- Category, SubCategory, ExternalId
-- Environment, DayHours, WeeklyHours
-- NodePointOffer, BrandInfo
-- MapExportContext, GeometryFloor, GeometryNodePoint, GeometryLayer
-- NodeMetadata, AssetPayloads
-- FloorImage
-- StepInstruction, PathSummary, StepByStepResult
-- NavState
-- filterPath
-- Theme
-- CameraPosition, ControlsPosition
-- MapApiResponse, MapDataExport
-
-## File structure
-
-```
-src/
-  index.ts
-  webviewBridge/
-    WebViewScreen.tsx
-    BridgeService.ts
-    BridgeStorage.ts
-    WebViewBridgeRef.ts
-  handlers/
-    WebBridgeHandlers.ts
-  types/
-    types.ts
-```
-
-## License
-
-MIT
+```ts
+ZoomBridgeService.zoomIn();
+ZoomBridgeService.zoomOut();
+```
+
+Example:
+
+```tsx
+<button onClick={() => ZoomBridgeService.zoomOut()}>Zoom Out</button>
+<button onClick={() => ZoomBridgeService.zoomIn()}>Zoom In</button>
+```
+
+### `ViewerBridgeService`
+
+Controls viewer mode, camera view, and text rendering.
+
+```ts
+ViewerBridgeService.setViewMode("2D", true);
+ViewerBridgeService.setViewMode("3D", true);
+ViewerBridgeService.setCameraView("street");
+ViewerBridgeService.setCameraView("sky");
+ViewerBridgeService.setTextType("2D");
+ViewerBridgeService.setTextType("3D");
+ViewerBridgeService.setShow2DIcon(true);
+ViewerBridgeService.setShow2DIcon(false);
+```
+
+Toolbar example:
+
+```tsx
+import { ViewerBridgeService, useViewerStore } from "wovvmap-webview-bridge/web";
+
+export function ViewerToolbar() {
+  const viewMode = useViewerStore((s) => s.viewMode);
+  const cameraView = useViewerStore((s) => s.cameraView);
+  const textType = useViewerStore((s) => s.textType);
+  const show2DIcon = useViewerStore((s) => s.show2DIcon);
+
+  return (
+    <div>
+      <button
+        className={viewMode === "2D" ? "active" : ""}
+        onClick={() => ViewerBridgeService.setViewMode("2D", true)}
+      >
+        2D View
+      </button>
+      <button
+        className={viewMode === "3D" ? "active" : ""}
+        onClick={() => ViewerBridgeService.setViewMode("3D", true)}
+      >
+        3D View
+      </button>
+      <button
+        className={cameraView === "street" ? "active" : ""}
+        onClick={() => ViewerBridgeService.setCameraView("street")}
+      >
+        Street
+      </button>
+      <button
+        className={cameraView === "sky" ? "active" : ""}
+        onClick={() => ViewerBridgeService.setCameraView("sky")}
+      >
+        Sky
+      </button>
+      <button
+        className={textType === "2D" ? "active" : ""}
+        onClick={() => ViewerBridgeService.setTextType("2D")}
+      >
+        2D Text
+      </button>
+      <button
+        className={textType === "3D" ? "active" : ""}
+        onClick={() => ViewerBridgeService.setTextType("3D")}
+      >
+        3D Text
+      </button>
+      <button
+        className={show2DIcon ? "active" : ""}
+        onClick={() => ViewerBridgeService.setShow2DIcon(!show2DIcon)}
+      >
+        2D Icon
+      </button>
+    </div>
+  );
+}
+```
+
+### `BridgeService`
+
+Low-level event sender. Use command services above for normal UI code.
+
+Available low-level methods:
+
+```ts
+BridgeService.setViewerConfig(config);
+BridgeService.setDestination(nodeId, cameraAnimate, clearSelection);
+BridgeService.clearDestination();
+BridgeService.setOrigin(nodeId, cameraAnimate, clearSelection);
+BridgeService.clearOrigin();
+BridgeService.swapOriginDestination();
+BridgeService.setActiveSelection(type, code);
+BridgeService.clearActiveSelection();
+BridgeService.setOfferSelected(isSelected);
+BridgeService.generateDirectionsRoute(callbacks);
+BridgeService.clearActivePath();
+BridgeService.changeFloor(floorIndex, animateCamera);
+BridgeService.goToStep(index);
+BridgeService.nextStep();
+BridgeService.prevStep();
+BridgeService.finishStep();
+BridgeService.zoomIn();
+BridgeService.zoomOut();
+BridgeService.setViewMode(viewMode, animate);
+BridgeService.setCameraView(cameraView);
+BridgeService.setTextType(textType);
+BridgeService.setShow2DIcon(show2DIcon);
+```
+
+## Synced Stores
+
+All stores are Zustand stores. Use them directly in React components.
+
+### `useBridgeStorage`
+
+Bridge and tenant state.
+
+Fields:
+
+- `isMapLoaded`: viewer sent map loaded state
+- `isBridgeLoaded`: bridge connection event received
+- `imageBaseUrl`: base URL for category, subcategory, amenity, and store images
+
+Example:
+
+```tsx
+const isReady = useBridgeStorage((s) => s.isBridgeLoaded && s.isMapLoaded);
+const imageBaseUrl = useBridgeStorage((s) => s.imageBaseUrl);
+```
+
+### `useViewerStore`
+
+Viewer configuration and loading state.
+
+Fields:
+
+- `apiVersion`: viewer API version, for example `"v2"`
+- `viewMode`: `"2D"` or `"3D"`
+- `cameraView`: `"street"` or `"sky"`
+- `textType`: `"2D"` or `"3D"`
+- `show2DIcon`: boolean
+- `isMapParsed`: true after viewer parsed map data
+- `isLoading`: viewer loading flag
+
+Example:
+
+```tsx
+const viewMode = useViewerStore((s) => s.viewMode);
+const cameraView = useViewerStore((s) => s.cameraView);
+```
+
+### `useCategoryStore`
+
+Category catalog.
+
+Fields:
+
+- `categories`: `Record<string, Category>`
+
+Example:
+
+```tsx
+const categories = useCategoryStore((s) => Object.values(s.categories));
+```
+
+Category active state:
+
+```tsx
+const activeSelection = useSelectionStore((s) => s.activeSelection);
+const isActiveCategory =
+  activeSelection.type === "Category" &&
+  activeSelection.id === category.code.toString();
+```
+
+### `useSubCategoryStore`
+
+Subcategory catalog.
+
+Fields:
+
+- `subCategories`: `Record<string, SubCategory>`
+
+Example:
+
+```tsx
+const subCategories = useSubCategoryStore((s) => Object.values(s.subCategories));
+```
+
+Subcategory active state:
+
+```tsx
+const isActiveSubCategory =
+  activeSelection.type === "SubCategory" &&
+  activeSelection.id === subCategory.code.toString();
+```
+
+### `useAmenityStore`
+
+Amenity catalog.
+
+Fields:
+
+- `amenities`: `Record<string, Amenity>`
+
+Example:
+
+```tsx
+const amenities = useAmenityStore((s) => Object.values(s.amenities));
+```
+
+Amenity active state:
+
+```tsx
+const isActiveAmenity =
+  activeSelection.type === "Amenity" &&
+  activeSelection.id === amenity.id.toString();
+```
+
+### `useNodePointStore`
+
+Searchable stores/locations and node maps.
+
+Fields:
+
+- `searchableNodePointMap`: `NodePoint[]`
+- `locationGroupedNodeMap`: `Record<string, string[]>`
+- `keyNodeMap`: `Record<string, NodePoint>`
+- `offersNodeMap`: `OffersNodeMap`
+
+Actions/helpers:
+
+- `getNodePointByKey(key)`
+- `clearSearchableNodePoints()`
+
+Example: search source data:
+
+```tsx
+const nodePoints = useNodePointStore((s) => s.searchableNodePointMap);
+```
+
+Example: get store name:
+
+```ts
+const node = useNodePointStore.getState().getNodePointByKey(nodeKey);
+const name = node?.assets?.locationName?.text || node?.key || "";
+```
+
+Example: group multi-location store:
+
+```ts
+const groupKeys = useNodePointStore.getState().locationGroupedNodeMap["Aldo"] || [];
+DirectionBridgeService.setDestination(groupKeys.join("<->"), true, false);
+```
+
+Example: offers data:
+
+```tsx
+const allOffers = useNodePointStore((s) => s.offersNodeMap.all_offers);
+const hasOffers = (allOffers?.nodePointsKey?.length ?? 0) > 0;
+```
+
+### `useSelectionStore`
+
+Active category/subcategory/amenity and offers state.
+
+Fields:
+
+- `activeSelection`: `{ type: "Category" | "SubCategory" | "Amenity" | null; id: string | null }`
+- `activeCategory`: `Category | null`
+- `isOfferSelected`: boolean
+
+Examples:
+
+```tsx
+const activeSelection = useSelectionStore((s) => s.activeSelection);
+const activeCategory = useSelectionStore((s) => s.activeCategory);
+const isOfferSelected = useSelectionStore((s) => s.isOfferSelected);
+```
+
+Offer button active:
+
+```tsx
+const isActive = useSelectionStore((s) => s.isOfferSelected);
+```
+
+Category tab active:
+
+```tsx
+const isActive =
+  activeSelection.type === "Category" &&
+  activeSelection.id === category.code.toString();
+```
+
+Subcategory tab active:
+
+```tsx
+const isActive =
+  activeSelection.type === "SubCategory" &&
+  activeSelection.id === subCategory.code.toString();
+```
+
+Amenity active:
+
+```tsx
+const isActive =
+  activeSelection.type === "Amenity" &&
+  activeSelection.id === amenity.id.toString();
+```
+
+### `useDirectionStore`
+
+Origin/destination and pathfinding state mirrored from the viewer.
+
+Fields:
+
+- `selectedOriginPointId`: selected start node id or joined node ids
+- `selectedDestinationPointId`: selected end node id or joined node ids
+- `pathfindingError`: route error string or `null`
+- `routingPreferences`: `{ elevator?: boolean; escalator?: boolean; stair?: boolean }`
+
+Examples:
+
+```tsx
+const origin = useDirectionStore((s) => s.selectedOriginPointId);
+const destination = useDirectionStore((s) => s.selectedDestinationPointId);
+const pathfindingError = useDirectionStore((s) => s.pathfindingError);
+const routingPreferences = useDirectionStore((s) => s.routingPreferences);
+```
+
+Show route error:
+
+```tsx
+{pathfindingError && <div>No Routes Available: {pathfindingError}</div>}
+```
+
+Enable get directions button:
+
+```tsx
+const canGenerateRoute = Boolean(origin && destination);
+```
+
+Update routing preference from host:
+
+```tsx
+useDirectionStore.getState().setRoutingPreferences({
+  elevator: true,
+  escalator: false,
+});
+```
+
+### `useDirectionsRouteRequestStore`
+
+Request state for `DirectionBridgeService.generateDirectionsRoute`.
+
+Fields:
+
+- `status`: `"idle" | "loading" | "success" | "error"`
+- `result`: `DirectionsRouteResult | null`
+- `error`: string or `null`
+- `isLoading`: boolean
+
+Example:
+
+```tsx
+const routeRequest = useDirectionsRouteRequestStore();
+
+if (routeRequest.isLoading) {
+  return <div>Generating route...</div>;
+}
+
+if (routeRequest.status === "error") {
+  return <div>{routeRequest.error}</div>;
+}
+```
+
+Navigate to step-by-step only when route succeeds:
+
+```tsx
+DirectionBridgeService.generateDirectionsRoute({
+  onSuccess: () => {
+    navigateToStepByStep();
+  },
+  onError: (result) => {
+    console.log(result.error);
+  },
+});
+```
+
+### `useFloorStore`
+
+Floor list and current floor.
+
+Fields:
+
+- `floors`: `FloorImage[]`
+- `activeFloor`: number or `null`
+
+Example:
+
+```tsx
+const floors = useFloorStore((s) => s.floors);
+const activeFloor = useFloorStore((s) => s.activeFloor);
+```
+
+### `useNavigationStore`
+
+Step-by-step navigation state.
+
+Fields:
+
+- `activePath`: `NodePoint[] | null`
+- `navigationResult`: `NavigationResult | null`
+- `simulationMode`: `"none" | "full" | "current"`
+- `currentStepIndex`: number
+
+Example:
+
+```tsx
+const navigationResult = useNavigationStore((s) => s.navigationResult);
+const currentStepIndex = useNavigationStore((s) => s.currentStepIndex);
+```
+
+Step data:
+
+```tsx
+navigationResult?.steps.map((step) => (
+  <div key={step.id}>
+    {step.instruction} - {step.distanceText}
+  </div>
+));
+```
+
+## Viewer Click Events
+
+Use `registerBridgeHandler` for viewer interaction events that should trigger host UI behavior.
+
+Currently supported handler:
+
+- `isShapeClick`: fires when a map shape/store is clicked in the viewer. Value is the clicked node id.
+
+Example:
+
+```tsx
+import { registerBridgeHandler } from "wovvmap-webview-bridge/web";
+
+useEffect(() => {
+  registerBridgeHandler("isShapeClick", (message) => {
+    console.log("Clicked node id", message.value);
+    openStoreDetail(message.value);
+  });
+}, []);
+```
+
+## Full Kiosk Host Example
+
+This example shows the main pieces together.
+
+```tsx
+import { useEffect, useRef } from "react";
+import {
+  WebIframeScreen,
+  DirectionBridgeService,
+  SelectionBridgeService,
+  ViewerBridgeService,
+  ZoomBridgeService,
+  useCategoryStore,
+  useDirectionStore,
+  useNodePointStore,
+  registerBridgeHandler,
+} from "wovvmap-webview-bridge/web";
+import { useDirectionInputStore } from "./useDirectionInputStore";
+
+export function KioskMap({ mapId }: { mapId: string | null }) {
+  const categories = useCategoryStore((s) => Object.values(s.categories));
+  const origin = useDirectionStore((s) => s.selectedOriginPointId);
+  const destination = useDirectionStore((s) => s.selectedDestinationPointId);
+  const configuredRef = useRef(false);
+
+  useEffect(() => {
+    if (configuredRef.current) return;
+    configuredRef.current = true;
+
+    DirectionBridgeService.configure({
+      directionInputAdapter: {
+        setDestinationState: (query, selectedId) =>
+          useDirectionInputStore.getState().setDestinationState(query, selectedId),
+        setOriginState: (query, selectedId) =>
+          useDirectionInputStore.getState().setOriginState(query, selectedId),
+        clearDestinationState: (clearQuery) =>
+          useDirectionInputStore.getState().clearDestinationState(clearQuery),
+        clearOriginState: () =>
+          useDirectionInputStore.getState().clearOriginState(),
+        setActiveDirectionField: (field) =>
+          useDirectionInputStore.getState().setActiveDirectionField(field),
+        getOriginQuery: () => useDirectionInputStore.getState().originQuery,
+        getDestinationQuery: () => useDirectionInputStore.getState().destinationQuery,
+      },
+      resolveLocationName: (nodeId) => {
+        const nodeKey = nodeId.split("<->")[0];
+        const node = useNodePointStore.getState().getNodePointByKey(nodeKey);
+        return node?.assets?.locationName?.text || nodeKey;
+      },
+      onClearSelection: () => SelectionBridgeService.clearSelection(),
+    });
+  }, []);
+
+  useEffect(() => {
+    registerBridgeHandler("isShapeClick", (message) => {
+      DirectionBridgeService.setDestination(message.value, true, false);
+    });
+  }, []);
+
+  if (!mapId) return null;
+
+  return (
+    <div>
+      <WebIframeScreen
+        url={`https://viewer.example.com/viewer/${mapId}?v=v2&template=embedded`}
+        origin="https://viewer.example.com"
+      />
+
+      <div>
+        {categories.map((category) => (
+          <button
+            key={category.code}
+            onClick={() => SelectionBridgeService.selectCategory(category)}
+          >
+            {category.name}
+          </button>
+        ))}
+      </div>
+
+      <button onClick={() => ViewerBridgeService.setViewMode("2D", true)}>
+        2D View
+      </button>
+      <button onClick={() => ViewerBridgeService.setViewMode("3D", true)}>
+        3D View
+      </button>
+      <button onClick={() => ZoomBridgeService.zoomOut()}>Zoom Out</button>
+      <button onClick={() => ZoomBridgeService.zoomIn()}>Zoom In</button>
+
+      <button
+        disabled={!origin || !destination}
+        onClick={() =>
+          DirectionBridgeService.generateDirectionsRoute({
+            onSuccess: () => console.log("route ready"),
+          })
+        }
+      >
+        Get Directions
+      </button>
+    </div>
+  );
+}
+```
+
+## Data Flow
+
+1. Host renders `WebIframeScreen` or `WebViewScreen`.
+2. Viewer initializes and sends grouped state events.
+3. Package handlers apply those events into Zustand stores.
+4. Host UI reads stores and renders categories, amenities, floors, offers, directions, and navigation.
+5. Host UI calls `*BridgeService` methods.
+6. Package sends typed bridge event to viewer.
+7. Viewer updates its internal state/scene and sends fresh grouped state back.
+
+## Incoming Viewer Events
+
+These are sent by the viewer to the host package and applied into stores automatically.
+
+| Key | Store updated | Value |
+| --- | --- | --- |
+| `bridgeState` | `useBridgeStorage.isMapLoaded` | `{ isMapLoaded: boolean }` |
+| `isConnection` | `useBridgeStorage.isBridgeLoaded` | `boolean` |
+| `tenantState` | `useBridgeStorage.imageBaseUrl` | `{ imageBaseUrl }` |
+| `viewerState` | `useViewerStore` | `ViewerBridgeState` |
+| `catalogState` | `useCategoryStore`, `useSubCategoryStore`, `useAmenityStore` | categories, subCategories, amenities |
+| `floorState` | `useFloorStore` | activeFloor, floors |
+| `nodePointState` | `useNodePointStore` | searchableNodePointMap, locationGroupedNodeMap, keyNodeMap, offersNodeMap |
+| `selectionState` | `useSelectionStore` | activeSelection, activeCategory, isOfferSelected |
+| `directionState` | `useDirectionStore` | selectedOriginPointId, selectedDestinationPointId, pathfindingError, routingPreferences |
+| `navigationState` | `useNavigationStore` | activePath, navigationResult, simulationMode, currentStepIndex |
+| `directionsRouteResult` | `useDirectionsRouteRequestStore` | status, navigationResult, error |
+| `isShapeClick` | event handler | clicked node id |
+
+## Outgoing Host Commands
+
+These are sent by command services to the viewer.
+
+| Service | Message key |
+| --- | --- |
+| `DirectionBridgeService.setDestination` | `setDestination` |
+| `DirectionBridgeService.clearDestination` | `clearDestination` |
+| `DirectionBridgeService.setOrigin` | `setOrigin` |
+| `DirectionBridgeService.clearOrigin` | `clearOrigin` |
+| `DirectionBridgeService.swapOriginDestination` | `swapOriginDestination` |
+| `DirectionBridgeService.generateDirectionsRoute` | `generateDirectionsRoute` |
+| `DirectionBridgeService.clearActivePath` | `clearActivePath` |
+| `SelectionBridgeService.selectCategory` | `setActiveSelection` |
+| `SelectionBridgeService.selectSubCategory` | `setActiveSelection` |
+| `SelectionBridgeService.selectAmenity` | `setActiveSelection` plus destination |
+| `SelectionBridgeService.toggleOffers` | `setOfferSelected` |
+| `SelectionBridgeService.clearSelection` | `clearActiveSelection` and `setOfferSelected(false)` |
+| `FloorBridgeService.changeFloor` | `changeFloor` |
+| `StepNavigationBridgeService.goToStep` | `goToStep` |
+| `StepNavigationBridgeService.nextStep` | `nextStep` |
+| `StepNavigationBridgeService.prevStep` | `prevStep` |
+| `StepNavigationBridgeService.finishStep` | `finishStep` |
+| `ZoomBridgeService.zoomIn` | `zoomIn` |
+| `ZoomBridgeService.zoomOut` | `zoomOut` |
+| `ViewerBridgeService.setViewMode` | `setViewMode` |
+| `ViewerBridgeService.setCameraView` | `setCameraView` |
+| `ViewerBridgeService.setTextType` | `setTextType` |
+| `ViewerBridgeService.setShow2DIcon` | `setShow2DIcon` |
+
+## Type Exports
+
+The package exports these core types:
+
+```ts
+type IncomingMessage;
+type OutgoingMessage;
+type NodePoint;
+type FloorImage;
+type Amenity;
+type Category;
+type SubCategory;
+type ViewerBridgeState;
+type ViewMode;
+type CameraView;
+type TextType;
+type NavigationBridgeState;
+type DirectionsRouteResult;
+type NavigationResult;
+type NavigationStep;
+type NavigationSummary;
+type SimulationMode;
+type DirectionBridgeServiceConfig;
+type DirectionInputAdapter;
+type ViewerConfig;
+```
+
+## Important Type Shapes
+
+### `Category`
+
+```ts
+type Category = {
+  code: string | number;
+  name: string;
+  image?: string;
+  subCategoryCodes: string[] | number[];
+  nodePointsKey?: string[];
+  nodePoints?: NodePoint[];
+};
+```
+
+### `SubCategory`
+
+```ts
+type SubCategory = {
+  code: string | number;
+  name: string;
+  image?: string;
+  description?: string;
+  categoryCode: string | number;
+  nodePointsKey?: string[];
+  nodePoints?: NodePoint[];
+};
+```
+
+### `Amenity`
+
+```ts
+type Amenity = {
+  id: string | number;
+  status: number;
+  fieldCode: string | number;
+  name: string;
+  image: string;
+  wayfinding_id?: string | number | null;
+  nodePointsKey?: string[];
+  nodePoints?: NodePoint[];
+};
+```
+
+### `NodePoint`
+
+Important fields:
+
+```ts
+type NodePoint = {
+  key: string;
+  floorIndex: number;
+  floorName: string;
+  assets: {
+    locationName: { text: string } | null;
+    pointImages: unknown | null;
+    logo: string | null;
+    brandLogo: string | null;
+    brandImages: string[];
+  };
+  categoryCode?: string | number;
+  subCategoryCode?: string | number;
+  offers: NodePointOffer[];
+  up: boolean;
+  down: boolean;
+};
+```
+
+### `DirectionsRouteResult`
+
+```ts
+type DirectionsRouteResult = {
+  status: "success" | "error";
+  navigationResult: NavigationResult | null;
+  error: string | null;
+};
+```
+
+### `NavigationStep`
+
+```ts
+type NavigationStep = {
+  id: string;
+  instruction: string;
+  action:
+    | "straight"
+    | "turn_left"
+    | "turn_right"
+    | "take_elevator"
+    | "take_escalator"
+    | "take_elevator_up"
+    | "take_elevator_down"
+    | "take_escalator_up"
+    | "take_escalator_down"
+    | "exit_elevator"
+    | "exit_escalator"
+    | "start"
+    | "arrive";
+  distanceText: string;
+  timeText: string;
+  floorIndex: number;
+};
+```
+
+## Common UI Recipes
+
+### Category Footer
+
+```tsx
+const categories = useCategoryStore((s) => Object.values(s.categories));
+const activeSelection = useSelectionStore((s) => s.activeSelection);
+
+return categories.map((category) => {
+  const active =
+    activeSelection.type === "Category" &&
+    activeSelection.id === category.code.toString();
+
+  return (
+    <button
+      key={category.code}
+      className={active ? "active" : ""}
+      onClick={() => SelectionBridgeService.selectCategory(category)}
+    >
+      {category.name}
+    </button>
+  );
+});
+```
+
+### Subcategory Footer
+
+```tsx
+const subCategories = useSubCategoryStore((s) => Object.values(s.subCategories));
+const activeCategory = useSelectionStore((s) => s.activeCategory);
+const activeSelection = useSelectionStore((s) => s.activeSelection);
+
+const visibleSubCategories = subCategories.filter((subCategory) =>
+  activeCategory?.subCategoryCodes.includes(subCategory.code)
+);
+
+return visibleSubCategories.map((subCategory) => {
+  const active =
+    activeSelection.type === "SubCategory" &&
+    activeSelection.id === subCategory.code.toString();
+
+  return (
+    <button
+      key={subCategory.code}
+      className={active ? "active" : ""}
+      onClick={() => SelectionBridgeService.selectSubCategory(subCategory)}
+    >
+      {subCategory.name}
+    </button>
+  );
+});
+```
+
+### Amenity List
+
+```tsx
+const amenities = useAmenityStore((s) => Object.values(s.amenities));
+const activeSelection = useSelectionStore((s) => s.activeSelection);
+
+return amenities.map((amenity) => {
+  const active =
+    activeSelection.type === "Amenity" &&
+    activeSelection.id === amenity.id.toString();
+
+  return (
+    <button
+      key={amenity.id}
+      className={active ? "active" : ""}
+      onClick={() => SelectionBridgeService.selectAmenity(amenity)}
+    >
+      {amenity.name}
+    </button>
+  );
+});
+```
+
+### Store Search Selection
+
+```tsx
+function selectStore(nodeKey: string, field: "from" | "to") {
+  const group = useNodePointStore.getState().locationGroupedNodeMap[nodeKey] || [nodeKey];
+  const joinedNodeIds = group.join("<->");
+
+  if (field === "from") {
+    DirectionBridgeService.setOrigin(joinedNodeIds, true, false);
+  } else {
+    DirectionBridgeService.setDestination(joinedNodeIds, true, false);
+  }
+}
+```
+
+### Default Location
+
+Default location should stay in the host app because only the host knows the map id and user preference.
+
+```tsx
+const defaultLocationKey = getDefaultLocationForMap(mapId);
+
+if (defaultLocationKey) {
+  DirectionBridgeService.setOrigin(defaultLocationKey, false, false);
+}
+```
+
+To show default location badge:
+
+```tsx
+const isDefaultLocation = selectedOriginPointId === defaultLocationKey;
+```
+
+### Get Directions Button
+
+```tsx
+const origin = useDirectionStore((s) => s.selectedOriginPointId);
+const destination = useDirectionStore((s) => s.selectedDestinationPointId);
+const isLoading = useDirectionsRouteRequestStore((s) => s.isLoading);
+
+return (
+  <button
+    disabled={!origin || !destination || isLoading}
+    onClick={() =>
+      DirectionBridgeService.generateDirectionsRoute({
+        onSuccess: () => navigateToStepByStep(),
+      })
+    }
+  >
+    {isLoading ? "Loading..." : "Get Directions"}
+  </button>
+);
+```
+
+### Pathfinding Error
+
+```tsx
+const pathfindingError = useDirectionStore((s) => s.pathfindingError);
+
+return pathfindingError ? (
+  <div>
+    <strong>No Routes Available</strong>
+    <span>{pathfindingError}</span>
+  </div>
+) : null;
+```
+
+### Step-by-Step Panel
+
+```tsx
+const navigationResult = useNavigationStore((s) => s.navigationResult);
+
+if (!navigationResult) return null;
+
+return (
+  <div>
+    <h3>Total Distance {navigationResult.summary.totalDistance}</h3>
+    <p>Arrive in {navigationResult.summary.totalApproxTime}</p>
+    {navigationResult.steps.map((step, index) => (
+      <button key={step.id} onClick={() => StepNavigationBridgeService.goToStep(index)}>
+        {step.instruction}
+      </button>
+    ))}
+  </div>
+);
+```
+
+## Image URLs
+
+Image base URL comes from tenant state:
+
+```tsx
+const imageBaseUrl = useBridgeStorage((s) => s.imageBaseUrl);
+```
+
+Category image:
+
+```tsx
+const src = category.image && imageBaseUrl ? `${imageBaseUrl}${category.image}` : "";
+```
+
+Amenity image:
+
+```tsx
+const src = amenity.image && imageBaseUrl ? `${imageBaseUrl}${amenity.image}` : "";
+```
+
+## What Should Stay In Host App
+
+Keep these in the host app:
+
+- `mapId`
+- default location per map id
+- local direction input query store if your UI has text inputs
+- host-specific flow history
+- custom UI layout
+- business-specific filtering that is not part of bridge protocol
+
+Use the package for:
+
+- iframe/WebView bridge setup
+- reading viewer-synced stores
+- sending viewer commands
+- route result lifecycle
+- selection/offers/floor/zoom/viewer controls
+
+## Troubleshooting
+
+### Stores are empty after refresh
+
+Check:
+
+- iframe/WebView URL is correct
+- viewer is using embedded template and initializes bridge after map parse
+- `useBridgeStorage((s) => s.isBridgeLoaded)` becomes `true`
+- `useBridgeStorage((s) => s.isMapLoaded)` becomes `true`
+- host is not rendering UI before `mapId` exists
+
+### Category or amenity images do not show
+
+Use `imageBaseUrl` from `useBridgeStorage`.
+
+Correct:
+
+```tsx
+const src = imageBaseUrl && item.image ? `${imageBaseUrl}${item.image}` : "";
+```
+
+Wrong:
+
+```tsx
+const src = imageBaseUrl || "" + item.image;
+```
+
+The wrong version returns only `imageBaseUrl` when it exists.
+
+### Direction input text is not updating
+
+Call `DirectionBridgeService.configure` and provide `directionInputAdapter`.
+
+Without adapter:
+
+- bridge command still works
+- viewer origin/destination still changes
+- local input text does not change automatically
+
+### Route success needs UI navigation
+
+Use `generateDirectionsRoute` callbacks or `useDirectionsRouteRequestStore`.
+
+```ts
+DirectionBridgeService.generateDirectionsRoute({
+  onSuccess: () => navigateToStepByStep(),
+  onError: (result) => showError(result.error),
+});
+```
+
+### Offers button active state
+
+Use:
+
+```tsx
+const isOfferSelected = useSelectionStore((s) => s.isOfferSelected);
+```
+
+Do not infer offer active state from category/subcategory.
+
+### Category active state
+
+Use:
+
+```tsx
+const activeSelection = useSelectionStore((s) => s.activeSelection);
+const isActive =
+  activeSelection.type === "Category" &&
+  activeSelection.id === category.code.toString();
+```
+
+### Subcategory unselect should keep category visible
+
+Keep `activeCategory` from `useSelectionStore`.
+
+```tsx
+const activeCategory = useSelectionStore((s) => s.activeCategory);
+```
+
+Use `activeCategory` to render subcategory list, not only `activeSelection`.
+
+### Text/view controls click but do not change
+
+Make sure your control overlay is above iframe/canvas layers.
+
+```tsx
+<div className="absolute z-[1000] pointer-events-auto">
+  ...
+</div>
+```
+
+### Do not duplicate bridge services in host app
+
+Do not recreate old local services like:
+
+- `TemplateDirectionService`
+- `TemplateSelectionService`
+- `TemplateFloorService`
+- `TemplateStepNavigationService`
+- `TemplateZoomService`
+- `TemplateViewerService`
+
+Use package exports instead:
+
+```ts
+import {
+  DirectionBridgeService,
+  SelectionBridgeService,
+  FloorBridgeService,
+  StepNavigationBridgeService,
+  ZoomBridgeService,
+  ViewerBridgeService,
+} from "wovvmap-webview-bridge/web";
+```
+
+## Export Checklist
+
+### Components
+
+- `WebIframeScreen`
+- `WebViewScreen`
+- `attachIframeBridge`
+
+### Services
+
+- `BridgeService`
+- `DirectionBridgeService`
+- `SelectionBridgeService`
+- `FloorBridgeService`
+- `StepNavigationBridgeService`
+- `ZoomBridgeService`
+- `ViewerBridgeService`
+
+### Stores
+
+- `useBridgeStorage`
+- `useViewerStore`
+- `useCategoryStore`
+- `useSubCategoryStore`
+- `useAmenityStore`
+- `useNodePointStore`
+- `useSelectionStore`
+- `useDirectionStore`
+- `useFloorStore`
+- `useNavigationStore`
+- `useDirectionsRouteRequestStore`
+
+### Handlers
+
+- `registerBridgeHandler`
+
+### Types
+
+- `IncomingMessage`
+- `OutgoingMessage`
+- `NodePoint`
+- `FloorImage`
+- `Amenity`
+- `Category`
+- `SubCategory`
+- `ViewerBridgeState`
+- `ViewMode`
+- `CameraView`
+- `TextType`
+- `NavigationBridgeState`
+- `DirectionsRouteResult`
+- `NavigationResult`
+- `NavigationStep`
+- `NavigationSummary`
+- `SimulationMode`
+- `DirectionBridgeServiceConfig`
+- `DirectionInputAdapter`
+- `ViewerConfig`