<p align="center">
  <a href="https://miris.com">
    <img src="https://cdn.jsdelivr.net/npm/@miris-inc/three/banner.svg" alt="Miris" width="100%" />
  </a>
</p>

# @miris-inc/three

Three.js rendering layer for the Miris 3D streaming SDK. Extends `@miris-inc/core` primitives with Three.js scene objects, controls, and splat rendering.

## Install

```bash
npm install @miris-inc/three three
```

## Usage

### From a CDN

```html
<script type="importmap">
  {
    "imports": {
      "three": "https://unpkg.com/three/build/three.module.js",
      "@miris-inc/three": "https://unpkg.com/@miris-inc/three"
    }
  }
</script>
<script type="module">
  import { Miris, MirisScene } from "@miris-inc/three";
</script>
```

CDNs serve the **standalone build** which bundles `@miris-inc/core` (with WASM inlined). Three.js remains a peer dependency — provide it via an import map or a separate `<script>`.

### With a bundler

```js
import { Miris, MirisScene, MirisStream, MirisControls } from "@miris-inc/three";
import * as THREE from "three";

const renderer = new THREE.WebGLRenderer();
const miris = await Miris.instance();
const scene = new MirisScene(miris);
const controls = new MirisControls(scene, renderer.domElement);
```

The default import resolves to the **chunked build** — `@miris-inc/core` and `three` are peer dependencies resolved by your bundler.

## Builds

| Build | File | Bundles | Externalizes |
|-------|------|---------|-------------|
| Chunked | `three.js` | Unminified. Own code | `three`, `@miris-inc/core` |
| Chunked prod | `three.prod.js` | Minified. Own code | `three`, `@miris-inc/core` |
| Standalone | `three.standalone.js` | Unminified. Own code + `@miris-inc/core` + WASM | `three` |
| Standalone prod | `three.standalone.prod.js` | Minified. Same as above | `three` |

## API

| Export | Description |
|--------|-------------|
| `Miris` | Three.js-aware Miris singleton. Bridges core scene-graph changes to Three.js objects. |
| `MirisScene` | A Three.js `Group` backed by a Miris streaming scene. |
| `MirisStream` | A Three.js `Object3D` for a single stream within a scene. |
| `MirisLod` | A Three.js mesh representing a single LOD node with splat data. |
| `MirisControls` | Orbit/pan/zoom controls that push camera state to the streaming engine. |
| `MirisDetector` | Detects browser/device capabilities for adaptive streaming. |

## Peer Dependencies

- `three` >= 0.182.0
- `@miris-inc/core` (same version)

## License

Apache-2.0
