@mapmap/maps 0.1.0 → 0.2.0

package/llms-sdk.txt

@@ -0,0 +1,131 @@
+# @mapmap/maps — agent integration guide
+
+You are integrating the MapMap Maps SDK: a thin TypeScript wrapper over
+MapLibre GL JS that renders a MapMap-branded map (signed territory PMTiles)
+with routing, places, reachability rings and effects against the MapMap
+gateway (default https://api.mapmap.ai). ESM only. British English docs.
+
+## Install and initialise
+
+    npm install @mapmap/maps maplibre-gl pmtiles
+
+maplibre-gl and pmtiles are PEER dependencies: the app must own exactly ONE
+copy of maplibre-gl. Two copies break the WebGL context, styles and the
+pmtiles protocol registration (the SDK console.errors `[duplicate-maplibre]`
+when it detects this).
+
+    import { MapMapMap } from "@mapmap/maps";
+    import "maplibre-gl/dist/maplibre-gl.css";   // required CSS
+
+    const map = new MapMapMap({ container: "map", apiKey: "snk_…" });
+    await map.whenReady();
+
+GOTCHA (the number-one blank-map cause): the container must have a real
+height. A bare `<div id="map">` resolves to 0px and MapLibre renders an
+invisible canvas with no error. Fix: `#map { height: 100vh; }`. The SDK
+console.errors `[container-zero-height]` when it detects this.
+
+## Get an API key (self-serve, no account)
+
+    curl -X POST https://api.mapmap.ai/v1/keys \
+      -H "Content-Type: application/json" \
+      -d '{"email": "you@example.co.uk", "accept_tos": true}'
+
+The key (`snk_…`) is shown once; store it as a secret. A verification email
+raises the initial rate limits. All SDK classes reuse the map's
+`apiKey`/`baseUrl` automatically.
+
+## Routing (cars, walking, trucks/ADR)
+
+    import { RouteLayer } from "@mapmap/maps";
+    const routes = new RouteLayer(map);
+    const route = await routes.route(
+      { lng: -0.1278, lat: 51.5074 },
+      { lng: -1.8904, lat: 52.4862 },
+      { profile: "truck", truck: { heightM: 4.0, weightT: 40, hazmat: true, tunnelCode: "C" } },
+    );
+    // route: { distanceM, durationS, geometry (GeoJSON LineString), raw }
+
+`routes.routePath([a, b, c])` for via points; `routes.clear()` removes the
+line. Coordinates accept `[lng, lat]`, `{lng, lat}` or `{lon, lat}` — never
+lat-first. Pass `{ voice: true, banner: true, language: "en-GB" }` for
+turn-by-turn instructions (see `extractGuidance`, `GuidanceBanner`, `speak`).
+
+## Markers, clustering, store finder
+
+    import { PlacesLayer } from "@mapmap/maps";
+    const stores = new PlacesLayer(map, {
+      places: [{ id: "s1", name: "Soho", lat: 51.51, lon: -0.13 }],
+      cluster: true,                 // default: clustered count badges
+      fitBounds: true,
+      popup: (p) => `<strong>${p.name}</strong>`,
+    });
+    stores.nearest({ lat, lon }, 3);                      // haversine
+    await stores.nearestByDriveTime({ lat, lon }, { n: 3 }); // gateway /matrix
+
+## Walkability rings (isochrones)
+
+    import { IsochroneLayer } from "@mapmap/maps";
+    const rings = new IsochroneLayer(map);
+    await rings.showReachability({
+      origin: { lat: 51.5074, lon: -0.1278 },
+      mode: "walk",            // "walk" | "cycle" | "drive" | "truck" | raw costing
+      minutes: [5, 10, 15],
+    });
+    rings.clear();
+
+Renders graduated-opacity fills, contour outlines and "N min" labels from
+the gateway's POST /isochrone (Valhalla). Returns the GeoJSON
+FeatureCollection for your own use.
+
+## Cinematic flythrough + scrollytelling
+
+    import { flythrough, bindFlythroughToScroll } from "@mapmap/maps";
+    const replay = flythrough(map, route, { pitch: 60, durationMs: 15000 });
+    replay.play();                       // also: pause, stop, seek(0..1), speed
+    replay.onProgress((t) => { /* 0..1 */ });
+    // Scroll-driven storytelling: scrolling scrubs the camera along the route.
+    const unbind = bindFlythroughToScroll(replay, document.querySelector("#story"));
+
+## Route effects (flowing energy ribbon)
+
+    map.setRouteEffect("flow");                        // attaches to the drawn route
+    map.setRouteEffect("flow", { color: "#ff7a1f", width: 12, speed: 0.8 });
+    map.setRouteEffect(null);                          // plain line again
+
+First-party GLSL in a MapLibre custom layer. Honours
+prefers-reduced-motion (static gradient); falls back silently to the plain
+route line if WebGL setup fails. Styles compiled from a theme with an
+`effects` block (`{"effects": {"route": "flow", "params": {…}}}`) carry
+`metadata["mapmap:effects"]` and auto-enable the ribbon; an explicit
+`setRouteEffect(…)` call always wins.
+
+## Navigation extras
+
+- `NavigationCamera` — turnkey chase cam for live GPS fixes (`follow`,
+  `overview`, auto-recentre). Use `flythrough` for replays, this for real
+  navigation. Not supported under globe projection.
+- `PositionPuck` — current-position marker with heading.
+- `GuidanceBanner` / `extractGuidance` / `speak` — visual + spoken
+  turn-by-turn from route responses.
+- Voice: request `{ voice: true }` on routes and feed `speak()`; a
+  dedicated `voice` module provides platform speech-synthesis helpers.
+- Themes: `style:` accepts "light", "dark", or a MapMap Studio Theme JSON
+  (palette slots + layer overrides + optional `effects`). `buildStyle()`
+  compiles one without a map.
+
+## Error diagnosis
+
+The SDK self-diagnoses the classic failures — one actionable console.error
+per issue per page, each tagged and linking https://mapmap.ai/docs:
+`[container-zero-height]`, `[container-detached]`, `[duplicate-maplibre]`,
+`[webgl-unavailable]`, `[invalid-api-key]` (a 401 usually means a missing,
+mistyped or revoked `snk_…` key — issue one via POST /v1/keys).
+
+Gateway errors are RFC 9457 problem+json; SDK exceptions surface their
+`title`/`detail` in the message.
+
+## Attribution
+
+"© OpenStreetMap contributors © OpenMapTiles" is legally required, baked
+into every style, and not removable. Do not attempt to hide it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapmap/maps",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MapMap Maps SDK — a thin, well-typed MapLibre GL JS wrapper that drops a MapMap-branded map with signed territory tiles and OSRM-compatible truck/ADR routing into any web app.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Precode Ltd",
@@ -18,7 +18,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "llms-sdk.txt"
   ],
   "scripts": {
     "build": "tsup",