@minmaps-dev/mm-web-sdk 1.0.0-rc.3 → 1.0.0-rc.30

package/README.md

@@ -1,31 +1,79 @@
+<div align="center">
+
 # MinuteMaps Web SDK
 
-`@minmaps-dev/mm-web-sdk` is the official MinuteMaps SDK for the web. It renders indoor venues — floors, POIs, amenities, destinations, and wayfinding routes — on top of [MapLibre GL JS](https://maplibre.org/), with data sourced from JACS.
+**Render indoor venues — floors, POIs, amenities, destinations, and wayfinding routes — on top of [MapLibre GL JS](https://maplibre.org/).**
 
-## Features
+[![npm](https://img.shields.io/npm/v/@minmaps-dev/mm-web-sdk?label=npm)](https://www.npmjs.com/package/@minmaps-dev/mm-web-sdk)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![types](https://img.shields.io/badge/types-included-blue)](./dist/index.d.ts)
 
-- **Venue + floors** — load a venue by `customerId` / `venueId`, switch active floor, and let the SDK manage layer visibility.
-- **POIs, amenities, destinations** — query the venue, filter by floor, and run keyword searches.
-- **Wayfinding** — compute kiosk-to-destination or waypoint-to-waypoint routes and render them on the map.
-- **View modes** — toggle 3D, flat (top-down), and 2D-units modes at runtime.
-- **Camera control** — `setView` / `resetView` / `getCameraPosition`, plus a live `cameraChange` event for compass UIs.
-- **React entrypoint** — drop-in `<MinuteMapsView />` for React 18/19 apps.
-- **JACS proxy or direct mode** — keep credentials server-side with the proxy mode, or call JACS directly from trusted environments.
+</div>
 
-## Installation
+`@minmaps-dev/mm-web-sdk` is the official MinuteMaps SDK for the web. It loads venues from JACS, manages floors, POIs, amenities, destinations, and the camera, and gives you a small, well-typed surface for building modern kiosks and indoor mapping web apps.
 
 ```bash
 npm install @minmaps-dev/mm-web-sdk maplibre-gl @turf/turf
 ```
 
-`maplibre-gl` (v4) and `@turf/turf` (v7) are peer dependencies. `react` / `react-dom` (v18 or v19) are optional peers, only required if you use the `/react` entrypoint.
-
-Don't forget to import the MapLibre stylesheet once in your app:
-
 ```ts
+import { MinuteMaps } from '@minmaps-dev/mm-web-sdk'
 import 'maplibre-gl/dist/maplibre-gl.css'
+
+const sdk = new MinuteMaps({
+  container: 'map',
+  jmap: { host: '', customerId: 123, venueId: 456 },
+  jacs: { mode: 'proxy', proxyBaseUrl: '/api/jacs' },
+  options: { styleMode: 'sdkTemplate' },
+})
+
+sdk.on('ready', ({ venue }) => console.log('venue ready', venue?.name))
+await sdk.init()
 ```
 
+---
+
+## Status
+
+This SDK is on a pre-1.0 release candidate (`1.0.0-rc.24`). A few capabilities remain **dormant pending backend support** — they are not yet functional in the published build:
+
+| Area | Status | Notes |
+| --- | --- | --- |
+| Floors, POIs, amenities, destinations | ✅ Shipped | Loads via JACS `building/full` + `venue/full`. |
+| Camera + view modes (3D/2D/flat) | ✅ Shipped | Style toggles work against the bundled `alt3-hybrid-style.json`. |
+| Wayfinding | ✅ Shipped | Built-in JACS path-graph routing (rc.18). `JacsWayfindingProvider` is wired by default; route computation runs inside the SDK (`src/data/wayfinding/`). No provider injection needed. |
+| Contextual map APIs | ✅ Shipped | `highlightPOI`/`highlightAmenity`/`clearHighlight`, `setPOIFilter`/`clearPOIFilter`, `amenities.getDistinct`, `findClosestWaypoint`, `searchAllPOIs`, `navigateFromKioskToPOI`, `refit`. See `docs/API.md#contextual-map`. |
+| Venue-served stylesheets | 🚧 Roadmap | SDK currently uses its bundled style; `loadAndPatchVenueStyle()` is bypassed. |
+| Polygon layers + 3D map templates | 🚧 Roadmap | `buildPolygonLayers` / `applyMapTemplate3d` imports are commented in `src/sdk.ts`. |
+
+Track re-enable points by grepping `// TODO: Re-enable` in `src/sdk.ts` and `src/data/jacsDataProvider.ts`.
+
+---
+
+## What's in the box
+
+- **Venue + floors** — load a venue by `customerId` / `venueId`, switch active floor, let the SDK manage layer visibility.
+- **POIs, amenities, destinations** — query by floor, run keyword searches, find the kiosk's "You are here" location.
+- **View modes** — toggle 3D extrusion, flat (top-down), and 2D-units modes at runtime.
+- **Camera control** — `setView` / `resetView` / `getCameraPosition`, plus a live `cameraChange` event for compass UIs.
+- **React entrypoint** — drop-in `<MinuteMapsView />` for React 18/19.
+- **JACS proxy or direct mode** — keep credentials server-side (recommended) or call JACS directly from trusted environments.
+
+---
+
+## Documentation
+
+The lean root README intentionally stops here. For depth, see:
+
+- [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) — module map, init flow, JACS data path, style patching, dormant 3D notes.
+- [`docs/API.md`](./docs/API.md) — full public API surface grouped by lifecycle, floors, POIs, amenities, wayfinding, camera, events.
+- [`docs/KIOSK.md`](./docs/KIOSK.md) — kiosk integration patterns (You-Are-Here, kiosk-to-destination wayfinding once enabled, view-mode UX, sprite hosting, idle reset).
+- [`docs/ICONS.md`](./docs/ICONS.md) — the curated icon registry, how amenity/connector/destination icons resolve and render, the CMS upload flow, and the release coupling between the icon-set and SDK packages.
+
+External integrators will usually only need the [API](./docs/API.md) and [Kiosk](./docs/KIOSK.md) docs. Internal MTS engineers should also read [Architecture](./docs/ARCHITECTURE.md) before touching `src/sdk.ts` or the JACS provider.
+
+---
+
 ## Quick start (vanilla)
 
 ```ts
@@ -51,9 +99,8 @@ const sdk = new MinuteMaps({
   },
 })
 
-sdk.on('ready', ({ venue }) => {
-  console.log('venue ready', venue?.name)
-})
+sdk.on('ready', ({ venue }) => console.log('venue ready', venue?.name))
+sdk.on('floorChanged', ({ floor }) => console.log('now showing', floor?.name))
 
 await sdk.init()
 ```
@@ -79,9 +126,11 @@ export function Map() {
 }
 ```
 
-For a more involved integration that wires events, floors, search, and wayfinding into React state, see the [`mm-web-sdk-example`](../mm-web-sdk-example) Next.js app — particularly [`hooks/useMap.ts`](../mm-web-sdk-example/hooks/useMap.ts).
+The React entry is intentionally minimal: it owns its own `<div>`, calls `init()` on mount, and `destroy()` on unmount. Reach for the vanilla `MinuteMaps` class when you need imperative control (floor switching from a side panel, camera animations driven by Redux, etc.).
+
+---
 
-## Configuration
+## Configuration at a glance
 
 ```ts
 type SDKConfig = {
@@ -95,37 +144,29 @@ type SDKConfig = {
   }
   jacs: {
     mode: 'proxy' | 'direct'
-    host?: string                                 // 'direct' only
+    host?: string                                  // 'direct' only
     auth?: { clientId: string; username: string; password: string } // 'direct' only
     proxyBaseUrl?: string                          // default '/api/jacs'
   }
   options?: SDKOptions
 }
-
-type SDKOptions = {
-  debug?: boolean
-  initialFloor?: string | number
-  customSprite?: string                            // sprite URL prefix (no extension)
-  minIndoorZoom?: number
-  boundsPadding?: number                           // default 50
-  styleMode?: 'venueStyleUrl' | 'sdkTemplate'
-  templateOverrideMode?: 'colorsOnly' | 'colorsAndConstants' | 'all'
-}
 ```
 
+Full option reference and an annotated `SDKOptions` shape live in [`docs/API.md`](./docs/API.md#configuration).
+
 ### JACS proxy mode (recommended)
 
-Browser apps should use `mode: 'proxy'` and forward requests through your own server so JACS credentials never reach the client. The example app ships a Next.js route handler at [`app/api/jacs/[...path]/route.ts`](../mm-web-sdk-example/app/api/jacs/%5B...path%5D/route.ts) that:
+Browser apps should use `mode: 'proxy'` and forward requests through your own server so JACS credentials never reach the client. Your proxy should:
 
-1. Reads `JACS_HOST`, `JACS_CLIENT_ID`, `JACS_USERNAME`, `JACS_PASSWORD` from server env.
-2. Exchanges the password grant for a bearer token (cached until expiry).
-3. Forwards `GET /api/jacs/<path>` to `${JACS_HOST}/JACS/api/<path>` with the token attached.
+1. Read `JACS_HOST`, `JACS_CLIENT_ID`, `JACS_USERNAME`, `JACS_PASSWORD` from server env.
+2. Exchange the password grant for a bearer token (cache until expiry).
+3. Forward `GET /api/jacs/<path>` to `${JACS_HOST}/JACS/api/<path>` with the token attached.
 
-Copy that handler into your own backend (or adapt it to your framework) and point `jacs.proxyBaseUrl` at it.
+A reference Next.js route handler ships in the example app at `apps/example/app/api/jacs/[...path]/route.ts`. Copy it into your own backend or adapt it to your framework, then point `jacs.proxyBaseUrl` at it.
 
 ### JACS direct mode
 
-For trusted environments (server-rendered pages, Electron kiosks, internal tools) you can call JACS directly:
+For trusted environments — server-rendered pages, Electron kiosks, internal tools — call JACS directly:
 
 ```ts
 jacs: {
@@ -135,104 +176,56 @@ jacs: {
 }
 ```
 
-## API
-
-### Class `MinuteMaps`
-
-```ts
-new MinuteMaps(config: SDKConfig)
-sdk.init(): Promise<void>
-sdk.destroy(): void
-sdk.isReady(): boolean
-sdk.getMap(): maplibregl.Map | null
-```
-
-`createMinuteMapsSDK(config)` is a factory shorthand for `new MinuteMaps(config)`.
+> ⚠ Never ship `direct` mode to a public browser bundle. Your JACS credentials would be visible to anyone with devtools.
 
-### Floors
+---
 
-```ts
-sdk.getFloors(): Floor[]
-sdk.getCurrentFloor(): Floor | null
-sdk.getDefaultFloor(): Floor | null
-sdk.setCurrentFloor(floor: Floor): Promise<void>
-```
+## Sprites
 
-### POIs, destinations, search
+`options.customSprite` is a sprite URL **prefix without extension** — MapLibre appends `.json` and `.png` (and `@2x` variants) automatically. The example app serves its sprite from `apps/example/public/sprites/`.
 
-```ts
-sdk.getAllPOIs(floor?: Floor): POI[]
-sdk.getDestinations(floor?: Floor): Destination[]
-sdk.searchPOIs(query: string, floor?: Floor): POI[]
-sdk.getYouAreHerePOI(floor?: Floor): POI | null
-sdk.getYouAreHereCoordinates(floor?: Floor): [number, number] | null
-```
-
-### Amenities (`sdk.amenities`)
+---
 
-```ts
-sdk.amenities.getAll(): AmenityWithFloor[]
-sdk.amenities.getByFloorId(floorId): AmenityWithFloor[]
-sdk.amenities.getAllKiosks(): AmenityWithFloor[]
-sdk.amenities.getKioskForFloor(floorId): AmenityWithFloor | null
-```
+## Development
 
-### Wayfinding
+Run commands from the **monorepo root** through pnpm/turbo (install pnpm via npm, not corepack):
 
-```ts
-sdk.navigateFromKioskToDestination(destination): Promise<...>
-sdk.wayfindBetweenWaypoints(from, to, opts?: {
-  centerMode?: 'none' | 'destination' | 'route'
-  zoom?: number
-}): Promise<...>
-sdk.clearRoute(): void
+```bash
+pnpm install           # once, at the root — one lockfile for the whole monorepo
+pnpm dev               # turbo: SDK rollup --watch + example next dev together
+pnpm build             # turbo: production build of all packages
+pnpm typecheck         # turbo: tsc --noEmit
+pnpm test              # turbo: vitest run
 ```
 
-### Camera + view modes
-
-```ts
-sdk.setView({ center?, zoom?, pitch?, bearing?, animate?, duration? })
-sdk.resetView({ animate?, duration? })
-sdk.getCameraPosition(): CameraState | null
-
-sdk.set3dEnabled(enabled) / toggle3d() / getIs3dEnabled()
-sdk.setUnits2dEnabled(enabled) / toggleUnits2d() / getIsUnits2dEnabled()
-sdk.setFlatMode(enabled) / toggleFlatMode() / getIsFlatMode()
-```
+SDK-only build: `pnpm --filter @minmaps-dev/mm-web-sdk build`. Per-package scripts (`dev:sdk`, `test:watch`, `test:coverage`) still exist and can be run with `pnpm --filter @minmaps-dev/mm-web-sdk <script>`.
 
-### MapLibre passthroughs
+The build emits ESM, CJS, and types under `dist/` for both the root entry and the `/react` entry. Tests live in `tests/` and target the three highest-leverage modules: `JacsProvider`, `WayfindingManager`, and `ViewModeController`. Coverage thresholds are gated in `vitest.config.ts` (currently 60% lines/funcs/stmts, 50% branches).
 
-```ts
-sdk.addControl(control, position?)   // forwards to the underlying MapLibre map
-sdk.getMap()                         // escape hatch: the raw maplibregl.Map
-```
+### Continuous integration
 
-### Events
+CI lives at the **monorepo root** in `.github/workflows/`:
 
-Subscribe with `sdk.on(event, cb)` / unsubscribe with `sdk.off(event, cb)`.
+- **`ci.yml`** — runs typecheck, vitest with coverage, and the production build on every push and pull request to `main` / `dev`.
+- **`release.yml`** — Changesets-driven releases. Write a changeset, merge to `main`, and a "Version Packages" PR is opened; merging it runs `changeset publish` to npm (access `public`). There is no tag-based publish workflow and no provenance flag.
+- **`deploy-example.yml`** — deploys the example app.
 
-| Event           | Payload                       | When                                                       |
-| --------------- | ----------------------------- | ---------------------------------------------------------- |
-| `ready`         | `{ venue }`                   | Map loaded and the initial floor is rendered.              |
-| `floorsLoaded`  | `{}`                          | All floor geojson is available.                            |
-| `floorChanged`  | `{ floor }`                   | After `setCurrentFloor` resolves.                          |
-| `cameraChange`  | `{ camera: CameraState }`     | On every map `move` (drives compass/heading UI).           |
-| `error`         | `{ error }`                   | Init or runtime error.                                     |
+> **Internal note:** future Claude sessions get oriented from [`CLAUDE.md`](./CLAUDE.md). Subagents at the monorepo-root `.claude/agents/` cover API doc sync, release notes, and style/template edits.
 
-## Sprites
+---
 
-Pass `options.customSprite` as a sprite URL prefix without the extension (MapLibre will append `.json` and `.png` / `@2x`). The example app serves its sprite from [`public/sprites/`](../mm-web-sdk-example/public/sprites/).
+## Browser + framework support
 
-## Development
+| Target | Version |
+| --- | --- |
+| Node (build/dev) | ≥ 18 |
+| `maplibre-gl` | ^4 |
+| `@turf/turf` | ^7 |
+| `react` / `react-dom` | ^18 or ^19 (only required for `/react` entry) |
 
-```bash
-npm install
-npm run dev:sdk    # rollup --watch
-npm run build      # clean + production build
-npm run typecheck  # tsc --noEmit
-```
+Modern evergreen browsers. Kiosk targets are typically pinned Chromium builds — if you need to support a specific minimum, open an issue.
 
-The build emits ESM, CJS, and types under `dist/` for both the root entry and the `/react` entry.
+---
 
 ## License