becomap-v2 2.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 beCoMap
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# becomap-v2
+
+High-performance indoor mapping and navigation SDK — a MapLibre GL basemap paired with a single unified Three.js layer that renders all 3D (floor plates, walls, extruded units, labels, routes).
+
+> ⚠️ **ALPHA — `2.0.0-alpha.0`.** This is an early pre-release of the beCoMap v2 rewrite. The public API may change between alpha releases without a major version bump. Pin an exact version if you depend on it.
+> The stable v1 SDK is published separately on npm as [`becomap`](https://www.npmjs.com/package/becomap) — this package does **not** replace it yet.
+
+## Requirements
+
+- A browser with **WebGL2**: evergreen desktop and mobile browsers, plus Chromium-based kiosks.
+- **Node.js >= 20** if you are building from source or bundling the ESM entry point.
+
+## Install
+
+```bash
+npm install becomap-v2
+```
+
+`maplibre-gl` and `three` are **peer dependencies** and are not bundled. Install them explicitly:
+
+```bash
+npm install maplibre-gl@^4.4.1 three@^0.172.0
+```
+
+## Quick start (ESM / bundler)
+
+The map needs a container element with an explicit height — it will not size itself:
+
+```html
+<div id="map" style="width: 100%; height: 100vh"></div>
+```
+
+```ts
+import 'maplibre-gl/dist/maplibre-gl.css';
+import { createMap, RestVenueProvider } from 'becomap-v2';
+
+const map = createMap(document.getElementById('map')!, {
+  center: [77.1062539422262, 28.642350800253993],
+  zoom: 16.6,
+  pitch: 45,
+  venue: {
+    provider: new RestVenueProvider({
+      baseUrl: 'https://your-backend.example.com',
+      siteId: 'your-site-id',
+      clientId: 'your-client-id',
+      clientSecret: 'your-client-secret',
+    }),
+  },
+});
+
+map.on('load', async () => {
+  // Fetches + parses the venue (REST metadata + protobuf binaries).
+  const stats = await map.venue.load(); // { buildings, floors, locations, shapes }
+  console.log(stats);
+
+  const building = map.venue.current()?.buildings[0];
+  const ground = building?.floors[0];
+  if (ground) map.floors.select(ground.id);
+});
+
+map.on('error', (e) => console.error(e.message, e.cause));
+```
+
+## Script tag (UMD)
+
+The UMD bundle does **not** contain `maplibre-gl` or `three` — they are consumed as external globals, so both must be loaded **first** as `maplibregl` and `THREE`:
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.css" />
+<script src="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.js"></script>
+<script src="https://unpkg.com/three@0.172.0/build/three.min.js"></script>
+<script src="https://unpkg.com/becomap-v2@2.0.0-alpha.0/dist/becomap.umd.js"></script>
+
+<div id="map" style="width: 100%; height: 100vh"></div>
+
+<script>
+  // The bundle exposes the global `becomap`.
+  const map = becomap.createMap(document.getElementById('map'), {
+    center: [77.1062539422262, 28.642350800253993],
+    zoom: 16.6,
+    pitch: 45,
+    venue: {
+      provider: new becomap.RestVenueProvider({
+        baseUrl: 'https://your-backend.example.com',
+        siteId: 'your-site-id',
+        clientId: 'your-client-id',
+        clientSecret: 'your-client-secret',
+      }),
+    },
+  });
+
+  map.on('load', async () => {
+    await map.venue.load();
+  });
+</script>
+```
+
+## API surface
+
+Exported from the package root:
+
+- `createMap(container, options)` — the only factory; returns a `BecoMap` instance. No default export, no module-level state.
+- `RestVenueProvider` — loads a real venue from the beCoMap backend (REST metadata + protobuf binaries).
+- `MockVenueProvider` — a synthetic venue for trying the SDK, tests, and local development **with no backend or credentials**.
+- `Venue` / `buildVenue` — the parsed venue model and its builder, for custom data providers.
+- Types: `BecoMap`, `BecoMapOptions`, `VenueProvider`, `VenueData`, `VenueStats`, `Building`, `Floor`, `VenueLocation`, `Shape`, `Category`, `GraphNode`, `GraphEdge`, `RouteStep`, `NavStepInfo`, `PolygonThemeName`, and the facade interfaces.
+
+Reachable off the map instance:
+
+- `map.venue` — load the venue, read the current `Venue`.
+- `map.floors` — list floors, `select(floorId)`, read the active floor.
+- `map.search` — query locations and categories.
+- `map.routing` — compute and display routes, turn-by-turn steps.
+- `map.camera` — programmatic camera control (center, zoom, pitch, bearing, fit).
+- `map.on(event, handler)` / `map.off(event, handler)` — event API (`'load'`, `'error'`, and the rest of `BecoMapEvents`).
+
+## License
+
+[ISC](./LICENSE)