# @liveposter/ar-viewer

Framework-agnostic AR scene builder for Liveposter using MindAR and A-Frame.

## Overview

This package generates complete A-Frame HTML scenes from Liveposter poster configurations with AR properties. It's designed to work standalone or as part of the Liveposter build system.

## Installation

```bash
npm install @liveposter/ar-viewer
```

## Usage

### Generate AR Scene

```javascript
import { buildArScene } from '@liveposter/ar-viewer';

const arConfig = {
  enabled: true,
  targetFiles: ['poster.mind'],
  layers: [
    {
      targetIndex: 0,
      type: 'model',
      src: 'bear.gltf',
      position: { x: 0, y: -0.25, z: 0 },
      scale: { x: 0.05, y: 0.05, z: 0.05 },
      animation: true
    }
  ]
};

const html = buildArScene(arConfig, {
  aframeVersion: '1.5.0',
  mindarVersion: '1.2.5',
  baseUrl: './',
});

// Write to file or serve
fs.writeFileSync('ar-scene.html', html);
```

### Validate Configuration

```javascript
import { validateArConfig, hasErrors, formatErrors } from '@liveposter/ar-viewer';

const errors = validateArConfig(arConfig, '/path/to/assets');

if (hasErrors(errors)) {
  console.error(formatErrors(errors));
  process.exit(1);
}
```

### Layer Rendering

```javascript
import { renderLayer } from '@liveposter/ar-viewer';

const layer = {
  targetIndex: 0,
  type: 'model',
  src: 'model.gltf',
  position: { x: 0, y: 0, z: 0 },
  scale: { x: 1, y: 1, z: 1 }
};

const { asset, entity } = renderLayer(layer, 0, './');
// asset: <a-asset-item> HTML
// entity: <a-gltf-model> HTML
```

## API

### `buildArScene(arConfig, options)`

Generates complete A-Frame HTML scene.

**Parameters:**
- `arConfig` - AR configuration object
- `options` - Viewer options:
  - `aframeVersion` (default: '1.5.0')
  - `mindarVersion` (default: '1.2.5')
  - `aframeExtrasVersion` (default: '7.0.0')
  - `baseUrl` (default: './')
  - `physicallyCorrectLights` (default: true)
  - `colorSpace` (default: 'sRGB')

**Returns:** Complete HTML string

### `buildSceneFromPosterConfig(posterConfig, options)`

Generates scene from full poster configuration.

**Parameters:**
- `posterConfig` - Poster config with `ar` property
- `options` - Same as `buildArScene`

**Returns:** Complete HTML string

### `validateArConfig(arConfig, basePath)`

Validates AR configuration.

**Parameters:**
- `arConfig` - AR configuration to validate
- `basePath` - Base path for file validation

**Returns:** Array of validation errors

### `hasErrors(errors)`

Check if validation errors include critical errors.

**Parameters:**
- `errors` - Array from `validateArConfig`

**Returns:** Boolean

### `formatErrors(errors)`

Format validation errors for display.

**Parameters:**
- `errors` - Array from `validateArConfig`

**Returns:** Formatted string

### `renderLayer(layer, index, baseUrl)`

Render single AR layer to A-Frame HTML.

**Parameters:**
- `layer` - Layer configuration
- `index` - Layer index for unique IDs
- `baseUrl` - Base URL for asset paths

**Returns:** `{ asset, entity }` - Asset and entity HTML strings

## Layer Types

### Model Layer

```typescript
{
  targetIndex: number;
  type: 'model';
  src: string | string[];
  position?: { x: number, y: number, z: number };
  rotation?: { x: number, y: number, z: number };
  scale?: { x: number, y: number, z: number };
  animation?: boolean;
  opacity?: number;
}
```

### Video Layer

```typescript
{
  targetIndex: number;
  type: 'video';
  src: string | string[];
  position?: { x: number, y: number, z: number };
  rotation?: { x: number, y: number, z: number };
  scale?: { x: number, y: number, z: number };
  loop?: boolean;
  autoplay?: boolean;
  opacity?: number;
}
```

### Image Layer

```typescript
{
  targetIndex: number;
  type: 'image';
  src: string;
  position?: { x: number, y: number, z: number };
  rotation?: { x: number, y: number, z: number };
  scale?: { x: number, y: number, z: number };
  opacity?: number;
}
```

## Build Output

The generated HTML includes:
- CDN-hosted dependencies (A-Frame, MindAR)
- `<a-assets>` section with models, videos, images
- `<a-camera>` with AR settings
- `<a-entity>` for each target with nested layers

## Framework Agnostic

This library is pure JavaScript with no framework dependencies. It generates static HTML that can be:
- Served directly
- Integrated into React/Vue/Angular apps
- Used in static site generators
- Embedded in mobile apps

## License

MIT