@minmaps-dev/mm-web-sdk 1.0.0-rc.3 → 1.0.0-rc.30

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { IControl, ControlPosition, Map } from 'maplibre-gl';
+import { IControl, ControlPosition, StyleSpecification, Map } from 'maplibre-gl';
 
 /**
  * Represents a floor in a building
@@ -6,6 +6,12 @@ import { IControl, ControlPosition, Map } from 'maplibre-gl';
 interface Floor {
     /** Unique floor identifier */
     id: string | number;
+    /**
+     * Underlying map entity id. Separate from `id` (the floor entity id) — used
+     * by waypoints (`wp.mapId`) and floor-geojson endpoints. Optional because
+     * not all providers populate it.
+     */
+    mapId?: string | number;
     /** Display name of the floor */
     name: string;
     /** Floor sequence/order (e.g., -1 for basement, 0 for ground, 1 for first floor) */
@@ -32,7 +38,7 @@ interface POI {
     /** Unique identifier */
     id: string | number;
     /** POI type */
-    type: 'amenity' | 'destination';
+    type: 'amenity' | 'destination' | 'kiosk';
     /** Display name */
     name: string;
     /** Geographic coordinates [longitude, latitude] */
@@ -55,6 +61,9 @@ interface POI {
     waypoint?: Waypoint;
     /** Marks this POI as the "You are here" kiosk */
     isYouAreHere?: boolean;
+    /** For kiosk POIs only: compass heading the device physically faces, in
+     *  degrees clockwise from north. Sourced from JACS `Device.heading`. */
+    heading?: number | null;
 }
 /**
  * Amenity - a specific type of POI (facilities, services)
@@ -64,8 +73,25 @@ interface Amenity {
     id: string | number;
     /** Display name */
     name: string;
-    /** SVG icon data */
+    /** Inline SVG markup (legacy fullcall DTO). When absent, icon is resolved from `uris`. */
     svg?: string;
+    /**
+     * Hosted icon descriptors from JACS (`uris[].locales[].uriPath`). Used by
+     * the SDK's runtime icon fetcher to register a map image at init time.
+     */
+    uris?: Array<{
+        mimeType?: string;
+        resourceType?: string;
+        locales?: Array<{
+            locale?: string;
+            uriPath?: string;
+        }>;
+    }>;
+    /**
+     * Map-image id used as `icon-image` in the POI style layer. Decorated
+     * in-place by AmenityIcons.register once the SVG is fetched and registered.
+     */
+    iconId?: string;
     /** Search keywords */
     keywords?: string[];
     /** Associated waypoints */
@@ -89,6 +115,20 @@ interface Destination {
     category?: string;
     /** Additional properties */
     properties?: Record<string, unknown>;
+    /** Uploaded image (e.g. brand/store logo). JACS `/all` fullcall serves this
+     *  as `{ items: [{ resourceType, mimeType, path }] }`; the legacy/basic shape
+     *  is `[{ locales: [{ uriPath }] }]`. `DestinationIcons.register` handles both. */
+    uris?: unknown;
+    /** Free-form CMS metadata (reserved for future destination icon options). */
+    extensors?: Record<string, unknown>;
+    /** Map-manager "Label Display" mode (JACS `displayMode`):
+     *  `0` Hidden (dot only) · `1` Label (dot + text) · `2` Image (uploaded logo).
+     *  Undefined → treated as Label (backwards-compatible default). */
+    displayMode?: number;
+    /** Runtime-assigned map-image id, decorated in place by
+     *  `DestinationIcons.register` (only for `displayMode === 2`).
+     *  Read by the POI builder + theme layer. */
+    iconId?: string;
 }
 /**
  * Waypoint - a specific point location
@@ -140,6 +180,83 @@ type ViewOptions = {
 /** SW/NE bounding box */
 type Bounds = [[number, number], [number, number]];
 
+/** How to center the map after computing a route */
+type WayfindCenterMode = 'none' | 'destination' | 'route';
+/**
+ * Per-call routing preferences forwarded to the wayfinding provider.
+ *
+ * - `accessible` — prefer accessible paths; providers should drop or heavily
+ *   penalize edges marked inaccessible (stairs by default, anything else
+ *   the provider's data flags).
+ * - `avoidStairs` — hard-filter stairs from the graph.
+ *
+ * The bundled stub provider doesn't compute routes; consumers wire a real
+ * provider (see `mm-web-sdk-example/lib/wayfinding`) that reads these
+ * flags when building edge weights.
+ */
+type RoutingOptions = {
+    accessible?: boolean;
+    avoidStairs?: boolean;
+};
+
+/**
+ * A single point along the rendered route. `mapId` lets the renderer
+ * split the polyline by floor (so other-floor segments don't paint
+ * through the visible floor's geometry); `waypointId` and `pathTypeId`
+ * let downstream layers (text-directions, step UI) classify
+ * transitions — e.g. "Take the elevator" vs "Walk straight". The two
+ * endpoint points are the kiosk and destination anchors (`isEndpoint`
+ * marks them so they can render endpoint pins). All fields except
+ * `coordinates` are optional for backward-compat with the straight-line
+ * fallback.
+ */
+type RoutePoint = {
+    coordinates: [number, number];
+    /** Floor mapId this point sits on. Missing on the straight-line fallback. */
+    mapId?: number;
+    /** JACS waypoint id this point resolved to, if any. */
+    waypointId?: number;
+    /** Path type of the edge that LEADS INTO this point (i.e. the edge
+     *  whose `toKey` is this node). Used to detect elevator / stair /
+     *  escalator transitions. Missing on the start point and on the
+     *  straight-line fallback. */
+    pathTypeId?: number;
+    /** True for the snapped kiosk + destination anchors. */
+    isEndpoint?: boolean;
+};
+
+type WayfindStep = DepartStep | TurnStep | ContinueStep | TransitionStep$1 | ArriveStep;
+type StepBase = {
+    /** Indices into the input `points` array that this step spans. */
+    pointRange: [startInclusive: number, endInclusive: number];
+    /** Floor this step is on. `null` for cross-floor transitions. */
+    floorId: number | null;
+    /** Localized instruction text. */
+    text: string;
+    /** Total walking distance within this step, in meters (rounded). */
+    distanceMeters?: number;
+    /** Landmark name used for anchoring, if any. */
+    landmark?: string;
+};
+type DepartStep = StepBase & {
+    type: 'depart';
+};
+type TurnStep = StepBase & {
+    type: 'turn-left' | 'turn-right' | 'u-turn';
+};
+type ContinueStep = StepBase & {
+    type: 'continue';
+};
+type TransitionStep$1 = StepBase & {
+    type: 'transition';
+    transition: 'elevator' | 'stairs' | 'escalator';
+    fromFloorId: number | null;
+    toFloorId: number | null;
+};
+type ArriveStep = StepBase & {
+    type: 'arrive';
+};
+
 interface MapEvent {
     floor?: Floor;
     poi?: POI;
@@ -147,18 +264,156 @@ interface MapEvent {
     error?: any;
     venue?: any;
     camera?: CameraState;
+    /** Emitted by `themeChanged`; `'custom'` when consumer passed a raw style. */
+    theme?: 'default' | 'high-contrast' | 'custom';
+    /** Emitted by `localeChanged` after `setLocale()` finishes patching the
+     *  venue model. BCP-47 code (`'en'`, `'es'`, `'es-MX'`). */
+    locale?: string;
+    /** Emitted by `routeReady` after a successful `navigateFromKioskToPOI`.
+     *  Carries the raw geometry (`points`) and the human-readable
+     *  step-by-step directions. Subscribe to drive a turn-by-turn UI. */
+    route?: {
+        points: RoutePoint[];
+        steps: WayfindStep[];
+        /** Floor mapId of each segment, in render order. `null` for
+         *  segments emitted by the straight-line fallback. */
+        floorIds: Array<number | null>;
+    };
 }
 type EventCallback = (event: MapEvent) => void;
 
+/**
+ * Padding kept clear inside the viewport when the SDK frames bounds —
+ * the initial venue/floor fit and the wayfinding route fit. A plain
+ * number pads all sides equally; the object form lets a kiosk reserve
+ * space for fixed UI overlays (header, dock, side rails) so framed
+ * content is never hidden behind them.
+ */
+type BoundsPadding = number | {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+};
+/**
+ * Built-in theme names accepted by `MinuteMaps.setTheme()` and the
+ * `options.theme` init option. Pass a `StyleSpecification` directly for
+ * custom themes.
+ */
+type ThemeName = 'default' | 'high-contrast';
+/**
+ * Style of the disc + ring rendered behind each amenity icon. The SDK
+ * composites this into the icon bitmap at registration time, so badge +
+ * icon participate in symbol collision as one unit.
+ */
+type AmenityBadgeStyle = {
+    /** Fill colour of the badge disc. Default `'#fdb81e'`. */
+    color?: string;
+    /** Stroke colour of the ring around the disc. Default `'#FFFFFF'`. */
+    ringColor?: string;
+    /** Ring width in logical px. Default `2`. */
+    ringWidth?: number;
+};
+type DestinationChipStyle = {
+    /** Chip fill colour. Default `'#FFFFFF'`. */
+    color?: string;
+    /** Chip border colour. Default navy `'#162e51'`. */
+    borderColor?: string;
+    /** Chip border width in logical px. Default `2`. */
+    borderWidth?: number;
+};
 interface SDKOptions {
     debug?: boolean;
-    theme?: 'light' | 'dark' | 'hybrid' | any;
+    /**
+     * Initial theme. `'default'` uses the bundled hybrid 3D theme.
+     * `'high-contrast'` uses the WCAG-AA tuned theme. Pass a
+     * `StyleSpecification` for fully custom styling.
+     */
+    theme?: ThemeName | any;
+    /**
+     * When true, the SDK skips animations on imperative camera calls
+     * (wayfinding fits, `setView`, idle re-frames). Consumers should
+     * mirror their app's `prefers-reduced-motion` state into this.
+     */
+    reducedMotion?: boolean;
+    /**
+     * Whether a freshly computed route auto-highlights its first step's
+     * segment (the brighter `route-line-active` overlay). Defaults to
+     * `true`, preserving the turn-by-turn segment highlight that
+     * `setActiveStep` drives.
+     *
+     * Set `false` for kiosk-style "show the whole route at once" UIs:
+     * the entire route line is shown without singling out one segment,
+     * which reads more clearly at a glance and avoids implying the visitor
+     * must step through the route. `setActiveStep` still works when called
+     * explicitly (e.g. a paginated QR-handoff / mobile flow) — this only
+     * controls the automatic highlight on `routeReady`.
+     */
+    routeStepHighlight?: boolean;
     initialFloor?: string | number;
     enableInteractions?: boolean;
     customSprite?: string;
     minIndoorZoom?: number;
     wallThickness?: number;
-    boundsPadding?: number;
+    boundsPadding?: BoundsPadding;
+    /**
+     * Pitch (deg) for the opening view, applied centred on the kiosk ("You
+     * are here"). Omit for top-down.
+     */
+    initialPitch?: number;
+    /**
+     * Zoom for the opening view, centred on the kiosk. Set this above the
+     * theme's unit-walls breakpoint (~16.5 in the bundled hybrid theme) so the
+     * kiosk opens on the building's interior floor plan (its contents) rather
+     * than a zoomed-out 3D massing outline. Omit to keep the post-floor-fit
+     * zoom.
+     */
+    initialZoom?: number;
+    /**
+     * Clamp zoom-out relative to the opening view. When set, the map's
+     * `minZoom` becomes `(initialZoom − this)`, so visitors can nudge out by
+     * this many zoom levels but never pull back below the interior into the
+     * massing/region. `0` locks zoom-out exactly to the opening view.
+     */
+    minZoomBelowInitialFit?: number;
+    /**
+     * Override the colour the SDK recolours every amenity SVG to before it
+     * composites the badge. `none` / `transparent` fills are preserved so
+     * cut-outs stay. When the badge is enabled (the default), this defaults
+     * to navy (`#162e51`) so icons read on gold. Set explicitly for a
+     * different look, or set `amenityBadge: false` to disable recolouring
+     * altogether and keep the CMS-uploaded colours.
+     */
+    amenityIconColor?: string;
+    /**
+     * Badge composited behind each amenity icon. Pass `false` to render the
+     * icon alone (no badge — useful for high-contrast or 2D themes where the
+     * gold disc would compete with the floor). Pass an object to tune the
+     * disc / ring style. Defaults to a VA-gold disc with a 2px white ring.
+     *
+     * The badge is baked into the icon bitmap (canvas composite) rather than
+     * drawn as a separate circle layer, so badge + icon participate in symbol
+     * collision together — overlapping amenities hide as one unit instead of
+     * the icon hiding while the disc stays painted.
+     */
+    amenityBadge?: AmenityBadgeStyle | false;
+    /**
+     * Badge for vertical-circulation connectors (elevator / stairs / escalator).
+     * These render as their own visual class — a navy disc with a white glyph —
+     * so circulation reads distinct from the gold service amenities. Pass `false`
+     * to fall them back into the regular gold badge, or an object to tune the
+     * disc / ring. When `amenityBadge` is `false`, connectors are badge-less too
+     * unless this is set explicitly.
+     */
+    connectorBadge?: AmenityBadgeStyle | false;
+    /**
+     * Chip composited behind each destination's uploaded logo. Destinations are
+     * full-colour brand images (not recoloured), so they get a neutral white
+     * rounded chip for legibility instead of the amenity gold badge. Pass `false`
+     * to render the logo bare, or an object to tune the chip fill / border.
+     * Defaults to a white chip with a 2px navy border.
+     */
+    destinationChip?: DestinationChipStyle | false;
     styleMode?: 'venueStyleUrl' | 'sdkTemplate';
     templateOverrideMode?: 'colorsOnly' | 'colorsAndConstants' | 'all';
 }
@@ -190,6 +445,13 @@ type SDKConfig = {
         venueId: number;
         locale?: string;
         auth?: JMapAuth;
+        /**
+         * Identifies which physical kiosk this instance is, so the SDK can pin
+         * the "You are here" marker. Matched against either the numeric device
+         * `id` or the device `uuid` from the venue's `devices`. The device's
+         * attached waypoint (`waypoint.deviceIds`) is the kiosk's location.
+         */
+        deviceId?: string | number;
     };
     jacs: {
         mode: 'proxy' | 'direct';
@@ -204,9 +466,6 @@ type SDKConfig = {
     options?: SDKOptions;
 };
 
-/** How to center the map after computing a route */
-type WayfindCenterMode = 'none' | 'destination' | 'route';
-
 type LoggerFn = (...args: unknown[]) => void;
 type AmenityManagerDeps = {
     getVenue: () => any;
@@ -224,6 +483,19 @@ declare class AmenityManager {
     private log;
     private loadForFloor;
     getAll(): AmenityWithFloor[];
+    /**
+     * Venue-wide amenities, one entry per id. `getAll()` returns each amenity
+     * once per floor it appears on (and so renders a multi-floor "Bathroom"
+     * three times in a venue list); this collapses those into a single record
+     * with all its waypoints merged across floors.
+     *
+     * Also folds any duplicate-id records from the provider (a CMS data bug)
+     * into a single entry so React lists don't trip on dup keys.
+     *
+     * Use this for venue-wide browse UIs; pair it with `findClosestWaypoint`
+     * (on the SDK) to resolve a tap to the nearest physical instance.
+     */
+    getDistinct(): Amenity[];
     getByFloorId(floorId: Floor['id']): AmenityWithFloor[];
     getAllKiosks(): AmenityWithFloor[];
     getKioskForFloor(floorId: Floor['id']): AmenityWithFloor | null;
@@ -243,8 +515,25 @@ declare class MinuteMaps {
     private readonly logger;
     private defaultCamera;
     private viewModes;
+    /** Mirror of `config.options.reducedMotion`, mutable via `setReducedMotion`. */
+    private reducedMotion;
+    /** Tracks the active theme name so `setTheme()` is a no-op when re-requested. */
+    private activeThemeName;
+    /** Tracks the active locale so `setLocale()` is a no-op when re-requested.
+     *  Seeded from `config.jmap.locale` at construction; `undefined` means
+     *  whatever the customer's default locale is on the JACS side. */
+    private currentLocale;
     private amenityManager;
     private wayfinding;
+    private highlightManager;
+    private youAreHerePulse;
+    /** Categorical POI layers in the bundled theme that `setPOIFilter`
+     *  toggles. Layers absent from this list — `poi-you-are-here-*`, the
+     *  `poi-accessibility-icons` badge, and the `poi-highlight-*` layers —
+     *  are intentionally unaffected; they're either anchors, status
+     *  indicators, or transient focus state, not categorical content. */
+    private static readonly POI_CATEGORY_LAYERS;
+    private poiVisibleTypes;
     constructor(config: SDKConfig);
     init(): Promise<void>;
     on(event: string, cb: (e: MapEvent) => void): void;
@@ -256,9 +545,69 @@ declare class MinuteMaps {
         animate?: boolean;
         duration?: number;
     }): void;
+    /**
+     * Content-aware re-frame: fit an active route if one is displayed,
+     * otherwise fit the current floor's geojson. Unlike `resetView()`, this
+     * preserves the user's pitch and bearing — it only adjusts center/zoom
+     * to bring the scene back into view. Intended use is after the map
+     * container resizes (e.g. a side drawer opens beside the map and the
+     * pane gets narrower), so what matters stays framed without a yank.
+     */
+    refit(opts?: {
+        animate?: boolean;
+        duration?: number;
+    }): void;
+    /**
+     * Update the bounds padding (camera insets) used by route + floor fits.
+     * Consumers measure their on-screen chrome (panels, rails) and pass the
+     * insets so a fit frames the path in the visible, unobscured area rather
+     * than under the UI. Stored; the next fit / `refit()` uses it (clamped so
+     * a fit always lands — see `clampPadding`).
+     */
+    setBoundsPadding(p: BoundsPadding): void;
+    private fitToBounds;
     set3dEnabled(enabled: boolean): void;
     toggle3d(): void;
     getIs3dEnabled(): boolean;
+    /**
+     * Set the active map theme by name (`'default'` / `'high-contrast'`) or by
+     * passing a custom `StyleSpecification`. The current floor, route, POIs
+     * and camera are preserved across the swap — only layer styling changes.
+     *
+     * Used by kiosk consumers to wire the OS-level / popover high-contrast
+     * toggle to the map. See `KIOSK.md` for the pattern.
+     */
+    setTheme(theme: ThemeName | StyleSpecification): Promise<void>;
+    /** Currently active theme name (or `'custom'` when a raw style was passed). */
+    getActiveTheme(): 'default' | 'high-contrast' | 'custom';
+    /**
+     * Update the SDK's reduced-motion preference at runtime. When true,
+     * imperative camera animations (route fits, idle re-frames) and the
+     * route line-draw animation run with `duration: 0`.
+     */
+    setReducedMotion(enabled: boolean): void;
+    getReducedMotion(): boolean;
+    /**
+     * Switch the locale used for POI / amenity / destination / floor names at
+     * runtime. The SDK refetches localized names from JACS (per-entity
+     * endpoints — `/all` does not honor `?locale=`), patches the in-memory
+     * venue model in place, then redraws the POI source for the current floor
+     * so map labels render in the new language.
+     *
+     * Structural data (waypoints, coordinates, iconIds) is preserved — only
+     * the localized fields (`name`, `description`) move.
+     *
+     * Emits a `localeChanged` event with the new code after the patch
+     * completes. No-op when the code matches the current locale.
+     *
+     * Throws if the underlying data provider doesn't implement locale support
+     * (only `JacsDataProvider` does today), or if the JACS fetch fails — the
+     * prior locale is left intact in that case.
+     */
+    setLocale(locale: string): Promise<void>;
+    /** Currently active locale (BCP-47), or `undefined` when no locale has
+     *  been set — meaning JACS resolves names to the customer's default. */
+    getActiveLocale(): string | undefined;
     setUnits2dEnabled(enabled: boolean): void;
     toggleUnits2d(): void;
     getIsUnits2dEnabled(): boolean;
@@ -274,21 +623,239 @@ declare class MinuteMaps {
     getAllPOIs(floor?: Floor): POI[];
     getYouAreHerePOI(floor?: Floor): POI | null;
     getYouAreHereCoordinates(floor?: Floor): [number, number] | null;
+    /**
+     * Compass heading the kiosk's physical hardware faces, in degrees
+     * clockwise from north. Sourced from JACS `Device.heading`. `null` when
+     * the venue's device record has no heading set.
+     *
+     * In order to rotate the map so it is oriented towards the user's gaze,
+     * 180 is subtracted from `Device.heading`.
+     *
+     * Drives `recenterOnKiosk({ useHeading: true })` and the directional
+     * cone rendered next to the "You are here" marker.
+     */
+    getKioskHeading(): number | null;
+    /**
+     * Display name of the JACS device the kiosk is anchored to (e.g.
+     * "Main Lobby Kiosk", "Information Desk Kiosk"). `null` when the venue
+     * has no kiosk anchor or the device record carries no `name`.
+     *
+     * Distinct from `getYouAreHerePOI()?.name`, which is always the
+     * literal "You are here" label rendered on the map. Use this for chrome
+     * that needs the kiosk's identity — e.g. the directions overlay's
+     * "From <kiosk>" header.
+     */
+    getKioskName(): string | null;
+    /**
+     * Distance + walking time from the kiosk's anchor waypoint to a target,
+     * computed over the JACS path graph (the same graph the routing engine
+     * uses). Designed for "Closest: 30 sec walk" subtitles in the consumer
+     * UI — no second graph build, no second Dijkstra implementation.
+     *
+     * Accepts a raw waypoint id, an amenity / destination object (the first
+     * entry of its `waypoints` array is treated as the entry point), or any
+     * `{ id, mapId? }` shape. Returns `null` when the kiosk isn't anchored,
+     * the target waypoint isn't on the graph, or no path resolves.
+     *
+     * Walking speed defaults to 1.2 m/s (indoor wayfinding norm). Pass
+     * `walkingSpeedMps` to estimate for accessibility (e.g. 0.9).
+     */
+    getWalkTimeFromKiosk(target: number | string | {
+        id?: number | string;
+        mapId?: number;
+    } | {
+        waypoints?: Array<number | string | {
+            id?: number | string;
+        }>;
+    }, opts?: {
+        walkingSpeedMps?: number;
+    }): {
+        meters: number;
+        seconds: number;
+        pathNodeCount: number;
+    } | null;
+    /**
+     * Center the camera on the kiosk's "You are here" position. Use this
+     * (not `resetView`) for a chrome "Recenter" button — `resetView` snaps
+     * to the SDK's captured default camera, which may have been a venue
+     * overview rather than the kiosk's spot.
+     *
+     * When `useHeading` is true (default) and the kiosk device has a
+     * `heading` on file, the camera's bearing is rotated so the direction
+     * the kiosk physically faces ends up at the top of the screen. That
+     * way "what the user sees in front of them" matches "what's up on the
+     * map" — the single largest readability win for stressed indoor users.
+     */
+    recenterOnKiosk(opts?: {
+        useHeading?: boolean;
+        zoom?: number;
+        pitch?: number;
+        animate?: boolean;
+        duration?: number;
+    }): void;
     searchPOIs(query: string, floor?: Floor): POI[];
+    /**
+     * Search POIs across every floor in the venue. Returns raw matches —
+     * an amenity that exists on multiple floors appears multiple times,
+     * once per instance. Consumers that need one row per logical amenity
+     * should dedupe by id (and, for "nearest", pick the instance closest
+     * to the kiosk via planar distance on `coordinates`).
+     */
+    searchAllPOIs(query: string): POI[];
     wayfindBetweenWaypoints(fromWaypoint: any, toWaypoint: any, options?: {
         centerMode?: 'none' | 'destination' | 'route';
         zoom?: number;
+        /** Prefer accessible paths (drops or penalizes stairs / inaccessible edges). */
+        accessible?: boolean;
+        /** Hard-filter stairs from the graph. */
+        avoidStairs?: boolean;
     }): Promise<any>;
     navigateFromKioskToDestination(destination: any): Promise<any>;
+    /**
+     * Route from the kiosk to a specific POI's waypoint. Use this when you
+     * already hold a resolved POI (e.g. from `searchPOIs` / `searchAllPOIs`).
+     * For a venue-wide amenity record with multiple instances, resolve via
+     * `findClosestWaypoint` first — or use `highlightAmenity` instead, if
+     * you want a visual focus rather than a route.
+     */
+    navigateFromKioskToPOI(poi: POI, options?: {
+        accessible?: boolean;
+        avoidStairs?: boolean;
+    }): Promise<any>;
+    /** Build the landmark / floor-name context the directions module needs.
+     *  Pulled out so `setLocale()` or `setActiveStep()` can rebuild it on
+     *  demand if we ever surface a locale-aware variant. */
+    private buildDirectionsContext;
+    /**
+     * Drive the turn-by-turn UI. Two effects:
+     *
+     * 1. When the step's `floorId` differs from the active floor, switch
+     *    floors so the segment for the step's leg becomes visible.
+     * 2. Highlight the step's slice of the route line by writing the
+     *    point range to the `route-active-step` source; the bundled
+     *    theme's `route-line-active` layer paints it in gold over the
+     *    muted base route.
+     *
+     * Transition steps (cross-floor elevator / stair hops) clear the
+     * highlight — the overlay text carries the action, and there's no
+     * meaningful on-floor segment to paint.
+     *
+     * Pass `null` to clear the highlight without changing the floor or
+     * tearing down the route.
+     */
+    setActiveStep(step: WayfindStep | null): Promise<void>;
+    private writeActiveStepHighlight;
+    private clearActiveStepHighlight;
     clearRoute(): void;
+    /**
+     * Highlight a single POI on the map — a pulsing ring — and bring it into
+     * view. Resolves the POI across all floors, switching the active floor if
+     * it lives on another one. Pass a POI / amenity / destination id.
+     */
+    highlightPOI(id: string | number): Promise<void>;
+    /** Remove the POI highlight set by `highlightPOI`. */
+    clearHighlight(): void;
+    /**
+     * Show only the named POI categories on the map. Pass `['amenity']` to
+     * emphasize amenities (e.g. while an Amenities drawer is open) — destination
+     * POIs hide. Call `clearPOIFilter()` to restore the default (all categories).
+     *
+     * The "You are here" marker, the wheelchair-accessibility badge, and any
+     * active highlight are not affected and always render.
+     */
+    setPOIFilter(types: Array<'amenity' | 'destination'>): void;
+    /** Restore the default — every POI category renders. */
+    clearPOIFilter(): void;
+    private applyPOIFilter;
+    /**
+     * Return the waypoint in `waypoints` closest to `from`. Useful for
+     * "route to the nearest X" against a venue-wide amenity record that has
+     * multiple physical instances. Defaults `from` to the kiosk's
+     * "You are here" coordinates.
+     *
+     * Distance is planar Euclidean on lng/lat — sufficient for ordering at
+     * single-venue scale, and avoids a turf dependency on the hot path.
+     */
+    findClosestWaypoint(waypoints: Waypoint[], from?: [number, number]): Waypoint | null;
+    /**
+     * Route from the kiosk to the closest physical instance of an amenity.
+     * Resolves the amenity venue-wide, picks the instance with the smallest
+     * path-graph walk time from the kiosk (falling back to planar Euclidean
+     * when the walk-time graph can't resolve any waypoint), switches the
+     * active floor if needed, and routes via the same plumbing as
+     * `navigateFromKioskToPOI` — so step-by-step directions, the
+     * `routeReady` event, and the active-floor camera fit all "just work."
+     *
+     * Pass `accessible` / `avoidStairs` to weight the *route* (the SDK's
+     * routing engine reads these per call). Note: closest-instance picking
+     * itself is currently distance-based and does not yet honor those
+     * weights — the underlying walk-time graph applies pixel-length only.
+     * In practice this matters when an amenity has multiple instances and
+     * the geometrically closest is reachable only via stairs; the picked
+     * instance won't change today, but the *route* to it will avoid stairs
+     * (or fail gracefully) if `accessible`/`avoidStairs` is set.
+     */
+    navigateFromKioskToClosestAmenity(amenityId: string | number, options?: {
+        accessible?: boolean;
+        avoidStairs?: boolean;
+    }): Promise<any>;
+    /**
+     * Highlight + center on the closest physical instance of an amenity.
+     * The amenity is resolved against `amenities.getDistinct()` (venue-wide,
+     * deduped); the closest waypoint to the kiosk is picked; the active floor
+     * is switched if that instance lives on another one.
+     *
+     * This is the right call from a venue-wide list ("here are all the
+     * bathrooms in the building, take me to the closest one"). For taps on
+     * a specific resolved POI (e.g. a search result that already names one
+     * instance), use `highlightPOI` instead.
+     */
+    highlightAmenity(amenityId: string | number): Promise<void>;
+    /** Which floor owns this waypoint, by matching mapId against the floor's
+     *  `mapId` (or `id` as fallback). Used to switch floors when routing /
+     *  highlighting hits an instance on a different one. */
+    private findFloorForWaypoint;
     getCameraPosition(): CameraState | null;
     getMap(): Map | null;
     destroy(): void;
     setCurrentFloor(floor: Floor): Promise<void>;
+    /**
+     * Filter the route-line / route-halo layers to only render segments
+     * whose `floorId` matches the active floor (or features that carry no
+     * `floorId` at all — the straight-line fallback, which we want visible
+     * on every floor since it has no floor membership to filter against).
+     *
+     * Features are tagged with the JACS pixel `mapId` (that's what flows
+     * through the route point's `mapId`), so the filter compares against
+     * the active floor's `mapId`, NOT its `id` — those are two different
+     * JACS identifiers (`floor.id` is the building-floor record; `mapId`
+     * is the SVG asset). We accept the floor's `id` here for convenience
+     * and resolve to `mapId` via `getFloors()`.
+     *
+     * Applied imperatively rather than baked into the theme JSON so the
+     * filter tracks runtime floor changes without restyling the map.
+     */
+    private updateRouteFloorFilter;
     isReady(): boolean;
     private setFloorLayerVisibility;
     private getBoundsPadding;
+    /**
+     * Shrink per-side padding if the requested insets would leave no room.
+     * `cameraForBounds` / `fitBounds` silently fail ("Map cannot fit within
+     * canvas") when an axis's total padding meets or exceeds that axis — cap
+     * each axis's total at 80% so a fit always has space to land.
+     */
+    private clampPadding;
     private getVenueBounds;
+    /**
+     * Opening-framing policy applied once after the initial floor fit.
+     *  - `initialPitch`: tilt to this and re-fit the building footprint so the
+     *    kiosk opens on a tilted building instead of a flat top-down plan.
+     *  - `minZoomBelowInitialFit`: clamp the map's minZoom to
+     *    `(fitZoom − margin)` so visitors can't pull back to the empty region.
+     * Both are no-ops when their option is unset.
+     */
+    private applyInitialFraming;
     private applyInitialViewFromVenue;
     private loadAndPatchVenueStyle;
     private ensureFloorLayersFromStyle;
@@ -296,5 +863,42 @@ declare class MinuteMaps {
 }
 declare function createMinuteMapsSDK(config: SDKConfig): MinuteMaps;
 
-export { MinuteMaps, createMinuteMapsSDK };
-export type { Amenity, AmenityWithFloor, Bounds, CameraState, Destination, EventCallback, Floor, FloorMetadata, JMapAuth, JMapConfig, JacsAuth, JacsConfig, MapEvent, POI, POISearchResult, SDKConfig, SDKOptions, ViewOptions, WayfindCenterMode, Waypoint };
+type TransitionStep = Extract<WayfindStep, {
+    type: 'transition';
+}>;
+type RouteFloorSection = {
+    /** Floor (JACS `mapId`) this section is on. `null` only for a degenerate
+     *  floorless route (straight-line fallback with no `mapId`). */
+    floorId: number | null;
+    /** This floor's steps, each with its index into the original flat array
+     *  so the consumer can call `setActiveStep` / highlight by index. */
+    steps: Array<{
+        step: WayfindStep;
+        index: number;
+    }>;
+    /** Index of this section's first step in the original array — the target
+     *  for `setActiveStep` when advancing INTO this section. */
+    firstStepIndex: number;
+    /** The transition step that leaves this floor for the next section, if
+     *  any. Absent on the final section. Its `text` ("Take the elevator to
+     *  Basement") makes a good "continue" button label. */
+    exit?: {
+        step: TransitionStep;
+        index: number;
+    };
+};
+/**
+ * Group steps into per-floor sections. Single-floor routes return one
+ * section (so a consumer can keep its whole-route view for that case).
+ */
+declare function groupStepsIntoFloorSections(steps: WayfindStep[]): RouteFloorSection[];
+/**
+ * Which section is "active" given the active step index — the last section
+ * whose `firstStepIndex` is at or before `activeStepIndex`. Returns 0 when
+ * nothing matches (e.g. index points at the leading transition, which
+ * shouldn't happen since routes start with a depart step).
+ */
+declare function activeSectionIndex(sections: RouteFloorSection[], activeStepIndex: number): number;
+
+export { MinuteMaps, activeSectionIndex, createMinuteMapsSDK, groupStepsIntoFloorSections };
+export type { Amenity, AmenityBadgeStyle, AmenityWithFloor, Bounds, BoundsPadding, CameraState, Destination, DestinationChipStyle, EventCallback, Floor, FloorMetadata, JMapAuth, JMapConfig, JacsAuth, JacsConfig, MapEvent, POI, POISearchResult, RouteFloorSection, RoutePoint, RoutingOptions, SDKConfig, SDKOptions, ThemeName, TransitionStep, ViewOptions, WayfindCenterMode, WayfindStep, Waypoint };