@mapmap/maps 0.1.0 → 0.2.0

package/README.md

@@ -22,6 +22,11 @@ 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.
 
+**Building with an AI agent?** The package ships
+[`llms-sdk.txt`](./llms-sdk.txt) - a concise, agent-facing integration
+guide (init, key issuance, routing, places, flythrough, effects,
+isochrones, and the classic gotchas). Point your coding agent at it.
+
 ## Quickstart
 
 ```ts
@@ -114,6 +119,12 @@ puck.remove();
 
 ### `class PlacesLayer` - places / store finder
 
+> **⚠️ Give the map container an explicit height first.** MapLibre silently
+> renders into a 0px-tall canvas when the container's height resolves to
+> zero (a bare `<div id="map">` with no CSS) - no error, no map, no pins.
+> Set `#map { height: 100vh; }` (or any real height) before debugging
+> anything else.
+
 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`).
@@ -128,15 +139,18 @@ const stores = new PlacesLayer(map /* MapMapMap or maplibregl.Map */, {
     // …or a plain GeoJSON FeatureCollection of Points
   ],
   cluster: true,                      // default; clusterRadius?, clusterMaxZoom?
-  color: "#ff6b35",                   // pin + cluster colour (default signal blue)
+  color: "#ff6b35",                   // pin colour: string or expression (below)
   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.setPlaces(nextPlaces);                    // replace data - never dropped
+stores.select("man-01");                         // list→map sync: popup + camera
+stores.deselect();                               // close the popup
 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.ids;       // { source, points, clusters, clusterCounts } - see below
 stores.clear();   // remove pins;  stores.destroy() also detaches listeners
 ```
 
@@ -146,6 +160,71 @@ 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.
 
+`setPlaces` never silently drops an update: once the source exists the data
+is applied immediately - even mid-render, while `map.isStyleLoaded()` is
+transiently `false` - and calls made before the style has first loaded are
+stashed (the latest one wins) and installed on `style.load`.
+Search-as-you-type just works.
+
+#### Per-category pin colours
+
+`color` also accepts a MapLibre expression, evaluated against each
+feature's `properties`. Everything in a place's `properties` is copied
+verbatim onto the **top level** of its GeoJSON feature's properties,
+alongside the reserved `id`, `name` and `__mapmapIndex` keys (which win on
+collision) - so a scalar like `category` is directly `["get", …]`-able.
+MapLibre JSON-stringifies nested objects/arrays at render time, so keep
+anything you want to style on as a top-level string/number/boolean:
+
+```ts
+const stores = new PlacesLayer(map, {
+  places: [
+    { id: "s1", name: "Corner Deli", lat: 51.5, lon: -0.1,
+      properties: { category: "food" } },
+    { id: "s2", name: "St Pancras", lat: 51.53, lon: -0.126,
+      properties: { category: "travel" } },
+  ],
+  color: [
+    "match", ["get", "category"],
+    "food",       "#e63946",
+    "travel",     "#457b9d",
+    "postoffice", "#d90429",
+    "childcare",  "#ffb703",
+    /* fallback */ "#3a86ff",
+  ],
+  clusterColor: "#3a86ff", // clusters mix categories → plain colour only
+});
+```
+
+A cluster mixes categories, so an expression never applies to cluster
+circles: they use `clusterColor`, which defaults to `color` when that is a
+plain string, else to MapMap signal blue. (With a custom `icon`, pins are
+images - `color` only styles the default circle pins.)
+
+#### Programmatic selection (list → map)
+
+`select(id, options?)` syncs a results list to the map: it opens the
+configured `popup` at the place (`popup: false` to skip) and eases the
+camera to it (`flyTo: false` to skip; `zoom` to also zoom in). It returns
+the `Place`, or `undefined` for an unknown id (nothing happens). It does
+**not** call `onPlaceClick` - programmatic selection is not a user click.
+`deselect()` closes any open popup.
+
+#### Escape-hatch styling: `ids`
+
+The generated MapLibre ids are public API via `stores.ids` →
+`{ source, points, clusters, clusterCounts }`, so raw MapLibre calls are
+supported when the options don't reach far enough:
+
+```ts
+map.setPaintProperty(stores.ids.points, "circle-radius", 9);
+map.queryRenderedFeatures({ layers: [stores.ids.points] });
+```
+
+`clusters`/`clusterCounts` are only installed with `cluster: true` (the
+default); `points` is a circle layer by default, or a symbol layer once a
+custom `icon` has loaded.
+
 ### `class NavigationCamera`
 
 The turnkey chase cam: follows each GPS fix course-up, tilted, with the
@@ -303,6 +382,89 @@ puck.setLocation({ lat: 51.5074, lon: -0.1278 }, 45); // heading in degrees
   payloads capped at 64 KB) - a malformed block falls back per-field to the
   defaults rather than failing.
 
+## Cinematic flythrough and scrollytelling
+
+`flythrough(map, route, options?)` replays a route as a chase-cam ride: the
+camera glides along the line, bearing eased along the shortest arc towards
+a look-ahead point, at a configurable pitch/zoom/speed.
+
+```ts
+import { flythrough, bindFlythroughToScroll } from "@mapmap/maps";
+
+const route = await routes.route(from, to);
+const replay = flythrough(map, route, { pitch: 60, durationMs: 15000 });
+replay.onProgress((t) => scrubber.value = String(t));
+replay.play(); // also: pause(), stop(), seek(0..1), speed = 2
+
+// Scrollytelling: scrolling the story column scrubs the camera.
+const unbind = bindFlythroughToScroll(replay, document.querySelector("#story")!);
+```
+
+Options: `pitch` (default 60), `zoom` (16), `durationMs` (20 000) or
+`speedMps` (ground speed; wins over duration), `lookAheadM` (200),
+`bearingEase` (3). Accepts a `ParsedRoute` or a GeoJSON LineString. Nothing
+moves until `play()`/`seek()`. `flythroughPose`, `bearingBetween` and
+`shortestArcDelta` are exported for apps driving the camera themselves.
+
+## Route effects (the flowing ribbon)
+
+`map.setRouteEffect("flow")` draws an animated energy ribbon along the
+active route line - a MapLibre custom layer with first-party GLSL, no
+extra dependencies.
+
+```ts
+map.setRouteEffect("flow");                          // uses the RouteLayer route
+map.setRouteEffect("flow", { color: "#ff7a1f", width: 12, speed: 0.8 });
+map.setRouteEffect("flow", { geometry });            // explicit geometry
+map.setRouteEffect(null);                            // plain line again
+```
+
+- Attaches automatically to whatever a `RouteLayer` on the map draws
+  (current and future routes), and dies with `routes.clear()`.
+- Themes can request it: a Studio theme with
+  `"effects": { "route": "flow", "params": { … } }` compiles to
+  `metadata["mapmap:effects"]` on the style, and the map auto-enables the
+  ribbon. An explicit `setRouteEffect(…)` call (including `null`) wins.
+- `prefers-reduced-motion` freezes the ribbon to a static gradient.
+- If WebGL setup for the effect fails, it falls back silently to the plain
+  route line (one console warning).
+
+## Walkability rings (isochrones)
+
+Reachability contours from the gateway's `POST /isochrone`:
+
+```ts
+import { IsochroneLayer } from "@mapmap/maps";
+
+const rings = new IsochroneLayer(map); // baseUrl/apiKey from the map
+await rings.showReachability({
+  origin: { lat: 51.5074, lon: -0.1278 },
+  mode: "walk",           // "walk" | "cycle" | "drive" | "truck" | raw costing
+  minutes: [5, 10, 15],
+  color: "#3a86ff",       // optional
+});
+rings.clear();
+```
+
+Renders graduated-opacity fills (nearest ring strongest), contour outlines
+and `"N min"` labels, survives theme swaps, and resolves to the raw GeoJSON
+`FeatureCollection` (each feature carries a `contour` property in minutes).
+`costingOptions` forwards Valhalla costing options verbatim (e.g.
+`{ pedestrian: { use_lit: 1.0 } }`).
+
+## Self-diagnosing errors
+
+The map diagnoses the classic silent failures at construction and logs ONE
+actionable `console.error` per issue per page, each with a docs link:
+
+- `[container-zero-height]` - the 0px container (top blank-map cause)
+- `[container-detached]` - container not in the DOM
+- `[duplicate-maplibre]` - two maplibre-gl copies on one page
+- `[webgl-unavailable]` - no WebGL context available
+- `[invalid-api-key]` - a 401 from the gateway (missing/mistyped/revoked key)
+
+`runMapDiagnostics(…)` is exported for apps wrapping a raw `maplibregl.Map`.
+
 ## The MapMap mark
 
 Maps render a small MapMap wordmark bottom-right (the same convention as
@@ -317,7 +479,7 @@ removable.
 import { GuidanceBanner, extractGuidance, speak } from "@mapmap/maps";
 
 const route = await routes.route(from, to, {
-  costing: "truck",
+  profile: "truck",
   voice: true,
   banner: true,
   language: "en-GB",