@mapmap/maps 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+MapMap Maps SDK (@mapmap/maps)
+
+Copyright (c) 2026 Precode Ltd. All rights reserved.
+
+This package is proprietary first-party software of Precode Ltd, distributed
+under a commercial licence. It is part of the MapMap
+product. Use of this package requires a written commercial agreement with
+Precode Ltd and a valid MapMap gateway API key; it is licensed per fleet
+vehicle or per monthly-active-user (see docs/SDK-DISTRIBUTION.md). No licence,
+express or implied, is granted except under that agreement.
+
+This SDK is a thin wrapper over third-party open-source components, used under
+their own permissive licences and not relicensed by this file:
+
+  - MapLibre GL JS (BSD-2-Clause) - the map renderer, a peer dependency.
+  - pmtiles (BSD-3-Clause) - the PMTiles protocol handler, a peer dependency.
+
+Map data rendered through this SDK is derived from OpenStreetMap and is
+subject to the Open Database License (ODbL) 1.0. The "© OpenStreetMap
+contributors" attribution is legally required and must not be removed from
+maps produced with this SDK.
+
+See the repository root LICENSE, THIRD-PARTY-NOTICES.md and docs/LINEAGE.md.

package/README.md

@@ -0,0 +1,411 @@
+# @mapmap/maps - MapMap Maps SDK
+
+A thin, well-typed TypeScript wrapper over [MapLibre GL JS](https://maplibre.org/)
+that drops a **MapMap-branded map** (signed territory PMTiles) plus
+**OSRM-compatible truck / ADR routing** into any web app - the way developers
+use Mapbox GL, but on MapMap's own tiles and routing gateway.
+
+The SDK does **not** reimplement MapLibre. MapLibre does all the rendering;
+this package wires in the MapMap default style, registers the `pmtiles`
+protocol, and gives you typed helpers for routing and ADR tunnel compliance
+against the MapMap gateway.
+
+## Install
+
+```sh
+npm install @mapmap/maps maplibre-gl pmtiles
+```
+
+`maplibre-gl` and `pmtiles` are **peer dependencies** - your app owns a single
+shared copy (two MapLibre instances on one page break the WebGL context).
+
+You also need a MapMap gateway API key (`snk_…`). See
+[`docs/SDK-DISTRIBUTION.md`](../docs/SDK-DISTRIBUTION.md) for licensing.
+
+## Quickstart
+
+```ts
+import { MapMapMap, RouteLayer } from "@mapmap/maps";
+import "maplibre-gl/dist/maplibre-gl.css";
+
+const map = new MapMapMap({
+  container: "map",
+  apiKey: "snk_…",
+  style: "light", // "light" | "dark" | a StyleSpecification | a style URL
+  center: [-1.5, 52.6],
+  zoom: 6,
+});
+
+await map.whenReady();
+
+const routes = new RouteLayer(map);
+const route = await routes.route(
+  { lng: -0.1278, lat: 51.5074 }, // London
+  { lng: -1.5106, lat: 52.4081 }, // Birmingham
+  {
+    profile: "truck",
+    truck: { heightM: 4.0, weightT: 40, hazmat: true, tunnelCode: "C" },
+  },
+);
+
+console.log(route.distanceM, route.durationS); // metres, seconds
+```
+
+The route line is drawn automatically in MapMap signal blue (`#3a86ff`)
+with a darker casing. Call `routes.clear()` to remove it, or
+`routes.route(...)` again to replace it.
+
+## API surface
+
+### `class MapMapMap` (alias: `createMap(options)`)
+
+Wraps `maplibregl.Map`.
+
+```ts
+new MapMapMap({
+  container,            // string id or HTMLElement (required)
+  apiKey?,             // gateway key, reused by RouteLayer/AdrCheck
+  baseUrl?,            // gateway origin, default https://api.mapmap.ai
+  style?,              // "light" | "dark" | Theme | StyleSpecification | URL
+  territoryTilesUrl?,  // override the PMTiles URL in the default styles
+  center?, zoom?,      // initial view ([lng, lat], number)
+  mapOptions?,         // extra native MapLibre MapOptions (escape hatch)
+});
+```
+
+- `.map` - the underlying `maplibregl.Map`; use it for any native call.
+- `.whenReady()` - resolves after the style and first tiles load.
+- `.destroy()` - removes the map and frees the WebGL context.
+- `.apiKey`, `.baseUrl` - read back for your own gateway calls.
+- `.navDesign` - the parsed Studio `extra.nav` block when the `style` theme
+  carried one (see "Using your Studio design").
+
+### `class RouteLayer`
+
+```ts
+const routes = new RouteLayer(map /* MapMapMap or maplibregl.Map */, {
+  baseUrl?, apiKey?, id?, design?, // design: extra.nav route block
+});
+
+await routes.route(from, to, { profile, truck });      // two-point
+await routes.routePath([a, b, c], { profile, truck }); // multi-point
+routes.current;  // last ParsedRoute
+routes.clear();  // remove the drawn line
+```
+
+Coordinates accept `[lng, lat]`, `{ lng, lat }` or `{ lon, lat }`. A route
+resolves to `{ distanceM, durationS, geometry (GeoJSON LineString), raw }`.
+
+`truck` params map onto the gateway's OSRM truck vendor extensions:
+`heightM`, `widthM`, `lengthM`, `weightT`, `hazmat`, and `tunnelCode` (ADR
+8.6.4, e.g. `"C"` or `"B/D"` - the slash is URL-encoded for you). They only
+take effect with `profile: "truck"`.
+
+### `class PositionPuck`
+
+The current-position marker: a coloured dot with a heading arrow, or a
+custom image, styled by a Studio design (see "Using your Studio design").
+
+```ts
+const puck = new PositionPuck(map /* MapMapMap or maplibregl.Map */, design?);
+puck.setLocation({ lat, lon }, headingDeg?); // adds it on first call
+puck.remove();
+```
+
+### `class PlacesLayer` - places / store finder
+
+Drop your own places (e.g. 300 store locations) onto the map: clustered
+pins, popups, and "nearest branch" answers by straight line or by drive
+time (via the gateway's `POST /matrix`).
+
+```ts
+import { PlacesLayer } from "@mapmap/maps";
+
+const stores = new PlacesLayer(map /* MapMapMap or maplibregl.Map */, {
+  places: [
+    { id: "bhm-01", name: "Birmingham", lat: 52.4862, lon: -1.8904 },
+    { id: "man-01", name: "Manchester", lat: 53.4808, lon: -2.2426 },
+    // …or a plain GeoJSON FeatureCollection of Points
+  ],
+  cluster: true,                      // default; clusterRadius?, clusterMaxZoom?
+  color: "#ff6b35",                   // pin + cluster colour (default signal blue)
+  fitBounds: true,                    // fit the view to the places on first set
+  popup: (place) => `<strong>${place.name}</strong>`,
+  onPlaceClick: (place, lngLat) => console.log(place.id, lngLat),
+});
+
+stores.setPlaces(nextPlaces);                    // replace data in place
+stores.nearest({ lat: 51.5, lon: -0.13 }, 3);    // haversine, adds distanceM
+await stores.nearestByDriveTime({ lat: 51.5, lon: -0.13 }, { n: 3, costing: "truck" });
+stores.clear();   // remove pins;  stores.destroy() also detaches listeners
+```
+
+Clicking a cluster zooms in to expand it; the cursor becomes a pointer over
+pins. Pass `icon: { url, size? }` for a custom pin image (falls back to the
+circle pin if it fails to load). `nearestByDriveTime` sorts by `durationS`
+(seconds, driven `distanceM` attached, unreachable places dropped) and reuses
+the map's `baseUrl`/`apiKey` - or pass them as layer options.
+
+### `class NavigationCamera`
+
+The turnkey chase cam: follows each GPS fix course-up, tilted, with the
+puck anchored low-centre (see "Navigation camera" below).
+
+```ts
+const camera = new NavigationCamera(map /* MapMapMap or maplibregl.Map */, {
+  pitch?,          // tilt in degrees, default 60, clamped 0-85
+  zoom?,           // follow zoom, default 17
+  anchorY?,        // puck's vertical screen position 0-1, default 0.72
+  easeMs?,         // ease per fix, default 900 (capped by the fix interval)
+  autoRecentreMs?, // idle time before auto-recentre, default 6000; 0 = never
+});
+// pitch/zoom precedence: option > Studio design (extra.nav.camera, when the
+// map is a MapMapMap built from a theme carrying one) > built-in default.
+
+camera.follow({ lat, lon }, courseDeg?); // glide to a fix, course-up
+camera.attachPuck(puck);                 // follow() then co-drives the puck
+camera.overview(route.geometry);         // whole route, top-down
+camera.resume();                         // back to the chase cam
+camera.mode;                             // "follow" | "overview" | "free"
+camera.destroy();                        // remove listeners
+NavigationCamera.isSupported(map);       // false under globe projection
+```
+
+### `class AdrCheck`
+
+Direct access to the gateway's `POST /adr/check` tunnel compliance engine:
+
+```ts
+import { AdrCheck } from "@mapmap/maps";
+
+const adr = new AdrCheck({ baseUrl: "https://api.mapmap.ai", apiKey: "snk_…" });
+const decision = await adr.check({ hazmat: true, tunnelCode: "C", tunnelCategory: "D" });
+// { status: "allowed" | "blocked", reason?, raw }
+```
+
+### Pure helpers (no browser required)
+
+Exported for server-side or test use - none of these touch MapLibre:
+
+- `buildStyle({ theme, territoryTilesUrl })` → a MapLibre `StyleSpecification`.
+- `buildRouteUrl(baseUrl, profile, points, truck?)` / `buildRouteQuery(truck?)`.
+- `parseOsrmRoute(body)` → `ParsedRoute`.
+- `toLngLat` / `formatCoord` / `formatCoords` - coordinate normalisation.
+- `haversineDistanceM(a, b)` - straight-line distance in metres.
+- `placesFromGeoJSON(collection)` - GeoJSON Points → `Place[]`.
+- `registerPmtilesProtocol(gl?)` - install the `pmtiles://` handler yourself.
+- `OSM_ATTRIBUTION`, `FULL_ATTRIBUTION`, `DEFAULT_TERRITORY_TILES_URL`,
+  `PALETTE_SLOTS`, `SOURCE_LAYERS`, `SIGNAL_BLUE`.
+
+### Themes (MapMap Studio)
+
+`buildStyle` (and `MapMapMap`'s `style` option) accepts `"light"`, `"dark"`,
+or a **MapMap Studio `Theme`** document - the same theme JSON the `sn-style`
+crate compiles server-side, so styles render identically in the browser and
+in signed territory packages:
+
+```ts
+const map = new MapMapMap({
+  container: "map",
+  style: {
+    name: "midnight-fleet",
+    base: "dark",
+    palette: { water: "#0b2038", roadMajor: "#8a6d3b" },
+    layers: {
+      building: { visible: false },
+      "road-minor": { paint: { "line-width": 2 }, minzoom: 10 },
+    },
+  },
+});
+```
+
+- **Palette slots** (17): `background water waterway landcover landuse park
+  building aeroway road roadMajor path rail boundary boundaryMinor
+  textPrimary textSecondary textHalo`.
+- **`extra.nav`** (Studio's navigation design block) is carried by the theme
+  file and ignored by style compilation - see "Using your Studio design"
+  below.
+- **Layer ids** (paint order): `background landcover landuse park water
+  waterway aeroway building rail road-path road-minor road-major
+  boundary-minor boundary housenumber road-labels water-name poi-labels
+  mountain-peak-labels aerodrome-labels place-labels`.
+- Per-layer overrides: `visible`, `paint`/`layout` (per-key merge), `filter`
+  (replace), `minzoom`/`maxzoom`. `extra_layers` (full MapLibre layers over
+  the `territory` source) are inserted above the base map, below labels.
+- Unknown slots/layer ids throw with the accepted values listed.
+- See `docs/STUDIO.md` for the full theme document reference.
+
+### Using your Studio design
+
+Studio's Navigation panel designs the turn-by-turn look - route line,
+current-position puck and banner instruction - and stores it under
+`extra.nav` in the theme JSON you download or copy. The block also survives
+hosted publishing: Studio's publish sends it with the theme, and the gateway
+serves it back from `GET /styles/{id}/theme`. Pass a theme file to
+`createMap` and the whole navigation UI styles itself:
+
+```ts
+import { createMap, RouteLayer, GuidanceBanner, PositionPuck } from "@mapmap/maps";
+import theme from "./midnight-fleet.theme.json"; // downloaded from Studio
+
+const map = createMap({ container: "map", apiKey: "snk_…", style: theme });
+await map.whenReady();
+
+// Route line: colour, width, opacity and casing from extra.nav.route.
+const routes = new RouteLayer(map);
+await routes.route({ lng: -0.1278, lat: 51.5074 }, { lng: -1.5106, lat: 52.4081 });
+
+// Banner: colours, font size, padding, radius, max width, height and the
+// lane row from extra.nav.banner.
+const banner = new GuidanceBanner(document.body, map.navDesign?.banner);
+
+// Puck: dot + heading arrow (or your custom image) from extra.nav.puck.
+const puck = new PositionPuck(map);
+puck.setLocation({ lat: 51.5074, lon: -0.1278 }, 45); // heading in degrees
+```
+
+- `map.navDesign` is the parsed `extra.nav` block (`undefined` when the
+  theme has none); `navDesignFromTheme(theme)` / `parseNavDesign(value)` are
+  exported for standalone use, and `defaultNavDesign()` matches the SDK's
+  built-in look.
+- `RouteLayer` and `PositionPuck` pick the design up from a `MapMapMap`
+  automatically; pass `{ design }` / a second argument to override. Without
+  a design everything renders exactly as before.
+- `extra.nav.camera` (optional since v1, whole block and each field) holds
+  the drive-camera tokens: `pitch` (degrees, 0-85, default 60), `zoom`
+  (14-20, default 17.5) and `speedMps` (drive speed in m/s, 2-40, default
+  12 - used by Studio's demo drive and route simulators; a camera following
+  real GPS fixes ignores it). `NavigationCamera` reads the block's
+  pitch/zoom as its option defaults when built from a `MapMapMap`; explicit
+  options still win (option > design > built-in). Themes saved without the
+  block load unchanged and stay `"version": 1`.
+- The nav block travels with the **theme document**, never the compiled
+  style: `extra` round-trips through `POST /styles` and
+  `GET /styles/{id}/theme` (bounded at 256 KB serialised), but a compiled
+  `style.json` URL alone never carries it. For a hosted style, fetch the
+  design from the theme endpoint (public, uncached):
+
+  ```ts
+  import { navDesignFromThemeUrl } from "@mapmap/maps";
+
+  const design = await navDesignFromThemeUrl(
+    "https://api.mapmap.ai/styles/midnight-fleet-a1b2c3/theme",
+  );
+  const banner = new GuidanceBanner(document.body, design?.banner);
+  const routes = new RouteLayer(map, { design: design?.route });
+  ```
+
+  `navDesignFromThemeUrl(url, fetchImpl?)` returns `undefined` when the
+  theme has no nav block and throws on HTTP/network failure; pass your own
+  `fetch` for tests or polyfills.
+- Parsing is lenient and clamped (widths 0.5-20, opacity 0-1, banner height
+  40-120 or unset for auto, puck images `https:`/`data:` only, data
+  payloads capped at 64 KB) - a malformed block falls back per-field to the
+  defaults rather than failing.
+
+## The MapMap mark
+
+Maps render a small MapMap wordmark bottom-right (the same convention as
+Google Maps and Mapbox). It links to mapmap.ai, needs no network fetch,
+and is on by default: pass `logo: false` to `createMap` to remove it, or
+`logo: { position, href }` to customise. Attribution is separate and not
+removable.
+
+## Turn-by-turn guidance
+
+```ts
+import { GuidanceBanner, extractGuidance, speak } from "@mapmap/maps";
+
+const route = await routes.route(from, to, {
+  costing: "truck",
+  voice: true,
+  banner: true,
+  language: "en-GB",
+});
+
+const steps = extractGuidance(route);
+const banner = new GuidanceBanner(document.body, map.navDesign?.banner);
+banner.update(steps[0].banners[0] ?? null);
+// As the driver advances, fire each voice prompt once when its
+// distanceAlongGeometry trigger is crossed:
+speak(steps[0].voice[0]);
+```
+
+Voice prompts arrive plain and as SSML; banners carry the maneuver glyph
+and, where OSM has `turn:lanes` data, a lane diagram (sprite icons
+`lane-left`, `lane-straight`, … ship with the map assets).
+
+## Navigation camera
+
+`NavigationCamera` gives the Google-Maps-style chase cam in one call per
+fix: tilted (pitch 60), course-up, the puck anchored low-centre so the
+camera looks up the road, each fix gliding into the next. Feed it from the
+same loop that drives your guidance:
+
+```ts
+import { NavigationCamera, PositionPuck } from "@mapmap/maps";
+
+const camera = new NavigationCamera(map, { pitch: 60, zoom: 17 });
+camera.attachPuck(new PositionPuck(map)); // one call now moves both
+navigator.geolocation.watchPosition(({ coords }) =>
+  camera.follow({ lat: coords.latitude, lon: coords.longitude }, coords.heading ?? undefined),
+);
+```
+
+- **Smoothness:** every `follow()` is an interruptible linear `easeTo`
+  whose duration is `easeMs` capped by the observed fix interval, so a
+  fast fix cadence glides continuously instead of queueing animations.
+- **User gestures win:** any drag / rotate / pitch / zoom switches the
+  camera to `"free"` mode (easing stops, fixes keep being recorded and the
+  puck keeps moving). It recentres itself after `autoRecentreMs` of idle
+  (default 6 s; `0` disables it - call `camera.resume()` yourself).
+- **Overview:** `camera.overview(route.geometry)` fits the whole route
+  top-down (pitch 0, north-up); `camera.resume()` returns to the chase cam
+  at the last fix. `camera.mode` reports `"follow" | "overview" | "free"`.
+- **Globe projection:** `NavigationCamera.isSupported(map)` returns
+  `false` when the map runs the globe (or vertical-perspective)
+  projection - the low-anchor offset maths and overview framing assume a
+  mercator camera. Switch to mercator
+  (`map.map.setProjection({ type: "mercator" })`) before navigating.
+- **Pitch above 60** is allowed (clamped at 85) and raises the map's
+  `maxPitch` for you, but MapLibre marks it experimental and DOM-marker
+  pucks flatten at extreme tilt - stay at 60 unless you have a reason.
+
+## Tiles, attribution and the verifying key
+
+The default light/dark styles load MapMap territory tiles as **PMTiles** over
+the `pmtiles://` protocol. Override the source with `territoryTilesUrl` (a
+`pmtiles://…` or plain `https://…` URL - the prefix is added for you).
+
+`© OpenStreetMap contributors © OpenMapTiles` attribution is **legally
+required** (ODbL + CC-BY 4.0) and is baked into every compiled style's tile
+source. It is not themable - no theme field can remove it.
+
+MapMap **territory packages** (the offline `.snpkg` bundles the mobile SDKs
+consume) are ed25519-signed and the app pins the factory public key. This web
+SDK renders tiles served by the gateway/CDN over HTTPS and does not verify
+package signatures in the browser; the signing/verifying-key story for the
+signed territory channel is documented in
+[`docs/SDK-DISTRIBUTION.md`](../docs/SDK-DISTRIBUTION.md) and
+[`docs/TERRITORY-UPDATES.md`](../docs/TERRITORY-UPDATES.md).
+
+## Bundler notes
+
+- ESM only. Ships `dist/index.js` + `dist/index.d.ts`.
+- `maplibre-gl` and `pmtiles` stay external; provide them in your app.
+- No bundler? See [`examples/index.html`](./examples/index.html) - it uses a
+  native import map and the unpkg ESM CDN.
+
+## Develop
+
+```sh
+npm install
+npm run typecheck   # tsc --noEmit
+npm run build       # tsup → dist/ (ESM + .d.ts)
+npm test            # vitest (pure-logic unit tests, no browser)
+```
+
+## Licence
+
+Proprietary - © 2026 Precode Ltd, distributed under a commercial licence.
+See [`LICENSE`](./LICENSE).