# @archvisioninc/canvas

A React component library built on BabylonJS 7 that provides a full-featured 3D viewer and editor. Drops into any React host application (FOVEA) and communicates bidirectionally over props.

## Getting Started

```bash
npm install @archvisioninc/canvas
```

```jsx
import Canvas from '@archvisioninc/canvas';
```

## Local Development

```bash
git clone <repo>
cd archvision-canvas
npm install
npm start       # dev server at localhost:3000
npm run build   # compile src/package → dist/
```

`src/scenes/App/App.js` is the local dev harness. It mounts `<Canvas />` with mock props to simulate the FOVEA environment. Use the `<DebugButton />` area to reproduce panel interactions locally.

### Linking to FOVEA (creator.archvision.app) for local development

Use `npm link` to point FOVEA at your local canvas build instead of the published npm package.

**1. Register the package globally (run once, from this repo):**

```powershell
mkdir "C:\Users\AVS\AppData\Roaming\npm"; npm link
```

**2. Link it in FOVEA (from the FOVEA repo root):**

```bash
npm link @archvisioninc/canvas
```

**3. In FOVEA's `vite.config.js` at line 35**, update the ESLint plugin to exclude the canvas `dist/` folder from linting (otherwise Vite will report lint errors from compiled output):

```js
eslint({ exclude: [/node_modules/, /archvision-canvas[\\/]dist/] }),
```

**4. Start both dev servers** — changes in `src/package/` are picked up by FOVEA after running `npm run build` in this repo.

## Canvas Modes

### Standard Mode

Full bidirectional communication with the host app. Required props:

| Prop | Type | Description |
|---|---|---|
| `theme` | Object | Theme schema matching `/src/static/theme` |
| `$selectedTheme` | `'light'` \| `'dark'` | Active theme |
| `defaultEnvironments` | Array | Preset environments from `canvasReducer` initialState |
| `notifications` | Array | Current notifications from host reducer |
| `addNotification` | Function | Send canvas messages to host |
| `clearNotifications` | Function | Clear notification events from canvas |
| `guidURL` | String | `.glb` URL to download and render |

Additional props:

| Prop | Type | Description |
|---|---|---|
| `reinitialize` | Boolean | Clears scene and resets to default empty state |
| `updateData` | Object | Payload from FOVEA panels — routed by `canvasCommunicationHelpers` |
| `clearUpdateData` | Function | Clears pending update payload |
| `exportModel` | Boolean | Triggers model export |
| `exportType` | `'glb'` | Controls `GLBAsync` vs `GLTFAsync` exporter |
| `toDownload` | Boolean | Triggers model download |
| `setDownloadedModel` | Function | Returns exported glTF data to host |
| `setConfirmMessage` | Function | Initiates a confirmation dialog in host |
| `setSerializedData` | Function | Receives serialized scene state after every Babylon change |
| `setBillboardImages` | Function | Returns screenshots for billboard proxy types |
| `integration` | Object | Viewport overrides: `{ shadows: bool, meshHighlighting: bool }` |

### Preview Mode

Read-only. Hides grid, gizmos, inspector, and turntable. Disables drag-and-drop. Takes all standard props except `guidURL`, plus:

| Prop | Type | Description |
|---|---|---|
| `previewMode` | Boolean | Enables preview mode |
| `previewURL` | String | `.glb` URL to render |

### Material Mode

Material editor with a shaderball scene. Camera is locked — no selection, transform, or zoom.

| Prop | Type | Description |
|---|---|---|
| `materialMode` | Boolean | Enables material mode |
| `file` | File | Local `.glb` file to load (or use `guidURL` for remote) |

### Demo Scene Mode

Development-only. Loads two basic objects for quick testing.

| Prop | Type | Description |
|---|---|---|
| `demoScene` | Boolean | Overrides empty scene with two test objects |

## Data Flow

The host sends `updateData = { type, method, ...payload }` as a prop. The canvas routes it to the appropriate helper, updates the Babylon scene, then serializes and returns the new state via `setSerializedData`.

```
Host prop: updateData → canvasCommunicationHelpers → domain helper → Babylon scene
Host callback: setSerializedData ← serializeScene() ←──────────────────────────────
```

Update `type` values: `material`, `mesh`, `camera`, `environment`, `viewport`, `lighting`, `publish`
Update `method` values: `update`, `add`, `remove`

See [README_DEV.md](README_DEV.md) for the full list of update payloads.

## Publishing

Before publishing, bump the version in `package.json` — npm will reject a duplicate.

All imports inside `src/package/` **must be relative paths**. Absolute imports work locally but will crash when consumed externally.

```bash
npm run push   # build + publish (requires npm login with 2FA)
```

Requires membership in the [`archvisioninc`](https://npmjs.com/settings/archvisioninc/packages) npm org.
