# API overview

`createAsukaDesigner(...)` returns one typed runtime instance shared by Fabric and Babylon views. Native Fabric objects and Babylon meshes never cross the public renderer contract.

```ts
import {
  createAsukaDesigner,
  loadAsuka3DEngineAddon,
  type AsukaDesignerOptions,
} from 'asuka-designer';

const options: AsukaDesignerOptions = {
  engines: {
    '3d': { loader: loadAsuka3DEngineAddon },
  },
};

const designer = createAsukaDesigner('#app', options);
```

## Runtime namespaces

- `designer.layout`: menus, blocks, overlays, and contextual selection menu.
- `designer.api`: renderer-neutral document and object commands.
- `designer.variations`: typed variation catalog and synchronized mutations.
- `designer.engine`: the active Renderer v2 contract.
- `designer.util`: state, engine selection, camera, permissions, license, uploads, i18n, and responsive behavior.
- `designer.theme`: live theme tokens and presets.
- `designer.ui`: UI helpers available to custom modules.
- `designer.registerModule(...)`: runtime module registration.
- `designer.destroy()`: unmount and release the instance.

## `designer.api`

### Objects

```ts
const image = await designer.api.addImage({
  url: '/assets/logo.png',
  name: 'Logo',
});

const text = await designer.api.addText({
  text: 'Hello',
  fontFamily: 'Inter',
});

await designer.api.updateObjectTransform(image.value.id, {
  x: 320,
  y: 240,
  rotation: 15,
});

await designer.api.duplicateObject(image.value.id);
await designer.api.setObjectLocked(text.value.id, true);
await designer.api.removeObject(image.value.id);
```

Use `listObjects()`, `getObject()`, `getSelectedObjects()`, and `selectObject()` to inspect or change selection without touching a native renderer object.

Coordinate-bearing methods use the spaces and units declared in the [renderer functional matrix](../RENDERER_FUNCTIONAL_MATRIX.md).

### Views and viewport

```ts
const viewId = designer.api.addView({
  name: 'Back',
  engine: 'fabric',
  width: 900,
  height: 600,
  unit: 'px',
});

designer.api.setActiveView(viewId);
designer.api.updateView(viewId, { name: 'Back 2D' });
designer.api.zoomIn();
designer.api.zoomOut();
designer.api.fitView();
```

### History and export

```ts
await designer.api.undo();
await designer.api.redo();
await designer.api.commitHistorySnapshot({ reason: 'host-confirmation' });

const png = await designer.api.exportPng({ scale: 2 });
```

Batch and format-specific exports are exposed by `designer.engine.exports`, including `downloadAllViews()`, `downloadAllAreas()`, and `downloadAllObjects()` when supported.

### Fonts

```ts
designer.api.addSystemFont({ family: 'Arial' });
await designer.api.addGoogleFont({ family: 'Inter', weights: [400, 700] });
await designer.api.addCustomFont({
  family: 'Brand Sans',
  url: '/fonts/brand-sans.woff2',
});

await designer.api.loadFont('Brand Sans');
const fonts = designer.api.getFonts();
```

See [Fonts](./fonts.md) for startup configuration and deduplication rules.

### Physical measurements

```ts
const measurement = designer.api.measureLayer(text.value.id);
await designer.api.resizeLayerPhysical(text.value.id, {
  width: 12,
  height: 4,
  unit: 'cm',
});

const production = designer.api.exportProductionMeasurements();
```

See [Physical measurements](./physical-measurements.md).

### Pricing

```ts
const total = designer.api.getPrice(29.99);
const breakdown = designer.api.getPriceUiBreakdown(29.99);

// PriceUiBreakdown:
// { base, standard, rules, total }
```

The pricing engine is part of the main bundle and evaluates the normalized document for both Fabric and Babylon. The Pricing Rules editor remains a licensed add-on.

## `designer.variations`

```ts
const result = await designer.variations.apply({
  elementId: 'demo-product-3d',
  partId: 'handle',
  variationId: 'demo-blue-part-handle',
});

const choices = designer.variations.list({
  elementId: 'demo-product-3d',
  partId: 'handle',
});

const active = designer.variations.getActive({
  elementId: 'demo-product-3d',
  partId: 'handle',
});
```

See [Element variations](./variations.md) for scopes, structured results, and events.

## `designer.engine`

Every active renderer implements required lifecycle, events, history, scene, objects, selection, viewport, and export services:

```ts
const objects = designer.engine.objects.list();
const selected = designer.engine.selection.list();
const history = designer.engine.history.getInfo();
```

Optional capabilities are exposed as optional services:

- `areas` and `surface` for drawing areas and 3D surface picking.
- `products`, `models`, `parts`, and `materials` for Babylon products.
- `canvas2d` for Fabric-only text, shape, snapping, and magnifier tooling.

Shared modules must test service availability or declared capabilities, never inspect `.fabric`, `.threeD`, or a native renderer object.

## `designer.layout`

```ts
designer.layout.openModule('text');
designer.layout.moveBlock('layers', 'right', 0);
designer.layout.setZoneType('right', 'panels');
designer.layout.setZoneCollapsed('right', false);

designer.layout.selectionMenu.setItems(['font-family', 'text-formatting', 'colors']);
designer.layout.selectionMenu.open();
```

See [Layout](./layout.md), [Overlays](./overlays.md), and [Responsive layout](./responsive.md).

## `designer.util`

```ts
const fullState = designer.util.state.exportFull();
designer.util.state.importFull(fullState);

designer.util.i18n.setLocale('fr');
designer.util.camera.get();
designer.util.engine.getKind();
designer.util.license.isActive();
designer.util.responsive.isMobile();
```

The permission helpers live directly on `designer.util`:

```ts
if (designer.util.can('canAddText')) {
  await designer.api.addText({ text: 'Allowed' });
}
```

Use the dedicated guides for [state](./state-and-persistence.md), [permissions](./permissions.md), [licensing](./license-api.md), and [camera controls](./camera-module-and-api.md).

## Custom modules

```ts
designer.registerModule({
  id: 'order-summary',
  label: 'Order summary',
  render: ({ context }) => {
    const engine = context.getEngine();
    return designer.ui.el('div', null, `${engine?.objects.list().length ?? 0} layers`);
  },
}, {
  addToLayout: true,
  layoutZone: 'right',
});
```

See [Custom modules](./modules-custom.md) for inline layout registration and reusable UI components.

## State policy

Canonical exports use `format: 'asuka-state'` and `schemaVersion: 2`. Imports are strict and reject incompatible payloads. There is deliberately no legacy compatibility facade while the product is still under active development.