@diginestai/core — Core React SDK

@diginestai/core is the primary entry point for the DigiNest Maps SDK. It wires together MapLibre GL JS, deck.gl, PMTiles, and Zustand into a composable React component and hook API for building indoor and outdoor mapping applications.

---

Installation

pnpm add @diginestai/core

Requires a fine-grained GitHub PAT with read:packages scope. See the Installation guide for .npmrc setup.

---

Quick Start

import { SpatialProvider, SpatialMap } from '@diginestai/core';

export default function App() {
  return (
    <SpatialProvider>
      <SpatialMap
        style="pmtiles://https://tiles.example.com/basemap.pmtiles"
        center={[-122.4, 37.78]}
        zoom={16}
        onFloorChange={(floor) => console.log('active floor:', floor.ordinal)}
      />
    </SpatialProvider>
  );
}

---

<SpatialProvider>

Mounts the root Zustand store and registers the pmtiles:// MapLibre protocol (module-level singleton — safe to render once at app root).

Props

Prop	Type	Default	Description
children	ReactNode	—	App tree.
workerConfig	WorkerConfig	{}	Override Comlink worker URLs for IMDF, navigation, RTLS, and PMTiles workers.
persistKey	string	'spatial'	IndexedDB key for zustand/middleware/persist state hydration.

---

<SpatialMap>

The top-level map container. Hosts the MapLibre GL JS instance and exposes an imperative ref handle.

Key Props

Prop	Type	Default	Description
style	string | StyleSpecification	—	MapLibre style URL or inline style object. Supports pmtiles:// prefix.
center	[number, number]	[0, 0]	Initial longitude/latitude.
zoom	number	14	Initial zoom level.
pitch	number	0	Initial pitch in degrees.
bearing	number	0	Initial bearing in degrees.
onLoad	(map: MapLibreMap) => void	—	Fires after MapLibre's load event.
onFloorChange	(floor: LevelFeature) => void	—	Fires when the active floor changes.
renderOptions	RenderOptions	—	Controls exploded view, satellite basemap blend, and label visibility.
theme	SpatialTheme	lightTheme	Theme applied via CSS custom properties.

---

Hooks

useMap()

Returns the live MapLibre Map instance and spatial store reference.

import { useMap } from '@diginestai/core';

const { map, store } = useMap();
map.flyTo({ center: [-122.4, 37.78], zoom: 18 });

Return	Type	Description
map	MapLibreMap | null	Raw MapLibre GL JS map instance.
store	SpatialStore	Zustand store handle.

---

useFloor()

Subscribes to the active floor state.

import { useFloor } from '@diginestai/core';

const { activeFloor, floors, setFloor } = useFloor();

Return	Type	Description
activeFloor	LevelFeature | null	Currently displayed floor.
floors	LevelFeature[]	All floors in the loaded building.
setFloor	(id: string) => void	Switch the active floor.

---

useRTLS(options?)

Connects an RTLS adapter and surfaces live position updates.

import { useRTLS } from '@diginestai/core';
import { SewioAdapter } from '@diginestai/rtls';

const { positions, health } = useRTLS({
  adapter: new SewioAdapter({ url: 'wss://sewio.example.com/realtime' }),
});

Option	Type	Description
adapter	RTLSAdapter	Any adapter from @diginestai/rtls.
floorFilter	boolean	Only surface positions matching the active floor (default: true).

---

useEditor()

Accesses Terra Draw editor state and undo/redo controls (powered by zundo, 50-step cap).

import { useEditor } from '@diginestai/core';

const { mode, setMode, undo, redo, features } = useEditor();

Return	Type	Description
mode	EditorMode	Active draw mode ('wall', 'door', 'select', etc.).
setMode	(mode: EditorMode) => void	Switch draw mode.
undo	() => void	Undo last edit.
redo	() => void	Redo last undone edit.
features	DrawFeature[]	Current feature collection.

---

Rendering Pipeline

MapLibre GL JS hosts the base layer stack (z 0–990). deck.gl layers interleave via @deck.gl/mapbox MapboxOverlay — one shared WebGL context, no double-buffer.

Z-order	Layer
0	Basemap
300	Floor fills (IMDF)
700	Data layers
800	Heatmap
950	RTLS trails
980	BlueDot
990	Selection highlight

Critical rule: Never recreate a MapLibre source or layer on re-render. Updates use setData, setPaintProperty, or setFeatureState. Live sensor updates use setFeatureState (not setData); batched per requestAnimationFrame. Feature state map is capped at ~10k keys (LRU) to avoid MapLibre issue #6633 zoom lag.

---

State Slices (Zustand)

Slice	Key state
buildingSlice	Active building, IMDF data, PMTiles archive URL
floorSlice	Active floor ordinal, floor list, exploded view offset
cameraSlice	Viewport center/zoom/pitch, camera mode
dataLayerSlice	Layer registry, visibility flags, color scale configs
selectionSlice	Selected feature ID, selection highlight state
editorSlice	Draw mode, feature collection, zundo temporal state
rtlsSlice	Adapter registry, position cache, health map
themeSlice	Active SpatialTheme, mode ('light' | 'dark')
wayfindingSlice	Origin/destination, active route, floor transitions

State persists to IndexedDB via zustand/middleware/persist.