Embed SDK@chamuka-labs/engine v0.3.0

@chamuka-labs/engine

The embeddable Chamuka DrawIt canvas. Drop a fully interactive diagram workspace into any web app with a single import and two lines of code.

Overview

Two-line setup

createEngine() + renderInto() is all you need to mount a live, interactive canvas.

Framework agnostic

Works in any environment — Vanilla JS, React, Vue, Svelte, or server-side with a DOM shim.

React bindings included

Import from @chamuka-labs/engine/react for a ready-made <DrawItCanvas> component.

Full interactivity

23 interaction tools, undo/redo, multi-select, real-time events — same engine as chamuka.ai.

TypeScript-first

Fully typed API surface. ESM only.

Event streaming

Subscribe to element lifecycle, selection, and command events via onEvent().

Installation

npm install @chamuka-labs/engine

Peer dependency: React 18+ is optional and only required for the /react subpath.

Quick Start

Mount a diagram canvas in four steps:

import { createEngine } from '@chamuka-labs/engine';

// 1. Load the engine (initialises the core)
const engine = await createEngine();

// 2. (Optional) Load an existing document
engine.loadDocument(myDrawitDoc);

// 3. Mount the renderer into a DOM element
const renderer = await engine.renderInto(
  document.getElementById('canvas')!,
  { backgroundColor: 0xffffff }
);

// 4. Subscribe to events
engine.onEvent((e) => {
  if (e.kind === 'element:created') console.log('New element:', e.payload);
});

// Later — clean up
renderer.dispose();
// or: engine.dispose(); // tears down all renderers

Load and serialize documents:

// Load a diagram
const doc = JSON.parse(fs.readFileSync('my.drawit', 'utf8'));
engine.loadDocument(doc);

// Serialize the current state
const saved = engine.toJSON();
localStorage.setItem('diagram', JSON.stringify(saved));

React Integration

Import from @chamuka-labs/engine/react to get a ready-made component:

import { DrawItCanvas } from '@chamuka-labs/engine/react';

export default function App() {
  return (
    <DrawItCanvas
      document={myDoc}            // optional — loads a document on mount
      backgroundColor={0xf5f5f5}  // optional
      onEvent={(e) => console.log(e)}
      style={{ width: '100%', height: '600px' }}
    />
  );
}

Or use the hook for full control:

import { useDrawItEngine } from '@chamuka-labs/engine/react';

function DiagramView() {
  const { engineRef, containerRef, ready } = useDrawItEngine({ document: myDoc });

  return (
    <div>
      {!ready && <p>Loading…</p>}
      <div ref={containerRef} style={{ width: 800, height: 600 }} />
    </div>
  );
}

API Reference

Export	Type	Description
createEngine(options?)	async → Engine	Async factory that initialises the core and returns an Engine instance.
EngineOptions	{ wasmUrl?: string }	Optional overrides. wasmUrl is reserved for future custom WASM hosting.
Engine.loadDocument(json)	void	Replace the current document. Emits a synthetic document:changed event.
Engine.toJSON()	object	Serialize the current document state to a plain JS object.
Engine.renderInto(target, opts?)	async → Renderer	Async. Mounts the canvas into target and resolves with a Renderer handle once WebGL is ready.
RenderOptions	{ width?, height?, backgroundColor?, antialias? }	All optional. backgroundColor is a 24-bit integer (e.g. 0xffffff).
Engine.onEvent(listener)	→ Unsubscribe	Subscribe to engine events. Returns a cleanup function.
Engine.dispose()	void	Release all resources. Idempotent. Disposes all attached renderers.
Renderer.resize(w, h)	void	Resize the canvas to w × h pixels.
Renderer.dispose()	void	Unmount this renderer without affecting other renderers on the same engine.

Multiple renderers can attach to the same engine — useful for minimap overlays or side-by-side comparisons. Each forwards events independently.

Events

All events have the shape { kind: string; payload: unknown }.

kind	payload
document:changed	null — emitted after loadDocument()
element:created	{ id, kind, label }
element:updated	{ id, changes }
element:deleted	{ id }
selection:changed	{ ids: string[] }
command:executed	{ name: string }

Stability Contract

0.x — unstable. Any documented symbol may change between minor versions. Pin exact versions in production until 1.0.

1.0 will freeze the public API surface. Breaking changes after 1.0 will follow semver and ship with migration notes.

The underlying @chamuka/drawit-bridge is intentionally not re-exported — it is an implementation detail and may change without notice.