### Start Local Development Server

Source: https://github.com/smplrspace/docs/blob/next/README.md

Starts a local development server for live preview. Changes are reflected without server restart.

```bash
$ yarn start
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/smplrspace/docs/blob/next/README.md

Installs project dependencies using Yarn. This is the first step before running any other commands.

```bash
$ yarn
```

--------------------------------

### Start Viewer

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/map/map.md

Initiates an interactive viewer session with various configuration options.

```APIDOC
## Start the viewer

To initiate an interactive viewer session, use the following code.

```ts
map.startViewer({
  spaceIds?: string[]
  hash?: boolean | string
  fitNewSpacesInScreen?: boolean
  loadingMessage?: string
  forceLoader?: boolean
  onReady?: () => void
  onError?: (errorMessage: string) => void
  onSpaceClick?: ({ space, levelIndex }: { space: object | undefined; levelIndex: number }) => void
  hideNavigationButtons?: boolean
  hideLevelPicker?: boolean
  hideControls?: boolean
  controlsPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center-left' | 'center-right'
  legendPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
  cameraPlacement?: PartialMapCameraPlacement
  search?: boolean
  protectScroll?: boolean
  map3dBuildings?: boolean
  enableSatelliteButton?: boolean
}) => Promise<void>
```

### Parameters

- `spaceIds` (string[]) - _optional_ - lets you specify the Smplrspace ID ("spc_xxx") of the spaces to render on the map when initializing the viewer. You can also do that dynamically as described on the [Building page](/api-reference/map/buildings).
- `hash` (boolean | string) - _optional_ - lets you choose whether to automatically sync the map location to the hash fragment of the page's URL. This makes it for easy to share links to specific map locations. It relies on Mapbox's corresponding [parameter](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-parameters) which supports turning it on (the hash would be the whole URL hash), or providing a custom hash key to avoid conflict with other hash parameters. _Default value: false_.
- `fitNewSpacesInScreen` (boolean) - _optional_ - lets you choose whether to automatically recenter the map to fit all the spaces when the spaces rendered on the map change. You can also center the map using [`fitAllSpacesInScreen`](#fit-all-spaces-in-screen). _Default value: true._
- `loadingMessage` (string) - _optional_ - lets you override the text displayed while the space is loading. This can be change dynamically as well, see [UI controls](#ui-controls). _Default value: "Loading map"_.
- `forceLoader` (boolean) - _optional_ - provides programmatic control to whether the loader should be displayed or not. By default we display it while loading the map and initial spaces provided by `spaceIds`, but you can control this if you load your own data as well. This option is more of a forced initial state, and then you can be change whether the loader is visible dynamically, see [UI controls](#ui-controls). _Default value: false._
- `onReady` (() => void) - _optional_ - is called once the viewer's initial render is done. You may alternatively use the promise returned by startViewer, which resolves when the viewer is ready.
- `onError` ((errorMessage: string) => void) - _optional_ - is called if an error occur that crashes the viewer. You may alternatively use the promise returned by startViewer to catch errors.
- `onSpaceClick` (({ space, levelIndex }: { space: object | undefined; levelIndex: number }) => void) - _optional_ - is called when the user clicks a 3D space, and provide data about which space and which level where clicked.
- `hideNavigationButtons` (boolean) - _optional_ - set this to true if you want the user to control the camera but want to remove the navigation buttons. Mouse, touch and keyboard inputs will work while the buttons are hidden. _Default value: false_
- `hideLevelPicker` (boolean) - _optional_ - set this to true if you want to remove the level picker from the viewer. Levels can still be controlled programmatically, so you could use your own buttons or logic. _Default value: false_
- `hideControls` (boolean) - _optional_ - set this to true if you want to remove *all* control buttons from the viewer. _Default value: false_
- `controlsPosition` ('top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center-left' | 'center-right') - _optional_ - lets you choose where the control buttons are rendered. _Default value: 'center-right'_.
- `legendPosition` ('top-left' | 'top-right' | 'bottom-left' | 'bottom-right') - _optional_ - lets you choose where the legend (if any is configured in the data layers) would be rendered. _Default value: 'top-left'_.
- `cameraPlacement` (PartialMapCameraPlacement) - _optional_ - set the initial position and direction of the camera. See [camera controls](/api-reference/map/custom-ux#set-the-camera-placement) for more details.
- `search` (boolean) - _optional_ - set this to true to add a search button on the top left corner of the map, letting you find places on the map by address, GPS coordinates, and more. This is using a custom Mapbox Geocoder, and clicking a result from the list will move the camera to the place of interest. _Default value: false_.
- `protectScroll` (boolean) - _optional_ - lets you force users to use cmd/ctrl + scroll to zoom on desktop, and two fingers to interact with the viewer on touch screens (leaving one-finger scroll free for the page). This allows you implement cooperative gestures easily in apps where the viewer is part of a scrollable page.
- `map3dBuildings` (boolean) - _optional_ - set this to false to disable Mapbox's 3D buildings rendering when starting the viewer. You can also control this dynamically using the methods described on the [Buildings page](/api-reference/map/buildings#control-3d-buildings). _Default value: true_.

### Returns

A promise that resolves when the viewer is ready.
```

--------------------------------

### Install Smplrspace NPM Loader

Source: https://context7.com/smplrspace/docs/llms.txt

Install the recommended NPM loader package for a fully-typed API. Use either npm or yarn.

```sh
npm install @smplrspace/smplr-loader
# OR
yarn add @smplrspace/smplr-loader
```

--------------------------------

### Install and Load Smplr.js via NPM

Source: https://github.com/smplrspace/docs/blob/next/docs/getting-started.md

Install the @smplrspace/smplr-loader package and use the loadSmplrJs function to asynchronously load the Smplr.js library. This method provides a fully typed API and auto-completion.

```sh
npm install @smplrspace/smplr-loader
# OR
yarn add @smplrspace/smplr-loader
```

```javascript
import { loadSmplrJs } from "@smplrspace/smplr-loader";

loadSmplrJs()
  .then((smplr) => {
    /* enjoy a fully typed API and auto-completion */
    const space = new smplr.Space({
      spaceId: "spc_xxx",
      clientToken: "pub_xxx",
      containerId: "xxx",
    });
    space.startViewer({
      preview: true,
      onReady: () => console.log("Viewer is ready"),
      onError: (error) => console.error("The viewer crashed", error),
    });
  })
  .catch((error) => console.error(error));
```

--------------------------------

### Using async/await with QueryClient

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/queryclient.md

Example demonstrating how to use the QueryClient with async/await syntax to fetch space data and handle potential errors.

```APIDOC
### Using async/await

```js
const smplrClient = new smplr.QueryClient({
  clientToken: "pub_xxx",
});

try {
  const space = await smplrClient.getSpace("spc_xxx");
  // do something with the data
} catch (error) {
  // handle the error
}
```
```

--------------------------------

### Start Editor Session

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/editor/editor.md

Initiates an editor session, loading the Smplrspace editor into the specified container.

```APIDOC
## Editor sessions

### Start a session

To initiate an editor session, use the following code.

```ts
editor.startSession({
  loadingMessage?: string
  onReady?: () => void
  onError?: (errorMessage: string) => void
}) => void
```

### Parameters

- **loadingMessage** (string) - Optional - Overrides the text displayed while the space is loading. Default value: "Loading the editor".
- **onReady** (function) - Optional - Called once the editor has successfully initialized.
- **onError** (function) - Optional - Called if an error occurs that crashes the editor.
```

--------------------------------

### Using Promise.then with QueryClient

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/queryclient.md

Example demonstrating how to use the QueryClient with Promise.then() and Promise.catch() syntax to fetch space data.

```APIDOC
### Using Promise.then

```js
const smplrClient = new smplr.QueryClient({
  clientToken: "pub_xxx",
});

smplrClient
  .getSpace("spc_xxx")
  .then((space) => {
    // do something with the data
  })
  .catch((error) => {
    // handle the error
  });
```
```

--------------------------------

### Draw Icons Swatches Example

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/color/legend.md

Provides a practical example of calling `drawIconsSwatches` to render a legend with specific icons, labels, and swatch height. Ensure the `containerId` matches an existing HTML element.

```typescript
smplr.Color.drawIconsSwatches({
  containerId: 'smplr-legend',
  icons: [
    {
      url: 'https://retail.smplrspace.io/img/electric.png',
      label: 'EV charging',
    },
    {
      url: 'https://retail.smplrspace.io/img/wheelchair.png',
      label: 'Reduced mobility',
    }
  ],
  height: 20
});
```

--------------------------------

### Start Viewer with Custom Options

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/space/custom-ux.md

Use this to configure the viewer's initial state and behavior. Options control rendering, camera, UI elements, and interaction.

```typescript
space.startViewer({
  // ...basicControls
  renderOptions?: SpaceRenderOptions
  topShownLevel?: number
  includeLevels?: number[]
  cameraPlacement?: {
    alpha?: number
    beta?: number
    radius?: number
    target?: {
      x?: number
      y?: number
      z?: number
    }
  },
  disableCameraControls?: boolean,
  disableCameraRotation?: boolean,
  autoRotate?: boolean,
  hideNavigationButtons?: boolean
  hideLevelPicker?: boolean
  hideControls?: boolean
  smallControls?: boolean
  darkControls?: boolean
  controlsPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center-left' | 'center-right'
  legendPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right',
  protectScroll?: boolean
  webGpuOptIn?: boolean
}) => void
```

--------------------------------

### Viewer Options

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/space/custom-ux.md

You can set a number of options when starting the viewer to customize its behavior and appearance. These options allow for fine-grained control over rendering, camera, and UI elements.

```APIDOC
## startViewer(options)

### Description
Starts the viewer with customizable options to control rendering, camera, and UI elements.

### Method
`space.startViewer(options: SpaceViewerOptions): void`

### Parameters
#### `options` (object) - Optional

- `renderOptions` (SpaceRenderOptions) - Optional - Options for rendering. Defaults to `{}`.
- `topShownLevel` (number) - Optional - The initial level to navigate to. See [Navigating levels](#navigate-levels).
- `includeLevels` (number[]) - Optional - A list of zero-based indices of levels to render. See [`includeLevels`](#control-which-levels-are-included-in-the-render).
- `cameraPlacement` ({ alpha?: number, beta?: number, radius?: number, target?: { x?: number, y?: number, z?: number } }) - Optional - Sets the initial position and direction of the camera. See [camera controls](./custom-ux#camera-controls).
- `disableCameraControls` (boolean) - Optional - If true, disables user camera manipulation (mouse, touch, keyboard) and removes zoom controls. Defaults to `false`.
- `disableCameraRotation` (boolean) - Optional - If true, forces a top-down view, matching 2D mode interactivity in 3D. Defaults to `false`.
- `autoRotate` (boolean) - Optional - If true, the viewer spins automatically. See [auto-rotate the viewer](#auto-rotate-the-viewer) for more controls. Defaults to `false`.
- `hideNavigationButtons` (boolean) - Optional - If true, hides navigation buttons but keeps mouse, touch, and keyboard input enabled. Defaults to `false`.
- `hideLevelPicker` (boolean) - Optional - If true, removes the level picker. Levels can still be controlled programmatically. Defaults to `false`.
- `hideControls` (boolean) - Optional - If true, removes all control buttons. Defaults to `false`.
- `smallControls` (boolean) - Optional - If true, reduces control button size from 32px to 24px. Defaults to `false`.
- `darkControls` (boolean) - Optional - If true, uses a dark style for control buttons. Defaults to `false`.
- `controlsPosition` ('top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center-left' | 'center-right') - Optional - Sets the position of the control buttons. Defaults to `'bottom-left'`.
- `legendPosition` ('top-left' | 'top-right' | 'bottom-left' | 'bottom-right') - Optional - Sets the position of the legend. Defaults to `'top-left'`.
- `protectScroll` (boolean) - Optional - If true, requires Cmd/Ctrl + scroll for zooming on desktop and two fingers on touch screens, allowing one-finger scroll for the page.
- `webGpuOptIn` (boolean) - Optional - If true, opts into WebGPU rendering. Falls back to WebGL if unavailable. Defaults to `false`.

### Request Example
```javascript
space.startViewer({
  renderOptions: { /* ... */ },
  topShownLevel: 1,
  cameraPlacement: {
    alpha: 0,
    beta: 0,
    radius: 1000,
    target: { x: 0, y: 0, z: 0 }
  },
  disableCameraControls: false,
  autoRotate: true,
  hideControls: false,
  controlsPosition: 'top-right',
  legendPosition: 'bottom-right',
  protectScroll: true,
  webGpuOptIn: true
});
```
```

--------------------------------

### Start Editor Session

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/editor/editor.md

Initiate an editor session using the `startSession` method. Customize the loading message and define callbacks for when the editor is ready or encounters an error.

```typescript
editor.startSession({
  loadingMessage?: string
  onReady?: () => void
  onError?: (errorMessage: string) => void
})
```

--------------------------------

### Get All Windows in Space (Sync)

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/doors-windows.md

Synchronously retrieves all windows within a specified space. Requires a `spaceId` and returns an array of `Opening` objects directly.

```typescript
smplrClient.getAllWindowsInSpaceFromCache(spaceId: string): Opening[]
```

--------------------------------

### Get All Windows in Space (Async)

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/doors-windows.md

Asynchronously retrieves all windows within a specified space. Requires a `spaceId` and returns a Promise resolving to an array of `Opening` objects.

```typescript
smplrClient.getAllWindowsInSpace(spaceId: string): Promise<Opening[]>
```

--------------------------------

### Get Windows on Level (Sync)

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/doors-windows.md

Synchronously retrieves all windows from a specific level within a space. Requires `spaceId` and `levelIndex`, returning an array of `Opening` objects directly.

```typescript
smplrClient.getWindowsOnLevelFromCache({
  spaceId: string
  levelIndex: number
}): Opening[]
```

--------------------------------

### Start Smplrspace Viewer Session

Source: https://context7.com/smplrspace/docs/llms.txt

Initiates an interactive 2D/3D viewer session. Configure rendering options, camera placement, and event handlers for mode changes and readiness. This method returns a promise that resolves when the viewer is ready.

```ts
import { loadSmplrJs } from "@smplrspace/smplr-loader";

loadSmplrJs().then((smplr) => {
  const space = new smplr.Space({
    spaceId: "spc_xxx",
    clientToken: "pub_xxx",
    containerId: "smplr-container",
  });

  space
    .startViewer({
      preview: true,          // show static preview with play button first
      mode: "3d",             // '2d' | '3d'
      allowModeChange: true,  // let user toggle 2D/3D
      onModeChange: (mode) => console.log("Mode changed to", mode),
      renderOptions: {
        backgroundColor: "#f5f5f5",
        walls: { alpha: 0.8 },
        grounds: { render: true },
      },
      cameraPlacement: {
        alpha: -Math.PI / 2,
        beta: 0.9,
        radius: 40,
        target: { x: 0, y: 0, z: 0 },
      },
      hideControls: false,
      hideLevelPicker: false,
      controlsPosition: "bottom-left",
      legendPosition: "top-left",
      protectScroll: true,
      onReady: () => console.log("Viewer is ready"),
      onError: (error) => console.error("Viewer crashed:", error),
    })
    .then(() => console.log("startViewer promise resolved"))
    .catch((err) => console.error(err));
});
```

--------------------------------

### Get Element Position on Screen

Source: https://context7.com/smplrspace/docs/llms.txt

Gets the screen (pixel) coordinates of a data element, useful for positioning custom tooltips or overlays. Requires a data layer to be added and the viewer to be initialized.

```typescript
const sensorLayer = space.addPointDataLayer({ id: "sensors", /* ... */ });

space.startViewer({
  onResize: () => {
    const pos = sensorLayer.getElementPositionOnScreen("s1");
    if (pos) {
      // pos: { screenX: number, screenY: number }
      setTooltipPosition({ x: pos.screenX, y: pos.screenY });
    }
  },
  // ...
});
```

--------------------------------

### Get Level Bounding Box

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/levels-rooms.md

Retrieves the bounding box of a space's floor plate as a polygon. Use this to get the overall dimensions of a level. The bounding box is always straight with respect to the (x, z) axes.

```typescript
smplrClient.getLevelBoundingBox({
  spaceId: string
  levelIndex: number
  padding?: number
}): Promise<{
  levelIndex: number
  x: number
  z: number
}[]>
```

--------------------------------

### DataLayerController.getElementPositionOnScreen

Source: https://context7.com/smplrspace/docs/llms.txt

Gets the screen (pixel) coordinates of a data element.

```APIDOC
## DataLayerController — getElementPositionOnScreen

Gets the screen (pixel) coordinates of a data element — useful for positioning custom React tooltips or overlays.

### Description
Retrieves the screen coordinates of a specific data element within a data layer, enabling precise placement of UI elements.

### Method
```ts
const sensorLayer = space.addPointDataLayer({ id: "sensors", /* ... */ });

space.startViewer({
  onResize: () => {
    const pos = sensorLayer.getElementPositionOnScreen("s1");
    if (pos) {
      // pos: { screenX: number, screenY: number }
      setTooltipPosition({ x: pos.screenX, y: pos.screenY });
    }
  },
  // ...
});
```
```

--------------------------------

### Initialize QueryClient

Source: https://context7.com/smplrspace/docs/llms.txt

Creates a client for programmatic queries against Smplrspace backend data. Requires the `smplr-loader` to be imported and the `clientToken` to be provided.

```typescript
import { loadSmplrJs } from "@smplrspace/smplr-loader";

loadSmplrJs().then((smplr) => {
  const smplrClient = new smplr.QueryClient({
    clientToken: "pub_xxx",
  });
});
```

--------------------------------

### Instantiate and Start Smplrspace Editor

Source: https://context7.com/smplrspace/docs/llms.txt

Embeds the Smplrspace floor plan editor into your application. Requires loading the smplr.js library and providing authentication details. Call `startSession` to initialize the editor with options like loading messages and callbacks for readiness and errors.

```typescript
loadSmplrJs().then((smplr) => {
  const editor = new smplr.Editor({
    spaceId: "spc_xxx",
    clientToken: "pub_xxx",
    containerId: "editor-container",
    user: {
      id: "user-123",        // your internal user ID
      name: "Jane Doe",
      picture: "https://example.com/avatars/jane.png",
    },
  });

  editor.startSession({
    loadingMessage: "Loading floor plan editor...",
    onReady: () => console.log("Editor ready"),
    onError: (err) => console.error("Editor error:", err),
  });

  // Clean up when done
  // editor.remove();
});
```

--------------------------------

### Initialize Smplrspace Space Viewer

Source: https://context7.com/smplrspace/docs/llms.txt

Creates an instance of the interactive floor plan viewer. Ensure you have loaded the smplr.js library first. Provide your unique space ID, client token, and the ID of the HTML container.

```ts
import { loadSmplrJs } from "@smplrspace/smplr-loader";

loadSmplrJs().then((smplr) => {
  const space = new smplr.Space({
    spaceId: "spc_xxx",         // unique space identifier
    clientToken: "pub_xxx",     // client-side API token
    containerId: "smplr-container", // id of the HTML div to render into
    whiteLabel: false,          // remove "Powered by Smplrspace" (paid add-on)
  });
});
```

--------------------------------

### Auto-Rotation

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/space/custom-ux.md

Controls the automatic rotation of the viewer around the space. Can be started with a specified speed and stopped.

```APIDOC
## Auto-Rotate Viewer

### Description
Enables or disables the automatic rotation of the viewer.

### Methods
- `space.startAutoRotation(speed?: number): void`
  - `speed` (number) - Optional. Sets the rotation speed. Defaults to `0.8`.
- `space.stopAutoRotation(): void`
```

--------------------------------

### Build Static Website Content

Source: https://github.com/smplrspace/docs/blob/next/README.md

Generates static website content into the 'build' directory, ready for hosting.

```bash
$ yarn build
```

--------------------------------

### Get Data Layer Controller

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/space/space.md

Retrieves the controller for a specific data layer using its ID.

```APIDOC
## getDataLayer

### Description
Retrieves the controller for a data layer by its unique identifier.

### Method
```ts
space.getDataLayer(id: string) => DataLayerController | undefined
```

### Parameters
- `id` (string) - The identifier of the data layer.
```

--------------------------------

### Start the viewer

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/map/map.md

Initiates an interactive viewer session. Use this to render spaces on the map, with options to control URL hash synchronization, fitting behavior, loading messages, and event handlers. It returns a promise that resolves when the viewer is ready or rejects if an error occurs.

```typescript
map.startViewer({
  spaceIds?: string[]
  hash?: boolean | string
  fitNewSpacesInScreen?: boolean
  loadingMessage?: string
  forceLoader?: boolean
  onReady?: () => void
  onError?: (errorMessage: string) => void
  onSpaceClick?: ({ space, levelIndex }: { space: object | undefined; levelIndex: number }) => void
  hideNavigationButtons?: boolean
  hideLevelPicker?: boolean
  hideControls?: boolean
  controlsPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center-left' | 'center-right'
  legendPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
  cameraPlacement?: PartialMapCameraPlacement
  search?: boolean
  protectScroll?: boolean
  map3dBuildings?: boolean
  enableSatelliteButton?: boolean
}) => Promise<void>
```

--------------------------------

### Get Polyline Midpoint

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/geometry.md

Finds the geometric center of a polyline. Useful for placing labels or anchors.

```typescript
smplrClient.getPolylineMidpoint({
  line: [
    {
      levelIndex: number,
      x: number,
      z: number,
      elevation: number
    }
  ]
}): {
  levelIndex: number
  x: number
  z: number
  elevation: number
}
```

--------------------------------

### Get Camera Placement

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/map/custom-ux.md

Retrieves the current camera's position, orientation, and zoom level.

```APIDOC
## Get Camera Placement

Retrieves the current state of the camera.

### `getCameraPlacement` Method

Returns an object representing the camera's current placement.

#### Signature

```ts
map.getCameraPlacement() => {
  pitch: number
  bearing: number
  zoom: number
  center: {
    lng: number
    lat: number
  }
}
```

#### Return Value

An object containing:

- **pitch** (number) - The angle in degrees of the camera's vertical position. `0` is top-down, `90` is ground level.
- **bearing** (number) - The angle in degrees of the camera's horizontal orientation. `0` is North, `90` is East.
- **zoom** (number) - The zoom level, ranging from `0` (world view) to `22` (detailed view).
- **center** (object) - The geographical center point the camera is targeting.
  - **lng** (number) - Longitude coordinate.
  - **lat** (number) - Latitude coordinate.
```

--------------------------------

### Start the interactive viewer session

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/space/space.md

Initiates an interactive viewer session with various configuration options. Use `preview: true` to avoid loading the space if the user does not intend to interact with it. The returned Promise can be used to handle readiness and errors as an alternative to callbacks.

```typescript
space.startViewer({
  preview?: boolean
  loadingMessage?: string
  renderingMessage?: string
  mode?: '2d' | '3d'
  allowModeChange?: boolean
  onModeChange?: (mode: '2d' | '3d') => void
  onReady?: () => void
  onError?: (errorMessage: string) => void
  onResize?: (containerRect: DOMRect) => void
  onVisibleLevelsChanged?: (visibleLevels: number[]) => void
  onObjectsUpdated?: () => void
  ...customUX: object
}) => Promise<void>
```

--------------------------------

### Start Auto-Rotation

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/space/custom-ux.md

Initiate automatic rotation of the viewer around the space. An optional speed parameter can be provided.

```typescript
space.startAutoRotation(speed?: number) => void
```

--------------------------------

### QueryClient Constructor

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/queryclient.md

Initializes a new instance of the QueryClient. Requires a clientToken for authentication.

```APIDOC
## Constructor

To create a QueryClient instance, initialise it as follow.

```ts
const smplrClient = new smplr.QueryClient({
  clientToken: string
});
```

- `clientToken` is an API token that is used to authenticate client-side requests. It is safe to have it exposed in your client code. You can manage your organisation's tokens in the Smplrspace app, by heading to the Developers page from the main menu. [More info](/guides/embedding#client-tokens).

:::caution Deprecation notice
`organizationId` was previously set on the `QueryClient` constructor. This is now deprecated. Pass `organizationId` directly to the query methods that require it, such as [`createSpace`](./spaces#createspace) and [`listSpaces`](./spaces#listspaces).
:::
```

--------------------------------

### Get a screenshot as a JS File

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/space/space.md

Returns the screenshot as a Javascript `File` object, suitable for uploading or further manipulation.

```APIDOC
## takeScreenshotToFile

### Description
Returns the screenshot as a Javascript `File` object. This can be used for uploading as `FormData` or for other programmatic manipulations.

### Method
```ts
space.takeScreenshotToFile({
  mode: '3d-scene' | 'full-viewer'
  width?: number
  height?: number
  forceRetinaPixelRatio?: boolean
  forceNonRetinaPixelRatio?: boolean
}) => Promise<File>
```

### Parameters
All arguments are the same as [`takeScreenshot`](#download-a-screenshot).
```

--------------------------------

### Get Polygon Center

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/geometry.md

Calculates the center point of a polygon. Supports single polygons or polygons with holes.

```typescript
smplrClient.getPolygonCenter({
  polygon: {
    levelIndex: number,
    x: number,
    z: number
  }[] | {
    levelIndex: number,
    x: number,
    z: number
  }[][]
}): {
  levelIndex: number
  x: number
  z: number
}
```

--------------------------------

### Deploy Website to GitHub Pages

Source: https://github.com/smplrspace/docs/blob/next/README.md

Builds the website and pushes it to the 'gh-pages' branch for GitHub Pages hosting. Requires GitHub username and SSH configuration.

```bash
$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
```

--------------------------------

### Check Segment Intersection

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/geometry.md

Determines if two line segments intersect. Each segment is defined by its start and end points.

```typescript
smplrClient.doSegmentsIntersect({
  segment1: {
    start: {
      levelIndex: number,
      x: number,
      z: number
    },
    end: {
      levelIndex: number,
      x: number,
      z: number
    }
  },
  segment2: {
    start: {
      levelIndex: number,
      x: number,
      z: number
    },
    end: {
      levelIndex: number,
      x: number,
      z: number
    }
  }
}): boolean
```

--------------------------------

### Map Constructor and startViewer

Source: https://context7.com/smplrspace/docs/llms.txt

Embeds a Mapbox-based geographic map with Smplrspace floor plans rendered in 3D at real-world locations.

```APIDOC
## Map — Constructor and startViewer

### Description
Embeds a Mapbox-based geographic map with Smplrspace floor plans rendered in 3D at real-world locations.

### Constructor
`new smplr.Map(options: { clientToken: string, containerId: string })

### Method
`map.startViewer(options: { spaceIds: string[], mode: '3d', fitNewSpacesInScreen: boolean, map3dBuildings: boolean, enableSatelliteButton: boolean, search: boolean, protectScroll: boolean, onSpaceClick: (event: { space: any, levelIndex: number }) => void, onReady: () => void, onError: (error: any) => void }): Promise<void>

### Request Example
```ts
loadSmplrJs().then((smplr) => {
  const map = new smplr.Map({
    clientToken: "pub_xxx",
    containerId: "map-container",
  });

  map
    .startViewer({
      spaceIds: ["spc_xxx", "spc_yyy"],
      mode: "3d",
      fitNewSpacesInScreen: true,
      map3dBuildings: true,
      enableSatelliteButton: true,
      search: true,
      protectScroll: true,
      onSpaceClick: ({ space, levelIndex }) => {
        console.log("Clicked space:", space, "level:", levelIndex);
      },
      onReady: () => console.log("Map ready"),
      onError: (err) => console.error(err),
    })
    .then(() => {
      map.flyToSpace("spc_xxx");
    });
});
```
```

--------------------------------

### Get All Furniture in Space (Async)

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/furniture.md

Asynchronously retrieves all furniture items within a specified space. Requires a spaceId.

```typescript
smplrClient.getAllFurnitureInSpace(spaceId: string): Promise<Furniture[]>
```

--------------------------------

### Initialize Smplr Map Instance

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/map/map.md

Instantiate the `smplr.Map` class to render the map viewer. Provide your `clientToken` for authentication. Optionally, specify a `containerId` or `container` element for rendering, and control error reporting with `disableErrorReporting`.

```typescript
const map = new smplr.Map({
  clientToken: string
  containerId?: string
  container?: HTMLElement
  disableErrorReporting?: boolean
}) => Map
```

--------------------------------

### Space Constructor

Source: https://context7.com/smplrspace/docs/llms.txt

Creates an instance of the interactive floor plan viewer. Requires spaceId, clientToken, and a containerId for rendering.

```APIDOC
## Space Constructor

### Description
Creates an instance of the interactive floor plan viewer.

### Parameters
#### Path Parameters
- **spaceId** (string) - Required - unique space identifier
- **clientToken** (string) - Required - client-side API token
- **containerId** (string) - Required - id of the HTML div to render into
- **whiteLabel** (boolean) - Optional - remove "Powered by Smplrspace" (paid add-on)

### Request Example
```javascript
import { loadSmplrJs } from "@smplrspace/smplr-loader";

loadSmplrJs().then((smplr) => {
  const space = new smplr.Space({
    spaceId: "spc_xxx",
    clientToken: "pub_xxx",
    containerId: "smplr-container",
    whiteLabel: false,
  });
});
```
```

--------------------------------

### space.updateRenderOptions / space.resetRenderOptionsToDefault / space.resetRenderOptionsToInitial

Source: https://context7.com/smplrspace/docs/llms.txt

Dynamically updates visual rendering options (walls, grounds, objects, etc.) after the viewer has started.

```APIDOC
## space.updateRenderOptions

Dynamically updates visual rendering options (walls, grounds, objects, etc.) after the viewer has started.

### Description
Allows modification of rendering properties like wall transparency or object visibility, with options to reset to default or initial settings.

### Method
```ts
// Make walls semi-transparent to "see through" them
space.updateRenderOptions({
  walls: { alpha: 0.3 },
  objects: { render: false },
});

// Restore defaults
space.resetRenderOptionsToDefault();

// Restore to the options provided at startViewer
space.resetRenderOptionsToInitial();
```
```

--------------------------------

### Get Space Assetmap From Cache

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/spaces.md

This is the synchronous equivalent of getSpaceAssetmap. It retrieves the space's entity list directly from the cache.

```typescript
smplrClient.getSpaceAssetmapFromCache(spaceId: string): unknown
```

--------------------------------

### QueryClient Constructor

Source: https://context7.com/smplrspace/docs/llms.txt

Creates a client for programmatic queries against Smplrspace backend data.

```APIDOC
## QueryClient — Constructor

Creates a client for programmatic queries against Smplrspace backend data.

### Description
Initializes a QueryClient instance used for making requests to the Smplrspace backend.

### Method
```ts
import { loadSmplrJs } from "@smplrspace/smplr-loader";

loadSmplrJs().then((smplr) => {
  const smplrClient = new smplr.QueryClient({
    clientToken: "pub_xxx",
  });
});
```
```

--------------------------------

### Get All Furniture in Space (From Cache)

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/furniture.md

Synchronously retrieves all furniture items within a specified space from the cache. Requires a spaceId.

```typescript
smplrClient.getAllFurnitureInSpaceFromCache(spaceId: string): Furniture[]
```

--------------------------------

### Get a screenshot as Base64 string

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/space/space.md

Returns a Base64 encoded string of the image, which can be used for various purposes including display or transmission.

```APIDOC
## takeScreenshotToString

### Description
Returns a string containing the Base64 encoded image. This can be manipulated, uploaded, or downloaded as per specific requirements.

### Method
```ts
space.takeScreenshotToString({
  mode: '3d-scene' | 'full-viewer'
  width?: number
  height?: number
  forceRetinaPixelRatio?: boolean
  forceNonRetinaPixelRatio?: boolean
}) => Promise<string>
```

### Parameters
All arguments are the same as [`takeScreenshot`](#download-a-screenshot).
```

--------------------------------

### Get Furniture By ID

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/furniture.md

Extracts a single piece of furniture from a space using its unique identifier. Returns null if the furniture is not found.

```typescript
smplrClient.getFurnitureById({
  spaceId: string
  furnitureId: string
}): Promise<Furniture | null>
```

--------------------------------

### Initialize and Start Smplrspace Map Viewer

Source: https://context7.com/smplrspace/docs/llms.txt

Embed a Mapbox-based map with Smplrspace floor plans. Configure space IDs, viewing mode, interaction options, and event handlers for clicks and readiness.

```typescript
loadSmplrJs().then((smplr) => {
  const map = new smplr.Map({
    clientToken: "pub_xxx",
    containerId: "map-container",
  });

  map
    .startViewer({
      spaceIds: ["spc_xxx", "spc_yyy"],
      mode: "3d",
      fitNewSpacesInScreen: true,
      map3dBuildings: true,
      enableSatelliteButton: true,
      search: true,
      protectScroll: true,
      onSpaceClick: ({ space, levelIndex }) => {
        console.log("Clicked space:", space, "level:", levelIndex);
      },
      onReady: () => console.log("Map ready"),
      onError: (err) => console.error(err),
    })
    .then(() => {
      map.flyToSpace("spc_xxx");
    });
});
```

--------------------------------

### Map Constructor

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/map/map.md

Initializes a new Map instance to render the Smplrspace map viewer. Requires a client token for authentication and optionally accepts container information and error reporting settings.

```APIDOC
## Constructor

To create a Map instance, initialise it as follow.

```ts
const map = new smplr.Map({
  clientToken: string
  containerId?: string
  container?: HTMLElement
  disableErrorReporting?: boolean
}) => Map
```

### Parameters

- `clientToken` (string) - Required - An API token used to authenticate client-side requests. Manage tokens in the Smplrspace app under the Developers page.
- `containerId` (string) - Optional - The 'id' of the HTML 'div' element where the viewer should be rendered. Only IDs are supported.
- `container` (HTMLElement) - Optional - An alternative to `containerId` to provide the HTML element directly.
- `disableErrorReporting` (boolean) - Optional - Set to `true` to disable automated error reporting to Sentry. Disabling this means Smplrspace will not automatically detect integration errors.
```

--------------------------------

### Get Points Bounding Box

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/geometry.md

Computes the axis-aligned bounding box for a set of points. Optional padding can be added around the box.

```typescript
smplrClient.getPointsBoundingBox({
  points: {
    levelIndex: number,
    x: number,
    z: number
  }[],
  padding?: number
}): {
  levelIndex: number
  x: number
  z: number
}[]
```

--------------------------------

### Get Rectangle Corners

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/geometry.md

Retrieves the corner coordinates of a rectangle based on its center, dimensions, and rotation. This is often used after fitting a rectangle with `fitRectangleInPolygon`.

```typescript
smplrClient.getRectangleCorners({
  center: {
    levelIndex: number
    x: number
    z: number
  }
  width: number
  height: number
  rotation: number
}): {
  levelIndex: number
  x: number
  z: number
}[]
```

--------------------------------

### Initialize QueryClient

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/queryclient.md

Instantiate the QueryClient with your API token. The client token is safe to expose in client-side code.

```typescript
const smplrClient = new smplr.QueryClient({
  clientToken: string
});
```

--------------------------------

### Get Furniture in Polygon (From Cache)

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/furniture.md

Synchronously retrieves furniture items contained within a polygon from the cache. Requires spaceId and polygon coordinates.

```typescript
smplrClient.getFurnitureInPolygonFromCache({
  spaceId: string
  polygon: {
    levelIndex: number
    x: number
    z: number
  }[] | {
    levelIndex: number
    x: number
    z: number
  }[][]
}): Furniture[]
```

--------------------------------

### Check if the viewer is ready

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/map/map.md

Checks if the viewer has finished initializing and is ready for API methods to be called.

```APIDOC
## Check if the viewer is ready

### Description
Checks if the viewer has finished initializing and is ready for API methods to be called.

### Method
```ts
map.isViewerStarted() => boolean
```
```

--------------------------------

### space.startViewer

Source: https://context7.com/smplrspace/docs/llms.txt

Initiates an interactive 2D/3D viewer session inside the container element. Accepts various options to customize the viewer's behavior and appearance.

```APIDOC
## space.startViewer

### Description
Initiates an interactive 2D/3D viewer session inside the container element.

### Parameters
#### Path Parameters
- **preview** (boolean) - Optional - show static preview with play button first
- **mode** (string) - Optional - '2d' | '3d'
- **allowModeChange** (boolean) - Optional - let user toggle 2D/3D
- **onModeChange** (function) - Optional - callback function when mode changes
- **renderOptions** (object) - Optional - options for rendering (e.g., backgroundColor, walls, grounds)
- **cameraPlacement** (object) - Optional - initial camera position and target
- **hideControls** (boolean) - Optional - hide viewer controls
- **hideLevelPicker** (boolean) - Optional - hide level picker
- **controlsPosition** (string) - Optional - position of controls (e.g., "bottom-left")
- **legendPosition** (string) - Optional - position of legend (e.g., "top-left")
- **protectScroll** (boolean) - Optional - protect scroll behavior
- **onReady** (function) - Optional - callback when viewer is ready
- **onError** (function) - Optional - callback when viewer encounters an error

### Request Example
```javascript
import { loadSmplrJs } from "@smplrspace/smplr-loader";

loadSmplrJs().then((smplr) => {
  const space = new smplr.Space({
    spaceId: "spc_xxx",
    clientToken: "pub_xxx",
    containerId: "smplr-container",
  });

  space
    .startViewer({
      preview: true,
      mode: "3d",
      allowModeChange: true,
      onModeChange: (mode) => console.log("Mode changed to", mode),
      renderOptions: {
        backgroundColor: "#f5f5f5",
        walls: { alpha: 0.8 },
        grounds: { render: true },
      },
      cameraPlacement: {
        alpha: -Math.PI / 2,
        beta: 0.9,
        radius: 40,
        target: { x: 0, y: 0, z: 0 },
      },
      hideControls: false,
      hideLevelPicker: false,
      controlsPosition: "bottom-left",
      legendPosition: "top-left",
      protectScroll: true,
      onReady: () => console.log("Viewer is ready"),
      onError: (error) => console.error("Viewer crashed:", error),
    })
    .then(() => console.log("startViewer promise resolved"))
    .catch((err) => console.error(err));
});
```
```

--------------------------------

### Get Furniture on Level (Async)

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/furniture.md

Asynchronously retrieves all furniture items on a specific level within a given space. Requires spaceId and levelIndex.

```typescript
smplrClient.getFurnitureOnLevel({
  spaceId: string
  levelIndex: number
}): Promise<Furniture[]>
```

--------------------------------

### Editor Constructor and startSession

Source: https://context7.com/smplrspace/docs/llms.txt

Embeds the full Smplrspace floor plan editor into your app with third-party authenticated sessions.

```APIDOC
## Editor — Constructor and startSession

Embeds the full Smplrspace floor plan editor into your app with third-party authenticated sessions.

```ts
loadSmplrJs().then((smplr) => {
  const editor = new smplr.Editor({
    spaceId: "spc_xxx",
    clientToken: "pub_xxx",
    containerId: "editor-container",
    user: {
      id: "user-123",        // your internal user ID
      name: "Jane Doe",
      picture: "https://example.com/avatars/jane.png",
    },
  });

  editor.startSession({
    loadingMessage: "Loading floor plan editor...",
    onReady: () => console.log("Editor ready"),
    onError: (err) => console.error("Editor error:", err),
  });

  // Clean up when done
  // editor.remove();
});
```
```

--------------------------------

### Get API Version

Source: https://github.com/smplrspace/docs/blob/next/docs/api-reference/queryclient/utils.md

Retrieve the API version to programmatically ensure your client version matches the API version. This is useful for maintaining compatibility.

```typescript
smplrClient.getApiVersion() => Promise<string>
```