@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

npm install @archvisioninc/canvas

import Canvas from '@archvisioninc/canvas';

Local Development

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):

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

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

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):

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 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.

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

Requires membership in the archvisioninc npm org.