@archvisioninc/canvas

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