@minmaps-dev/mm-web-sdk 1.0.0-rc.4 → 1.0.0-rc.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { IControl, ControlPosition, Map } from 'maplibre-gl';
1
+ import { Map, IControl, ControlPosition, StyleSpecification } from 'maplibre-gl';
2
2
 
3
3
  /**
4
4
  * Represents a floor in a building
@@ -6,8 +6,18 @@ import { IControl, ControlPosition, Map } from 'maplibre-gl';
6
6
  interface Floor {
7
7
  /** Unique floor identifier */
8
8
  id: string | number;
9
+ /**
10
+ * Underlying map entity id. Separate from `id` (the floor entity id) — used
11
+ * by waypoints (`wp.mapId`) and floor-geojson endpoints. Optional because
12
+ * not all providers populate it.
13
+ */
14
+ mapId?: string | number;
9
15
  /** Display name of the floor */
10
16
  name: string;
17
+ /** Short display name of the floor (e.g. "L2"). Optional: JACS leaves it
18
+ * unset on plenty of floors, and `JacsDataProvider` maps a blank one to
19
+ * `undefined` rather than inventing a value. */
20
+ shortName?: string;
11
21
  /** Floor sequence/order (e.g., -1 for basement, 0 for ground, 1 for first floor) */
12
22
  sequence?: number;
13
23
  /** Associated map data */
@@ -23,6 +33,7 @@ interface Floor {
23
33
  interface FloorMetadata {
24
34
  id: string | number;
25
35
  name: string;
36
+ shortName?: string;
26
37
  sequence?: number;
27
38
  isDefault?: boolean;
28
39
  isActive?: boolean;
@@ -32,7 +43,7 @@ interface POI {
32
43
  /** Unique identifier */
33
44
  id: string | number;
34
45
  /** POI type */
35
- type: 'amenity' | 'destination';
46
+ type: 'amenity' | 'destination' | 'kiosk';
36
47
  /** Display name */
37
48
  name: string;
38
49
  /** Geographic coordinates [longitude, latitude] */
@@ -45,6 +56,17 @@ interface POI {
45
56
  floorId: string | number;
46
57
  /** Category/type of amenity (e.g., 'restroom', 'elevator') */
47
58
  amenityType?: string;
59
+ /** Locale-stable classification text (name + type + keywords, frozen at
60
+ * load before any locale patch can translate them). Copied from the
61
+ * source `Amenity.classifyText`; used by `amenityCategoryFor`/rank
62
+ * instead of the live, possibly-translated fields. See `Amenity.classifyText`. */
63
+ classifyText?: string;
64
+ /** Which amenity icon layer this POI renders in — `'connector'`,
65
+ * `'entrance'`, `'parking'`, `'bus'`, `'information'` or `'other'`.
66
+ * Derived from the amenity's connector flag, name, type and keywords;
67
+ * emitted as the `amenityCategory` feature property the theme filters on.
68
+ * Amenities only. See `amenityCategoryFor`. */
69
+ amenityCategory?: 'connector' | 'entrance' | 'parking' | 'bus' | 'information' | 'other';
48
70
  /** Search keywords */
49
71
  keywords?: string[];
50
72
  /** Additional properties */
@@ -55,6 +77,15 @@ interface POI {
55
77
  waypoint?: Waypoint;
56
78
  /** Marks this POI as the "You are here" kiosk */
57
79
  isYouAreHere?: boolean;
80
+ /** For kiosk POIs only: compass heading the device physically faces, in
81
+ * degrees clockwise from north. Sourced from JACS `Device.heading`. */
82
+ heading?: number | null;
83
+ /** Per-instance name for this specific placement of an amenity (e.g.
84
+ * "Parking Lot A" for a "Parking" amenity), resolved from the waypoint's
85
+ * `amenityAssociations`. Distinct from `name`, which is the amenity's
86
+ * type-level name shared by every instance — see `Amenity.name`. Amenities
87
+ * only, and only set when JACS actually returned an instance name. */
88
+ instanceName?: string;
58
89
  }
59
90
  /**
60
91
  * Amenity - a specific type of POI (facilities, services)
@@ -64,14 +95,42 @@ interface Amenity {
64
95
  id: string | number;
65
96
  /** Display name */
66
97
  name: string;
67
- /** SVG icon data */
98
+ /** Inline SVG markup (legacy fullcall DTO). When absent, icon is resolved from `uris`. */
68
99
  svg?: string;
100
+ /**
101
+ * Hosted icon descriptors from JACS (`uris[].locales[].uriPath`). Used by
102
+ * the SDK's runtime icon fetcher to register a map image at init time.
103
+ */
104
+ uris?: Array<{
105
+ mimeType?: string;
106
+ resourceType?: string;
107
+ locales?: Array<{
108
+ locale?: string;
109
+ uriPath?: string;
110
+ }>;
111
+ }>;
112
+ /**
113
+ * Map-image id used as `icon-image` in the POI style layer. Decorated
114
+ * in-place by AmenityIcons.register once the SVG is fetched and registered.
115
+ */
116
+ iconId?: string;
69
117
  /** Search keywords */
70
118
  keywords?: string[];
71
119
  /** Associated waypoints */
72
120
  waypoints?: Waypoint[];
73
121
  /** Amenity type/category */
74
122
  type?: string;
123
+ /**
124
+ * Locale-stable snapshot of `name + type + keywords`, captured once from
125
+ * the `/all` payload before `applyLocale` ever runs. `amenityCategoryFor`
126
+ * and the icon-rank heuristics in `poi.ts` match hard-coded English
127
+ * vocabulary against those fields; `name`/`keywords` are legitimately
128
+ * overwritten with translated text on a language switch
129
+ * (`LOCALIZED_FIELDS.amenity`), which reclassified every translated
130
+ * amenity to `'other'`/tier-3 and dropped its icon until the next zoom
131
+ * recomputed the rank gate. Classification reads this frozen copy instead.
132
+ */
133
+ classifyText?: string;
75
134
  /** Extended properties */
76
135
  extensors?: Record<string, unknown>;
77
136
  }
@@ -87,8 +146,34 @@ interface Destination {
87
146
  waypoints?: Waypoint[];
88
147
  /** Category/classification */
89
148
  category?: string;
149
+ /** Room number — the CMS's "Room Number" field. A **real JACS column**, not
150
+ * one of the `mm_` stand-in extensors, so it arrives on the entity rather
151
+ * than in `extensors`. Surfaced as `getPOIDetails().roomNumber`. */
152
+ unitNumber?: string | null;
153
+ /** Search keywords */
154
+ keywords?: string[];
90
155
  /** Additional properties */
91
156
  properties?: Record<string, unknown>;
157
+ /** The CMS "Location Image" — a photo or logo for the popover, not a map
158
+ * marker. JACS `/all` fullcall serves this as
159
+ * `{ items: [{ resourceType, mimeType, path }] }`; the legacy/basic shape is
160
+ * `[{ locales: [{ uriPath }] }]`. `destinationImageSrc` handles both, and
161
+ * surfaces the result on `sdk.getPOIDetails(poi).imageUrl`. */
162
+ uris?: unknown;
163
+ /** Inline SVG for the uploaded image, embedded by JACS `/all`. Preferred over
164
+ * fetching `uris[].path` — no network round-trip. */
165
+ svg?: string;
166
+ /** Free-form CMS metadata. */
167
+ extensors?: Record<string, unknown>;
168
+ /** @deprecated Read by nothing in the SDK as of rc.34.
169
+ *
170
+ * JACS still serves the old map-manager "Label Display" mode
171
+ * (`0` Hidden · `1` Label · `2` Image), but the CMS removed the picker and
172
+ * pins every write to `1`. Rows authored before that keep a stale `0`/`2`
173
+ * the author can no longer change, so honouring the field would hide labels
174
+ * with no way to bring them back. Destinations always render dot + text
175
+ * label; the uploaded image goes to the popover instead. */
176
+ displayMode?: number;
92
177
  }
93
178
  /**
94
179
  * Waypoint - a specific point location
@@ -102,6 +187,19 @@ interface Waypoint {
102
187
  floorId?: string | number;
103
188
  /** Whether this is the primary/default waypoint */
104
189
  isPrimary?: boolean;
190
+ /** CMS zone (department) this waypoint belongs to, if any. The only backend
191
+ * link between a location and its department — read at runtime across the
192
+ * data provider (see the package CLAUDE.md zone landmine). */
193
+ zoneId?: string | number;
194
+ /** Per-instance names JACS attaches to this waypoint's amenities (e.g. a
195
+ * "Parking" amenity placed twice as "Parking Lot A" / "Parking Lot B").
196
+ * `id` matches an `Amenity.id`, not this waypoint — a waypoint can carry
197
+ * more than one amenity, so a consumer must find the entry for the
198
+ * specific amenity it's rendering rather than assuming index 0. */
199
+ amenityAssociations?: Array<{
200
+ id: string | number;
201
+ name: string;
202
+ }>;
105
203
  }
106
204
  /**
107
205
  * Amenity enriched with the floor it belongs to
@@ -121,6 +219,23 @@ interface POISearchResult {
121
219
  matchedFields: string[];
122
220
  }
123
221
 
222
+ /**
223
+ * A Zone is a CMS-authored department category — a named, colored grouping
224
+ * (e.g. "Cardiology", "Surgical", "Admin"). Zones are venue-wide (not
225
+ * floor-scoped) in the JACS `/all` payload and carry no geometry of their own;
226
+ * their spatial footprint is derived from the waypoints that reference them
227
+ * (`waypoint.zoneId`), which lets the SDK color-code the room/unit polygons a
228
+ * zone covers. See `map/zones.ts` for the derivation.
229
+ */
230
+ interface Zone {
231
+ id: number;
232
+ name: string;
233
+ /** Authored hex color (e.g. "#d32f2f"); may be empty when the author
234
+ * hasn't picked one — such zones are skipped for color-coding. */
235
+ color: string;
236
+ description?: string;
237
+ }
238
+
124
239
  /** Captured camera state (center, zoom, pitch, bearing) */
125
240
  type CameraState = {
126
241
  center: [number, number];
@@ -140,25 +255,341 @@ type ViewOptions = {
140
255
  /** SW/NE bounding box */
141
256
  type Bounds = [[number, number], [number, number]];
142
257
 
258
+ /** How to center the map after computing a route */
259
+ type WayfindCenterMode = 'none' | 'destination' | 'route';
260
+ /**
261
+ * Per-call routing preferences forwarded to the wayfinding provider.
262
+ *
263
+ * - `avoidStairs` — hard-filter stairs from the graph. Accessibility
264
+ * preference otherwise comes from the CMS's per-path-type `weight`
265
+ * (elevators score low, stairs/escalators score high) — see
266
+ * `data/wayfinding/weights.ts` — not from a caller-supplied flag.
267
+ *
268
+ * The bundled stub provider doesn't compute routes; consumers wire a real
269
+ * provider (see `mm-web-sdk-example/lib/wayfinding`) that reads this
270
+ * flag when building edge weights.
271
+ */
272
+ type RoutingOptions = {
273
+ avoidStairs?: boolean;
274
+ };
275
+
276
+ /**
277
+ * A single point along the rendered route. `mapId` lets the renderer
278
+ * split the polyline by floor (so other-floor segments don't paint
279
+ * through the visible floor's geometry); `waypointId` and `pathTypeId`
280
+ * let downstream layers (text-directions, step UI) classify
281
+ * transitions — e.g. "Take the elevator" vs "Walk straight". The two
282
+ * endpoint points are the kiosk and destination anchors (`isEndpoint`
283
+ * marks them so they can render endpoint pins). All fields except
284
+ * `coordinates` are optional for backward-compat with the straight-line
285
+ * fallback.
286
+ */
287
+ type RoutePoint = {
288
+ coordinates: [number, number];
289
+ /** Floor mapId this point sits on. Missing on the straight-line fallback. */
290
+ mapId?: number;
291
+ /** JACS waypoint id this point resolved to, if any. */
292
+ waypointId?: number;
293
+ /** Path type of the edge that LEADS INTO this point (i.e. the edge
294
+ * whose `toKey` is this node). Used to detect elevator / stair /
295
+ * escalator transitions. Missing on the start point and on the
296
+ * straight-line fallback. */
297
+ pathTypeId?: number;
298
+ /** True for the snapped kiosk + destination anchors. */
299
+ isEndpoint?: boolean;
300
+ };
301
+
302
+ type WayfindStep = DepartStep | TurnStep | ContinueStep | TransitionStep$1 | ArriveStep;
303
+ type StepBase = {
304
+ /** Indices into the input `points` array that this step spans. */
305
+ pointRange: [startInclusive: number, endInclusive: number];
306
+ /** Floor this step is on. `null` for cross-floor transitions. */
307
+ floorId: number | null;
308
+ /** Localized instruction text. */
309
+ text: string;
310
+ /** Total walking distance within this step, in feet (rounded). */
311
+ distanceFeet?: number;
312
+ /** Landmark name used for anchoring, if any. */
313
+ landmark?: string;
314
+ };
315
+ type DepartStep = StepBase & {
316
+ type: 'depart';
317
+ /** Which way the traveller turns before walking off, relative to the
318
+ * way they're facing at the origin. Absent when `originFacingBearing`
319
+ * wasn't supplied (direction unknowable) or when the route heads
320
+ * straight ahead. Consumers use it to pick the step's icon. */
321
+ initialTurn?: 'left' | 'right' | 'around';
322
+ };
323
+ type TurnStep = StepBase & {
324
+ type: 'turn-left' | 'turn-right' | 'u-turn';
325
+ };
326
+ type ContinueStep = StepBase & {
327
+ type: 'continue';
328
+ };
329
+ type TransitionStep$1 = StepBase & {
330
+ type: 'transition';
331
+ transition: 'elevator' | 'stairs' | 'escalator';
332
+ fromFloorId: number | null;
333
+ toFloorId: number | null;
334
+ };
335
+ type ArriveStep = StepBase & {
336
+ type: 'arrive';
337
+ };
338
+
143
339
  interface MapEvent {
144
340
  floor?: Floor;
145
341
  poi?: POI;
342
+ /** All POIs co-located at a clicked point (overlapping pins / a shared
343
+ * suite). Emitted by `poiSelected`; length ≥ 1, and `poi` mirrors
344
+ * `pois[0]` for single-POI consumers. */
345
+ pois?: POI[];
146
346
  coordinates?: [number, number];
147
347
  error?: any;
148
348
  venue?: any;
149
349
  camera?: CameraState;
350
+ /** Emitted by `themeChanged`; `'custom'` when consumer passed a raw style. */
351
+ theme?: 'default' | 'high-contrast' | 'custom';
352
+ /** Emitted by `localeChanged` after `setLocale()` finishes patching the
353
+ * venue model. BCP-47 code (`'en'`, `'es'`, `'es-MX'`). */
354
+ locale?: string;
355
+ /** Emitted by `routeReady` after a successful `navigateFromKioskToPOI`.
356
+ * Carries the raw geometry (`points`) and the human-readable
357
+ * step-by-step directions. Subscribe to drive a turn-by-turn UI. */
358
+ route?: {
359
+ points: RoutePoint[];
360
+ steps: WayfindStep[];
361
+ /** Floor mapId of each segment, in render order. `null` for
362
+ * segments emitted by the straight-line fallback. */
363
+ floorIds: Array<number | null>;
364
+ };
150
365
  }
151
366
  type EventCallback = (event: MapEvent) => void;
152
367
 
368
+ /**
369
+ * Padding kept clear inside the viewport when the SDK frames bounds —
370
+ * the initial venue/floor fit and the wayfinding route fit. A plain
371
+ * number pads all sides equally; the object form lets a kiosk reserve
372
+ * space for fixed UI overlays (header, dock, side rails) so framed
373
+ * content is never hidden behind them.
374
+ */
375
+ type BoundsPadding = number | {
376
+ top: number;
377
+ bottom: number;
378
+ left: number;
379
+ right: number;
380
+ };
381
+ /**
382
+ * Built-in theme names accepted by `MinuteMaps.setTheme()` and the
383
+ * `options.theme` init option. Pass a `StyleSpecification` directly for
384
+ * custom themes.
385
+ */
386
+ type ThemeName = 'default' | 'high-contrast';
387
+ /**
388
+ * Style of the disc + ring rendered behind each amenity icon. The SDK
389
+ * composites this into the icon bitmap at registration time, so badge +
390
+ * icon participate in symbol collision as one unit.
391
+ */
392
+ type AmenityBadgeStyle = {
393
+ /** Fill colour of the badge disc. Default `'#fdb81e'`. */
394
+ color?: string;
395
+ /** Stroke colour of the ring around the disc. Default `'#FFFFFF'`. */
396
+ ringColor?: string;
397
+ /** Ring width in logical px. Default `2`. */
398
+ ringWidth?: number;
399
+ /** Extra inset between the icon and the badge's inner edge, in logical px
400
+ * (applied on all sides). Default `0` — the icon fills ~85% of the disc
401
+ * as before. Raise this if an icon's own artwork reaches close to its
402
+ * viewBox edges and ends up touching the ring. */
403
+ padding?: number;
404
+ };
153
405
  interface SDKOptions {
154
406
  debug?: boolean;
155
- theme?: 'light' | 'dark' | 'hybrid' | any;
407
+ /**
408
+ * `window` key the SDK instance is published under while `debug` is on, so
409
+ * a running kiosk can be driven from devtools (`mm.debug.hide('labels')`,
410
+ * `mm.getMap()`). Defaults to `'mm'`. Pass another name to avoid a clash,
411
+ * or `false` to publish nothing even in debug mode. Ignored entirely when
412
+ * `debug` is off.
413
+ */
414
+ debugGlobal?: string | false;
415
+ /**
416
+ * Initial theme. `'default'` uses the bundled hybrid 3D theme.
417
+ * `'high-contrast'` uses the WCAG-AA tuned theme. Pass a
418
+ * `StyleSpecification` for fully custom styling.
419
+ */
420
+ theme?: ThemeName | any;
421
+ /**
422
+ * When true, the SDK skips animations on imperative camera calls
423
+ * (wayfinding fits, `setView`, idle re-frames). Consumers should
424
+ * mirror their app's `prefers-reduced-motion` state into this.
425
+ */
426
+ reducedMotion?: boolean;
427
+ /**
428
+ * Whether a freshly computed route auto-highlights its first step's
429
+ * segment (the brighter `route-line-active` overlay). Defaults to
430
+ * `true`, preserving the turn-by-turn segment highlight that
431
+ * `setActiveStep` drives.
432
+ *
433
+ * Set `false` for kiosk-style "show the whole route at once" UIs:
434
+ * the entire route line is shown without singling out one segment,
435
+ * which reads more clearly at a glance and avoids implying the visitor
436
+ * must step through the route. `setActiveStep` still works when called
437
+ * explicitly (e.g. a paginated QR-handoff / mobile flow) — this only
438
+ * controls the automatic highlight on `routeReady`.
439
+ */
440
+ routeStepHighlight?: boolean;
441
+ /**
442
+ * Whether restroom pins that are too close together to draw individually
443
+ * collapse into a single Material `wc` badge. Defaults to `true`.
444
+ *
445
+ * Venues author men's and women's restrooms as two amenities a few metres
446
+ * apart. Both are wayfinding-critical (rank 0) and both draw on a layer that
447
+ * doesn't allow icon overlap, so without this MapLibre resolves the collision
448
+ * by hiding one of them outright until the camera is very close in. Grouping
449
+ * shows one badge in their place and hands back *all* the members when it's
450
+ * tapped, so the consumer can offer directions to each.
451
+ *
452
+ * Set `false` to opt out and get the raw collision behaviour back.
453
+ */
454
+ groupRestroomIcons?: boolean;
156
455
  initialFloor?: string | number;
157
456
  enableInteractions?: boolean;
158
457
  customSprite?: string;
159
458
  minIndoorZoom?: number;
459
+ /**
460
+ * How far, in **metres** (default `0.3`, ≈1 ft), extruded interior polygons
461
+ * (restrooms, back-of-house, obstacles, connectors) are inset so their edges
462
+ * don't z-fight the neighbouring room block. A polygon too thin to survive
463
+ * the inset (it would keep under half its area, e.g. a ~0.3 m back-of-house
464
+ * perimeter band) is left at its original size rather than erased. Metres to match the theme's
465
+ * `fill-extrusion-height` values, which MapLibre defines in metres — unlike
466
+ * the distances shown to visitors, which are in feet. Was feet before this
467
+ * option changed units; a value of `1` is now ~3.3× thicker.
468
+ */
160
469
  wallThickness?: number;
161
- boundsPadding?: number;
470
+ /**
471
+ * How much costlier a candidate on a **different floor** from the kiosk is
472
+ * treated when choosing the closest instance of an amenity (default `1.5`).
473
+ * Used by `findClosestByWalkTime`, and so by `navigateFromKioskToClosestAmenity`
474
+ * and `highlightAmenity`.
475
+ *
476
+ * A multiplier on the trip's effort — walk time plus the elevator wait — not
477
+ * a distance: `1.5` means another floor's instance has to be a third cheaper
478
+ * to beat one on the kiosk's floor. It is a *preference* for not making the
479
+ * visitor change floors, layered on top of the physical cost of doing so
480
+ * (which is already in the effort). `1` turns it off and ranks by effort
481
+ * alone; a value below `1` is treated as `1`. It only affects which instance
482
+ * is chosen — never a route.
483
+ *
484
+ * For scale: at the Las Vegas VA the nearest other-floor Lactation Pod costs
485
+ * ~400 ft-equivalent against ~530 for the one on the kiosk's floor, so it
486
+ * takes a value above ~1.32 to keep the visitor on their floor.
487
+ */
488
+ otherFloorPenalty?: number;
489
+ boundsPadding?: BoundsPadding;
490
+ /**
491
+ * Caps how far a visitor can pan/zoom out. By default the SDK derives this
492
+ * from the venue's own bounds, scaled to 3x its width/height around the
493
+ * same center — enough room to pan around the building without drifting
494
+ * into an empty, un-tiled region. The default box is never smaller than
495
+ * ~3.7 km a side, so a small venue isn't forced to zoom in tighter than a
496
+ * large one. Pass a number to use a different
497
+ * multiplier (e.g. `1.5` for a tighter leash), explicit `[[west, south],
498
+ * [east, north]]` bounds to override entirely, or `false` to disable
499
+ * max-bounds clamping.
500
+ */
501
+ maxBounds?: Bounds | number | false;
502
+ /**
503
+ * Pitch (deg) for the opening view, applied centred on the kiosk ("You
504
+ * are here"). Omit for top-down.
505
+ */
506
+ initialPitch?: number;
507
+ /**
508
+ * Zoom for the opening view, centred on the kiosk. Set this above the
509
+ * theme's unit-walls breakpoint (~16.5 in the bundled hybrid theme) so the
510
+ * kiosk opens on the building's interior floor plan (its contents) rather
511
+ * than a zoomed-out 3D massing outline. Omit to keep the post-floor-fit
512
+ * zoom.
513
+ */
514
+ initialZoom?: number;
515
+ /**
516
+ * Clamp zoom-out relative to the opening view. When set, the map's
517
+ * `minZoom` becomes `(initialZoom − this)`, so visitors can nudge out by
518
+ * this many zoom levels but never pull back below the interior into the
519
+ * massing/region. `0` locks zoom-out exactly to the opening view.
520
+ */
521
+ minZoomBelowInitialFit?: number;
522
+ /**
523
+ * Zoom-out floor expressed as ground scale: the most metres one CSS pixel
524
+ * may span. The SDK converts it to a `minZoom` at the venue's latitude, so
525
+ * every venue shows the same amount of surrounding map when fully zoomed
526
+ * out — a plain zoom number doesn't, because Web Mercator shows less ground
527
+ * per zoom level the further a venue is from the equator. Takes precedence
528
+ * over `minZoomBelowInitialFit`. For scale, `1.207` is zoom 15.8 at Orlando
529
+ * (about 2.3 km x 1.3 km on a 1920x1080 screen).
530
+ */
531
+ minZoomMetersPerPixel?: number;
532
+ /**
533
+ * Override the colour the SDK recolours every amenity SVG to before it
534
+ * composites the badge. `none` / `transparent` fills are preserved so
535
+ * cut-outs stay. When the badge is enabled (the default), this defaults
536
+ * to navy (`#162e51`) so icons read on gold. Set explicitly for a
537
+ * different look, or set `amenityBadge: false` to disable recolouring
538
+ * altogether and keep the CMS-uploaded colours.
539
+ */
540
+ amenityIconColor?: string;
541
+ /**
542
+ * Badge composited behind each amenity icon. Pass `false` to render the
543
+ * icon alone (no badge — useful for high-contrast or 2D themes where the
544
+ * gold disc would compete with the floor). Pass an object to tune the
545
+ * disc / ring style. Defaults to a VA-gold disc with a 2px white ring.
546
+ *
547
+ * The badge is baked into the icon bitmap (canvas composite) rather than
548
+ * drawn as a separate circle layer, so badge + icon participate in symbol
549
+ * collision together — overlapping amenities hide as one unit instead of
550
+ * the icon hiding while the disc stays painted.
551
+ */
552
+ amenityBadge?: AmenityBadgeStyle | false;
553
+ /**
554
+ * Badge for vertical-circulation connectors (elevator / stairs / escalator).
555
+ * These render as their own visual class — a navy disc with a white glyph —
556
+ * so circulation reads distinct from the gold service amenities. Pass `false`
557
+ * to fall them back into the regular gold badge, or an object to tune the
558
+ * disc / ring. When `amenityBadge` is `false`, connectors are badge-less too
559
+ * unless this is set explicitly.
560
+ */
561
+ connectorBadge?: AmenityBadgeStyle | false;
562
+ /**
563
+ * Badge for information-desk amenities (curated `information`/`info`
564
+ * icon). These render as their own visual class — a green disc with a
565
+ * white glyph by default — so information reads distinct from the gold
566
+ * service amenities. Pass `false` to fall them back into the regular gold
567
+ * badge, or an object to tune the disc / ring. When `amenityBadge` is
568
+ * `false`, information icons are badge-less too unless this is set
569
+ * explicitly.
570
+ */
571
+ informationBadge?: AmenityBadgeStyle | false;
572
+ /**
573
+ * Glyph colour for information icons on their badge. Default white
574
+ * (matches `informationBadge`'s default green disc).
575
+ */
576
+ informationIconColor?: string;
577
+ /**
578
+ * Badge for the end-of-route flag (`poi-route-end-flag`) shown in place of a
579
+ * destination's dot while a route to it is displayed. Has its own defaults
580
+ * (green disc, white ring) that don't follow `amenityBadge`. Pass an object
581
+ * to tune the disc / ring, or `false` for the bare flag glyph with no badge.
582
+ * When `amenityBadge` is `false`, the flag is badge-less too unless this is
583
+ * set explicitly. Under the high-contrast theme the disc colour is forced to
584
+ * the high-contrast amenity yellow, like the amenity and connector badges.
585
+ */
586
+ routeEndBadge?: AmenityBadgeStyle | false;
587
+ /**
588
+ * Flag glyph colour on the end-of-route badge. Default white (contrasts the
589
+ * default green disc); doesn't follow `amenityIconColor`. Ignored under the
590
+ * high-contrast theme, which forces its own glyph colour.
591
+ */
592
+ routeEndIconColor?: string;
162
593
  styleMode?: 'venueStyleUrl' | 'sdkTemplate';
163
594
  templateOverrideMode?: 'colorsOnly' | 'colorsAndConstants' | 'all';
164
595
  }
@@ -190,6 +621,13 @@ type SDKConfig = {
190
621
  venueId: number;
191
622
  locale?: string;
192
623
  auth?: JMapAuth;
624
+ /**
625
+ * Identifies which physical kiosk this instance is, so the SDK can pin
626
+ * the "You are here" marker. Matched against either the numeric device
627
+ * `id` or the device `uuid` from the venue's `devices`. The device's
628
+ * attached waypoint (`waypoint.deviceIds`) is the kiosk's location.
629
+ */
630
+ deviceId?: string | number;
193
631
  };
194
632
  jacs: {
195
633
  mode: 'proxy' | 'direct';
@@ -204,8 +642,229 @@ type SDKConfig = {
204
642
  options?: SDKOptions;
205
643
  };
206
644
 
207
- /** How to center the map after computing a route */
208
- type WayfindCenterMode = 'none' | 'destination' | 'route';
645
+ type Visibility = 'visible' | 'none';
646
+ type DebugLayersDeps = {
647
+ getMap: () => Map | null;
648
+ /**
649
+ * Re-assert the visibility the SDK itself owns — floor layers, the POI
650
+ * category filter, the 2D/3D view mode. Called at the end of `reset()`,
651
+ * because restoring a captured `visibility` can't distinguish "the theme
652
+ * ships this visible" from "the SDK hid it because it belongs to another
653
+ * floor", and the naive restore would reveal every floor at once.
654
+ */
655
+ reapplySdkState?: () => void;
656
+ log?: (...args: unknown[]) => void;
657
+ };
658
+ type LayerRow = {
659
+ id: string;
660
+ type: string;
661
+ visibility: Visibility;
662
+ /**
663
+ * What this layer's visibility was before we touched it — i.e. what the
664
+ * theme and the SDK want it to be. Equal to `visibility` for any layer we
665
+ * hold no override on. A UI wanting to show "is this group on" should judge
666
+ * only the layers whose `base` is `'visible'`: the rest (the 3D extrusions
667
+ * in flat mode, the 2D outlines outside it) aren't rendering by design, so
668
+ * counting them makes a healthy group look half-off.
669
+ */
670
+ base: Visibility;
671
+ };
672
+ /**
673
+ * Console-facing layer inspector for demos, screenshots and debugging.
674
+ *
675
+ * Reachable as `sdk.debug`, and as `window.mm.debug` when
676
+ * `options.debug` is on (see `options.debugGlobal`).
677
+ *
678
+ * Two things make it more than a wrapper around `setLayoutProperty`:
679
+ *
680
+ * 1. **Selectors.** `hide('amenities')`, `hide('route-')`, `hide('/^poi-/')`
681
+ * and `hide('type:fill-extrusion')` all work, so you don't have to know
682
+ * the theme's layer ids to start poking at it.
683
+ * 2. **Overrides are sticky.** The SDK re-asserts layer visibility on floor
684
+ * changes, `setPOIFilter`, flat-mode toggles and theme swaps — all of which
685
+ * would otherwise wipe a manual toggle mid-demo. Every override is re-applied
686
+ * on `styledata`, so what you hid stays hidden until `reset()`.
687
+ */
688
+ declare class DebugLayers {
689
+ private deps;
690
+ /** layer id → visibility this API is asserting. */
691
+ private overrides;
692
+ /** layer id → visibility before we first touched it. */
693
+ private originals;
694
+ /** `${layer}|${prop}` → paint value before we first touched it. */
695
+ private paintOriginals;
696
+ private sticky;
697
+ private attachedTo;
698
+ /** Re-entrancy guard: our own `setLayoutProperty` fires `styledata`. */
699
+ private applying;
700
+ private readonly onStyleData;
701
+ constructor(deps: DebugLayersDeps);
702
+ /** Begin re-asserting overrides across style/floor changes. */
703
+ attach(map: Map): void;
704
+ detach(): void;
705
+ /**
706
+ * Every layer in the active style, newest-on-top last, with its current
707
+ * visibility. Pass a selector to narrow it (same grammar as `hide`).
708
+ */
709
+ list(selector?: string): LayerRow[];
710
+ /** Just the ids currently rendering — the quickest "what am I looking at". */
711
+ visible(): string[];
712
+ /** Group name → the ids it resolves to *in the active style*. */
713
+ groups(): Record<string, string[]>;
714
+ /** Hide every layer the selectors resolve to. Returns the ids affected. */
715
+ hide(...selectors: string[]): string[];
716
+ /**
717
+ * **Force** every resolved layer visible — including ones the SDK
718
+ * deliberately keeps off: the 3D extrusions while flat mode is on, the 2D
719
+ * outlines while it isn't, every floor but the active one. Forcing those
720
+ * renders two representations of the same geometry at once, or every floor
721
+ * stacked, and the map looks wrong.
722
+ *
723
+ * So this is *not* the way to undo a `hide()` — use `restore()`, which puts
724
+ * each layer back to what it was rather than blanket-revealing the group.
725
+ * Reach for `show()` only when you actually mean "reveal this regardless".
726
+ */
727
+ show(...selectors: string[]): string[];
728
+ /**
729
+ * Undo our overrides on these layers: each goes back to the visibility it
730
+ * had before we first touched it, and control returns to the SDK (floor
731
+ * layers, POI filter, view mode re-assert afterwards).
732
+ *
733
+ * This is the correct inverse of `hide()`. A group is rarely uniformly
734
+ * visible to begin with — `rooms` hides either the 2D outline or the 3D
735
+ * extrusion depending on view mode, and every floor layer but the active
736
+ * one is off — so `hide()` then `show()` does not round-trip, but `hide()`
737
+ * then `restore()` does.
738
+ *
739
+ * Returns the ids that actually had an override; layers we never touched
740
+ * are left alone.
741
+ */
742
+ restore(...selectors: string[]): string[];
743
+ /** Flip each resolved layer independently. Returns the ids affected. */
744
+ toggle(...selectors: string[]): string[];
745
+ /**
746
+ * Show only what the selectors resolve to — everything else is hidden
747
+ * (except `background`, which is just the canvas colour). The one-liner for
748
+ * "which layer is drawing that thing".
749
+ *
750
+ * The kept set is *restored*, not forced: anything we'd previously hidden
751
+ * comes back, but a layer the theme ships hidden stays hidden. Soloing must
752
+ * not invent geometry that never renders normally — see `show()`.
753
+ */
754
+ solo(...selectors: string[]): string[];
755
+ /**
756
+ * Set a paint property — `paint('units-fill', 'fill-color', '#f00')`. The
757
+ * original value is captured so `reset()` puts it back. Not sticky: unlike
758
+ * visibility, a theme swap rebuilds paint from the new style and re-applying
759
+ * a captured expression across themes is exactly the bug `setTheme` had to
760
+ * fix. Re-run it after a swap if you need it back.
761
+ */
762
+ paint(selector: string, prop: string, value: unknown): string[];
763
+ /**
764
+ * Drop every override and paint change, then let the SDK re-assert the
765
+ * visibility it owns (floor layers, POI filter, view mode). Back to the map
766
+ * you'd have had without touching anything.
767
+ */
768
+ reset(): void;
769
+ /**
770
+ * Hand the layers we just released back to the SDK, then re-assert whatever
771
+ * overrides are still standing.
772
+ *
773
+ * The second half is not belt-and-braces. The SDK's re-assert passes are
774
+ * all-or-nothing: with no POI filter active, `applyPOIFilter` writes
775
+ * `visible` to *every* POI category layer, and the floor / view-mode passes
776
+ * sweep their whole layer sets the same way. So releasing one group would
777
+ * un-hide every other group you'd hidden — hide labels, destinations and
778
+ * amenities, re-check one, and all three came back.
779
+ *
780
+ * Doing it here rather than waiting for the `styledata` the SDK's writes
781
+ * trigger also keeps it synchronous: MapLibre fires that on a later frame,
782
+ * so a UI reading visibility straight after this call would otherwise see —
783
+ * and render — the clobbered state.
784
+ */
785
+ private handBackToSdk;
786
+ /**
787
+ * The current override set as a plain object — save it, paste it back with
788
+ * `apply()` to reproduce the exact same framing for a screenshot later.
789
+ */
790
+ snapshot(): Record<string, Visibility>;
791
+ /** Apply a `snapshot()` (or any layer-id → visibility map). */
792
+ apply(snapshot: Record<string, Visibility>): string[];
793
+ /**
794
+ * Stop (or resume) re-asserting overrides when the style changes. Turn it
795
+ * off if you want a floor switch or `setPOIFilter` to win over what you
796
+ * toggled by hand.
797
+ */
798
+ setSticky(enabled: boolean): boolean;
799
+ /** Console cheat sheet. */
800
+ help(): Array<{
801
+ call: string;
802
+ does: string;
803
+ }>;
804
+ /**
805
+ * Resolve one selector to layer ids present in the active style, tried in
806
+ * order: group name → exact layer id → `type:<layer type>` → `/regex/` →
807
+ * case-insensitive substring on the id.
808
+ */
809
+ resolve(selector: string): string[];
810
+ private resolveAll;
811
+ private set;
812
+ /**
813
+ * Put these layers back to their pre-override visibility and forget them.
814
+ * Callers decide whether to follow up with `reapplySdkState` — `restore()`
815
+ * and `reset()` do, `solo()` deliberately doesn't.
816
+ */
817
+ private restoreVisibility;
818
+ /** Write one layer's visibility and remember it as an override. */
819
+ private write;
820
+ /**
821
+ * Re-assert overrides after something else rewrote layer visibility. Only
822
+ * writes when the current value actually differs, so this doesn't feed
823
+ * itself through the `styledata` it triggers.
824
+ */
825
+ private reapply;
826
+ private styleLayers;
827
+ private visibilityOf;
828
+ /**
829
+ * MapLibre throws from these getters/setters while a style is mid-swap (the
830
+ * layer exists in `getStyle()` but its owner is being replaced). A debug tool
831
+ * that can break the map it's inspecting is worse than useless.
832
+ */
833
+ private safe;
834
+ }
835
+
836
+ type LayerAudit = {
837
+ /** `featureType` values the CMS permits for this customer. */
838
+ allowed: string[];
839
+ /** `featureType` values actually present in the loaded floors. */
840
+ inData: string[];
841
+ /** `featureType` values some theme layer filters on. */
842
+ inStyle: string[];
843
+ /**
844
+ * Drawn on a map but not in the customer's allowed list — a mis-authored
845
+ * or renamed layer. These render only by accident (if the theme happens to
846
+ * match the string) and are invisible otherwise.
847
+ */
848
+ unauthorized: string[];
849
+ /**
850
+ * Present in the data and allowed, but no theme layer filters on it. The
851
+ * author drew something the map will never show.
852
+ */
853
+ unstyled: string[];
854
+ /**
855
+ * The theme filters on it, but no loaded floor contains it. Dead weight in
856
+ * the style *for this venue* — another venue may well use it, so this is a
857
+ * prompt to check, not a delete list. Cross-reference `allowed`: a value
858
+ * that isn't in there either is dead everywhere for this customer.
859
+ */
860
+ unused: string[];
861
+ /**
862
+ * Allowed by the CMS but no theme rule matches it, whether or not this
863
+ * venue happens to draw it. The SDK's total blind spot — an author can
864
+ * legitimately draw any of these and get nothing.
865
+ */
866
+ allowedNotStyled: string[];
867
+ };
209
868
 
210
869
  type LoggerFn = (...args: unknown[]) => void;
211
870
  type AmenityManagerDeps = {
@@ -224,41 +883,535 @@ declare class AmenityManager {
224
883
  private log;
225
884
  private loadForFloor;
226
885
  getAll(): AmenityWithFloor[];
886
+ /**
887
+ * Venue-wide amenities, one entry per id. `getAll()` returns each amenity
888
+ * once per floor it appears on (and so renders a multi-floor "Bathroom"
889
+ * three times in a venue list); this collapses those into a single record
890
+ * with all its waypoints merged across floors.
891
+ *
892
+ * Also folds any duplicate-id records from the provider into a single entry
893
+ * so React lists don't trip on dup keys. This used to say those duplicates
894
+ * were "a CMS data bug" — they weren't. JACS returns one record per amenity;
895
+ * the SDK's own floor index pushed it once per waypoint, so an amenity with
896
+ * four placements on a floor came back four times. Fixed at the source in
897
+ * `jacsDataProvider.floorIdsForWaypoints`; the fold stays as a cheap guard
898
+ * for a provider that genuinely repeats an id.
899
+ *
900
+ * Use this for venue-wide browse UIs; pair it with `findClosestWaypoint`
901
+ * (on the SDK) to resolve a tap to the nearest physical instance.
902
+ */
903
+ getDistinct(): Amenity[];
227
904
  getByFloorId(floorId: Floor['id']): AmenityWithFloor[];
228
905
  getAllKiosks(): AmenityWithFloor[];
229
906
  getKioskForFloor(floorId: Floor['id']): AmenityWithFloor | null;
230
907
  logKioskForFloor(floorId: Floor['id']): void;
231
908
  }
232
909
 
910
+ /**
911
+ * The `mm_`-prefixed extensor keys the CMS reserves for fields JACS has no
912
+ * column for yet.
913
+ *
914
+ * This file is the read half of a cross-repo table: the write half is
915
+ * `cms/packages/map-manager/app/utils/reserved-extensors.js`, which owns the key
916
+ * names, the value encodings, and the rule that a default value is deleted
917
+ * rather than stored. Change them together.
918
+ *
919
+ * The `mm_` prefix is load-bearing on both sides. Authors can type anything into
920
+ * the CMS's free-form Properties editor, so an unprefixed key like
921
+ * `point_of_interest` could collide with a hand-entered one; the prefix also
922
+ * makes "is this key reserved?" a prefix scan rather than a hand-maintained list
923
+ * once JACS grows real columns and these are migrated away.
924
+ *
925
+ * Two things that look like they belong here and don't:
926
+ *
927
+ * - **Room number.** The CMS labels it "Room Number", but it writes the real
928
+ * `Destination.unitNumber` field, not an extensor. `getPOIDetails().roomNumber`
929
+ * reads that field (see `sdk.ts`).
930
+ * - **`mm_point_of_interest`.** Registered by the CMS and parsed here for
931
+ * completeness, but deliberately not surfaced on `getPOIDetails` — nothing has
932
+ * pinned down whether an unflagged destination should drop out of search, out
933
+ * of the map, or neither, and guessing wrong is worse than omitting it.
934
+ */
935
+ declare const RESERVED_EXTENSOR_PREFIX = "mm_";
936
+ /** Weekly opening hours. Value shape and parser live in `openHours.ts`. */
937
+ declare const OPEN_HOURS_EXTENSOR_KEY = "mm_open_hours";
938
+ /** Phone number, with the extension folded into the same value. */
939
+ declare const PHONE_EXTENSOR_KEY = "mm_phone";
940
+ /** Alt text for the destination's uploaded Location Image. */
941
+ declare const IMAGE_ALT_EXTENSOR_KEY = "mm_image_alt";
942
+ /** Author-set "this is a point of interest" flag. Parsed, not surfaced. */
943
+ declare const POINT_OF_INTEREST_EXTENSOR_KEY = "mm_point_of_interest";
944
+ /**
945
+ * Which building on the campus the destination stands in.
946
+ *
947
+ * The venue's own `Building` record can't answer this: the CMS binds a venue to
948
+ * a single building and hangs the floor list off it, so a campus with a dozen
949
+ * numbered buildings has one `Building` and no way to say which one a room is
950
+ * in. The author types it as free text, and that text is what a kiosk prints —
951
+ * it is not a reference to anything, so don't try to resolve it against
952
+ * `venue.buildings`.
953
+ */
954
+ declare const BUILDING_NAME_EXTENSOR_KEY = "mm_building_name";
955
+ interface DestinationPhone {
956
+ /** Exactly as the author typed it — `"(408) 300-9294"`. Deliberately not
957
+ * normalised: doing that properly across international formats needs a real
958
+ * phone library, and the CMS makes the same choice on the way in. */
959
+ number: string;
960
+ /** Internal extension digits, when there is one. */
961
+ ext?: string;
962
+ }
963
+ /**
964
+ * `"(408) 300-9294;ext=123"` → `{ number, ext }`. `null` when there's no number
965
+ * — including for the empty string, which is how JACS spells a deleted key.
966
+ */
967
+ declare function parsePhone(raw: unknown): DestinationPhone | null;
968
+ /** Alt text for the Location Image, or `undefined` when the author set none. */
969
+ declare function parseImageAlt(raw: unknown): string | undefined;
970
+ /** The building name, or `undefined` when the author set none. */
971
+ declare function parseBuildingName(raw: unknown): string | undefined;
972
+ /** The point-of-interest flag. Absence means false — only the checked state is
973
+ * ever stored. */
974
+ declare function parsePointOfInterest(raw: unknown): boolean;
975
+
976
+ /**
977
+ * Weekly opening hours for a destination.
978
+ *
979
+ * JACS has no hours column, so the CMS ships the whole week in a single
980
+ * destination extensor — key `mm_open_hours`, value a JSON string:
981
+ *
982
+ * {"v":1,"days":{"mon":[["09:00","17:30"]],"sat":[],"sun":[["00:00","24:00"]]}}
983
+ *
984
+ * - Times are 24-hour `"HH:MM"` and **venue-local**; no timezone is recorded.
985
+ * - Each day maps to an array of `[open, close]` ranges. The editor exposes one
986
+ * range per day today, but the array shape leaves room for split shifts (a
987
+ * cafeteria that closes over the afternoon) and extra ranges round-trip.
988
+ * - An empty array — or a missing day — means closed.
989
+ * - `[["00:00","24:00"]]` means open 24 hours.
990
+ *
991
+ * This module owns the read half: parse the value (`parseOpenHours`) and derive
992
+ * the live open/closed state from it (`getOpenStatus`). The write half lives in
993
+ * the CMS (`map-manager`'s `utils/open-hours.js`) — the two must agree on the
994
+ * wire shape above, so change them together. The key itself is registered in
995
+ * `reservedExtensors.ts` alongside the CMS's other stand-in fields, mirroring
996
+ * the same split on the authoring side.
997
+ */
998
+
999
+ /** Wire-format version this module understands. */
1000
+ declare const OPEN_HOURS_VERSION = 1;
1001
+ type DayKey = 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun';
1002
+ /** Monday-first, matching the wire format's own day order. `getOpenStatus`
1003
+ * reports `OpenHoursTransition.day` as one of these. */
1004
+ declare const DAY_KEYS: readonly DayKey[];
1005
+ /** One open→close stretch within a single day. 24-hour `"HH:MM"`, venue-local.
1006
+ * `close` may be `"24:00"` (end of day); `open` never is. */
1007
+ interface HoursRange {
1008
+ open: string;
1009
+ close: string;
1010
+ }
1011
+ /** A parsed week. Every day is present; a closed day is an empty array. */
1012
+ interface OpenHours {
1013
+ days: Record<DayKey, HoursRange[]>;
1014
+ /** Open every minute of the week (a 24/7 emergency department, say). The
1015
+ * status has no `closesAt` in this case — there is nothing to count down to. */
1016
+ alwaysOpen: boolean;
1017
+ }
1018
+ /** A point in the week the status is counting toward. */
1019
+ interface OpenHoursTransition {
1020
+ /** Day the transition falls on, venue-local. */
1021
+ day: DayKey;
1022
+ /** 24-hour `"HH:MM"`, venue-local. Midnight is always `"00:00"` on the
1023
+ * following day — `"24:00"` never surfaces here. */
1024
+ time: string;
1025
+ /** Whole minutes from `now`. */
1026
+ minutesUntil: number;
1027
+ /** Calendar days ahead: `0` today, `1` tomorrow. */
1028
+ daysAhead: number;
1029
+ }
1030
+ interface OpenStatus {
1031
+ /** Open right now. */
1032
+ open: boolean;
1033
+ /** Open every minute of the week — no closing time to show. */
1034
+ alwaysOpen: boolean;
1035
+ /** Open, and closing within `soonMinutes`. */
1036
+ closingSoon: boolean;
1037
+ /** Closed, and opening within `soonMinutes`. */
1038
+ openingSoon: boolean;
1039
+ /** When open: the end of the current stretch. Absent when `alwaysOpen`. */
1040
+ closesAt?: OpenHoursTransition;
1041
+ /** When closed: the next time it opens. Absent when no day is open. */
1042
+ opensAt?: OpenHoursTransition;
1043
+ }
1044
+ interface OpenStatusOptions {
1045
+ /** How near a transition counts as "soon". Default `30`. */
1046
+ soonMinutes?: number;
1047
+ /** IANA zone the hours are expressed in (`'America/Denver'`). Omit — the
1048
+ * normal case for a kiosk standing in the venue — to read the host clock.
1049
+ * An unrecognised zone falls back to the host clock rather than throwing. */
1050
+ timeZone?: string;
1051
+ }
1052
+ /**
1053
+ * Extensor value → a parsed week, or `null` when there is nothing usable.
1054
+ *
1055
+ * Accepts the stored JSON string or an already-parsed object. Anything
1056
+ * unreadable — absent key, malformed JSON, no open day — is `null` rather than
1057
+ * a throw, so a bad value costs the consumer an omitted section, not a crash.
1058
+ *
1059
+ * An unknown `v` is also `null`, deliberately. A future version could add
1060
+ * holiday overrides or a timezone; reading only the `days` it recognises would
1061
+ * let the SDK announce "Open" on a day the venue marked closed, and a confidently
1062
+ * wrong answer at a kiosk is worse than a missing one.
1063
+ */
1064
+ declare function parseOpenHours(raw: unknown): OpenHours | null;
1065
+ /**
1066
+ * The live open/closed state for a parsed week.
1067
+ *
1068
+ * Pure and time-explicit: pass the `now` you want evaluated (default: the
1069
+ * moment of the call). Nothing is cached, so a consumer that wants a status
1070
+ * that stays true — a kiosk card sitting open — re-calls this on a tick rather
1071
+ * than holding the result.
1072
+ *
1073
+ * Hours carry no timezone of their own, so they are read against the host clock
1074
+ * unless `options.timeZone` names the venue's zone. The kiosk case needs no
1075
+ * option: the machine stands in the building it is describing.
1076
+ */
1077
+ declare function getOpenStatus(hours: OpenHours, now?: Date, options?: OpenStatusOptions): OpenStatus;
1078
+
233
1079
  declare class MinuteMaps {
234
1080
  private config;
235
1081
  private map;
1082
+ /**
1083
+ * Generation token for `init()`. Bumped by every `init()` and by `destroy()`,
1084
+ * so an init suspended on a network await can tell it has been superseded and
1085
+ * bail instead of creating a map nobody holds a reference to.
1086
+ *
1087
+ * This is what makes `destroy()` safe *during* init: `destroy()` only removes
1088
+ * `this.map`, which is still null until step 3, so a teardown that lands
1089
+ * mid-fetch has nothing to clean up — and without this token the init would
1090
+ * resume and build a fully live orphan (WebGL context, render loop, map-level
1091
+ * listeners, YAH pulse) that can never be reached to shut down. React
1092
+ * StrictMode's mount → unmount → mount does exactly this on every dev load.
1093
+ *
1094
+ * A counter, not a sticky `destroyed` flag: `destroy()` → `init()` re-init is
1095
+ * a supported lifecycle (see the manager-class note in CLAUDE.md), so the
1096
+ * instance has to stay usable after teardown.
1097
+ */
1098
+ private initGeneration;
236
1099
  private data;
237
1100
  private wayfindingProvider;
238
1101
  private events;
239
1102
  private floorsApi;
240
1103
  private venue;
241
1104
  private spriteKeys;
242
- private readonly debug;
1105
+ private readonly debugEnabled;
243
1106
  private readonly logger;
1107
+ /**
1108
+ * Console-facing layer inspector — `sdk.debug.hide('labels')`,
1109
+ * `sdk.debug.solo('route')`, `sdk.debug.reset()`. Always present so demo
1110
+ * code can drive it; additionally reachable as `window.mm.debug` when
1111
+ * `options.debug` is on. See `DebugLayers`.
1112
+ */
1113
+ readonly debug: DebugLayers;
1114
+ /** The `window` key `debug` mode installed this instance under, if any. */
1115
+ private debugGlobalKey;
244
1116
  private defaultCamera;
1117
+ /** This venue's opening zoom, captured once after the initial fit resolves.
1118
+ * Anchors the pinned zoom profile's icon/label reveal thresholds (idle
1119
+ * spotlight, active route) to this venue's own opening view rather than an
1120
+ * absolute MapLibre zoom, and the roof fill's fade-in. See `zoomViews`. */
1121
+ private iconZoomBase;
1122
+ /** Which layers show at which zoom: the Campus / Building / Kiosk views, or
1123
+ * the pinned profile while the idle spotlight or a route is up. Re-applied
1124
+ * after every `setTheme()` swap, since `setStyle({ diff: false })`
1125
+ * recreates layers from the pristine theme. */
1126
+ private zoomViews;
245
1127
  private viewModes;
1128
+ /** Mirror of `config.options.reducedMotion`, mutable via `setReducedMotion`. */
1129
+ private reducedMotion;
1130
+ /** Whether map labels render in OpenDyslexic, mutable via `setDyslexicFont`.
1131
+ * Re-applied after every `setTheme()` swap, same reason as `iconZoomBase`. */
1132
+ private dyslexicFont;
1133
+ /** Multiplier applied to every theme label's `text-size`, mutable via
1134
+ * `setTextScale`. Re-applied after every `setTheme()` swap. */
1135
+ private textScale;
1136
+ /** Each label layer's unscaled `text-size`, captured by `setTextScale`.
1137
+ * Cleared on `setTheme()` — the recreated layers carry new base values. */
1138
+ private baseTextSizes;
1139
+ /** Tracks the active theme name so `setTheme()` is a no-op when re-requested. */
1140
+ private activeThemeName;
1141
+ /** Tracks the active locale so `setLocale()` is a no-op when re-requested.
1142
+ * Seeded from `config.jmap.locale` at construction; `undefined` means
1143
+ * whatever the customer's default locale is on the JACS side. */
1144
+ private currentLocale;
1145
+ /** The destination of the last successfully computed route — kept so
1146
+ * `setLocale()` can rebuild + re-emit `routeReady` with retranslated
1147
+ * step text without recomputing the path. Cleared on route failure. */
1148
+ private lastRouteDestinationPoi;
246
1149
  private amenityManager;
247
1150
  private wayfinding;
1151
+ private highlightManager;
1152
+ private selectionManager;
1153
+ private restroomGroups;
1154
+ /** Captured unit paint values to restore when the selection clears, or
1155
+ * `null` when no room is currently focused. See `UNIT_DIM_TARGETS`. */
1156
+ private unitDimRestore;
1157
+ /** Captured destination-layer filters to restore when the selection clears,
1158
+ * or `null` when no destination focus is active. See `setDestinationFocus`. */
1159
+ private destFocusRestore;
1160
+ /** The allow-list currently narrowing the destination layers, or `null` when
1161
+ * no focus is active. Kept alongside `destFocusRestore` (which holds the
1162
+ * *previous* filters, not the ids) so `setTheme` can re-apply the same focus
1163
+ * to the new style's layers after a swap discards the old ones. */
1164
+ private destFocusIds;
1165
+ /** The predicate currently narrowing the POI marker layers to a curated set,
1166
+ * or `null` when no spotlight is active. See `setPOISpotlight`. Held as the
1167
+ * predicate, not a resolved id list, so a floor change or locale redraw can
1168
+ * re-resolve it against the POIs now on screen. */
1169
+ private poiSpotlight;
1170
+ /** Layer filters as they were before the spotlight narrowed them, put back
1171
+ * verbatim when it releases. `null` when no spotlight filter is applied. */
1172
+ private poiSpotlightRestore;
1173
+ /** Coordinates of the current tap/Info selection, or `null` when nothing is
1174
+ * selected. `easeToSelection` reads `getBoundsPadding()` at the moment a
1175
+ * selection is made, which is often *before* the consumer's info card has
1176
+ * mounted and been measured into that padding — so the first pan can land
1177
+ * the POI behind the card. Kept here so `setBoundsPadding` can re-nudge the
1178
+ * camera once the consumer measures its now-mounted chrome and reports
1179
+ * fresh insets, the same way it already re-fits an active route. Cleared by
1180
+ * `clearHighlight`. */
1181
+ private selectedCoordinates;
1182
+ private youAreHerePulse;
1183
+ /** Theme layers whose features represent a tappable destination/amenity.
1184
+ * A click hit-tests these (see `SelectionManager`) → `poiSelected`. The
1185
+ * "You are here" anchor and the transient highlight layers are excluded;
1186
+ * a POI drawn across the circle/label/icon layers is de-duped downstream
1187
+ * in `resolveClickedPOIs`. */
1188
+ private static readonly CLICKABLE_POI_LAYERS;
1189
+ /** Room-body layers that are also tappable: a click on a `Units` polygon
1190
+ * resolves to the destination pin inside it (see `resolvePOIsFromFeatures`).
1191
+ * Queried alongside the pin layers so tapping the room or its dot behaves
1192
+ * identically. Kept separate from the pin list because these carry no POI
1193
+ * identity of their own — they resolve spatially. */
1194
+ private static readonly CLICKABLE_UNIT_LAYERS;
1195
+ /** The kiosk's own "you are here" pin — icon, directional heading wedge,
1196
+ * and the ring drawn behind them. Deliberately **not** part of
1197
+ * `CLICKABLE_POI_LAYERS`: that list feeds `emitPoiSelected`, which opens
1198
+ * a selection card for a destination/amenity, and this pin isn't one —
1199
+ * it's where the kiosk itself is standing. A tap here means "where am
1200
+ * I", so it gets its own delegated listener emitting `youAreHereClicked`
1201
+ * instead, for a consumer to wire to the same recenter action as its
1202
+ * own recenter control. */
1203
+ private static readonly YOU_ARE_HERE_LAYERS;
1204
+ /** While a room is selected, the other units are recolored to a flat, muted
1205
+ * gray so the raised, full-strength highlight block reads as the focus. We
1206
+ * recolor rather than lower opacity on purpose: translucent extrusions blend
1207
+ * through their neighbours and look murky. The blocks stay fully opaque (and
1208
+ * keep their vertical-gradient shading, so they still read as rooms) — just
1209
+ * colorless. The selected room's own base grays too, but its highlight cap
1210
+ * sits opaque and taller on top, so it still stands out. The original paint
1211
+ * value (the data-driven color expression) is captured at mute time and put
1212
+ * back on `clearHighlight`, so department tinting returns intact. */
1213
+ private static readonly UNIT_DIM_TARGETS;
1214
+ /** Destination marker layers hidden down to just the selected destination
1215
+ * while a room is focused, so the map declutters to the one place in view.
1216
+ * Amenity/connector layers (`poiType: 'amenity'`), the "you are here" anchor,
1217
+ * and room name labels (`map-labels`) are deliberately absent — they stay
1218
+ * visible as wayfinding reference. Restored on `clearHighlight`. */
1219
+ private static readonly DESTINATION_FOCUS_LAYERS;
1220
+ /** Categorical POI layers in the bundled theme that `setPOIFilter`
1221
+ * toggles. Layers absent from this list — `poi-you-are-here-*` and the
1222
+ * `poi-highlight-*` layers — are intentionally unaffected; they're
1223
+ * anchors or transient focus state, not categorical content. */
1224
+ private static readonly POI_CATEGORY_LAYERS;
1225
+ /** Marker layers `setPOISpotlight` narrows. Every categorical POI layer
1226
+ * except `poi-other-amenity-icons`, whose filter the restroom-group manager
1227
+ * and the zoom-range pass rewrite as the camera moves — a spotlight
1228
+ * narrowing would be silently overwritten mid-orbit — plus the per-instance
1229
+ * amenity label, which is a marker in every sense but isn't a category. */
1230
+ private static readonly POI_SPOTLIGHT_LAYERS;
1231
+ private poiVisibleTypes;
1232
+ /** Independent show/hide state for destination dots and name labels, set
1233
+ * by `setDestinationCirclesVisible`/`setDestinationLabelsVisible`. Kept
1234
+ * separate from `poiVisibleTypes` so the two controls compose instead of
1235
+ * clobbering each other — `applyPOIFilter` and `applyDestinationDisplay`
1236
+ * each own one paint/layout axis of the same layers. */
1237
+ private destinationCirclesVisible;
1238
+ private destinationLabelsVisible;
248
1239
  constructor(config: SDKConfig);
249
1240
  init(): Promise<void>;
1241
+ /**
1242
+ * Supply an image the current style has requested but doesn't have.
1243
+ *
1244
+ * Every imperatively-registered image is served from here, because a theme
1245
+ * swap (`setStyle` with `diff: false`) drops all of them and the code that
1246
+ * registered them doesn't run again:
1247
+ *
1248
+ * - the **route arrow** isn't in the sprite sheet at all — it's canvas-drawn
1249
+ * on demand (this was already the case);
1250
+ * - **amenity / destination icons** come back from `iconCache`. Their
1251
+ * registrars run only during `init`, so before this they went missing on
1252
+ * the first theme swap and never returned — the map kept the dots and
1253
+ * labels but lost every badge and logo.
1254
+ *
1255
+ * Serving lazily (rather than re-registering everything on `style.load`)
1256
+ * means only the ids the new style actually asks for are restored, with no
1257
+ * refetch and no re-compositing.
1258
+ */
1259
+ private serveMissingStyleImage;
250
1260
  on(event: string, cb: (e: MapEvent) => void): void;
251
1261
  off(event: string, cb?: (e: MapEvent) => void): void;
252
1262
  addControl(control: IControl, position?: ControlPosition): void;
253
1263
  setView(options: ViewOptions): void;
1264
+ /**
1265
+ * Force a camera move to land instantly while reduced motion is on.
1266
+ *
1267
+ * The single gate every consumer-driven move goes through — zoom
1268
+ * buttons, compass reset, go-home, recenter, route fits — so the one
1269
+ * toggle covers them all instead of each call site remembering to ask.
1270
+ * Returns `opts` untouched when the preference is off, so a caller that
1271
+ * asked for `animate: false` keeps it either way.
1272
+ */
1273
+ private motionGated;
254
1274
  get amenities(): AmenityManager;
255
1275
  resetView(opts?: {
256
1276
  animate?: boolean;
257
1277
  duration?: number;
258
1278
  }): void;
1279
+ /**
1280
+ * Content-aware re-frame: fit an active route if one is displayed,
1281
+ * otherwise fit the current floor's geojson. Unlike `resetView()`, this
1282
+ * preserves the user's pitch and bearing — it only adjusts center/zoom
1283
+ * to bring the scene back into view. Intended use is after the map
1284
+ * container resizes (e.g. a side drawer opens beside the map and the
1285
+ * pane gets narrower), so what matters stays framed without a yank.
1286
+ */
1287
+ refit(opts?: {
1288
+ animate?: boolean;
1289
+ duration?: number;
1290
+ }): void;
1291
+ /**
1292
+ * Update the bounds padding (camera insets) used by route + floor fits.
1293
+ * Consumers measure their on-screen chrome (panels, rails) and pass the
1294
+ * insets so a fit frames the path in the visible, unobscured area rather
1295
+ * than under the UI. Stored; the next fit / `refit()` uses it (clamped so
1296
+ * a fit always lands — see `clampPadding`).
1297
+ */
1298
+ setBoundsPadding(p: BoundsPadding): void;
1299
+ private fitToBounds;
259
1300
  set3dEnabled(enabled: boolean): void;
260
1301
  toggle3d(): void;
261
1302
  getIs3dEnabled(): boolean;
1303
+ /**
1304
+ * (Re-)register per-amenity icons, per-destination logos, and the kiosk
1305
+ * "you are here" icon. Needed both at init and after every `setTheme()`
1306
+ * call — `map.setStyle(..., { diff: false })` tears down and recreates
1307
+ * the whole `Style` object, which drops every image added at runtime via
1308
+ * `map.addImage`. Only `route-arrow` re-registers itself lazily via
1309
+ * `styleimagemissing`; everything else must be re-run explicitly here or
1310
+ * it silently goes blank after a theme swap.
1311
+ *
1312
+ * `themeName === 'high-contrast'` recolors both the amenity badge disc
1313
+ * and the connector (elevator/stairs/escalator) badge disc to
1314
+ * `HIGH_CONTRAST_AMENITY_BADGE_COLOR`, and forces both the regular and
1315
+ * connector glyph to `HIGH_CONTRAST_AMENITY_ICON_COLOR` so neither
1316
+ * washes out against its now-yellow disc and the two match each other.
1317
+ * Ring colors are left untouched. Failures per icon set are logged and
1318
+ * skipped so one bad icon doesn't block the rest.
1319
+ */
1320
+ private registerRuntimeIcons;
1321
+ /**
1322
+ * Set the active map theme by name (`'default'` / `'high-contrast'`) or by
1323
+ * passing a custom `StyleSpecification`. The current floor, route, POIs
1324
+ * and camera are preserved across the swap — only layer styling changes.
1325
+ *
1326
+ * Used by kiosk consumers to wire the OS-level / popover high-contrast
1327
+ * toggle to the map. See `KIOSK.md` for the pattern.
1328
+ */
1329
+ setTheme(theme: ThemeName | StyleSpecification): Promise<void>;
1330
+ /** Currently active theme name (or `'custom'` when a raw style was passed). */
1331
+ getActiveTheme(): 'default' | 'high-contrast' | 'custom';
1332
+ /**
1333
+ * Update the SDK's reduced-motion preference at runtime. When true, every
1334
+ * imperative camera move (`setView`, `resetView`, `refit`, recenter, route
1335
+ * fits, selection pans, floor fits) runs with `duration: 0`, and every
1336
+ * looping animation the SDK drives — the route line-draw, the flowing route
1337
+ * arrows, the "You are here" pulse, the selection ring's ping — is stopped.
1338
+ *
1339
+ * Anything already on screen is switched over here, not just on the next
1340
+ * action: a visitor who flips the toggle mid-route is doing it *because* of
1341
+ * the motion they can see, so waiting for the next event would be the one
1342
+ * moment the preference doesn't work.
1343
+ */
1344
+ setReducedMotion(enabled: boolean): void;
1345
+ getReducedMotion(): boolean;
1346
+ /**
1347
+ * Swap every map label (street names, POI names, building labels, "You are
1348
+ * here") between the bundled themes' default font and OpenDyslexic. Mirrors
1349
+ * the DOM-side dyslexic-font accommodation onto the canvas, which CSS can't
1350
+ * reach.
1351
+ *
1352
+ * Goes through the same local-glyph fallback the themes already use for
1353
+ * `Material Icons` (`LOCAL_GLYPH_FONTS`): `text-font` values are swapped to
1354
+ * fontstack names intentionally absent from the glyph server
1355
+ * (`OpenDyslexic Bold` etc.), so MapLibre rasterizes them from a
1356
+ * page-loaded `@font-face` instead. The consuming app owns loading that
1357
+ * font — the SDK ships no assets — so this is a no-op glyph-wise (labels
1358
+ * fall back to tofu-free default rendering) if the app never declared it.
1359
+ *
1360
+ * Re-applied after `setTheme()`, since `setStyle({ diff: false })`
1361
+ * recreates every layer from the pristine (non-dyslexic) theme JSON.
1362
+ */
1363
+ setDyslexicFont(enabled: boolean): Promise<void>;
1364
+ getDyslexicFont(): boolean;
1365
+ private applyDyslexicFontToLabels;
1366
+ /**
1367
+ * Scale every map label's `text-size` by `scale` (1 = theme default; the
1368
+ * example kiosk passes 1.15 for its "large text" setting). Mirrors the
1369
+ * DOM-side text-size accommodation onto the canvas, which CSS can't reach.
1370
+ *
1371
+ * Multiplies the output values inside each layer's `text-size` (MapLibre
1372
+ * requires `zoom` to stay at the top of the expression, so it can't be
1373
+ * wrapped), so zoom interpolation and data-driven sizing keep working. Re-applied after
1374
+ * `setTheme()`, since `setStyle({ diff: false })` recreates every layer from
1375
+ * the pristine theme JSON. Non-finite or non-positive values reset to 1.
1376
+ */
1377
+ setTextScale(scale: number): void;
1378
+ getTextScale(): number;
1379
+ private applyTextScaleToLabels;
1380
+ /**
1381
+ * Switch the locale used for POI / amenity / destination / floor names at
1382
+ * runtime. The SDK refetches localized names from JACS (per-entity
1383
+ * endpoints — `/all` does not honor `?locale=`), patches the in-memory
1384
+ * venue model in place, then redraws the POI source for the current floor
1385
+ * so map labels render in the new language.
1386
+ *
1387
+ * Structural data (waypoints, coordinates, iconIds) is preserved — only
1388
+ * the localized fields (`name`, `description`) move.
1389
+ *
1390
+ * Emits a `localeChanged` event with the new code after the patch
1391
+ * completes. No-op when the code matches the current locale.
1392
+ *
1393
+ * Throws only on programmer error — a provider without locale support
1394
+ * (only `JacsDataProvider` has it today) or an empty code. A **failed
1395
+ * JACS fetch is not fatal**: the locale still switches and is reported,
1396
+ * it's only the localized names that stay on the prior language. That
1397
+ * split is deliberate — generated directions text ships inside the SDK
1398
+ * and must not be held hostage to a network round-trip.
1399
+ */
1400
+ setLocale(locale: string): Promise<void>;
1401
+ /**
1402
+ * Start fetching the localized names for `locale` in the background so a
1403
+ * later `setLocale(locale)` only has the in-memory patch and redraw left to
1404
+ * do. Call it once after `ready` for each alternate language the UI offers.
1405
+ *
1406
+ * Never throws and never changes the active locale or the map — a provider
1407
+ * without locale support, an empty code or a failed fetch is a silent no-op
1408
+ * (a failed fetch is retried when `setLocale` runs). Safe to call
1409
+ * repeatedly; the fetch for a given code happens once.
1410
+ */
1411
+ prefetchLocale(locale: string): Promise<void>;
1412
+ /** Currently active locale (BCP-47), or `undefined` when no locale has
1413
+ * been set — meaning JACS resolves names to the customer's default. */
1414
+ getActiveLocale(): string | undefined;
262
1415
  setUnits2dEnabled(enabled: boolean): void;
263
1416
  toggleUnits2d(): void;
264
1417
  getIsUnits2dEnabled(): boolean;
@@ -269,26 +1422,639 @@ declare class MinuteMaps {
269
1422
  getCurrentFloor(): Floor | null;
270
1423
  getDefaultFloor(): Floor | null;
271
1424
  getDestinations(floor?: Floor): Destination[];
1425
+ getZones(): Zone[];
1426
+ /** The department (zone) a POI belongs to, resolved via its waypoint's
1427
+ * `zoneId` — the only backend link between a location and a department
1428
+ * (see the zone landmine in the package CLAUDE.md). `null` when the POI
1429
+ * has no waypoint, no zone, or the zone id is unknown. */
1430
+ getZoneForPOI(poi: POI): Zone | null;
1431
+ /** Human-readable detail fields for a POI info popover. Only surfaces
1432
+ * fields that exist on the current data — `category`, `floorName`,
1433
+ * `zoneName`, `keywords`, `description`, and `imageUrl` are each omitted
1434
+ * when absent. Keeps the display-field derivation (incl. the zone lookup)
1435
+ * in the SDK so consumers stay thin. */
1436
+ getPOIDetails(poi: POI): {
1437
+ name: string;
1438
+ type: 'amenity' | 'destination' | 'kiosk';
1439
+ category?: string;
1440
+ floorName?: string;
1441
+ floorShortName?: string;
1442
+ zoneName?: string;
1443
+ zoneDescription?: string;
1444
+ /** The department's authored hex colour (`Zone.color`) — the same value
1445
+ * that tints this room's polygon on the map, so a consumer can print a
1446
+ * swatch beside the department name and connect the two. Absent when the
1447
+ * author never picked one, which is also when the map leaves the room
1448
+ * untinted; treat "no colour" as "this department isn't colour-coded",
1449
+ * not as "fall back to a default swatch". */
1450
+ zoneColor?: string;
1451
+ keywords?: string[];
1452
+ description?: string;
1453
+ /** CMS-authored extras from the entity's `extensors` bag (opening hours,
1454
+ * days, room, building). Free-form — the consumer decides what to render.
1455
+ * Artwork is not in here; see `imageUrl`. */
1456
+ properties?: Record<string, unknown>;
1457
+ /** The destination's uploaded location image, ready for an `<img src>`.
1458
+ * Destinations only — amenities use sprite glyphs, not photos. Inline SVG
1459
+ * from `/all` comes back as a data URI; otherwise it's the uploaded uri
1460
+ * path. Absent when nothing was uploaded in the CMS. */
1461
+ imageUrl?: string;
1462
+ /** Author-written alt text for `imageUrl` (`mm_image_alt`) — a description
1463
+ * of the place, for screen readers and for anyone the image fails to load
1464
+ * for. Absent when the author wrote none, in which case the image is
1465
+ * decorative and belongs in an `<img alt="">`, not an unlabelled one. */
1466
+ imageAlt?: string;
1467
+ /** Room number — the CMS's "Room Number". Reads the real
1468
+ * `Destination.unitNumber` column, falling back to a legacy hand-typed
1469
+ * `room_number` property for venues authored before that field existed. */
1470
+ roomNumber?: string;
1471
+ /** Which building on the campus this destination is in (`mm_building_name`),
1472
+ * as the author typed it — "200", "Ambulatory Care". Free text, not a
1473
+ * reference to a `Building` record; render it, don't resolve it. Falls back
1474
+ * to the legacy hand-typed `building_name` property, which is unprefixed
1475
+ * and therefore a different key. */
1476
+ buildingName?: string;
1477
+ /** Phone number and internal extension (`mm_phone`). The number is exactly
1478
+ * as the author typed it, not normalised — see `parsePhone`. */
1479
+ phone?: DestinationPhone;
1480
+ /** The CMS-authored opening hours (`mm_open_hours`), parsed. Absent when
1481
+ * the author set none, or the stored value is unreadable.
1482
+ *
1483
+ * Static — it describes the week, not this moment. Pass it to
1484
+ * `getOpenStatus()` for the live open/closed state, and re-call that on a
1485
+ * tick if the UI stays on screen. The raw string also remains in
1486
+ * `properties` for consumers that would rather parse it themselves. */
1487
+ openHours?: OpenHours;
1488
+ };
1489
+ /** Resolve the source Destination/Amenity record backing a rendered POI,
1490
+ * for detail fields (category, localized description) that don't live on
1491
+ * the built POI object. */
1492
+ private getSourceEntity;
272
1493
  getPolygonLayers(): any[];
1494
+ /**
1495
+ * Cross-reference the venue's drawn layers against the customer's allowed
1496
+ * layer list (JACS `GET /customer/{id}/polygon-layer`) and against what the
1497
+ * active theme can actually render.
1498
+ *
1499
+ * Three failure modes, none of which is visible by looking at the map:
1500
+ * a layer drawn under a name the CMS doesn't list (`unauthorized`), a layer
1501
+ * legitimately drawn that no theme rule matches (`unstyled`), and a theme
1502
+ * rule with nothing to draw at this venue (`unused`). Runs automatically
1503
+ * once after `ready` when `options.debug` is on; call it directly —
1504
+ * `mm.validateMapLayers()` — any time.
1505
+ *
1506
+ * Only counts floors whose geojson has loaded. Init preloads the rest in
1507
+ * the background, so a call in the first moments after `ready` may report
1508
+ * fewer `inData` types than a call a second later.
1509
+ */
1510
+ validateMapLayers(): Promise<LayerAudit>;
1511
+ /** Debug-mode auto-run: log findings once, stay silent when clean. */
1512
+ private reportLayerAudit;
273
1513
  getFloorMapTemplate3d(floorId: string | number): any[];
274
1514
  getAllPOIs(floor?: Floor): POI[];
1515
+ /**
1516
+ * Put the map on the kiosk's floor before drawing a route from it.
1517
+ *
1518
+ * **A route from the kiosk always starts on the kiosk's floor**, so that is
1519
+ * the floor the visitor has to be looking at when it appears. The renderer
1520
+ * agrees with that already — `wayfinding` reveals and frames *the active
1521
+ * floor's* slice of the route — which is exactly why this matters: leave the
1522
+ * map where the visitor had wandered to and the route arrives framed on the
1523
+ * wrong leg, or on no leg at all.
1524
+ *
1525
+ * Both halves of that were reported from a real kiosk. Browse up to Level 3,
1526
+ * search, press Directions: if Level 3 isn't on the route the fit falls back
1527
+ * to the union of every floor and nothing reads as a path from here; if it
1528
+ * *is* on the route — because the destination is up there — the visitor is
1529
+ * looking at the last leg of a walk they haven't started, with no indication
1530
+ * that the first one is two floors down.
1531
+ *
1532
+ * Called before the route is computed rather than after it's drawn, so the
1533
+ * camera makes one move instead of fitting the wrong floor and correcting.
1534
+ * No-op when the venue has no kiosk anchor (those routes fail anyway) or the
1535
+ * map is already there.
1536
+ */
1537
+ private showKioskFloorForRoute;
1538
+ /**
1539
+ * The floor the kiosk is physically anchored to — not necessarily the
1540
+ * floor currently displayed (the visitor may have panned the floor
1541
+ * selector to preview a destination on another level, and the SDK opens
1542
+ * on the venue's configured default floor rather than the kiosk's own —
1543
+ * see `FloorManager.selectInitialFloor`). Anchor resolution (routing,
1544
+ * recentering, closest-waypoint) must resolve against this floor, never
1545
+ * `getCurrentFloor()`, or it silently misses the "you are here" POI
1546
+ * whenever the two diverge. `null` when the venue has no kiosk anchor.
1547
+ */
1548
+ getKioskFloor(): Floor | null;
275
1549
  getYouAreHerePOI(floor?: Floor): POI | null;
276
1550
  getYouAreHereCoordinates(floor?: Floor): [number, number] | null;
1551
+ /**
1552
+ * Compass heading the kiosk's physical hardware faces, in degrees
1553
+ * clockwise from north. Sourced from JACS `Device.heading`. `null` when
1554
+ * the venue's device record has no heading set.
1555
+ *
1556
+ * In order to rotate the map so it is oriented towards the user's gaze,
1557
+ * 180 is subtracted from `Device.heading`.
1558
+ *
1559
+ * Drives `recenterOnKiosk({ useHeading: true })` and the directional
1560
+ * cone rendered next to the "You are here" marker.
1561
+ */
1562
+ getKioskHeading(): number | null;
1563
+ /**
1564
+ * Bearing (degrees clockwise from north) the visitor at the kiosk is
1565
+ * FACING — the device heading rotated 180°, since they stand in front
1566
+ * of the screen looking back at it. `null` when the device record
1567
+ * carries no heading, in which case direction-relative wording ("turn
1568
+ * right and walk 40 ft") is suppressed rather than guessed.
1569
+ */
1570
+ private getVisitorFacingBearing;
1571
+ /**
1572
+ * Display name of the JACS device the kiosk is anchored to (e.g.
1573
+ * "Main Lobby Kiosk", "Information Desk Kiosk"). `null` when the venue
1574
+ * has no kiosk anchor or the device record carries no `name`.
1575
+ *
1576
+ * Distinct from `getYouAreHerePOI()?.name`, which is always the
1577
+ * literal "You are here" label rendered on the map. Use this for chrome
1578
+ * that needs the kiosk's identity — e.g. the directions overlay's
1579
+ * "From <kiosk>" header.
1580
+ */
1581
+ getKioskName(): string | null;
1582
+ /**
1583
+ * Distance + walking time from the kiosk's anchor waypoint to a target,
1584
+ * computed over the JACS path graph (the same graph the routing engine
1585
+ * uses). Designed for "Closest: 30 sec walk" subtitles in the consumer
1586
+ * UI — no second graph build, no second Dijkstra implementation.
1587
+ *
1588
+ * Accepts a raw waypoint id, an amenity / destination object (the first
1589
+ * entry of its `waypoints` array is treated as the entry point), or any
1590
+ * `{ id, mapId? }` shape. Returns `null` when the kiosk isn't anchored,
1591
+ * the target waypoint isn't on the graph, or no path resolves.
1592
+ *
1593
+ * Walking speed defaults to 2.953 ft/s (0.9 m/s, average adult walking speed —
1594
+ * PMC2967707). Pass `walkingSpeedFps` to estimate for accessibility (e.g. 2).
1595
+ *
1596
+ * `feet` / `seconds` are the *physical* walk — horizontal legs only, what a
1597
+ * visitor is shown. `effortSeconds` adds the router's charge for each floor
1598
+ * change (the elevator wait) and is what to *rank* candidates by; see
1599
+ * `findClosestByWalkTime`. Pass `avoidStairs` to price the path as a route
1600
+ * with that option would be.
1601
+ */
1602
+ getWalkTimeFromKiosk(target: number | string | {
1603
+ id?: number | string;
1604
+ mapId?: number;
1605
+ } | {
1606
+ waypoints?: Array<number | string | {
1607
+ id?: number | string;
1608
+ }>;
1609
+ }, opts?: {
1610
+ walkingSpeedFps?: number;
1611
+ avoidStairs?: boolean;
1612
+ }): {
1613
+ feet: number;
1614
+ seconds: number;
1615
+ effortSeconds: number;
1616
+ pathNodeCount: number;
1617
+ } | null;
1618
+ /**
1619
+ * Center the camera on the kiosk's "You are here" position. Use this
1620
+ * (not `resetView`) for a chrome "Recenter" button — `resetView` snaps
1621
+ * to the SDK's captured default camera, which may have been a venue
1622
+ * overview rather than the kiosk's spot.
1623
+ *
1624
+ * When `useHeading` is true (default) and the kiosk device has a
1625
+ * `heading` on file, the camera's bearing is rotated so the direction
1626
+ * the kiosk physically faces ends up at the top of the screen. That
1627
+ * way "what the user sees in front of them" matches "what's up on the
1628
+ * map" — the single largest readability win for stressed indoor users.
1629
+ */
1630
+ recenterOnKiosk(opts?: {
1631
+ useHeading?: boolean;
1632
+ zoom?: number;
1633
+ pitch?: number;
1634
+ animate?: boolean;
1635
+ duration?: number;
1636
+ }): void;
277
1637
  searchPOIs(query: string, floor?: Floor): POI[];
1638
+ /**
1639
+ * Search POIs across every floor in the venue. Returns raw matches —
1640
+ * an amenity that exists on multiple floors appears multiple times,
1641
+ * once per instance. Consumers that need one row per logical amenity
1642
+ * should dedupe by id (and, for "nearest", pick the instance closest
1643
+ * to the kiosk via planar distance on `coordinates`).
1644
+ */
1645
+ searchAllPOIs(query: string): POI[];
278
1646
  wayfindBetweenWaypoints(fromWaypoint: any, toWaypoint: any, options?: {
279
1647
  centerMode?: 'none' | 'destination' | 'route';
280
1648
  zoom?: number;
1649
+ /** Hard-filter stairs from the graph. */
1650
+ avoidStairs?: boolean;
281
1651
  }): Promise<any>;
282
1652
  navigateFromKioskToDestination(destination: any): Promise<any>;
1653
+ /**
1654
+ * Route from the kiosk to a specific POI's waypoint. Use this when you
1655
+ * already hold a resolved POI (e.g. from `searchPOIs` / `searchAllPOIs`).
1656
+ * For a venue-wide amenity record with multiple instances, resolve via
1657
+ * `findClosestWaypoint` first — or use `highlightAmenity` instead, if
1658
+ * you want a visual focus rather than a route.
1659
+ */
1660
+ navigateFromKioskToPOI(poi: POI, options?: {
1661
+ avoidStairs?: boolean;
1662
+ }): Promise<any>;
1663
+ /** Build the landmark / floor-name context the directions module needs.
1664
+ * Pulled out so `setLocale()` or `setActiveStep()` can rebuild it on
1665
+ * demand if we ever surface a locale-aware variant. */
1666
+ /**
1667
+ * Rewrite every source whose features carry venue-authored *text* for a
1668
+ * floor: POI labels and map labels. Both read their names straight out of
1669
+ * the venue model, so anything that mutates that model in place — today
1670
+ * `setLocale`'s translation patch — has to call this or the map keeps
1671
+ * rendering the old strings until the next floor change.
1672
+ *
1673
+ * Map labels ride the same lifecycle as POIs and carry the `allLevels`
1674
+ * flag, which the projector has already honored by duplicating the
1675
+ * instance under every floor's list.
1676
+ */
1677
+ private redrawFloorText;
1678
+ private buildDirectionsContext;
1679
+ /**
1680
+ * Drive the turn-by-turn UI. Two effects:
1681
+ *
1682
+ * 1. When the step's `floorId` differs from the active floor, switch
1683
+ * floors so the segment for the step's leg becomes visible.
1684
+ * 2. Highlight the step's slice of the route line by writing the
1685
+ * point range to the `route-active-step` source; the bundled
1686
+ * theme's `route-line-active` layer paints it in gold over the
1687
+ * muted base route.
1688
+ *
1689
+ * Transition steps (cross-floor elevator / stair hops) clear the
1690
+ * highlight — the overlay text carries the action, and there's no
1691
+ * meaningful on-floor segment to paint.
1692
+ *
1693
+ * Pass `null` to clear the highlight without changing the floor or
1694
+ * tearing down the route.
1695
+ */
1696
+ setActiveStep(step: WayfindStep | null): Promise<void>;
1697
+ private writeActiveStepHighlight;
1698
+ private clearActiveStepHighlight;
283
1699
  clearRoute(): void;
1700
+ /**
1701
+ * Put the end-of-route marker on `poi`, or take it down (`null`).
1702
+ *
1703
+ * A destination gets a flag in place of its dot; an amenity instance gets an
1704
+ * enlarged copy of its own icon (`map/routeEnd.ts`). Both are drawn from a
1705
+ * source of their own, so this never touches the POI layers — clearing the
1706
+ * route empties the source and the ordinary dot / icon are what remain.
1707
+ *
1708
+ * The routed restroom is also kept out of restroom grouping while the marker
1709
+ * is up; see `RestroomGroupManager.setExcludedKey`.
1710
+ */
1711
+ private setRouteEnd;
1712
+ /**
1713
+ * Highlight a single POI on the map — a pulsing ring — and bring it into
1714
+ * view. Resolves the POI across all floors, switching the active floor if
1715
+ * it lives on another one. Pass a POI / amenity / destination id.
1716
+ */
1717
+ highlightPOI(id: string | number): Promise<void>;
1718
+ /**
1719
+ * Select a POI programmatically — the same end state as tapping it on the
1720
+ * map, from a list or any other chrome.
1721
+ *
1722
+ * Switches the active floor first when the POI lives on another one, raises
1723
+ * its room as a highlighted block, mutes the neighbouring units, declutters
1724
+ * to the selected destination(s), pans it into the unobscured map area and
1725
+ * emits **`poiSelected`** carrying every co-located POI. A consumer that
1726
+ * already renders an info card off that event therefore needs no second code
1727
+ * path: a tap and a list pick arrive the same way.
1728
+ *
1729
+ * This is deliberately *not* `highlightPOI`, which is the search-locate
1730
+ * gesture — it zooms and recenters and draws a pulsing ring, and emits
1731
+ * nothing. Selection is the quieter one: current zoom kept, no ring, the
1732
+ * raised room is the indicator.
1733
+ *
1734
+ * Accepts a `POI` (preferred — its `type` and `waypointId` pin down the exact
1735
+ * instance, which matters for an amenity that shares one id across every
1736
+ * physical pin) or a bare id.
1737
+ *
1738
+ * **`includeCoLocated: false` emits only the requested POI.** By default the
1739
+ * payload carries everything sharing the room, which is right when the
1740
+ * gesture was a tap — the visitor pointed at a place on a floor plan and the
1741
+ * consumer has to show them what's there. It's wrong when they picked one
1742
+ * entry out of a named list: they have already disambiguated, and handing
1743
+ * back four places would ask them to do it again, on a card that opened
1744
+ * *because* they were specific. The map treatment is identical either way
1745
+ * (same room raised, same neighbours muted, same pan); only the payload —
1746
+ * and so the declutter's allow-list — narrows.
1747
+ *
1748
+ * Returns the selected POIs, `pois[0]` being the requested one; an empty
1749
+ * array if no POI matched, which is also when nothing on the map changes.
1750
+ */
1751
+ selectPOI(target: POI | string | number, options?: {
1752
+ includeCoLocated?: boolean;
1753
+ }): Promise<POI[]>;
1754
+ /** Remove the POI highlight set by `highlightPOI`, un-dim the other units,
1755
+ * and bring back the destination markers hidden by a room selection. */
1756
+ clearHighlight(): void;
1757
+ /** Map a click's raw feature hits to the full, de-duplicated POIs at that
1758
+ * point (see `resolvePOIsFromFeatures`). Injected into `SelectionManager`.
1759
+ * `getAllPOIs()` is the current floor's rendered POIs — the only clickable
1760
+ * ones — and carries each POI's `waypoint`, needed for directions. */
1761
+ private resolveClickedPOIs;
1762
+ /** Emit `poiSelected` for the co-located POIs at a clicked point. Focuses the
1763
+ * selection in place (no recenter — the user already sees where they
1764
+ * tapped): rings the tapped dot and, when the tap landed in a room, raises
1765
+ * that room as a highlighted block so the eye goes to the selected unit.
1766
+ * `clearHighlight` removes both. `poi` mirrors `pois[0]` for single-POI
1767
+ * consumers. */
1768
+ private emitPoiSelected;
1769
+ /**
1770
+ * Build the room-highlight payload for a selection. The colour comes from the
1771
+ * *clicked* feature (the rendered truth), but the geometry comes from the
1772
+ * floor's full source polygon — the clicked feature is from
1773
+ * `queryRenderedFeatures`, whose geometry is clipped to on-screen tiles, so
1774
+ * highlighting it directly would leave any off-screen part of the room grey
1775
+ * (its base extrusion is muted). Falls back to the clipped geometry if the
1776
+ * full polygon can't be found. Returns `null` for a pin with no room.
1777
+ */
1778
+ private unitHighlightFor;
1779
+ /** The full, unclipped `Units` polygon on the current floor that contains
1780
+ * `coord`, straight from the floor source (not the tile-clipped render). */
1781
+ private fullUnitPolygonAt;
1782
+ /**
1783
+ * Hide every destination marker except the given ids (pass `null` to
1784
+ * restore all). Narrows each destination layer's own filter with an id
1785
+ * allow-list; amenity/connector/"you are here" layers are untouched, so they
1786
+ * stay on the map as reference. Captures the original filters once and puts
1787
+ * them back verbatim, so the layers' base rules (poiType, showLabel, iconId)
1788
+ * survive.
1789
+ */
1790
+ private setDestinationFocus;
1791
+ /**
1792
+ * Select every destination inside a tapped cluster bubble, so a consumer's
1793
+ * multi-place card lists them — the same `poiSelected` a tap on stacked pins
1794
+ * emits.
1795
+ *
1796
+ * Unlike `emitPoiSelected` this raises no room and narrows no markers. A
1797
+ * cluster spans rooms, so there is no one unit to raise or dim around, and
1798
+ * the destination focus would filter out the bubble that was just tapped
1799
+ * (its features carry no `id`) and the members hidden inside it with it.
1800
+ * Any earlier selection is cleared first, so a room left raised by the last
1801
+ * tap doesn't outlive this one. `clearHighlight` afterwards is a harmless
1802
+ * no-op for the consumer to call on dismiss.
1803
+ *
1804
+ * The leaves are read back from the cluster source (`getClusterLeaves`: a
1805
+ * promise on MapLibre v5, a callback on v4 — `peerDependencies` allows both)
1806
+ * and resolved against the floor's POIs, since a source feature only carries
1807
+ * enough identity to look the full POI (with its waypoint) back up.
1808
+ */
1809
+ private selectCluster;
1810
+ /** Gentle pan so the selection sits in the centre of the map area MapLibre
1811
+ * frames within `boundsPadding` (which the consumer sets to reserve for its
1812
+ * bottom-docked chrome / info card). A straight `easeTo`, current zoom kept,
1813
+ * so it reads as a nudge, not a recenter. */
1814
+ private easeToSelection;
1815
+ /** Dim every unit's paint (or restore it) so a selected room reads as the
1816
+ * focus. Idempotent: capturing only happens on the first activate, and the
1817
+ * captured originals are put back verbatim on deactivate. */
1818
+ private setUnitFocusDim;
1819
+ /**
1820
+ * Show only the named POI categories on the map. Pass `['amenity']` to
1821
+ * emphasize amenities (e.g. while an Amenities drawer is open) — destination
1822
+ * POIs hide. Call `clearPOIFilter()` to restore the default (all categories).
1823
+ *
1824
+ * The "You are here" marker, the wheelchair-accessibility badge, and any
1825
+ * active highlight are not affected and always render.
1826
+ */
1827
+ setPOIFilter(types: Array<'amenity' | 'destination'>): void;
1828
+ /** Restore the default — every POI category renders. */
1829
+ clearPOIFilter(): void;
1830
+ /**
1831
+ * Narrow the POI markers to a curated set: only POIs for which `match`
1832
+ * returns true keep their icon and label, every other pin on the categorical
1833
+ * marker layers (destinations, entrances, parking, bus, connectors,
1834
+ * information, and the per-instance amenity names) is filtered out. Built for
1835
+ * an attract loop that wants a few chosen places on screen instead of either
1836
+ * every marker or none.
1837
+ *
1838
+ * `match` runs against the current floor's POIs — the same objects
1839
+ * `getAllPOIs()` returns, `instanceName` and `amenityCategory` included — and
1840
+ * is re-run on every floor change, theme swap and locale redraw, so the
1841
+ * spotlight follows the map rather than the floor it was set on. Kiosk
1842
+ * "You are here" is never touched.
1843
+ *
1844
+ * Two things it deliberately leaves alone:
1845
+ * - `poi-other-amenity-icons` and the restroom badge. Their filters are owned
1846
+ * by the restroom-group manager and rewritten as the camera moves, so a
1847
+ * narrowing there would not survive a frame. Hide them with `hideLayers`
1848
+ * if the spotlight should exclude them.
1849
+ * - `setPOIFilter`'s category visibility, which composes: a category the
1850
+ * filter hides stays hidden whatever `match` says.
1851
+ *
1852
+ * Selecting a place (`selectPOI`, a map tap) releases the spotlight. Pass
1853
+ * `null` — or call `clearPOISpotlight()` — to restore every marker.
1854
+ */
1855
+ setPOISpotlight(match: ((poi: POI) => boolean) | null): void;
1856
+ /** Re-apply the zoom profile if the idle spotlight or a route just changed
1857
+ * which one is in force, and refresh what hangs off it. */
1858
+ private syncZoomViews;
1859
+ /** Restore every POI marker narrowed by `setPOISpotlight`. */
1860
+ clearPOISpotlight(): void;
1861
+ private applyPOISpotlight;
1862
+ private applyPOIFilter;
1863
+ /**
1864
+ * Show or hide destination dots, independently of their name labels and of
1865
+ * `setPOIFilter`'s combined `'destination'` category (which still toggles
1866
+ * both together). Affects every destination dot — both the dot+label
1867
+ * marker on `poi-destination-labels` and the dot-only fallback on
1868
+ * `poi-destination-circles` that a `showLabel: false` POI renders on.
1869
+ *
1870
+ * Implemented as `icon-opacity`, not a layer swap: dot and label are
1871
+ * placed as one collision unit on `poi-destination-labels` (`icon-optional:
1872
+ * false` / `text-optional: true`), which is what guarantees a label never
1873
+ * renders without a dot beneath it. Splitting them into independently
1874
+ * *placed* layers would let MapLibre's collision index resolve each half
1875
+ * on its own, so a label could win placement while its dot lost — the
1876
+ * "floating name" bug this theme's combined layer was built to fix (see
1877
+ * `themes.test.ts` :: "a destination is one marker").
1878
+ */
1879
+ setDestinationCirclesVisible(visible: boolean): void;
1880
+ /**
1881
+ * Show or hide destination name labels, independently of their dots. See
1882
+ * `setDestinationCirclesVisible` for why this is an opacity toggle on the
1883
+ * shared marker layer rather than a separate label layer.
1884
+ *
1885
+ * `visible: true` (the default) doesn't mean "always on" — labels still
1886
+ * fade in only once the visitor has zoomed in past the venue's opening
1887
+ * view (`DESTINATION_LABEL_REVEAL_OFFSET` in `iconZoomRanges.ts`), so a
1888
+ * zoomed-out visitor sees dots without the screen filling with names. Pass
1889
+ * `false` to suppress labels outright regardless of zoom.
1890
+ */
1891
+ setDestinationLabelsVisible(visible: boolean): void;
1892
+ private applyDestinationDisplay;
1893
+ /**
1894
+ * Return the waypoint in `waypoints` closest to `from`. Useful for
1895
+ * "route to the nearest X" against a venue-wide amenity record that has
1896
+ * multiple physical instances. Defaults `from` to the kiosk's
1897
+ * "You are here" coordinates.
1898
+ *
1899
+ * Distance is planar Euclidean on lng/lat — sufficient for ordering at
1900
+ * single-venue scale, and avoids a turf dependency on the hot path.
1901
+ */
1902
+ findClosestWaypoint(waypoints: Waypoint[], from?: [number, number]): Waypoint | null;
1903
+ /**
1904
+ * Pick the candidate cheapest to reach from the kiosk — the one rule for
1905
+ * "closest instance of an amenity". `navigateFromKioskToClosestAmenity` and
1906
+ * `highlightAmenity` use it, and a consumer collapsing a venue-wide amenity
1907
+ * to a single search row should too, so a tap and a search result can never
1908
+ * resolve the same amenity to different floors.
1909
+ *
1910
+ * Each candidate is scored by `getWalkTimeFromKiosk().effortSeconds` — walk
1911
+ * time over the JACS path graph **plus the elevator wait** for any floor
1912
+ * change — and a candidate on a *different floor* from the kiosk has that
1913
+ * score multiplied by `options.otherFloorPenalty` (default `1.5`; `1`
1914
+ * disables it). The wait is the physical cost of leaving the floor; the
1915
+ * multiplier is a preference for not making the visitor do it, and only
1916
+ * applies here — it never changes a route.
1917
+ *
1918
+ * `toWaypoint` maps a candidate to the waypoint it stands for (identity for
1919
+ * a `Waypoint[]`, `poi => poi.waypoint` for a `POI[]`). Candidates whose
1920
+ * waypoint is missing or has no coordinates are ignored, as are waypoints
1921
+ * the graph can't reach from the kiosk. If none resolve a cost, falls back
1922
+ * to the planar `findClosestWaypoint`, **restricted to the kiosk's floor
1923
+ * when any candidate is on it** (planar distance is meaningless across
1924
+ * overlaid floors). Returns `null` for no usable candidate. Pass the same
1925
+ * `avoidStairs` the route will use so the pick and the route agree.
1926
+ */
1927
+ findClosestByWalkTime<T>(items: readonly T[], toWaypoint: (item: T) => Waypoint | null | undefined, opts?: {
1928
+ avoidStairs?: boolean;
1929
+ }): T | null;
1930
+ /**
1931
+ * Route from the kiosk to the closest physical instance of an amenity.
1932
+ * Resolves the amenity venue-wide, picks the instance with the smallest
1933
+ * path-graph cost from the kiosk (`findClosestByWalkTime`: walk time plus
1934
+ * the elevator wait, with a preference for the kiosk's floor; falling back
1935
+ * to planar Euclidean when the walk-time graph can't resolve any waypoint), switches the
1936
+ * active floor if needed, and routes via the same plumbing as
1937
+ * `navigateFromKioskToPOI` — so step-by-step directions, the
1938
+ * `routeReady` event, and the active-floor camera fit all "just work."
1939
+ *
1940
+ * Pass `avoidStairs` to hard-filter stairs from the *route* (the SDK's
1941
+ * routing engine reads it per call; the CMS's per-path-type weight
1942
+ * otherwise handles accessibility preference automatically). The same
1943
+ * flag is passed to the closest-instance pick, so an instance reachable
1944
+ * only by stairs is skipped in favour of one the route can actually reach.
1945
+ */
1946
+ navigateFromKioskToClosestAmenity(amenityId: string | number, options?: {
1947
+ avoidStairs?: boolean;
1948
+ }): Promise<any>;
1949
+ /**
1950
+ * Highlight + center on the closest physical instance of an amenity.
1951
+ * The amenity is resolved against `amenities.getDistinct()` (venue-wide,
1952
+ * deduped); the closest waypoint to the kiosk is picked; the active floor
1953
+ * is switched if that instance lives on another one.
1954
+ *
1955
+ * This is the right call from a venue-wide list ("here are all the
1956
+ * bathrooms in the building, take me to the closest one"). For taps on
1957
+ * a specific resolved POI (e.g. a search result that already names one
1958
+ * instance), use `highlightPOI` instead.
1959
+ */
1960
+ highlightAmenity(amenityId: string | number): Promise<void>;
1961
+ /** Which floor owns this waypoint, by matching mapId against the floor's
1962
+ * `mapId` (or `id` as fallback). Used to switch floors when routing /
1963
+ * highlighting hits an instance on a different one. */
1964
+ private findFloorForWaypoint;
284
1965
  getCameraPosition(): CameraState | null;
285
1966
  getMap(): Map | null;
1967
+ /**
1968
+ * Hide one or more layers by id — a public, always-live counterpart to
1969
+ * `debug.hide()` for consumers that want to toggle arbitrary layers
1970
+ * without reaching into the console-facing debug API. Sticky: the
1971
+ * override is re-asserted across floor changes, `setPOIFilter`, view-mode
1972
+ * toggles and theme swaps until `showLayers` undoes it. Ids absent from
1973
+ * the active style are skipped silently. Returns the ids actually found
1974
+ * and hidden.
1975
+ */
1976
+ hideLayers(layerIds: string[]): string[];
1977
+ /**
1978
+ * Undo `hideLayers` for these ids. Each layer returns to whatever
1979
+ * visibility the SDK's own state — current floor, POI filter, view mode —
1980
+ * says it should have; it is **not** forced to `visible`. A layer the SDK
1981
+ * is independently keeping hidden (another floor's layers, an
1982
+ * off-view-mode extrusion) stays hidden rather than being force-revealed.
1983
+ * This is the correct inverse of `hideLayers` (mirrors `debug.restore()` —
1984
+ * see `debugLayers.ts` for why a blanket "show" is usually the wrong
1985
+ * undo). Returns the ids that actually had an override to release.
1986
+ */
1987
+ showLayers(layerIds: string[]): string[];
1988
+ /**
1989
+ * Whether a layer is currently rendering (`visibility !== 'none'`).
1990
+ * `false` for a layer absent from the active style.
1991
+ */
1992
+ isLayerVisible(layerId: string): boolean;
1993
+ /**
1994
+ * Put this instance on `window` so a kiosk running in a browser can be
1995
+ * driven from devtools — `mm.debug.help()`, `mm.getMap()`, `mm.setTheme(…)`.
1996
+ * Debug builds only: nothing is exposed unless `options.debug` is on, and
1997
+ * `options.debugGlobal` renames the key (or `false` opts out entirely).
1998
+ *
1999
+ * Refuses to clobber a key that already holds something that isn't a
2000
+ * MinuteMaps — a kiosk shell with its own `window.mm` shouldn't lose it to
2001
+ * a dev-mode convenience.
2002
+ */
2003
+ private exposeDebugGlobal;
2004
+ /** Drop the `window` handle, but only if it still points at this instance. */
2005
+ private releaseDebugGlobal;
286
2006
  destroy(): void;
287
2007
  setCurrentFloor(floor: Floor): Promise<void>;
2008
+ /**
2009
+ * Filter the route-line / route-halo layers to only render segments
2010
+ * whose `floorId` matches the active floor (or features that carry no
2011
+ * `floorId` at all — the straight-line fallback, which we want visible
2012
+ * on every floor since it has no floor membership to filter against).
2013
+ *
2014
+ * Features are tagged with the JACS pixel `mapId` (that's what flows
2015
+ * through the route point's `mapId`), so the filter compares against
2016
+ * the active floor's `mapId`, NOT its `id` — those are two different
2017
+ * JACS identifiers (`floor.id` is the building-floor record; `mapId`
2018
+ * is the SVG asset). We accept the floor's `id` here for convenience
2019
+ * and resolve to `mapId` via `getFloors()`.
2020
+ *
2021
+ * Applied imperatively rather than baked into the theme JSON so the
2022
+ * filter tracks runtime floor changes without restyling the map.
2023
+ */
2024
+ private updateRouteFloorFilter;
288
2025
  isReady(): boolean;
289
2026
  private setFloorLayerVisibility;
290
2027
  private getBoundsPadding;
2028
+ /**
2029
+ * Shrink per-side padding if the requested insets would leave no room.
2030
+ * `cameraForBounds` / `fitBounds` silently fail ("Map cannot fit within
2031
+ * canvas") when an axis's total padding meets or exceeds that axis — cap
2032
+ * each axis's total at 80% so a fit always has space to land.
2033
+ */
2034
+ private clampPadding;
291
2035
  private getVenueBounds;
2036
+ /**
2037
+ * Resolve `options.maxBounds` into the actual pan/zoom-out cap. `false`
2038
+ * disables it, explicit bounds pass through as-is, and a number (or the
2039
+ * unset default of 3) scales the venue's own bounds outward around its
2040
+ * center — see `scaleBounds`.
2041
+ *
2042
+ * The unset default is also floored at `DEFAULT_MIN_MAX_BOUNDS_SPAN_M` per
2043
+ * side. MapLibre won't zoom out past the point where `maxBounds` fills the
2044
+ * viewport, so a small venue's 3x box would otherwise raise the effective
2045
+ * zoom-out floor above `minZoom` and show far less surrounding map than a
2046
+ * large venue does. An explicit number is a deliberate leash and is left as-is.
2047
+ */
2048
+ private getMaxBounds;
2049
+ /**
2050
+ * Opening-framing policy applied once after the initial floor fit.
2051
+ * - `initialPitch`: tilt to this and re-fit the building footprint so the
2052
+ * kiosk opens on a tilted building instead of a flat top-down plan.
2053
+ * - `minZoomBelowInitialFit`: clamp the map's minZoom to
2054
+ * `(fitZoom − margin)` so visitors can't pull back to the empty region.
2055
+ * Both are no-ops when their option is unset.
2056
+ */
2057
+ private applyInitialFraming;
292
2058
  private applyInitialViewFromVenue;
293
2059
  private loadAndPatchVenueStyle;
294
2060
  private ensureFloorLayersFromStyle;
@@ -296,5 +2062,113 @@ declare class MinuteMaps {
296
2062
  }
297
2063
  declare function createMinuteMapsSDK(config: SDKConfig): MinuteMaps;
298
2064
 
299
- export { MinuteMaps, createMinuteMapsSDK };
300
- export type { Amenity, AmenityWithFloor, Bounds, CameraState, Destination, EventCallback, Floor, FloorMetadata, JMapAuth, JMapConfig, JacsAuth, JacsConfig, MapEvent, POI, POISearchResult, SDKConfig, SDKOptions, ViewOptions, WayfindCenterMode, Waypoint };
2065
+ type TransitionStep = Extract<WayfindStep, {
2066
+ type: 'transition';
2067
+ }>;
2068
+ type RouteFloorSection = {
2069
+ /** Floor (JACS `mapId`) this section is on. `null` only for a degenerate
2070
+ * floorless route (straight-line fallback with no `mapId`). */
2071
+ floorId: number | null;
2072
+ /** This floor's steps, each with its index into the original flat array
2073
+ * so the consumer can call `setActiveStep` / highlight by index. */
2074
+ steps: Array<{
2075
+ step: WayfindStep;
2076
+ index: number;
2077
+ }>;
2078
+ /** Index of this section's first step in the original array — the target
2079
+ * for `setActiveStep` when advancing INTO this section. */
2080
+ firstStepIndex: number;
2081
+ /** The transition step that leaves this floor for the next section, if
2082
+ * any. Absent on the final section. Its `text` ("Take the elevator to
2083
+ * Basement") makes a good "continue" button label. */
2084
+ exit?: {
2085
+ step: TransitionStep;
2086
+ index: number;
2087
+ };
2088
+ };
2089
+ /**
2090
+ * Group steps into per-floor sections. Single-floor routes return one
2091
+ * section (so a consumer can keep its whole-route view for that case).
2092
+ */
2093
+ declare function groupStepsIntoFloorSections(steps: WayfindStep[]): RouteFloorSection[];
2094
+ /**
2095
+ * Which section is "active" given the active step index — the last section
2096
+ * whose `firstStepIndex` is at or before `activeStepIndex`. Returns 0 when
2097
+ * nothing matches (e.g. index points at the leading transition, which
2098
+ * shouldn't happen since routes start with a depart step).
2099
+ */
2100
+ declare function activeSectionIndex(sections: RouteFloorSection[], activeStepIndex: number): number;
2101
+
2102
+ /** True when an amenity is a vertical-circulation connector. The provider
2103
+ * stamps `_connector` on every synthetic elevator / stairs / escalator, which
2104
+ * is the reliable signal — `extensors.iconName` is only the *display* glyph
2105
+ * and may be any CMS-assigned icon (we still honour it as a fallback for
2106
+ * amenities authored with a connector icon name directly). */
2107
+ declare function isConnectorAmenity(amenity: AmenityLike): boolean;
2108
+ type LocaleField = {
2109
+ locale?: string;
2110
+ uriPath?: string;
2111
+ };
2112
+ type UriField = {
2113
+ mimeType?: string;
2114
+ resourceType?: string;
2115
+ locales?: LocaleField[];
2116
+ };
2117
+ type AmenityLike = {
2118
+ id: number | string;
2119
+ iconId?: string;
2120
+ uris?: UriField[] | null;
2121
+ /** Inline SVG markup. Used by the SDK for synthetic connector
2122
+ * amenities (elevator / stairs / escalator) where the CMS has no
2123
+ * uploaded icon to fetch. When set, this short-circuits the
2124
+ * `uris[].locales[].uriPath` lookup. */
2125
+ svg?: string;
2126
+ /** Free-form CMS metadata. When `extensors.iconName` names a curated
2127
+ * Material Symbols icon, the SDK renders it from the bundled registry
2128
+ * (no upload, no network) — see `pickMaterialSvg`. */
2129
+ extensors?: Record<string, unknown> | null;
2130
+ /** Set by the JACS provider on synthetic vertical-circulation amenities
2131
+ * (elevator / stairs / escalator built from path types). The reliable
2132
+ * connector signal — `extensors.iconName` is the *display* glyph, which
2133
+ * may be any CMS-assigned icon, not the connector kind. */
2134
+ _connector?: boolean;
2135
+ };
2136
+ type ResolvedIconSource = {
2137
+ /** Map image id to register/reference. Shared across amenities for
2138
+ * connectors (preset) and curated Material icons (`material-<name>`). */
2139
+ iconId: string;
2140
+ /** Source for `composeAmenityBitmap` — exactly one of url / inlineSvg. */
2141
+ source: {
2142
+ url?: string;
2143
+ inlineSvg?: string;
2144
+ };
2145
+ /**
2146
+ * Where the artwork came from. The map doesn't care — it rasterises all
2147
+ * three the same way — but a DOM consumer must, because provenance decides
2148
+ * both trust and styling:
2149
+ *
2150
+ * - `material` — from the SDK's bundled registry. Ours, so it's safe to
2151
+ * inline into the DOM, and safe to recolour (it's a monochrome glyph).
2152
+ * - `inline` — an `svg` string off the CMS record. **Author-supplied
2153
+ * markup**: an inline `<svg>` can carry `<script>`, so render it through
2154
+ * an `<img src="data:…">` (which never executes script), not
2155
+ * `dangerouslySetInnerHTML`.
2156
+ * - `upload` — a URL to a CMS-uploaded file. Also author-supplied, also an
2157
+ * `<img>`; and it arrives in whatever colours the author chose, so don't
2158
+ * assume you can tint it to match a badge.
2159
+ */
2160
+ kind: 'material' | 'inline' | 'upload';
2161
+ };
2162
+ /**
2163
+ * Pure icon-source resolution by precedence — no map/DOM side effects, so it's
2164
+ * unit-testable:
2165
+ * 1. inline svg — explicit inline-SVG override (rare)
2166
+ * 2. extensors.iconName — curated Material icon (bundled, shared bitmap);
2167
+ * also how synthetic connectors render now
2168
+ * 3. uris[].uriPath — legacy / custom-uploaded SVG (fetched)
2169
+ * Returns null when the amenity has no resolvable icon.
2170
+ */
2171
+ declare function resolveAmenityIconSource(amenity: AmenityLike, preferredLocale?: string): ResolvedIconSource | null;
2172
+
2173
+ export { BUILDING_NAME_EXTENSOR_KEY, DAY_KEYS, IMAGE_ALT_EXTENSOR_KEY, MinuteMaps, OPEN_HOURS_EXTENSOR_KEY, OPEN_HOURS_VERSION, PHONE_EXTENSOR_KEY, POINT_OF_INTEREST_EXTENSOR_KEY, RESERVED_EXTENSOR_PREFIX, activeSectionIndex, createMinuteMapsSDK, getOpenStatus, groupStepsIntoFloorSections, isConnectorAmenity, parseBuildingName, parseImageAlt, parseOpenHours, parsePhone, parsePointOfInterest, resolveAmenityIconSource };
2174
+ export type { Amenity, AmenityBadgeStyle, AmenityWithFloor, Bounds, BoundsPadding, CameraState, DayKey, Destination, DestinationPhone, EventCallback, Floor, FloorMetadata, HoursRange, JMapAuth, JMapConfig, JacsAuth, JacsConfig, MapEvent, OpenHours, OpenHoursTransition, OpenStatus, OpenStatusOptions, POI, POISearchResult, ResolvedIconSource, RouteFloorSection, RoutePoint, RoutingOptions, SDKConfig, SDKOptions, ThemeName, TransitionStep, ViewOptions, WayfindCenterMode, WayfindStep, Waypoint, Zone };