# State and persistence

AsukaDesigner supports one persistence envelope:

```ts
type AsukaExportedState = {
  format: 'asuka-state';
  schemaVersion: 2;
  exportedAt: string;
  scope: object;
  // selected state branches
};
```

Imports are strict. Payloads with another format or schema version are rejected. There is no migration layer, document wrapper, generic config import, or compatibility fallback.

## Full state

Use a full state when the whole designer session must be restored: layout, opened modules, mixed 2D/3D document, catalogs, appearance, pricing, tools, configuration, permissions and history.

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

designer.util.state.importFull(fullState, {
  replaceViews: true,
  replaceSnapshots: true,
});
```

## Named parts

Use `exportPart()` and `importPart()` when only one domain should be persisted.

```ts
const themeState = designer.util.state.exportPart('theme');
designer.util.state.importPart('theme', themeState);

const documentState = designer.util.state.exportPart('document');
designer.util.state.importPart('document', documentState, {
  replaceViews: true,
  replaceSnapshots: true,
});
```

Supported parts:

- `template`
- `theme`
- `layout`
- `modules`
- `document`
- `catalog`
- `pricing`
- `tools`
- `behavior`
- `configuration`
- `permissions`

Every part remains a self-describing `asuka-state` schema v2 payload. A part can therefore be stored, downloaded and validated exactly like a full state.

A complete state may also be used as the source of a partial import:

```ts
const fullState = designer.util.state.exportFull();
designer.util.state.importPart('theme', fullState);
```

The selected part is strictly opt-in; unrelated branches are not restored.

## Document-only persistence

The `document` part contains views, drawing areas, Fabric snapshots and objects, Babylon scenes, selection, viewport state and the element catalog required by placed elements.

```ts
const savedDesign = designer.util.state.exportPart('document');
await api.saveDesign(savedDesign);

const loadedDesign = await api.loadDesign();
designer.util.state.importPart('document', loadedDesign, {
  replaceViews: true,
  replaceSnapshots: true,
});
```

There is no standalone `asuka-document` public import API. The optional `document.asukaDocument` member is an internal engine-neutral representation contained inside the canonical state envelope.

## Restore at initialization

Pass any canonical state payload through `initialState`. A document part is still an `asuka-state`, so it uses the same option.

```ts
const savedState = await api.loadState();

const designer = createAsukaDesigner('#app', {
  initialState: savedState,
});
```

The explicit boot form accepts the same payload:

```ts
createAsukaDesigner('#app', {
  boot: {
    mode: 'initialState',
    state: savedState,
  },
});
```

Supported boot modes are `initialState` and `replace-product`.

## Replace a mounted product/session

```ts
const next = designer.util.state.replaceProduct(fullState);
```

Or replace the entire mounted instance:

```ts
const next = replaceAsukaDesigner('#app', fullState);
```

## Local storage

```ts
const fullState = designer.util.state.exportFull();
designer.util.state.saveToStorage(fullState, { key: 'product-editor' });

const saved = designer.util.state.loadFromStorage({ key: 'product-editor' });
if (saved) designer.util.state.importFull(saved);

designer.util.state.clearStorage({ key: 'product-editor' });
```

Storage only returns canonical schema v2 payloads.

## Runtime rebuild helper

After a low-level host operation, the active Fabric view can be rebuilt from the imported document state:

```ts
designer.util.state.rebuildActiveViewFromDocument();
```

Normal `importFull()`, `importPart('document', ...)` and boot flows already perform the required restoration.

## Recommended contracts

Use `exportFull()` for a complete product/session. Use `exportPart('document')` for saved designs. Use another named part only when the host deliberately owns the remaining state. Always persist the returned payload unchanged and reject unsupported `format` or `schemaVersion` values before importing external JSON.