wovvmap-webview-bridge 1.0.29 → 1.1.0

package/README.md

@@ -1,289 +1,1707 @@
 # 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.
+The embedded viewer URL must use `template=embedded`. If the host app has its own URL state, keep the host template separate, for example `/websdk?template=kiosk`, and pass `template=embedded` only to the iframe/WebView URL.
 
 ```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
+<WebIframeScreen
+  url={`http://localhost:5174/viewer/${mapId}?v=v2&template=embedded`}
+  origin="http://localhost:5174"
+  style={{ width: "100%", height: "100%", border: "none" }}
+/>
+```
+
+## Recommended Ready Gate
+
+For kiosk demos and production embeds, keep the host chrome hidden until the embedded viewer has sent enough state to render the real mall UI. This avoids showing placeholder titles such as "Web SDK Demo" before the mall name arrives.
 
 ```tsx
-import React, { useEffect, useRef } from "react";
 import {
-  attachIframeBridge,
-  registerBridgeHandler,
-  sendStartPointToBridge,
+  WebIframeScreen,
+  useBridgeStorage,
+  useFloorStore,
+  useNodePointStore,
+  useViewerStore,
 } from "wovvmap-webview-bridge/web";
 
-export default function App() {
+export function KioskHost({ mapId }: { mapId: string }) {
+  const mallName = useViewerStore((s) => s.mallName);
+  const isMapParsed = useViewerStore((s) => s.isMapParsed);
+  const isLoading = useViewerStore((s) => s.isLoading);
+  const isBridgeLoaded = useBridgeStorage((s) => s.isBridgeLoaded);
+  const isMapLoaded = useBridgeStorage((s) => s.isMapLoaded);
+  const floorCount = useFloorStore((s) => s.floors.length);
+  const nodeCount = useNodePointStore((s) => s.searchableNodePointMap.length);
+
+  const isReady =
+    Boolean(mallName) &&
+    isBridgeLoaded &&
+    isMapLoaded &&
+    isMapParsed &&
+    !isLoading &&
+    floorCount > 0 &&
+    nodeCount > 0;
+
+  return (
+    <div className="host-shell">
+      {isReady && <Header title={`Welcome to ${mallName}`} />}
+
+      <WebIframeScreen
+        url={`https://viewer.example.com/viewer/${mapId}?v=v2&template=embedded`}
+        origin="https://viewer.example.com"
+      />
+
+      {isReady && <Footer />}
+      {!isReady && <LoadingOverlay />}
+    </div>
+  );
+}
+```
+
+## Demo Recording Mode
+
+The sample web host can expose a demo URL such as:
+
+```txt
+http://localhost:5173/websdk?demo=1&resetDefault=1
+```
+
+Recommended demo parameters:
+
+- `demo=1`: shows labeled walkthrough cards and runs a guided feature sequence.
+- `resetDefault=1`: clears the saved default location so the default-location selection flow can be demonstrated.
+- `mapId=<id>`: optionally chooses the mall map to open.
+- `template=kiosk`: host template for the SDK wrapper.
+
+The embedded viewer URL generated by the host must still use `template=embedded`; this parameter belongs only inside the iframe/WebView URL.
+
+Suggested video sequence:
+
+1. Web SDK channel URL and embedded viewer load.
+2. Mall-name header after real map data is ready.
+3. Default location selection.
+4. Search store results.
+5. Store detail card.
+6. Category and subcategory browsing.
+7. Amenities and offers.
+8. Origin/destination directions.
+9. `pathVisible=true` active route.
+10. Step-by-step guidance.
+11. Reverse directions / swap endpoints.
+12. Floor navigation.
+13. Zoom, 2D/3D, street/top view, and text controls.
+
+## 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 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:
 
-export default function App() {
-  return <WebViewScreen url="https://your-map-app-url.com" />;
+```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;
+
+  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,
-  sendEditableViewToBridge,
-  sendSensorDataToBridge,
-} 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" });
-sendEditableViewToBridge(mapDataExportObj);
-sendSensorDataToBridge({ timestamp: Date.now(), accelerometerSignal: {x: 0, y: 0, z: 0} });
+  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
-- sensorData: SensorDataPayload
-
-## 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
-- sendEditableViewToBridge
-- sendSensorDataToBridge
+```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:
+
+- `mallName`: mall name from the embedded viewer, or `null` before map data is ready
+- `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 mallName = useViewerStore((s) => s.mallName);
+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` | mallName, API version, view mode, camera/text settings, parsed/loading state |
+| `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`