# @liveposter/ar-minimal-app

Build tool for creating deployable AR experiences from Liveposter posters.

## Overview

This package provides a CLI tool that builds standalone AR experiences from Liveposter poster configurations. It handles asset copying, path resolution, and generates production-ready static files.

## Installation

```bash
npm install -g @liveposter/ar-minimal-app
```

Or use with npx:

```bash
npx liveposter ar-build poster.json
```

## CLI Usage

### Basic Build

```bash
npx liveposter-ar <input> [output] [options]
```

**Arguments:**
- `input` - Path to poster config (JSON/JSONC) or poster list
- `output` - Output directory (default: `dist-ar`)

**Options:**
- `--aframe-version <version>` - A-Frame version (default: 1.5.0)
- `--mindar-version <version>` - MindAR version (default: 1.2.5)

### Examples

```bash
# Single poster
npx liveposter-ar poster.json

# Custom output directory
npx liveposter-ar poster.json public/ar

# Poster list (multiple posters)
npx liveposter-ar poster-list.json dist-ar

# Custom CDN versions
npx liveposter-ar poster.json dist-ar --aframe-version 1.6.0
```

## Build Process

1. **Load Configuration** - Parses JSON/JSONC files
2. **Validate** - Checks for required files and valid config
3. **Copy Assets** - Copies models, videos, images, `.mind` files
4. **Generate HTML** - Creates A-Frame scene using @liveposter/ar-viewer
5. **Output** - Writes index.html and assets to output directory

## Output Structure

```
dist-ar/
├── index.html         # Complete AR scene
└── assets/
    ├── poster.mind    # Target files
    ├── model.gltf     # 3D models
    ├── video.mp4      # Videos
    └── image.png      # Images
```

## Input Formats

### Single Poster

```json
{
  "mode": "diaporama",
  "images": [{ "src": "poster.jpg" }],
  "ar": {
    "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 }
      }
    ]
  }
}
```

### Poster List (Array)

```json
[
  "poster1.json",
  "poster2.json",
  "poster3.json"
]
```

### Poster List (Object)

```json
{
  "posters": [
    { "configPath": "poster1.json" },
    { "configPath": "poster2.json" }
  ]
}
```

## Multi-Poster Builds

When building from a poster list, the build system:
1. Merges all target files into single array
2. Adjusts `targetIndex` to avoid conflicts
3. Combines all layers into single scene
4. Copies all assets to single output directory

Result: One AR experience that detects all posters.

## Programmatic API

```javascript
import { buildAr, buildSinglePoster, buildMultiPoster } from '@liveposter/ar-minimal-app';

// Auto-detect single vs multi
buildAr('poster.json', 'dist-ar');

// Build single poster explicitly
buildSinglePoster('poster.json', 'dist-ar', {
  aframeVersion: '1.5.0',
  mindarVersion: '1.2.5'
});

// Build from poster list
buildMultiPoster('poster-list.json', 'dist-ar');
```

## Asset Path Resolution

### Relative Paths

Resolved relative to the spec file location:

```json
{
  "ar": {
    "targetFiles": ["./targets/poster.mind"],  // Relative to spec file
    "layers": [
      {
        "src": "../models/bear.gltf"  // Relative to spec file
      }
    ]
  }
}
```

### URLs

External URLs are preserved as-is:

```json
{
  "ar": {
    "layers": [
      {
        "src": "https://cdn.example.com/model.gltf"  // Not copied, used directly
      }
    ]
  }
}
```

## Deployment

The build output is production-ready and can be deployed to:

- **Static Hosts:** Netlify, Vercel, GitHub Pages
- **Cloud Storage:** AWS S3, Google Cloud Storage, Azure Blob
- **Web Servers:** Apache, Nginx, any static file server

**Requirements:**
- HTTPS (required for camera access)
- Modern mobile browser support
- No server-side processing needed

## Development Workflow

```bash
# 1. Create poster spec with AR config
vim poster.json

# 2. Generate .mind file
# Visit: https://hiukim.github.io/mind-ar-js-doc/tools/compile

# 3. Test locally with dev server
npx liveposter ar-dev poster.json

# 4. Build for production
npx liveposter ar-build poster.json dist-ar

# 5. Test production build
npx serve dist-ar

# 6. Deploy to hosting service
```

## Error Handling

The build tool validates:
- `.mind` files exist
- Asset files exist (models, videos, images)
- Layer types are valid
- Target indices are within range
- File formats are appropriate

Errors are reported with:
- Field name (e.g., `ar.layers[0].src`)
- Error message
- Severity (error or warning)

## License

MIT