@multisetai/vps 1.1.0 → 2.1.0

package/README.md

@@ -1,473 +1,402 @@
 # MultiSet VPS WebXR
 
-MultiSet VPS WebXR is a TypeScript SDK that enables developers to integrate MultiSet's Visual Positioning System (VPS) capabilities into WebXR applications. It provides precise 6-DOF (6 degrees of freedom) localization by matching camera frames against cloud-hosted maps, allowing AR applications to understand their position and orientation in physical space.
+TypeScript SDK for integrating MultiSet's Visual Positioning System (VPS) into WebXR applications. Provides 6-DOF localization by matching camera frames against cloud-hosted maps.
 
-## Features
+## Architecture
 
-- **Core Client** (`@multisetai/vps/core`) - Authentication and API client for MultiSet VPS services
-- **WebXR Controller** (`@multisetai/vps/webxr`) - Three.js WebXR session management and frame capture
-- **Framework-agnostic** - Works with React, Vue, Angular, or vanilla JavaScript
-- **TypeScript support** - Full type definitions included
-- **Event-driven architecture** - Comprehensive callbacks for all operations
-- **Precise localization** - 6-DOF pose estimation with position and rotation
-- **Cloud-based mapping** - Leverages MultiSet's cloud infrastructure for map storage and matching
+The SDK is split into two independent entry points:
+
+| Entry point | Contents | Three.js required |
+|---|---|---|
+| `@multisetai/vps/core` | `MultisetClient` + `XRSessionManager` | No |
+| `@multisetai/vps/three` | `ThreeAdapter` | Yes (peer dep) |
+
+`XRSessionManager` owns the full vanilla WebXR session lifecycle — frame loop, camera capture, localization, tracking-loss recovery — with zero Three.js dependency. `ThreeAdapter` wires it to a Three.js renderer and scene.
 
 ## Installation
 
 ```bash
+# Core only (no Three.js)
+npm install @multisetai/vps
+
+# With Three.js adapter
 npm install @multisetai/vps three
 ```
 
-> **Note**: `three` is a peer dependency and must be installed separately.
-
 ## Requirements
 
-### Runtime Requirements
-
-- **HTTPS**: WebXR requires a secure context. Use HTTPS in production or `http://localhost` for local development.
-- **WebXR-capable device**: Android device with ARCore
-- **Modern browser**: Chrome or Edge on Android
-- **Three.js**: Version 0.176.0 or higher (peer dependency)
+- **HTTPS** — WebXR requires a secure context (`https://` or `http://localhost`).
+- **Android + ARCore** — Chrome or Edge on an ARCore-capable Android device.
+- **Three.js ≥ 0.176.0** — only required when using `@multisetai/vps/three`.
 
-> **iOS is not supported.** This SDK requires the `camera-access` WebXR feature to capture frames for localization. Safari on iOS does not implement `camera-access`, so the AR session will fail to start on any iOS browser.
+> **iOS is not supported.** This SDK requires the `camera-access` WebXR feature. Safari on iOS does not implement it.
 
-### Development Requirements
+## CORS Configuration
 
-- Node.js 16+ and npm
-- TypeScript 5.8+ (for TypeScript projects)
+The SDK makes direct browser-to-API requests, so your domain must be whitelisted in the MultiSet dashboard.
 
-## Configuration
+1. Open the [MultiSet Dashboard](https://docs.multiset.ai/basics/credentials/configuring-allowed-domains-cors)
+2. Go to **Credentials → Settings → Domains**
+3. Click **Add +** and enter your origin (e.g. `https://localhost:5173` for dev, `https://your-app.com` for prod)
 
-### CORS Domain Whitelisting
+Without this, the browser will block every API request with a CORS error.
 
-Since this SDK makes direct API calls to MultiSet servers from browser-based applications, you **must** configure Cross-Origin Resource Sharing (CORS) by whitelisting your application's domain in the MultiSet dashboard.
+---
 
-**Why is this required?** Browsers restrict cross-origin HTTP requests for security. By adding your domain to the MultiSet whitelist, you allow your web application to make API requests to MultiSet services.
-
-#### How to Whitelist Your Domain
+## Quick Start
 
-1. Navigate to the [MultiSet Dashboard](https://docs.multiset.ai/basics/credentials/configuring-allowed-domains-cors)
-2. Go to **Credentials → Settings** tab
-3. Locate the **Domains** section
-4. Click the purple **Add +** button
-5. Enter your application's full origin (protocol + domain + port if applicable)
+### With Three.js
 
-#### Recommended Setup
+```typescript
+import * as THREE from 'three';
+import { MultisetClient, XRSessionManager } from '@multisetai/vps/core';
+import { ThreeAdapter } from '@multisetai/vps/three';
 
-Add entries for both your local development and production environments:
+// Check support before showing any AR UI
+const supported = await ThreeAdapter.isSupported();
+if (!supported) {
+  console.warn('WebXR immersive-ar is not supported on this device.');
+}
 
-**Local Development:**
-- **Format:** `https://localhost:PORT` (e.g., `https://localhost:3000`, `https://localhost:5173`)
-- **Note:** Use the exact port your development server runs on
+const client = new MultisetClient({
+  clientId: 'CLIENT_ID',
+  clientSecret: 'CLIENT_SECRET',
+  code: 'MAP_OR_MAPSET_CODE',
+  mapType: 'map',
+});
 
-**Production:**
-- **Format:** `https://your-domain.com` (e.g., `https://www.myapp.com`)
-- **Note:** Do not include trailing slashes
+await client.authorize();
 
-> **Important:** Without whitelisting your domain, API requests will be blocked by the browser's CORS policy, and you'll see errors in the browser console.
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+document.body.appendChild(renderer.domElement);
 
-For more details, see the [MultiSet CORS Configuration Documentation](https://docs.multiset.ai/basics/credentials/configuring-allowed-domains-cors).
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(70, window.innerWidth / window.innerHeight, 0.01, 1000);
 
-## Quick Start
+const session = new XRSessionManager(renderer.getContext() as WebGL2RenderingContext, {
+  client,
+  overlayRoot: document.body,
+  autoLocalize: true,
+  confidenceCheck: true,
+  confidenceThreshold: 0.5,
+  onSessionStart: () => {
+    // Hide the canvas during AR — the XR compositor owns the display.
+    // Leaving it visible shows the stale preview frame on top of the AR scene.
+    renderer.domElement.style.display = 'none';
+  },
+  onSessionEnd: () => {
+    renderer.domElement.style.display = 'block';
+  },
+  onLocalizationSuccess: (result) => console.log('Localized:', result.localizeData.position),
+  onLocalizationFailure: (reason) => console.warn('Failed:', reason),
+  onError: (err) => console.error(err),
+});
 
-### 1. Import the SDK
+const adapter = new ThreeAdapter({ session, renderer, scene, camera, showMesh: true });
+adapter.initialize(); // mounts the built-in START AR / STOP AR button
 
-```typescript
-import { MultisetClient } from '@multisetai/vps/core';
-import { WebxrController } from '@multisetai/vps/webxr';
+// Add your 3D content
+scene.add(new THREE.Mesh(
+  new THREE.BoxGeometry(0.1, 0.1, 0.1),
+  new THREE.MeshBasicMaterial({ color: 0xff0077 })
+));
 ```
 
-### 2. Create and authorize the client
+### Without Three.js (vanilla WebXR)
 
 ```typescript
-const client = new MultisetClient({
-  clientId: 'CLIENT_ID',
-  clientSecret: 'CLIENT_SECRET',
-  code: 'MAP_OR_MAPSET_CODE',
-  mapType: 'map', // or 'map-set'
-  onAuthorize: (token) => console.log('Authorized:', token),
-  onError: (error) => console.error('Error:', error),
-});
+import { MultisetClient, XRSessionManager } from '@multisetai/vps/core';
+
+const supported = await XRSessionManager.isSupported();
+if (!supported) {
+  console.warn('WebXR immersive-ar is not supported on this device.');
+}
 
+const client = new MultisetClient({ clientId: '...', clientSecret: '...', code: '...', mapType: 'map' });
 await client.authorize();
-```
 
-### 3. Initialize WebXR controller
+const gl = document.querySelector('canvas')!.getContext('webgl2')!;
 
-```typescript
-const controller = new WebxrController({
+const session = new XRSessionManager(gl, {
   client,
-  canvas: document.querySelector('canvas'),
   overlayRoot: document.body,
-  onSessionStart: () => console.log('AR session started'),
-  onSessionEnd: () => console.log('AR session ended'),
+  autoLocalize: true,
+  onLocalizationSuccess: (result) => console.log('Localized:', result.localizeData.position),
+  onError: (err) => console.error(err),
+});
+
+// Wire your own render loop before creating the button
+session.setXRFrameHandler((event) => {
+  // event: { time, frame, pose, view, viewport, baseLayer, referenceSpace, deltaSeconds }
+  // render here using event.baseLayer.framebuffer
 });
 
-await controller.initialize();
+document.body.appendChild(session.createButton());
 ```
 
-### 4. Capture and localize
+---
+
+## Canvas Visibility During AR
+
+> **Important** — the SDK renders the Three.js scene into the **XR framebuffer**, not the canvas element. During an active AR session the canvas element is not updated; it retains whatever was last drawn by the preview loop. If the canvas is visible during AR (e.g. as part of the WebXR DOM overlay) it will appear as a frozen image on top of the AR scene.
+
+Always hide the canvas when the session starts and restore it when it ends:
 
 ```typescript
-const result = await controller.localizeFrame();
-if (result?.localizeData?.poseFound) {
-  console.log('Position:', result.localizeData.position);
-  console.log('Rotation:', result.localizeData.rotation);
-}
+onSessionStart: () => { renderer.domElement.style.display = 'none'; },
+onSessionEnd:   () => { renderer.domElement.style.display = 'block'; },
 ```
 
-## Core Client API
+---
 
-### `MultisetClient`
+## API Reference
 
-The core client handles authentication and API interactions with MultiSet services.
+### `MultisetClient`
 
-#### Constructor
+Pure HTTP client for auth and localization. No WebXR or rendering concerns.
 
 ```typescript
-new MultisetClient(config: IMultisetSdkConfig)
+new MultisetClient(config: IMultisetClientConfig)
 ```
 
-`IMultisetSdkConfig` is a **discriminated union** on `mapType`. This means TypeScript enforces parameter constraints at compile time — see the notes in the table below.
-
-**Configuration Options:**
+#### `IMultisetClientConfig`
 
 | Parameter | Type | Description |
 |---|---|---|
 | `clientId` | `string` | Your MultiSet client ID |
 | `clientSecret` | `string` | Your MultiSet client secret |
-| `code` | `string` | Map or map-set code (e.g. `'MAP_XXXXX'`) |
-| `mapType` | `'map' \| 'map-set'` | Whether `code` refers to a single map or a map set |
-| `endpoints` | `Partial<IMultisetSdkEndpoints>` | Override default API endpoints |
-| `showMesh` | `boolean` | Show the VPS map mesh in the AR scene. Default: `false` |
-| `showGizmo` | `boolean` | Show coordinate gizmo when a pose is found. Default: `true` |
-| `autoLocalize` | `boolean` | Automatically start localization when the AR session starts |
-| `relocalization` | `boolean` | Automatically re-localize after tracking loss is recovered |
-| `confidenceCheck` | `boolean` | Only accept results with `confidence >= confidenceThreshold` |
-| `confidenceThreshold` | `number` | Minimum confidence (0.2–0.8). Used when `confidenceCheck` is `true`. Default: `0.5` |
-| `isRightHanded` | `boolean` | Handedness of the coordinate system sent to the API. Default: `true` |
-| `passGeoPose` | `boolean` | Use the browser Geolocation API to send a `geoHint` with each localization request |
-| `use2DFiltering` | `boolean` | Skip altitude in geoHint spatial filtering. **Only valid when `passGeoPose: true`** — TypeScript will error if `passGeoPose` is omitted or `false` |
-| `convertToGeoCoordinates` | `boolean` | Request the backend to return results as geographic coordinates |
-| `hintMapCodes` | `string[]` | Narrow candidate maps by code. **Only valid when `mapType: 'map-set'`** — TypeScript will error on `mapType: 'map'` |
-| `hintPosition` | `string` | Local-space position hint as `"x,y,z"` (e.g. `"2.5,0.1,8.0"`) |
-| `hintRadius` | `number \| string` | Search radius in meters for spatial filtering (range 1–100). Requires `hintPosition` or `passGeoPose` |
-| `localizationTrackingTimeoutMs` | `number` | Max ms to wait for a valid viewer pose before failing. Default: `10000` |
-| `onLocalizationInit` | `() => void` | Called at the start of a localization run |
-| `onLocalizationSuccess` | `(result) => void` | Called when localization succeeds (and passes confidence check if enabled) |
-| `onLocalizationFailure` | `(reason?) => void` | Called when all attempts fail or confidence is below threshold |
-| `onAuthorize` | `(token) => void` | Called after successful authorization |
-| `onFrameCaptured` | `(payload) => void` | Called when a camera frame is captured |
-| `onCameraIntrinsics` | `(intrinsics) => void` | Called with camera intrinsic parameters |
-| `onPoseResult` | `(payload) => void` | Called with the raw pose result from the backend |
-| `onError` | `(error) => void` | Called when any error occurs |
+| `code` | `string` | Map or map-set code |
+| `mapType` | `'map' \| 'map-set'` | Whether `code` is a single map or a map set |
+| `endpoints?` | `Partial<IMultisetSdkEndpoints>` | Override default API endpoints |
+| `isRightHanded?` | `boolean` | Handedness sent to the API. Default `true` |
+| `convertToGeoCoordinates?` | `boolean` | Request geographic coordinates in the response |
+| `hintPosition?` | `string` | Local-space position hint `"x,y,z"` |
+| `hintRadius?` | `number \| string` | Search radius in metres (1–100). Requires `hintPosition` or `passGeoPose` |
+| `hintMapCodes?` | `string[]` | Narrow candidates by map code. Only valid when `mapType: 'map-set'` |
+| `passGeoPose?` | `boolean` | Send a `geoHint` from the Geolocation API with each request |
+| `use2DFiltering?` | `boolean` | Skip altitude in geo filtering. Only valid when `passGeoPose: true` |
 
 #### Methods
 
-##### `authorize(): Promise<string>`
+| Method | Returns | Description |
+|---|---|---|
+| `authorize()` | `Promise<string>` | Authenticate and cache an access token. Call before any other method. |
+| `localizeWithFrame(frame, intrinsics)` | `Promise<ILocalizeAndMapDetails \| null>` | Submit a captured frame for localization. |
+| `fetchMapDetails(mapCode)` | `Promise<IGetMapsDetailsResponse \| null>` | Fetch map metadata by code (result is cached). |
 
-Authenticates with MultiSet services and obtains an access token. Must be called before making any API requests.
+---
 
-```typescript
-const token = await client.authorize();
-```
+### `XRSessionManager`
 
-**Returns**: The access token as a string.
+Owns the WebXR session lifecycle — frame loop, camera capture, localization, and tracking-loss recovery. Zero Three.js dependency.
 
-#### Events and callbacks
+```typescript
+import { XRSessionManager } from '@multisetai/vps/core';
 
-The client and controller emit events through callback functions:
+new XRSessionManager(gl: WebGL2RenderingContext, options: IXRSessionOptions)
+```
 
-- **`onAuthorize`**: Called when authorization succeeds with the access token
-- **`onFrameCaptured`**: Called when a camera frame is captured for localization
-- **`onCameraIntrinsics`**: Called with camera intrinsic parameters
-- **`onPoseResult`**: Called with localization results (pose found/not found)
-- **`onLocalizationInit`**: Called at the start of a localization run
-- **`onLocalizationSuccess`**: Called when a localization run succeeds (optionally after confidence checks)
-- **`onLocalizationFailure`**: Called when a localization run fails or the best result is below the confidence threshold
-- **`onError`**: Called when any error occurs during authorization or localization
+#### `IXRSessionOptions`
 
-### Advanced localization behavior
+| Parameter | Type | Description |
+|---|---|---|
+| `client` | `MultisetClient` | Required. |
+| `overlayRoot?` | `HTMLElement` | Root element for the WebXR DOM overlay. |
+| `autoLocalize?` | `boolean` | Run one localization automatically when the session starts. |
+| `relocalization?` | `boolean` | Re-localize whenever tracking is recovered after loss. |
+| `confidenceCheck?` | `boolean` | Only accept results with `confidence >= confidenceThreshold`. |
+| `confidenceThreshold?` | `number` | Minimum confidence (0.2–0.8). Default `0.5`. |
+| `localizationTrackingTimeoutMs?` | `number` | Max ms to wait for a viewer pose before failing. Default `10000`. |
+| `referenceSpaceType?` | `XRReferenceSpaceType` | XR reference space type. Default `'local'`. Use `'local-floor'` for floor-relative tracking if the device supports it. |
+| `framebufferScaleFactor?` | `number` | XR framebuffer scale relative to native resolution. Values `< 1` reduce GPU load; values `> 1` supersample. |
+| `onSessionStart?` | `() => void` | Called when the AR session starts. |
+| `onSessionEnd?` | `() => void` | Called when the AR session ends. |
+| `onLocalizationInit?` | `() => void` | Called at the start of a localization run. |
+| `onLocalizationSuccess?` | `(result: ILocalizeAndMapDetails) => void` | Called when localization succeeds (and passes the confidence check, if enabled). |
+| `onLocalizationFailure?` | `(reason?: string) => void` | Called when localization fails or falls below the confidence threshold. |
+| `onFrameCaptured?` | `(frame: IFrameCaptureEvent) => void` | Called when a camera frame is captured for localization. |
+| `onCameraIntrinsics?` | `(intrinsics: ICameraIntrinsicsEvent) => void` | Called with camera intrinsic parameters for the captured frame. |
+| `onPoseResult?` | `(pose: IPoseResultEvent) => void` | Called with the raw pose result from the VPS backend. |
+| `onError?` | `(error: unknown) => void` | Called when any error occurs. |
+| `onContextLost?` | `() => void` | Called when the WebGL context is lost. The active session is ended automatically. |
+| `onContextRestored?` | `() => void` | Called when the WebGL context is restored. The user may restart the session. |
+
+#### Static methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `XRSessionManager.isSupported()` | `Promise<boolean>` | Returns `true` if the browser supports `immersive-ar` WebXR sessions. Use this to conditionally show AR UI before creating any objects. |
 
-`MultisetClient` together with `WebxrController` supports a higher-level localization flow similar to the Unity SingleFrameLocalizationManager:
+#### Methods
 
-- **Confidence-based acceptance**: When `confidenceCheck` is `true`, only results with `confidence >= confidenceThreshold` (0.2–0.8) are treated as successful.
-- **Auto-localize**: When `autoLocalize` is `true`, a localization run is started automatically when the AR session starts.
-- **Re-localize on tracking loss**: When `relocalization` is `true`, the controller automatically tries to re-localize after tracking has been lost for a short period.
-- **Geo hint**: When `passGeoPose` is `true`, the SDK uses the browser Geolocation API to compute a `geoHint` string `"lat,lon,alt"` and sends it with each localization request to improve candidate matching. When `convertToGeoCoordinates` is `true`, the backend may include geo coordinates in the response.
-- **2D filtering**: When `use2DFiltering` is `true` (requires `passGeoPose: true`), altitude is ignored in the `geoHint` spatial filter — useful when elevation data is unreliable.
-- **Position hint**: `hintPosition` provides a local-space `"x,y,z"` starting point for candidate search. `hintRadius` (1–100 m) constrains the search radius around either `hintPosition` or the `geoHint`.
-- **Map code hints**: When `mapType` is `'map-set'`, `hintMapCodes` narrows the set of candidate maps queried during localization.
+| Method | Returns | Description |
+|---|---|---|
+| `createButton()` | `HTMLButtonElement` | Create the built-in styled AR button. Shows **START AR** / **STOP AR** and toggles the session on click. |
+| `startSession()` | `Promise<void>` | Start an AR session programmatically. **Must be called from within a user gesture handler** (click/tap). |
+| `stopSession()` | `void` | Stop the active AR session. No-op if no session is running. |
+| `localizeFrame()` | `Promise<ILocalizeAndMapDetails \| null>` | Capture and localize one frame. Requires an active session. |
+| `isActive()` | `boolean` | Whether an XR session is currently running. |
+| `isLocalizing` | `boolean` | Whether a localization run is currently in progress. |
+| `getClient()` | `MultisetClient` | Access the underlying `MultisetClient`. |
+| `dispose()` | `void` | End the session, remove context loss listeners, and release all resources. |
 
-## WebXR Controller API
+#### Adapter hooks
 
-### `WebxrController`
+Used internally by `ThreeAdapter`. Only call these when building a custom renderer adapter.
 
-Manages WebXR sessions, Three.js scene, camera, and renderer. Handles AR button creation and frame capture for localization.
+| Method | Description |
+|---|---|
+| `setXRFrameHandler(fn)` | Called every XR frame with pose, view, viewport, and framebuffer info. |
+| `setAdapterResultHandler(fn)` | Called after a successful localization with the result and tracker-space matrix. |
+| `setAdapterSessionHandlers(onStart, onEnd)` | Called on session start/end, before user callbacks. |
 
-#### Constructor
+---
 
-```typescript
-new WebxrController(options: IWebxrControllerOptions)
-```
+### `ThreeAdapter`
 
-**Configuration Options:**
+Wires `XRSessionManager` to a Three.js renderer. Handles XR framebuffer binding, camera matrix sync, preview loop, resize, and optional map mesh / gizmo display.
 
 ```typescript
-interface IWebxrControllerOptions {
-  client: MultisetClient;                    // Required: MultisetClient instance
-  canvas?: HTMLCanvasElement;                // Optional: Canvas element (created if not provided)
-  overlayRoot?: HTMLElement;                 // Optional: Root for DOM overlay (default: document.body)
-  buttonContainer?: HTMLElement;             // Optional: Container for AR button
-  onARButtonCreated?: (button: HTMLButtonElement) => void;
-  onSessionStart?: () => void;
-  onSessionEnd?: () => void;
-}
+import { ThreeAdapter } from '@multisetai/vps/three';
+
+new ThreeAdapter(options: IThreeAdapterOptions)
 ```
 
-#### Methods
+#### `IThreeAdapterOptions`
 
-##### `initialize(buttonContainer?: HTMLElement): Promise<HTMLButtonElement>`
+| Parameter | Type | Description |
+|---|---|---|
+| `session` | `XRSessionManager` | Required. |
+| `renderer` | `THREE.WebGLRenderer` | Required. |
+| `scene` | `THREE.Scene` | Required. |
+| `camera` | `THREE.PerspectiveCamera` | Required. |
+| `showMesh?` | `boolean` | Show the VPS map mesh after localization. Default `false`. |
+| `showGizmo?` | `boolean` | Show a transform gizmo after localization. Default `true`. |
+| `useDefaultButton?` | `boolean` | Mount the built-in START AR / STOP AR button. Default `true`. Set to `false` to drive the session via `startSession()` / `stopSession()`. |
+| `buttonContainer?` | `HTMLElement` | Where to append the built-in button. Defaults to `overlayRoot` or `document.body`. |
+| `onButtonCreated?` | `(button: HTMLButtonElement) => void` | Called after the built-in button is created. |
+| `onXRFrame?` | `(event: IXRFrameEvent) => void` | Called every XR frame after camera matrices are synced, before the scene is rendered. Use this to update scene objects each frame. |
+| `onLocalizationSuccess?` | `(result: ILocalizeAndMapDetails, worldFromMap: THREE.Matrix4) => void` | Called after a successful localization. `worldFromMap` transforms any point from VPS map space into Three.js world space — use it to place scene objects at known physical locations in the scanned map. |
+
+#### Static methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `ThreeAdapter.isSupported()` | `Promise<boolean>` | Returns `true` if the browser supports `immersive-ar` WebXR sessions. |
 
-Initializes the WebXR controller, sets up Three.js scene/renderer/camera, and creates the AR button.
+#### Methods
 
-```typescript
-const arButton = await controller.initialize(buttonContainer);
-```
+| Method | Returns | Description |
+|---|---|---|
+| `initialize(buttonContainer?)` | `HTMLButtonElement \| null` | Start the preview render loop, attach resize handler, and mount the built-in button. Returns `null` when `useDefaultButton: false`. |
+| `isActive()` | `boolean` | Whether an XR session is currently running. |
+| `isLocalizing` | `boolean` | Whether a localization run is currently in progress. |
+| `startSession()` | `Promise<void>` | Start an AR session. **Must be called from within a user gesture handler.** |
+| `stopSession()` | `void` | Stop the active AR session. No-op if no session is running. |
+| `localizeFrame()` | `Promise<ILocalizeAndMapDetails \| null>` | Capture and localize one frame. |
+| `dispose()` | `void` | Stop loops, remove listeners, dispose Three.js resources, and end the session. |
 
-**Returns**: The created AR button element.
+---
 
-##### `localizeFrame(): Promise<ILocalizeAndMapDetails | null>`
+## Placing Content at Map Coordinates
 
-Captures one frame from the active AR session and localizes against the configured map. Waits for a valid viewer pose up to `localizationTrackingTimeoutMs` before failing.
+After localization, the `onLocalizationSuccess` callback on `ThreeAdapter` provides a `worldFromMap` matrix that converts any point from VPS map space into Three.js world space. Use this to anchor scene objects to specific physical locations in the scanned map — independently of where the user started the AR session.
 
 ```typescript
-const result = await controller.localizeFrame();
-if (result?.localizeData?.poseFound) {
-  console.log('Localized at:', result.localizeData.position);
-}
+const adapter = new ThreeAdapter({
+  session,
+  renderer, scene, camera,
+  onLocalizationSuccess: (result, worldFromMap) => {
+    // mapPoint is a position you measured from the scanned map (in metres)
+    const mapPoint = new THREE.Vector3(1.5, 0, -2.0);
+
+    const marker = new THREE.Mesh(
+      new THREE.SphereGeometry(0.05),
+      new THREE.MeshBasicMaterial({ color: 0x00ff88 })
+    );
+    marker.position.copy(mapPoint.applyMatrix4(worldFromMap));
+    scene.add(marker);
+  },
+});
 ```
 
-This method:
+> **Note** — `worldFromMap` is recomputed on every successful localization. If you re-localize, update or re-add your objects so they stay in sync with the latest result.
 
-- Fires `onLocalizationInit` at the start of the run
-- Waits for a valid viewer pose (up to `localizationTrackingTimeoutMs`, default 10 s)
-- Captures the camera frame and calls the localization API
-- Applies the confidence threshold when `confidenceCheck` is enabled
-- Calls `onLocalizationSuccess` or `onLocalizationFailure` accordingly
+---
 
-##### `getScene(): THREE.Scene`
+## Styling the AR Button
 
-Gets the Three.js scene object for adding 3D models and objects.
+The built-in button ships with minimal inline styles. Use these CSS classes to override appearance from your own stylesheet:
 
-```typescript
-const scene = controller.getScene();
-const cube = new THREE.Mesh(geometry, material);
-scene.add(cube);
-```
+| Class | When present |
+|---|---|
+| `.multiset-ar-button` | Always — use for base styles |
+| `.multiset-ar-inactive` | No active session (START AR state) |
+| `.multiset-ar-active` | During an active AR session (STOP AR state) |
 
-##### `getCamera(): THREE.PerspectiveCamera`
+```css
+.multiset-ar-button {
+  font-family: 'Your Font', sans-serif;
+  border-radius: 8px;
+}
 
-Gets the Three.js camera object for custom camera configuration.
+.multiset-ar-inactive {
+  background: rgba(0, 0, 0, 0.5);
+}
 
-```typescript
-const camera = controller.getCamera();
-camera.near = 0.1;
-camera.far = 1000;
+.multiset-ar-active {
+  background: rgba(200, 0, 0, 0.6);
+  border-color: #ff4444;
+}
 ```
 
-##### `getRenderer(): THREE.WebGLRenderer`
+---
 
-Gets the Three.js WebGL renderer for advanced rendering configuration.
+## Custom Start / Stop Button
 
-```typescript
-const renderer = controller.getRenderer();
-renderer.shadowMap.enabled = true;
-```
-
-##### `hasActiveSession(): boolean`
-
-Checks if an active WebXR session is currently running.
+Set `useDefaultButton: false` to manage the session yourself:
 
 ```typescript
-if (controller.hasActiveSession()) {
-  // AR session is active
-}
-```
-
-##### `dispose(): void`
+const adapter = new ThreeAdapter({
+  session,
+  renderer, scene, camera,
+  useDefaultButton: false,
+});
 
-Cleans up resources and removes event listeners. Call this when destroying the controller.
+adapter.initialize();
 
-```typescript
-controller.dispose();
+myButton.addEventListener('click', () => {
+  if (adapter.isActive()) {
+    adapter.stopSession();
+  } else {
+    // startSession() must be the first call inside the gesture handler —
+    // any await before it consumes the browser's user activation token.
+    void adapter.startSession();
+  }
+});
 ```
 
-## Type Definitions
+---
 
-All TypeScript types are exported from the main entry points:
+## Type Definitions
 
 ```typescript
-// Core types
 import type {
-  IMultisetSdkConfig,
-  IMultisetPublicConfig,
+  IMultisetClientConfig,
   IMultisetSdkEndpoints,
+  IXRSessionOptions,
+  IXRFrameEvent,
   IFrameCaptureEvent,
   ICameraIntrinsicsEvent,
   IPoseResultEvent,
   ILocalizeAndMapDetails,
-  ILocalizeResultEvent,
+  IGetMapsDetailsResponse,
   MapType,
 } from '@multisetai/vps/core';
 
-// WebXR types
-import type {
-  IWebxrControllerOptions,
-} from '@multisetai/vps/webxr';
-```
-
-## Examples
-
-> **Full working examples**: This repository includes complete, runnable example applications in the [`examples/`](./examples) directory:
-> - **[React Example](./examples/react)** - Full React implementation with TypeScript
-> - **[Vanilla JavaScript Example](./examples/vanilla)** - Vanilla JavaScript implementation
->
-> Each example includes setup instructions, configuration, and demonstrates the complete SDK integration workflow.
-
-### Vanilla JavaScript
-
-```javascript
-import * as THREE from 'three';
-import { MultisetClient } from '@multisetai/vps/core';
-import { WebxrController } from '@multisetai/vps/webxr';
-
-const client = new MultisetClient({
-  clientId: 'CLIENT_ID',
-  clientSecret: 'CLIENT_SECRET',
-  code: 'MAP_OR_MAPSET_CODE',
-  mapType: 'map',
-  showMesh: true,
-  confidenceCheck: true,
-  confidenceThreshold: 0.5,
-  onLocalizationSuccess: (result) => console.log('Localized:', result.localizeData.position),
-  onLocalizationFailure: (reason) => console.warn('Localization failed:', reason),
-  onAuthorize: (token) => console.log('Authorized:', token),
-  onError: (error) => console.error('Error:', error),
-});
-
-const controller = new WebxrController({
-  client,
-  canvas: document.querySelector('canvas'),
-  overlayRoot: document.body,
-  onSessionStart: () => console.log('AR session started'),
-  onSessionEnd: () => console.log('AR session ended'),
-});
-
-// Authorize and initialize
-await client.authorize();
-await controller.initialize();
-
-// Add 3D objects to scene
-const scene = controller.getScene();
-const cube = new THREE.Mesh(
-  new THREE.BoxGeometry(0.1, 0.1, 0.1),
-  new THREE.MeshBasicMaterial({ color: 0xff0077 })
-);
-cube.position.set(0, 0, -0.4);
-scene.add(cube);
-
-// Manually trigger a single localization attempt
-const result = await controller.localizeFrame();
-if (result?.localizeData?.poseFound) {
-  console.log('Position:', result.localizeData.position);
-  console.log('Rotation:', result.localizeData.rotation);
-}
-```
-
-### React
-
-```tsx
-import { useEffect, useRef, useState } from 'react';
-import * as THREE from 'three';
-import { MultisetClient } from '@multisetai/vps/core';
-import { WebxrController } from '@multisetai/vps/webxr';
-
-export default function App() {
-  const [authorized, setAuthorized] = useState(false);
-  const [arSessionActive, setArSessionActive] = useState(false);
-  const canvasRef = useRef<HTMLCanvasElement>(null);
-  const clientRef = useRef<MultisetClient | null>(null);
-  const controllerRef = useRef<WebxrController | null>(null);
-
-  useEffect(() => {
-    return () => {
-      controllerRef.current?.dispose();
-    };
-  }, []);
-
-  const handleAuthorize = async () => {
-    if (!canvasRef.current) return;
-
-    clientRef.current = new MultisetClient({
-      clientId: 'CLIENT_ID',
-      clientSecret: 'CLIENT_SECRET',
-      code: 'MAP_OR_MAPSET_CODE',
-      mapType: 'map',
-      showMesh: true,
-      confidenceCheck: true,
-      confidenceThreshold: 0.5,
-      onLocalizationSuccess: (result) => console.log('Localized:', result.localizeData.position),
-      onLocalizationFailure: (reason) => console.warn('Localization failed:', reason),
-      onError: (error) => console.error('Error:', error),
-    });
-
-    controllerRef.current = new WebxrController({
-      client: clientRef.current,
-      canvas: canvasRef.current,
-      overlayRoot: document.body,
-      onSessionStart: () => setArSessionActive(true),
-      onSessionEnd: () => setArSessionActive(false),
-    });
-
-    await clientRef.current.authorize();
-    await controllerRef.current.initialize();
-
-    // Add 3D objects to the scene
-    const scene = controllerRef.current.getScene();
-    const cube = new THREE.Mesh(
-      new THREE.BoxGeometry(0.1, 0.1, 0.1),
-      new THREE.MeshBasicMaterial({ color: 0xff0077 })
-    );
-    cube.position.set(0, 0, -0.4);
-    scene.add(cube);
-
-    setAuthorized(true);
-  };
-
-  const handleCapture = async () => {
-    const result = await controllerRef.current!.localizeFrame();
-    if (result?.localizeData?.poseFound) {
-      console.log('Position:', result.localizeData.position);
-      console.log('Rotation:', result.localizeData.rotation);
-    }
-  };
-
-  return (
-    <div>
-      {!authorized && (
-        <button onClick={handleAuthorize}>Authorize</button>
-      )}
-      {arSessionActive && (
-        <button onClick={handleCapture}>Capture</button>
-      )}
-      <canvas ref={canvasRef} />
-    </div>
-  );
-}
+import type { IThreeAdapterOptions } from '@multisetai/vps/three';
 ```
 
 ## License
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-