How to Use Atomos Structura

Step-by-step guide to installing, configuring, and rendering the visual canvas engine.

1. Package Installation

Atomos Structura is distributed as a suite of decoupled packages depending on your needs.

pnpm add @atomos-web/structura
pnpm add @atomos-web/structura-core
pnpm add @atomos-web/prime-style

2. Initialization & Bootstrapping

To render the canvas inside your DOM, simply call the createCanvasPage('my-instance-id') factory and attach its element to your container. You also need to boot the schema kernel for core entity interactions.

import '@atomos-web/prime-style/dist/styles.css';
import { createCanvasPage } from '@atomos-web/structura/dist/preview/create-canvas-page.js';
import { getEntityManager } from '@atomos-web/structura/dist/core/presentation/entity-manager.js';
import { createSchemaGraphKernel } from '@atomos-web/structura/dist/core/create-schema-graph-kernel.js';
import { createKernelAdapter } from '@atomos-web/structura/dist/adapters/create-kernel-adapter.js';

export function mountCanvas(containerDiv) {
  // 1. Create the UI page (v2.0.0 requires an instanceId)
  const page = createCanvasPage('my-unique-canvas-id');
  containerDiv.appendChild(page.element);

  // 2. Boot the headless schema AST kernel
  const kernel = createSchemaGraphKernel();

  // 3. Connect the kernel back to the visual Canvas
  const bridge = createKernelAdapter(kernel, getEntityManager());

  return () => {
    bridge.destroy();
    page.cleanup.destroy();
  };
}

3. Operating the Kernel

With the bridge established, you can command the graph directly using the kernel instance. Updates will instantly sync to the Redux state and auto-render inside the Canvas.

// Add a new box shape to the graph payload programmatically
kernel.execute({
  type: 'add-entity',
  schemaId: 'schema-1',
  entity: {
    id: `entity-${Date.now()}`,
    position: { x: 100, y: 100 },
    dimensions: { width: 250, height: 150 },
    type: 'box',
    data: {
      name: 'UserDatabase',
      baseColor: '#2563eb'
    }
  }
});