@minmaps-dev/mm-web-sdk 0.0.0-rc-20260623204551

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MTS LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+<div align="center">
+
+# MinuteMaps Web SDK
+
+**Render indoor venues — floors, POIs, amenities, destinations, and wayfinding routes — on top of [MapLibre GL JS](https://maplibre.org/).**
+
+[![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)
+
+</div>
+
+`@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
+```
+
+```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).
+
+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
+import { MinuteMaps } from '@minmaps-dev/mm-web-sdk'
+import 'maplibre-gl/dist/maplibre-gl.css'
+
+const sdk = new MinuteMaps({
+  container: 'map',                   // element or element id
+  jmap: {
+    host: '',                         // unused in proxy mode
+    customerId: 123,
+    venueId: 456,
+  },
+  jacs: {
+    mode: 'proxy',                    // recommended for browser apps
+    proxyBaseUrl: '/api/jacs',
+  },
+  options: {
+    customSprite: '/sprites/sprite',  // your icon sprite (no extension)
+    minIndoorZoom: 16,
+    debug: true,
+    styleMode: 'sdkTemplate',
+  },
+})
+
+sdk.on('ready', ({ venue }) => console.log('venue ready', venue?.name))
+sdk.on('floorChanged', ({ floor }) => console.log('now showing', floor?.name))
+
+await sdk.init()
+```
+
+## Quick start (React)
+
+```tsx
+import { MinuteMapsView } from '@minmaps-dev/mm-web-sdk/react'
+import 'maplibre-gl/dist/maplibre-gl.css'
+
+export function Map() {
+  return (
+    <MinuteMapsView
+      className="h-screen w-screen"
+      config={{
+        container: '',                // ignored — the component owns the element
+        jmap: { host: '', customerId: 123, venueId: 456 },
+        jacs: { mode: 'proxy', proxyBaseUrl: '/api/jacs' },
+        options: { styleMode: 'sdkTemplate' },
+      }}
+    />
+  )
+}
+```
+
+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 at a glance
+
+```ts
+type SDKConfig = {
+  container: HTMLElement | string
+  jmap: {
+    host: string
+    customerId: number
+    venueId: number
+    locale?: string
+    auth?: { clientId: string; clientSecret: string }
+  }
+  jacs: {
+    mode: 'proxy' | 'direct'
+    host?: string                                  // 'direct' only
+    auth?: { clientId: string; username: string; password: string } // 'direct' only
+    proxyBaseUrl?: string                          // default '/api/jacs'
+  }
+  options?: SDKOptions
+}
+```
+
+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. Your proxy should:
+
+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.
+
+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 — call JACS directly:
+
+```ts
+jacs: {
+  mode: 'direct',
+  host: 'https://jacs.example.com',
+  auth: { clientId, username, password },
+}
+```
+
+> ⚠ Never ship `direct` mode to a public browser bundle. Your JACS credentials would be visible to anyone with devtools.
+
+---
+
+## Sprites
+
+`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/`.
+
+---
+
+## Development
+
+Run commands from the **monorepo root** through pnpm/turbo (install pnpm via npm, not corepack):
+
+```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
+```
+
+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>`.
+
+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).
+
+### Continuous integration
+
+CI lives at the **monorepo root** in `.github/workflows/`:
+
+- **`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.
+
+> **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.
+
+---
+
+## Browser + framework support
+
+| Target | Version |
+| --- | --- |
+| Node (build/dev) | ≥ 18 |
+| `maplibre-gl` | ^4 |
+| `@turf/turf` | ^7 |
+| `react` / `react-dom` | ^18 or ^19 (only required for `/react` entry) |
+
+Modern evergreen browsers. Kiosk targets are typically pinned Chromium builds — if you need to support a specific minimum, open an issue.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).