# Built-in modules

AsukaDesigner ships with built-in modules for product personalization workflows. Modules can be shown in the layout, opened programmatically, or used as contextual popovers.

Some modules are always available. Others are registered lazily and loaded only when opened. Premium modules can also be hidden by permissions/licence features.

## Common module ids

Use these ids in `layout.<zone>.items[].kind`, `designer.layout.openModule(...)`, or custom module composition.

| Module id | Purpose |
| --- | --- |
| `views` | Manage product views such as front/back. |
| `designs` | Add reusable design assets/templates. |
| `text` | Create text objects. |
| `image` | Add/upload images and access image providers. |
| `shapes` | Add or draw shapes/SVG assets. |
| `layers` | Inspect, select, reorder, and delete layers. |
| `colors` | Edit object and SVG-part colors. |
| `zoom` | Control canvas zoom. |
| `camera` | Configure 3D camera limits and variation camera views. |
| `magnifier` | Toggle/configure magnifier tooling. |
| `ruler` | Toggle/configure ruler tooling. |
| `download` | Export/download the design. |
| `history` | Undo/redo and history inspection. |
| `state` | Export/import state. |
| `pricing` | Display/calculates product price. |
| `pricingRules` | Configure advanced pricing rules. |
| `elements` | Manage product elements and variations. |
| `element-editor` | Stateful internal editor for an element. |
| `element-variation-picker` | Stateful internal variation picker. |
| `drawingAreas` | Create/manage drawing areas. |
| `marker` | Create/manage fixed slots/markers. |
| `license` | Inspect active license/features. |
| `studio` | Advanced object/image editing tools. |
| `font-family` | Text font selector. |
| `text-formatting` | Text formatting controls. |
| `text-curve` | Text curve controls. |
| `upload-image` | Upload-focused image flow. |
| `pixabay-image` | Pixabay image provider. |
| `pexels-image` | Pexels image provider. |
| `facebook-image` | Facebook image provider. |
| `qrcode-image` | QR code image provider. |

## Add modules to the layout

```ts
const designer = createAsukaDesigner('#app', {
  layout: {
    left: {
      items: [
        { kind: 'views', label: 'Views', icon: 'views', type: 'floating' },
        { kind: 'designs', label: 'Designs', icon: 'brush', type: 'floating' },
        { kind: 'text', label: 'Text', icon: 'text', type: 'floating' },
        { kind: 'image', label: 'Images', icon: 'images', type: 'floating' },
        { kind: 'shapes', label: 'Shapes', icon: 'customize', type: 'floating' },
        { kind: 'layers', label: 'Layers', icon: 'layers', type: 'floating' },
        { kind: 'marker', label: 'Marker', icon: 'marker', type: 'floating' },
        { kind: 'drawingAreas', label: 'Drawing Areas', icon: 'pencil', type: 'floating' },
        { kind: 'elements', label: 'Elements', icon: 'puzzle', type: 'floating' },
        { kind: 'camera', label: 'Camera', icon: 'camera', type: 'floating', supportedEngines: ['3d'] },
      ],
    },
    top: {
      items: [
        { kind: 'magnifier', label: 'Magnifier', icon: 'magnifying-glass', type: 'floating' },
        { kind: 'ruler', label: 'Ruler', icon: 'ruler', type: 'floating' },
        { kind: 'zoom', label: 'Zoom', icon: 'zoom', type: 'floating' },
        { kind: 'download', label: 'Download', icon: 'download', type: 'floating' },
      ],
    },
  },
});
```

No `zone` property is needed on items. The zone is inferred from the parent key.

## Lazy and premium modules

Licensed modules such as `studio`, `pricing`, `marker`, `drawingAreas`,
`pricingRules`, and `modelOptimizer` are shipped as optional named add-ons. The
runtime requests only entitled add-ons, and the module is registered only after
its file loads successfully. Free/base modules, including `designs`, remain in
the main product bundle.

They may still be hidden or disabled by permissions/licence features. For example:

- `studio` can depend on basic Studio features.
- `pricing` can depend on pricing features.
- `designs` is part of the base bundle; premium template catalogs can still depend on `premiumTemplates` at the catalog/integration level.
- `marker` can depend on fixed-slot features.
- `drawingAreas` can depend on drawing-area features.
- `pricingRules` can depend on advanced pricing features.

If a module does not appear in the layout, check:

1. the item `kind`
2. module registration
3. permissions
4. active license features
5. presence of the corresponding `*-addon.js` file
6. hidden module state

## Opening modules programmatically

```ts
designer.layout.openModule('download');
designer.layout.openModule('layers');
designer.layout.overlay.close();
```

For stateful modules such as `element-editor`, use the dedicated flow that provides the required payload instead of opening an empty module manually.

## Views

The Views module manages multi-view editing.

```ts
designer.api.getViews();
designer.api.getActiveViewId();
designer.api.setActiveView(id);
designer.api.addView(payload?);
designer.api.updateView(id, patch);
designer.api.removeView(id);
```

## Designs

Configure design assets at startup:

```ts
const designer = createAsukaDesigner('#app', {
  moduleConfig: {
    designs: {
      items: [
        {
          url: 'https://example.com/design.svg',
          name: 'My design',
          price: 19.99,
          category: 'Sports',
        },
      ],
    },
  },
});
```

## Images and upload policy

The Images workflow supports:

- `objectUrl` for local blob previews
- `base64` for data URLs
- `remote` for server uploads

Base64 is the default when no upload configuration is supplied. Configuring `endpoint` or
`handler` implicitly selects `remote`; an explicit `strategy` takes precedence.

```ts
const designer = createAsukaDesigner('#app', {
  moduleConfig: {
    upload: {
      multiple: true,
      autoAddOnSingle: true,
      strategy: 'remote',
      endpoint: '/upload.php',
      method: 'POST',
      mapResponseToUrl: (json) => json.url,
    },
  },
  integrations: {
    pixabay: { apiKey: '...' },
    pexels: { apiKey: '...' },
  },
});
```

Remote image providers reuse the upload policy when possible. If a browser cannot download a remote provider image as a `File`, AsukaDesigner falls back to `addImageFromUrl(...)`. Canvas uploads, the public image API, Fabric, Babylon, and file inputs used by forms (`MediaInput`, `ImageField`, `IconField`) all use the same effective strategy.

The Upload module can also use a host-controlled picker instead of the browser file dialog. Provide `moduleConfig.upload.selectHandler`, return File objects or URL/media objects from your WordPress/custom picker promise, and AsukaDesigner handles registration, form assignment, and canvas insertion itself.

The Upload module list is shared globally. Files added through the Upload module, canvas uploads, media inputs, and custom upload handlers are all registered in the same list, so users can reuse recently uploaded assets from the module.

## Text modules

Text-related flows include:

- `text`
- `font-family`
- `text-formatting`
- `text-curve`
- `colors`

These are often used in the contextual selection menu.

## Shapes

Shapes supports visual shape picking and drawing. Runtime configuration can define custom SVG assets and defaults:

```ts
const designer = createAsukaDesigner('#app', {
  moduleConfig: {
    shapes: {
      svgAssets: [{ name: 'Heart', svgText: '<svg>...</svg>' }],
      style: {
        fill: '#111827',
        stroke: '#000000',
        strokeWidth: 1,
        opacity: 1,
      },
    },
  },
});
```

## Drawing areas

Drawing areas define regions where content can be auto-fit, clipped, and exported. They are view-scoped: a drawing area created on one view should not appear on other views.

Related helpers:

```ts
designer.engine.areas?.list();
await designer.engine.areas?.create(area);
designer.engine.areas?.select(id);
```

## 3D camera

The `camera` module configures per-view orbit limits, exact camera placement, and camera presets saved on Product 3D variations. Integrations can perform the same operations through `designer.util.camera`, so the UI module is optional.

See [3D camera module and API](./camera-module-and-api.md) for the complete API and examples.

## Elements and variations

Elements represent configurable product components and variation trees. The editor updates the current view's placed instance visually, while variation-selection flows can intentionally synchronize the active variation across related views.

Use the Elements UI for normal editing instead of opening `element-editor` directly without payload.

## Download

The Download module supports client export and server HD export. For server HD export, the frontend sends explicit sizing fields such as `renderWidth` and `renderHeight`; the server renderer must consume those fields.

## State

The State module exposes document, modular, and full-state export/import flows. See [State and persistence](./state-and-persistence.md).

## See also

- [Layout](./layout.md)
- [Overlays and mount targets](./overlays.md)
- [Permissions](./permissions.md)
- [State and persistence](./state-and-persistence.md)